graphiti-core 0.20.4__py3-none-any.whl → 0.21.0__py3-none-any.whl

graphiti_core/prompts/dedupe_nodes.py

@@ -64,20 +64,20 @@ def node(context: dict[str, Any]) -> list[Message]:
             role='user',
             content=f"""
         <PREVIOUS MESSAGES>
-        {to_prompt_json([ep for ep in context['previous_episodes']], ensure_ascii=context.get('ensure_ascii', False), indent=2)}
+        {to_prompt_json([ep for ep in context['previous_episodes']], indent=2)}
         </PREVIOUS MESSAGES>
         <CURRENT MESSAGE>
         {context['episode_content']}
         </CURRENT MESSAGE>
         <NEW ENTITY>
-        {to_prompt_json(context['extracted_node'], ensure_ascii=context.get('ensure_ascii', False), indent=2)}
+        {to_prompt_json(context['extracted_node'], indent=2)}
         </NEW ENTITY>
         <ENTITY TYPE DESCRIPTION>
-        {to_prompt_json(context['entity_type_description'], ensure_ascii=context.get('ensure_ascii', False), indent=2)}
+        {to_prompt_json(context['entity_type_description'], indent=2)}
         </ENTITY TYPE DESCRIPTION>
 
         <EXISTING ENTITIES>
-        {to_prompt_json(context['existing_nodes'], ensure_ascii=context.get('ensure_ascii', False), indent=2)}
+        {to_prompt_json(context['existing_nodes'], indent=2)}
         </EXISTING ENTITIES>
         
         Given the above EXISTING ENTITIES and their attributes, MESSAGE, and PREVIOUS MESSAGES; Determine if the NEW ENTITY extracted from the conversation
@@ -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.
         """,
         ),
     ]
@@ -114,7 +125,7 @@ def nodes(context: dict[str, Any]) -> list[Message]:
             role='user',
             content=f"""
         <PREVIOUS MESSAGES>
-        {to_prompt_json([ep for ep in context['previous_episodes']], ensure_ascii=context.get('ensure_ascii', True), indent=2)}
+        {to_prompt_json([ep for ep in context['previous_episodes']], indent=2)}
         </PREVIOUS MESSAGES>
         <CURRENT MESSAGE>
         {context['episode_content']}
@@ -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)}
+        {to_prompt_json(context['extracted_nodes'], indent=2)}
         </ENTITIES>
-        
+
         <EXISTING ENTITIES>
-        {to_prompt_json(context['existing_nodes'], ensure_ascii=context.get('ensure_ascii', True), indent=2)}
+        {to_prompt_json(context['existing_nodes'], 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,20 @@ 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
+        ENTITIES contains {len(context['extracted_nodes'])} entities with IDs 0 through {len(context['extracted_nodes']) - 1}.
+        Your response MUST include EXACTLY {len(context['extracted_nodes'])} resolutions with IDs 0 through {len(context['extracted_nodes']) - 1}. Do not skip or add IDs.
+
+        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.
         """,
         ),
     ]
@@ -180,7 +197,7 @@ def node_list(context: dict[str, Any]) -> list[Message]:
         Given the following context, deduplicate a list of nodes:
 
         Nodes:
-        {to_prompt_json(context['nodes'], ensure_ascii=context.get('ensure_ascii', True), indent=2)}
+        {to_prompt_json(context['nodes'], indent=2)}
 
         Task:
         1. Group nodes together such that all duplicate nodes are in the same list of uuids

graphiti_core/prompts/eval.py

@@ -68,7 +68,7 @@ def query_expansion(context: dict[str, Any]) -> list[Message]:
     Bob is asking Alice a question, are you able to rephrase the question into a simpler one about Alice in the third person
     that maintains the relevant context?
     <QUESTION>
