axon-rag

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.

Axon REPL — startup banner, ingest, and a cited query

🤔 Why Axon?

Most RAG tools make you choose between cloud power and data privacy. Axon is local-first — full capability with zero egress when you run on Ollama or vLLM; cloud providers (OpenAI, Gemini, Grok, GitHub Copilot, Ollama Cloud) stay optional.

🔒 Private by default — local inference via Ollama or vLLM is the recommended path; cloud providers (OpenAI, Gemini, Grok, GitHub Copilot, Ollama Cloud) remain opt-in. No telemetry. Strict offline / air-gap mode shuts every outbound call off entirely.
📄 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. Sealed (AES-256-GCM encrypted) sharing works safely through OneDrive, Dropbox, and Google Drive. Per-user permissions, full audit trail, no extra infrastructure. Quick setup →
🕸️ 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 inspect its supporting chunks and source excerpt.
🔬 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
Structured citations — sources + citations arrays with character offsets (Claude / OpenAI compatible)

🧠 Graph Intelligence

GraphRAG — entity/relation/community graph (local / global / hybrid)
Dynamic Graph — bi-temporal SQLite facts with valid_at + invalid_at
Federated — weighted RRF over multiple backends, tunable per query
Point-in-time queries (v0.3.2) — --graph-retrieve "..." --graph-at TS
Conflict inspection (v0.3.2) — --graph-conflicts surfaces status='conflicted' facts
RAPTOR — hierarchical corpus summaries · Code Graph via AST · 3D webview

📥 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 (API key): OpenAI, Gemini, xAI Grok, GitHub Copilot, Ollama Cloud
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

☁️ Cloud-Drive Sharing

Sealed (AES-256-GCM encrypted) sharing works through any cloud sync drive. Files are ciphertext on disk — cloud providers see only encrypted bytes.

OneDrive Personal / Business
Dropbox
Google Drive (Mirror mode)

→ Sharing Guide | Quick Setup →

🛡️ Governance & Agents

Governance Console — full audit trail of every query
Graceful maintenance states: normal → draining → readonly → offline
REST API — 73 endpoints with Swagger docs at /docs
MCP server — 51 tools for Claude Code, Codex, Gemini, Cursor, Copilot
@axon VS Code chat participant with Graph and Governance panels

⚡ Quick Start

pip install "axon-rag[starter]"   # Python 3.10+. Sealed sharing + extra loaders. Web GUI ships with axon-api.
axon                              # First run auto-launches the setup wizard, then drops into the REPL.

That's it. The wizard configures your LLM provider, embedding model, and retrieval defaults; subsequent runs go straight to the REPL.

See it run — first-run wizard, ingest, and a cited query

Axon REPL — first-run wizard, ingest, and a cited query in action

If something doesn't look right:

axon --doctor                     # Health checks: Python, Ollama, model pulled, store writable.

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

→ Setup guide for VS Code, MCP, and cloud providers →

🔐 Sealed Sharing Quick Start

Share an encrypted knowledge base through OneDrive, Dropbox, or Google Drive. Cloud providers see only ciphertext.

pip install "axon-rag[sealed]"   # install sealed extra on both machines

Owner (5 steps)

axon --store-init "/path/to/OneDrive/AxonStore"  # 1. point store at sync folder
axon --store-bootstrap "your-passphrase"          # 2. bootstrap master key (once per machine)
axon --project-new research                       # 3. create project + ingest
axon --project research --ingest /docs
axon --project-seal research                      # 4. encrypt in place (≈1 s per 100 MB)
axon --share-generate research alice              # 5. print SEALED1:... string — send to grantee

Grantee (3 steps)

axon --store-init "/path/to/OneDrive/AxonStore"   # 1. same shared folder
axon --share-redeem "SEALED1:..."                  # 2. redeem — DEK stored in OS keyring
axon --project mounts/owner_research "question"   # 3. query; Axon decrypts to temp, wipes on exit

→ Full Sharing Guide — OneDrive setup, revocation, headless/Docker grantees, filesystem compatibility matrix.

🚀 Entry Points

Command	Starts	Default Port	Best For
`axon`	Interactive REPL	—	Day-to-day exploration, power users
`axon-api`	FastAPI REST server + web GUI	`8000`	Agents, scripts, CI pipelines, browser UI
`axon-mcp`	MCP stdio server	—	Any MCP-compatible agent (Claude Code, Codex, Gemini CLI, Cursor, Copilot…)
`axon-ui`	Streamlit UI — deprecated	`8501`	Superseded by the web GUI below

Browser UI: start axon-api and open http://localhost:8000/gui/. No extra command or dependency needed — the GUI ships with the server.

