Your LLM makes the same mistake twice.
AUA makes sure it doesn't make it three times.

# 1. Install
pip install adaptive-utility-agent

# 2. Scaffold — Mac/CPU uses Ollama; swap --tier for GPU
aua init my-aua-project --preset coding --tier macbook
cd my-project

# 3. Validate setup
aua doctor

# 4. Start
aua serve

# 5. First query (new terminal)
# Auth is disabled by default — the Authorization header is optional until you enable it
curl -s -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Write binary search in Python", "session_id": "qs-demo"}' \
  | python3 -m json.tool

# Runtime only (Ollama / CPU)
pip install adaptive-utility-agent

# GPU backend (Linux + CUDA required)
pip install "adaptive-utility-agent[vllm]"

# Dev tools — tests, linting, type checks
pip install "adaptive-utility-agent[dev]"

# Verify
aua --version
aua, version 1.0.0

aua init my-aua-project --preset coding --tier macbook
cd my-project

# See what init created
aua config expand

aua doctor                 # PASS / FAIL / WARN per check, with fixes
aua doctor --strict        # warnings as failures — use in CI
aua doctor --json          # machine-readable output

aua serve                  # start specialists + router + arbiter
aua serve --with-ui        # also start Chat UI at :3001 (see note below)
aua serve --dry-run        # print commands without executing

aua:
  version: "0.5"   # version field generated by aua init — do not edit manually
  mode: local
  backend: ollama

specialists:
  - name: swe
    model: qwen-coder-7b-awq    # registry alias → full model ID
    port: 11434
    field: software_engineering
    gpu: 0

arbiter:
  model: qwen2.5:3b
  port: 11434

router:
  port: 8000
  single_domain_threshold: 0.75
  fanout_threshold: 0.30

security:
  cors_origins: ["http://localhost:3001"]  # Chat UI port; Grafana is on :3000

state:
  backend: sqlite
  path: .aua/state/aua.db

aua models list
NAME                   PROVIDER   BACKEND   VRAM
qwen-coder-7b-awq      ollama     ollama    ~6 GB
qwen-math-7b-awq       ollama     ollama    ~6 GB
qwen-14b-awq           vllm       vllm      ~12 GB
llama3-8b              ollama     ollama    ~6 GB
...

aua models inspect qwen-coder-7b-awq

aua fields list
aua fields inspect software_engineering

curl -s -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AUA_TOKEN" \
  -d '{
    "query": "Write binary search in Python. State the time complexity.",
    "session_id": "demo-session"
  }' | python3 -m json.tool

{
  "session_id": "demo-session",
  "trace_id": "01HXYZ...",
  "request_id": "req_abc123",
  "routing_mode": "single",
  "primary_field": "software_engineering",
  "response": "...",
  "u_score": 0.641,
  "confidence": 0.76,
  "contradictions_detected": 0,
  "corrections_injected": 1,
  "latency_ms": 287.4,
  "cost_estimate_usd": 0.00012
}

aua status                 # auto-refreshing terminal UI
aua status --once          # single snapshot
aua status --json          # machine-readable

curl http://localhost:8000/status | python3 -m json.tool

# ArbiterAgent runs automatically inside aua serve.
# Use directly in Python for testing or custom workflows:
from aua import ArbiterAgent, AssertionsStore

store = AssertionsStore()
arbiter = ArbiterAgent(store)

verdict = arbiter.arbitrate(  # sync — call directly
    subject="bubble_sort_complexity",
    domain="software_engineering",
    output_A="Bubble sort is O(n) average case.",
    output_B="Bubble sort is O(n²) average case.",
    field_penalty_multiplier=2.0,
)

print(verdict.case.value)        # "case_1"
print(verdict.verified_claim)    # "Bubble sort is O(n²) average case."
print(verdict.external_response) # safe to return to user

curl -X POST http://localhost:8000/corrections \
  -H "Authorization: Bearer $AUA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "heapsort_complexity",
    "domain": "software_engineering",
    "claim": "Heapsort is O(n log n) worst-case, O(1) extra space.",
    "confidence": 0.99
  }'

blue_green:
  swe:
    delta: 0.025    # GREEN must beat BLUE by +2.5% U
    T_min: 10       # need at least 10 canary interactions
    tau: 0.20       # softmax temperature for traffic split

