Features

• Document ingestion — PDF, DOCX, PPTX, HTML, Markdown, images, and more via Docling
• Embedding providers — OpenAI, OpenAI-compatible gateways, Cohere, and Voyage
• Embedding presets — save named provider/model configs once, reuse across collections
• Turbopuffer search — vectors, chunk text, metadata filters, BM25 keyword search, and hybrid retrieval via Turbopuffer
• Namespace isolation — each collection maps to a Turbopuffer namespace for scoped writes, exports, truncation, and deletion
• Reranking — Cohere reranking for improved result relevance
• Multi-collection queries — search across collections in a single request
• Generated chat — stateless backend-grounded playground chat with streaming and citations
• Batch operations — bulk upload, delete, status checks, and queries
• S3/R2 connector — mirror bucket prefixes with manual or scheduled sync
• Status polling — REST endpoints for document and batch processing status
• Auth, audit, scopes — admin accounts, session cookies, scoped bigrag_sk_… API keys, and full audit/access logs
• Metadata controls — per-collection metadata schemas, file validation, and content-hash deduplication at ingest
• Retrieval evaluation runner — ship recall@k / MRR / nDCG regressions against a golden set
• Analytics — per-collection query analytics and platform-wide stats
• Webhooks — HMAC-signed delivery, retries, circuit breaker, admin replay
• Encrypted sensitive caches at rest — provider API keys, webhook secrets, embedding-cache rows, and Redis cache payloads sealed with Fernet (BIGRAG_MASTER_KEY)
• Self-hostable — single docker compose up to run everything
• Clients — TypeScript and Python SDKs plus an MCP server for Claude Desktop, Cursor, and any MCP-aware runtime

Quick Start

docker compose up -d

This starts the bigRAG API, worker, admin UI, Postgres, and Redis. Open localhost:3000 for the admin UI or localhost:4000/docs for the interactive API docs.

[!IMPORTANT] Configure Turbopuffer from onboarding before ingesting or querying collections.

Once Turbopuffer is configured, create the first admin and mint an API key for HTTP clients:

export BASE="http://localhost:4000"

curl -X POST "$BASE/v1/auth/setup" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email": "[email protected]", "password": "a-strong-password", "display_name": "Admin"}'

export BIGRAG_API_KEY=$(curl -s -X POST "$BASE/v1/admin/api-keys" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"name": "local-dev", "scopes": ["*:*"]}' | jq -r .key)

# Create a collection
curl -X POST "$BASE/v1/collections" \
  -H "Authorization: Bearer $BIGRAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "docs", "embedding_api_key": "sk-..."}'

# Upload a document
curl -X POST "$BASE/v1/collections/docs/documents" \
  -H "Authorization: Bearer $BIGRAG_API_KEY" \
  -F "[email protected]"

# Query
curl -X POST "$BASE/v1/collections/docs/query" \
  -H "Authorization: Bearer $BIGRAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the main findings?"}'

Development

./dev.sh  # starts Postgres, Redis, the API with hot reload, and the worker

Docker Images

docker pull yoginth/bigrag-api:latest
docker pull yoginth/bigrag-ui:latest

Release artifacts use CalVer (YYYY.M.D). Docker publishes latest for quick starts; pin a dated tag from the release you deploy in production.

Architecture

