Drop-in RAG Backend

A modular, plug-and-play Retrieval-Augmented Generation (RAG) backend API and command-line (CLI) utility. Built using clean architectural principles, it provides a ready-to-run environment for local document ingestion, semantic search indexing, and LLM completions with source citation tracking.

🚀 Key Features

• Local-First AI Orchestration: Interfaces directly with a local Ollama daemon for text embeddings (nomic-embed-text) and text synthesis completions (llama3), giving you complete privacy with zero cloud bills.
• Embedded Vector Storage: Integrates Chroma DB as a zero-config SQLite-backed persistent client vector store, utilizing Cosine Similarity spaces.
• Custom Recursive split Chunker: Implements a sliding-window recursive splitter that cascades through logical boundaries (\n\n, \n, , and "") to keep paragraphs and sentences intact, mapping characters to coordinate slices for 100% precise citations.
• FastAPI presentation routes: Secures Multi-part Document Upload (/api/v1/upload for PDF, MD, TXT parsing) and Synthesis Querying (/api/v1/query) behind configurable header authentication tokens.
• Developer Experience CLI: Provides shell command maps (rag init, rag start, rag index, and rag query) built via Typer for developer tools.
• 100% Mocked Test Coverage: Incorporates a unit and API integration testing suite using mock decorators to verify controller routes without spinning up server instances or calling live network nodes.

---

📂 Project Architecture Layout

The codebase follows the Dependency Inversion Principle, decoupling core business definitions (RAG logic interface contracts) from third-party infrastructure client integrations (Chroma, Ollama, PyPDF):

├── cli/                        # CLI command handler (Typer)
│   ├── __init__.py
│   └── main.py                 # Commands: init, start, index, query
├── src/                        # Core application modules
│   ├── __init__.py
│   ├── config.py               # Pydantic Settings & environmental loading
│   ├── main.py                 # FastAPI Application router & dependency bindings
│   ├── core/                   # Abstract Interfaces (Domain Layer)
│   │   ├── Chunker.py          # Chunker base interface contract
│   │   ├── Embeddings.py       # Embeddings base interface contract
│   │   ├── Generator.py        # Text generator base interface contract
│   │   └── VectorStore.py      # Vector store base interface contract
│   └── infra/                  # Implementation Adapters (Infrastructure Layer)
│       ├── chunkers/           # Recursive splits splitter
│       ├── embeddings/         # Ollama HTTP embeddings adapter
│       ├── generators/         # Ollama HTTP chat generator adapter
│       └── vector_stores/      # Chroma persistent client adapter
├── tests/                      # Pytest automation suite
│   ├── __init__.py
│   ├── test_adapters.py        # Intercepted client network call mock checks
│   ├── test_api.py             # TestClient FastAPI endpoints mock integration checks
│   ├── test_chunker.py         # Splitting logic and coordinates slices checks
│   └── test_config.py          # Configuration and environments overrides checks
├── pyproject.toml              # Packaging and dependency rules
├── rag-config.yaml.example     # YAML Configuration template
└── progress_tracker.md         # SDLC sprint status tracker

---

🛠️ Installation & Setup

1. Prerequisite Environments

Make sure you have Ollama installed and running locally on your host container. Pull the default embedding and generator models:

ollama pull nomic-embed-text
ollama pull llama3

2. Configure Virtual Environment & Install Package

Clone the repository, initialize a Python virtual environment, and install the package in editable development mode:

# Initialize virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install the core application and CLI entrypoint
pip install -e .

# Install developer dependencies (for running pytest)
pip install -e ".[dev]"

---

💻 CLI Commands Usage

The package registers the rag command entrypoint directly in your virtual environment's executables bin:

# Show command usage instructions
rag --help

1. Initialize Configuration

Initialize a local configuration YAML template file in your directory root:

rag init --output rag-config.yaml

2. Run the API Server

Start the FastAPI server (loaded with host/port variables from your configuration file):

rag start --config rag-config.yaml

Add the --reload flag for auto-restart development cycles.

3. Index Documents

Upload and split TXT, MD, or PDF documents into the local Chroma vector store:

rag index doc1.txt manual.pdf --config rag-config.yaml

4. Semantic Grounded Queries

Submit natural language questions to retrieve RAG-grounded answers along with source document text snippets and cosine similarity coordinates:

rag query "Who created the Drop-in RAG tool?" --top-k 3 --config rag-config.yaml

---

📡 REST API Documentation

Once the server is running (rag start), you can access the interactive Swagger UI OpenAPI documentation at http://localhost:8000/docs.

1. Health Status (GET /health)

Performs diagnostic system checks on active components and model parameters.

• Response Output:

  {
    "status": "healthy",
    "service": "Drop-in RAG Backend API",
    "version": "0.1.0",
    "environment": {
      "chunk_strategy": "recursive",
      "chunk_size": 500,
      "chunk_overlap": 50,
      "embeddings_provider": "ollama",
      "embeddings_model": "nomic-embed-text",
      "generator_provider": "ollama",
      "generator_model": "llama3",
      "vector_store_provider": "chroma"
    }
  }

2. Ingest Document Files (POST /api/v1/upload)

Accepts multipart file uploads (.txt, .md, .pdf). Secure with the X-API-KEY header if configured.

• Curl Example:

  curl -X POST "http://localhost:8000/api/v1/upload" \
    -H "accept: application/json" \
    -H "Content-Type: multipart/form-data" \
    -F "files=@document.pdf"

3. Query Grounded Completion (POST /api/v1/query)

Retrieves matching similarity chunks from Chroma, structures prompt contexts, runs inferences via Ollama, and matches outputs to citation coordinates.

• Curl Example:

  curl -X POST "http://localhost:8000/api/v1/query" \
    -H "Content-Type: application/json" \
    -d '{"question": "Who created the Drop-in RAG?", "top_k": 2}'

• Response Output:

  {
    "answer": "According to specs.txt, the Drop-in RAG Backend was built by developers...",
    "sources": [
      {
        "text": "The Drop-in RAG Backend is a plug-and-play API system...",
        "score": 0.6837,
        "metadata": {
          "filename": "specs.txt",
          "document_id": "doc_abc123",
          "chunk_index": 0,
          "char_start": 0,
          "char_end": 250
        }
      }
    ]
  }

---

🧪 Running Test Suites

Run the complete test suite utilizing mock clients to intercept HTTP networking:

pytest tests/

Use pytest -v tests/ for detailed test execution lists.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.