# Trigger blue-green promotion check via REST API
curl -X POST http://localhost:8000/deploy/green \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AUA_TOKEN" \
  -d '{"specialist": "swe", "new_model": "qwen2.5-coder:14b"}'

# Check status
aua status --once

# Roll back to previous BLUE
aua rollback --specialist swe
aua rollback --specialist swe --yes     # skip confirmation
aua rollback --no-restart               # update config only, no restart
aua rollback --all --yes                # roll back all specialists

from aua import BlueGreenDeployment
from aua.config import load_config

config = load_config("aua_config.yaml")
bg = BlueGreenDeployment(config, specialist_name="swe")

bg.register_green("models/swe-green-v2/")

import asyncio
summary = asyncio.run(bg.evaluate(n_queries=10))  # async — use asyncio.run() from sync context
print(f"GREEN U mean: {summary.green_u_mean:.3f}")
print(f"BLUE  U mean: {summary.blue_u_mean:.3f}")

if bg.should_promote(summary):
    bg.promote()
    print("GREEN promoted to BLUE")

aua config validate           # strict schema check — catches typos, dupe ports, bad ranges
aua config expand             # full resolved config with all defaults filled in (secrets redacted)
aua presets list              # list all built-in presets
aua presets inspect coding    # full preset config

aua config reload             # sends SIGHUP to running router
kill -HUP $(cat .aua/pids/router.pid)  # same effect

# Config versioning: the aua.version field tracks schema compatibility.
# v1.0 does not provide automatic migration — update config manually if upgrading.
aua config validate   # validates your config against the current schema
aua config expand     # shows full resolved config with all defaults applied

# Export all verified corrections as JSONL
aua corrections export --format jsonl

# Export as preference pairs for DPO training
aua dpo export --format preference-pairs

# With redaction (remove PII from prompts)
aua dpo export --format preference-pairs --redact

{
  "query": "bubble_sort_complexity",
  "chosen": "Bubble sort is O(n²) average case.",
  "rejected": "Bubble sort is O(n) average case.",
  "field": "software_engineering",
  "utility_chosen": 0.72,
  "utility_rejected": 0.41,
  "correction_ids": ["corr_abc123"],
  "trace_id": "01HXYZ..."
}

import asyncio
from aua import CorrectionLoop
from aua.config import load_config

config = load_config("aua_config.yaml")
loop = CorrectionLoop(config, router_url="http://localhost:8000")

async def main():
    pairs = await loop.collect_pairs(min_confidence=0.8)
    print(f"Collected {len(pairs)} pairs")
    summary = loop.export_pairs(pairs, output_dir="dpo_pairs")
    print(f"Exported to: {summary.output_path}")

asyncio.run(main())

from aua import FIELD_CONFIGS

for pair in pairs:
    cfg = FIELD_CONFIGS.get(pair.field, FIELD_CONFIGS["general"])
    loss_weight = cfg.penalty_multiplier  # 2× for SWE, 10× for surgery
    # pass loss_weight to your DPO trainer's per-sample weight

ls evals/
coding_smoke.yaml   math_smoke.yaml    routing_smoke.yaml
correction_smoke.yaml   arbiter_smoke.yaml   safety_smoke.yaml

# Run the coding smoke suite
aua eval run --dataset evals/coding_smoke.yaml --config aua_config.yaml

# View the report
aua eval report .aua/evals/latest.json

# Compare blue vs green
aua eval compare --baseline blue --candidate green

name: coding_smoke
field: software_engineering
cases:
  - id: binary_search
    prompt: "Implement binary search in Python. State time complexity."
    expected_properties:
      - "O(log n)"
      - "def binary_search"
      - correctness: true

  - id: bubble_sort_complexity
    prompt: "What is the average-case time complexity of bubble sort?"
    expected_properties:
      - "O(n²)"

aua eval report .aua/evals/latest.json

Eval run: coding_smoke  2026-05-11T14:30:22Z
Cases:     8 total · 7 passed · 1 failed
U mean:    0.638 (baseline: 0.601)  ▲ +6.2%
Regressions: 0

FAILED:
  merge_sort_stability — expected "stable" in response
  U score: 0.41 (threshold: 0.45)

- name: Run AUA eval
  run: |
    aua eval run \
      --dataset evals/coding_smoke.yaml \
      --config aua_config.yaml \
      --json > .aua/evals/ci_result.json
  # check exit code: 0 = pass, 1 = failure

node --version   # must be 18+
npm --version

