Metadata-Version: 2.4
Name: axon-rag
Version: 0.2.1
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Dist: numpy>=1.20.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: sentence-transformers>=3.0.0
Requires-Dist: tf-keras>=2.0.0
Requires-Dist: ollama>=0.1.0
Requires-Dist: openai>=1.0.0
Requires-Dist: google-genai>=1.4.0
Requires-Dist: rank-bm25>=0.2.2
Requires-Dist: httpx>=0.25.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: uvicorn>=0.22.0
Requires-Dist: python-docx>=1.0.0
Requires-Dist: python-pptx>=0.6.18
Requires-Dist: pymupdf>=1.24.0
Requires-Dist: pypdf>=4.0.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: pyarrow>=10.0.0
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: lancedb>=0.8.0
Requires-Dist: tqdb>=0.2.1
Requires-Dist: streamlit>=1.30.0 ; extra == 'all'
Requires-Dist: chromadb>=0.4.0 ; extra == 'all'
Requires-Dist: qdrant-client>=1.7.0,<2.0.0 ; extra == 'all'
Requires-Dist: fastembed>=0.1.0,<1.0.0 ; extra == 'all'
Requires-Dist: networkx>=3.0 ; extra == 'all'
Requires-Dist: leidenalg>=0.11.0 ; extra == 'all'
Requires-Dist: igraph>=1.0.0 ; extra == 'all'
Requires-Dist: gliner>=0.2.0 ; extra == 'all'
Requires-Dist: llmlingua>=0.2.0 ; extra == 'all'
Requires-Dist: transformers>=4.20.0 ; extra == 'all'
Requires-Dist: ebooklib>=0.18 ; extra == 'all'
Requires-Dist: striprtf>=0.0.26 ; extra == 'all'
Requires-Dist: extract-msg>=0.28.0 ; extra == 'all'
Requires-Dist: chromadb>=0.4.0 ; extra == 'chroma'
Requires-Dist: pytest>=7.4.0,<8.0.0 ; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0,<1.0.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0,<5.0.0 ; extra == 'dev'
Requires-Dist: black==23.12.1 ; extra == 'dev'
Requires-Dist: ruff>=0.1.0,<1.0.0 ; extra == 'dev'
Requires-Dist: mypy>=1.5.0,<2.0.0 ; extra == 'dev'
Requires-Dist: pre-commit>=3.4.0,<4.0.0 ; extra == 'dev'
Requires-Dist: chromadb>=0.4.0 ; extra == 'dev'
Requires-Dist: deepeval>=0.21.0 ; extra == 'eval'
Requires-Dist: fastembed>=0.1.0,<1.0.0 ; extra == 'fastembed'
Requires-Dist: gliner>=0.2.0 ; extra == 'gliner'
Requires-Dist: networkx>=3.0 ; extra == 'graphrag'
Requires-Dist: leidenalg>=0.11.0 ; extra == 'graphrag'
Requires-Dist: igraph>=1.0.0 ; extra == 'graphrag'
Requires-Dist: llmlingua>=0.2.0 ; extra == 'llmlingua'
Requires-Dist: ebooklib>=0.18 ; extra == 'loaders'
Requires-Dist: striprtf>=0.0.26 ; extra == 'loaders'
Requires-Dist: extract-msg>=0.28.0 ; extra == 'loaders'
Requires-Dist: qdrant-client>=1.7.0,<2.0.0 ; extra == 'qdrant'
Requires-Dist: transformers>=4.20.0 ; extra == 'rebel'
Requires-Dist: streamlit>=1.30.0 ; extra == 'ui'
Provides-Extra: all
Provides-Extra: chroma
Provides-Extra: dev
Provides-Extra: eval
Provides-Extra: fastembed
Provides-Extra: gliner
Provides-Extra: graphrag
Provides-Extra: llmlingua
Provides-Extra: loaders
Provides-Extra: qdrant
Provides-Extra: rebel
Provides-Extra: ui
License-File: LICENSE
Summary: General-purpose open-source RAG engine with multi-LLM, hybrid retrieval, GraphRAG, and MCP support
Keywords: rag,llm,embeddings,vector-search,knowledge-base,mcp,ollama,graphrag
Author: Open Source Contributor
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: API Reference, https://github.com/jyunming/Axon/blob/main/docs/API_REFERENCE.md
Project-URL: Advanced RAG, https://github.com/jyunming/Axon/blob/main/docs/ADVANCED_RAG.md
Project-URL: AxonStore Guide, https://github.com/jyunming/Axon/blob/main/docs/AXON_STORE.md
Project-URL: Code RAG Guide, https://github.com/jyunming/Axon/blob/main/docs/CODE_RAG_GUIDE.md
Project-URL: Documentation, https://github.com/jyunming/Axon/tree/main/docs
Project-URL: Getting Started, https://github.com/jyunming/Axon/blob/main/docs/GETTING_STARTED.md
Project-URL: Governance Console, https://github.com/jyunming/Axon/blob/main/docs/GOVERNANCE_CONSOLE.md
Project-URL: Homepage, https://github.com/jyunming/Axon
Project-URL: Issue Tracker, https://github.com/jyunming/Axon/issues
Project-URL: MCP Tools, https://github.com/jyunming/Axon/blob/main/docs/MCP_TOOLS.md
Project-URL: Offline Guide, https://github.com/jyunming/Axon/blob/main/docs/OFFLINE_GUIDE.md
Project-URL: Release Notes, https://github.com/jyunming/Axon/releases
Project-URL: Repository, https://github.com/jyunming/Axon
Project-URL: Security, https://github.com/jyunming/Axon/blob/main/SECURITY.md
Project-URL: Setup Guide, https://github.com/jyunming/Axon/blob/main/docs/SETUP.md

  Axon

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.

  [![PyPI version](https://img.shields.io/pypi/v/axon-rag.svg)](https://pypi.org/project/axon-rag/)
  [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
  [![CI](https://github.com/jyunming/Axon/actions/workflows/ci.yml/badge.svg)](https://github.com/jyunming/Axon/actions/workflows/ci.yml)
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/jyunming/Axon/blob/main/LICENSE)
  [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

---

  Axon REPL startup

---

## 🤔 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

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

Local inference uses [Ollama](https://ollama.com). Cloud providers (OpenAI, Gemini, Grok, vLLM, GitHub Copilot) work via API keys.

**[→ Full installation guide with VS Code, MCP, and cloud provider setup](https://github.com/jyunming/Axon/blob/main/docs/GETTING_STARTED.md)**

---

## 🚀 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

  Axon Copilot integration

  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 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 →](https://github.com/jyunming/Axon/blob/main/docs/SETUP.md)**

---

## 📚 Documentation

**Getting started**

| | Guide | What it covers |
|-|-------|---------------|
| 🚀 | **[Getting Started](https://github.com/jyunming/Axon/blob/main/docs/GETTING_STARTED.md)** | First-time walkthrough — ingest, query, settings |
| ⚙️ | **[Setup Guide](https://github.com/jyunming/Axon/blob/main/docs/SETUP.md)** | Install, models, VS Code extension, MCP connection |
| 🔧 | **[Troubleshooting](https://github.com/jyunming/Axon/blob/main/docs/TROUBLESHOOTING.md)** | Common errors and platform-specific fixes |

**Reference**

| | Guide | What it covers |
|-|-------|---------------|
| 🔑 | **[Admin Reference](https://github.com/jyunming/Axon/blob/main/docs/ADMIN_REFERENCE.md)** | Every endpoint, REPL command, CLI flag, and config option |
| ⚡ | **[Quick Reference](https://github.com/jyunming/Axon/blob/main/docs/QUICKREF.md)** | Commands and flags at a glance |
| 📡 | **[API Reference](https://github.com/jyunming/Axon/blob/main/docs/API_REFERENCE.md)** | Full REST endpoint reference with request/response schemas |
| 🔌 | **[MCP Tools](https://github.com/jyunming/Axon/blob/main/docs/MCP_TOOLS.md)** | All 31 MCP tool signatures with parameter defaults |

**Deep dives**

| | Guide | What it covers |
|-|-------|---------------|
| 🤖 | **[Model Guide](https://github.com/jyunming/Axon/blob/main/docs/MODEL_GUIDE.md)** | Choosing LLM and embeddings; per-provider config examples |
| 🔬 | **[Advanced RAG](https://github.com/jyunming/Axon/blob/main/docs/ADVANCED_RAG.md)** | HyDE, RAPTOR, GraphRAG, CRAG-Lite — how each technique works |
| 🌐 | **[Web Search](https://github.com/jyunming/Axon/blob/main/docs/WEB_SEARCH.md)** | Brave Search integration, CRAG-Lite fallback setup |
| 🏝️ | **[Offline / Air-gap Guide](https://github.com/jyunming/Axon/blob/main/docs/OFFLINE_GUIDE.md)** | Full air-gap setup, model pre-download, local-assets-only mode |
| 💻 | **[Code RAG Guide](https://github.com/jyunming/Axon/blob/main/docs/CODE_RAG_GUIDE.md)** | Code graph retrieval and structural search |
| 🤝 | **[AxonStore](https://github.com/jyunming/Axon/blob/main/docs/AXON_STORE.md)** | Multi-user sharing, revocation, and the lease lifecycle |
| 📊 | **[Governance Console](https://github.com/jyunming/Axon/blob/main/docs/GOVERNANCE_CONSOLE.md)** | Audit trail, maintenance runbook, session management |
| 📈 | **[Evaluation Guide](https://github.com/jyunming/Axon/blob/main/docs/EVALUATION.md)** | RAGAS metrics, running evals, building testsets |
| 🛠️ | **[Development Guide](https://github.com/jyunming/Axon/blob/main/docs/DEVELOPMENT.md)** | Tests, contributing, pre-commit hooks |
| 📦 | **[Packaging & Release](https://github.com/jyunming/Axon/blob/main/docs/packaging_release.md)** | 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](https://github.com/jyunming/Axon/blob/main/SECURITY.md).

## 📄 License

MIT — see [LICENSE](https://github.com/jyunming/Axon/blob/main/LICENSE).


