axon-rag 0.2.1

General-purpose open-source RAG engine with multi-LLM, hybrid retrieval, GraphRAG, and MCP support

Your documents, answerable. On your hardware.

Drop in PDFs, code, spreadsheets, or URLs — ask anything, get cited answers from a local LLM.
Nothing leaves your machine.

---

---

🤔 Why Axon?

Most RAG tools make you choose between cloud power and data privacy. Axon runs entirely on your hardware — full capability, zero egress.

• 🔒 Private by default — all inference runs locally via Ollama or vLLM. No API key, no upload, no telemetry.
• 📄 Ingest anything — 54 file formats (PDF, DOCX, Jupyter, code, images, URLs) in one command. SHA-256 dedup skips unchanged files.
• 🤖 Works in your tools — @axon in Copilot Chat, MCP for Claude Code / Codex / Gemini CLI / Cursor, Graph panel in VS Code or your browser.
• 🤝 Built for teams — share your knowledge base with signed, revocable read-only keys. Per-user permissions, full audit trail, no extra infrastructure.
• 🕸️ See your knowledge as a graph — interactive 3D entity-relationship graph. Embedded webview in VS Code; opens in your browser everywhere else. Click any node to jump to the exact source line.
• 🔬 Production-grade retrieval — hybrid search, reranking, HyDE, multi-query expansion, and automatic web fallback. Zero manual tuning.

---

✨ Capabilities

🔍 Retrieval Hybrid semantic + keyword search HyDE, multi-query, step-back, query decomposition Sentence-window context retrieval BGE reranker for second-pass precision Web fallback via Brave Search (CRAG-Lite) Smart per-question query routing	🧠 Graph Intelligence RAPTOR — hierarchical corpus summaries GraphRAG — entity/relation/community graph (local / global / hybrid) Code Graph — file/class/function graph with import edges Interactive 3D graph — embedded webview in VS Code, browser elsewhere
📥 Ingest Everything 54 file formats — PDF, DOCX, XLSX, PPTX, Jupyter, images, 24 code formats URL ingestion — any public web page SHA-256 dedup skips unchanged files Stale detection for modified sources 4 content-aware chunking strategies	🔧 LLMs & Embeddings Local: Ollama, vLLM Cloud: OpenAI, Gemini, xAI Grok, GitHub Copilot (API) Hot-swap provider and model — no restart needed Streaming on all providers 4 embedding providers; BGE-M3 for multilingual
🏗️ Projects & Privacy Isolated knowledge base per project, with nesting Federated search across projects (@projects, @mounts, @store) Strict offline / air-gapped mode — zero outbound calls AxonStore — signed read-only sharing across OS users	🛡️ Governance & Agents Governance Console — full audit trail of every query Graceful maintenance states: normal → draining → readonly → offline REST API — 54 endpoints with Swagger docs at /docs MCP server — 31 tools for Claude Code, Codex, Gemini, Cursor, Copilot @axon VS Code chat participant with Graph and Governance panels

---

⚡ Quick Start

pip install axon-rag    # requires Python 3.10+
axon                    # launches the interactive REPL

Local inference uses Ollama. Cloud providers (OpenAI, Gemini, Grok, vLLM, GitHub Copilot) work via API keys.

→ Full installation guide with VS Code, MCP, and cloud provider setup

---

🚀 Entry Points

Command	Starts	Default Port	Best For
axon	Interactive REPL	—	Day-to-day exploration, power users
axon-api	FastAPI REST server	8000	Agents, scripts, CI pipelines
axon-mcp	MCP stdio server	—	Any MCP-compatible agent (Claude Code, Codex, Gemini CLI, Cursor, Copilot…)
axon-ui	Streamlit UI	8501	Browser-based exploration

---

🔌 VS Code + GitHub Copilot

Install the bundled VSIX to unlock the @axon chat participant, Knowledge Graph panel, Code Graph panel, and Governance dashboard — directly inside VS Code alongside Copilot.

Extensions panel  →  "..."  →  Install from VSIX...
→  run `axon-ext`  (or install from VSIX manually)

Or connect via MCP for Copilot agent mode — point .vscode/mcp.json at axon-mcp and all 31 tools appear in the agent hammer menu automatically.

The VS Code extension surfaces 35 LM tools to Copilot Chat (a superset of the 31 MCP tools, adding VS Code–specific helpers like show_graph).

Full setup guide →

---

📚 Documentation

Getting started

	Guide	What it covers
🚀	Getting Started	First-time walkthrough — ingest, query, settings
⚙️	Setup Guide	Install, models, VS Code extension, MCP connection
🔧	Troubleshooting	Common errors and platform-specific fixes

Reference

	Guide	What it covers
🔑	Admin Reference	Every endpoint, REPL command, CLI flag, and config option
⚡	Quick Reference	Commands and flags at a glance
📡	API Reference	Full REST endpoint reference with request/response schemas
🔌	MCP Tools	All 31 MCP tool signatures with parameter defaults

Deep dives

	Guide	What it covers
🤖	Model Guide	Choosing LLM and embeddings; per-provider config examples
🔬	Advanced RAG	HyDE, RAPTOR, GraphRAG, CRAG-Lite — how each technique works
🌐	Web Search	Brave Search integration, CRAG-Lite fallback setup
🏝️	Offline / Air-gap Guide	Full air-gap setup, model pre-download, local-assets-only mode
💻	Code RAG Guide	Code graph retrieval and structural search
🤝	AxonStore	Multi-user sharing, revocation, and the lease lifecycle
📊	Governance Console	Audit trail, maintenance runbook, session management
📈	Evaluation Guide	RAGAS metrics, running evals, building testsets
🛠️	Development Guide	Tests, contributing, pre-commit hooks
📦	Packaging & Release	Single-package PyPI release with optional Rust acceleration

---

🔒 Security

Ingestion is sandboxed to a configurable base directory (RAG_INGEST_BASE). Requests outside it are rejected with 403. See SECURITY.md.

📄 License

MIT — see LICENSE.