# Install Node.js if missing:
brew install node          # macOS
# or download from https://nodejs.org

cd my-aua-project
aua serve --tier macbook        # Mac / Apple Silicon + Ollama
# aua serve                     # Linux / RTX 4090 + vLLM

aua ui                          # starts on http://localhost:3001
# Or combined: aua serve --tier macbook --with-ui

cd Adaptive-Utility-Agent/apps/aua_chat
npm install          # first run only
npm run dev          # starts on http://localhost:3001

# Create a session
curl -X POST http://localhost:8000/sessions \
  -H "Authorization: Bearer $AUA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-coding-session"}'

# Post a message (streaming)
curl -X POST http://localhost:8000/sessions/{id}/stream \
  -H "Authorization: Bearer $AUA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "Explain quicksort"}'

# List all sessions
curl http://localhost:8000/sessions \
  -H "Authorization: Bearer $AUA_TOKEN"

from aua.guard import assertion, AssertionLevel

# ── Guardrail: block syntax errors from ever reaching the user ─────────────
@assertion(name="PythonSyntaxCheck", level=AssertionLevel.BLOCKING)
def validate_python_syntax(output: str, context: dict) -> tuple[bool, str | None]:
    """Blocks output if any Python code block contains syntax errors."""
    import ast, re
    blocks = re.findall(r"```python(.*?)```", output, re.DOTALL)
    if not blocks:
        return True, None   # no code block — pass through
    for block in blocks:
        try:
            ast.parse(block)
        except SyntaxError as e:
            return False, f"Syntax error at line {e.lineno}: {e.msg}"
    return True, None

# ── Guardrail: soft-flag refusals without blocking ─────────────────────────
@assertion(name="NoAIisms", level=AssertionLevel.SOFT)
def no_ai_isms(output: str, context: dict) -> tuple[bool, str | None]:
    """Soft-flags common 'AI-isms' like 'as an AI language model'."""
    phrases = ["as an ai", "as a language model", "i cannot help with"]
    found = next((p for p in phrases if p in output.lower()), None)
    if found:
        return False, f"AI-ism detected: '{found}'"
    return True, None

@assertion(name="AnalogyBonus", level=AssertionLevel.INFO, bonus=0.10)
def reward_analogy(output: str, context: dict) -> tuple[bool, str | None]:
    """Rewards responses that use analogies to explain concepts."""
    phrases = ["like a", "similar to", "imagine a", "think of it as", "just like"]
    if any(p in output.lower() for p in phrases):
        return True, "Positive: analogy used for clarity"
    return True, None   # neutral — no bonus if condition not met

@assertion(name="SocraticEnding", level=AssertionLevel.INFO, bonus=0.08)
def reward_question_ending(output: str, context: dict) -> tuple[bool, str | None]:
    """Rewards responses that end with an engaging question."""
    if output.strip().endswith("?"):
        return True, "Positive: Socratic engagement"
    return True, None

@assertion(name="PythonSyntaxBonus", level=AssertionLevel.INFO, bonus=0.12)
def reward_clean_code(output: str, context: dict) -> tuple[bool, str | None]:
    """Rewards syntactically clean Python with a bonus (stack with syntax check)."""
    import ast, re
    blocks = re.findall(r"```python(.*?)```", output, re.DOTALL)
    if blocks:
        try:
            for b in blocks:
                ast.parse(b)
            return True, "Positive: clean executable Python"
        except SyntaxError:
            pass
    return True, None

from aua.policy import Policy

# Bundle guardrails + incentives into one named Policy
coding_policy = Policy(
    name="SafeCoding",
    version="1.0",
    max_retries=3,          # BLOCKING retries before giving up
    max_total_bonus=0.30,   # cap on total E bonus (Option B)
    utility_overrides={
        "w_k": 0.30,        # slightly raise curiosity weight for this policy
    }
)

# Add assertions — chaining supported
coding_policy.add(validate_python_syntax)   # BLOCKING
coding_policy.add(no_ai_isms)               # SOFT
coding_policy.add(reward_analogy)           # INFO +0.10
coding_policy.add(reward_clean_code)        # INFO +0.12

# Inspect before applying
print(coding_policy.summary())

