Examples gallery

Every example below is a self-contained PEP 723 script. Run any of them with one command — no clone, no virtualenv:

uv run https://raw.githubusercontent.com/273v/learn-kaos/main/examples/<id>.py

Cards marked offline need no API key and run deterministically in this site’s CI. needs key marks examples that call a live LLM provider.

Golden path & getting started (10)

Extract legal citations

Pull typed, normalized legal citations out of plain text — pure-Python, deterministic.offline intro

uv run examples/citations-extract.py

Packages: kaos-citations

Author your first tool

Write, register, and execute a typed @kaos_tool on a KaosRuntime.offline intro

uv run examples/first-tool.py

Packages: kaos-core

Build a document

Build a Block/Inline ContentDocument, serialize to Markdown, read its block refs.offline intro

uv run examples/build-a-document.py

Packages: kaos-content

Offline LLM with FunctionClient

A deterministic fake model that satisfies the real client interface — free, keyless.offline core

uv run examples/functionclient-chat.py

Packages: kaos-llm-client

A typed LLM call

Declare a Signature, run a typed Call, get a validated object back — offline.offline core

uv run examples/typed-call-offline.py

Packages: kaos-llm-core, kaos-llm-client

Your first agent

A stateful chat agent that remembers across turns — run offline via FunctionClient, no key.offline advanced

uv run examples/first-agent.py

Packages: kaos-agents, kaos-llm-client, kaos-llm-core

Scaffold a full app

Generate a FastAPI + React app wired to kaos-agents — shown via offline dry-run.offline advanced

uv run examples/scaffold-app.py

Packages: kaos-ui

Verify a citation

Check that a claim's quote really appears in its source — catch a hallucinated citation.offline core

uv run examples/grounded-citations.py

Packages: kaos-llm-core

Serve tools over MCP

Mount a runtime's tools on the kaos-mcp bridge to expose them to any MCP client — offline.offline advanced

uv run examples/serve-over-mcp.py

Packages: kaos-mcp, kaos-core

Research agent with citations

Full ResearchAgent: retrieve, answer with a verified citation, or refuse — offline via FunctionClient.offline advanced

uv run examples/research-agent.py

Packages: kaos-agents, kaos-llm-client, kaos-llm-core

How-to recipes (35)

Rank text with BM25

Fast, offline lexical retrieval — rank sentences against a query the way agents retrieve context.offline intro

uv run examples/bm25-search.py

Packages: kaos-nlp-core

Friendly session handles

Generate readable, deterministic identifiers like silky-commissioner-04 for sessions and agents.offline intro

uv run examples/names-seeded.py

Packages: kaos-names

Fail over across providers

Retry on a backup LLM provider when the primary errors — same chat interface.offline core

uv run examples/provider-failover.py

Packages: kaos-llm-client

SQL over billing data

uv run examples/sql-analytics.py

Packages: kaos-tabular

Extract contract definitions

Pull the defined-terms glossary out of a contract document — the backbone of contract review.offline intro

uv run examples/contract-definitions.py

Packages: kaos-content

Read & write Office docs

Write a real DOCX then extract it back to the document AST — the one-model idea, end to end.offline core

uv run examples/office-roundtrip.py

Packages: kaos-office, kaos-content

Mini research pipeline

Retrieve, answer with a verified citation, or refuse — the research-agent contract, offline.offline advanced

uv run examples/research-over-corpus.py

Packages: kaos-nlp-core, kaos-llm-core

Extract a PDF

Turn a PDF into the document AST with kaos-pdf — self-contained (generates its own PDF), offline.offline core

uv run examples/pdf-extract.py

Packages: kaos-pdf, kaos-content

Extract a web page

Readability extraction of HTML into the document AST — boilerplate stripped, offline.offline core

uv run examples/web-extract.py

Packages: kaos-web, kaos-content

Semantic embeddings

Dense embeddings + similarity with a vendored static model — semantic, offline, no download.offline core

uv run examples/embeddings.py

Packages: kaos-nlp-transformers

Find near-duplicates

MinHash near-duplicate detection — spot contract revisions and boilerplate, offline.offline core

uv run examples/near-duplicates.py

Packages: kaos-nlp-core

Agent permissions

Allow / ask / deny tool calls with a PermissionPolicy — the agent safety boundary, offline.offline core

uv run examples/agent-permissions.py

Packages: kaos-agents

Typed module settings

ModuleSettings with env-var resolution and SecretStr redaction — the config foundation, offline.offline core

uv run examples/typed-settings.py

Packages: kaos-core

Parse an email

Parse a raw .eml into typed sender/recipients/subject/body/forensics — e-discovery, offline.offline core

uv run examples/email-forensics.py

Packages: kaos-source

Query a knowledge graph

Load RDF and run SPARQL over a legal entity/citation graph — kaos-graph, offline.offline core

uv run examples/knowledge-graph.py

Packages: kaos-graph

Cluster a corpus

Embed + k-means to group documents by topic with no labels — composes two packages, offline.offline advanced

uv run examples/cluster-documents.py

Packages: kaos-ml-core, kaos-nlp-transformers

Delegate to a sub-agent

A coordinator delegates a task to a specialist sub-agent via agent_as_tool — offline.offline advanced

uv run examples/agent-delegation.py

Packages: kaos-agents

Optimize a program

BootstrapOptimizer improves an LLM program against a metric — keeps a change only if it helps. Offline.offline advanced

