Metadata-Version: 2.4
Name: citadel-governance
Version: 0.2.2
Summary: Minimal embeddable Citadel governance kernel — hard cost enforcement + cryptographic audit evidence
Author-email: Anthony Cass <casseussergio@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://citadelsdk.com
Project-URL: Documentation, https://citadelsdk.com/docs
Project-URL: Repository, https://github.com/casss20/citadel-sdk
Keywords: governance,cost-control,audit,agent,llm
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: citadel-governance>=0.1.0
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"

# 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](../../BACKEND_SETUP.md) for local development)

## Installation

```bash
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:**

```python
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**

```python
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`.

```python
# 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:

```python
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:

```python
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:

```python
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:

```python
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:

```bash
# 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](https://github.com/casss20/citadel-sdk)** if you need those features.

## Environment Variables

```bash
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).
