graphiti-core 0.30.0rc1__tar.gz → 0.30.0rc3__tar.gz

{graphiti_core-0.30.0rc1 → graphiti_core-0.30.0rc3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphiti-core
-Version: 0.30.0rc1
+Version: 0.30.0rc3
 Summary: A temporal graph building library
 Project-URL: Homepage, https://help.getzep.com/graphiti/graphiti/overview
 Project-URL: Repository, https://github.com/getzep/graphiti

{graphiti_core-0.30.0rc1 → graphiti_core-0.30.0rc3}/graphiti_core/prompts/dedupe_nodes.py

@@ -92,12 +92,23 @@ def node(context: dict[str, Any]) -> list[Message]:
 
          TASK:
          1. Compare `new_entity` against each item in `existing_entities`.
-         2. If it refers to the same real‐world object or concept, collect its index.
-         3. Let `duplicate_idx` = the *first* collected index, or –1 if none.
-         4. Let `duplicates` = the list of *all* collected indices (empty list if none).
-        
-        Also return the full name of the NEW ENTITY (whether it is the name of the NEW ENTITY, a node it
-        is a duplicate of, or a combination of the two).
+         2. If it refers to the same real-world object or concept, collect its index.
+         3. Let `duplicate_idx` = the smallest collected index, or -1 if none.
+         4. Let `duplicates` = the sorted list of all collected indices (empty list if none).
+
+        Respond with a JSON object containing an "entity_resolutions" array with a single entry:
+        {{
+            "entity_resolutions": [
+                {{
+                    "id": integer id from NEW ENTITY,
+                    "name": the best full name for the entity,
+                    "duplicate_idx": integer index of the best duplicate in EXISTING ENTITIES, or -1 if none,
+                    "duplicates": sorted list of all duplicate indices you collected (deduplicate the list, use [] when none)
+                }}
+            ]
+        }}
+
+        Only reference indices that appear in EXISTING ENTITIES, and return [] / -1 when unsure.
         """,
         ),
     ]
@@ -126,26 +137,26 @@ def nodes(context: dict[str, Any]) -> list[Message]:
         {{
             id: integer id of the entity,
             name: "name of the entity",
-            entity_type: "ontological classification of the entity",
-            entity_type_description: "Description of what the entity type represents",
-            duplication_candidates: [
-                {{
-                    idx: integer index of the candidate entity,
-                    name: "name of the candidate entity",
-                    entity_type: "ontological classification of the candidate entity",
-                    ...<additional attributes>
-                }}
-            ]
+            entity_type: ["Entity", "<optional additional label>", ...],
+            entity_type_description: "Description of what the entity type represents"
         }}
-        
+
         <ENTITIES>
         {to_prompt_json(context['extracted_nodes'], ensure_ascii=context.get('ensure_ascii', True), indent=2)}
         </ENTITIES>
-        
+
         <EXISTING ENTITIES>
         {to_prompt_json(context['existing_nodes'], ensure_ascii=context.get('ensure_ascii', True), indent=2)}
         </EXISTING ENTITIES>
 
+        Each entry in EXISTING ENTITIES is an object with the following structure:
+        {{
+            idx: integer index of the candidate entity (use this when referencing a duplicate),
+            name: "name of the candidate entity",
+            entity_types: ["Entity", "<optional additional label>", ...],
+            ...<additional attributes such as summaries or metadata>
+        }}
+
         For each of the above ENTITIES, determine if the entity is a duplicate of any of the EXISTING ENTITIES.
 
         Entities should only be considered duplicates if they refer to the *same real-world object or concept*.
@@ -155,14 +166,19 @@ def nodes(context: dict[str, Any]) -> list[Message]:
         - They have similar names or purposes but refer to separate instances or concepts.
 
         Task:
-        Your response will be a list called entity_resolutions which contains one entry for each entity.
-        
-        For each entity, return the id of the entity as id, the name of the entity as name, and the duplicate_idx
-        as an integer.
-        
-        - If an entity is a duplicate of one of the EXISTING ENTITIES, return the idx of the candidate it is a 
-        duplicate of.
-        - If an entity is not a duplicate of one of the EXISTING ENTITIES, return the -1 as the duplication_idx
+        Respond with a JSON object that contains an "entity_resolutions" array with one entry for each entity in ENTITIES, ordered by the entity id.
+
+        For every entity, return an object with the following keys:
+        {{
+            "id": integer id from ENTITIES,
+            "name": the best full name for the entity (preserve the original name unless a duplicate has a more complete name),
+            "duplicate_idx": the idx of the EXISTING ENTITY that is the best duplicate match, or -1 if there is no duplicate,
+            "duplicates": a sorted list of all idx values from EXISTING ENTITIES that refer to duplicates (deduplicate the list, use [] when none or unsure)
+        }}
+
+        - Only use idx values that appear in EXISTING ENTITIES.
+        - Set duplicate_idx to the smallest idx you collected for that entity, or -1 if duplicates is empty.
+        - Never fabricate entities or indices.
         """,
         ),
     ]

