# KAOS — Kelvin Agentic Operating System

> KAOS is an open-source, MCP-native, AST-grounded Python platform for legal AI. Eighteen packages. Real provenance. Apache-2.0 licensed.

Source code: https://github.com/273v (one repo per package) · License: Apache-2.0 (open source) · Status: 18 packages on PyPI, Development Status :: 5 Production/Stable · Python ≥ 3.13

## Headline numbers (verified)

- **18 packages** — the same set the kaos-compliance dashboard tracks; one repo per package at https://github.com/273v
- **~289 MCP tools across 14 servers** (recounted from source 2026-06; re-count via `kaos status --json | jq '.tools | length'` before pinning a number)
- **34 AST node classes** in kaos-content (Block and Inline)
- **10 program types + 9 optimizers** in kaos-llm-core
- **~60 citation kinds** in kaos-citations (25 legal + 19 financial + 13 accounting + 3 identifier)
- **17 memory sections** in kaos-agents, with 6 agent patterns
- **6 planning + 7 extraction recipes** in kaos-agents — named for real legal work: contract-extraction, corpus-qa, edgar-research, federal-register-research, legal-review, summarization (planning); merger-agreement, spa-deal-points, lease, lpa, court-opinion, privilege-classification, change-of-control (extraction)
- **42 graph algorithms** in kaos-graph
- **7 LLM providers** in kaos-llm-client: OpenAI, Anthropic, Google, xAI, Groq, Mistral, OpenRouter
- **5 agentic clients** wired via `kaos setup`: Claude Code, Codex CLI, Gemini CLI, VS Code, Cursor

Verified performance anchor: `kaos-nlp-core` BM25 — typical 2-term queries complete in <600 µs over 69K USC documents (>1,600 QPS). Source: kaos-nlp-core/docs/benchmarks/README.md.

## The seven narrative truths

1. **MCP-native, not retrofitted.** KAOS types are MCP pydantic models with `to_mcp_dict()`. Designed for agents from the first commit.
2. **One AST, every source.** kaos-content's ContentDocument is the contract. PDF, DOCX, HTML, EDGAR — all produce the same typed Block/Inline tree, with provenance on every node.
3. **Provenance all the way through.** Page, bbox, char_span, confidence preserved from extraction → retrieval → LLM output (`Cited[T]`, `Answer[T]`, `GroundedAnswer[T]`) → citation verification.
4. **Open-source, license-audited, no AGPL.** pypdfium2 over PyMuPDF on purpose. License-audited embedding registry. Apache-2.0 across all 18 packages; 0 GPL/AGPL in the dependency tree (see the kaos-compliance dashboard).
5. **Three first-class consumers.** Same package, three surfaces: Python API for developers, MCP server for agents, CLI for operators and (sometimes) lawyers.
6. **Composable, not monolithic.** 18 packages with a clean dependency graph. Install kaos-pdf alone, or run `kaos serve` and get all servers in one process.
7. **Real legal grounding.** Recipes named for real legal work. Fixtures: Enron, FERC, EDGAR, FOLIO, GLEIF — public records, not toy demos.

## Packages

### kaos-core

- **Category:** Core
- **Tagline:** The MCP-native runtime every other KAOS package builds on — types, tools, VFS, artifacts, and settings.
- **MCP tools:** 10
- **Install:** `pip install kaos-core`
- **Source:** https://github.com/273v/kaos-core
- **Docs:** https://273v.github.io/learn-kaos/reference/packages/
- **Surface:** https://kelvin.legal/runtime

### kaos-content

- **Category:** Core
- **Tagline:** The canonical document AST every extractor produces and every consumer reads — 34 Block/Inline node classes, all carrying provenance.
- **MCP tools:** 17
- **Install:** `pip install kaos-content`
- **Source:** https://github.com/273v/kaos-content
- **Docs:** https://273v.github.io/learn-kaos/reference/packages/
- **Surface:** https://kelvin.legal/runtime

### kaos-mcp

- **Category:** Bridge
- **Tagline:** FastMCP bridge for the platform — expose any KAOS runtime over MCP. Ships the unified `kaos` CLI.
- **Install:** `pip install kaos-mcp`
- **Source:** https://github.com/273v/kaos-mcp
- **Docs:** https://273v.github.io/learn-kaos/reference/packages/
- **Surface:** https://kelvin.legal/runtime

