Fix additionalProperties in auto-generated KG schema models (#20768)

* fix: clean additionalProperties in auto-generated KG schema models

Pydantic generates `additionalProperties: true` for `Dict[str, Any]`
fields in the Entity/Relation models created by SchemaLLMPathExtractor.
This breaks OpenAI structured outputs (which require `false`) and
Google Gemini (which rejects `true` entirely).

Added a `_clean_additional_properties` helper that recursively sets
`additionalProperties: true` to `false`, applied via ConfigDict on the
auto-generated models only when they include a properties dict field.
User-provided kg_schema_cls is not affected.

Fixes #20629

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: make additionalProperties cleanup opt-in via allow_additional_properties

Address review feedback from AstraBert: the additionalProperties fix is now
opt-in rather than unconditional. Users pass allow_additional_properties=False
to SchemaLLMPathExtractor when they need strict schemas (OpenAI structured
outputs, Google Gemini). Default is True, preserving existing behavior.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: pass __config__ as keyword arg to satisfy mypy overload resolution

The dict unpacking pattern (**config_kwargs) caused mypy to see a
dict[str, ConfigDict] positional argument that doesn't match any
create_model overload. Passing __config__ directly as a keyword
argument with a conditional expression resolves the type error.

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: bledden

llama-index-core/llama_index/core/indices/property_graph/transformations/schema_llm.py

@@ -116,6 +116,12 @@ class SchemaLLMPathExtractor(TransformComponent):
             The maximum number of triplets to extract per chunk. Defaults to 10.
         num_workers (int, optional):
             The number of workers to use. Defaults to 4.
+        allow_additional_properties (bool, optional):
+            Whether to allow ``additionalProperties: true`` in auto-generated
+            JSON schemas for entity/relation models with Dict properties.
+            Set to ``False`` when using LLM providers that require strict
+            schemas (e.g. OpenAI structured outputs, Google Gemini).
+            Defaults to True (preserving existing behavior).
 
     """
 
@@ -144,6 +150,7 @@ def __init__(
         kg_validation_schema: Optional[Union[Dict[str, str], List[Triple]]] = None,
         max_triplets_per_chunk: int = 10,
         num_workers: int = 4,
+        allow_additional_properties: bool = True,
     ) -> None:
         """Init params."""
         if isinstance(extract_prompt, str):
@@ -159,7 +166,12 @@ def __init__(
                 ]
             else:
                 entity_props = possible_entity_props  # type: ignore
-            entity_cls = get_entity_class(possible_entities, entity_props, strict)
+            entity_cls = get_entity_class(
+                possible_entities,
+                entity_props,
+                strict,
+                clean_additional_properties=not allow_additional_properties,
+            )
 
             possible_relations = possible_relations or DEFAULT_RELATIONS  # type: ignore
             if possible_relation_props and isinstance(
@@ -172,7 +184,10 @@ def __init__(
             else:
                 relation_props = possible_relation_props  # type: ignore
             relation_cls = get_relation_class(
-                possible_relations, relation_props, strict
+                possible_relations,
+                relation_props,
+                strict,
+                clean_additional_properties=not allow_additional_properties,
             )
 
             triplet_cls = create_model(

llama-index-core/llama_index/core/indices/property_graph/transformations/utils.py

@@ -6,13 +6,33 @@
     # python 3.8 and 3.9 compatibility
     from typing import Any as TypeAlias  # type: ignore
 
-from llama_index.core.bridge.pydantic import create_model, Field
+from llama_index.core.bridge.pydantic import ConfigDict, create_model, Field
+
+
+def _clean_additional_properties(schema: Dict[str, Any]) -> None:
+    """
+    Recursively set ``additionalProperties: true`` to ``false`` in a JSON schema.
+
+    Pydantic generates ``additionalProperties: true`` for ``Dict[str, Any]``
+    fields. This is incompatible with OpenAI structured outputs (which require
+    ``false``) and Google Gemini (which rejects the field entirely when set to
+    ``true``). Setting it to ``false`` satisfies both APIs.
+    """
+    if isinstance(schema, dict):
+        if schema.get("additionalProperties") is True:
+            schema["additionalProperties"] = False
+        for value in schema.values():
+            _clean_additional_properties(value)
+    elif isinstance(schema, list):
+        for item in schema:
+            _clean_additional_properties(item)
 
 
 def get_entity_class(
     possible_entities: TypeAlias,
     possible_entity_props: Optional[List[str]],
     strict: bool,
+    clean_additional_properties: bool = False,
 ) -> Any:
     """Get entity class."""
     if not possible_entity_props:
@@ -31,8 +51,14 @@ def get_entity_class(
             name=(str, ...),
         )
     else:
+        config = (
+            ConfigDict(json_schema_extra=_clean_additional_properties)
+            if clean_additional_properties
+            else None
+        )
         return create_model(
             "Entity",
+            __config__=config,
             type=(
                 possible_entities if strict else str,
                 Field(
@@ -61,6 +87,7 @@ def get_relation_class(
     possible_relations: TypeAlias,
     possible_relation_props: Optional[List[str]],
     strict: bool,
+    clean_additional_properties: bool = False,
 ) -> Any:
     """Get relation class."""
     if not possible_relation_props:
@@ -78,8 +105,14 @@ def get_relation_class(
             ),
         )
     else:
+        config = (
+            ConfigDict(json_schema_extra=_clean_additional_properties)
+            if clean_additional_properties
+            else None
+        )
         return create_model(
             "Relation",
+            __config__=config,
             type=(
                 possible_relations if strict else str,
                 Field(

llama-index-core/tests/indices/property_graph/test_schema_utils.py

@@ -0,0 +1,183 @@
+"""
+Tests for property graph schema utility functions.
+
+Validates that auto-generated Entity/Relation Pydantic models produce
+JSON schemas compatible with OpenAI structured outputs and Google Gemini
+when ``clean_additional_properties=True`` is passed.
+"""
+
+import json
+from typing import Literal
+
+from llama_index.core.indices.property_graph.transformations.utils import (
+    _clean_additional_properties,
+    get_entity_class,
+    get_relation_class,
+)
+
+
+def _schema_contains(schema: dict, key: str, value: object) -> bool:
+    """Recursively check whether *schema* contains *key* mapped to *value*."""
+    if isinstance(schema, dict):
+        if schema.get(key) is value:
+            return True
+        return any(_schema_contains(v, key, value) for v in schema.values())
+    if isinstance(schema, list):
+        return any(_schema_contains(item, key, value) for item in schema)
+    return False
+
+
+# -- _clean_additional_properties ------------------------------------------
+
+
+def test_clean_additional_properties_sets_true_to_false():
+    schema = {"additionalProperties": True, "properties": {"x": {"type": "string"}}}
+    _clean_additional_properties(schema)
+    assert schema["additionalProperties"] is False
+
+
+def test_clean_additional_properties_nested():
+    schema = {
+        "properties": {
+            "inner": {
+                "additionalProperties": True,
+                "type": "object",
+            }
+        }
+    }
+    _clean_additional_properties(schema)
+    assert schema["properties"]["inner"]["additionalProperties"] is False
+
+
+def test_clean_additional_properties_ignores_false():
+    schema = {"additionalProperties": False}
+    _clean_additional_properties(schema)
+    assert schema["additionalProperties"] is False
+
+
+def test_clean_additional_properties_ignores_absent():
+    schema = {"properties": {"x": {"type": "string"}}}
+    _clean_additional_properties(schema)
+    assert "additionalProperties" not in schema
+
+
+def test_clean_additional_properties_handles_list():
+    schema = {"anyOf": [{"additionalProperties": True}, {"type": "null"}]}
+    _clean_additional_properties(schema)
+    assert schema["anyOf"][0]["additionalProperties"] is False
+
+
+# -- get_entity_class (no props → no additionalProperties issue) -----------
+
+
+def test_entity_class_without_props_has_no_additional_properties_true():
+    entities = Literal["PERSON", "LOCATION"]
+    cls = get_entity_class(entities, None, strict=True)
+    schema = cls.model_json_schema()
+    assert not _schema_contains(schema, "additionalProperties", True)
+
+
+# -- get_entity_class (default: additionalProperties preserved) ------------
+
+
+def test_entity_class_with_props_default_preserves_additional_properties():
+    """By default, additionalProperties: true is left as-is."""
+    entities = Literal["PERSON", "LOCATION"]
+    cls = get_entity_class(entities, ["age", "occupation"], strict=True)
+    schema = cls.model_json_schema()
+    assert _schema_contains(schema, "additionalProperties", True), (
+        f"Expected additionalProperties: true in default mode:\n"
+        f"{json.dumps(schema, indent=2)}"
+    )
+
+
+# -- get_entity_class (opt-in: fix applied) --------------------------------
+
+
+def test_entity_class_with_props_clean_removes_additional_properties():
+    entities = Literal["PERSON", "LOCATION"]
+    cls = get_entity_class(
+        entities, ["age", "occupation"], strict=True, clean_additional_properties=True
+    )
+    schema = cls.model_json_schema()
+    assert not _schema_contains(schema, "additionalProperties", True), (
+        f"Schema still contains additionalProperties: true:\n"
+        f"{json.dumps(schema, indent=2)}"
+    )
+
+
+def test_entity_class_with_props_non_strict_clean():
+    cls = get_entity_class(str, ["age"], strict=False, clean_additional_properties=True)
+    schema = cls.model_json_schema()
+    assert not _schema_contains(schema, "additionalProperties", True)
+
+
+# -- get_relation_class (no props → no issue) ------------------------------
+
+
+def test_relation_class_without_props_has_no_additional_properties_true():
+    relations = Literal["USED_BY", "PART_OF"]
+    cls = get_relation_class(relations, None, strict=True)
+    schema = cls.model_json_schema()
+    assert not _schema_contains(schema, "additionalProperties", True)
+
+
+# -- get_relation_class (default: additionalProperties preserved) ----------
+
+
+def test_relation_class_with_props_default_preserves_additional_properties():
+    """By default, additionalProperties: true is left as-is."""
+    relations = Literal["USED_BY", "PART_OF"]
+    cls = get_relation_class(relations, ["weight", "source"], strict=True)
+    schema = cls.model_json_schema()
+    assert _schema_contains(schema, "additionalProperties", True), (
+        f"Expected additionalProperties: true in default mode:\n"
+        f"{json.dumps(schema, indent=2)}"
+    )
+
+
+# -- get_relation_class (opt-in: fix applied) ------------------------------
+
+
+def test_relation_class_with_props_clean_removes_additional_properties():
+    relations = Literal["USED_BY", "PART_OF"]
+    cls = get_relation_class(
+        relations, ["weight", "source"], strict=True, clean_additional_properties=True
+    )
+    schema = cls.model_json_schema()
+    assert not _schema_contains(schema, "additionalProperties", True), (
+        f"Schema still contains additionalProperties: true:\n"
+        f"{json.dumps(schema, indent=2)}"
+    )
+
+
+def test_relation_class_with_props_non_strict_clean():
+    cls = get_relation_class(
+        str, ["weight"], strict=False, clean_additional_properties=True
+    )
+    schema = cls.model_json_schema()
+    assert not _schema_contains(schema, "additionalProperties", True)
+
+
+# -- Models still validate correctly after the fix -------------------------
+
+
+def test_entity_model_with_props_roundtrips():
+    entities = Literal["PERSON", "LOCATION"]
+    cls = get_entity_class(
+        entities, ["age", "occupation"], strict=True, clean_additional_properties=True
+    )
+    instance = cls(type="PERSON", name="Alice", properties={"age": 30})
+    assert instance.type == "PERSON"
+    assert instance.name == "Alice"
+    assert instance.properties == {"age": 30}
+
+
+def test_relation_model_with_props_roundtrips():
+    relations = Literal["USED_BY", "PART_OF"]
+    cls = get_relation_class(
+        relations, ["weight"], strict=True, clean_additional_properties=True
+    )
+    instance = cls(type="USED_BY", properties={"weight": 0.9})
+    assert instance.type == "USED_BY"
+    assert instance.properties == {"weight": 0.9}