--- title: rag-pipeline sdk: docker emoji: 🏃 colorFrom: purple colorTo: indigo --- # RAG Backend Pipeline API This repository contains a high-performance, lightweight Retrieval-Augmented Generation (RAG) backend service built using **FastAPI**, **SentenceTransformers** (`all-MiniLM-L6-v2`), and **Qdrant Vector Database**. It is fully optimized to be deployed to **Hugging Face Spaces** via the Docker SDK. It is designed to work seamlessly with a separate frontend client (such as a ReactJS application) by implementing CORS. --- ## Architecture Overview 1. **Document Ingestion**: Accepts raw text documents, splits them into semantic chunks using `langchain-text-splitters`, computes vector embeddings locally using SentenceTransformers, and stores them in Qdrant. 2. **Context Retrieval**: Accepts user queries, computes query embeddings, conducts a cosine-similarity search against Qdrant, and returns the top matching text chunks as a flat array of strings to be injected as LLM context. 3. **Storage Flexibility**: Connects to **Qdrant Cloud** (for persistent production databases) and automatically falls back to an **In-Memory Qdrant instance** for rapid local testing without credentials. --- ## API Endpoints Reference ### 1. Ingest Documents * **Route**: `POST /documents` * **Content-Type**: `application/json` * **Description**: Splits, embeds, and stores documents. * **Request Body**: ```json { "documents": [ { "text": "Retrieval-Augmented Generation (RAG) is an AI framework for retrieving facts from an external knowledge base.", "metadata": { "source": "wikipedia", "topic": "RAG" } } ], "chunk_size": 500, "chunk_overlap": 50 } ``` * **Response**: ```json { "status": "success", "message": "Successfully indexed 1 documents into 1 chunks.", "documents_processed": 1, "chunks_created": 1 } ``` * **Response**: ```json { "status": "success", "message": "Successfully indexed 1 documents into 1 chunks.", "documents_processed": 1, "chunks_created": 1 } ``` ### 1b. Upload Document File * **Route**: `POST /documents/upload` * **Content-Type**: `multipart/form-data` * **Description**: Accepts an uploaded file (`.pdf` or `.txt`), automatically extracts text, chunks, embeds, and stores it in Qdrant. * **Form Fields**: - `file`: The document file to upload (PDF or TXT). - `chunk_size` (Optional): Maximum character length of each chunk (Default: `500`, Range: `50`-`5000`). - `chunk_overlap` (Optional): Character overlap between adjacent chunks (Default: `50`, Range: `0`-`1000`). - `metadata` (Optional): A JSON-formatted string representing custom key-value metadata to attach to the ingested chunks (e.g. `{"category": "physics"}`). * **Example curl command**: ```bash curl -X POST "http://localhost:7860/documents/upload" \ -F "file=@/path/to/document.pdf" \ -F "chunk_size=500" \ -F "chunk_overlap=50" \ -F "metadata={\"category\": \"research\", \"author\": \"John Doe\"}" ``` * **Response**: ```json { "status": "success", "message": "Successfully indexed document 'document.pdf' into 4 chunks.", "documents_processed": 1, "chunks_created": 4 } ``` ### 2. Retrieve Context * **Route**: `POST /retrieve` * **Content-Type**: `application/json` * **Description**: Performs a vector search and returns matching contexts. * **Request Body**: ```json { "query": "What is RAG?", "top_k": 3 } ``` * **Response**: ```json { "query": "What is RAG?", "results": [ { "text": "Retrieval-Augmented Generation (RAG) is an AI framework for retrieving facts from an external knowledge base.", "score": 0.892, "metadata": { "source": "wikipedia", "topic": "RAG", "doc_index": 0 } } ], "context": [ "Retrieval-Augmented Generation (RAG) is an AI framework for retrieving facts from an external knowledge base." ] } ``` ### 2b. Agentic Chat * **Route**: `POST /agent/chat` * **Content-Type**: `application/json` * **Description**: Runs a tool-calling reasoning loop using the Gemini API. If the agent needs details from the vector database to answer the user prompt, it dynamically calls the `query_knowledge_base` search tool. * **Request Body**: ```json { "prompt": "What is antigravity based on our database?", "chat_history": [ { "role": "user", "content": "Hi there" }, { "role": "model", "content": "Hello! How can I help you today?" } ] } ``` * **Response**: ```json { "answer": "Based on the database, antigravity is a concept of creating a place or object that is free from the force of gravity...", "tool_calls": [ { "query": "antigravity", "top_k": 3, "results_count": 1, "results": [ { "text": "Antigravity is a concept of creating a place or object that is free from the force of gravity...", "score": 0.892, "metadata": { "source": "physics_101", "category": "gravity" } } ] } ], "sources": [ { "text": "Antigravity is a concept of creating a place or object that is free from the force of gravity...", "score": 0.892, "metadata": { "source": "physics_101", "category": "gravity" } } ] } ``` ### 3. Database Status * **Route**: `GET /documents` * **Description**: Gets collection metrics and database connection status. * **Response**: ```json { "connection_type": "Cloud", "collection_name": "rag_documents", "vector_size": 384, "vectors_count": 1, "status": "green" } ``` ### 4. Reset Vector Store * **Route**: `DELETE /documents` * **Description**: Clears all records from the vector store. * **Response**: ```json { "status": "success", "message": "Vector database has been reset successfully." } ``` ### 5. Health Check * **Route**: `GET /health` * **Description**: Returns overall API and vector store health status. --- ## Local Setup & Development ### 1. Install Dependencies Make sure you have Python 3.9+ installed. Run: ```bash pip install -r requirements.txt ``` ### 2. Run the Server To run locally in development mode: ```bash uvicorn main:app --reload --port 7860 ``` Open [http://localhost:7860/docs](http://localhost:7860/docs) in your browser to test endpoints interactively using the Swagger UI. --- ## Deployment to Hugging Face Spaces This backend is ready to run as a Docker Space on Hugging Face. ### Step 1: Create a Hugging Face Space 1. Visit [Hugging Face Spaces](https://huggingface.co/new-space). 2. Enter your Space name (e.g., `rag-backend-api`). 3. Under **SDK**, select **Docker**. 4. Choose the **Blank** template. 5. Set Space visibility (Public or Private) and click **Create Space**. ### Step 2: Configure Environment Variables / Secrets Go to your Space's **Settings** tab, scroll to the **Variables and Secrets** section, and add your credentials as secrets: * `GEMINI_API_KEY` (Required for the Agentic RAG chat feature) * `QDRANT_URL` (e.g., `https://xxxxxx-xxxx.eu-west3-1.gcp.qdrant.tech:443` or just `https://xxxxxx-xxxx.eu-west3-1.gcp.qdrant.tech`) * `QDRANT_API_KEY` (Your Qdrant API Key) * `QDRANT_COLLECTION` (Optional: The collection name to use, defaults to `rag_documents`) ### Step 3: Push Your Code Clone the HF Space repository and push this project's code: ```bash git init git remote add origin https://huggingface.co/spaces// git add . git commit -m "Deploy RAG Backend API" git push -u origin main ``` Hugging Face will automatically build the Docker image (pre-caching the model weights) and launch the FastAPI server on port 7860. The API docs will be available at `https://-.hf.space/docs`.