### kaos-nlp-core

- **Category:** Primitives
- **Tagline:** Rust-powered NLP primitives — BM25, Punkt segmentation, string distances, Aho-Corasick, MinHash/LSH.
- **MCP tools:** 17
- **Install:** `pip install kaos-nlp-core`
- **Source:** https://github.com/273v/kaos-nlp-core
- **Docs:** https://273v.github.io/learn-kaos/reference/packages/
- **Surface:** https://kelvin.legal/search-and-retrieval

### kaos-graph

- **Category:** Primitives
- **Tagline:** Rust-powered graph engine — 42 algorithms, first-class RDF/SPARQL, knowledge graphs.
- **MCP tools:** 17
- **Install:** `pip install kaos-graph`
- **Source:** https://github.com/273v/kaos-graph
- **Docs:** https://273v.github.io/learn-kaos/reference/packages/

### kaos-pdf

- **Category:** Extraction
- **Tagline:** PDF extraction with provenance on every paragraph, table, and OCR line — plus auto re-OCR of garbled scans, via Tesseract or a local ONNX engine.
- **MCP tools:** 7
- **Install:** `pip install kaos-pdf`
- **Source:** https://github.com/273v/kaos-pdf
- **Docs:** https://273v.github.io/learn-kaos/reference/packages/
- **Surface:** https://kelvin.legal/extraction

### kaos-web

- **Category:** Extraction
- **Tagline:** Web extraction, browser automation, search, and domain intelligence — for agents.
- **MCP tools:** 45
- **Install:** `pip install kaos-web`
- **Source:** https://github.com/273v/kaos-web
- **Docs:** https://273v.github.io/learn-kaos/reference/packages/
- **Surface:** https://kelvin.legal/extraction

### kaos-office

- **Category:** Extraction
- **Tagline:** DOCX, PPTX, XLSX — read, write, and redline into the same document AST, with embedded images inlined as data URIs.
- **MCP tools:** 18
- **Install:** `pip install kaos-office`
- **Source:** https://github.com/273v/kaos-office
- **Docs:** https://273v.github.io/learn-kaos/reference/packages/
- **Surface:** https://kelvin.legal/extraction

### kaos-tabular

- **Category:** Extraction
- **Tagline:** DuckDB-powered SQL over CSV, Parquet, JSON, XLSX, and SQLite — agent-ready analytics on legal data.
- **MCP tools:** 17
- **Install:** `pip install kaos-tabular`
- **Source:** https://github.com/273v/kaos-tabular
- **Docs:** https://273v.github.io/learn-kaos/reference/packages/
- **Surface:** https://kelvin.legal/extraction

### kaos-source

- **Category:** Data
- **Tagline:** Government, financial, and forensic data sources — Federal Register, eCFR, EDGAR, GovInfo, GLEIF, PACER.
- **MCP tools:** 30
- **Install:** `pip install kaos-source`
- **Source:** https://github.com/273v/kaos-source
- **Docs:** https://273v.github.io/learn-kaos/reference/packages/
- **Surface:** https://kelvin.legal/extraction

### kaos-llm-client

- **Category:** LLM
- **Tagline:** One LLM client, many providers — async-first, streaming, retries, structured output, per-call cost estimates.
- **MCP tools:** 7
- **Install:** `pip install kaos-llm-client`
- **Source:** https://github.com/273v/kaos-llm-client
- **Docs:** https://273v.github.io/learn-kaos/reference/packages/
- **Surface:** https://kelvin.legal/llm

### kaos-llm-core

- **Category:** LLM
- **Tagline:** Typed, composable, optimizable LLM programs — signatures, codecs, optimizers, plus vision tools that OCR, describe, and classify page images. A DSPy descendant.
- **MCP tools:** 35
- **Install:** `pip install kaos-llm-core`
- **Source:** https://github.com/273v/kaos-llm-core
- **Docs:** https://273v.github.io/learn-kaos/reference/packages/
- **Surface:** https://kelvin.legal/llm

### kaos-ml-core

