ao-kernel 4.3.1

Governed AI orchestration runtime — policy-driven, fail-closed, evidence-trail

ao-kernel

Governed AI orchestration runtime — policy-driven, fail-closed, evidence-trail.

ao-kernel is not a general-purpose agent framework or a blanket "production coding automation platform" claim. It is a governed runtime that enforces policies, records evidence, and provides deterministic LLM routing for production Python teams.

Roadmap status: A V5.0.0 Full Production Promotion Roadmap is published as a transparent program plan; it does not flip the three guard flags (support_widening, production_platform_claim, live_adapter_execution), which remain const false. Promotion authority lives in the final operator-bound supersession PR at the end of the roadmap, not in any individual epic or slice. See V5-FULL-PRODUCTION-PROMOTION-ROADMAP.md for the evidence matrix.

Installation

pip install ao-kernel                # Core (only jsonschema dependency)
pip install ao-kernel==4.3.1         # Exact stable pin
pip install ao-kernel[llm]           # LLM modules (tenacity + tiktoken)
pip install ao-kernel[mcp]           # MCP server support
pip install ao-kernel[otel]          # OpenTelemetry instrumentation
pip install ao-kernel[llm,mcp,otel]  # Everything

v4.3.1 is the current stable patch line prepared for PyPI. Post-publish verification must confirm both pip install ao-kernel and pip install ao-kernel==4.3.1 resolve to ao-kernel 4.3.1 in fresh virtual environments.

For production-grade live LLM calls, install the [llm] extra. Without it the runtime still dispatches requests, but two guarantees weaken: retry / backoff (tenacity) degrades to a single-attempt call so transient 429 / 5xx responses fail the request instead of being retried, and exact token counting (tiktoken) falls back to a heuristic estimator (~4 chars/token) so budget accounting is approximate. The core install is fully sufficient for policy evaluation, evidence replay, workflow inspection, and MCP server hosting.

ao-kernel doctor surfaces the missing extra via a tenacity/tiktoken (optional) check that shows WARN when the extra is missing. That WARN is expected on the core install and clears once you run pip install 'ao-kernel[llm]'. The same command now also prints a bundled extension truth inventory so operators can see which manifests are runtime-backed versus contract-only or quarantined candidates.

Requires Python 3.11+. POSIX-only at the moment (Windows support scheduled for a future major release; see LockPlatformNotSupported in docs/COORDINATION.md).

Quick Start

# Create workspace
ao-kernel init

# Check health
ao-kernel doctor

# Library mode (no workspace required)
from ao_kernel.config import load_default
policy = load_default("policies", "policy_autonomy.v1.json")

# LLM routing
from ao_kernel.llm import build_request, normalize_response

request = build_request(
    provider_id="openai",
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}],
    base_url="https://api.openai.com/v1/chat/completions",
    api_key="sk-...",
)

# Streaming
from ao_kernel.llm import build_request as build_req

stream_request = build_req(
    provider_id="claude",
    model="claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "Hello"}],
    base_url="https://api.anthropic.com/v1/messages",
    api_key="sk-ant-...",
    stream=True,
)

CLI Reference

Command	Description
ao-kernel init	Create .ao/ workspace
ao-kernel doctor	Workspace health check + extension truth audit
ao-kernel migrate [--dry-run] [--backup]	Version migration
ao-kernel version	Print version
ao-kernel mcp serve	Start MCP server (stdio)
ao-kernel evidence timeline --run <id>	Chronological event timeline (table or --format json)
ao-kernel evidence replay --run <id>	Inferred state trace replay (--mode inspect|dry-run)
ao-kernel evidence generate-manifest --run <id>	On-demand SHA-256 manifest
ao-kernel evidence verify-manifest --run <id>	Recompute + verify manifest integrity

Quick Demo

python3 examples/demo_review.py --cleanup

Run this from an environment where ao-kernel is already installed (wheel, venv, or editable install). The script spins up a disposable workspace and invokes python -m ao_kernel init inside that temp checkout.

Runs review_ai_flow end-to-end against a disposable workspace (git init + ao-kernel init + codex-stub deterministic adapter, no LLM required). The demo verifies the workflow completes (workflow_completed event), the review_findings artefact materializes and validates against review-findings.schema.v1.json, and the evidence timeline is emitted to .ao/evidence/workflows/<run_id>/events.jsonl.

