[BUG] Validation error on pydantic ExtractedEntities

[did-82]

Bug Description

I get a validation error when running the quickstart_neo4j on the ExtractedEntities pydantic model.

I am using deepseek-r1:7b.

LLM response is the following:
'{"$defs": {"ExtractedEntity": {"properties": {"name": {"description": "Name of the extracted entity", "title": "Name", "type": "string"}, "entity_type_id": {"description": "ID of the classified entity type. Must be one of the provided entity_type_id integers.", "title": "Entity Type Id", "type": "integer"}}, "required": ["name", "entity_type_id"], "title": "ExtractedEntity", "type": "object"}}, "properties": {"extracted_entities": {"description": "List of extracted entities", "items": {"$ref": "#/$defs/ExtractedEntity"}, "title": "Extracted Entities", "type": "array"}}, "required": ["extracted_entities"], "title": "ExtractedEntities", "type": "object"}'

that throws the following error:
Field required [type=missing, input_value={'$def': {'ExtractedEntit... 'entity_type_id': 0}]}}, input_type=dict]

Steps to Reproduce

Provide a minimal code example that reproduces the issue:

from datetime import datetime
from graphiti_core import Graphiti
from graphiti_core.nodes import EpisodeType
from graphiti_core.search.search_config_recipes import NODE_HYBRID_SEARCH_RRF
from graphiti_core.llm_client import LLMConfig
from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
from graphiti_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient

from graphiti_core.llm_client.openai_generic_client import OpenAIGenericClient


# Configure Ollama LLM client
llm_config = LLMConfig(
    api_key="ollama",  # Ollama doesn't require a real API key, but some placeholder is needed
    model="deepseek-r1:7b",
    small_model="deepseek-r1:7b",
    base_url="http://localhost:11434/v1",  # Ollama's OpenAI-compatible endpoint
)

llm_client = OpenAIGenericClient(config=llm_config)

# Initialize Graphiti with Ollama clients
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "your_password",
    llm_client=llm_client,
    embedder=OpenAIEmbedder(
        config=OpenAIEmbedderConfig(
            api_key="ollama",  # Placeholder API key
            embedding_model="bge-m3",
            embedding_dim=1024,
            base_url="http://localhost:11434/v1",
        )
    ),
    cross_encoder=OpenAIRerankerClient(client=llm_client, config=llm_config),
)

async def main():
    # Initialize the graph database with graphiti's indices. This only needs to be done once.
    await graphiti.build_indices_and_constraints()
    await graphiti.add_episode(
        name="tech_innovation_article",
        episode_body=(
            "MIT researchers have unveiled 'ClimateNet', an AI system capable of predicting "
            "climate patterns with unprecedented accuracy. Early tests show it can forecast "
            "major weather events up to three weeks in advance, potentially revolutionizing "
            "disaster preparedness and agricultural planning."
        ),
        source=EpisodeType.text,
        # A description of the source (e.g., "podcast", "news article")
        source_description="Technology magazine article",
        # The timestamp for when this episode occurred or was created
        reference_time=datetime(2023, 11, 15, 9, 30),
    )

Expected Behavior

A clear and concise description of what you expected to happen.

Actual Behavior

A clear and concise description of what actually happened.

Environment

• Graphiti Version: 0.20.4
• Python Version: 3.12.11
• Operating System: MacOS 15.6.1
• Database Backend: Neo4j 5.26
• LLM Provider & Model: deepseek-r1:7b

Installation Method

• pip install
• uv add
• Development installation (git clone)

Error Messages/Traceback

2025-09-17 08:53:25 - httpx - INFO - HTTP Request: POST http://localhost:11434/v1/chat/completions "HTTP/1.1 200 OK"

Connection closed
Traceback (most recent call last):
  File "/Users/xxx/projects/xxx/monorepo/apps/backend/ai/agents/xxx-troubleshooting/scripts/quickstart_neo4j_azure.py", line 327, in <module>
    asyncio.run(main())
  File "/Users/xxx/.local/share/uv/python/cpython-3.12.11-macos-aarch64-none/lib/python3.12/asyncio/runners.py", line 195, in run
    return runner.run(main)
           ^^^^^^^^^^^^^^^^
  File "/Users/xxx/.local/share/uv/python/cpython-3.12.11-macos-aarch64-none/lib/python3.12/asyncio/runners.py", line 118, in run
    return self._loop.run_until_complete(task)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/xxx/.local/share/uv/python/cpython-3.12.11-macos-aarch64-none/lib/python3.12/asyncio/base_events.py", line 691, in run_until_complete
    return future.result()
           ^^^^^^^^^^^^^^^
  File "/Users/xxx/projects/xxx/monorepo/apps/backend/ai/agents/xxx-troubleshooting/scripts/quickstart_neo4j_azure.py", line 202, in main
    await graphiti.add_episode(
  File "/Users/xxx/projects/xxx/monorepo/apps/backend/ai/agents/xxx-troubleshooting/.venv/lib/python3.12/site-packages/graphiti_core/graphiti.py", line 587, in add_episode
    raise e
  File "/Users/xxx/projects/xxx/monorepo/apps/backend/ai/agents/xxx-troubleshooting/.venv/lib/python3.12/site-packages/graphiti_core/graphiti.py", line 503, in add_episode
    extracted_nodes = await extract_nodes(
                      ^^^^^^^^^^^^^^^^^^^^
  File "/Users/xxx/projects/xxx/monorepo/apps/backend/ai/agents/xxx-troubleshooting/.venv/lib/python3.12/site-packages/graphiti_core/utils/maintenance/node_operations.py", line 129, in extract_nodes
    response_object = ExtractedEntities(**llm_response)
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/xxx/projects/xxx/monorepo/apps/backend/ai/agents/xxx-troubleshooting/.venv/lib/python3.12/site-packages/pydantic/main.py", line 253, in __init__
    validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
pydantic_core._pydantic_core.ValidationError: 1 validation error for ExtractedEntities
extracted_entities
  Field required [type=missing, input_value={'$def': {'ExtractedEntit... 'entity_type_id': 0}]}}, input_type=dict]
    For further information visit https://errors.pydantic.dev/2.11/v/missing

Configuration

# Relevant configuration or initialization code

Additional Context

• Does this happen consistently or intermittently?
• Which component are you using? (core library, REST server, MCP server)
• Any recent changes to your environment?
• Related issues or similar problems you've encountered?

Possible Solution

[cyberbobjr]

Exactly the same error, with the basic quickstart, this is my output :

entity_resolutions.0.duplicates
  Field required [type=missing, input_value={'id': 0, 'name': 'Kamala...s', 'duplicate_idx': -1}, input_type=dict]
    For further information visit https://errors.pydantic.dev/2.11/v/missing
entity_resolutions.1.duplicates
  Field required [type=missing, input_value={'id': 1, 'name': 'Attorn...a', 'duplicate_idx': -1}, input_type=dict]
    For further information visit https://errors.pydantic.dev/2.11/v/missing
entity_resolutions.2.duplicates
  Field required [type=missing, input_value={'id': 2, 'name': 'San Fr...o', 'duplicate_idx': -1}, input_type=dict]
    For further information visit https://errors.pydantic.dev/2.11/v/missing
entity_resolutions.3.duplicates
  Field required [type=missing, input_value={'id': 3, 'name': 'distri...y', 'duplicate_idx': -1}, input_type=dict]
    For further information visit https://errors.pydantic.dev/2.11/v/missing

[bulexu]

me too...

pydantic_core._pydantic_core.ValidationError: 3 validation errors for EdgeDuplicate
duplicate_facts
  Field required [type=missing, input_value={'properties': {'duplicat...cate', 'type': 'object'}, input_type=dict]
    For further information visit https://errors.pydantic.dev/2.11/v/missing
contradicted_facts
  Field required [type=missing, input_value={'properties': {'duplicat...cate', 'type': 'object'}, input_type=dict]
    For further information visit https://errors.pydantic.dev/2.11/v/missing
fact_type
  Field required [type=missing, input_value={'properties': {'duplicat...cate', 'type': 'object'}, input_type=dict]
    For further information visit https://errors.pydantic.dev/2.11/v/missing

[yzim]

Did authors only test the official OpenAI service?

I tried my self-hosted LLM service and third-party OpenAI-compatible suppliers. I followed the quick start documentation and encountered the same bug. The bug is caused by the mismatch between the LLM response and expected data format of ExtractedEntities.

I modified the prompt to guide the LLM to generate correct format and solved this bug. But later, a bug with NodeResolutions appeared. After solving the bug with NodeResolutions, another bug raised.

After days of debugging, I still cannot run a simple demo followed by the quick start documentation. The very experience is really painful. I am wondering what’s wrong with the documentation and code? Could the authors validate the documentation and provide an out-of-the-box configuration for OpenAI-compatible services?

[tobsentobsentobs]

Hey! 👋

I've been working on a similar issue with graphiti-core and XAI Grok-4, and I've created a comprehensive solution that should help with your \ExtractedEntities\ validation errors.

🎯 The Problem You're Facing:
The issue is that graphiti-core uses the basic
esponse_format={'type': 'json_object'}\ which doesn't guarantee proper schema compliance. This causes LLMs to return schema definitions instead of actual data, leading to validation errors like \ arget_entity_id = None.

✅ My Solution:
I've implemented XAI Structured Outputs with strict Pydantic schema enforcement, plus a robust fallback system. The fix includes:

• Structured Outputs Patch: Uses \json_schema\ with strict enforcement when
  esponse_model\ is provided
• Automatic Fallback: Falls back to \json_object\ if schema enforcement fails
• Optimized Prompts: Shorter, clearer prompts that explicitly prevent schema definition returns
• Comprehensive Testing: Works with complex content up to 5000+ characters

📊 Results:

• ~90% reduction in validation errors
• No more schema definition returns
• Tested with complex multi-entity scenarios
• Production ready

🔗 Repository:
https://github.com/tobsentobsentobs/cursor-graphiti

The patches are in the \patches/\ directory, and there's detailed documentation in \STRUCTURED_OUTPUTS_PATCH.md. The solution is specifically designed for XAI Grok-4 but should work with other OpenAI-compatible LLMs too.

💡 Key Files:

• \patches/openai_generic_client_patch.py\ - Main Structured Outputs implementation
• \patches/extract_nodes_patch.py\ - Optimized prompts
• \STRUCTURED_OUTPUTS_PATCH.md\ - Complete documentation and testing results

Hope this helps! Let me know if you have any questions or if you'd like me to explain any part of the implementation. ��

[laotoutou]

Do not use OpenAIGenericClient. I am using OpenRouter as my LLM provider and fixed this issue by replacing OpenAIGenericClient with OpenAIClient. Here is some of the code:

LLM_API_KEY = os.getenv("LLM_API_KEY", "")
LLM_MODEL = os.getenv("LLM_MODEL", "")
LLM_SMALL_MODEL = os.getenv("LLM_SMALL_MODEL", "")
LLM_BASE_URL = os.getenv("LLM_BASE_URL", "")

RERANKER_API_KEY = os.getenv("RERANKER_API_KEY", LLM_API_KEY)
RERANKER_MODEL = os.getenv("RERANKER_MODEL", LLM_SMALL_MODEL)
RERANKER_BASE_URL = os.getenv("RERANKER_BASE_URL", LLM_BASE_URL)


    graphiti_client = Graphiti(
        uri=os.getenv("NEO4J_URI"),
        user=os.getenv("NEO4J_USERNAME"),
        password=os.getenv("NEO4J_PASSWORD"),
        # graph_driver=kuzu_driver,
        llm_client=OpenAIClient(config=LLMConfig(
            api_key=LLM_API_KEY,
            model=LLM_MODEL,         
            small_model=LLM_SMALL_MODEL, 
            base_url=LLM_BASE_URL,   
            temperature=0.1,         
        )),
        embedder=get_openai_embedder(),
        cross_encoder=OpenAIRerankerClient(
            config=LLMConfig(
                api_key=RERANKER_API_KEY,
                model=RERANKER_MODEL,  # Use smaller model for reranking
                base_url=RERANKER_BASE_URL,
            )
        )
    )