name: SafeCoding
version: "1.0"
max_retries: 3
max_total_bonus: 0.30
assertions:
  - import_path: mypackage.policies:validate_python_syntax
    # level defaults to what's declared on the @assertion decorator
  - import_path: mypackage.policies:no_ai_isms
  - import_path: mypackage.policies:reward_analogy
    bonus: 0.10          # override decorator default
  - import_path: mypackage.policies:reward_clean_code
    bonus: 0.12
utility_overrides:
  w_k: 0.30

# Validate schema before applying
aua policy validate policies/safe_coding.yaml
# ✓ policies/safe_coding.yaml is valid

# Preview — see what would be activated
aua policy apply policies/safe_coding.yaml --dry-run

# Activate — writes pointer to .aua/active_policy
aua policy apply policies/safe_coding.yaml
# ✓ Policy activated. Restart or hot-reload to apply.

# List all policies in policies/
aua policy list

# Test a single assertion against sample output
aua guard list
aua guard test --import-path mypackage.policies:validate_python_syntax
aua guard test --import-path mypackage.policies:reward_analogy \
    --output "Think of it as a balanced binary tree."

# Run the eval harness — same as `aua eval run` but surfaced as a calibration step
aua calibrate --layer 1 --dataset evals/coding_smoke.yaml

# Use the default dataset if it exists
aua calibrate --layer 1

aua calibrate --layer 2

# Example output:
# ┌──────────────────────────┬─────────┬───────────┬───────────┬──────────────┐
# │ Domain                   │ Queries │ Pass Rate │ Avg Bonus │ Signal       │
# ├──────────────────────────┼─────────┼───────────┼───────────┼──────────────┤
# │ software_engineering     │     312 │    91.3%  │  +0.087   │ ↑ Strong     │
# │ mathematics              │     148 │    83.1%  │  +0.041   │ → Stable     │
# │ general                  │      44 │    56.2%  │     —     │ ↓ Weak       │
# └──────────────────────────┴─────────┴───────────┴───────────┴──────────────┘
# Stagnation signal: same assertions failing week over week
# → Check: is the assertion too strict? Is the model too small?

aua calibrate --layer 2 --dry-run  # preview only

# See what would be exported without writing files
aua calibrate --layer 3 --dry-run

# Example dry-run output:
# Gold-standard sessions:   47
# Failed sessions:          12
# Exportable pairs:         12
# --dry-run: would export 12 DPO pairs → dpo_pairs/calibration.jsonl

# Export when ready
aua calibrate --layer 3 --output dpo_pairs/may_calibration.jsonl

# Force export even if below min-pairs threshold
aua calibrate --layer 3 --force --output dpo_pairs/early_export.jsonl

# Fine-tune your specialist with the exported pairs:
# Axolotl:  axolotl train configs/dpo.yaml --data dpo_pairs/may_calibration.jsonl
# TRL:      trl dpo --dataset dpo_pairs/may_calibration.jsonl
# Then deploy as GREEN: curl -X POST http://localhost:8000/deploy/green

# All recent assertion events
aua logs assertions

# Filter to failures only — the assertions that need attention
aua logs assertions --filter passed=false

# Filter by assertion name
aua logs assertions --assertion PythonSyntaxCheck --tail 20

# Filter by domain
aua logs assertions --filter domain=software_engineering

# Export for offline analysis
aua logs assertions --json > my_assertions.json

# Recent sessions with U scores
aua logs sessions

# Export sessions to JSON
aua logs export --table audit_log --output sessions.json

# 1. Week 1-4: run queries with policy active, accumulate assertion events

# 2. Check Layer 2 health at any point
aua calibrate --layer 2

# 3. Review failures — add/refine assertions if the same things keep failing
aua logs assertions --filter passed=false --tail 50

# 4. End of month: export gold-standard sessions
aua calibrate --layer 3 --dry-run      # preview
aua calibrate --layer 3                # export to dpo_pairs/calibration.jsonl

# 5. Fine-tune your specialist on the exported pairs (external step)
# trl dpo --dataset dpo_pairs/calibration.jsonl

# 6. Deploy the fine-tuned model as GREEN
curl -X POST http://localhost:8000/deploy/green \
  -d '{"specialist": "swe", "new_model": "qwen2.5-coder:14b-finetuned"}'

# 7. Blue-green evaluates and promotes if U score delta passes threshold
aua status --once    # watch the promotion

# 8. Compare metrics to confirm improvement
aua metrics --compare 30d

