Metadata-Version: 2.4
Name: heso
Version: 0.4.3
Requires-Dist: pytest>=7 ; extra == 'test'
Requires-Dist: langchain-core>=0.2 ; extra == 'test'
Provides-Extra: test
Summary: The compliance layer for AI agents — gate, approve, redact, sign, and audit every AI-agent action into offline-verifiable receipts.
License: LicenseRef-Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://www.heso.ca/docs
Project-URL: Homepage, https://www.heso.ca
Project-URL: Source, https://github.com/heso-inc/heso
Project-URL: Verify, https://www.heso.ca/verify

# heso

**The compliance layer for AI agents.** Wrap an agent and every action it takes —
LLM call, tool call, payment, account change, delete — is gated against your policy
(allow / block / redact / require-approval), routed to a human when a decision is
risky, PII-redacted before signing, and signed into an offline-verifiable
**Action Receipt** appended to a BLAKE3-chained audit log.

You hold the signing keys. heso's cloud can verify and mirror receipts but can
**never forge one** — so anyone (a customer, an auditor, a court) can check exactly
what your agent did, and that it was authorized, without trusting heso at all.

- **Site** · [heso.ca](https://www.heso.ca)
- **Docs** · [heso.ca/docs](https://www.heso.ca/docs)
- **Verify a receipt (no account)** · [heso.ca/verify](https://www.heso.ca/verify)

```sh
pip install heso        # or: uv add heso
```

## First receipt in 60 seconds

```sh
heso demo
```

`heso demo` scaffolds a project, mints one allowed and one redacted receipt through
the real engine, verifies both offline, and prints how to re-verify them yourself.
No cloud account, no key ceremony — a dev key is generated for you (strict custody
is opt-in for production).

The CLI:

| command | what it does |
|---|---|
| `heso init [dir]` | scaffold `heso.toml` + policy, mint your operator identity in-process |
| `heso demo [dir]` | mint + verify your first receipts end to end |
| `heso verify <path\|hash>` | re-run the hash + signature math locally, print the verdict (zero network) |
| `heso show <hash>` | pretty-print a stored receipt |

## Gate an agent

Every decorated call is gated **before its body runs** — a blocked or
approval-pending action raises, so the side effect can never fire ungated.

```python
import heso

heso.init()

@heso.tool
def search(query: str) -> list[str]:
    ...

@heso.destructive                      # verb=delete → matched against policy
def delete_account(account_id: str) -> None:
    ...

@heso.tool(redact=["api_key"])         # PII stripped before the receipt is signed
def call_vendor(api_key: str, payload: dict) -> dict:
    ...
```

Policy lives in a `heso.toml` the SDK reads at gate time — allow the safe lanes,
`require_approval` the risky ones. Edit it freely; it's the single source of policy
truth.

## Human approval (L1)

When a rule says `require_approval`, the action **suspends** instead of running.
A human approver co-signs it (in the heso console or via your own webhook), and the
receipt is upgraded to L1 — proving an authorized human approved this specific
action, not just that the operator allowed the lane.

```python
from heso import gated, resume

gate = gated(charge_card, amount=5000)   # suspends if policy requires approval
if gate.status is heso.SUSPENDED:
    ...                                  # notify approver; park the work
else:
    result = gate.run()
```

## Framework adapters

Drop-in wrappers over the same gate core — no rewrite:

```python
import heso

heso.claude_agent   # Anthropic Claude Agent SDK
heso.openai_agents  # OpenAI Agents SDK
heso.langgraph      # LangGraph / LangChain
heso.crewai         # CrewAI
heso.pydantic_ai    # Pydantic AI
heso.mcp            # Model Context Protocol tools
```

There's also `heso-mcp`, an MCP server so an agent can gate and verify through heso
directly.

## Verify anywhere

Receipts verify offline with heso fully removed from the loop — the hash and
signature math is open and the format is specified in
[`ACTION-RECEIPT-1.0`](https://github.com/heso-inc/heso). Hand a receipt to anyone
and they can confirm it's untampered and see who signed it.

```sh
heso verify ./receipt.json
# → Valid · L1 (operator + human approver)
```

## Trust model

heso proves an action was **authorized** under policy, and at L1 that an authorized
human **approved or blocked** it. It does **not** prove the action's outcome was
truthful — that's unprovable from the artifact. Trust grades are L0 (operator) and
L1 (operator + human approver).

---

Proprietary. See [heso.ca](https://www.heso.ca) for licensing and the hosted console.