uv run examples/optimize-program.py

Packages: kaos-llm-core

Pause for approval

Durable RunState lets an agent pause on a sensitive tool, wait for a human, and resume — offline.offline advanced

uv run examples/pause-resume.py

Packages: kaos-agents

Trace with OpenTelemetry

OTelHook emits standard OTel spans for an agent turn — captured offline with an in-memory exporter.offline advanced

uv run examples/export-otel.py

Packages: kaos-agents

Cap LLM cost

A Budget bounds a run by cost/tokens/trials/time and stops at the ceiling — offline.offline core

uv run examples/cap-cost.py

Packages: kaos-llm-core

Add an app template

uv run examples/add-template-kind.py

Packages: kaos-ui

Review a contract

Recall-first FindingsAgent: enumerate, filter, synthesize findings under a cost cap — the NDA review, offline.offline advanced

uv run examples/findings-review.py

Packages: kaos-agents, kaos-content, kaos-nlp-core

Parse legal citations

Recognize cases/regulations/statutes as typed Bluebook records — deterministic, offline, no key.offline core

uv run examples/parse-citations.py

Packages: kaos-citations

Chunk a document

Split text into sentence or section chunks with char-span provenance — offline.offline core

uv run examples/chunk-a-document.py

Packages: kaos-nlp-core

Triage a file before ingest

Detect format from bytes and whether a PDF needs OCR — deterministic ingestion routing, offline.offline core

uv run examples/triage-before-ingest.py

Packages: kaos-nlp-core, kaos-pdf

Selective OCR for hybrid PDFs

Classify each PDF page (text vs scanned) and route only the scanned pages to OCR/VLM — offline.offline core

uv run examples/selective-ocr.py

Packages: kaos-pdf

Redline a contract

Compare two DOCX versions into tracked changes, list revisions, and accept/reject them — offline.offline core

uv run examples/redline-contract.py

Packages: kaos-office, kaos-content

Extract entities (local NER)

Zero-shot NER pulls people/orgs/money/dates with a local ONNX model — no LLM, no key.offline core

uv run examples/extract-entities.py

Packages: kaos-nlp-transformers

Detect & redact PII

Find and redact names/emails/phones with a local PII model — private, no LLM, no key.offline core

uv run examples/detect-pii.py

Packages: kaos-nlp-transformers

Conflict checking

Fuzzy-match incoming party names against a client list (typos, punctuation) with FstSet — offline.offline core

uv run examples/conflict-check.py

Packages: kaos-nlp-core

Find money/dates (no model)

Locate sentences with money/dates/percents/durations via built-in patterns — deterministic, offline.offline core

uv run examples/find-financial-terms.py

Packages: kaos-content, kaos-nlp-core

Generate synthetic data

Generate ~180 reproducible synthetic billing entries via per-row hashed seeds (the kaos-embeddings pattern).offline core

uv run examples/generate-billing-data.py

Packages: kaos-names

Analyze billing data

Roll up synthetic billing by matter/role/UTBMS code with kaos-tabular's DuckDB engine — offline.offline core

uv run examples/analyze-billing.py

Packages: kaos-tabular, kaos-names

Contract → reusable template

Read a contract PDF, find its parties/amounts/dates with on-device NER, swap them for {{template}} fields, and redline the changes — no LLM, no key.offline core

uv run examples/contract-to-template.py

Packages: kaos-pdf, kaos-office, kaos-nlp-transformers

Legal & financial use cases (10)

Litigation triage

Classify court documents by type to route them — the litigation-automation use case.offline core

uv run examples/uc-litigation-triage.py

Packages: kaos-llm-core

UTBMS billing codes

Assign UTBMS task codes to billing narratives — pre-bill compliance.offline core

uv run examples/uc-billing-utbms.py

Packages: kaos-llm-core

Matter tagging

Tag matters with practice area for reporting — matter data tagging.offline core

uv run examples/uc-matter-tagging.py

Packages: kaos-llm-core

Complaint database

Extract parties/violation/penalty from a complaint — complaint & settlement databases.offline core

uv run examples/uc-complaint-extract.py

Packages: kaos-llm-core

Contract abstraction

Extract dates/term/renewal/law from an executed contract — post-execution tracking.offline core

uv run examples/uc-contract-abstract.py

Packages: kaos-llm-core

Credit covenants

Extract financial covenants from a credit agreement — lending analysis.offline core

uv run examples/uc-credit-covenants.py

Packages: kaos-llm-core

IPO deal terms

Extract offering terms from an S-1 — SEC EDGAR deal databases.offline core

uv run examples/uc-s1-deal-terms.py

Packages: kaos-llm-core

Expertise database

Extract practice areas/industries/languages from an attorney profile.offline core

uv run examples/uc-expertise-extract.py

Packages: kaos-llm-core

Regulatory monitoring

Filter & summarize Federal Register notices by relevance.offline core

uv run examples/uc-regulatory-monitoring.py

Packages: kaos-llm-core

Matter pricing

Estimate cost & staffing for a new matter from its scope — RFP pricing.offline core

uv run examples/uc-matter-pricing.py

Packages: kaos-llm-core

More examples (1)

Rank a graph with PageRank

Build a tiny directed graph and rank its nodes — Rust-backed, byte-for-byte stable.offline intro

uv run examples/graph-pagerank.py

Packages: kaos-graph