Metadata-Version: 2.4
Name: intent-anchor-sdk
Version: 0.1.0
Summary: Python client for Intent-Anchor — cryptographic provenance and Zero-Trust execution gating for AI agents.
Author: Shachar Goldberg
License: MIT
Project-URL: Homepage, https://github.com/Stavenote/intent-anchor-poc
Project-URL: Repository, https://github.com/Stavenote/intent-anchor-poc
Project-URL: Documentation, https://github.com/Stavenote/intent-anchor-poc/blob/main/docs/ARCHITECTURE_WHITEPAPER.md
Project-URL: Bug Tracker, https://github.com/Stavenote/intent-anchor-poc/issues
Keywords: ai-agents,provenance,zero-trust,audit,cryptography,llm,guard-proxy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# intent-anchor-sdk

Python client for **Intent-Anchor** — cryptographic provenance and Zero-Trust execution gating for AI agents. Anchor an agent's intent and response, gate a sensitive action behind that proof, and verify the whole trail without trusting the server.

## Install

```bash
pip install intent-anchor-sdk
```

## Quickstart

```python
from intent_anchor_sdk import IntentAnchorClient

client = IntentAnchorClient(base_url="http://localhost:8000", api_key="your-api-key")
execution = client.run_execution("Draft a refund approval for order #4471")
decision = client.execute_intent(execution["execution_id"], {
    "action_type": "issue_refund",
    "action_payload": {"order_id": "4471", "amount": 42.00},
})
print(decision["status"])  # "APPROVED" or "BLOCKED", with an exact reason either way
```

That's the whole integration: anchor the intent, run the agent, gate the action it wants to take. No server-side code changes, no framework lock-in — just HTTP calls this client wraps for you.

## What each method does

| Method | Calls | What it's for |
|---|---|---|
| `anchor_intent(text, context)` | `POST /anchor` | Anchor an intent in the cryptographic chain (no LLM call) |
| `run_execution(text, context)` | `POST /intent/execute` | Full pipeline: anchor the intent, call the LLM, seal intent+response together |
| `execute_intent(execution_id, action)` | `POST /guard/execute-action` | Gate a proposed action — returns `APPROVED` or `BLOCKED` with the exact reason |
| `export_bundle(execution_id)` | `GET /audit/export/{id}` | Export a self-contained, signed Proof Bundle |
| `verify_bundle_online(bundle)` | `POST /audit/verify-bundle` | Server-side bundle verification |
| `verify_bundle_offline(path)` | *(no network call)* | Verify a Proof Bundle or Time-Stamp Token entirely offline — see note below |
| `whoami()` | `GET /auth/whoami` | Resolve your own API key to its `client_id` |
| `health()` | `GET /` | Liveness check |

Every write call (`anchor_intent`, `run_execution`, `execute_intent`) attaches your API key automatically; verification/read calls are public and never need one.

## `context` conventions the Guard Proxy understands

Declare these when anchoring an intent to control what `execute_intent()` will later approve:

```python
client.run_execution(
    "Approve a transfer of 100 ILS to vendor Acme Ltd for invoice 4471",
    context={
        "allowed_action_types": ["transfer_funds"],       # reject any other action_type outright
        "expected_action_fields": {"amount": 100},        # exact-match gate — a payload with amount=1000 is BLOCKED immediately
    },
)
```

## Known limitation in this release

`verify_bundle_offline()` delegates to this project's `audit_cli.py` for genuinely offline, zero-server-trust verification — but that file (and its own dependencies: `cryptography`-based signature checks, Merkle proof recomputation) lives in the full server repository, not in this standalone package. Calling it without that repository available raises a clear `RuntimeError` telling you so. Every other method works identically with just `pip install intent-anchor-sdk` — this is the one exception, not a hidden gap.

Two ways around it today:
- Use `verify_bundle_online(bundle)` instead — needs network access to the server, not a local repository.
- Clone the full repo ([github.com/Stavenote/intent-anchor-poc](https://github.com/Stavenote/intent-anchor-poc)) and run from within it — `verify_bundle_offline()` works exactly as documented there.

## Full documentation

This package is the thin client half of a larger system. For the cryptographic design, the threat model, and an honest list of what's production-ready today versus roadmap, see the main repository:

- [Architecture Whitepaper](https://github.com/Stavenote/intent-anchor-poc/blob/main/docs/ARCHITECTURE_WHITEPAPER.md)
- [Due Diligence Guide](https://github.com/Stavenote/intent-anchor-poc/blob/main/docs/DUE_DILIGENCE_GUIDE.md)

## License

MIT — see [LICENSE](https://github.com/Stavenote/intent-anchor-poc/blob/main/LICENSE).