Deprecation: axon-ui (Streamlit) is deprecated and will be removed in a future release. It is no longer part of [starter] or [all]; install it explicitly with pip install "axon-rag[ui]" if you still need it.

🔌 VS Code + GitHub Copilot

Axon VS Code Graph Panel — answer, cited sources, and interactive 3D code graph

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

The VS Code extension surfaces 39 LM tools to Copilot Chat, covering core RAG operations, sealed-store security, sharing, and governance.

Full setup guide →

🐍 Use Axon from Your Python Agent

Drop-in retrievers for LangChain and LlamaIndex agents — no REST round-trips, no extra process. Both wrap the same AxonBrain.search_raw() codepath the REST and REPL surfaces use, so hybrid search, reranking, HyDE, multi-query, and the GraphRAG budget apply automatically.

# pip install "axon-rag[langchain]"
from axon import AxonBrain, AxonConfig
from axon.integrations.langchain import AxonRetriever

brain = AxonBrain(AxonConfig.from_yaml("config.yaml"))
retriever = AxonRetriever(brain=brain, top_k=5)

docs = retriever.invoke("what does the project do?")  # list[Document]

# pip install "axon-rag[llama-index]"
from axon.integrations.llama_index import AxonLlamaRetriever

retriever = AxonLlamaRetriever(brain=brain, top_k=5)
nodes = retriever.retrieve("what does the project do?")  # list[NodeWithScore]

Per-call overrides (e.g. force HyDE for one question): retriever.with_overrides({"hyde": True}).invoke(query). From async code, await retriever.aretrieve(query, hyde=True, top_k=8) accepts the same flags as kwargs without rebuilding the retriever (v0.4.1).

📚 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 55 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
🔐	Sharing Guide	Plaintext and sealed sharing — which filesystems are safe, OneDrive/Dropbox/Google Drive setup, revocation
📊	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

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

axon_rag-0.4.3.tar.gz (1.9 MB view details)

Uploaded Aug 9, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

axon_rag-0.4.3-cp313-cp313-win_amd64.whl (2.9 MB view details)

Uploaded Aug 9, 2026 CPython 3.13Windows x86-64

axon_rag-0.4.3-cp313-cp313-musllinux_1_2_x86_64.whl (3.4 MB view details)

Uploaded Aug 9, 2026 CPython 3.13musllinux: musl 1.2+ x86-64

axon_rag-0.4.3-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.1 MB view details)

Uploaded Aug 9, 2026 CPython 3.13manylinux: glibc 2.17+ x86-64

axon_rag-0.4.3-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.1 MB view details)

Uploaded Aug 9, 2026 CPython 3.13manylinux: glibc 2.17+ ARM64

axon_rag-0.4.3-cp313-cp313-macosx_11_0_arm64.whl (3.0 MB view details)

Uploaded Aug 9, 2026 CPython 3.13macOS 11.0+ ARM64

axon_rag-0.4.3-cp312-cp312-win_amd64.whl (2.9 MB view details)

Uploaded Aug 9, 2026 CPython 3.12Windows x86-64

axon_rag-0.4.3-cp312-cp312-musllinux_1_2_x86_64.whl (3.4 MB view details)

Uploaded Aug 9, 2026 CPython 3.12musllinux: musl 1.2+ x86-64

axon_rag-0.4.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.1 MB view details)

Uploaded Aug 9, 2026 CPython 3.12manylinux: glibc 2.17+ x86-64

axon_rag-0.4.3-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.1 MB view details)

Uploaded Aug 9, 2026 CPython 3.12manylinux: glibc 2.17+ ARM64

axon_rag-0.4.3-cp312-cp312-macosx_11_0_arm64.whl (3.0 MB view details)

Uploaded Aug 9, 2026 CPython 3.12macOS 11.0+ ARM64

axon_rag-0.4.3-cp311-cp311-win_amd64.whl (2.9 MB view details)

Uploaded Aug 9, 2026 CPython 3.11Windows x86-64

axon_rag-0.4.3-cp311-cp311-musllinux_1_2_x86_64.whl (3.4 MB view details)

Uploaded Aug 9, 2026 CPython 3.11musllinux: musl 1.2+ x86-64

axon_rag-0.4.3-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.1 MB view details)

Uploaded Aug 9, 2026 CPython 3.11manylinux: glibc 2.17+ x86-64

axon_rag-0.4.3-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.1 MB view details)

Uploaded Aug 9, 2026 CPython 3.11manylinux: glibc 2.17+ ARM64

axon_rag-0.4.3-cp311-cp311-macosx_11_0_arm64.whl (3.0 MB view details)

Uploaded Aug 9, 2026 CPython 3.11macOS 11.0+ ARM64

axon_rag-0.4.3-cp310-cp310-win_amd64.whl (2.9 MB view details)

