# Trusted Agent Stack

[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.12%2B-3776AB.svg)](pyproject.toml)
[![Status](https://img.shields.io/badge/status-experimental-orange.svg)](#project-status)

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](https://github.com/docling-project/docling) | Extracts structured PDF content and provenance, including visually hidden text |
| [Granite Guardian](https://github.com/ibm-granite/granite-guardian) | Runs local, score-only checks for document instructions, groundedness, and tool safety |
| [Mellea](https://github.com/IBM/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

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

## Quick start

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

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

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

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

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

## Claude Code takeaway

Install the local groundedness verifier as an MCP server:

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

```bash
./scripts/rehearse_booth.sh 5
```

Use `100` for the day-before soak test. See
[`docs/booth-runbook.md`](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:

```bash
./scripts/setup_guardian.sh
```

Then run the live local probe:

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

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

```bash
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](CONTRIBUTING.md) before opening a pull request.
- Use the issue forms for bugs, feature ideas, and booth feedback.
- Follow the [Code of Conduct](CODE_OF_CONDUCT.md).
- Report vulnerabilities through the process in [SECURITY.md](SECURITY.md).

## License

Licensed under the [Apache License 2.0](LICENSE).