# Repeat — each cycle, the model gets better at following your policy.
# After a few cycles, the assertions become less necessary because the
# defined behaviours are baked into the model weights.

from aua.plugins.interfaces import UtilityScorerPlugin

class RiskWeightedUtilityScorer(UtilityScorerPlugin):
    """Weights efficacy down when confidence is below threshold."""

    def __init__(self, config: dict):
        self.risk_threshold = config.get("risk_threshold", 0.80)

    def score(
        self,
        response: str,
        field: str,
        efficacy: float,
        confidence: float,
        curiosity: float,
        weights: dict,
    ) -> float:
        if confidence < self.risk_threshold:
            weights = {**weights, "efficacy": weights["efficacy"] * 0.6}
        return (
            weights["efficacy"] * efficacy
            + weights["confidence"] * confidence
            + weights["curiosity"] * curiosity
        )

plugins:
  utility_scorer:
    import_path: plugins.risk_scorer:RiskWeightedUtilityScorer
    config:
      risk_threshold: 0.85

aua extensions test \
  --kind utility_scorer \
  --import-path plugins.risk_scorer:RiskWeightedUtilityScorer

✓ Interface satisfied: UtilityScorerPlugin
✓ score() signature valid
✓ Test vector passed (U=0.612)

from aua.plugins.interfaces import ModelBackendPlugin
from typing import AsyncIterator
import httpx

class GatewayBackend(ModelBackendPlugin):
    def __init__(self, config: dict):
        self.base_url = config["base_url"]
        self.api_key = config["api_key"]

    async def complete(self, request: dict) -> dict:
        async with httpx.AsyncClient() as client:
            r = await client.post(
                f"{self.base_url}/v1/chat/completions",
                headers={"Authorization": f"Bearer {self.api_key}"},
                json=request,
            )
            return r.json()

    async def stream(self, request: dict) -> AsyncIterator[str]:
        # yield SSE chunks
        ...

    async def health(self) -> dict:
        return {"status": "ok"}

backends:
  my_gateway:
    plugin: plugins.gateway_backend:GatewayBackend
    base_url: https://api.my-gateway.internal
    api_key_secret: MY_GATEWAY_KEY  # resolved from secrets provider

aua extensions list
aua extensions inspect utility_scorer
aua extensions test --kind utility_scorer --import-path mypackage.myplugin:MyPlugin
# To pick up plugin changes: restart aua serve

from aua.plugins.interfaces import HookPlugin

class AuditHook(HookPlugin):
    hook_name = "post_arbiter"
    error_policy = "fail_open"  # don't block response if hook fails
    timeout_seconds = 2.0

    async def __call__(self, event: dict) -> dict:
        # event contains: session_id, trace_id, field, verdict, utility_scores, ...
        if event.get("verdict") == "case_4":
            await self.alert_slack(event)  # your logic here
        return event  # always return event (can mutate)

    async def alert_slack(self, event: dict):
        ...

hooks:
  - import_path: plugins.audit_hook:AuditHook
    order: 10  # lower number runs first

from aua.plugins.interfaces import AUAMiddleware

class PIIRedactionMiddleware(AUAMiddleware):
    async def before_query(self, request: dict) -> dict:
        request["prompt"] = self._redact(request["prompt"])
        return request

    async def after_response(self, response: dict) -> dict:
        # optionally mutate response
        return response

    def _redact(self, text: str) -> str:
        # your PII redaction logic
        return text

middleware:
  - plugins.pii_middleware:PIIRedactionMiddleware
  - plugins.tenant_policy:TenantPolicyMiddleware

# Create a query-only token expiring in 30 days
aua token create --scope aua:query --expires 30d

# Create an admin token
aua token create --scope aua:admin --expires 7d

# List all tokens
aua token list

# Revoke a token
aua token revoke <token-id>

export AUA_TOKEN="aua_tk_..."

curl -X POST http://localhost:8000/query \
  -H "Authorization: Bearer $AUA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "Explain quicksort", "session_id": "s1"}'

# Generate dev certs (self-signed, router + specialists + arbiter)
aua certs generate

# Inspect cert details
aua certs inspect

# Rotate certs (hot-reloaded, no restart needed)

security:
  mtls:
    enabled: true
    cert_dir: .aua/certs
    auto_generate: true    # false in production — bring your own CA

secrets:
  provider: env            # "env" | "vault" | "aws_sm" | "gcp_sm"

