Spaces:
Runtime error
Runtime error
Download agent.py from its-seraj/rag-backend-api: direct link, hf CLI and curl.
- Browser
- Download file 12 kB
-
https://huggingface.co/spaces/its-seraj/rag-backend-api/resolve/main/agent.py
- Command line
-
hf download hf://spaces/its-seraj/rag-backend-api/agent.py
-
curl -L -o agent.py https://huggingface.co/spaces/its-seraj/rag-backend-api/resolve/main/agent.py
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 | |
| } | |