raggit

A plug-and-play production-grade RAG system that connects to local and remote object storage, automatically indexes documents, and answers questions using hybrid retrieval with reranking and LLM augmentation.

What raggit does

raggit is built for teams that need reliable retrieval-augmented generation without managing a patchwork of vector databases, parsers, and rerankers. It handles the full document lifecycle: watching storage, parsing common formats, chunking intelligently, embedding, searching, and generating cited answers.

Documents live in storage you already control. Point raggit at a local directory, S3 bucket, GCS bucket, or Azure container and it keeps an index in sync automatically. Query it through the CLI and receive an answer grounded in your documents, with citations.

Features

Ingestion

• Automatic watching via raggit serve. Local filesystem changes are detected instantly through OS-native events (fsevents/inotify). Cloud storage is polled and diffed.
• Format-aware parsing for PDF, DOCX, HTML, Markdown, and plain text. PDF page numbers are preserved through chunking.
• Smart chunking respects Markdown headers, code boundaries, and PDF pages, with recursive character splitting as a fallback.
• Deduplication removes exact and near-duplicate chunks using content hashes and Jaccard word-set similarity.
• Cleaning & normalization fixes Unicode, hyphenation, and whitespace before embedding.
• Optional safety steps: PII redaction and prompt-injection hardening.
• Model-scoped collections in Qdrant so changing embedding models never corrupts an existing index.

Retrieval

• Hybrid search combines BM25 keyword search with dense semantic search.
• Weighted Reciprocal Rank Fusion merges heterogeneous rank lists.
• Query rewriting with multi-query expansion and HyDE.
• Optional cross-encoder reranking for better top-N ordering.
• Dynamic top-k scales with corpus size while staying bounded.
• Parent-window expansion provides surrounding context for each hit.
• Structured citations include source URI, filename, page, section, offsets, score, and excerpt.

Operations

• Multi-tenancy & filtering by tenant, tags, source prefix, filename prefix, document IDs, and date range.
• Structured audit logs persisted to PostgreSQL for every ingestion, query, and answer.
• Document lifecycle status tracks pending, indexing, parsed, chunked, embedded, completed, failed, and deleted states.
• Async-first architecture using asyncpg, async Qdrant client, and async cloud SDKs.
• FastAPI HTTP API with interactive /docs Swagger UI for every operation: query, manage documents, inspect chunks and logs, update configuration, trigger ingestion, and control the watcher.
• Three-tier evaluation framework – isolated component suites (parser, chunker, cleaner, PII, injection, sanitizer, RRF, reranker, safety, embedder, storage), pipeline suites (ingestion & retrieval chains), and system end-to-end (22+ system metrics including citations, hallucination, tenant/tag/prefix filters, p50/p95 latency, audit). 69+ metrics total, `kind: all` runs every tier.
• Optional MCP server exposing the same core operations to MCP clients over stdio or SSE. Install with raggit[mcp].

Quick Start

You need Docker Desktop (or Docker Engine + Compose). For local development you also need uv.

Option 1: Docker (recommended)

Build and run the entire stack with one command:

docker compose up -d

This starts:

• raggit-postgres on port 5433
• raggit-qdrant on ports 6333 and 6334
• raggit-app running raggit serve with the FastAPI server on port 8000 and the watcher enabled

Place documents in ./data/documents for local storage ingestion. The container entrypoint applies Alembic migrations before starting the service.

If you rebuild the image after Dockerfile changes, recreate the app container:

docker compose down raggit
docker compose build --no-cache raggit
docker compose up -d raggit

Useful commands

# View logs
docker compose logs -f raggit

# Run one-time ingestion inside the container
docker compose exec raggit raggit ingest

# Run a query
docker compose exec raggit raggit query "What is raggit?"

# Stop everything
docker compose down

Option 2: Local development

1. Start PostgreSQL and Qdrant

   docker compose up -d postgres qdrant

   PostgreSQL is mapped to host port 5433 to avoid conflicts with a local postgres on 5432.

2. Install dependencies

   uv sync

3. Run database migrations

   uv run alembic upgrade head

