File size: 12,049 Bytes
9c8bf34
d3f7d23
 
9c8bf34
 
 
 
 
d3f7d23
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
9c8bf34
 
 
 
d3f7d23
9c8bf34
 
 
 
d3f7d23
 
 
9c8bf34
 
 
 
 
d3f7d23
9c8bf34
 
 
 
 
 
 
 
 
d3f7d23
9c8bf34
d3f7d23
9c8bf34
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
d3f7d23
9c8bf34
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
d3f7d23
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
9c8bf34
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
d3f7d23
 
 
 
 
9c8bf34
 
d3f7d23
9c8bf34
 
d3f7d23
 
 
9c8bf34
d3f7d23
 
 
 
 
 
 
 
9c8bf34
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
d3f7d23
 
 
 
 
 
9c8bf34
 
d3f7d23
9c8bf34
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
import logging
from typing import List, Dict, Any, Optional
from pydantic import BaseModel, Field
from google import genai
from google.genai import types

logger = logging.getLogger("rag_backend")

class EntityModel(BaseModel):
    name: str = Field(..., description="The name of the entity, e.g. 'Albert Einstein', 'Google', 'Gravity'. Keep it concise, singular, and normalized.")
    type: str = Field(..., description="The category/type of entity, e.g., Person, Organization, Concept, Location, Product.")
    description: str = Field(..., description="A short sentence summarizing what or who this entity is based on the text.")

class RelationshipModel(BaseModel):
    source: str = Field(..., description="The name of the source entity.")
    target: str = Field(..., description="The name of the target entity.")
    type: str = Field(..., description="The type of connection, e.g., WORKS_AT, INVENTED, IS_A, PART_OF, ASSOCIATED_WITH. Uppercase snake_case preferred.")
    description: str = Field(..., description="A short clause explaining the connection (e.g. 'discovered general relativity').")

class GraphExtractionModel(BaseModel):
    entities: List[EntityModel]
    relationships: List[RelationshipModel]

def extract_graph_elements(chunk_text: str) -> GraphExtractionModel:
    """
    Uses Gemini structured outputs to extract key entities and relationships from a text chunk.
    """
    try:
        client = genai.Client()
        response = client.models.generate_content(
            model="gemini-2.5-flash",
            contents=f"Analyze the following text chunk and extract key entities and their semantic relationships:\n\n{chunk_text}",
            config=types.GenerateContentConfig(
                response_mime_type="application/json",
                response_schema=GraphExtractionModel,
                system_instruction=(
                    "You are a precise information extraction engine. Extract only entities and relations that are "
                    "explicitly supported by the text chunk. Do not extrapolate. Keep entity names normalized (e.g. use "
                    "singular nouns, expand acronyms if clear)."
                )
            )
        )
        return GraphExtractionModel.model_validate_json(response.text)
    except Exception as e:
        logger.error(f"Failed to extract graph elements from text: {e}")
        return GraphExtractionModel(entities=[], relationships=[])