-    {to_prompt_json(context['query'], ensure_ascii=context.get('ensure_ascii', False))}
+    {to_prompt_json(context['query'])}
     </QUESTION>
     """
     return [
@@ -84,10 +84,10 @@ def qa_prompt(context: dict[str, Any]) -> list[Message]:
     Your task is to briefly answer the question in the way that you think Alice would answer the question.
     You are given the following entity summaries and facts to help you determine the answer to your question.
     <ENTITY_SUMMARIES>
-    {to_prompt_json(context['entity_summaries'], ensure_ascii=context.get('ensure_ascii', False))}
+    {to_prompt_json(context['entity_summaries'])}
     </ENTITY_SUMMARIES>
     <FACTS>
-    {to_prompt_json(context['facts'], ensure_ascii=context.get('ensure_ascii', False))}
+    {to_prompt_json(context['facts'])}
     </FACTS>
     <QUESTION>
     {context['query']}

graphiti_core/prompts/extract_edges.py

@@ -24,9 +24,16 @@ from .prompt_helpers import to_prompt_json
 
 class Edge(BaseModel):
     relation_type: str = Field(..., description='FACT_PREDICATE_IN_SCREAMING_SNAKE_CASE')
-    source_entity_id: int = Field(..., description='The id of the source entity of the fact.')
-    target_entity_id: int = Field(..., description='The id of the target entity of the fact.')
-    fact: str = Field(..., description='')
+    source_entity_id: int = Field(
+        ..., description='The id of the source entity from the ENTITIES list'
+    )
+    target_entity_id: int = Field(
+        ..., description='The id of the target entity from the ENTITIES list'
+    )
+    fact: str = Field(
+        ...,
+        description='A natural language description of the relationship between the entities, paraphrased from the source text',
+    )
     valid_at: str | None = Field(
         None,
         description='The date and time when the relationship described by the edge fact became true or was established. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS.SSSSSSZ)',
@@ -73,7 +80,7 @@ def edge(context: dict[str, Any]) -> list[Message]:
 </FACT TYPES>
 
 <PREVIOUS_MESSAGES>
-{to_prompt_json([ep for ep in context['previous_episodes']], ensure_ascii=context.get('ensure_ascii', False), indent=2)}
+{to_prompt_json([ep for ep in context['previous_episodes']], indent=2)}
 </PREVIOUS_MESSAGES>
 
 <CURRENT_MESSAGE>
@@ -81,7 +88,7 @@ def edge(context: dict[str, Any]) -> list[Message]:
 </CURRENT_MESSAGE>
 
 <ENTITIES>
-{context['nodes']} 
+{to_prompt_json(context['nodes'], indent=2)}
 </ENTITIES>
 
 <REFERENCE_TIME>
@@ -107,11 +114,12 @@ You may use information from the PREVIOUS MESSAGES only to disambiguate referenc
 
 # EXTRACTION RULES
 
-1. Only emit facts where both the subject and object match IDs in ENTITIES.
+1. **Entity ID Validation**: `source_entity_id` and `target_entity_id` must use only the `id` values from the ENTITIES list provided above.
+   - **CRITICAL**: Using IDs not in the list will cause the edge to be rejected
 2. Each fact must involve two **distinct** entities.
 3. Use a SCREAMING_SNAKE_CASE string as the `relation_type` (e.g., FOUNDED, WORKS_AT).
 4. Do not emit duplicate or semantically redundant facts.
-5. The `fact_text` should quote or closely paraphrase the original source sentence(s).
+5. The `fact` should closely paraphrase the original source sentence(s). Do not verbatim quote the original text.
 6. Use `REFERENCE_TIME` to resolve vague or relative temporal expressions (e.g., "last week").
 7. Do **not** hallucinate or infer temporal bounds from unrelated events.
 
@@ -133,7 +141,7 @@ def reflexion(context: dict[str, Any]) -> list[Message]:
 
     user_prompt = f"""
 <PREVIOUS MESSAGES>