4. Configure raggit

   uv run raggit setup \
     --database-url postgresql+asyncpg://raggit:raggit@localhost:5433/raggit \
     --qdrant-url http://localhost:6333 \
     --storage-source-type local \
     --storage-uri ./data/documents \
     --llm-provider openai \
     --llm-model gpt-4o-mini \
     --llm-api-key $OPENAI_API_KEY

   raggit setup writes ~/.config/raggit/raggit.env with 0600 permissions and bootstraps the system by checking Postgres, running migrations, checking Qdrant, and creating the local document directory.

5. Add documents

   mkdir -p data/documents
   cp my-docs/*.pdf data/documents/

6. Run the service for continuous indexing

   uv run raggit serve

   raggit will start the FastAPI server on http://localhost:8000 and perform an initial sync, then watch for new, modified, and deleted files. Local changes are reflected almost instantly. Open /docs for interactive Swagger UI.

7. Ask questions

   uv run raggit query "What is raggit?"

   Or use the HTTP API:

   curl -X POST http://localhost:8000/query \
     -H "Content-Type: application/json" \
     -d '{"query": "What is raggit?"}'

See the HTTP API and storage backends sections for more. Live +/- file event indicators are now shown directly by raggit serve.

Architecture

raggit is organized into clear layers: storage, ingestion, data, retrieval, LLM, audit, and interface. The HTTP API is built on FastAPI and exposes every major operation. All I/O is async, and every significant input and output is logged to PostgreSQL.

flowchart TB
    subgraph Storage
        LS[Local Filesystem]
        RS[S3 / GCS / Azure Blob]
    end

    subgraph Ingestion
        W[Watcher Service]
        I[Indexing Service]
        P[Parser Registry]
        FA[Format-Aware Chunker]
        DED[Dedup]
        CL[Chunk Cleaner]
        PI[PII Redaction]
        IH[Injection Hardening]
        E[Embedder]
    end

    subgraph PostgreSQL
        D[documents]
        CH[chunks]
        EC[embedding_collections]
        LG[logs]
    end

    VS[Qdrant Vector Store]

    LS --> W
    RS --> W
    W --> I
    I --> P
    P --> FA
    FA --> DED
    DED --> CL
    CL --> PI
    PI --> IH
    IH --> E
    E --> VS
    I --> D
    IH --> CH
    E --> CH
    I --> EC
    IH --> LG
    E --> LG

    subgraph Retrieval
        Q[User Query]
        QR[Query Rewriter]
        MQ[Multi-Query]
        HY[HyDE]
        BM25[Postgres FTS / BM25]
        SEM[Qdrant Semantic Search]
        RRF[Weighted RRF]
        RR[Cross-Encoder Reranker]
        TH[Score Threshold]
        PW[Parent-Window Expansion]
        AUG[Augmenter]
        LLM[LLM Provider]
        GRD[Groundedness Check]
        OUT[Answer + Citations]
    end

    Q --> QR
    QR --> BM25
    QR --> SEM
    QR --> MQ
    QR --> HY
    BM25 --> RRF
    SEM --> RRF
    RRF --> RR
    RR --> TH
    TH --> PW
    PW --> AUG
    AUG --> LLM
    LLM --> GRD
    GRD --> OUT
    RRF --> LG
    AUG --> LG
    LLM --> LG

    subgraph Interface
        CLI[Typer CLI]
        API[FastAPI HTTP API]
    end

    API --> Q
    CLI --> Q
    API --> W
    CLI --> W

Component responsibilities

• Storage layer abstracts local directories and cloud object stores behind a common interface. Local backends emit OS-native events; cloud backends poll and diff.
• WatcherService starts storage watching, runs an initial sync, and dispatches file events to the indexer with lightweight debouncing.
• Indexer orchestrates hash checks, parsing, chunking, cleaning, embedding, and persistence.
• Parser registry selects the right parser by file extension and extracts text plus structural hints like page numbers.
• Chunker produces format-aware pieces and links sequential siblings for relevance-chain retrieval.
• Embedder generates dense vectors using sentence-transformers or an OpenAI-compatible API.
• Vector store manages Qdrant collections scoped to the embedding model and version.
• Retrieval engine sanitizes queries, optionally rewrites them, runs BM25 and semantic search in parallel, fuses results, reranks, thresholds, and expands parent windows.
• LLM layer augments prompts with isolated untrusted context and generates cited answers.
• Audit logger persists structured events to PostgreSQL.
• HTTP API exposes every operation via FastAPI with interactive OpenAPI documentation at /docs.

Design goals

• Accuracy through hybrid retrieval, cross-encoder reranking, query rewriting, and parent-document expansion.
• Safety by isolating untrusted document text from system instructions and optionally redacting PII.
• Observability with lifecycle statuses, model-scoped collections, and structured audit logs.
• Multi-tenancy via tenant_id and tags applied consistently across BM25 and vector search.
• Evolvability via model-scoped Qdrant collections so changing embedding models does not corrupt existing indexes.

Data Model

PostgreSQL is the source of truth for metadata, chunks, audit logs, and collection tracking. Qdrant holds the dense vectors with filterable payloads.

documents

chunks

embedding_collections

Tracks which Qdrant collection is active for the current embedding model. Changing models creates a new collection and activates it automatically.

logs

Structured audit log with level, component, message, and JSON extra field. Captures ingestion inputs/outputs, queries, retrieval results, and generated answers.

Ingestion Pipeline

When a file is added or changed, the watcher triggers the indexer, which runs the document through parsing, format-aware chunking, cleaning, optional safety steps, embedding, and persistence.

Retrieval Pipeline

Queries are sanitized, optionally rewritten, run through BM25 and semantic search in parallel, fused, reranked, expanded, and then passed to the LLM with citations.

Watcher & Continuous Indexing

raggit keeps your index in sync with storage automatically. The recommended way to run it is raggit serve, a lightweight long-running process that starts a WatcherService.

raggit serve

raggit serve is the default long-running mode. It:

• Loads configuration from environment variables and ~/.config/raggit/raggit.env.
• Runs an initial full sync of all existing files.
• Starts the storage-specific watcher.
• Dispatches add/modify/delete events to the indexer with per-path debouncing.
• Handles SIGINT and SIGTERM gracefully.

uv run raggit serve
uv run raggit serve ./data/documents
uv run raggit serve --log-level DEBUG --tenant acme --tag finance

Event-driven local watching

For local directories, raggit uses watchdog to receive OS-native filesystem events (FSEvents on macOS, inotify on Linux). This means:

• New or modified files are detected almost instantly.
• There is no periodic polling loop waking the CPU.
• Idle resource usage is negligible.

Git-like stat snapshot

On startup and during sync, raggit stores a cheap stat snapshot (file_size and file_modified_at) for each document. When a file is seen again, the indexer first compares this metadata. Only when size or modification time differs does it read the file and compute a content hash. This makes initial sync fast when most files have not changed.

Cloud storage watching

S3, GCS, and Azure backends do not have a universal push-notification mechanism, so they use lightweight polling and snapshot diffing. The interval is configurable with STORAGE_POLL_INTERVAL_SECONDS (default 30 seconds). You can make cloud watching near-instant by routing provider events (S3 Event Notifications, GCS Pub/Sub, Azure Event Grid) into a queue that a future extension can consume.

Automatic & independent operation

The watcher is now a single canonical implementation inside WatcherService. It starts automatically with raggit serve and via the FastAPI lifespan when running uvicorn raggit.api.server:app – no manual POST /watcher/start needed. The legacy raggit watch command has been removed; raggit serve now prints live +/- indicators itself. Disable the watcher with raggit serve --no-watcher or RAGGIT_NO_AUTO_WATCHER=1.

HTTP API

raggit exposes a FastAPI HTTP server on port 8000 (configurable via --port). Every major operation is available over HTTP, and interactive documentation is served at /docs (Swagger UI) and /redoc (ReDoc).

Running the API

uv run raggit serve
uv run raggit serve --host 0.0.0.0 --port 8000
uv run raggit serve --no-watcher  # API only, no file watcher

Endpoints

Examples

Query

curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "What is raggit?"}'

Filtered query

curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is raggit?",
    "tenant_id": "acme",
    "tags": ["finance"],
    "top_k": 10,
    "generate_answer": false
  }'

Update configuration

curl -X POST http://localhost:8000/config \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "retrieval": {
        "min_top_k": 10,
        "max_top_k": 50,
        "query_rewrite": "multi_query"
      },
      "safety": {
        "groundedness_check": true
      }
    }
  }'

Trigger ingestion

curl -X POST http://localhost:8000/ingest \
  -H "Content-Type: application/json" \
  -d '{"path": "./data/documents", "tenant_id": "acme"}'

List logs

curl "http://localhost:8000/logs?level=INFO&limit=50"

Delete a document

curl -X DELETE http://localhost:8000/documents/{document_id}

Watcher control

curl -X POST http://localhost:8000/watcher/start
# ... later ...
curl -X POST http://localhost:8000/watcher/stop

Evaluation

raggit ships a three-tier evaluation framework so every feature is measurable in isolation, as a pipeline, and end-to-end. Run it from the CLI or HTTP API and export reports as JSON or Markdown. All 69+ metrics are available via --list-metrics.

Dataset format by tier

Datasets are JSON/YAML with a kind discriminator. Old datasets without kind default to system for backwards compatibility.

Component (kind: component)

name: chunker-eval
kind: component
component: chunker   # parser|chunker|cleaner|pii|injection|sanitizer|embedder|rrf|reranker|safety|storage|watcher|retriever
metrics: [chunker_section_preservation, chunker_dedup_effectiveness]
k_values: [5]
component_tests:
  - id: chunker-md-1
    component: chunker
    input: {text: "# Title\nContent", path: "doc.md"}
    expected: {expected_titles: ["Title"]}
    tags: [markdown]

Pipeline (kind: pipeline)

name: ingestion-pipeline
kind: pipeline
pipeline: ingestion   # ingestion|retrieval|e2e
metrics: [pipeline_ingestion_success_rate, pipeline_retrieval_success_rate]
pipeline_tests:
  - id: ingest-1
    pipeline: ingestion
    documents: [{path: "note.md", text: "# Hello\nWorld"}]
  - id: retrieve-1
    pipeline: retrieval
    query: "What is hello?"
    expected_chunk_ids: ["11111111-1111-1111-1111-111111111111"]

System (kind: system)

name: my-eval
kind: system
metrics:
  - retrieval_recall@k
  - retrieval_mrr
  - answer_contains
  - answer_semantic_similarity
  - system_citation_precision
  - filter_tenant_accuracy
k_values: [5, 10]
tests:
  - id: q1
    query: "What is raggit?"
    filters: {tenant_id: "acme", tags: ["finance"]}
    expected_chunk_ids:
      - 11111111-1111-1111-1111-111111111111
    expected_answer: "raggit is a production-grade RAG system"
    tags: [basic]

All tiers (kind: all)

name: raggit-all-tiers
kind: all
metrics: [chunker_section_preservation, pipeline_ingestion_success_rate, retrieval_recall@k, system_citation_precision]
component_tests: [...]  # every component
pipeline_tests: [...]   # ingestion + retrieval + e2e
tests: [...]            # system end-to-end

Metrics – every feature covered

CLI – every tier

# Component – isolated primitive (no DB needed for many)
uv run raggit eval --generate --kind component --component chunker --name chunker-suite
uv run raggit eval chunker-suite.yaml

# All components at once
uv run raggit eval --generate --kind component --component retriever --name retriever-suite

# Pipeline – ingestion & retrieval chains (needs DB/vector store)
uv run raggit eval --generate --kind pipeline --pipeline ingestion --name ingest-pipe
uv run raggit eval --generate --kind pipeline --pipeline retrieval --name retrieve-pipe
uv run raggit eval ingest-pipe.yaml
uv run raggit eval retrieve-pipe.yaml

# System – end-to-end with LLM (default)
uv run raggit eval --generate --name my-eval
uv run raggit eval my-eval.yaml --output report.json
uv run raggit eval my-eval.yaml --output report.md

# Comprehensive: every feature in one file
uv run raggit eval --comprehensive --name full-suite   # kind: system, 12 tests, 22 metrics
uv run raggit eval --generate --kind all --name all-tiers   # component+pipeline+system

# Explore metrics
uv run raggit eval --list-metrics
uv run raggit eval --generate --kind component --component pii --name pii-suite

Golden datasets – built-in & custom

raggit ships golden datasets under eval_datasets/ – curated ground-truth for every tier, committed to git so CI and teammates share the same baseline:

• eval_datasets/golden.yaml / golden-all-tiers.yaml – all tiers, every component + pipeline + system (27+13 tests, 53 metrics)
• eval_datasets/golden-system.yaml – comprehensive system (12 tests, 22 metrics covering retrieval, filters, safety, citations, latency, MCP)
• eval_datasets/golden-component-<name>.yaml – per-primitive (parser 3 tests, chunker 3, cleaner 3, pii 3, injection 3, sanitizer 2, etc.)
• eval_datasets/golden-pipeline-<ingestion|retrieval|e2e>.yaml – ingestion and retrieval chains

Run them directly:

uv run raggit eval eval_datasets/golden.yaml
uv run raggit eval eval_datasets/golden-component-chunker.yaml
uv run raggit eval eval_datasets/golden-pipeline-ingestion.yaml
uv run raggit eval eval_datasets/golden-system.yaml --output report.json

Custom golden dataset: add your own ground-truth and merge or diff:

# Create your own golden dataset (edit it with your queries & expected chunk IDs/answers)
uv run raggit eval --generate --kind system --name my-golden
# → my-golden.yaml  (fill in expected_chunk_ids, expected_answer, filters, tags)

# Run your dataset merged with the built-in golden
uv run raggit eval my-custom.yaml --golden-dataset eval_datasets/golden-system.yaml

# Or use your custom golden as the sole dataset
uv run raggit eval --golden-dataset ./my-golden.yaml

# Use any dataset as golden
uv run raggit eval eval_datasets/golden-component-pii.yaml --golden-dataset ./my-pii-golden.yaml

# Compare current run against a previous JSON report (shows Δ in terminal)
uv run raggit eval eval_datasets/golden-component-cleaner.yaml --output report.json
uv run raggit eval eval_datasets/golden-component-cleaner.yaml --golden-report report.json

The terminal report now renders a detailed per-tier breakdown (header with kind, summary with pass rate, aggregate table with Δ vs golden, per-test table with latency and key metric, component/pipeline details, answer & citation preview, and a final verdict). The same rich report is available via --output report.md and the HTTP API.

HTTP API – tier-aware

# Component
curl -X POST http://localhost:8000/eval/run \
  -H "Content-Type: application/json" \
  -d '{"dataset": {"name": "chunker-suite","kind": "component","component": "chunker","metrics": ["chunker_section_preservation"],"component_tests": [{"id": "c1","component": "chunker","input": {"text": "# T\nhello"},"expected": {"expected_titles": ["T"]}}]}}'

# Pipeline
curl -X POST http://localhost:8000/eval/run \
  -H "Content-Type: application/json" \
  -d '{"dataset": {"name": "pipe","kind": "pipeline","pipeline": "ingestion","pipeline_tests": [{"id": "p1","pipeline": "ingestion","documents": [{"path": "a.md","text": "# Hi"}]}]}}'

# System (default)
curl -X POST http://localhost:8000/eval/run \
  -H "Content-Type: application/json" \
  -d '{
    "dataset": {
      "name": "my-eval",
      "kind": "system",
      "metrics": ["retrieval_recall@k", "retrieval_mrr"],
      "k_values": [5],
      "tests": [{"id": "q1","query": "What is raggit?","expected_chunk_ids": ["11111111-1111-1111-1111-111111111111"]}]
    }
  }'

# All tiers in one call
curl -X POST http://localhost:8000/eval/run -d '{"dataset": {"kind": "all", ...}}'

MCP Server (optional)

raggit can expose its operations through the Model Context Protocol (MCP). This lets MCP clients such as Claude Desktop, Cursor, or any other MCP host query documents, inspect status, run ingestion, and trigger evaluation runs.

Installation

MCP support is an optional extra so raggit still works when mcp is not installed.

uv pip install 'raggit[mcp]'

CLI: stdio transport

Run the MCP server over stdio for local MCP clients:

uv run raggit mcp

HTTP API: SSE transport

When the mcp extra is installed and raggit serve is running, the MCP server is mounted at /mcp using Server-Sent Events:

curl -N http://localhost:8000/mcp

Exposed tools

CLI Reference

The raggit CLI is the primary interface for setup, ingestion, watching, and querying.

setup

Writes ~/.config/raggit/raggit.env and bootstraps the system. Exposes every configuration parameter as a CLI option.

uv run raggit setup --help

serve

uv run raggit serve [PATH] [OPTIONS]

Options: --host, --port, --poll-interval, --no-watcher, --log-level, --tenant, --tag (repeatable). The watcher runs automatically; no separate raggit watch needed. Removed raggit watch now shows a deprecation message directing to raggit serve.

ingest

uv run raggit ingest [PATH] [OPTIONS]

Options: --chunk-size, --chunk-overlap, --preserve-sections/--split-sections, --embedding-provider, --embedding-model, --log-level, --tenant, --tag.

query

uv run raggit query "<question>" [OPTIONS]

Options include --top-k, --min-top-k, --max-top-k, --top-k-ratio, --rrf-k, --source-prefix, --filename-prefix, --tenant, --tag, --document-id, --created-after, --created-before, --min-score, --rewrite, --multi-query-count, --parent-window, --reranker/--no-reranker, --reranker-model, --reranker-top-n, --refuse-on-empty/--no-refuse-on-empty, --refuse-on-low-score/--no-refuse-on-low-score, --min-answer-score, --groundedness-check/--no-groundedness-check, --pii-redaction/--no-pii-redaction, --prompt-injection-hardening/--no-prompt-injection-hardening, and --no-llm.

chunks

uv run raggit chunks <document-id> [OPTIONS]

Options: --filename to look up by filename, --full to show full content.

status

uv run raggit status

Shows a table of indexed documents and active embedding collections.

eval

uv run raggit eval <dataset.yaml> [OPTIONS]
uv run raggit eval --generate --kind component --component chunker --name my-chunker
uv run raggit eval --generate --kind pipeline --pipeline ingestion --name pipe
uv run raggit eval --comprehensive --name full
uv run raggit eval --generate --kind all --name all-tiers

Options: --generate, --comprehensive, --list-metrics, --kind component|pipeline|system|all, --component parser|chunker|..., --pipeline ingestion|retrieval|e2e, --name, --description, --metric (repeatable, 69+ available), --k (repeatable), --output, --output-format, --log-level.

Tier mapping: component isolates primitives (14 types) with synthetic data; pipeline tests ingestion (parse→chunk→clean→embed) and retrieval (sanitize→RRF→rerank→traversal) with DB; system end-to-end with LLM, citations, filters, p50/p95; all runs every tier sequentially.

Storage Backends

raggit supports local filesystem, S3, Google Cloud Storage, and Azure Blob Storage. Remote backends are installed as optional extras to keep the base install small.

Local filesystem

The default backend. Set STORAGE_SOURCE_TYPE=local and STORAGE_URI to a directory path. The directory is created automatically if it does not exist. Changes are detected instantly via OS-native events.

AWS S3

Install the S3 extra:

uv pip install 'raggit[s3]'

Then run setup with S3 options:

uv run raggit setup \
  --database-url postgresql+asyncpg://raggit:raggit@localhost:5433/raggit \
  --qdrant-url http://localhost:6333 \
  --storage-source-type s3 \
  --storage-uri s3://my-bucket/documents \
  --storage-bucket my-bucket \
  --storage-prefix documents \
  --storage-region us-east-1 \
  --aws-access-key-id $AWS_ACCESS_KEY_ID \
  --aws-secret-access-key $AWS_SECRET_ACCESS_KEY \
  --llm-provider openai \
  --llm-model gpt-4o-mini \
  --llm-api-key $OPENAI_API_KEY

Google Cloud Storage

Install the GCS extra:

uv pip install 'raggit[gcs]'

uv run raggit setup \
  --database-url postgresql+asyncpg://raggit:raggit@localhost:5433/raggit \
  --qdrant-url http://localhost:6333 \
  --storage-source-type gcs \
  --storage-uri gs://my-bucket/documents \
  --storage-bucket my-bucket \
  --storage-prefix documents \
  --gcs-service-account-path /path/to/service-account.json \
  --llm-provider openai \
  --llm-model gpt-4o-mini \
  --llm-api-key $OPENAI_API_KEY

Azure Blob Storage

Install the Azure extra:

uv pip install 'raggit[azure]'

uv run raggit setup \
  --database-url postgresql+asyncpg://raggit:raggit@localhost:5433/raggit \
  --qdrant-url http://localhost:6333 \
  --storage-source-type azure_blob \
  --storage-uri azure://my-container/documents \
  --storage-container my-container \
  --storage-prefix documents \
  --azure-connection-string $AZURE_STORAGE_CONNECTION_STRING \
  --llm-provider openai \
  --llm-model gpt-4o-mini \
  --llm-api-key $OPENAI_API_KEY

Configuration

Configuration is loaded from environment variables and a ~/.config/raggit/raggit.env file generated by raggit setup. The setup command writes the file with 0600 permissions.

Environment variables

Docker Deployment

Build and run the entire stack with one command:

docker compose up -d

This starts:

• raggit-postgres on port 5433
• raggit-qdrant on ports 6333 and 6334
• raggit-app running raggit serve with the FastAPI server on port 8000 and the watcher enabled by default

Mount your documents into ./data/documents. The container entrypoint applies Alembic migrations before starting the service.

Useful commands

# View logs
docker compose logs -f raggit

# Run one-time ingestion inside the container
docker compose exec raggit raggit ingest

# Run a query
docker compose exec raggit raggit query "What is raggit?"

# Use the HTTP API from the host
curl http://localhost:8000/health
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "What is raggit?"}'

# Stop everything
docker compose down

Development

raggit uses uv for dependency management and pytest for testing. The default dependency group includes dev tools and all cloud SDKs.

# Install dependencies
uv sync

# Run linting
uv run ruff check .

# Run type checking
uv run mypy raggit

# Run tests
uv run pytest

Project structure

raggit/
  api/            # Pydantic models, public API types, and FastAPI server
  cli/            # Typer CLI commands
  core/           # Configuration, logging, audit, watcher service
  db/             # SQLAlchemy models, repositories, sessions, vector store
  eval/           # Evaluation: component (14 types) / pipeline (ingestion|retrieval|e2e) / system (E2E) / all; 69+ metrics
  ingestion/      # Parsing, chunking, cleaning, PII, injection, embedding, indexer
  llm/            # LLM providers and answer augmentation
  retrieval/      # Sanitizer, rewrite, BM25, semantic, RRF, reranker, threshold, parent-window, traversal, safety
  storage/        # Storage backends and factory

Adding a storage backend

1. Subclass raggit.storage.base.Storage.
2. Implement list_files, read_file, file_exists, compute_hash, watch, and close.
3. Register the backend in raggit.storage.factory.create_storage.
4. Add corresponding fields to raggit.api.models.StorageConfig if needed.
5. Add tests mirroring tests/test_storage_s3.py.

Troubleshooting

Watcher is not detecting local file changes

• Verify you are running raggit serve (the watcher is automatic – no separate raggit watch needed).
• Ensure the watched path is the exact directory where files are created and that the watcher is not disabled via --no-watcher or RAGGIT_NO_AUTO_WATCHER=1.
• Check /watcher/status to confirm the watcher is running; if not, start it via POST /watcher/start or restart raggit serve.
• Network filesystems (NFS, some Docker volumes) may not emit reliable filesystem events. Use host paths when possible.

Initial sync is slow

• The first sync must read, parse, chunk, and embed every file. Subsequent syncs use the stat snapshot and skip unchanged files.
• Enable the sentence-transformers cache and ensure you have enough CPU/GPU for embedding.

Queries return no results

• Check raggit status to confirm documents are completed.
• Verify the active embedding collection in embedding_collections matches the model you queried with.
• Try lowering --min-score or disabling --refuse-on-empty temporarily.

Cloud watcher misses events

• Cloud watchers poll by default. Decrease STORAGE_POLL_INTERVAL_SECONDS if you need faster detection.
• For true real-time cloud watching, route provider events to a message queue and extend the watcher to consume it.

Permission denied on config file

• raggit setup writes ~/.config/raggit/raggit.env with 0600 permissions. If you created it manually, ensure it is readable by your user.

License

raggit is released under the MIT License.