Spaces:
Runtime error
Runtime error
Download main.py from its-seraj/rag-backend-api: direct link, hf CLI and curl.
- Browser
- Download file 23.5 kB
-
https://huggingface.co/spaces/its-seraj/rag-backend-api/resolve/main/main.py
- Command line
-
hf download hf://spaces/its-seraj/rag-backend-api/main.py
-
curl -L -o main.py https://huggingface.co/spaces/its-seraj/rag-backend-api/resolve/main/main.py
23.5 kB
| import io | |
| import json | |
| import logging | |
| from typing import List, Optional | |
| from fastapi import FastAPI, HTTPException, status, File, UploadFile, Form | |
| from fastapi.middleware.cors import CORSMiddleware | |
| from pydantic import BaseModel, Field | |
| from sentence_transformers import SentenceTransformer | |
| from langchain_text_splitters import RecursiveCharacterTextSplitter | |
| from pypdf import PdfReader | |
| import os | |
| import uuid | |
| from vector_store import QdrantVectorStore | |
| from graph_store import Neo4jGraphStore | |
| from agent import run_agent_rag, extract_graph_elements | |
| # Configure logging | |
| logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s") | |
| logger = logging.getLogger("rag_backend") | |
| # Initialize FastAPI App | |
| app = FastAPI( | |
| title="RAG Backend API", | |
| description="A highly performant RAG pipeline backend deployable to Hugging Face Spaces. It offers document ingestion (chunking, embedding) and vector retrieval.", | |
| version="1.0.0", | |
| docs_url="/docs", | |
| redoc_url="/redoc" | |
| ) | |
| # Enable CORS for ReactJS Frontend Integration | |
| app.add_middleware( | |
| CORSMiddleware, | |
| allow_origins=["*"], # Allows all origins, ideal for external React UI. Customize if needed. | |
| allow_credentials=True, | |
| allow_methods=["*"], | |
| allow_headers=["*"], | |
| ) | |
| # Initialize Embedding Model and Vector Store | |
| logger.info("Initializing SentenceTransformer model 'all-MiniLM-L6-v2'...") | |
| embedding_model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2") | |
| logger.info("SentenceTransformer model initialized successfully.") | |
| logger.info("Initializing Qdrant Vector Store...") | |
| vector_store = QdrantVectorStore() | |
| logger.info("Qdrant Vector Store initialized successfully.") | |
| logger.info("Initializing Neo4j Graph Store...") | |
| graph_store = Neo4jGraphStore() | |
| logger.info("Neo4j Graph Store initialized successfully.") | |
| # Pydantic Schemas for Request/Response Validation | |
| class DocumentInput(BaseModel): | |
| text: str = Field(..., description="The main text content of the document to index.") | |
| metadata: Optional[dict] = Field(default=None, description="Key-value pairs containing metadata (e.g. source, author, category).") | |
| class IngestionRequest(BaseModel): | |
| documents: List[DocumentInput] = Field(..., description="A list of documents to chunk, embed, and store.") | |
| chunk_size: int = Field(default=500, ge=50, le=5000, description="The maximum size of each text chunk in characters.") | |
| chunk_overlap: int = Field(default=50, ge=0, le=1000, description="The character overlap between adjacent chunks.") | |
| class IngestionResponse(BaseModel): | |
| status: str | |
| message: str | |
| documents_processed: int | |
| chunks_created: int | |
| class RetrievalRequest(BaseModel): | |
| query: str = Field(..., description="The search query to match against stored documents.") | |
| top_k: int = Field(default=3, ge=1, le=50, description="The maximum number of relevant chunks to retrieve.") | |
| class RetrievalResult(BaseModel): | |
| text: str | |
| score: float | |
| metadata: dict | |
| class RetrievalResponse(BaseModel): | |
| query: str | |
| results: List[RetrievalResult] | |
| context: List[str] # Array of strings to be used directly as LLM context | |
| class AgentChatTurn(BaseModel): | |
| role: str = Field(..., description="The role of the speaker, either 'user' or 'model'.") | |
| content: str = Field(..., description="The text content of the turn.") | |
| class AgentRequest(BaseModel): | |
| prompt: str = Field(..., description="The query/message to the agent.") | |
| chat_history: Optional[List[AgentChatTurn]] = Field(default=None, description="Optional conversation history for multi-turn chat.") | |
| class AgentResponse(BaseModel): | |
| answer: str = Field(..., description="The final text answer generated by the agent.") | |
| tool_calls: List[dict] = Field(..., description="A log of all tool calls made during reasoning.") | |
| sources: List[dict] = Field(..., description="A list of retrieved document chunks used as sources.") | |
| class GraphRetrieveRequest(BaseModel): | |
| query: str = Field(..., description="The query to extract entities from and search in the graph.") | |
| top_k_entities: int = Field(default=5, ge=1, le=20, description="The maximum number of entities to extract and query.") | |
| class GraphRetrieveResponse(BaseModel): | |
| query: str | |
| extracted_entities: List[str] | |
| relationships: str | |
| class GraphQueryRequest(BaseModel): | |
| query: str = Field(..., description="The user question to answer using the graph context.") | |
| class GraphQueryResponse(BaseModel): | |
| query: str | |
| answer: str | |
| context: str | |
| class EntityListModel(BaseModel): | |
| entities: List[str] = Field(..., description="List of normalized entity names/nouns found in the query.") | |
| # API Endpoints | |
| def root(): | |
| """ | |
| Root endpoint serving basic API metadata. | |
| """ | |
| return { | |
| "app": "RAG Backend Service", | |
| "version": "1.0.0", | |
| "documentation": "/docs", | |
| "status": "online" | |
| } | |
| def health(): | |
| """ | |
| Health check endpoint returning system status. | |
| """ | |
| return { | |
| "status": "healthy", | |
| "vector_store": vector_store.get_status(), | |
| "graph_store": graph_store.get_status() | |
| } | |
| def ingest_documents(payload: IngestionRequest): | |
| """ | |
| Ingests, chunks, embeds, and stores documents in the vector database. | |
| """ | |
| if not payload.documents: | |
| raise HTTPException( | |
| status_code=status.HTTP_400_BAD_REQUEST, | |
| detail="No documents were provided in the request." | |
| ) | |
| # Initialize LangChain text splitter | |
| text_splitter = RecursiveCharacterTextSplitter( | |
| chunk_size=payload.chunk_size, | |
| chunk_overlap=payload.chunk_overlap, | |
| length_function=len | |
| ) | |
| all_chunks: List[str] = [] | |
| all_metadatas: List[dict] = [] | |
| try: | |
| # Split documents into chunks | |
| for idx, doc in enumerate(payload.documents): | |
| chunks = text_splitter.split_text(doc.text) | |
| for chunk in chunks: | |
| all_chunks.append(chunk) | |
| # Propagate original document metadata, default to empty dict | |
| meta = doc.metadata.copy() if doc.metadata else {} | |
| meta["doc_index"] = idx | |
| all_metadatas.append(meta) | |
| if not all_chunks: | |
| return IngestionResponse( | |
| status="success", | |
| message="No chunks were created from the input documents.", | |
| documents_processed=len(payload.documents), | |
| chunks_created=0 | |
| ) | |
| logger.info(f"Generating embeddings for {len(all_chunks)} chunks...") | |
| # Compute embeddings in batch | |
| embeddings = embedding_model.encode(all_chunks, show_progress_bar=False).tolist() | |
| logger.info("Upserting vectors into Qdrant...") | |
| # Store in Qdrant | |
| chunks_inserted = vector_store.add_documents( | |
| texts=all_chunks, | |
| embeddings=embeddings, | |
| metadatas=all_metadatas | |
| ) | |
| # Dual indexing to Neo4j | |
| if graph_store.is_connected: | |
| logger.info("Extracting and indexing graph relationships into Neo4j...") | |
| for idx, chunk in enumerate(all_chunks): | |
| try: | |
| chunk_uuid = str(uuid.uuid4()) | |
| meta = all_metadatas[idx] | |
| source = meta.get("source", f"doc_{meta.get('doc_index', 0)}") | |
| graph_data = extract_graph_elements(chunk) | |
| entities_list = [ent.model_dump() for ent in graph_data.entities] | |
| relationships_list = [rel.model_dump() for rel in graph_data.relationships] | |
| graph_store.add_graph_data( | |
| chunk_id=chunk_uuid, | |
| chunk_text=chunk, | |
| source=source, | |
| entities=entities_list, | |
| relationships=relationships_list | |
| ) | |
| except Exception as ex: | |
| logger.error(f"Failed to index chunk {idx} in Neo4j: {ex}") | |
| return IngestionResponse( | |
| status="success", | |
| message=f"Successfully indexed {len(payload.documents)} documents into {chunks_inserted} chunks.", | |
| documents_processed=len(payload.documents), | |
| chunks_created=chunks_inserted | |
| ) | |
| except Exception as e: | |
| logger.error(f"Error during document ingestion: {e}") | |
| raise HTTPException( | |
| status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, | |
| detail=f"An error occurred while indexing documents: {str(e)}" | |
| ) | |
| async def upload_document( | |
| file: UploadFile = File(...), | |
| chunk_size: int = Form(500), | |
| chunk_overlap: int = Form(50), | |
| metadata: Optional[str] = Form(None) | |
| ): | |
| """ | |
| Ingests an uploaded document (.pdf or .txt), chunks, embeds, and stores it in the vector database. | |
| """ | |
| # Validate form parameters | |
| if chunk_size < 50 or chunk_size > 5000: | |
| raise HTTPException( | |
| status_code=status.HTTP_400_BAD_REQUEST, | |
| detail="chunk_size must be between 50 and 5000." | |
| ) | |
| if chunk_overlap < 0 or chunk_overlap > 1000: | |
| raise HTTPException( | |
| status_code=status.HTTP_400_BAD_REQUEST, | |
| detail="chunk_overlap must be between 0 and 1000." | |
| ) | |
| # Parse optional metadata JSON string | |
| parsed_metadata = {} | |
| if metadata: | |
| try: | |
| parsed_metadata = json.loads(metadata) | |
| if not isinstance(parsed_metadata, dict): | |
| raise HTTPException( | |
| status_code=status.HTTP_400_BAD_REQUEST, | |
| detail="Metadata must be a JSON object (dictionary)." | |
| ) | |
| except json.JSONDecodeError: | |
| raise HTTPException( | |
| status_code=status.HTTP_400_BAD_REQUEST, | |
| detail="Metadata must be a valid JSON-formatted string." | |
| ) | |
| filename = file.filename or "" | |
| content_type = file.content_type or "" | |
| logger.info(f"Received file upload: {filename} (Content-Type: {content_type})") | |
| try: | |
| file_bytes = await file.read() | |
| except Exception as e: | |
| logger.error(f"Failed to read uploaded file: {e}") | |
| raise HTTPException( | |
| status_code=status.HTTP_400_BAD_REQUEST, | |
| detail=f"Failed to read uploaded file: {str(e)}" | |
| ) | |
| text_content = "" | |
| is_pdf = filename.lower().endswith(".pdf") or content_type == "application/pdf" | |
| is_txt = filename.lower().endswith(".txt") or content_type.startswith("text/") | |
| if is_pdf: | |
| try: | |
| pdf_file = io.BytesIO(file_bytes) | |
| reader = PdfReader(pdf_file) | |
| extracted_pages = [] | |
| for page in reader.pages: | |
| page_text = page.extract_text() | |
| if page_text: | |
| extracted_pages.append(page_text) | |
| text_content = "\n".join(extracted_pages) | |
| if not text_content.strip(): | |
| raise HTTPException( | |
| status_code=status.HTTP_400_BAD_REQUEST, | |
| detail="The uploaded PDF file does not contain any extractable text." | |
| ) | |
| except HTTPException: | |
| raise | |
| except Exception as e: | |
| logger.error(f"Error parsing PDF file: {e}") | |
| raise HTTPException( | |
| status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, | |
| detail=f"Error parsing PDF file: {str(e)}" | |
| ) | |
| elif is_txt or content_type == "": | |
| try: | |
| text_content = file_bytes.decode("utf-8") | |
| except UnicodeDecodeError: | |
| try: | |
| text_content = file_bytes.decode("latin-1") | |
| except Exception as e: | |
| logger.error(f"Failed to decode text file: {e}") | |
| raise HTTPException( | |
| status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, | |
| detail=f"Failed to decode text file as UTF-8 or Latin-1: {str(e)}" | |
| ) | |
| else: | |
| raise HTTPException( | |
| status_code=status.HTTP_400_BAD_REQUEST, | |
| detail="Unsupported file format. Only PDF (.pdf) and raw text (.txt) files are supported." | |
| ) | |
| if not text_content.strip(): | |
| raise HTTPException( | |
| status_code=status.HTTP_400_BAD_REQUEST, | |
| detail="The uploaded file contains no text content to index." | |
| ) | |
| text_splitter = RecursiveCharacterTextSplitter( | |
| chunk_size=chunk_size, | |
| chunk_overlap=chunk_overlap, | |
| length_function=len | |
| ) | |
| try: | |
| chunks = text_splitter.split_text(text_content) | |
| if not chunks: | |
| return IngestionResponse( | |
| status="success", | |
| message="No chunks were created from the uploaded file.", | |
| documents_processed=1, | |
| chunks_created=0 | |
| ) | |
| all_metadatas = [] | |
| for chunk in chunks: | |
| meta = parsed_metadata.copy() | |
| meta["source"] = filename | |
| all_metadatas.append(meta) | |
| logger.info(f"Generating embeddings for {len(chunks)} chunks from uploaded file...") | |
| embeddings = embedding_model.encode(chunks, show_progress_bar=False).tolist() | |
| logger.info("Upserting vectors into Qdrant...") | |
| chunks_inserted = vector_store.add_documents( | |
| texts=chunks, | |
| embeddings=embeddings, | |
| metadatas=all_metadatas | |
| ) | |
| # Dual indexing to Neo4j | |
| if graph_store.is_connected: | |
| logger.info("Extracting and indexing graph relationships from uploaded file into Neo4j...") | |
| for idx, chunk in enumerate(chunks): | |
| try: | |
| chunk_uuid = str(uuid.uuid4()) | |
| meta = all_metadatas[idx] | |
| source = meta.get("source", filename) | |
| graph_data = extract_graph_elements(chunk) | |
| entities_list = [ent.model_dump() for ent in graph_data.entities] | |
| relationships_list = [rel.model_dump() for rel in graph_data.relationships] | |
| graph_store.add_graph_data( | |
| chunk_id=chunk_uuid, | |
| chunk_text=chunk, | |
| source=source, | |
| entities=entities_list, | |
| relationships=relationships_list | |
| ) | |
| except Exception as ex: | |
| logger.error(f"Failed to index uploaded chunk {idx} in Neo4j: {ex}") | |
| return IngestionResponse( | |
| status="success", | |
| message=f"Successfully indexed document '{filename}' into {chunks_inserted} chunks.", | |
| documents_processed=1, | |
| chunks_created=chunks_inserted | |
| ) | |
| except Exception as e: | |
| logger.error(f"Error during document file ingestion: {e}") | |
| raise HTTPException( | |
| status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, | |
| detail=f"An error occurred while indexing the uploaded file: {str(e)}" | |
| ) | |
| def retrieve_context(payload: RetrievalRequest): | |
| """ | |
| Retrieves the top_k most similar document chunks for a query. | |
| Returns both structured results and a flat array of context strings. | |
| """ | |
| try: | |
| logger.info(f"Generating embedding for query: '{payload.query}'") | |
| # Embed query text | |
| query_embedding = embedding_model.encode(payload.query, show_progress_bar=False).tolist() | |
| logger.info(f"Searching for top {payload.top_k} matches...") | |
| # Search vector database | |
| search_results = vector_store.search(query_embedding, top_k=payload.top_k) | |
| results = [] | |
| context = [] | |
| for res in search_results: | |
| results.append(RetrievalResult( | |
| text=res["text"], | |
| score=res["score"], | |
| metadata=res["metadata"] | |
| )) | |
| context.append(res["text"]) | |
| return RetrievalResponse( | |
| query=payload.query, | |
| results=results, | |
| context=context | |
| ) | |
| except Exception as e: | |
| logger.error(f"Error during retrieval: {e}") | |
| raise HTTPException( | |
| status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, | |
| detail=f"An error occurred during retrieval: {str(e)}" | |
| ) | |
| def agent_chat(payload: AgentRequest): | |
| """ | |
| Agentic RAG chat endpoint. The system runs a tool-calling loop using the Gemini API. | |
| It queries the local knowledge base if it needs facts, reformulates queries if needed, | |
| and answers the user prompt. | |
| """ | |
| # Check if GEMINI_API_KEY is configured | |
| if not os.getenv("GEMINI_API_KEY"): | |
| raise HTTPException( | |
| status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, | |
| detail="GEMINI_API_KEY environment variable is not set. Please configure it to use the agentic RAG service." | |
| ) | |
| try: | |
| # Convert Pydantic request chat_history to simple dict list for the agent | |
| chat_history_dicts = None | |
| if payload.chat_history: | |
| chat_history_dicts = [{"role": turn.role, "content": turn.content} for turn in payload.chat_history] | |
| result = run_agent_rag( | |
| user_message=payload.prompt, | |
| embedding_model=embedding_model, | |
| vector_store=vector_store, | |
| graph_store=graph_store, | |
| chat_history=chat_history_dicts | |
| ) | |
| return AgentResponse( | |
| answer=result["answer"], | |
| tool_calls=result["tool_calls"], | |
| sources=result["sources"] | |
| ) | |
| except Exception as e: | |
| logger.error(f"Error during agentic chat: {e}") | |
| raise HTTPException( | |
| status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, | |
| detail=f"An error occurred during the agentic RAG execution: {str(e)}" | |
| ) | |
| def get_documents_status(): | |
| """ | |
| Retrieves statistics and connection information about the vector database. | |
| """ | |
| return vector_store.get_status() | |
| def clear_documents(): | |
| """ | |
| Resets/clears the vector database and the graph database collections. | |
| """ | |
| vector_success = vector_store.clear() | |
| # Clear Neo4j | |
| graph_success = True | |
| if graph_store.is_connected: | |
| graph_success = graph_store.clear() | |
| if not vector_success or not graph_success: | |
| raise HTTPException( | |
| status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, | |
| detail="Failed to reset the vector database or graph database collections." | |
| ) | |
| return { | |
| "status": "success", | |
| "message": "Vector and Graph databases have been reset successfully." | |
| } | |
| def extract_query_entities(query_text: str) -> List[str]: | |
| if not os.getenv("GEMINI_API_KEY"): | |
| return [] | |
| from google import genai | |
| from google.genai import types | |
| client = genai.Client() | |
| try: | |
| response = client.models.generate_content( | |
| model="gemini-2.5-flash", | |
| contents=f"Extract the main named entities, concepts, or terms from this search query:\n\n{query_text}", | |
| config=types.GenerateContentConfig( | |
| response_mime_type="application/json", | |
| response_schema=EntityListModel, | |
| system_instruction="Extract only the key noun entities/concepts that would be useful for searching a knowledge graph." | |
| ) | |
| ) | |
| obj = EntityListModel.model_validate_json(response.text) | |
| return obj.entities | |
| except Exception as e: | |
| logger.error(f"Failed to extract query entities: {e}") | |
| return [] | |
| def retrieve_graph_context(payload: GraphRetrieveRequest): | |
| """ | |
| Extracts key entities from the search query and retrieves their | |
| 1-hop and 2-hop relationships from the Neo4j Graph Database. | |
| """ | |
| if not graph_store.is_connected: | |
| raise HTTPException( | |
| status_code=status.HTTP_503_SERVICE_UNAVAILABLE, | |
| detail="Neo4j Graph Database is not connected." | |
| ) | |
| try: | |
| entities = extract_query_entities(payload.query) | |
| entities = entities[:payload.top_k_entities] | |
| relationships = graph_store.query_subgraph(entities) | |
| return GraphRetrieveResponse( | |
| query=payload.query, | |
| extracted_entities=entities, | |
| relationships=relationships | |
| ) | |
| except Exception as e: | |
| logger.error(f"Error during graph retrieval: {e}") | |
| raise HTTPException( | |
| status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, | |
| detail=f"An error occurred during graph retrieval: {str(e)}" | |
| ) | |
| def query_graph_rag(payload: GraphQueryRequest): | |
| """ | |
| Performs GraphRAG querying: retrieves relevant entity relationships from | |
| Neo4j and prompts Gemini to answer the query grounded in that context. | |
| """ | |
| if not graph_store.is_connected: | |
| raise HTTPException( | |
| status_code=status.HTTP_503_SERVICE_UNAVAILABLE, | |
| detail="Neo4j Graph Database is not connected." | |
| ) | |
| if not os.getenv("GEMINI_API_KEY"): | |
| raise HTTPException( | |
| status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, | |
| detail="GEMINI_API_KEY environment variable is not configured." | |
| ) | |
| try: | |
| entities = extract_query_entities(payload.query) | |
| relationships = graph_store.query_subgraph(entities) | |
| from google import genai | |
| from google.genai import types | |
| client = genai.Client() | |
| prompt = f""" | |
| Answer the user query based ONLY on the provided knowledge graph relationships. | |
| If the information is not present, state clearly that it was not found in the graph. | |
| Knowledge Graph Relationships: | |
| {relationships} | |
| User Query: | |
| {payload.query} | |
| """ | |
| response = client.models.generate_content( | |
| model="gemini-2.5-flash", | |
| contents=prompt, | |
| config=types.GenerateContentConfig( | |
| system_instruction="You are a precise GraphRAG assistant. Answer questions using only the relationships provided." | |
| ) | |
| ) | |
| return GraphQueryResponse( | |
| query=payload.query, | |
| answer=response.text, | |
| context=relationships | |
| ) | |
| except Exception as e: | |
| logger.error(f"Error during graph query: {e}") | |
| raise HTTPException( | |
| status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, | |
| detail=f"An error occurred during graph query: {str(e)}" | |
| ) | |