Uploaded Aug 9, 2026 CPython 3.10Windows x86-64

axon_rag-0.4.3-cp310-cp310-musllinux_1_2_x86_64.whl (3.4 MB view details)

Uploaded Aug 9, 2026 CPython 3.10musllinux: musl 1.2+ x86-64

axon_rag-0.4.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.1 MB view details)

Uploaded Aug 9, 2026 CPython 3.10manylinux: glibc 2.17+ x86-64

axon_rag-0.4.3-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.1 MB view details)

Uploaded Aug 9, 2026 CPython 3.10manylinux: glibc 2.17+ ARM64

axon_rag-0.4.3-cp310-cp310-macosx_11_0_arm64.whl (3.0 MB view details)

Uploaded Aug 9, 2026 CPython 3.10macOS 11.0+ ARM64

File details

Details for the file axon_rag-0.4.3.tar.gz.

File metadata

Download URL: axon_rag-0.4.3.tar.gz
Upload date: Aug 9, 2026
Size: 1.9 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for axon_rag-0.4.3.tar.gz
Algorithm	Hash digest
SHA256	`875c7f63eacf4bc7252aff8c376a908bf49610f4ed23bf79c93dc3c340e8693b`
MD5	`de1730814087467eb10a0b87f1ce3afc`
BLAKE2b-256	`59bf1d71feb155b19ff1db6c184d6d6707e2706037ecdaf6b99f025ac1ccb7ed`

Algorithm	Hash digest
SHA256	`72a29a2a4fc4f21a75d0f548cdf3f4054105fd7ed2b5deb58e09a722ce047604`
MD5	`a08df25b819e43c114e966c221dae851`
BLAKE2b-256	`dc1988d3b4af468065e473a3a1b26879b44fcd3884d20ad0101c7a7008198af4`

Algorithm	Hash digest
SHA256	`5ae4fe0d979d337c420b6d086a95b6eec5cb7a93c3d72dc7c711b0a5985d180d`
MD5	`5fa8543ffa72db176073436f0410e6c5`
BLAKE2b-256	`c8d8a8b47c0fe0ae29502c9de56f3c700c05312eb2777d89d1911e143655c94a`

Algorithm	Hash digest
SHA256	`1f2d4fbd1dd31635bfe0e01e63d9a051dd43d47e9c8aac3f5a5c56920bb8ae25`
MD5	`96df6dbeeaa1b661b07ad09cb594e529`
BLAKE2b-256	`0ea59adaaedf27d919284f5384e88a97d7940e37984972123b267394624b843e`

Algorithm	Hash digest
SHA256	`1a589034ab27ac1f977cc92fba2b9a36fbf23d3708ea79d5a93fe0b35cdb7471`
MD5	`057c4bae4d5b2de0b9c11af4fdcc4c57`
BLAKE2b-256	`c9ba5dace93d08b56637cd9224e5131ef6cb5661876cdfe7fae21965b1a79756`

Algorithm	Hash digest
SHA256	`e307c6673bfb758785919c79863f518d68efa8230f7fa26a737c71d2863a0486`
MD5	`634f0ba3173dd16f9b0bbd188acaa062`
BLAKE2b-256	`9d566e45d39003c9e8a0a84e5a12d74ce4b630ea2abe44a7bd272e58a4d0df88`

Algorithm	Hash digest
SHA256	`d16898d59f1b45289cfaafdf413d68912edc33673036c02e297d5de64c215bb8`
MD5	`c5c01b4041e48dfd61c354f9f082d573`
BLAKE2b-256	`7f83436971a64c061261135f6f75d23552670c439cacce853ced53eb665cc83f`

Algorithm	Hash digest
SHA256	`1582e0cfcd82503753c806b3891399f8a93da945bf1911ec247280bc85df8fb4`
MD5	`6d83a2268797d5c4de95cc3437b7e0d1`
BLAKE2b-256	`52227b71de6a114378b4362ff7525d6b09babec5feafb2ac725f634c0bbb2015`

Algorithm	Hash digest
SHA256	`b89de03d6738898b630111fdd2853afbecc99395df5e722f954c8fc07e9212ba`
MD5	`e2768b5c2e94faf42c29591ba3ed966d`
BLAKE2b-256	`bc84a9f8e5a992bc0008304cd024dc476231147c0a45cb5953afdcdc375e06b6`

Algorithm	Hash digest
SHA256	`236b29239107e11a0b4f790d89d5ef682745bb8a43dbbdda64fb4275b6885a07`
MD5	`6c7294ce97823d48337b694a0d3c31b3`
BLAKE2b-256	`fda639eee70e7fe75c101ed55d570e271e9aae091e48c12ff3a70e3dc62fe3ec`