-{to_prompt_json([ep for ep in context['previous_episodes']], ensure_ascii=context.get('ensure_ascii', False), indent=2)}
+{to_prompt_json([ep for ep in context['previous_episodes']], indent=2)}
 </PREVIOUS MESSAGES>
 <CURRENT MESSAGE>
 {context['episode_content']}
@@ -167,7 +175,7 @@ def extract_attributes(context: dict[str, Any]) -> list[Message]:
             content=f"""
 
         <MESSAGE>
-        {to_prompt_json(context['episode_content'], ensure_ascii=context.get('ensure_ascii', False), indent=2)}
+        {to_prompt_json(context['episode_content'], indent=2)}
         </MESSAGE>
         <REFERENCE TIME>
         {context['reference_time']}

graphiti_core/prompts/extract_nodes.py

@@ -89,7 +89,7 @@ def extract_message(context: dict[str, Any]) -> list[Message]:
 </ENTITY TYPES>
 
 <PREVIOUS MESSAGES>
-{to_prompt_json([ep for ep in context['previous_episodes']], ensure_ascii=context.get('ensure_ascii', True), indent=2)}
+{to_prompt_json([ep for ep in context['previous_episodes']], indent=2)}
 </PREVIOUS MESSAGES>
 
 <CURRENT MESSAGE>
@@ -151,8 +151,9 @@ For each entity extracted, also determine its entity type based on the provided
 Indicate the classified entity type by providing its entity_type_id.
 
 Guidelines:
-1. Always try to extract an entities that the JSON represents. This will often be something like a "name" or "user field
-2. Do NOT extract any properties that contain dates
+1. Extract all entities that the JSON represents. This will often be something like a "name" or "user" field
+2. Extract all entities mentioned in all other properties throughout the JSON structure
+3. Do NOT extract any properties that contain dates
 """
     return [
         Message(role='system', content=sys_prompt),
@@ -196,7 +197,7 @@ def reflexion(context: dict[str, Any]) -> list[Message]:
 
     user_prompt = f"""
 <PREVIOUS MESSAGES>
-{to_prompt_json([ep for ep in context['previous_episodes']], ensure_ascii=context.get('ensure_ascii', True), indent=2)}
+{to_prompt_json([ep for ep in context['previous_episodes']], indent=2)}
 </PREVIOUS MESSAGES>
 <CURRENT MESSAGE>
 {context['episode_content']}
@@ -220,7 +221,7 @@ def classify_nodes(context: dict[str, Any]) -> list[Message]:
 
     user_prompt = f"""
     <PREVIOUS MESSAGES>
-    {to_prompt_json([ep for ep in context['previous_episodes']], ensure_ascii=context.get('ensure_ascii', True), indent=2)}
+    {to_prompt_json([ep for ep in context['previous_episodes']], indent=2)}
     </PREVIOUS MESSAGES>
     <CURRENT MESSAGE>
     {context['episode_content']}
@@ -258,8 +259,8 @@ def extract_attributes(context: dict[str, Any]) -> list[Message]:
             content=f"""
 
         <MESSAGES>
-        {to_prompt_json(context['previous_episodes'], ensure_ascii=context.get('ensure_ascii', True), indent=2)}
-        {to_prompt_json(context['episode_content'], ensure_ascii=context.get('ensure_ascii', True), indent=2)}
+        {to_prompt_json(context['previous_episodes'], indent=2)}
+        {to_prompt_json(context['episode_content'], indent=2)}
         </MESSAGES>
 
         Given the above MESSAGES and the following ENTITY, update any of its attributes based on the information provided
@@ -288,8 +289,8 @@ def extract_summary(context: dict[str, Any]) -> list[Message]:
             content=f"""
 
         <MESSAGES>
-        {to_prompt_json(context['previous_episodes'], ensure_ascii=context.get('ensure_ascii', True), indent=2)}
-        {to_prompt_json(context['episode_content'], ensure_ascii=context.get('ensure_ascii', True), indent=2)}
+        {to_prompt_json(context['previous_episodes'], indent=2)}
+        {to_prompt_json(context['episode_content'], indent=2)}
         </MESSAGES>
 
         Given the above MESSAGES and the following ENTITY, update the summary that combines relevant information about the entity

graphiti_core/prompts/prompt_helpers.py

@@ -4,20 +4,20 @@ from typing import Any
 DO_NOT_ESCAPE_UNICODE = '\nDo not escape unicode characters.\n'
 
 
-def to_prompt_json(data: Any, ensure_ascii: bool = True, indent: int = 2) -> str:
+def to_prompt_json(data: Any, ensure_ascii: bool = False, indent: int = 2) -> str:
     """
     Serialize data to JSON for use in prompts.
 
     Args:
         data: The data to serialize
-        ensure_ascii: If True, escape non-ASCII characters. If False, preserve them.
+        ensure_ascii: If True, escape non-ASCII characters. If False (default), preserve them.
         indent: Number of spaces for indentation
 
     Returns:
         JSON string representation of the data
 
     Notes:
-        When ensure_ascii=False, non-ASCII characters (e.g., Korean, Japanese, Chinese)
+        By default (ensure_ascii=False), non-ASCII characters (e.g., Korean, Japanese, Chinese)
         are preserved in their original form in the prompt, making them readable
         in LLM logs and improving model understanding.
     """

graphiti_core/prompts/summarize_nodes.py

@@ -59,7 +59,7 @@ def summarize_pair(context: dict[str, Any]) -> list[Message]:
         Summaries must be under 250 words.
 
         Summaries:
-        {to_prompt_json(context['node_summaries'], ensure_ascii=context.get('ensure_ascii', True), indent=2)}
+        {to_prompt_json(context['node_summaries'], indent=2)}
         """,
         ),
     ]
@@ -76,8 +76,8 @@ def summarize_context(context: dict[str, Any]) -> list[Message]:
             content=f"""
             
         <MESSAGES>
-        {to_prompt_json(context['previous_episodes'], ensure_ascii=context.get('ensure_ascii', True), indent=2)}
-        {to_prompt_json(context['episode_content'], ensure_ascii=context.get('ensure_ascii', True), indent=2)}
+        {to_prompt_json(context['previous_episodes'], indent=2)}
+        {to_prompt_json(context['episode_content'], indent=2)}
         </MESSAGES>
         
         Given the above MESSAGES and the following ENTITY name, create a summary for the ENTITY. Your summary must only use
@@ -100,7 +100,7 @@ def summarize_context(context: dict[str, Any]) -> list[Message]:
         </ENTITY CONTEXT>
         
         <ATTRIBUTES>
-        {to_prompt_json(context['attributes'], ensure_ascii=context.get('ensure_ascii', True), indent=2)}
+        {to_prompt_json(context['attributes'], indent=2)}
         </ATTRIBUTES>
         """,
         ),
@@ -120,7 +120,7 @@ def summary_description(context: dict[str, Any]) -> list[Message]:
         Summaries must be under 250 words.
 
         Summary:
-        {to_prompt_json(context['summary'], ensure_ascii=context.get('ensure_ascii', True), indent=2)}
+        {to_prompt_json(context['summary'], indent=2)}
         """,
         ),
     ]