See docs/PUBLIC-BETA.md for the support matrix (Shipped / Beta / Deferred / Known Bugs). bug_fix_flow (full patch-preview flow) stays on the roadmap — see docs/roadmap/DEMO-SCRIPT-SPEC.md. For the opt-in real-adapter benchmark path, see docs/BENCHMARK-FULL-MODE.md.

Support Boundary

Treat the repo in three layers:

• Stable shipped baseline: entrypoint/version commands, ao-kernel doctor, bundled review_ai_flow + codex-stub, examples/demo_review.py, policy command enforcement, wheel-installed packaging smoke, and documented read-only PRJ-KERNEL-API actions.
• Operator / evaluation only: benchmark docs, real-adapter runbooks, prompt experiment runbooks, and other opt-in validation paths that are intentionally outside the default deterministic CI/demo lane.
• Contract / reference inventory: bundled JSON defaults, adapter manifests, registry files, and example code such as examples/hello-llm/. Their presence in the tree is useful reference material, not blanket proof that every surface is production-ready end to end. The bundled extension inventory is especially narrow at runtime today: PRJ-HELLO is the explicit bootstrap-backed smoke path; the rest of the bundled manifests should be treated as contract inventory unless a support doc says otherwise.

Operational Docs

• docs/SUPPORT-BOUNDARY.md
• docs/OPERATIONS-RUNBOOK.md
• docs/UPGRADE-NOTES.md
• docs/ROLLBACK.md
• docs/KNOWN-BUGS.md

Python API

ao_kernel.config

Function	Description
workspace_root(override=None)	Resolve workspace (returns None in library mode)
load_default(resource_type, filename)	Load bundled JSON default
load_with_override(resource_type, filename, workspace)	Workspace override > bundled default

ao_kernel.llm

Function	Description
resolve_route(intent, ...)	Deterministic LLM routing
build_request(provider_id, model, messages, ...)	Provider-native HTTP request
normalize_response(resp_bytes, provider_id)	Extract text + usage + tool_calls
extract_text(resp_bytes)	Extract text from response
execute_request(url, headers, body_bytes, ...)	HTTP with retry + circuit breaker
stream_request(url, headers, ...)	SSE streaming with OK/PARTIAL/FAIL
get_circuit_breaker(provider_id)	Per-provider circuit breaker
count_tokens(messages, provider_id, model)	Token counting

Supported Providers

Provider	Streaming	Tool Use	Embedding
Claude	Yes	Yes	No
OpenAI	Yes	Yes	Yes
Google Gemini	Yes	No	Yes
DeepSeek	Yes	Yes	No
Qwen	Yes	Yes	No
xAI	Yes	Yes	No

AoKernelClient — Unified SDK

Full governed pipeline: route → capabilities → context → build → execute → normalize → decisions → eval → telemetry.

from ao_kernel import AoKernelClient

with AoKernelClient(workspace_root=".") as client:
    result = client.llm_call(
        messages=[{"role": "user", "content": "Hello"}],
        intent="FAST_TEXT",
    )
    print(result["text"])

MCP Server

ao-kernel runs as an MCP (Model Context Protocol) server, exposing governance tools:

ao-kernel mcp serve                          # stdio transport (default)
ao-kernel mcp serve --transport http --port 8080   # HTTP (needs ao-kernel[mcp-http])

Tools:

• ao_policy_check — Validate action against policy (allow/deny)
• ao_llm_route — Resolve provider/model for intent
• ao_llm_call — Execute governed LLM call (thin executor — see matrix below)
• ao_quality_gate — Check output quality
• ao_workspace_status — Workspace health
• ao_memory_read — Read canonical decisions + workspace facts (policy-gated, fail-closed, read-only)
• ao_memory_write — Promote a decision to canonical memory (policy-gated, fail-closed, server-side fixed confidence)

Resources:

• ao://policies/{name} — Policy JSON
• ao://schemas/{name} — Schema JSON
• ao://registry/{name} — Registry JSON

SDK vs MCP — Which one should I use?