Algorithm	Hash digest
SHA256	`0ad8f7529e88909ede5d850677d6d99cd9a0daebffed0fdac577f2ba6fc7a922`
MD5	`90ccf132496eee4f982f44fa47ce16a9`
BLAKE2b-256	`8157417aa0229c07cd93dbb22da5f068f16cfc72c816be288a9cee0f106a28cb`

Algorithm	Hash digest
SHA256	`56b4a1e8f7f10d3577dd4185787f7fd52378bf3967b7b1080bc0c05cb671e384`
MD5	`8864c514b6fbd5adfcd74eedb106fdce`
BLAKE2b-256	`cae6325bcdd52770f54a8b0d6523ba7e07e1939381d82c389ce1e5e94fec661d`

Algorithm	Hash digest
SHA256	`eacfc1bb54ae7fd1c2c2aa455b7870dc6f96527cb5f98502d3a00dadd8ea0d29`
MD5	`0856ddb6b10c791a03d8e770736a427e`
BLAKE2b-256	`23447ab1b8293d2bc1cc45ea6536ba2155ed73c380cb7f25453388723d00e2cc`

Algorithm	Hash digest
SHA256	`010a12a804e742e1923a6fd2cdf4ad1036f2ffc049cc7e26dcae86e0c099db01`
MD5	`9a19b4790f6075b5ebafdc3cff2a18fd`
BLAKE2b-256	`0f870aac5030876c966e93bfe6f918414e59f0abaffa1d7b04c3aa00b004e0e6`

Algorithm	Hash digest
SHA256	`ee8e247b57929400625cc71da420f3772c0c7649fddf635f26f7aaa7a91134e0`
MD5	`b0502aecbd671870cfb86202a2d55580`
BLAKE2b-256	`82d73cade551c8e7d77dac807166b0bfe6260f602d8eefbab811d485b2774524`

Algorithm	Hash digest
SHA256	`4a2fb630fd707a3b034429ab53f5a2b0fea90070654ebfb1104b5dfd0c16c5e1`
MD5	`57ec4ca40bbfc3bf1a455ee9a63e1b46`
BLAKE2b-256	`c2ae469107327eb907318b01b897b80e0b643b6089eec3c0fb31c4c4e0242341`

Algorithm	Hash digest
SHA256	`5ad934ec057069eb69ea7a2e8fcb0d9c7683e114e633107a8ae1921d34bf8176`
MD5	`06ec2d0bd0f4a0842d805a0f9fe11266`
BLAKE2b-256	`58a262a569a008da9c8668d60714f7ce5c8a5d64dc4ebf64f6cf8174a557be93`

Algorithm	Hash digest
SHA256	`72e1b91d669cda6ea5c6638c4b3e549cbeefcad58cf4b42e7f6d5e18b26399f3`
MD5	`38826c376e70e3332472c99ce95d3cb9`
BLAKE2b-256	`6744f437064fd97cf599d091b73a2420e167a2174e3cd2ef544b4ee34f76e875`

Algorithm	Hash digest
SHA256	`019d9f980c18c87b34ddecdce2472c6f2c3c94789f58644e80a7b17ad0810e31`
MD5	`2c5fd5e2a94f370fef63cfc5ff2b24d5`
BLAKE2b-256	`338aa64b487a647765d03f61d41b836aec543ebeb1b1d0674eb9302972110ff0`

Algorithm	Hash digest
SHA256	`00a0e650a2ffabb90f389ac3afb35fb2173b3bfb0060abcfec5031f408eaeb14`
MD5	`94bc987247560bf3495b6604b708c069`
BLAKE2b-256	`61b089cf07501fda43a9b547fdea861d6f83517b594b065f4b7459283d410bb3`

Algorithm	Hash digest
SHA256	`633ba06e900918bebfe7b8718e0cd0bb782d924b2e646c0a06477e3fdb2d6f38`
MD5	`9c5a5725c8a77e3924565941c99c0bd6`
BLAKE2b-256	`6a194e63c5d64d3973345877d5578b8c124dcf1be6044a5c6d0f768e60e5f758`

axon-rag 0.4.3

Your documents, answerable. On your hardware.

🤔 Why Axon?

✨ Capabilities

🔍 Retrieval

🧠 Graph Intelligence

📥 Ingest Everything

🔧 LLMs & Embeddings

🏗️ Projects & Privacy

☁️ Cloud-Drive Sharing

🛡️ Governance & Agents

⚡ Quick Start

🔐 Sealed Sharing Quick Start

🚀 Entry Points

🔌 VS Code + GitHub Copilot

🐍 Use Axon from Your Python Agent

📚 Documentation

🔒 Security

📄 License

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance