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 }