citadel-governance 0.2.2

Minimal embeddable Citadel governance kernel — hard cost enforcement + cryptographic audit evidence

Citadel Kernel — Minimal Governance for AI Agents

Early Alpha (0.1.0) — Hard cost enforcement + cryptographic decision audit evidence.

A lightweight, embeddable governance kernel for agent frameworks. Zero dashboard, orchestration, or billing baggage. Just two wedges:

1. Pre-execution cost blocking — estimate LLM cost, check budgets, BLOCK before the API call if exceeded
2. Cryptographic audit evidence — export decision bundles with tamper-evident hash chains for regulatory review

Prerequisites

• Python 3.10+
• A running Citadel runtime backend (see BACKEND_SETUP.md for local development)

Installation

pip install citadel-kernel

Note: Early alpha. API may change. Pricing tables are hardcoded and will drift with provider updates.

Quickstart

Both wedges in 10 lines:

import citadel_kernel as ck; import asyncio
async def main():
    client = ck.KernelClient(base_url="https://api.citadelsdk.com", api_key="sk_your_key_here")
    result = await client.execute(action="llm.generate", provider="anthropic", model="claude-opus-4-7", input_tokens=10000, output_tokens=2000)
    print(f"Wedge A (Cost Blocking): {result.status}")
    evidence = await client.export_evidence(result.action_id)
    verified = await client.verify_evidence(result.action_id)
    print(f"Wedge B (Audit Evidence): {verified['verified']}")
    await client.close()
asyncio.run(main())

Full Example

import citadel_kernel as ck
import asyncio

async def main():
    client = ck.KernelClient(
        base_url="https://api.citadelsdk.com",
        api_key="sk_your_key_here",
        actor_id="my-agent",
    )

    # Wedge A: Hard cost enforcement blocks before API call
    result = await client.execute(
        action="llm.generate",
        resource="anthropic:claude",
        provider="anthropic",
        model="claude-opus-4-7",
        input_tokens=10_000,
        output_tokens=2_000,
    )

    if result.status == "executed":
        print("Cost was within budget, action executed")
    elif result.status == "spend_limit_exceeded":
        print(f"Blocked: {result.reason}")

    # Wedge B: Cryptographic audit evidence
    evidence = await client.export_evidence(result.action_id)
    print(f"Evidence exported (hash: {evidence['root_hash'][:16]}...)")

    verified = await client.verify_evidence(result.action_id)
    print(f"Evidence verified: {verified['verified']}")

    await client.close()

asyncio.run(main())

Cost Estimation

The kernel automatically estimates cost from provider + model + token counts.

Note (Early Alpha): Pricing is hardcoded from April 2026 Anthropic rates. For production, update pricing tables in apps/runtime/citadel/commercial/cost_estimator.py or use explicit projected_cost_cents.

# Kernel estimates cost from Anthropic pricing tables
result = await client.execute(
    action="llm.generate",
    resource="anthropic:claude",
    provider="anthropic",
    model="claude-opus-4-7",
    input_tokens=10_000,
    output_tokens=2_000,
)

Or provide explicit cost in cents:

result = await client.execute(
    action="llm.generate",
    resource="anthropic:claude",
    projected_cost_cents=1000,  # $10.00
)

Budget Enforcement

Configure budgets via the Citadel dashboard. The kernel checks against:

• Tenant budgets — entire organization spending limits
• Project budgets — per-project caps
• Agent budgets — per-agent caps
• API key budgets — per-key caps

If any budget with block enforcement would be exceeded, the kernel returns spend_limit_exceeded before the LLM call is made.

Audit Evidence

Export decision evidence for regulatory review:

evidence = await client.export_evidence(decision_id)

# Returns:
{
  "decision_id": "dec-abc123",
  "action_id": "act-xyz789",
  "status": "executed",
  "winning_rule": "policy_allow",
  "reason": "Budget check passed",
  "created_at": "2026-04-29T12:34:56Z",
  "policy_snapshot_id": "snap-def456",
  "audit_events": [
    {
      "event_id": 1,
      "event_type": "action_received",
      "actor_id": null,
      "payload": {...},
      "event_ts": "2026-04-29T12:34:56Z"
    },
    ...
  ],
  "root_hash": "a7f3b2c9d1e4..."  # SHA256 over all events
}

Verify the evidence hasn't been tampered with:

verified = await client.verify_evidence(decision_id)
# Returns: {"decision_id": "...", "verified": true, "root_hash": "...", "event_count": 5}

Module-Level API

Use the default client without instantiating:

import citadel_kernel as ck

result = await ck.execute(
    action="llm.generate",
    resource="anthropic:claude",
    provider="anthropic",
    model="claude-opus-4-7",
    input_tokens=10_000,
    output_tokens=2_000,
)

evidence = await ck.export_evidence(result.action_id)

The default client uses environment variables:

• CITADEL_URL — API base URL (defaults to http://localhost:8000)
• CITADEL_API_KEY — API key for authentication
• CITADEL_ACTOR_ID — Actor identifier (defaults to "default")

E2E Verification

Verify both wedges work correctly with the standalone test script at the repository root:

# From the repository root
PYTHONPATH=apps/runtime:. python verify_wedge_e2e.py

This runs without database or API server, using mock collaborators to verify:

• Wedge A: Hard cost enforcement blocks actions before execution
• Wedge B: Cryptographic audit evidence is tamper-evident and exportable

What's NOT Included

This kernel does not include:

• Dashboard UI (no web interface)
• Orchestration runtime (no multi-step workflows)
• Billing adapters (no Stripe integration)
• Telemetry (no OpenTelemetry)
• Advanced trust scoring (no agent reputation system)
• Multi-tenant management UI

Use the full Citadel SDK if you need those features.

Environment Variables

CITADEL_URL=https://api.citadelsdk.com
CITADEL_API_KEY=sk_your_key_here
CITADEL_ACTOR_ID=my-agent

Documentation

• Quickstart: https://citadelsdk.com/docs
• Cost Estimation: https://citadelsdk.com/docs/cost-estimation
• Audit Evidence: https://citadelsdk.com/docs/audit-evidence
• Budget Configuration: https://citadelsdk.com/docs/budgets

License

citadel-kernel is Apache License 2.0 — fully open source.

The SDK depends on citadel-governance (also Apache 2.0). If you self-host the Citadel runtime backend (apps/runtime/), that code is Business Source License 1.1 (self-host and modify freely, but no competing hosted service without a license agreement).