Skip to content
Learn KAOS

Glossary

The terms you’ll meet across the KAOS packages and these docs. Each entry links to the concept that explains it or the example that uses it. New here? Start with what is KAOS? and the architecture.

Runtime & tools

Section titled “Runtime & tools”
  • KaosRuntime — the dependency-injection container holding tools, a virtual filesystem, artifacts, and settings; agents and MCP servers run on it. KaosRuntime.test_mode() gives an in-memory, isolated one. → why DI over globals
  • KaosTool / @kaos_tool — a typed, MCP-native unit of work; the runtime derives its input schema from your type hints. → your first tool
  • ToolResult — the typed return of a tool: .text, structured content, or a resource link, sized by the artifact ladder.
  • VFS (virtual filesystem) — KAOS’s storage abstraction; sessions and artifacts live here. The disk-backed default is a test footgun — use test_mode(). → inspect a runtime
  • Artifact — a stored, addressable blob referenced by a kaos:// URI; how large results travel. → the artifact size ladder
  • Settings resolution — the layered precedence (defaults → file → env → call) that decides a config value. → typed settings

Document model

Section titled “Document model”
  • ContentDocument — the Block/Inline AST every extractor produces; the “write once, run on everything” bet. → one document model
  • Block / Inline — structural nodes (heading, paragraph, table) vs. content within them (text, bold, link, citation). → build a document
  • Provenance — where a node came from (page, bounding box, confidence), preserved through extraction. → ingest a PDF
  • block ref — a stable address into a document (e.g. #/body/2); what a citation points at. → grounded citations
  • DocumentView — a queryable view over a ContentDocument (sentences, paragraphs, entities). → find money & dates
  • Chunk — a retrieval-sized slice of a document with a char-span back to the source. → chunk a document
  • Revision — a tracked change (insertion/deletion) surfaced from a DOCX redline; resolve with accept_all/reject_all. → redline a contract

LLM programming

Section titled “LLM programming”
  • kaos-llm-client — the transport layer: one interface over every provider. → transport vs. programming
  • FunctionClient — a client that runs a Python callable instead of an HTTP request; the deterministic offline seam that makes this whole site testable. → offline LLM
  • ModelProfile — typed capability metadata for a model (preferred over if provider == ...). → provider failover
  • Signature — a typed input/output contract for an LLM task. → typed LLM programming
  • Call — a Signature compiled into a function returning a validated, typed object. → one-liner to program
  • Program — a composition of Calls (extract → classify → summarize).
  • Codec — the JSON↔typed-object layer that validates and retries model output against a Signature.
  • Optimizer — improves a Program against a metric, keeping a change only if it helps (BootstrapOptimizer, MIPRO). → optimize a program
  • Budget — a cost/token/trial/time ceiling enforced before spend; returns a StopReason. → cap LLM cost · cost as a contract
  • Cited[T] / Span — a typed value with verifiable supporting spans; Span.verify checks a quote against its source. → grounding & verification
  • GroundedAnswer — the answer-or-refuse result of corpus QA: an Answer with claims and spans, or InsufficientEvidence. → the refusal contract

Agents

Section titled “Agents”
  • Agent — frozen agent config (instructions, model, pattern, tools); stateless and reconstructable. → agent vs. runner
  • Runner — the engine that drives an Agent over a runtime for one turn.
  • Turn loop — the 8-step structured loop a turn runs through. → the turn loop
  • Pattern — how a turn executes: chat, research, plan-execute, findings, router. → choose a pattern
  • ResearchAgent — retrieve → answer-with-verified-citation → refuse over a corpus. → a research agent
  • FindingsAgent — recall-first enumerate → filter → synthesize, under a cost cap. → review a contract
  • ReAct — the inner reason-act-observe tool loop (the agent is the outer loop).
  • Delegation / handoff — running a sub-agent as a tool, or transferring a turn to another agent. → delegate to a sub-agent
  • RunState — a serializable paused-turn snapshot for approval/resume. → pause & resume
  • SessionMemory — budgeted, sectioned context assembled per turn. → memory as context assembly
  • Hook — an observer of the event stream (logging, cost, OTel, circuit breaker). → trace with OpenTelemetry
  • PermissionPolicy — rules gating tool calls (read-only auto-allowed, destructive asked). → configure permissions
  • Span / value event — phase boundaries vs. facts in the typed event stream. → events & spans

Deterministic substrate

Section titled “Deterministic substrate”

Protocol & serving

Section titled “Protocol & serving”

Data & testing

Section titled “Data & testing”