Axiom
A domain-agnostic platform for building federated, AI-powered operational systems.
Axiom is the intelligence substrate — LLM routing, RAG, memory, an agent fleet, federation, and a self-discovering CLI — that domain products build on. Each product brings its own knowledge, agents, and tools; Axiom provides everything underneath. A domain consumer (e.g. a scientific-facility consumer) sits on top as the first layer.
Install (60 seconds)
pip install axiom-os-lm
axi config # onboarding wizard: provisions a local llamafile + model
axi status # platform health
axi chat # interactive agent
axi config provisions a single-binary llamafile and a local weights file in ~/.axi/llamafile/ so the platform runs without a cloud key. Run axi config --model <name> to choose a different bundled model; the LLM Gateway routes to self-hosted, private-network, or cloud providers per request tier.
Architecture
Harnesses and users reach the platform through one gateway; the agent fleet reasons over memory and RAG; Vega governs federation, identity, and the trust graph; the data platform carries the medallion tiers; everything persists to a single Postgres, one schema per extension (ADR-052).
Nodes join the federation independently at any tier — a laptop, a private GPU server behind a VPN, or an HPC cluster for isolated workloads. A domain product (a consumer layer) sits on top, extending the platform through AEOS extensions.
What Axiom Provides
| Capability | What it is |
|---|---|
| LLM Gateway | Multi-provider routing with tier classification, private-network checks, circuit breakers, and audit logging |
| RAG | Three-tier corpus (community / organization / personal), pgvector embeddings, hybrid vector + full-text search, grounding hooks |
| Composition Memory | MemoryFragment with immutable (T,U,A,R) provenance and the MIRIX 6-type taxonomy, behind a single CompositionService (ADR-026/027) |
| Agent Fleet | 15 builtin agents coordinating read → reason → act → publish (see below) |
| Federation (Vega) | Ed25519 node identity, peer discovery, trust graph, .axiompack portable knowledge bundles, A2A agent cards |
| Connectors | Uniform inbound/outbound connectors for Slack, Teams, Email, and Microsoft 365, with a common descriptor for adding more (ADR-068) |
| Data Platform | Medallion ingest + storage via the data_platform extension: Bronze sinks, a pgvector vector store, and a source registry (Box and more); heavier lakehouse query tiers (DuckDB / Iceberg) install via the optional [data-platform] extra |
| Scheduling & Secrets | App-level scheduler with cadences (PULSE) and a pluggable secret/vault backend (KEEP / OpenBao) |
| Extensions (AEOS) | Every capability is an extension conforming to the Agent Extension Open Standard; the CLI, MCP catalog, and agents discover them from manifests |
| CLI | 50+ purpose-named nouns with availability-aware dispatch (ADR-047) — verbs whose backing service is unreachable are hidden, not broken |
Key Concepts
A request is a chat turn
A turn enters from the CLI (axi chat) or an MCP client, an agent reads (recalls memory and retrieves grounding), reasons (the LLM Gateway classifies the request and routes it to the right tier), acts (skills and tools; any op that mutates external state passes the action guard), and publishes (appends an immutable memory fragment and delivers through HERALD). Content classified as controlled stays on a private-network model and never leaves to a cloud provider; eligibility gating applies at the same seam.
One database, one schema per extension
Extensions never construct an engine or see a DSN. They call session_for("<ext>"); the DatabaseProvider hands back a Session scoped to the extension's own Postgres schema (search_path = "<ext>, public"). One Postgres per install, schema-per-extension isolation, a guided within-extension tenancy menu (single-tenant / row-level tenant_id / schema-per-tenant), and cross-extension reads that ride the data platform rather than OLTP joins — all per ADR-052.
The Agent Fleet
Agents are LLM personas with deterministic guardrails; the CLI nouns are their purpose-named "arms and legs" (ADR-056 — axi hygiene, not axi tidy). Fifteen builtin agents ship with the platform, grouped by lane:
| Agent | Lane | Focus | Primary CLI surface |
|---|---|---|---|
| AXI | Interaction | Interactive assistant + work routing | axi chat |
| SCAN | Knowledge | Signal ingestion & extraction (events → structured signals) | axi signal |
| CURIO | Knowledge | Auto-research & corpus evaluation — quality gating, confidence learning, knowledge-pack lifecycle | agent; gates the RAG corpus |
| PRESS | Knowledge | Document lifecycle (draft → standards → publish) | axi publish |
| TIDY | Reliability & Review | Workspace & repo hygiene, service health, CI watch (steward) | axi hygiene |
| TRIAGE | Reliability & Review | AI-assisted diagnostics & self-healing | axi doctor, axi triage |
| RIVET | Reliability & Review | Release lifecycle & CI/heartbeat monitoring | axi release |
| REV-U | Reliability & Review | Multi-pass diff review | axi review |
| GUARD | Governance & Security | Authorization & policy decisions (the sole decision point) | axi audit |
| KEEP | Governance & Security | Capability-token lifecycle + credential chaining | axi vault |
| HERALD | Platform services | Outbound multi-channel notifications | axi notifications |
| PULSE | Platform services | Scheduling & cadences | axi schedule, axi calendar |
| PLINTH | Data platform | Medallion data platform (Bronze/Silver/Gold) | axi data |
| CHALKE | Classroom (Keplo) | Classroom orchestration & instructor brief | axi classroom |
| WARDEN | Vega (Federation) | Federation trust boundary — peer-state transitions, signature verification, classification policy, trust-graph queries | axi federation, axi nodes |
WARDEN is Vega's federation-governance agent (Verifier · Enforcer · Gatekeeper · Arbiter); its verdicts are deterministic and auditable. The federated research and knowledge-observatory surfaces (axi research, axi knowledge, axi security) live on the same federation extension.
Extensions (AEOS)
Everything non-core is an extension conforming to the Agent Extension Open Standard. The CLI, MCP catalog, and agents discover commands, skills, tools, and agents from an axiom-extension.toml manifest:
[extension]
name = "my-extension"
version = "0.1.0"
description = "What it does"
license = "Apache-2.0"
[[extension.provides]]
kind = "cmd" # one of eight kinds: agent · tool · cmd · service · adapter · skill · hook · prompt
noun = "myext"
entry = "my_extension.cli:main"
description = "My custom commands"
AEOS defines exactly eight capability kinds — agent, tool, cmd, service, adapter, skill, hook, prompt. CLI verbs are thin wrappers over skill functions ((params, ctx) -> SkillResult, ADR-056), so the same capability is callable from the CLI, from a peer agent over A2A, and from an external harness over MCP. Discovery tiers: builtin (src/axiom/extensions/builtins/) → installed PyPI packages → user (~/.axi/extensions/), with later tiers shadowing earlier ones for the same noun. Scaffold one with axi ext init <name>; check conformance with axi ext lint.
Where Things Live
axiom/
src/axiom/
memory/ # MemoryFragment, CompositionService, ownership, policy
vega/ # Vega (federation + identity), pre-extraction staging per ADR-031
federation/ # cohort registry, A2A, trust graph, classification; hosts WARDEN
identity/ # keypair, signatures, principals
extensions/builtins/ # the domain-agnostic builtin extensions (one dir per extension)
infra/ # gateway, orchestrator, prompt registry, DatabaseProvider (session_for)
rag/ # retrieval store, hybrid search
policy/ # scope policy engine + agent-action guard
docs/
adrs/ # Architecture Decision Records (the WHY)
prds/ # Product Requirement Documents (the WHAT)
specs/ # Technical specifications (the HOW)
papers/ working/ # published research; drafts, audits, design notes
assets/diagrams/ # rendered PNG diagrams authored in Mermaid
packages/ # sibling distributions (axiom-tests, design tokens, data-platform ext)
runtime/ # instance-specific data (gitignored)
tests/ # cross-cutting tests (extension tests live alongside their code)
vega/ is the federation and identity layer — the substrate WARDEN governs — staged inside the repo ahead of its extraction to a standalone product (ADR-031 Phase 3).
Domain Products
Axiom is domain-agnostic. Domain products add the knowledge, agents, and tools for their field:
| Product | Domain |
|---|---|
| (a domain consumer) | A scientific facility (experiment + processing lifecycle, digital twin) |
| (your product) | Any domain |
Development
git clone https://github.com/b-tree-labs/axiom-os.git
cd axiom-os
pip install -e ".[all]"
pytest # tests (TDD is the house rule)
ruff check src/ tests/ # lint
python -m build # wheel + sdist
See CLAUDE.md for architecture, conventions, and the load-bearing ADRs.
Documentation
| Document | Description |
|---|---|
| CLAUDE.md | Architecture, conventions, ADR index |
| Spec index | Every current spec, grouped by area (start at the memory stack) |
| AEOS spec | Agent Extension Open Standard |
| CLI spec | Full command reference |
| Federation spec | Multi-node protocol |
| RAG architecture | Knowledge retrieval design |
| Agent architecture | Agent capabilities |
Contributing
Contributions are welcome — code, extensions, docs, and good bug reports.
- CONTRIBUTING.md — setup, the house rules (TDD, AEOS, domain-agnostic core), the AI-assisted-contributions policy, and the DCO.
- GOVERNANCE.md — how decisions get made and what we optimize for.
- SUPPORT.md — where to ask questions (best-effort, volunteer-run).
- SECURITY.md — report vulnerabilities privately; supply-chain posture and coordinated disclosure.
- Code of Conduct — be excellent to each other.
License
Apache-2.0 — see LICENSE.
Acknowledgments
Developed at an academic institution and released as open source under Apache-2.0 with the institution's technology-transfer approval.
Copyright (c) 2026 The University of Texas at Austin and B-Tree Labs. Apache-2.0 licensed.
1 maintainer
Metadata
1 maintainer
Release files for axiom-os-lm 0.51.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| axiom_os_lm-0.51.0.tar.gz | 10.4 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| axiom_os_lm-0.51.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 16.8 MB
Release files / axiom_os_lm-0.51.0.tar.gz
| Download URL | axiom_os_lm-0.51.0.tar.gz |
|---|---|
| Size | 10.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e9fae0e3fb4a943651cd37ca1ad22dc1c913a298a02b1c4f47c0dba0eb3cf16d
|
|
BLAKE2b-256 checksum How to use checksums |
63db1b20a6d8e15715d1ee4addac02b6187e51b2d434c02d5d8f54a62c315071
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency logRelease files / axiom_os_lm-0.51.0-py3-none-any.whl
| Download URL | axiom_os_lm-0.51.0-py3-none-any.whl |
|---|---|
| Size | 6.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6633cdf95de183fd289b04c859894392333ffcbb546f6c9b559e244dafd75f26
|
|
BLAKE2b-256 checksum How to use checksums |
622d5e834a58b908b4719ffec6daad95d1b4daceb69f97516543353995844827
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency log