def run_agent_rag(
    user_message: str,
    embedding_model,
    vector_store,
    graph_store=None,
    chat_history: list = None
):
    """
    Executes an Agentic RAG loop using the Gemini API (via the google-genai SDK).
    It defines custom search tools over Qdrant (vector) and Neo4j (graph) databases,
    allowing the model to dynamically decide when to call which tool, handles query 
    reformulation/multi-step searches, and returns final answers alongside traces.
    
    Args:
        user_message: The prompt/query from the user.
        embedding_model: The SentenceTransformer embedding model to vectorize search queries.
        vector_store: The QdrantVectorStore instance to search documents.
        graph_store: The Neo4jGraphStore instance to query knowledge graph relationships.
        chat_history: Optional history of the conversation formatted as a list of dicts.
    """
    # Trace variables to return for API response
    tool_calls_log = []
    retrieved_documents = []

    # 1. Define the Vector Search Tool
    def query_knowledge_base(query: str, top_k: int = 3) -> str:
        """
        Searches the internal vector database for relevant document chunks.
        Use this tool when the user asks questions that require retrieving facts
        or searching general text documents.
        
        Args:
            query: The search query to run against the vector database.
            top_k: Number of relevant results to retrieve (default: 3).
        """
        logger.info(f"Agent tool executing: query_knowledge_base with query='{query}' and top_k={top_k}")
        
        try:
            # Generate query embedding
            query_embedding = embedding_model.encode(query, show_progress_bar=False).tolist()
            # Query the Qdrant database
            search_results = vector_store.search(query_embedding, top_k=top_k)
        except Exception as e:
            logger.error(f"Error querying vector store in agent tool: {e}")
            raise e
        
        call_details = {
            "query": query,
            "top_k": top_k,
            "results_count": len(search_results),
            "results": []
        }
        
        if not search_results:
            tool_calls_log.append(call_details)
            return "No matching documents found in the vector database."
            
        formatted_chunks = []
        for i, hit in enumerate(search_results):
            text = hit.get("text", "")
            metadata = hit.get("metadata", {})
            score = hit.get("score", 0.0)
            
            # Format document for the agent
            source_name = metadata.get("source", "unknown")
            formatted_chunks.append(f"Document {i+1} (Source: {source_name}, Similarity Score: {score:.3f}):\n{text}")
            
            # Save detail for response metadata
            doc_detail = {"text": text, "score": score, "metadata": metadata}
            call_details["results"].append(doc_detail)
            retrieved_documents.append(doc_detail)
            
        tool_calls_log.append(call_details)
        return "\n\n".join(formatted_chunks)

    # 1b. Define the Graph Search Tool
    def query_graph_database(entity_names: List[str]) -> str:
        """
        Queries the internal Neo4j Knowledge Graph for relationships, properties, and 
        connections surrounding specific key entities/concepts. Use this tool when 
        you need to answer complex relationship queries, find paths between topics, 
        or see how concepts connect to each other.
        
        Args:
            entity_names: A list of entity names/concepts to look up in the graph database.
        """
        logger.info(f"Agent tool executing: query_graph_database with entities={entity_names}")
        if not graph_store or not graph_store.is_connected:
            return "Graph database connection is not available. Please fall back to query_knowledge_base (vector search)."
        
        try:
            result = graph_store.query_subgraph(entity_names)
            call_details = {
                "query": f"Graph lookup for: {entity_names}",
                "top_k": len(entity_names),
                "results_count": 1 if result else 0,
                "results": [{"text": result, "score": 1.0, "metadata": {"entities": entity_names}}]
            }
            tool_calls_log.append(call_details)
            return result
        except Exception as e:
            logger.error(f"Error querying Neo4j in agent tool: {e}")
            return f"Error querying graph database: {str(e)}"

    # 2. Initialize Gemini Client (picks up GEMINI_API_KEY from environment)
    client = genai.Client()
    model_name = "gemini-2.5-flash"
    
    # 3. Setup conversation history
    contents = []
    if chat_history:
        for turn in chat_history:
            role = turn.get("role", "user")
            content = turn.get("content", "")
            contents.append(types.Content(
                role=role,
                parts=[types.Part.from_text(text=content)]
            ))
            
    # Add current user prompt
    contents.append(types.Content(
        role="user",
        parts=[types.Part.from_text(text=user_message)]
    ))
    
    # Register available tools
    tools = [query_knowledge_base]
    if graph_store and graph_store.is_connected:
        tools.append(query_graph_database)

    # Generate content configuration with system instruction and tools
    config = types.GenerateContentConfig(
        tools=tools,
        automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True),
        system_instruction=(
            "You are a helpful, precise Agentic RAG assistant. You have access to a vector search tool (query_knowledge_base) "
            + ("and a graph search tool (query_graph_database). " if len(tools) > 1 else "") +
            "Follow these guidelines:\n"
            "1. If a query requires factual information from the database, call the tool query_knowledge_base first.\n"
            + ("2. If the user asks about connections, relationships, paths, or structured associations between specific concepts, "
               "call query_graph_database with the list of concept/entity names.\n" if len(tools) > 1 else "") +
            "3. Inspect the retrieved context. If it does not answer the question or you need more information, you "
            "may call the tools again with a reformulated or more specific query. You can use both tools in a multi-step sequence.\n"
            "4. If the user's request is simple chitchat or doesn't require database lookups (e.g. 'hello', 'how are you'), "
            "do not call the tools; answer directly.\n"
            "5. Make sure your final answer is fully grounded in the retrieved documents or relationships. State clearly if "
            "some information was not found or could not be verified in the databases."
        )
    )
    
    # 4. Run the reasoning/retrieval loop
    logger.info("Initiating agentic RAG call to Gemini...")
    response = client.models.generate_content(
        model=model_name,
        contents=contents,
        config=config
    )
    
    iterations = 0
    max_iterations = 5  # Safety threshold to prevent infinite tool loops
    
    while response.function_calls and iterations < max_iterations:
        iterations += 1
        logger.info(f"Agentic loop: Iteration {iterations}, Model requested function calls: {len(response.function_calls)}")
        
        # Append the assistant's function call response to history
        contents.append(response.candidates[0].content)
        
        # Run requested tools
        function_responses = []
        for call in response.function_calls:
            func_args = call.args if call.args else {}
            try:
                if call.name == "query_knowledge_base":
                    result = query_knowledge_base(**func_args)
                elif call.name == "query_graph_database":
                    result = query_graph_database(**func_args)
                else:
                    result = f"Unknown tool: {call.name}"
            except Exception as e:
                logger.error(f"Error executing agent tool '{call.name}': {e}")
                result = f"Error executing tool {call.name}: {str(e)}"
                
            function_responses.append(
                types.Part.from_function_response(
                    name=call.name,
                    response={"result": result}
                )
            )
            
        # Append the tool's response to history
        contents.append(types.Content(role="tool", parts=function_responses))
        
        # Call model again with updated history
        response = client.models.generate_content(
            model=model_name,
            contents=contents,
            config=config
        )
        
    # If the model gets stuck in a loop, force a final text generation without tools
    if response.function_calls and iterations >= max_iterations:
        logger.warning(f"Agent exceeded maximum tool call iterations ({max_iterations}). Exiting loop.")
        config_no_tools = types.GenerateContentConfig(
            system_instruction=config.system_instruction
        )
        response = client.models.generate_content(
            model=model_name,
            contents=contents,
            config=config_no_tools
        )

    # Return final output
    return {
        "answer": response.text,
        "tool_calls": tool_calls_log,
        "sources": retrieved_documents
    }