AoKernelClient (SDK) runs the full governed pipeline. ao_llm_call (MCP) is a thin executor — by design, not a limitation. Pick the surface that matches your trust boundary.

Stage	AoKernelClient.llm_call (SDK)	MCP ao_llm_call
Route resolution (provider/model)	✅	✅
Capability gap check	✅	✅ (inside build)
Context injection (4-lane compile: session/canonical/facts/consultations)	✅	❌
Transport + retry + circuit breaker	✅	✅
Normalize (text/usage/tool_calls)	✅	✅
Decision extraction + memory loop	✅	❌
Evidence trail (JSONL)	✅	❌
Eval scorecard (diagnostic)	✅	❌
Quality gates (policy-enforced)	✅ (evaluate_quality)	✅ (ao_quality_gate)
OTEL telemetry	✅	❌

Rule of thumb:

• SDK — your own Python process runs the governed loop. Full context, full audit.
• MCP — an external agent (Claude Desktop, Cursor, your own MCP client) delegates a single LLM call through the governance boundary. Context, memory, and telemetry stay in the caller's process, not in the server.

Mixing is fine: an MCP client can call ao_policy_check and ao_quality_gate for governance decisions, run its own LLM, and call back for ao_workspace_status. The server stays thin on purpose.

Productized Local Workflows

These CLI surfaces package the governed building blocks into repeatable local workflows. They do not install GitHub Apps, call GitHub, configure Vault, configure webhooks, mutate branch protection, enable live adapter execution, or make any platform-readiness claim.

Start from the end-to-end guide: docs/PRODUCT-QUICKSTART.md.

Repo-intelligence onboarding (read-only):

ao-kernel repo onboarding template --output yaml
ao-kernel repo onboarding init-config --project-root . --path .ao/repo-intelligence.yml
ao-kernel repo onboarding doctor --project-root . --output json

The generated contract requires only GitHub App installation, explicit repository selection, and optional repo-local config. End-user Cloud Run, Vault, webhook, private-key, release-gate, and deployment-protection service setup all remain false.

PR delivery metadata UX:

ao-kernel pr-metadata generate --work-package AO-MA-10 --issue '#123'
ao-kernel pr-metadata fix --body-file pr-body.md --write --work-package AO-MA-10
ao-kernel pr-metadata validate --body-file pr-body.md --output json

The metadata block is a PR-author declaration only. Release authority remains the repo-owned ao-release-gate required check plus GitHub enforcement.

Multi-agent local run wrapper:

ao-kernel orchestration run-wrapper \
  --goal "bounded local slice" \
  --declared-spec task-001:src/a.py:"bounded write scope" \
  --dry-run

ao-kernel orchestration run-wrapper \
  --goal "bounded local slice" \
  --declared-spec task-001:src/a.py:"bounded write scope" \
  --execute-local-fixture

ao-kernel orchestration run-wrapper-async \
  --goal "bounded parallel local slice" \
  --declared-spec task-001:src/a.py:"worker one" \
  --declared-spec task-002:src/b.py:"worker two" \
  --execute-local-fixture \
  --max-workers 2

The wrapper chains plan -> spawn in dry-run mode or plan -> spawn -> invoke with the pinned deterministic local worker fixture. The async wrapper v2 emits one task graph, invokes pinned local fixtures through a bounded worker pool, collects artifacts, and reports review/verification as external evidence required rather than fabricating AI approval. Both wrappers require explicit declared write scopes and keep support_widening, production_platform_claim, and live_adapter_execution closed.

Cross-provider AI review collection:

export AO_MA10_OPENAI_REVIEW_CMD="python3 -m ao_kernel.ai_review_provider_wrappers codex"
export AO_MA10_ANTHROPIC_REVIEW_CMD="python3 -m ao_kernel.ai_review_provider_wrappers claude"
export AO_MA10_MINIMAX_REVIEW_CMD="python3 -m ao_kernel.ai_review_provider_wrappers mavis"
export AO_MA10_MAVIS_BIN="mavis"  # Optional; set to ~/.mavis/bin/mavis if not on PATH.

ao-kernel ai-review collect \
  --work-package AO-MA-10X \
  --base-ref origin/main \
  --head-ref HEAD \
  --implementer-provider openai \

