warden-guard 0.1.0

Guardrail and evaluation framework for business-process AI agents — governs and tests action safety, not just output quality.

Warden

Guardrails and evaluation for AI agents that take real actions against real systems — not chatbots that only produce text.

Existing LLM eval tools (promptfoo, deepeval, langsmith) score output quality. Warden governs and tests action safety — what an agent is about to do to a system of record (ERP, accounting, email, internal APIs), before it does it, with a tamper-evident audit trail afterwards.

Naming: working name is warden; published as warden-guard on PyPI (the bare name was taken). Import path stays import warden.

The problem

An agent wired to your ERP is one hallucinated tool call away from deleting last quarter's invoices or emailing a customer the wrong balance. You can't unit-test that with a prompt-quality scorer. Warden puts a gateway between the agent and the system: every proposed action is validated, risk-classified, checked against policy, optionally routed to a human, and logged — then allowed, blocked, sanitized, or held.

The single architectural idea: the agent never touches the target system directly. Everything routes through the gateway. Guardrails (runtime) and eval (offline) share the same ProposedAction model and the same policy engine — so the guarantees you demo in production are the same ones your CI suite proves.

Quickstart (30 seconds)

pip install -e ".[dev]"

from warden import Operation
from warden.gateway import Gateway, guard
from warden.policy import load_policies, PolicyEngine

engine = PolicyEngine(load_policies("policies/builtin.yaml"))
gateway = Gateway(engine)

@guard(gateway, tool_name="odoo.create_invoice", target="odoo-prod",
       operation=Operation.CREATE, agent_id="billing-bot")
def create_invoice(**payload):
    ...  # only ever called on ALLOW

# A DELETE against prod with no explicit ALLOW policy is escalated/blocked,
# never silently executed.

Run the eval suite (CI-gating):

warden eval scenarios/
warden audit verify

Core principles

1. Fail-closed. Validation error, engine exception, approver timeout, audit-write failure → BLOCK. No code path allows an uncertain action.
2. Default-deny for destructive ops. DELETE / EXTERNAL_SEND / EXECUTE need an explicit ALLOW or they escalate to human approval.
3. The audit log is the spine. Every action that reaches the gateway produces exactly one hash-chained audit record — including blocked and errored ones.
4. Eval can never cause real side effects. Eval mode is hard-isolated from production connectors.
5. Policies are data, the engine is code. Add rules in YAML or Python without touching the engine.
6. Secrets never enter policies, logs, or audit records. Redaction runs before persistence.
7. Idempotent approvals. An approval resolves at most once; replays are rejected.

Architecture

                        ┌──────────────────────────────────────────────┐
   Agent (LLM + tools)  │                  WARDEN                       │
                        │                                              │
  "create invoice" ───► │  Gateway.check(ProposedAction)               │
                        │     │                                        │
                        │     ▼                                        │
                        │  Decision Pipeline                           │
                        │   1. validate (pydantic)      [fail-closed]  │
                        │   2. classify risk tier                      │
                        │   3. evaluate policies (priority order)      │
                        │   4. resolve outcome                         │
                        │   5. if REQUIRE_APPROVAL → Approver (await)  │
                        │   6. write AuditRecord (always)              │
                        │     │                                        │
                        │     ▼                                        │
                        │  Decision {ALLOW│BLOCK│SANITIZE│...}         │
                        └─────┬────────────────────────────────────────┘
                              │ ALLOW / sanitized payload
                              ▼
                        Target system (Odoo, mail, API)   ◄── only reached on ALLOW

See docs/architecture.md and docs/security.md.

Status

MVP in progress. See SPEC.md for the full build specification and phasing.

License

Apache-2.0.