trustwarden 0.1.0__tar.gz

trustwarden-0.1.0/.cursor/mcp.json

@@ -0,0 +1,19 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@upstash/context7-mcp"
+      ]
+    },
+    "shadcn": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "shadcn@latest",
+        "mcp"
+      ]
+    }
+  }
+}

trustwarden-0.1.0/.cursor/rules/efficiency.mdc

@@ -0,0 +1,20 @@
+---
+description: Work efficiently with few tokens
+alwaysApply: true
+---
+
+# Efficiency
+
+- Read only the files you need; search before opening; never print whole large files.
+- Make focused edits; do not rewrite files that only need a small change.
+- Prefer established libraries and generators over writing boilerplate by hand.
+- Look up current library APIs with the Context7 MCP server instead of guessing.
+- Verify by running the commands, not by reasoning about them.
+- Never run anything that does not exit on its own in the foreground (`next start`,
+  `npm run dev`, `uvicorn`, `vite`, watch modes): it blocks you until your time runs out.
+  To try a server, start it, check it and stop it in ONE command, with a time limit:
+  `timeout 120 npx next start -p 3999 > /tmp/server.log 2>&1 & pid=$!; for i in $(seq 40);
+  do curl -sf -m 3 http://127.0.0.1:3999/api/health && break; sleep 1; done; <your curl
+  checks>; kill $pid`. Use port 3999, never 8765 (the Factory's own check uses it). Run
+  tests once, never in watch mode (`vitest run`, `CI=1`).
+- Keep your final summary short: what changed and what was verified.

trustwarden-0.1.0/.cursor/rules/engineering.mdc

@@ -0,0 +1,30 @@
+---
+description: Kaisen Factory engineering standards
+alwaysApply: true
+---
+
+# Engineering standards
+
+- Production quality, not a prototype: every feature works end to end (UI, API, database),
+  with validation, error handling, loading and empty states.
+- Layout: `frontend/` (the web app) and the backend API served under `/api` (see AGENTS.md).
+  Keep modules small and named by what they do. Shared types between layers where the stack
+  allows it.
+- Data: model the domain properly (relations, indexes, timestamps, ownership per user/team).
+  Seed realistic demo data so the product is meaningful on first login.
+- Serverless startup must be fast (the backend runs as a function that cold-starts): never
+  run a chain of database calls before serving. Create indexes concurrently (e.g.
+  `asyncio.gather` / `Promise.all`) and at most once per process, and keep `/api/health`
+  independent of index creation. No work at import time beyond building the app.
+- Authentication is mandatory: every application has accounts with JWT authentication
+  (sign-up, sign-in, sign-out, the current user; tokens signed with `JWT_SECRET`, with an
+  expiry), and every non-public endpoint and page requires a valid token.
+- Security: hash passwords (bcrypt/argon2), sign tokens with `JWT_SECRET`, check authorisation
+  on every endpoint (users only see their own or their team's data), validate all input,
+  never log or return secrets, never commit `.env` (only `.env.example` with names).
+- Configuration comes only from environment variables (names in AGENTS.md); never hardcode
+  their values.
+- Tests: unit tests for logic and API tests for every endpoint, including auth failures.
+  Never delete or weaken tests to make them pass.
+- Before finishing a task, run the install, lint, typecheck, test and build commands from
+  AGENTS.md and fix what fails.

trustwarden-0.1.0/.env.example

@@ -0,0 +1,2 @@
+# PyPI: published package name for this project (set by the Factory; do not commit real .env)
+PYPI_PACKAGE_NAME

trustwarden-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Environment and secrets
+.env
+.env.*
+!.env.example
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+wheels/
+*.egg-info/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Tooling
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+.cache/
+
+# Editors / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store

trustwarden-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

trustwarden-0.1.0/AGENTS.md

@@ -0,0 +1,50 @@
+# TrustWarden — Guarding your tools with certainty.
+
+Built autonomously by Kaisen Factory. This file and `.cursor/rules` are generated by the Factory; keep them. `README.md` is the application's documentation, written in the plan's documentation task and kept current by every change; the Factory maintains the part between `<!-- kaisen-factory:live -->` markers (live URLs, owner account).
+
+## Product
+A production-ready Python security library that propagates trust labels from tool outputs into subsequent calls, evaluates declared policies before sensitive tools run, and provides a runnable attack simulator to test enforcement.
+
+- Domain: AI agent security and developer tools
+- Core: Track trust and sensitivity labels across wrapped Python tool calls, then evaluate policy before sensitive actions execute.
+- Features (all of them must be fully implemented):
+  - Typed decorator and adapter API for wrapping Python tools without requiring a specific agent framework.
+  - Trust-label propagation for tool outputs, with explicit APIs for marking user input, trusted instructions, and sensitive values.
+  - Pre-execution policies for data exposure, destinations, and state-changing actions, with configurable allow, block, or escalate decisions.
+  - Optional LLM-assisted review for policy-defined ambiguous cases; deterministic rules remain available without an LLM.
+  - Safe-by-default handling of unknown labels and policy errors, with explicit configuration for fail-closed behavior.
+  - Local attack simulator with realistic malicious tool outputs, expected outcomes, and policy regression tests.
+  - Structured, secret-redacted decision records and hooks for applications to export events to their own logging systems.
+  - Framework-neutral core, compatibility adapters, typed interfaces, versioned policy formats, and comprehensive documentation and examples.
+
+## Brand
+- Name: TrustWarden
+- Tagline: Guarding your tools with certainty.
+- Colours: primary `#003366`, accent `#FFCC00`
+- Logo: `frontend/public/logo.svg` (also `frontend/public/favicon.svg`)
+
+## Stack
+- Frontend: -; backend: -; database: -; vector database: -
+- Install: `uv sync`
+- Lint: `uv run ruff check .`
+- Typecheck: `uv run mypy src`
+- Test: `uv run pytest`
+- Build: `uv build`
+
+## Third-party services: each user brings their own keys
+Add an external service only when a feature truly needs it. The application is multi-tenant: every user (or workspace) connects **their own** account or API key for it (Slack, Stripe, Notion, an email provider, …), never a shared key of the owner:
+- A Connections/Integrations page in the user's settings: paste a key, token or webhook URL; test it with one harmless call before saving; show it masked (last 4 characters); allow replace and disconnect.
+- Store each credential encrypted at rest (AES-GCM, e.g. Fernet) in the user's or workspace's own record, with a key derived from `JWT_SECRET` via HKDF (info `tenant-credentials`); never return it to the browser, log it or send it to another tenant; every call uses the current tenant's credential.
+- A feature whose service the user has not connected shows a clear "connect <service> in Settings" state; nothing crashes.
+- Prefer services that work with a pasted key or webhook URL. Only when a service requires an OAuth app (a client ID and secret registered once for the whole application), treat that app credential as an owner key (below); each user's OAuth tokens are still stored per tenant as above.
+- A Python package takes credentials from its caller (arguments or the caller's own environment variables), never bundles one.
+
+## Keys the owner provides (rare: application-wide credentials only)
+For an application-wide credential that cannot be per user (an OAuth app's client ID and secret):
+- Read its key from an environment variable and declare it in `.env.example` of the part that uses it (a key the browser needs: the frontend's, prefixed `VITE_`), with a comment line right above: `# <Feature>: <what the key is and where to get it>`.
+- The application must work, deploy and pass every check **without** the key: the feature shows a clear "not configured yet" state and nothing crashes.
+- The Factory asks the owner for declared keys and redeploys when one is provided; never hardcode, commit or log a key.
+
+## Environment (already set; read at runtime, never hardcode)
+`PYPI_PACKAGE_NAME`
+

trustwarden-0.1.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.5
+Name: trustwarden
+Version: 0.1.0
+Summary: Guarding your tools with certainty. Trust labels and policy enforcement for AI agent tools.
+License-Expression: MIT
+Keywords: ai-agents,llm,policy,security,tool-calling,trust
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# TrustWarden
+
+TrustWarden is a Python security library for AI agents and tool-calling applications. It tracks trust and sensitivity labels across wrapped Python tool calls, then evaluates policy before sensitive actions execute—so prompt injection, secret exfiltration, and untrusted mutations can be denied fail-closed before they run.
+
+## Features
+
+### Typed decorator and adapter API
+
+Wrap any sync Python callable with pre-execution policy checks. No LangChain, OpenAI, or other agent framework is required.
+
+**Main actions:** decorate with `@warden.tool(...)`, adapt an existing function with `warden.adapt(...)`, or wrap registries via `wrap_callable`, `wrap_tool_map`, and `wrap_tool_specs` / `ToolSpec`.
+
+```python
+from trustwarden import Warden, mark_user_input, unwrap_result
+
+warden = Warden()
+
+@warden.tool(destination="local", state_changing=False)
+def search(query: object) -> str:
+    return str(unwrap_result(query))
+
+search(mark_user_input("roadmap"))
+```
+
+### Trust-label propagation and marking
+
+Values carry `TrustLevel` (`unknown` → `system`) and `Sensitivity` (`unknown` → `secret`) via `Labelled`. Mark data at boundaries with `mark_user_input`, `mark_trusted`, `mark_system`, `mark_untrusted`, `mark_sensitive`, and `mark_secret`. Tool outputs inherit the weakest trust and strongest sensitivity from their inputs through `propagate_labels` / the decorator (or use `collect_labels` / `as_labelled` / `unwrap_result` directly).
+
+```python
+from trustwarden import mark_user_input, mark_secret, collect_labels, propagate_labels
+
+trust, sensitivity = collect_labels(mark_user_input("q"), mark_secret("sk"))
+out = propagate_labels({"hits": 1}, mark_user_input("q"))
+```
+
+### Pre-execution policies (allow / block / escalate)
+
+Versioned policy documents (`POLICY_FORMAT_VERSION` = `1.0`) declare rules for data exposure, destinations, and state-changing actions. `PolicyEngine` evaluates a `ToolContext` and returns a `DecisionAction`. Load JSON with `load_policy` / `load_policy_file`, or use `default_safe_policy()`. Author rules with `Policy`, `PolicyRule`, and `RuleKind`.
+
+```python
+from pathlib import Path
+from trustwarden import Warden, load_policy_file, mark_secret
+
+policy = load_policy_file(Path("policies/default.json"))
+warden = Warden(policy)
+warden.decide(
+    "http_post",
+    {"body": mark_secret("sk-demo")},
+    destination="external_http",
+    state_changing=True,
+)
+```
+
+### Optional LLM-assisted review
+
+When a rule returns `escalate`, `Warden` can call a caller-supplied `LLMReviewer` (`ReviewRequest` → `ReviewResult`). TrustWarden never bundles an LLM client or API key. Without one, `DeterministicReviewer` resolves escalations offline (default: block). Use `apply_review` for manual review of a decision.
+
+```python
+from trustwarden import Warden, DeterministicReviewer, DecisionAction, mark_user_input
+
+warden = Warden(reviewer=DeterministicReviewer(default_action=DecisionAction.BLOCK))
+warden.decide(
+    "send_email",
+    {"body": mark_user_input("hello")},
+    destination="email",
+    state_changing=True,
+)
+```
+
+### Safe-by-default / fail-closed behavior
+
+Unknown labels and policy evaluation errors deny by default. Configure posture with `FailClosedConfig` (safe defaults or permissive) on `Warden` / `PolicyEngine`. Detect bare values with `has_unknown_labels`. Wrapped tools raise `PolicyBlockedError` when blocked; invalid policy documents raise `PolicyError` (both under `TrustWardenError`).
+
+```python
+from trustwarden import Warden, FailClosedConfig, has_unknown_labels
+
+assert has_unknown_labels("bare") is True
+Warden(fail_closed=FailClosedConfig.safe_defaults())
+```
+
+### Local attack simulator
+
+`AttackSimulator` runs built-in malicious scenarios (`builtin_scenarios`: prompt-injection exfil, secret/webhook exfil, untrusted writes, unknown labels, and more) against a policy and reports pass/fail (`AttackScenario`, `ScenarioResult`). Use `assert_all_passed()` / `summary()` in CI, or the CLI entrypoint `trustwarden-simulate`.
+
+```python
+from trustwarden import AttackSimulator
+
+AttackSimulator().assert_all_passed()
+```
+
+```bash
+uv run trustwarden-simulate
+```
+
+### Structured, secret-redacted decision records and event hooks
+
+Every evaluation produces a `DecisionRecord` (via `build_decision`) with redacted arguments (`redact_text` / `redact_value` / `REDACTED`). Subscribe to `EventBus` with callables or a `DecisionSink`: built-ins are `CollectingSink`, `LoggingSink`, and `JsonLinesSink`. Export flat dicts with `decision_to_log_record`.
+
+```python
+from io import StringIO
+from trustwarden import EventBus, JsonLinesSink, Warden, mark_user_input
+
+bus = EventBus()
+buf = StringIO()
+bus.subscribe_sink(JsonLinesSink(buf))
+warden = Warden(events=bus)
+warden.decide("read", {"q": mark_user_input("x")}, destination="local")
+```
+
+### Framework-neutral core, typed interfaces, versioned policies, examples
+
+The core lives under `src/trustwarden/` with `py.typed`. Compatibility adapters and typed interfaces (`ToolSpec`, `ToolCallable`, `LLMReviewer`, `DecisionSink`) sit beside the policy format (`policies/default.json`). Runnable examples: `examples/basic_usage.py`, `examples/logging_hooks.py`, `examples/wrap_registry.py`, `examples/custom_policy.py`. Brand assets (logo/favicon) are in `frontend/public/` for packaging and docs; there is no web UI.
+
+## Pages
+
+TrustWarden is a **Python package**, not a web application. There are **no frontend routes** and no interactive screens.
+
+| Path | What it is |
+| --- | --- |
+| _(none)_ | No app pages or SPA routes are served |
+| `frontend/public/logo.svg` | Brand logo asset (primary `#003366`, accent `#FFCC00`) |
+| `frontend/public/favicon.svg` | Brand favicon asset |
+
+Use the library from your own agent or service process; there is nothing to open in a browser for TrustWarden itself.
+
+## API
+
+There is **no HTTP backend**. The product surface is the **importable Python API** (package version `0.1.0`) plus one console script. Grouped by feature:
+
+### Labels and marking
+
+| Symbol | Purpose |
+| --- | --- |
+| `TrustLevel` / `Sensitivity` | Enumerations for provenance and sensitivity |
+| `Labelled` | Value + label metadata (`unwrap`, `with_labels`) |
+| `as_labelled` / `collect_labels` / `propagate_labels` | Coerce, aggregate, and attach labels |
+| `mark_user_input` / `mark_trusted` / `mark_system` / `mark_untrusted` | Mark provenance |
+| `mark_sensitive` / `mark_secret` | Mark sensitivity |
+| `unwrap_result` | Extract raw value from a labelled result |
+
+### Guarding tools
+
+| Symbol | Purpose |
+| --- | --- |
+| `Warden` | Policy guard: `tool`, `adapt`, `decide`, `check` |
+| `ToolSpec` | Declarative tool description for registries |
+| `wrap_callable` / `wrap_tool_map` / `wrap_tool_specs` | Framework-neutral adapters |
+
+### Policy
+
+| Symbol | Purpose |
+| --- | --- |
+| `POLICY_FORMAT_VERSION` | Schema version (`1.0`) |
+| `Policy` / `PolicyRule` / `RuleKind` / `ToolContext` | Versioned policy model |
+| `PolicyEngine` | Deterministic evaluation |
+| `default_safe_policy` | Built-in fail-closed policy |
+| `load_policy` / `load_policy_file` | Parse JSON policies |
+
+### Decisions, redaction, events
+
+| Symbol | Purpose |
+| --- | --- |
+| `DecisionAction` / `DecisionRecord` / `build_decision` | Structured decisions |
+| `REDACTED` / `redact_text` / `redact_value` | Secret scrubbing |
+| `EventBus` / `DecisionSink` | Export hooks |
+| `CollectingSink` / `LoggingSink` / `JsonLinesSink` | Built-in sinks |
+| `decision_to_log_record` | Flat mapping for loggers |
+
+### Review, safety, simulation, errors
+
+| Symbol | Purpose |
+| --- | --- |
+| `LLMReviewer` / `ReviewRequest` / `ReviewResult` / `DeterministicReviewer` / `apply_review` | Escalation review |
+| `FailClosedConfig` / `has_unknown_labels` | Fail-closed configuration |
+| `AttackScenario` / `ScenarioResult` / `builtin_scenarios` / `AttackSimulator` | Attack simulation |
+| `TrustWardenError` / `PolicyError` / `PolicyBlockedError` | Exception hierarchy |
+
+### CLI
+
+| Entry | Purpose |
+| --- | --- |
+| `trustwarden-simulate` | Run built-in attack scenarios and print a JSON summary (`trustwarden.simulator:main`) |
+
+Import everything from the package root, for example `from trustwarden import Warden, mark_user_input`.
+
+## Configuration
+
+| Variable | Required | Purpose |
+| --- | --- | --- |
+| `PYPI_PACKAGE_NAME` | Yes (for publish / simulator package field) | Distribution name of this package on PyPI; read at runtime via `trustwarden.config` (never hardcode). Listed in `.env.example`. |
+
+**Third-party API keys:** none are owned or required by TrustWarden. Optional LLM review uses a caller-supplied `LLMReviewer`; pass any model credentials only inside that implementation (arguments or the caller’s own environment). The library works fully without an LLM via `DeterministicReviewer`.
+
+Do not commit a `.env` file or put secret values in documentation.
+
+## Run it locally
+
+Install dependencies and the editable package:
+
+```bash
+uv sync
+```
+
+Lint, typecheck, test, and build:
+
+```bash
+uv run ruff check .
+uv run mypy src
+uv run pytest
+uv build
+```
+
+Try the library:
+
+```bash
+uv run python examples/basic_usage.py
+uv run trustwarden-simulate
+```
+
+`uv build` writes a wheel and sdist under `dist/` (for example `trustwarden-0.1.0-py3-none-any.whl` and `trustwarden-0.1.0.tar.gz`).
+
+## Architecture
+
+**Stack:** frontend none · backend none · database none · vector database none. Language: Python 3.11+ · package manager: uv · build backend: hatchling · typed package with `py.typed`.
+
+**Repository layout:**
+
+| Path | Role |
+| --- | --- |
+| `src/trustwarden/` | Library implementation (labels, wrap, policy, events, simulator, …) |
+| `tests/` | Unit tests and doctest runner |
+| `examples/` | Runnable usage samples |
+| `policies/default.json` | Sample versioned policy document |
+| `frontend/public/` | Brand SVG assets only (no app) |
+| `pyproject.toml` | Package metadata, ruff/mypy/pytest, `trustwarden-simulate` script |
+| `.env.example` | Declares `PYPI_PACKAGE_NAME` (names only) |
+
+**How “frontend” and “backend” talk:** they do not—there is no browser client and no HTTP API. Consumers import `trustwarden` in their own process (agent runtime, worker, or CLI). Policy evaluation happens in-process before the wrapped tool body runs; decisions can be exported to the host app’s logging via `EventBus` sinks.

trustwarden-0.1.0/README.md

@@ -0,0 +1,238 @@
+# TrustWarden
+
+TrustWarden is a Python security library for AI agents and tool-calling applications. It tracks trust and sensitivity labels across wrapped Python tool calls, then evaluates policy before sensitive actions execute—so prompt injection, secret exfiltration, and untrusted mutations can be denied fail-closed before they run.
+
+## Features
+
+### Typed decorator and adapter API
+
+Wrap any sync Python callable with pre-execution policy checks. No LangChain, OpenAI, or other agent framework is required.
+
+**Main actions:** decorate with `@warden.tool(...)`, adapt an existing function with `warden.adapt(...)`, or wrap registries via `wrap_callable`, `wrap_tool_map`, and `wrap_tool_specs` / `ToolSpec`.
+
+```python
+from trustwarden import Warden, mark_user_input, unwrap_result
+
+warden = Warden()
+
+@warden.tool(destination="local", state_changing=False)
+def search(query: object) -> str:
+    return str(unwrap_result(query))
+
+search(mark_user_input("roadmap"))
+```
+
+### Trust-label propagation and marking
+
+Values carry `TrustLevel` (`unknown` → `system`) and `Sensitivity` (`unknown` → `secret`) via `Labelled`. Mark data at boundaries with `mark_user_input`, `mark_trusted`, `mark_system`, `mark_untrusted`, `mark_sensitive`, and `mark_secret`. Tool outputs inherit the weakest trust and strongest sensitivity from their inputs through `propagate_labels` / the decorator (or use `collect_labels` / `as_labelled` / `unwrap_result` directly).
+
+```python
+from trustwarden import mark_user_input, mark_secret, collect_labels, propagate_labels
+
+trust, sensitivity = collect_labels(mark_user_input("q"), mark_secret("sk"))
+out = propagate_labels({"hits": 1}, mark_user_input("q"))
+```
+
+### Pre-execution policies (allow / block / escalate)
+
+Versioned policy documents (`POLICY_FORMAT_VERSION` = `1.0`) declare rules for data exposure, destinations, and state-changing actions. `PolicyEngine` evaluates a `ToolContext` and returns a `DecisionAction`. Load JSON with `load_policy` / `load_policy_file`, or use `default_safe_policy()`. Author rules with `Policy`, `PolicyRule`, and `RuleKind`.
+
+```python
+from pathlib import Path
+from trustwarden import Warden, load_policy_file, mark_secret
+
+policy = load_policy_file(Path("policies/default.json"))
+warden = Warden(policy)
+warden.decide(
+    "http_post",
+    {"body": mark_secret("sk-demo")},
+    destination="external_http",
+    state_changing=True,
+)
+```
+
+### Optional LLM-assisted review
+
+When a rule returns `escalate`, `Warden` can call a caller-supplied `LLMReviewer` (`ReviewRequest` → `ReviewResult`). TrustWarden never bundles an LLM client or API key. Without one, `DeterministicReviewer` resolves escalations offline (default: block). Use `apply_review` for manual review of a decision.
+
+```python
+from trustwarden import Warden, DeterministicReviewer, DecisionAction, mark_user_input
+
+warden = Warden(reviewer=DeterministicReviewer(default_action=DecisionAction.BLOCK))
+warden.decide(
+    "send_email",
+    {"body": mark_user_input("hello")},
+    destination="email",
+    state_changing=True,
+)
+```
+
+### Safe-by-default / fail-closed behavior
+
+Unknown labels and policy evaluation errors deny by default. Configure posture with `FailClosedConfig` (safe defaults or permissive) on `Warden` / `PolicyEngine`. Detect bare values with `has_unknown_labels`. Wrapped tools raise `PolicyBlockedError` when blocked; invalid policy documents raise `PolicyError` (both under `TrustWardenError`).
+
+```python
+from trustwarden import Warden, FailClosedConfig, has_unknown_labels
+
+assert has_unknown_labels("bare") is True
+Warden(fail_closed=FailClosedConfig.safe_defaults())
+```
+
+### Local attack simulator
+
+`AttackSimulator` runs built-in malicious scenarios (`builtin_scenarios`: prompt-injection exfil, secret/webhook exfil, untrusted writes, unknown labels, and more) against a policy and reports pass/fail (`AttackScenario`, `ScenarioResult`). Use `assert_all_passed()` / `summary()` in CI, or the CLI entrypoint `trustwarden-simulate`.
+
+```python
+from trustwarden import AttackSimulator
+
+AttackSimulator().assert_all_passed()
+```
+
+```bash
+uv run trustwarden-simulate
+```
+
+### Structured, secret-redacted decision records and event hooks
+
+Every evaluation produces a `DecisionRecord` (via `build_decision`) with redacted arguments (`redact_text` / `redact_value` / `REDACTED`). Subscribe to `EventBus` with callables or a `DecisionSink`: built-ins are `CollectingSink`, `LoggingSink`, and `JsonLinesSink`. Export flat dicts with `decision_to_log_record`.
+
+```python
+from io import StringIO
+from trustwarden import EventBus, JsonLinesSink, Warden, mark_user_input
+
+bus = EventBus()
+buf = StringIO()
+bus.subscribe_sink(JsonLinesSink(buf))
+warden = Warden(events=bus)
+warden.decide("read", {"q": mark_user_input("x")}, destination="local")
+```
+
+### Framework-neutral core, typed interfaces, versioned policies, examples
+
+The core lives under `src/trustwarden/` with `py.typed`. Compatibility adapters and typed interfaces (`ToolSpec`, `ToolCallable`, `LLMReviewer`, `DecisionSink`) sit beside the policy format (`policies/default.json`). Runnable examples: `examples/basic_usage.py`, `examples/logging_hooks.py`, `examples/wrap_registry.py`, `examples/custom_policy.py`. Brand assets (logo/favicon) are in `frontend/public/` for packaging and docs; there is no web UI.
+
+## Pages
+
+TrustWarden is a **Python package**, not a web application. There are **no frontend routes** and no interactive screens.
+
+| Path | What it is |
+| --- | --- |
+| _(none)_ | No app pages or SPA routes are served |
+| `frontend/public/logo.svg` | Brand logo asset (primary `#003366`, accent `#FFCC00`) |
+| `frontend/public/favicon.svg` | Brand favicon asset |
+
+Use the library from your own agent or service process; there is nothing to open in a browser for TrustWarden itself.
+
+## API
+
+There is **no HTTP backend**. The product surface is the **importable Python API** (package version `0.1.0`) plus one console script. Grouped by feature:
+
+### Labels and marking
+
+| Symbol | Purpose |
+| --- | --- |
+| `TrustLevel` / `Sensitivity` | Enumerations for provenance and sensitivity |
+| `Labelled` | Value + label metadata (`unwrap`, `with_labels`) |
+| `as_labelled` / `collect_labels` / `propagate_labels` | Coerce, aggregate, and attach labels |
+| `mark_user_input` / `mark_trusted` / `mark_system` / `mark_untrusted` | Mark provenance |
+| `mark_sensitive` / `mark_secret` | Mark sensitivity |
+| `unwrap_result` | Extract raw value from a labelled result |
+
+### Guarding tools
+
+| Symbol | Purpose |
+| --- | --- |
+| `Warden` | Policy guard: `tool`, `adapt`, `decide`, `check` |
+| `ToolSpec` | Declarative tool description for registries |
+| `wrap_callable` / `wrap_tool_map` / `wrap_tool_specs` | Framework-neutral adapters |
+
+### Policy
+
+| Symbol | Purpose |
+| --- | --- |
+| `POLICY_FORMAT_VERSION` | Schema version (`1.0`) |
+| `Policy` / `PolicyRule` / `RuleKind` / `ToolContext` | Versioned policy model |
+| `PolicyEngine` | Deterministic evaluation |
+| `default_safe_policy` | Built-in fail-closed policy |
+| `load_policy` / `load_policy_file` | Parse JSON policies |
+
+### Decisions, redaction, events
+
+| Symbol | Purpose |
+| --- | --- |
+| `DecisionAction` / `DecisionRecord` / `build_decision` | Structured decisions |
+| `REDACTED` / `redact_text` / `redact_value` | Secret scrubbing |
+| `EventBus` / `DecisionSink` | Export hooks |
+| `CollectingSink` / `LoggingSink` / `JsonLinesSink` | Built-in sinks |
+| `decision_to_log_record` | Flat mapping for loggers |
+
+### Review, safety, simulation, errors
+
+| Symbol | Purpose |
+| --- | --- |
+| `LLMReviewer` / `ReviewRequest` / `ReviewResult` / `DeterministicReviewer` / `apply_review` | Escalation review |
+| `FailClosedConfig` / `has_unknown_labels` | Fail-closed configuration |
+| `AttackScenario` / `ScenarioResult` / `builtin_scenarios` / `AttackSimulator` | Attack simulation |
+| `TrustWardenError` / `PolicyError` / `PolicyBlockedError` | Exception hierarchy |
+
+### CLI
+
+| Entry | Purpose |
+| --- | --- |
+| `trustwarden-simulate` | Run built-in attack scenarios and print a JSON summary (`trustwarden.simulator:main`) |
+
+Import everything from the package root, for example `from trustwarden import Warden, mark_user_input`.
+
+## Configuration
+
+| Variable | Required | Purpose |
+| --- | --- | --- |
+| `PYPI_PACKAGE_NAME` | Yes (for publish / simulator package field) | Distribution name of this package on PyPI; read at runtime via `trustwarden.config` (never hardcode). Listed in `.env.example`. |
+
+**Third-party API keys:** none are owned or required by TrustWarden. Optional LLM review uses a caller-supplied `LLMReviewer`; pass any model credentials only inside that implementation (arguments or the caller’s own environment). The library works fully without an LLM via `DeterministicReviewer`.
+
+Do not commit a `.env` file or put secret values in documentation.
+
+## Run it locally
+
+Install dependencies and the editable package:
+
+```bash
+uv sync
+```
+
+Lint, typecheck, test, and build:
+
+```bash
+uv run ruff check .
+uv run mypy src
+uv run pytest
+uv build
+```
+
+Try the library:
+
+```bash
+uv run python examples/basic_usage.py
+uv run trustwarden-simulate
+```
+
+`uv build` writes a wheel and sdist under `dist/` (for example `trustwarden-0.1.0-py3-none-any.whl` and `trustwarden-0.1.0.tar.gz`).
+
+## Architecture
+
+**Stack:** frontend none · backend none · database none · vector database none. Language: Python 3.11+ · package manager: uv · build backend: hatchling · typed package with `py.typed`.
+
+**Repository layout:**
+
+| Path | Role |
+| --- | --- |
+| `src/trustwarden/` | Library implementation (labels, wrap, policy, events, simulator, …) |
+| `tests/` | Unit tests and doctest runner |
+| `examples/` | Runnable usage samples |
+| `policies/default.json` | Sample versioned policy document |
+| `frontend/public/` | Brand SVG assets only (no app) |
+| `pyproject.toml` | Package metadata, ruff/mypy/pytest, `trustwarden-simulate` script |
+| `.env.example` | Declares `PYPI_PACKAGE_NAME` (names only) |
+
+**How “frontend” and “backend” talk:** they do not—there is no browser client and no HTTP API. Consumers import `trustwarden` in their own process (agent runtime, worker, or CLI). Policy evaluation happens in-process before the wrapped tool body runs; decisions can be exported to the host app’s logging via `EventBus` sinks.