rag-backend-api / main.py
its-seraj's picture
Update main.py
cc5ab64 verified
Raw History Blame Contribute Delete
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
@app.get("/", status_code=status.HTTP_200_OK)
def root():
"""
Root endpoint serving basic API metadata.
"""
return {
"app": "RAG Backend Service",
"version": "1.0.0",
"documentation": "/docs",
"status": "online"
}
@app.get("/health", status_code=status.HTTP_200_OK)
def health():
"""
Health check endpoint returning system status.
"""
return {
"status": "healthy",
"vector_store": vector_store.get_status(),
"graph_store": graph_store.get_status()
}
@app.post("/documents", response_model=IngestionResponse, status_code=status.HTTP_201_CREATED)
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)}"
)
@app.post("/documents/upload", response_model=IngestionResponse, status_code=status.HTTP_201_CREATED)
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)}"
)
@app.post("/retrieve", response_model=RetrievalResponse, status_code=status.HTTP_200_OK)
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)}"
)
@app.post("/agent/chat", response_model=AgentResponse, status_code=status.HTTP_200_OK)
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)}"
)
@app.get("/documents", status_code=status.HTTP_200_OK)
def get_documents_status():
"""
Retrieves statistics and connection information about the vector database.
"""
return vector_store.get_status()
@app.delete("/documents", status_code=status.HTTP_200_OK)
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 []
@app.post("/retrieve/graph", response_model=GraphRetrieveResponse, status_code=status.HTTP_200_OK)
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)}"
)
@app.post("/query/graph", response_model=GraphQueryResponse, status_code=status.HTTP_200_OK)
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)}"
)