specialists:
  - name: swe
    api_key_secret: SWE_API_KEY    # reads env var SWE_API_KEY

secrets:
  provider: vault
  vault_addr: https://vault.internal:8200
  vault_token_secret: VAULT_TOKEN   # token from env
  vault_path_prefix: secret/aua

security:
  encryption:
    enabled: true
    key_secret: AUA_ENCRYPTION_KEY   # 64-char hex key — see §14.3 for generation

# View recent audit events (written to .aua/audit.log)
tail -f .aua/audit.log

# Export corrections (machine-readable audit trail)
aua corrections export --format jsonl

logging:
  level: INFO          # DEBUG | INFO | WARNING | ERROR
  format: json         # "json" (default) | "text" (human-readable dev mode)
  output: stdout       # "stdout" | "stderr" | "/var/log/aua/router.log"

{"ts":1747000000.12,"level":"INFO","logger":"aua.router","msg":"single→software_engineering  U=0.731","session_id":"s_abc123","trace_id":"01HX...","field":"software_engineering","routing_mode":"single","latency_ms":312.4,"utility_score":0.731,"confidence":0.823}
{"ts":1747000000.43,"level":"INFO","logger":"aua.router","msg":"Query routed","session_id":"s_abc123","trace_id":"01HX...","domain":"software_engineering","u_score":0.731,"latency_ms":315.1}

logging:
  format: json
  output: /var/log/aua/router.log    # Filebeat monitors this path

filebeat.inputs:
  - type: log
    paths: ["/var/log/aua/router.log"]
    json.keys_under_root: true     # promote JSON fields to top-level
    json.add_error_key: true

processors:
  - timestamp:
      field: ts
      layouts: ["UNIX"]
      target_field: "@timestamp"

output.elasticsearch:
  hosts: ["https://your-elastic:9200"]
  index: "aua-logs-%{+yyyy.MM.dd}"
  api_key: "your-api-key"

# All failed assertions in the last 24h
logger: "aua.router" AND level: "WARNING" AND msg: "assertion"

# Low U-score sessions (worth reviewing)
utility_score < 0.4

# All events for a specific session
session_id: "s_abc123"

# High latency queries
latency_ms > 5000

# Authentication failures
logger: "aua.auth" AND level: "WARNING"

# Arbiter fired
routing_mode: "arbiter" AND verdict: *