ao-kernel ai-review consensus \
  --work-package AO-MA-10X \
  --base-ref origin/main \
  --head-ref HEAD \
  --implementer-provider openai \
  --max-rounds 3

ao-kernel ai-review high-risk-dry-run \
  --work-package AO-MA-10X \
  --base-ref origin/main \
  --head-ref HEAD \
  --implementer-provider openai \
  --review-evidence ai-review-artifacts/anthropic.local-ai-review-evidence.v1.json \
  --review-evidence ai-review-artifacts/minimax.local-ai-review-evidence.v1.json

The provider wrappers read the ai-review JSON request from stdin, call the local Claude, Codex, or Mavis/MiniMax runtime, extract a single review JSON object, and emit only normalized JSON on stdout. The Mavis wrapper opens a fresh one-shot Mavis session by default; operators can opt into persistent communication mode with AO_MA10_MAVIS_MODE=communication plus explicit AO_MA10_MAVIS_FROM_SESSION_ID / AO_MA10_MAVIS_TO_SESSION_ID bindings. ai-review records provider command provenance (command_argv_sha256) and prompt provenance (prompt_sha256) without storing secrets. It can collect raw reviewer evidence, run bounded cross-provider ping-pong until unanimous AGREE, and locally dry-run the high-risk ao-release-gate path. The CLI prints only a safe status/provider summary; full artifact paths and provenance are written under --output-dir. It does not make AI output release authority, mutate GitHub, widen support, claim broad readiness, or execute live adapters.

Context Management

Governed context loop — decisions extracted, scored, and injected automatically.

from ao_kernel.context import start_session, process_turn, compile_context, end_session

# Start session
ctx = start_session(workspace_root=".", session_id="my-session")

# After each LLM turn — automatic extraction + compaction
ctx = process_turn(llm_output, ctx, workspace_root=".", request_id="req-1")

# Compile context for next LLM call (relevance-scored, budget-aware)
compiled = compile_context(ctx, profile="TASK_EXECUTION", max_tokens=4000)
# compiled.preamble → inject into system prompt

# End session — compact + distill + promote
end_session(ctx, workspace_root=".")

SDK Hooks (multi-agent):

from ao_kernel.context.agent_coordination import record_decision, query_memory

record_decision(ws, key="arch.pattern", value="microservices", confidence=0.9)
items = query_memory(ws, key_pattern="arch.*")

Profiles: STARTUP (minimal), TASK_EXECUTION (full), REVIEW (quality focus)

What Makes ao-kernel Different

	ao-kernel	LangGraph	CrewAI	Pydantic AI
Policy engine	100+ policy files	No	No	No
Fail-closed	Yes	No	No	No
Evidence trail	Self-hosted JSONL	LangSmith SaaS	No	No
Migration CLI	Yes	No	No	No
Doctor	Yes	No	No	No
MCP server	Yes	No	No	No
Streaming	SSE (6 providers)	Yes	Yes	Yes

Counts as of v3.13.0: ao_kernel/defaults/ ships 377 bundled JSON files — 106 policies + 231 schemas + 19 extensions + 9 registry + 4 workflows + 3 operations + 3 adapters + 1 catalogs + 1 intent_rules. Run find ao_kernel/defaults -name '*.json' | wc -l for the live number. This is an inventory count, not a support-matrix count; use docs/PUBLIC-BETA.md for what is actually supported.

Architecture

ao_kernel/              <- Public facade (clean API)
  client.py             <- AoKernelClient — unified SDK
  llm.py                <- LLM routing, building, normalization
  governance.py         <- Policy SSOT (4 policy types, fail-closed)
  mcp_server.py         <- MCP server (7 tools, 3 resources)
  context/              <- Context pipeline (compile, inject, extract, promote)
  _internal/            <- Private implementation (do not import directly)
  defaults/             <- 377 bundled JSON (policies, schemas, registry, extensions, operations, adapters, workflows, catalogs, intent_rules)

Development

pip install -e ".[dev,llm,mcp]"          # Dev environment
pytest tests/ -x                          # Run tests
ruff check ao_kernel/ tests/              # Lint
mypy ao_kernel/ --ignore-missing-imports  # Type check

Coverage target: 70% branch coverage (excluding _internal).

License

MIT