Metadata-Version: 2.4
Name: threshold-keel
Version: 0.2.3
Summary: Structural persistence guarantee for LLM agent systems
Author-email: Brian McCallion <brian@thresholdsignalworks.com>
License-Expression: LicenseRef-Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Provides-Extra: llm
Requires-Dist: tiktoken>=0.5; extra == "llm"

# Keel

Persistent safety policies and cryptographic audit trails for tool-using agents.

Keel keeps constraints on disk, not in the prompt. Policies survive context compaction.
Every action is logged to a tamper-evident SHA-256 hash chain. Policy enforcement is
deterministic -- no LLM in the enforcement path.

## Install

```
pip install threshold-keel
```

Requires Python 3.10 or later. Zero runtime dependencies.

## Quick start

```bash
# Initialise (creates ~/.keel/ with default safety policies)
keel init

# Check status
keel --human status

# List active policies
keel --human policies

# Add a policy
keel add-policy --content "Block all financial transactions" --scope financial --priority 0

# Check a proposed action against policies
keel check-policy --action-json '{"action_type":"payment","target_ids":["vendor@example.com"],"surface":"financial","reversibility":"irreversible"}'

# Log an action to the WAL
keel wal-append --event-type PROPOSED --payload '{"action_type":"send_email","target_ids":["user@example.com"]}'

# Verify hash chain integrity
keel verify-chain

# Run a full fidelity self-check
keel fidelity
```

## What it does

Keel is a safety layer for autonomous agents that use tools. It provides three things:

**Persistent policies.** Rules live on disk in `~/.keel/store.json`, not in the chat
prompt. They survive context compaction, session restarts, and machine changes. The
agent checks policies before every action. A blocked action stays blocked -- the agent
cannot override it.

**Cryptographic audit trail.** Every action the agent takes is logged to an append-only
write-ahead log (WAL) with SHA-256 hash chaining. Each entry contains a cryptographic
hash of the previous entry, making the log tamper-evident. Chain integrity can be
verified at any time with `keel verify-chain`.

**Deterministic policy evaluation.** The CLI checks policies using structural matching,
not language model interpretation. A constraint scoped to `financial` blocks all actions
on the `financial` surface. No ambiguity, no "I think the user meant...".

## CLI commands

| Command | What it does |
|---------|-------------|
| `keel init` | Create `~/.keel/` directory with default safety policies |
| `keel check-policy` | Check a proposed action against active policies |
| `keel wal-append` | Log an event to the write-ahead log |
| `keel wal-query` | Query recent WAL entries |
| `keel verify-chain` | Verify WAL hash chain integrity |
| `keel --human status` | Show session overview |
| `keel fidelity` | Run a full self-check (policies, WAL, chain) |
| `keel --human policies` | List active policies |
| `keel add-policy` | Add a new policy |
| `keel remove-policy` | Deactivate a policy |
| `keel quarantine` | List quarantined items |
| `keel restore` | Restore an item from quarantine |

All commands output JSON by default. Add `--human` before the subcommand for
human-readable output. Add `--local` to force local mode when cloud credentials
are set.

## Exit codes

| Code | Meaning |
|------|---------|
| 0 | Success / action allowed |
| 1 | Blocked by policy or error |
| 2 | Requires human approval (T2/T3 action) |

## Risk tiers

Keel classifies actions into four risk tiers:

| Tier | Risk | Examples |
|------|------|----------|
| T0 | Read-only | Fetch email, list files, search |
| T1 | Reversible | Create files, add labels |
| T2 | Reversible within window | Archive, move to bin |
| T3 | Irreversible | Send email, permanent delete, publish, pay |

## Cloud sync (optional)

Set `KEEL_CLOUD_API_KEY` and the CLI syncs policies and WAL events with
Threshold Cloud automatically. Local safety continues uninterrupted if the
cloud is unreachable.

```bash
export KEEL_CLOUD_API_KEY=sk-keel-your-key-here
keel --human status
```

See [thresholdsignalworks.com/cloud](https://thresholdsignalworks.com/cloud)
for plans and pricing.

## OpenClaw integration

Keel ships with a SKILL.md that can be installed as an OpenClaw skill. In
instructions-only mode, the agent follows Keel's safety rules using file tools
directly. When the CLI is installed, the agent uses it automatically for
cryptographic hashing and deterministic policy checks.

## Security

See [SECURITY.md](SECURITY.md) for the security model and vulnerability
reporting process.

## Licence

BSL 1.1. Converts to Apache 2.0 after 4 years.

## Author

Brian McCallion, Threshold Signalworks Ltd, Limerick, Ireland.
ORCID: [0009-0004-1442-1743](https://orcid.org/0009-0004-1442-1743)
