Metadata-Version: 2.4
Name: warden-guard
Version: 0.1.0
Summary: Guardrail and evaluation framework for business-process AI agents — governs and tests action safety, not just output quality.
Project-URL: Homepage, https://github.com/warden-ai/warden
Project-URL: Source, https://github.com/warden-ai/warden
Project-URL: Issues, https://github.com/warden-ai/warden/issues
Author: Mohammad Khalaf
License: Apache-2.0
License-File: LICENSE
Keywords: action-safety,ai-act,ai-agents,audit,guardrails,human-in-the-loop,llm-eval
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: pydantic<3,>=2.6
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: typer<1,>=0.12
Provides-Extra: dev
Requires-Dist: fastapi<1,>=0.110; extra == 'dev'
Requires-Dist: httpx<1,>=0.27; extra == 'dev'
Requires-Dist: mypy<2,>=1.10; extra == 'dev'
Requires-Dist: pip-audit<3,>=2.7; extra == 'dev'
Requires-Dist: pytest-asyncio<1,>=0.23; extra == 'dev'
Requires-Dist: pytest<9,>=8.0; extra == 'dev'
Requires-Dist: ruff<1,>=0.5; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: llm
Requires-Dist: anthropic<1,>=0.40; extra == 'llm'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.0; extra == 'mcp'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.24; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.24; extra == 'otel'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]<4,>=3.1; extra == 'postgres'
Provides-Extra: slack
Requires-Dist: slack-sdk<4,>=3.27; extra == 'slack'
Provides-Extra: telegram
Requires-Dist: python-telegram-bot<22,>=21; extra == 'telegram'
Provides-Extra: webhook
Requires-Dist: fastapi<1,>=0.110; extra == 'webhook'
Requires-Dist: uvicorn<1,>=0.29; extra == 'webhook'
Description-Content-Type: text/markdown

# Warden

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

[![CI](https://github.com/warden-ai/warden/actions/workflows/ci.yml/badge.svg)](https://github.com/warden-ai/warden/actions/workflows/ci.yml)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)

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)

```bash
pip install -e ".[dev]"
```

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

```bash
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`](docs/architecture.md) and [`docs/security.md`](docs/security.md).

## Status

MVP in progress. See [`SPEC.md`](SPEC.md) for the full build specification and phasing.

## License

Apache-2.0.
