AgentRAG

<div align="center">  <br/> [](https://github.com/SARAMALI15792/AgentRAG/actions/workflows/ci.yml) [](https://pypi.org/project/aicompatible-rag/) [](https://www.python.org/downloads/) [](LICENSE) [](https://mypy.readthedocs.io/) [](https://github.com/psf/black) </div> --- ## What It Does AI models are powerful reasoners — but they are blind to your private data. Every session starts from zero. AgentRAG closes that gap. It is a locally-running MCP server that gives Claude a persistent, semantically-indexed memory over any documents you bring in. Claude calls `search_documents`, `plan_query`, and `evaluate_chunks` the same way it calls any other tool — and gets back the most relevant chunk from the right document, ranked by meaning rather than keyword match. **Key properties:** - **Fully local by default** — Qdrant vector store runs in-process, embeddings generated locally via `sentence-transformers`. No API keys required for core retrieval. - **Universal ingestion** — 20+ file types: PDF, DOCX, XLSX, EPUB, JSON, YAML, Markdown, Python, Jupyter notebooks, subtitles, emails, and web pages. - **Agentic retrieval** — Claude decomposes complex queries into sub-questions, searches multiple angles, scores relevance, and re-searches if needed — all through native MCP tool calls. - **Workspace isolation** — maintain separate knowledge bases per project via named Qdrant collections. - **Cloud sync (opt-in)** — encrypted snapshot push/pull to S3-compatible storage. Never syncs without explicit `agentrag sync push`. - **Privacy by design** — no telemetry, no analytics, no network calls unless you explicitly configure one. --- ## 60-Second Quickstart ```bash # Install pip install aicompatible-rag # (Optional) Enable agentic retrieval — free key from https://aistudio.google.com/ export AGENTRAG_GOOGLE_API_KEY=your_key_here # Start the MCP server agentrag serve ``` Then add the config block below to Claude Desktop and start chatting over your documents. --- ## Integrations AgentRAG works with any MCP-compatible client. Pick the integration that matches your workflow. --- ### Claude Desktop Add to your Claude Desktop config file: | Platform | Path | |----------|------| | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | | Windows | `%APPDATA%\Claude\claude_desktop_config.json` | | Linux | `~/.config/Claude/claude_desktop_config.json` | **Option A — pip install (recommended)** ```json { "mcpServers": { "agentrag": { "command": "agentrag", "args": ["serve", "--data-dir", "~/.agentrag"] } } } ``` **Option B — zero-install via uvx (no pip required)** ```json { "mcpServers": { "agentrag": { "command": "uvx", "args": ["--from", "aicompatible-rag", "agentrag", "serve", "--data-dir", "~/.agentrag"] } } } ``` --- ### Claude Code (CLI) [Claude Code](https://claude.ai/code) supports MCP servers via project-level or global config. **Add to project** (`.claude/mcp_servers.json` in your repo): ```json { "agentrag": { "command": "agentrag", "args": ["serve", "--data-dir", "~/.agentrag"], "env": { "AGENTRAG_GOOGLE_API_KEY": "your_key_here" } } } ``` Or register globally via the Claude Code CLI: ```bash claude mcp add agentrag agentrag serve --data-dir ~/.agentrag ``` Once registered, Claude Code can call all AgentRAG tools (`ingest_file`, `search_documents`, etc.) directly from any coding session — giving it semantic memory over your private docs, codebases, and notes. --- ### VS Code (GitHub Copilot / MCP extension) Any VS Code extension that supports MCP servers (e.g. GitHub Copilot with MCP, or the official MCP extension) can connect to AgentRAG over HTTP transport. > **Why `localhost`?** VS Code does not support `stdio` transport — it requires an HTTP URL. `localhost:8000` is the address of AgentRAG running on your own machine. No data leaves your computer; the URL is purely local. **Step 1 — start AgentRAG in HTTP mode:** ```bash AGENTRAG_TRANSPORT=http AGENTRAG_PORT=8000 agentrag serve ``` **Step 2 — add to VS Code `settings.json`:** ```json { "mcp.servers": { "agentrag": { "url": "http://localhost:8000/mcp" } } } ``` --- ### JetBrains IDEs (IntelliJ, PyCharm, WebStorm, etc.) JetBrains AI Assistant supports MCP servers via HTTP transport. > **Why `localhost`?** JetBrains AI Assistant requires an HTTP URL to connect to MCP servers. `localhost:8000` points to AgentRAG running on your own machine — the same privacy guarantee applies; nothing is sent over the network. **Step 1 — start AgentRAG in HTTP mode:** ```bash AGENTRAG_TRANSPORT=http AGENTRAG_PORT=8000 agentrag serve ``` **Step 2 — add in** `Settings → Tools → AI Assistant → MCP Servers`: ``` Name: agentrag URL: http://localhost:8000/mcp ``` --- ### Any MCP-compatible client AgentRAG speaks the [Model Context Protocol](https://modelcontextprotocol.io/) over both `stdio` and HTTP. Any client that supports MCP can connect: | Transport | Use case | How to start | |-----------|----------|--------------| | `stdio` | Claude Desktop, Claude Code, local tools | `agentrag serve` (default) | | `http` | VS Code, JetBrains, remote agents, custom clients | `AGENTRAG_TRANSPORT=http agentrag serve` | --- ## CLI Reference ``` agentrag serve Start the MCP server agentrag ingest Ingest a file or directory into the vector store agentrag list List all ingested sources agentrag sync Cloud sync subcommands (push / pull / status) ``` ### `agentrag serve` | Flag | Default | Description | |------|---------|-------------| | `--data-dir` | `~/.agentrag` | Root directory for Qdrant data | | `--transport` | `stdio` | `stdio` (Claude Desktop) or `http` | | `--port` | `8000` | HTTP port (ignored for stdio) | | `--embed-model` | `sentence-transformers/all-MiniLM-L6-v2` | Embedding model | | `--collection` | `documents` | Active Qdrant collection name | ### `agentrag ingest` ```bash agentrag ingest /path/to/file.pdf agentrag ingest /path/to/directory --recursive ``` ### `agentrag sync` ```bash agentrag sync push # snapshot current store and upload agentrag sync pull # download latest snapshot and restore agentrag sync status # show last push/pull timestamps ``` Requires `AGENTRAG_SYNC_BACKEND`, `AGENTRAG_SYNC_ENDPOINT`, and `AGENTRAG_SYNC_KEY`. See [Cloud Sync](#cloud-sync) for setup. --- ## Environment Variables All variables are loaded from environment or `.env` file via `pydantic-settings`. ### Core | Variable | Default | Description | |----------|---------|-------------| | `AGENTRAG_DATA_DIR` | `~/.agentrag` | Root directory for Qdrant data and config | | `AGENTRAG_EMBED_MODEL` | `sentence-transformers/all-MiniLM-L6-v2` | Embedding model name (full `{org}/{model}` HuggingFace path) | | `AGENTRAG_VECTOR_DIM` | `384` | Output dimension of the embedding model — must match the Qdrant collection | | `AGENTRAG_CHUNK_SIZE` | `512` | Token chunk size for sliding-window splitting | | `AGENTRAG_CHUNK_OVERLAP` | `64` | Token overlap between consecutive chunks | | `AGENTRAG_PORT` | `8000` | HTTP port for HTTP transport mode | | `AGENTRAG_TRANSPORT` | `stdio` | `stdio` or `http` | | `AGENTRAG_COLLECTION` | `documents` | Active Qdrant collection name | | `AGENTRAG_INGEST_TIMEOUT` | `300` | Max seconds per file ingestion before timeout | | `AGENTRAG_MAX_FILE_SIZE_MB` | `100` | Max file size in MB — files above this are rejected with an actionable error | ### Agentic Retrieval (Gemini) | Variable | Default | Description | |----------|---------|-------------| | `AGENTRAG_GOOGLE_API_KEY` | _(none)_ | Google Gemini API key. Free key at [aistudio.google.com](https://aistudio.google.com/). Graceful degrade if missing. | | `AGENTRAG_GEMINI_MODEL` | `gemini-2.0-flash` | Gemini model for query decomposition and chunk evaluation | | `AGENTRAG_QUERY_EXPAND` | `false` | Set `true` to enable Gemini-backed query expansion in `plan_query` | | `AGENTRAG_RERANK` | `false` | Set `true` to activate cross-encoder re-ranking (`ms-marco-MiniLM-L-6-v2`) | ### Cloud Sync | Variable | Default | Description | |----------|---------|-------------| | `AGENTRAG_SYNC_BACKEND` | `local` | `local` or `s3` | | `AGENTRAG_SYNC_ENDPOINT` | _(none)_ | S3: bucket name. S3-compatible: full endpoint URL | | `AGENTRAG_SYNC_KEY` | _(none)_ | Fernet encryption key (base64). Generate: `python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'` | | `AGENTRAG_SYNC_LOCAL_DIR` | `~/.agentrag/backups` | Directory for local backend snapshot archives | | `AGENTRAG_SYNC_PREFIX` | `agentrag/` | S3 key prefix for all uploaded snapshots | --- ## MCP Tools All tools are available natively in Claude — no special prompting required. ### Ingestion | Tool | Input | Description | |------|-------|-------------| | `ingest_file` | `path, metadata?` | Ingest a single local file into the vector store | | `ingest_directory` | `path, recursive?, file_types?, metadata?` | Bulk ingest all supported files in a directory | | `ingest_url` | `url, metadata?` | Fetch a web page and ingest its text content | ### Retrieval | Tool | Input | Description | |------|-------|-------------| | `search_documents` | `query, top_k?, filters?` | Semantic search — returns chunks ranked by relevance | | `search_by_metadata` | `filters` | Filter sources by metadata without a semantic query | | `search_multi` | `queries, top_k?` | Search with multiple queries; deduplicates by `chunk_id` | | `search_stream` | `query, top_k?` | Streaming search — results arrive as they score | ### Agentic Loop | Tool | Input | Description | |------|-------|-------------| | `plan_query` | `query` | Decompose a complex query into focused sub-queries (Gemini-backed) | | `evaluate_chunks` | `query, results` | Score each chunk's relevance; returns `EvaluationReport` with re-search suggestions | ### Document Management | Tool | Input | Description | |------|-------|-------------| | `list_sources` | _(none)_ | List all ingested sources with metadata summary | | `get_document` | `source_id` | Retrieve the full reconstructed text of a source | | `delete_source` | `source_id` | Remove a source and all its vector chunks | ### Workspace (Collections) | Tool | Input | Description | |------|-------|-------------| | `list_collections` | _(none)_ | List all named Qdrant collections | | `create_collection` | `name` | Create a new named collection for workspace isolation | | `switch_collection` | `name` | Set active collection for subsequent operations | --- ## Agentic Retrieval Loop When `AGENTRAG_GOOGLE_API_KEY` is set, Claude can run a full agentic retrieval loop: ``` plan_query("compare treatment A and treatment B for condition X") → QueryPlan(sub_queries=["what is treatment A?", "what is treatment B?", "comparison studies"]) search_multi(sub_queries, top_k=5) → deduplicated SearchResult list evaluate_chunks(original_query, results) → EvaluationReport(sufficient=False, suggested_queries=["side effects comparison", ...]) search_multi(suggested_queries) ← re-search if not sufficient ``` All three tools degrade gracefully when the API is unavailable — retrieval is never blocked. --- ## Supported File Types | Extension | Category | Install | |-----------|----------|---------| | `.txt`, `.md` | Plaintext | _(included)_ | | `.pdf` | Document | _(included)_ | | `.docx` | Document | _(included)_ | | `.html` | Web | _(included)_ | | `.py` | Code | _(included)_ | | `.ipynb` | Notebook | _(included)_ | | `.json`, `.yaml`, `.xml`, `.toml` | Structured data | _(included)_ | | `.csv` | Tabular | _(included)_ | | `.eml`, `.mbox` | Email | _(included)_ | | `.xlsx` | Spreadsheet | `pip install aicompatible-rag[office]` | | `.pptx` | Presentation | `pip install aicompatible-rag[office]` | | `.epub` | eBook | `pip install aicompatible-rag[ebooks]` | | `.mobi` | eBook | `pip install aicompatible-rag[ebooks]` | | `.srt`, `.vtt` | Subtitles | `pip install aicompatible-rag[web]` | | URL | Web page | `pip install aicompatible-rag[web]` | Install all optional types at once: ```bash pip install aicompatible-rag[all] ``` --- ## Cloud Sync AgentRAG can back up and restore your Qdrant vector store to any S3-compatible storage. All snapshots are encrypted client-side before upload — your encryption key never leaves your machine. ### Local backup (no cloud required) ```bash # .env AGENTRAG_SYNC_BACKEND=local AGENTRAG_SYNC_LOCAL_DIR=~/agentrag-backups AGENTRAG_SYNC_KEY=<your-fernet-key> ``` ### S3 sync ```bash # .env AGENTRAG_SYNC_BACKEND=s3 AGENTRAG_SYNC_ENDPOINT=my-bucket-name AGENTRAG_SYNC_KEY=<your-fernet-key> ``` Generate a key: ```bash python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())' ``` Then push and pull: ```bash agentrag sync push # snapshot + encrypt + upload agentrag sync pull # download + decrypt + restore agentrag sync status # timestamps of last push/pull ``` > **Privacy guarantee:** Snapshots are encrypted with Fernet (AES-128-CBC + HMAC-SHA256) before upload. The server never sees plaintext data. --- ## Workspace Isolation Maintain separate knowledge bases per project using named Qdrant collections. ```bash # via env var AGENTRAG_COLLECTION=project-alpha agentrag serve # via MCP tool (from Claude) create_collection("project-alpha") switch_collection("project-alpha") ingest_file("/path/to/docs") search_documents("query") # scoped to project-alpha only ``` Data in one collection is never visible from another. --- ## Architecture ``` Ingestion path: File / URL → reader_registry (dispatches to format reader) → reader.py RawDocument → chunker.py List[Chunk] (512 tokens / 64 overlap) → embedder.py List[EmbeddedChunk] (local sentence-transformers) → store/qdrant.py upsert (embedded Qdrant, persisted to ~/.agentrag) Retrieval path: Claude → search_documents → searcher.py embed query + qdrant.query + rerank → List[SearchResult] Agentic path: Claude → plan_query → search_multi → evaluate_chunks → (re-search if needed) ``` **Dependency direction is strict** — `store/` never imports from `ingestion/` or `retrieval/`. `ingestion/` never imports from `retrieval/`. Reader modules in `ingestion/readers/` are pure leaf functions: `(Path) -> str`. --- ## Development Setup ```bash git clone https://github.com/SARAMALI15792/AgentRAG cd AgentRAG uv pip install -e ".[dev,office,ebooks,web]" uv run pytest --tb=short ``` ### Toolchain | Tool | Command | |------|---------| | Format | `uv run black .` | | Lint | `uv run ruff check .` | | Type check | `uv run mypy --strict src/` | | Test | `uv run pytest --tb=short` | | All checks | `uv run black . && uv run ruff check . && uv run mypy --strict src/` | A pre-commit hook runs all three checks automatically before every commit. ### Project Layout ``` src/agentrag/ cli.py CLI entry point (typer) config.py All runtime configuration (pydantic-settings) types.py Domain dataclasses — single source of truth ingestion/ reader → chunker → embedder → pipeline retrieval/ searcher, reranker, query_planner, evaluator, streaming store/ qdrant.py — sole importer of qdrant_client sync/ cloud sync backends (local + S3) server/ MCP server, tool handlers tests/ unit/ isolated, all external deps mocked integration/ real Qdrant embedded, real files scripts/ verify_phase*.sh deterministic phase exit gates ``` --- ## Roadmap | Phase | Status | Deliverable | |-------|--------|-------------| | 1 — Core Pipeline | ✅ Complete | read → chunk → embed → store | | 2 — MCP Server | ✅ Complete | 7 MCP tools, stdio + HTTP transport | | 3A — Extended Files | ✅ Complete | DOCX, HTML, Python, Jupyter | | 3B — Agentic Retrieval | ✅ Complete | 20+ file types, `plan_query`, `search_multi`, `evaluate_chunks` | | 4 — Search Quality | ✅ Complete | Cross-encoder reranker, metadata filter hardening | | 5 — Distribution | ✅ Complete | PyPI package (`aicompatible-rag`), `uvx` entry point | | 6 — Multi-Collection | ✅ Complete | Named collections, streaming retrieval | | 7 — Cloud Sync | ✅ Complete | Encrypted push/pull to S3-compatible backends | --- ## License MIT — see [LICENSE](LICENSE).