rag-backend-api / agent.py
seraj-b2
graph rag added
d3f7d23
Raw History Blame Contribute Delete
12 kB
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
}