axon-rag 0.1.0

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 — 30 tools for Claude Code, Codex, Gemini, Cursor, Copilot @axon VS Code chat participant with Graph and Governance panels

---

⚡ Quick Start

pip install -e .   # requires Python 3.10+ and Ollama
axon               # launches the interactive REPL

→ 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 30 tools appear in the agent hammer menu automatically.

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 30 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

---

🔒 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.