[monitor:///var/log/aua/router.log]
index = aua
sourcetype = aua_json

[aua_json]
KV_MODE = json
TIME_FORMAT = %s%3N
TIME_PREFIX = "ts":
MAX_TIMESTAMP_LOOKAHEAD = 20

pip install splunk-handler

from splunk_handler import SplunkHandler
import logging

logging.getLogger("aua").addHandler(
    SplunkHandler(
        host="splunk.yourcompany.com",
        port=8088,
        token="your-hec-token",
        index="aua",
        sourcetype="aua_json",
    )
)

# Failed assertions over time
index=aua sourcetype=aua_json logger="aua.router" "assertion"
| timechart count by assertion_name

# U-score trend per domain
index=aua sourcetype=aua_json utility_score=*
| timechart avg(utility_score) by field

# P95 latency by routing mode
index=aua sourcetype=aua_json latency_ms=*
| stats perc95(latency_ms) by routing_mode

curl http://localhost:8000/metrics | head -30

curl http://localhost:8000/metrics/cost | python3 -m json.tool

{
  "swe":  {"queries": 42, "gpu_hours": 0.012, "cost_usd": 0.0083},
  "math": {"queries": 18, "gpu_hours": 0.005, "cost_usd": 0.0034},
  "total_cost_usd": 0.0117
}

docker compose --profile obs up

# Grafana at http://localhost:3000 (admin / aua-admin)
# Dashboard pre-loaded: 20 panels covering query volume, latency p50/p95/p99,
# routing distribution, U score trends, contradiction rate, arbiter verdicts,
# specialist health, VRAM usage, blue-green split, assertion fail rate,
# DPO pairs accumulated, auth failures, cost per specialist

pip install "adaptive-utility-agent[otel]"

observability:
  otel:
    enabled: true
    endpoint: http://localhost:4317   # OTLP gRPC collector
    service_name: aua-router

observability:
  otel:
    enabled: true
    endpoint: https://ingest.us1.signalfx.com:443
    service_name: aua-router
    headers:
      X-SF-Token: "your-splunk-o11y-token"

services:
  aua-router:
    logging:
      driver: json-file    # Docker captures stdout as JSON
    labels:
      logging: "aua"

  alloy:
    image: grafana/alloy
    volumes:
      - /var/lib/docker/containers:/var/lib/docker/containers:ro
    # Alloy → Loki → Grafana: full log + metric correlation

# fluent-bit ConfigMap snippet
[INPUT]
    Name              tail
    Path              /var/log/containers/aua-*.log
    Parser            json
    Tag               aua.*

[OUTPUT]
    Name              es
    Match             aua.*
    Host              elasticsearch.logging.svc
    Index             aua-logs
    Type              _doc

# CPU / Ollama
docker compose up

# GPU / vLLM (requires NVIDIA runtime)
docker compose --profile gpu up

# + Prometheus and Grafana
docker compose --profile obs up

# Full local stack (Ollama + observability)
docker compose --profile ollama --profile obs up

# GPU (Linux + NVIDIA) — uses separate compose file
docker compose -f docker compose.gpu.yml up

# Option 1 — Python (no extra dependencies)
python3 -c "import os; print(os.urandom(32).hex())"

# Option 2 — OpenSSL
openssl rand -hex 32

# Either prints a 64-character hex string, e.g.:
# a3f2c1e8b7d4509261af3e2c84b19d07f6a5c3e1b8294d6072f1e3a5c8b2d490

AUA_ENCRYPTION_KEY=<64-char hex string from above>
AUA_ADMIN_TOKEN=aua_tk_...
SWE_API_KEY=...
POSTGRES_URL=postgresql://aua:password@db:5432/aua_state

security:
  mtls: {enabled: true, cert_dir: /certs, auto_generate: false}
  encryption: {enabled: true, key_secret: AUA_ENCRYPTION_KEY}
  cors_origins: ["https://your-domain.com"]

state:
  backend: postgres
  url_secret: POSTGRES_URL

audit:
  enabled: true
  hash_chain: true

aua init <name> [--preset <name>] [--tier <name>] [--force]

aua serve [--dry-run] [--tier <name>] [--reuse-running] [--with-ui] [--config <path>]

aua doctor [--strict] [--json] [--check-certs]

aua config validate [--config <path>]
aua config expand [--json]
aua config expand
aua config reload

aua models list | inspect <name>
aua fields list | inspect <name>
aua presets list | inspect <name>
aua defaults show [<category>]

aua token create --scope <scope> [--expires <duration>] [--name <label>]
aua token list [--json]
aua token revoke <token-id>
aua token inspect <token-id>

aua certs generate [--ca-cert <path>] [--ca-key <path>]
aua certs inspect

aua eval run --dataset <path> [--config <path>] [--json]
aua eval report <results.json>
aua eval compare --baseline <blue.json> --candidate <green.json>

aua corrections export --format jsonl [--redact]
aua dpo export --format preference-pairs [--redact]

aua extensions list
aua extensions inspect <name>
aua extensions test --kind <type> --import-path <path>
# Validate: aua extensions test --kind  --import-path 

aua status [--once] [--json] [--url <url>] [--refresh <seconds>]
aua rollback [--specialist <name>] [--all] [--yes] [--no-restart]

aua guard list [--json]
aua guard test --import-path <module:function> [--output <text>] [--domain <name>]

aua policy list
aua policy validate <path.yaml>
aua policy apply <path.yaml> [--dry-run]

aua calibrate --layer <1|2|3> [--force] [--dry-run] [--config <path>]
              [--dataset <path>]          # layer 1 only
              [--output <path.jsonl>]     # layer 3 only
              [--min-pairs <N>]           # layer 3 only (default: 10)

aua logs sessions [--limit <N>] [--domain <name>] [--json]
aua logs assertions [--filter <key=value>] [--assertion <name>] [--tail <N>] [--json]
aua logs export [--output <path>] [--table <table>] [--limit <N>]

aua metrics --compare <window>   # 7d, 30d, or YYYY-MM-DD:YYYY-MM-DD
            [--metric <name>]   # u_score | assertion_fail_rate | retry_rate
            [--json]

{
  "error": "AUA_SPECIALIST_TIMEOUT",     // stable AUA_* error code
  "message": "Specialist swe timed out after 30s",
  "trace_id": "01HXYZ...",
  "details": {"specialist": "swe", "timeout_seconds": 30}
}