{graphiti_core-0.30.0rc1 → graphiti_core-0.30.0rc3}/graphiti_core/utils/maintenance/node_operations.py

@@ -241,7 +241,11 @@ async def _resolve_with_llm(
     previous_episodes: list[EpisodicNode] | None,
     entity_types: dict[str, type[BaseModel]] | None,
 ) -> None:
-    """Escalate unresolved nodes to the dedupe prompt so the LLM can select or reject duplicates."""
+    """Escalate unresolved nodes to the dedupe prompt so the LLM can select or reject duplicates.
+
+    The guardrails below defensively ignore malformed or duplicate LLM responses so the
+    ingestion workflow remains deterministic even when the model misbehaves.
+    """
     if not state.unresolved_indices:
         return
 
@@ -291,18 +295,41 @@ async def _resolve_with_llm(
 
     node_resolutions: list[NodeDuplicate] = NodeResolutions(**llm_response).entity_resolutions
 
+    valid_relative_range = range(len(state.unresolved_indices))
+    processed_relative_ids: set[int] = set()
+
     for resolution in node_resolutions:
         relative_id: int = resolution.id
         duplicate_idx: int = resolution.duplicate_idx
 
+        if relative_id not in valid_relative_range:
+            logger.warning(
+                'Skipping invalid LLM dedupe id %s (unresolved indices: %s)',
+                relative_id,
+                state.unresolved_indices,
+            )
+            continue
+
+        if relative_id in processed_relative_ids:
+            logger.warning('Duplicate LLM dedupe id %s received; ignoring.', relative_id)
+            continue
+        processed_relative_ids.add(relative_id)
+
         original_index = state.unresolved_indices[relative_id]
         extracted_node = extracted_nodes[original_index]
 
-        resolved_node = (
-            indexes.existing_nodes[duplicate_idx]
-            if 0 <= duplicate_idx < len(indexes.existing_nodes)
-            else extracted_node
-        )
+        resolved_node: EntityNode
+        if duplicate_idx == -1:
+            resolved_node = extracted_node
+        elif 0 <= duplicate_idx < len(indexes.existing_nodes):
+            resolved_node = indexes.existing_nodes[duplicate_idx]
+        else:
+            logger.warning(
+                'Invalid duplicate_idx %s for extracted node %s; treating as no duplicate.',
+                duplicate_idx,
+                extracted_node.uuid,
+            )
+            resolved_node = extracted_node
 
         state.resolved_nodes[original_index] = resolved_node
         state.uuid_map[extracted_node.uuid] = resolved_node.uuid

{graphiti_core-0.30.0rc1 → graphiti_core-0.30.0rc3}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "graphiti-core"
 description = "A temporal graph building library"
-version = "0.30.0pre1"
+version = "0.30.0pre3"
 authors = [
     { name = "Paul Paliychuk", email = "paul@getzep.com" },
     { name = "Preston Rasmussen", email = "preston@getzep.com" },

{graphiti_core-0.30.0rc1 → graphiti_core-0.30.0rc3}/tests/utils/maintenance/test_node_operations.py

@@ -1,3 +1,4 @@
+import logging
 from collections import defaultdict
 from unittest.mock import AsyncMock, MagicMock
 
@@ -343,3 +344,136 @@ async def test_resolve_with_llm_updates_unresolved(monkeypatch):
     assert captured_context['existing_nodes'][0]['idx'] == 0
     assert isinstance(captured_context['existing_nodes'], list)
     assert state.duplicate_pairs == [(extracted, candidate)]
+
+
+@pytest.mark.asyncio
+async def test_resolve_with_llm_ignores_out_of_range_relative_ids(monkeypatch, caplog):
+    extracted = EntityNode(name='Dexter', group_id='group', labels=['Entity'])
+
+    indexes = _build_candidate_indexes([])
+    state = DedupResolutionState(resolved_nodes=[None], uuid_map={}, unresolved_indices=[0])
+
+    monkeypatch.setattr(
+        'graphiti_core.utils.maintenance.node_operations.prompt_library.dedupe_nodes.nodes',
+        lambda context: ['prompt'],
+    )
+
+    llm_client = MagicMock()
+    llm_client.generate_response = AsyncMock(
+        return_value={
+            'entity_resolutions': [
+                {
+                    'id': 5,
+                    'duplicate_idx': -1,
+                    'name': 'Dexter',
+                    'duplicates': [],
+                }
+            ]
+        }
+    )
+
+    with caplog.at_level(logging.WARNING):
+        await _resolve_with_llm(
+            llm_client,
+            [extracted],
+            indexes,
+            state,
+            ensure_ascii=False,
+            episode=_make_episode(),
+            previous_episodes=[],
+            entity_types=None,
+        )
+
+    assert state.resolved_nodes[0] is None
+    assert 'Skipping invalid LLM dedupe id 5' in caplog.text
+
+
+@pytest.mark.asyncio
+async def test_resolve_with_llm_ignores_duplicate_relative_ids(monkeypatch):
+    extracted = EntityNode(name='Dizzy', group_id='group', labels=['Entity'])
+    candidate = EntityNode(name='Dizzy Gillespie', group_id='group', labels=['Entity'])
+
+    indexes = _build_candidate_indexes([candidate])
+    state = DedupResolutionState(resolved_nodes=[None], uuid_map={}, unresolved_indices=[0])
+
+    monkeypatch.setattr(
+        'graphiti_core.utils.maintenance.node_operations.prompt_library.dedupe_nodes.nodes',
+        lambda context: ['prompt'],
+    )
+
+    llm_client = MagicMock()
+    llm_client.generate_response = AsyncMock(
+        return_value={
+            'entity_resolutions': [
+                {
+                    'id': 0,
+                    'duplicate_idx': 0,
+                    'name': 'Dizzy Gillespie',
+                    'duplicates': [0],
+                },
+                {
+                    'id': 0,
+                    'duplicate_idx': -1,
+                    'name': 'Dizzy',
+                    'duplicates': [],
+                },
+            ]
+        }
+    )
+
+    await _resolve_with_llm(
+        llm_client,
+        [extracted],
+        indexes,
+        state,
+        ensure_ascii=False,
+        episode=_make_episode(),
+        previous_episodes=[],
+        entity_types=None,
+    )
+
+    assert state.resolved_nodes[0].uuid == candidate.uuid
+    assert state.uuid_map[extracted.uuid] == candidate.uuid
+    assert state.duplicate_pairs == [(extracted, candidate)]
+
+
+@pytest.mark.asyncio
+async def test_resolve_with_llm_invalid_duplicate_idx_defaults_to_extracted(monkeypatch):
+    extracted = EntityNode(name='Dexter', group_id='group', labels=['Entity'])
+
+    indexes = _build_candidate_indexes([])
+    state = DedupResolutionState(resolved_nodes=[None], uuid_map={}, unresolved_indices=[0])
+
+    monkeypatch.setattr(
+        'graphiti_core.utils.maintenance.node_operations.prompt_library.dedupe_nodes.nodes',
+        lambda context: ['prompt'],
+    )
+
+    llm_client = MagicMock()
+    llm_client.generate_response = AsyncMock(
+        return_value={
+            'entity_resolutions': [
+                {
+                    'id': 0,
+                    'duplicate_idx': 10,
+                    'name': 'Dexter',
+                    'duplicates': [],
+                }
+            ]
+        }
+    )
+
+    await _resolve_with_llm(
+        llm_client,
+        [extracted],
+        indexes,
+        state,
+        ensure_ascii=False,
+        episode=_make_episode(),
+        previous_episodes=[],
+        entity_types=None,
+    )
+
+    assert state.resolved_nodes[0] == extracted
+    assert state.uuid_map[extracted.uuid] == extracted.uuid
+    assert state.duplicate_pairs == []

{graphiti_core-0.30.0rc1 → graphiti_core-0.30.0rc3}/uv.lock

@@ -783,7 +783,7 @@ wheels = [
 
 [[package]]
 name = "graphiti-core"
-version = "0.30.0rc1"
+version = "0.30.0rc3"
 source = { editable = "." }
 dependencies = [
     { name = "diskcache" },