Metadata-Version: 2.3
Name: axiom-os-lm
Version: 0.31.0
Summary: Composable and Extensible Agent Operating System for Language Models
Project-URL: Homepage, https://github.com/b-tree-labs/axiom-os
Project-URL: Repository, https://github.com/b-tree-labs/axiom-os
Project-URL: Bug Tracker, https://github.com/b-tree-labs/axiom-os/issues
Author-email: Benjamin Booth <no-reply@axiom-os.ai>
License: Apache-2.0
Keywords: ai-agents,federation,llm,platform,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Requires-Dist: alembic>=1.13
Requires-Dist: argcomplete>=3.0
Requires-Dist: croniter>=2.0
Requires-Dist: cryptography>=42.0
Requires-Dist: fastapi>=0.110
Requires-Dist: jsonschema>=4.20
Requires-Dist: psycopg2-binary>=2.9
Requires-Dist: python-dateutil>=2.8
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.28
Requires-Dist: rich>=13.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: tomlkit>=0.13
Requires-Dist: uvicorn>=0.27
Provides-Extra: all
Requires-Dist: alembic>=1.13; extra == 'all'
Requires-Dist: boto3>=1.28; extra == 'all'
Requires-Dist: filelock>=3; extra == 'all'
Requires-Dist: jsonschema>=4.20; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: moto[s3]>=5.0; extra == 'all'
Requires-Dist: pgvector>=0.2; extra == 'all'
Requires-Dist: prompt-toolkit>=3.0; extra == 'all'
Requires-Dist: psycopg2-binary>=2.9; extra == 'all'
Requires-Dist: pygithub>=2.0; extra == 'all'
Requires-Dist: pygments>=2.17; extra == 'all'
Requires-Dist: pyright>=1.1; extra == 'all'
Requires-Dist: pytest-cov>=4.0; extra == 'all'
Requires-Dist: pytest-timeout>=2.3; extra == 'all'
Requires-Dist: pytest-xdist>=3.5; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: python-docx>=1.1; extra == 'all'
Requires-Dist: python-gitlab>=4.0; extra == 'all'
Requires-Dist: ruff>=0.4; extra == 'all'
Requires-Dist: sqlalchemy>=2.0; extra == 'all'
Requires-Dist: tiktoken>=0.7; extra == 'all'
Requires-Dist: watchdog>=3.0; extra == 'all'
Provides-Extra: browser
Requires-Dist: playwright>=1.40; extra == 'browser'
Provides-Extra: calendar
Requires-Dist: google-api-python-client>=2.0; extra == 'calendar'
Requires-Dist: google-auth>=2.0; extra == 'calendar'
Provides-Extra: chat
Requires-Dist: prompt-toolkit>=3.0; extra == 'chat'
Requires-Dist: pygments>=2.17; extra == 'chat'
Provides-Extra: data-platform
Requires-Dist: dagster>=1.7; extra == 'data-platform'
Requires-Dist: dbt-core>=1.8; extra == 'data-platform'
Requires-Dist: duckdb>=1.0; extra == 'data-platform'
Requires-Dist: pyiceberg>=0.7; extra == 'data-platform'
Provides-Extra: dev
Requires-Dist: filelock>=3; extra == 'dev'
Requires-Dist: moto[s3]>=5.0; extra == 'dev'
Requires-Dist: pyright>=1.1; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: tiktoken>=0.7; extra == 'dev'
Provides-Extra: learning
Requires-Dist: dendra>=0.2.0; extra == 'learning'
Provides-Extra: m365
Requires-Dist: msal>=1.28; extra == 'm365'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: publisher
Requires-Dist: python-docx>=1.1; extra == 'publisher'
Provides-Extra: rag
Requires-Dist: psycopg2-binary>=2.9; extra == 'rag'
Requires-Dist: watchdog>=3.0; extra == 'rag'
Provides-Extra: repos
Requires-Dist: pygithub>=2.0; extra == 'repos'
Requires-Dist: python-gitlab>=4.0; extra == 'repos'
Provides-Extra: runtime
Requires-Dist: alembic>=1.13; extra == 'runtime'
Requires-Dist: boto3>=1.28; extra == 'runtime'
Requires-Dist: jsonschema>=4.20; extra == 'runtime'
Requires-Dist: mcp>=1.0; extra == 'runtime'
Requires-Dist: pgvector>=0.2; extra == 'runtime'
Requires-Dist: prompt-toolkit>=3.0; extra == 'runtime'
Requires-Dist: psycopg2-binary>=2.9; extra == 'runtime'
Requires-Dist: pygithub>=2.0; extra == 'runtime'
Requires-Dist: pygments>=2.17; extra == 'runtime'
Requires-Dist: python-docx>=1.1; extra == 'runtime'
Requires-Dist: python-gitlab>=4.0; extra == 'runtime'
Requires-Dist: sqlalchemy>=2.0; extra == 'runtime'
Requires-Dist: watchdog>=3.0; extra == 'runtime'
Provides-Extra: signal
Requires-Dist: alembic>=1.13; extra == 'signal'
Requires-Dist: pgvector>=0.2; extra == 'signal'
Requires-Dist: psycopg2-binary>=2.9; extra == 'signal'
Requires-Dist: sqlalchemy>=2.0; extra == 'signal'
Provides-Extra: storage
Requires-Dist: boto3>=1.28; extra == 'storage'
Requires-Dist: jsonschema>=4.20; extra == 'storage'
Description-Content-Type: text/markdown

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

