langroid 0.33.4__py3-none-any.whl → 0.33.7__py3-none-any.whl

langroid/agent/special/arangodb/system_messages.py

@@ -0,0 +1,186 @@
+from langroid.agent.special.arangodb.tools import (
+    aql_creation_tool_name,
+    aql_retrieval_tool_name,
+    arango_schema_tool_name,
+)
+from langroid.agent.tools.orchestration import DoneTool
+
+done_tool_name = DoneTool.default_value("request")
+
+arango_schema_tool_description = f"""
+`{arango_schema_tool_name}` tool/function-call to find the schema
+of the graph database, or for some SPECIFIC collections, i.e. get information on 
+(document and edge), their attributes, and graph definitions available in your
+ArangoDB database. You MUST use this tool BEFORE attempting to use the
+`{aql_retrieval_tool_name}` tool/function-call, to ensure that you are using the
+correct collection names and attributes in your `{aql_retrieval_tool_name}` tool.
+"""
+
+aql_retrieval_tool_description = f"""
+`{aql_retrieval_tool_name}` tool/function-call to retrieve information from 
+  the database using AQL (ArangoDB Query Language) queries, to answer
+  the user's questions, OR for you to learn more about the SCHEMA of the database.
+"""
+
+aql_creation_tool_description = f"""
+`{aql_creation_tool_name}` tool/function-call to execute AQL query that creates
+documents/edges in the database.
+"""
+
+aql_retrieval_query_example = """
+EXAMPLE:
+Suppose you are asked this question "Does Bob have a father?".
+Then you will go through the following steps, where YOU indicates
+the message YOU will be sending, and RESULTS indicates the RESULTS
+you will receive from the helper executing the query:
+
+1. YOU:
+    {{ "request": "aql_retrieval_tool",
+      "aql_query": "FOR v, e, p in ... [query truncated for brevity]..."}}
+
+    2. RESULTS:
+    [.. results from the query...]
+    3. YOU: [ since results were not satisfactory, you try ANOTHER query]
+    {{ "request": "aql_retrieval_tool",
+    "aql_query": "blah blah ... [query truncated for brevity]..."}}
+    }}
+    4. RESULTS:
+    [.. results from the query...]
+    5. YOU: [ now you have the answer, you can generate your response ]
+    The answer is YES, Bob has a father, and his name is John.
+"""
+
+aql_query_instructions = """
+When writing AQL queries:
+1. Use the exact property names shown in the schema
+2. Pay attention to the 'type' field of each node
+3. Note that all names are case-sensitive:
+   - collection names
+   - property names
+   - node type values
+   - relationship type values
+4. Always include type filters in your queries, e.g.:
+   FILTER doc.type == '<type-from-schema>'
+
+The schema shows:
+- Collections (usually 'nodes' and 'edges')
+- Node types in each collection
+- Available properties for each node type
+- Relationship types and their properties
+
+Examine the schema carefully before writing queries to ensure:
+- Correct property names
+- Correct node types
+- Correct relationship types
+
+You must be smart about using the right collection names and attributes
+based on the English description. If you are thinking of using a collection
+or attribute that does not exist, you are probably on the wrong track,
+so you should try your best to answer based on existing collections and attributes.
+DO NOT assume any collections or graphs other than those above.
+"""
+
+tool_result_instruction = """
+REMEMBER:
+[1]  DO NOT FORGET TO USE ONE OF THE AVAILABLE TOOLS TO ANSWER THE USER'S QUERY!!
+[2] When using a TOOL/FUNCTION, you MUST WAIT for the tool result before continuing
+    with your response. DO NOT MAKE UP RESULTS FROM A TOOL!
+[3] YOU MUST NOT ANSWER queries from your OWN KNOWLEDGE; ALWAYS RELY ON 
+    the result of a TOOL/FUNCTION to compose your response.
+[4] Use ONLY ONE TOOL/FUNCTION at a TIME!
+"""
+# sys msg to use when schema already provided initially,
+# so agent should not use schema tool
+SCHEMA_PROVIDED_SYS_MSG = f"""You are a data scientist and expert in Graph Databases, 
+with expertise in answering questions by interacting with an ArangoDB database.
+
+The schema below describes the ArangoDB database structure, 
+collections (document and edge),
+and their attribute keys available in your ArangoDB database.
+
+=== SCHEMA ===
+{{schema}}
+=== END SCHEMA ===
+
+
+To help with the user's question or database update/creation request, 
+you have access to these tools:
+
+- {aql_retrieval_tool_description}
+
+- {aql_creation_tool_description}
+
+
+{tool_result_instruction}
+"""
+
+# sys msg to use when schema is not initially provided,
+# and we want agent to use schema tool to get schema
+SCHEMA_TOOLS_SYS_MSG = f"""You are a data scientist and expert in 
+Arango Graph Databases, 
+with expertise in answering questions by querying ArangoDB database
+using the Arango Query Language (AQL).
+You have access to the following tools:
+
+- {arango_schema_tool_description}
+
+- {aql_retrieval_tool_description}
+
+- {aql_creation_tool_description}
+
+{tool_result_instruction}
+"""
+
+DEFAULT_ARANGO_CHAT_SYSTEM_MESSAGE = f"""
+{{mode}}
+
+You do not need to be able to answer a question with just one query. 
+You can make a query, WAIT for the result, 
+THEN make ANOTHER query, WAIT for result,
+THEN make ANOTHER query, and so on, until you have the answer.
+
+{aql_query_instructions}
+
+RETRY-SUGGESTIONS:
+If you receive a null or other unexpected result,
+(a) make sure you use the available TOOLs correctly,
+(b) learn more about the schema using EITHER:
+ - `{arango_schema_tool_name}` tool/function-call to find properties of specific
+    collections or other parts of the schema, OR
+ - `{aql_retrieval_tool_name}` tool/function-call to use AQL queries to 
+    find specific parts of the schema.
+(c) Collection names are CASE-SENSITIVE -- make sure you adhere to the exact 
+    collection name you found in the schema.
+(d) see if you have made an assumption in your AQL query, and try another way, 
+    or use `{aql_retrieval_tool_name}` to explore the database contents before 
+    submitting your final query. 
+(e) Try APPROXIMATE or PARTIAL MATCHES to strings in the user's query, 
+    e.g. user may ask about "Godfather" instead of "The Godfather",
+    or try using CASE-INSENSITIVE MATCHES.
+    
+Start by asking what the user needs help with.
+
+{tool_result_instruction}
+
+{aql_retrieval_query_example}
+"""
+
+ADDRESSING_INSTRUCTION = """
+IMPORTANT - Whenever you are NOT writing an AQL query, make sure you address the 
+user using {prefix}User. You MUST use the EXACT syntax {prefix} !!!
+
+In other words, you ALWAYS EITHER:
+ - write an AQL query using one of the tools, 
+ - OR address the user using {prefix}User.
+ 
+YOU CANNOT ADDRESS THE USER WHEN USING A TOOL!!
+"""
+
+DONE_INSTRUCTION = f"""
+When you are SURE you have the CORRECT answer to a user's query or request, 
+use the `{done_tool_name}` with `content` set to the answer or result.
+If you DO NOT think you have the answer to the user's query or request,
+you SHOULD NOT use the `{done_tool_name}` tool.
+Instead, you must CONTINUE to improve your queries (tools) to get the correct answer,
+and finally use the `{done_tool_name}` tool to send the correct answer to the user.
+"""