- **Category:** ML
- **Tagline:** Classical ML on the document AST — corpus, clustering, labeling, logistic regression, calibrated thresholds.
- **MCP tools:** 11
- **Install:** `pip install kaos-ml-core`
- **Source:** https://github.com/273v/kaos-ml-core
- **Docs:** https://273v.github.io/learn-kaos/reference/packages/

### kaos-nlp-transformers

- **Category:** ML
- **Tagline:** Dense embeddings, reranking, NLI, NER, and PII detection — Rust ONNX backend, no runtime PyTorch.
- **Install:** `pip install kaos-nlp-transformers`
- **Source:** https://github.com/273v/kaos-nlp-transformers
- **Docs:** https://273v.github.io/learn-kaos/reference/packages/
- **Surface:** https://kelvin.legal/search-and-retrieval

### kaos-citations

- **Category:** Legal
- **Tagline:** Extract, resolve, and verify legal, financial, and accounting citations — ~60 kinds, deterministic, AST-grounded.
- **MCP tools:** 3
- **Install:** `pip install kaos-citations`
- **Source:** https://github.com/273v/kaos-citations
- **Docs:** https://273v.github.io/learn-kaos/reference/packages/
- **Surface:** https://kelvin.legal/legal-intelligence

### kaos-agents

- **Category:** Agentic
- **Tagline:** Agent runtime for legal work — session memory, patterns, recipes, cost accounting, grounded findings, and tiered OCR that escalates hard scans to a vision model.
- **MCP tools:** 14
- **Install:** `pip install kaos-agents`
- **Source:** https://github.com/273v/kaos-agents
- **Docs:** https://273v.github.io/learn-kaos/reference/packages/
- **Surface:** https://kelvin.legal/agentic

### kaos-ui

- **Category:** Tooling
- **Tagline:** Scaffold KAOS apps and build agent chat UIs — six Python project templates plus a React 19 component library.
- **MCP tools:** 4
- **Install:** `pip install kaos-ui`
- **Source:** https://github.com/273v/kaos-ui
- **Docs:** https://273v.github.io/learn-kaos/reference/packages/

### kaos-names

- **Category:** Tooling
- **Tagline:** Friendly, legal-flavored handles for sessions, agents, and traces — zero dependencies, deterministic when seeded.
- **Install:** `pip install kaos-names`
- **Source:** https://github.com/273v/kaos-names
- **Docs:** https://273v.github.io/learn-kaos/reference/packages/

## Audiences

KAOS speaks to three readers, called out by name on every relevant page:

1. **Agents** — what MCP tools are exposed, what resource templates are, what error messages look like, what the auto-approval annotations are. Code blocks are JSON or `kaos doctor` output.
2. **Python developers** — what the import surface is, what the typed return shape is, what optional extras unlock. Code blocks are 6–10 lines of Python.
3. **Lawyers** (where applicable) — what legal task this enables, what the failure modes are, what fixtures the team tests against. Code blocks are CLI snippets they could plausibly run.

## Adjacent properties (linked, not duplicated)

- **github.com/273v** — canonical source code.
- **training.kelvin.legal** (or wherever kelvin-training is hosted) — live training scenarios; 35 KAOS scenarios across 5 parts plus the vibe-coder track.
- **273ventures.com** — services around KAOS (training engagements, advisory, implementation, recruiting).
- **ai4lf.com** — the conceptual minibooks (LLM Essentials for Law and Finance; Agentic AI in Law and Finance) — assigned reading every KAOS book builds on.
- **theainativefirm.com** — forthcoming book; strategic context for who is buying KAOS-built systems.
- **aleainstitute.ai** — ALEA Institute, the 501(c)(3) nonprofit open-source steward.

## What KAOS is NOT

- A SaaS product (no hosted runtime; install locally or self-host).
- A drop-in replacement for Harvey / CoCounsel / Lexis+ Protégé (those are workflow products; KAOS is the substrate).
- A wrapper around one LLM provider (kaos-llm-client speaks to seven natively).
- A general-purpose agentic framework (KAOS is legal-domain-shaped; recipes, fixtures, and resolvers are tuned to legal work).
- KL3M (KL3M is an ALEA Institute asset, not a KAOS product).