# Axiom

**A domain-agnostic platform framework for building federated, AI-powered operational systems.**

Axiom provides the intelligence infrastructure — LLM routing, RAG, federation, agents, CLI — that domain products build on top of. [NeutronOS](https://rsicc-gitlab.tacc.utexas.edu/ut-computational-ne/neutron-os-core) is the first domain consumer (nuclear facilities).

[![PyPI](https://img.shields.io/pypi/v/axi-platform)](https://pypi.org/project/axi-platform/)
[![Tests](https://img.shields.io/badge/tests-2270%2B-brightgreen)]()
[![Python](https://img.shields.io/pypi/pyversions/axi-platform)](https://pypi.org/project/axi-platform/)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

## Install

```bash
pip install axi-platform
```

## What Axiom Does

```
User (laptop, mobile, IDE)
    |
    v
axi chat ───> LLM Gateway ───> Qwen (self-hosted) / Claude / OpenAI
    |              |
    |              v
    |         Query Router (keyword + SLM classification + VPN check)
    |              |
    |              v
    +---------> RAG Store (pgvector) ──> local + federated knowledge
    |
    v
Agents: SCAN (signals) | TIDY (steward) | PRESS (publisher) | RIVET (releases) | TRIAGE (diagnostics)
    |
    v
Federation: Node identity | Peer discovery | Trust | .axiompack distribution
```

### Core Capabilities

| Capability | Description |
|-----------|-------------|
| **LLM Gateway** | Multi-provider routing with tier classification, VPN check, circuit breakers, audit logging |
| **RAG** | Three-tier corpus (community / organization / personal), pgvector embeddings, hybrid vector+full-text search |
| **Federation** | Ed25519 node identity, peer discovery, trust establishment, `.axiompack` portable knowledge bundles, A2A agent cards |
| **Agents** | SCAN (signal ingestion), TIDY (resource steward), PRESS (document publisher), RIVET (release management), TRIAGE (diagnostics), Neut (chat assistant) |
| **CLI** | 28+ nouns, 150+ commands via extension discovery. Noun-verb pattern: `axi <noun> <verb>` |
| **Interactive Chat** | Multi-turn tool calling, RAG grounding, streaming, approval gates, session persistence |
| **Knowledge Observatory** | Velocity, accumulation, and impact metrics across knowledge bases |
| **Call to Research** | 5-level distributed research coordination protocol |
| **SECUR-T** | Security guardian — content verification, anomaly detection, trust scoring |
| **Canary Nodes** | Federated release promotion — edge/stable channels, signed attestations, quorum-based promotion |
| **Document Publishing** | Markdown to DOCX lifecycle with provider-based generation, storage, review gates |
| **Signal Pipeline** | Ingest from voice memos, Teams, GitLab; extract structured insights; publish briefings |

## Quick Start

```bash
pip install axi-platform

# Run the onboarding wizard (provisions a local llamafile + qwen2.5:7b)
axi config

# Check platform health
axi status

# Start an interactive chat session
axi chat

# Index documents for RAG
axi rag index ./docs/

# Search the knowledge base
axi rag search "how does the cooling system work?"

# Initialize federation identity
axi federation init

# Run diagnostics
axi doctor
```

### Bundled local model

`axi config` provisions a single-binary llamafile and a local LLM
weights file in `~/.axi/llamafile/`. Default is **qwen2.5:7b** (Q4_K_M,
~4.7GB). Despite the larger weights, p50 latency is **~481ms** vs the
older Bonsai-1.7B's ~3.2s — the smaller model wasn't using the chip
efficiently.

To use a smaller model with lower verifier-task accuracy, run
`axi config --model bonsai` (1.7GB).

## Architecture

Axiom is designed as a **platform framework** — it provides generic infrastructure that domain products extend with domain-specific knowledge, agents, and tools.

```
Domain Products (e.g., NeutronOS)
    |
    | extends via extensions + domain packs
    |
Axiom Platform
    |
    +-- CLI Framework (axi)           28+ nouns via extension discovery
    +-- LLM Gateway                   Multi-provider routing + audit
    +-- RAG Engine                    pgvector, 3-tier corpus
    +-- Agent Framework               6 builtin agents
    +-- Federation Protocol            Node identity, trust, .axiompack
    +-- State Management              PostgreSQL + JSON fallback
    +-- Prompt Registry               Versioned, cacheable templates
    +-- Extension System              3-tier discovery (builtin, installed, user)
    |
PostgreSQL (pgvector)               Single database for RAG + sessions + state
```

### Deployment Progression

| Tier | Role | Infrastructure |
|------|------|---------------|
| **Local** | Development, personal RAG | Laptop, SQLite fallback |
| **Private server** | Shared LLM (GPU), team RAG | VPN, K3D, PostgreSQL |
| **HPC cluster** | Export-controlled workloads | Institutional VPN |

Nodes at any tier join the federation independently. See [execution-plan-2026.md](docs/working/execution-plan-2026.md) for the full roadmap.

## CLI Reference

```bash
# Core
axi chat                    # Interactive agent with tool calling
axi status                  # System health dashboard
axi doctor                  # AI-powered diagnostics

# Knowledge
axi rag index|search|status # RAG corpus management
axi knowledge status        # Knowledge observatory
axi research create|list    # Call to Research protocol

# Federation
axi federation init|join|leave|peers
axi nodes add|status|list   # Fleet monitoring
axi security status|alerts  # SECUR-T guardian
axi chaos run               # Resilience testing

# Operations
axi signal brief|draft      # Signal pipeline (SCAN agent)
axi pub publish|review      # Document lifecycle (PRESS agent)
axi tidy status|vitals        # Resource steward (TIDY agent)
axi release status|check    # Release management (RIVET agent)

# Infrastructure
axi connect [name]          # Manage external connections
axi db up|migrate|status    # PostgreSQL lifecycle
axi agents start|stop       # Agent service management
axi serve                   # HTTP API server
```

Full command reference: [spec-axi-cli.md](docs/specs/spec-axi-cli.md)

## Development

```bash
# Clone and install
git clone https://github.com/b-tree-labs/axiom-os.git
cd axiom
pip install -e ".[all]"

# Run tests (2,270+)
pytest

# Lint
ruff check src/ tests/
ruff format src/ tests/

# Build
python -m build
```

## Extension System

Axiom discovers CLI commands, tools, and agents from extensions via `axiom-extension.toml` manifests:

```toml
[extension]
name = "my-extension"
version = "0.1.0"
description = "What it does"

[[cli.commands]]
noun = "myext"
module = "my_extension.cli"
description = "My custom commands"
```

**Discovery tiers:**
1. Builtin (`src/axiom/extensions/builtins/`)
2. Installed PyPI packages with `axiom-extension.toml`
3. User extensions (`~/.axi/extensions/`)

## Domain Products

Axiom is domain-agnostic. Domain products add domain-specific knowledge, agents, and tools:

| Product | Package | Domain |
|---------|---------|--------|
| **NeutronOS** | [`neutron-os`](https://pypi.org/project/neutron-os/) | Nuclear facilities |
| *(your product)* | — | Any domain |

## Documentation

| Document | Description |
|----------|-------------|
| [Execution Plan 2026](docs/working/execution-plan-2026.md) | Roadmap: what gets built, in what order |
| [CLI Spec](docs/specs/spec-axi-cli.md) | Full command reference |
| [Federation Spec](docs/specs/spec-federation.md) | Multi-node protocol |
| [RAG Architecture](docs/specs/spec-rag-architecture.md) | Knowledge retrieval design |
| [Agent Architecture](docs/specs/spec-agent-architecture.md) | Agent capabilities |
| [Session Store](docs/specs/spec-session-store.md) | PostgreSQL session backend |
| [Canary Nodes](docs/specs/spec-canary-nodes.md) | Release promotion protocol |

## License

MIT License — see [LICENSE](LICENSE) file.

## Acknowledgments

Developed at The University of Texas at Austin, Department of Mechanical Engineering — Nuclear & Radiation Engineering Program. Released as open source under the MIT License with approval from UT Austin Discovery to Impact.
_Copyright (c) 2026 The University of Texas at Austin and B-Tree Labs. Apache-2.0 licensed._