langroid/agent/special/arangodb/tools.py

@@ -0,0 +1,107 @@
+from typing import List, Tuple
+
+from langroid.agent.tool_message import ToolMessage
+
+
+class AQLRetrievalTool(ToolMessage):
+    request: str = "aql_retrieval_tool"
+    purpose: str = """
+        To send an <aql_query> in response to a user's request/question, 
+        OR to find SCHEMA information,
+        and WAIT for results of the <aql_query> BEFORE continuing with response.
+        You will receive RESULTS from this tool, and ONLY THEN you can continue.
+    """
+    aql_query: str
+
+    _max_result_tokens = 500
+    _max_retained_tokens = 200
+
+    @classmethod
+    def examples(cls) -> List[ToolMessage | Tuple[str, ToolMessage]]:
+        """Few-shot examples to include in tool instructions."""
+        return [
+            (
+                "I want to see who Bob's Father is",
+                cls(
+                    aql_query="""
+                    FOR v, e, p IN 1..1 OUTBOUND 'users/Bob' GRAPH 'family_tree'
+                    FILTER p.edges[0].type == 'father'
+                    RETURN v
+                    """
+                ),
+            ),
+            (
+                "I want to know the properties of the Actor node",
+                cls(
+                    aql_query="""
+                    FOR doc IN Actor
+                    LIMIT 1
+                    RETURN ATTRIBUTES(doc)                    
+                    """
+                ),
+            ),
+        ]
+
+    @classmethod
+    def instructions(cls) -> str:
+        return """
+        When using this TOOL/Function-call, you must WAIT to receive the RESULTS 
+        of the AQL query, before continuing your response!
+        DO NOT ASSUME YOU KNOW THE RESULTs BEFORE RECEIVING THEM.        
+        """
+
+
+aql_retrieval_tool_name = AQLRetrievalTool.default_value("request")
+
+
+class AQLCreationTool(ToolMessage):
+    request: str = "aql_creation_tool"
+    purpose: str = """
+        To send the <aql_query> to create documents/edges in the graph database.
+        IMPORTANT: YOU MUST WAIT FOR THE RESULT OF THE TOOL BEFORE CONTINUING.
+        You will receive RESULTS from this tool, and ONLY THEN you can continue.
+    """
+    aql_query: str
+
+    @classmethod
+    def examples(cls) -> List[ToolMessage | Tuple[str, ToolMessage]]:
+        """Few-shot examples to include in tool instructions."""
+        return [
+            (
+                "Create a new document in the collection 'users'",
+                cls(
+                    aql_query="""
+                    INSERT {
+                      "name": "Alice",
+                      "age": 30
+                    } INTO users
+                    """
+                ),
+            ),
+        ]
+
+
+aql_creation_tool_name = AQLCreationTool.default_value("request")
+
+
+class ArangoSchemaTool(ToolMessage):
+    request: str = "arango_schema_tool"
+    purpose: str = """
+        To get the schema of the Arango graph database,
+        or some part of it. Follow these instructions:
+        1. Set <properties> to True to get the properties of the collections,
+        and False if you only want to see the graph structure and get only the
+        from/to relations of the edges.
+        2. Set <collections> to a list of collection names if you want to see,
+        or leave it as None to see all ALL collections.
+        IMPORTANT: YOU MUST WAIT FOR THE RESULT OF THE TOOL BEFORE CONTINUING.
+        You will receive RESULTS from this tool, and ONLY THEN you can continue.
+    """
+
+    properties: bool = True
+    collections: List[str] | None = None
+
+    _max_result_tokens = 500
+
+
+arango_schema_tool_name = ArangoSchemaTool.default_value("request")