graph TD
    MCP([MCP client<br/>Claude / Cursor]) -->|bigrag-mcp| API
    AdminUI([Admin UI]) -->|session cookie| API
    SDK([TS / Python SDK]) -->|bigrag_sk_… key| API
    Curl([curl / any HTTP client]) -->|bigrag_sk_… key| API

    API[bigRAG API<br/>Python / FastAPI]

    API --> Auth[Auth, scopes, audit]
    API --> Collections[Collections]
    API --> Documents[Documents]
    API --> Query[Query]
    API --> Chat[Chat]
    API --> Webhooks[Webhooks]

    Documents -->|stage ingestion files| Storage[(Temporary staging<br/>Local disk)]
    Documents -->|sync object prefixes| S3[S3 / R2<br/>bucket prefix mirror]
    Documents -->|enqueue| Redis[(Redis<br/>Job queue + event bus)]
    Redis -->|process| Worker[Ingestion worker]

    Worker -->|parse| Docling[Docling<br/>PDF, DOCX, HTML, Images]
    Worker -->|embed| Embedding[Embedding provider<br/>OpenAI / compatible / Cohere / Voyage]
    Worker -->|store vectors + text| Vectors[(Turbopuffer)]

    Query -->|search| Vectors
    Query -->|embed query| Embedding
    Query -->|rerank| Reranker[Cohere Rerank]
    Chat -->|retrieve context| Query
    Chat -->|generate answer| LLM[Chat provider<br/>OpenAI / compatible]

    Auth --> Postgres
    Collections --> Postgres[(Postgres<br/>Metadata + audit + deliveries)]
    Documents --> Postgres
    Webhooks --> Postgres

API Reference

Full interactive docs at /docs (Swagger UI) when running.

Embedding Models

SDKs

TypeScript

npm install @bigrag/client

Published npm releases use CalVer, for example @bigrag/[email protected].

import { BigRAG } from "@bigrag/client";

const client = new BigRAG({ apiKey: "your-key", baseUrl: "http://localhost:4000" });

// Upload a document
const doc = await client.documents.upload("docs", new File([pdf], "paper.pdf"));

// Poll processing status
let current = doc;
while (current.status === "pending" || current.status === "processing") {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  current = await client.documents.get("docs", doc.id);
  console.log(current.progress?.message ?? current.status, current.progress?.progress ?? 0);
}

// Query
const { results } = await client.queries.query("docs", { query: "What is RAG?" });

Python

pip install bigrag==2026.5.23

from bigrag import BigRAG

client = BigRAG(api_key="your-key", base_url="http://localhost:4000")

# Upload a document
doc = await client.documents.upload("docs", "/path/to/paper.pdf")

# Query
result = await client.queries.query("docs", {"query": "What is RAG?"})

MCP Server

Expose bigRAG to Claude Desktop, Cursor, and any MCP-aware runtime:

BIGRAG_URL=https://bigrag.example.com \
BIGRAG_API_KEY=bigrag_sk_... \
bigrag-mcp

Drop this into claude_desktop_config.json:

{
  "mcpServers": {
    "bigrag": {
      "command": "bigrag-mcp",
      "env": {
        "BIGRAG_URL": "https://bigrag.example.com",
        "BIGRAG_API_KEY": "bigrag_sk_..."
      }
    }
  }
}

Full-workspace keys expose 8 tools — list_collections, get_collection, get_collection_stats, query, multi_collection_query, list_documents, get_document, get_document_chunks. Collection-pinned keys see 6 (no list_collections or multi_collection_query). See docs/sdks/mcp for details.

Configuration

Bootstrap settings use the BIGRAG_ prefix as environment variables, or configure them in bigrag.toml. Backend logging defaults to info / text — use BIGRAG_LOG_FORMAT=json for production log collection. Turbopuffer is configured from the admin UI and stored in Postgres alongside the other instance settings.

Server

Database & Redis

Sessions & Auth

[!TIP] ./dev.sh and the default Docker Compose setup allow the local admin UI origin http://localhost:3000. For production, set BIGRAG_CORS_ORIGINS to the exact admin UI origin. Cross-site admin UI deployments also need BIGRAG_SESSION_COOKIE_SECURE=true and usually BIGRAG_SESSION_COOKIE_SAMESITE=none.

Embedding

Chat

Security

Ingestion & Uploads

Caching

Webhooks

Supported Formats

PDF, DOCX, PPTX, XLSX, HTML, Markdown, CSV, TSV, XML, JSON, PNG, JPG, TIFF, BMP, GIF — text PDFs are extracted directly, while scanned PDFs and other rich formats are powered by Docling. Scanned-PDF OCR is enabled by default.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Sponsor

If bigRAG is useful to you, consider sponsoring the project.

License

MIT