[![PyPI](https://img.shields.io/pypi/v/axiom-os-lm)](https://pypi.org/project/axiom-os-lm/)
[![Python](https://img.shields.io/pypi/pyversions/axiom-os-lm)](https://pypi.org/project/axiom-os-lm/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)

## Install

```bash
pip install axiom-os-lm
axi config      # onboarding wizard: provisions a local llamafile + model
axi status      # platform health
axi chat        # interactive agent
```

## Architecture

```mermaid
flowchart TB
    User["User · laptop / mobile / IDE / MCP client"]
    GW["LLM Gateway<br/>tier routing · circuit breakers · audit"]
    LLM["Providers<br/>self-hosted Qwen · Claude · OpenAI · Ollama"]
    RAG["RAG<br/>pgvector · 3-tier corpus"]
    MEM["Composition Memory<br/>CompositionService · MIRIX"]
    FLEET["Agent Fleet<br/>14 builtin agents"]
    CONN["Connectors<br/>Slack · Teams · Email · M365"]
    DATA["Data Platform<br/>Bronze / Silver / Gold"]
    FED["Federation<br/>node identity · trust · A2A · .axiompack"]
    PG["PostgreSQL + pgvector<br/>schema-per-extension (ADR-052)"]

    User --> GW
    GW --> LLM
    GW --> RAG
    GW --> MEM
    GW --> FLEET
    FLEET --> CONN
    FLEET --> DATA
    FLEET --> FED
    RAG --> PG
    MEM --> PG
    DATA --> PG

    style User fill:#e3f2fd,color:#000000,stroke:#1976d2
    style GW fill:#fff3e0,color:#000000,stroke:#f57c00
    style LLM fill:#f5f5f5,color:#000000,stroke:#616161
    style RAG fill:#e8f5e9,color:#000000,stroke:#388e3c
    style MEM fill:#e8f5e9,color:#000000,stroke:#388e3c
    style FLEET fill:#f3e5f5,color:#000000,stroke:#7b1fa2
    style CONN fill:#e0f2f1,color:#000000,stroke:#00897b
    style DATA fill:#e0f2f1,color:#000000,stroke:#00897b
    style FED fill:#fff9c4,color:#000000,stroke:#f9a825
    style PG fill:#f5f5f5,color:#000000,stroke:#616161
    linkStyle default stroke:#777777,stroke-width:2px
```

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** | 14 builtin agents coordinating read → reason → act → publish (see below) |
| **Federation** | 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** | 40+ purpose-named nouns with availability-aware dispatch (ADR-047) — verbs whose backing service is unreachable are hidden, not broken |

## 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`).

| Agent | Role | Primary CLI surface |
|---|---|---|
| **AXI** | Interactive assistant + work routing | `axi chat` |
| **SCAN** | Signal ingestion & extraction (events → structured signals) | `axi signal` |
| **CURIO** | Deep research & knowledge synthesis | `axi research`, `axi knowledge` |
| **PRESS** | Document publishing & content gating | `axi publish` |
| **HERALD** | Outbound comms / multi-channel notifications | `axi notifications` |
| **TIDY** | Workspace & repo hygiene (steward) | `axi hygiene` |
| **RIVET** | CI/CD monitoring & releases | `axi release` |
| **TRIAGE** | Diagnostics & security scanning | `axi doctor`, `axi triage` |
| **GUARD** | Authorization & policy decisions | `axi audit` |
| **KEEP** | Capability tokens & secret/vault management | `axi secrets`, `axi vault` |
| **PULSE** | Scheduling & cadences | `axi schedule` |
| **PLINTH** | Data platform (medallion tiers) | `axi data` |
| **REV-U** | Review workflows | `axi review` |
| **CHALKE** | Classroom orchestration (Keplo) | `axi classroom` |

## Quick Start

```bash
pip install axiom-os-lm

axi config                              # provision local model, write config
axi status                              # health dashboard
axi chat                                # multi-turn agent with tool calling + RAG

axi rag ingest ./docs/                  # index documents into the corpus
axi rag search "how does retry work?"   # hybrid search over the knowledge base

axi connect                             # set up an external connection (Slack/M365/Box/…)
axi federation init                     # create this node's identity and join a cohort
axi doctor                              # AI-assisted diagnostics
```

### Bundled local model

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

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

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

[[extension.provides]]
kind = "cmd"        # cmd · agent · tool · service · adapter · skill · hook
noun = "myext"
entry = "my_extension.cli:main"
description = "My custom commands"
```

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/`). Scaffold one with `axi ext init <name>`; check conformance with `axi ext lint`.

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

```bash
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](CLAUDE.md) for architecture, conventions, and the load-bearing ADRs.

## Documentation

| Document | Description |
|---|---|
| [CLAUDE.md](CLAUDE.md) | Architecture, conventions, ADR index |
| [AEOS spec](docs/specs/spec-aeos-0.1.md) | Agent Extension Open Standard |
| [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 |

## Contributing

Contributions are welcome — code, extensions, docs, and good bug reports.

- **[CONTRIBUTING.md](CONTRIBUTING.md)** — setup, the house rules (TDD, AEOS,
  domain-agnostic core), the AI-assisted-contributions policy, and the DCO.
- **[GOVERNANCE.md](GOVERNANCE.md)** — how decisions get made and what we
  optimize for.
- **[SUPPORT.md](SUPPORT.md)** — where to ask questions (best-effort, volunteer-run).
- **[SECURITY.md](SECURITY.md)** — report vulnerabilities privately; supply-chain
  posture and coordinated disclosure.
- **[Code of Conduct](CODE_OF_CONDUCT.md)** — be excellent to each other.

## License

Apache-2.0 — see [LICENSE](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._