graphiti_core/search/search_filters.py

@@ -52,6 +52,17 @@ class SearchFilters(BaseModel):
     invalid_at: list[list[DateFilter]] | None = Field(default=None)
     created_at: list[list[DateFilter]] | None = Field(default=None)
     expired_at: list[list[DateFilter]] | None = Field(default=None)
+    edge_uuids: list[str] | None = Field(default=None)
+
+
+def cypher_to_opensearch_operator(op: ComparisonOperator) -> str:
+    mapping = {
+        ComparisonOperator.greater_than: 'gt',
+        ComparisonOperator.less_than: 'lt',
+        ComparisonOperator.greater_than_equal: 'gte',
+        ComparisonOperator.less_than_equal: 'lte',
+    }
+    return mapping.get(op, op.value)
 
 
 def node_search_filter_query_constructor(
@@ -98,6 +109,10 @@ def edge_search_filter_query_constructor(
         filter_queries.append('e.name in $edge_types')
         filter_params['edge_types'] = edge_types
 
+    if filters.edge_uuids is not None:
+        filter_queries.append('e.uuid in $edge_uuids')
+        filter_params['edge_uuids'] = filters.edge_uuids
+
     if filters.node_labels is not None:
         if provider == GraphProvider.KUZU:
             node_label_filter = (
@@ -234,3 +249,41 @@ def edge_search_filter_query_constructor(
         filter_queries.append(expired_at_filter)
 
     return filter_queries, filter_params
+
+
+def build_aoss_node_filters(group_ids: list[str], search_filters: SearchFilters) -> list[dict]:
+    filters = [{'terms': {'group_id': group_ids}}]
+
+    if search_filters.node_labels:
+        filters.append({'terms': {'node_labels': search_filters.node_labels}})
+
+    return filters
+
+
+def build_aoss_edge_filters(group_ids: list[str], search_filters: SearchFilters) -> list[dict]:
+    filters: list[dict] = [{'terms': {'group_id': group_ids}}]
+
+    if search_filters.edge_types:
+        filters.append({'terms': {'edge_types': search_filters.edge_types}})
+
+    if search_filters.edge_uuids:
+        filters.append({'terms': {'uuid': search_filters.edge_uuids}})
+
+    for field in ['valid_at', 'invalid_at', 'created_at', 'expired_at']:
+        ranges = getattr(search_filters, field)
+        if ranges:
+            # OR of ANDs
+            should_clauses = []
+            for and_group in ranges:
+                and_filters = []
+                for df in and_group:  # df is a DateFilter
+                    range_query = {
+                        'range': {
+                            field: {cypher_to_opensearch_operator(df.comparison_operator): df.date}
+                        }
+                    }
+                    and_filters.append(range_query)
+                should_clauses.append({'bool': {'filter': and_filters}})
+            filters.append({'bool': {'should': should_clauses, 'minimum_should_match': 1}})
+
+    return filters

graphiti_core/search/search_helpers.py

@@ -24,9 +24,7 @@ def format_edge_date_range(edge: EntityEdge) -> str:
     return f'{edge.valid_at if edge.valid_at else "date unknown"} - {(edge.invalid_at if edge.invalid_at else "present")}'
 
 
-def search_results_to_context_string(
-    search_results: SearchResults, ensure_ascii: bool = False
-) -> str:
+def search_results_to_context_string(search_results: SearchResults) -> str:
     """Reformats a set of SearchResults into a single string to pass directly to an LLM as context"""
     fact_json = [
         {
@@ -58,16 +56,16 @@ def search_results_to_context_string(
     These are the most relevant facts and their valid and invalid dates. Facts are considered valid
     between their valid_at and invalid_at dates. Facts with an invalid_at date of "Present" are considered valid.
     <FACTS>
-            {to_prompt_json(fact_json, ensure_ascii=ensure_ascii, indent=12)}
+            {to_prompt_json(fact_json, indent=12)}
     </FACTS>
     <ENTITIES>
-            {to_prompt_json(entity_json, ensure_ascii=ensure_ascii, indent=12)}
+            {to_prompt_json(entity_json, indent=12)}
     </ENTITIES>
     <EPISODES>
-            {to_prompt_json(episode_json, ensure_ascii=ensure_ascii, indent=12)}
+            {to_prompt_json(episode_json, indent=12)}
     </EPISODES>
     <COMMUNITIES>
-            {to_prompt_json(community_json, ensure_ascii=ensure_ascii, indent=12)}
+            {to_prompt_json(community_json, indent=12)}
     </COMMUNITIES>
 """