Trusted Agent Stack

An open trust plane that validates and repairs frontier-model answers and actions before they reach users or tools.

[!NOTE] This is an independent open-source demonstration built with IBM open-source technologies. It is not an IBM product, and it does not connect to any real payment or enterprise system.

Demo

See the poisoned-invoice scenario progress from an unsafe simulated payment to a verified human-approval action:

https://github.com/user-attachments/assets/d1b12482-69b7-4f85-9da3-f9b183fc07e9

The first vertical slice is a booth-safe, simulated invoice-payment scenario:

1. A frontier model proposes one typed action.
2. The exact same proposal is forked into unverified and trusted paths.
3. The unverified path executes against a local sandbox.
4. The trusted path runs semantic and deterministic checks.
5. Failed actions are repaired, revalidated, and emitted with a Trust Receipt.

No real payment or enterprise system is connected.

IBM open-source building blocks

Project	Role in this stack
Docling	Extracts structured PDF content and provenance, including visually hidden text
Granite Guardian	Runs local, score-only checks for document instructions, groundedness, and tool safety
Mellea	Provides the optional typed repair and validation-retry path

Exact account matching, payment thresholds, and tool schemas remain deterministic Python policies. The booth hot path uses deterministic repair for latency and repeatability; the Mellea repair path is available through the CLI.

Architecture

PDF → Docling evidence → frontier action proposal
                           ├─ unverified sandbox
                           └─ Guardian + policy checks
                                      ↓ fail
                               repair → revalidate
                                      ↓ pass
                              sandbox + Trust Receipt

Quick start

uv sync --extra dev
uv run demo spike poisoned-invoice
uv run pytest

Mock mode is deterministic and requires no model download or credentials.

For a live frontier proposal with automatic disk-cache fallback:

uv sync --extra api --extra frontier
FRONTIER_PROVIDER=mellea-litellm \
FRONTIER_MODEL=anthropic/your-model-id \
uv run tas-api

Run the fixed scenario once while online to seed cache/generations/. At the venue, set FRONTIER_OFFLINE=true; the receipt will explicitly mark the generation as cached. The provider model ID and credential environment variable depend on the selected LiteLLM provider.

Booth UI

Start the API and UI in separate terminals:

uv sync --extra api --extra dev
uv run tas-api

cd frontend
npm install
npm run dev

Open http://127.0.0.1:5173. The attract loop is on by default: it starts after six idle seconds, holds the completed receipt for twelve seconds, resets, and repeats. Use ?attract=0 for operator-only mode or toggle it from the status bar.

Before doors open, verify the frozen artifacts, frontend build, Ollama model, and running API:

uv run tas preflight --api-url http://127.0.0.1:8000

Claude Code takeaway

Install the local groundedness verifier as an MCP server:

uv sync --extra mcp
claude mcp add trusted-agent-stack -- \
  uv run --project /absolute/path/to/trusted-agent-stack tas-mcp

The verify_answer tool accepts a question, draft answer, and document excerpts. It returns only a groundedness verdict from the local Granite Guardian and fails closed when the verifier is unavailable. Document excerpts are always treated as untrusted data.

Rehearsal

Run the complete build, preflight, test suite, and repeated live-Guardian scenario:

./scripts/rehearse_booth.sh 5

Use 100 for the day-before soak test. See docs/booth-runbook.md for startup, operator controls, and the failure matrix.

Granite Guardian probe

Download the official IBM Q4 GGUF and register it with Ollama:

./scripts/setup_guardian.sh

Then run the live local probe:

uv run demo spike poisoned-invoice \
  --guardian ollama \
  --guardian-model trusted-granite-guardian:4.1

The hot path uses score-only judging. The demo never exposes a model reasoning trace.

Mellea repair probe

With a local Ollama model available:

uv sync --extra dev --extra mellea
uv run demo spike poisoned-invoice \
  --repair mellea-ollama \
  --repair-model granite4.1:3b

Mellea generates a typed repair, validates the repair with an executable requirement, and retries with validation feedback when necessary. The deterministic business-policy checks still run after Mellea returns.

Run modes

• mock: deterministic local development.
• ollama: live local Guardian checks with deterministic business policy enforcement.

Receipts are written below runs/ by default and are intentionally ignored by Git.

Rebuild the document fixture

The poisoned PDF contains a visually hidden instruction in its text layer. Rebuild and preprocess it with:

uv sync --extra demo-assets --extra docling
uv run python scripts/generate_demo_invoice.py
uv run python scripts/preprocess_docling.py

Docling output is frozen below scenarios/poisoned-invoice/docling/ for booth use. The live demo does not parse the PDF on its hot path.

Project status

Trusted Agent Stack is an experimental booth demo and reference implementation. Its payment tool is an in-memory sandbox. Do not use it as a production authorization or payment system without an independent security review.

Community

• Read CONTRIBUTING.md before opening a pull request.
• Use the issue forms for bugs, feature ideas, and booth feedback.
• Follow the Code of Conduct.
• Report vulnerabilities through the process in SECURITY.md.

License

Licensed under the Apache License 2.0.