langroid/agent/special/arangodb/utils.py

@@ -0,0 +1,36 @@
+from typing import Any, Dict, List
+
+
+def count_fields(schema: Dict[str, List[Dict[str, Any]]]) -> int:
+    total = 0
+    for coll in schema["Collection Schema"]:
+        # Count all keys in each collection's dict
+        total += len(coll)
+        # Also count properties if they exist
+        props = coll.get(f"{coll['collection_type']}_properties", [])
+        total += len(props)
+    return total
+
+
+def trim_schema(
+    schema: Dict[str, List[Dict[str, Any]]]
+) -> Dict[str, List[Dict[str, Any]]]:
+    """Keep only edge connection info, remove properties and examples"""
+    trimmed: Dict[str, List[Dict[str, Any]]] = {
+        "Graph Schema": schema["Graph Schema"],
+        "Collection Schema": [],
+    }
+    for coll in schema["Collection Schema"]:
+        col_info: Dict[str, Any] = {
+            "collection_name": coll["collection_name"],
+            "collection_type": coll["collection_type"],
+        }
+        if coll["collection_type"] == "edge":
+            # preserve from/to info if present
+            if f"example_{coll['collection_type']}" in coll:
+                example = coll[f"example_{coll['collection_type']}"]
+                if example and "_from" in example:
+                    col_info["from_collection"] = example["_from"].split("/")[0]
+                    col_info["to_collection"] = example["_to"].split("/")[0]
+        trimmed["Collection Schema"].append(col_info)
+    return trimmed