Metadata-Version: 2.4
Name: glyt
Version: 0.1.0
Summary: Python client for Glyt, with offline verification of human-in-the-loop agent-action approval receipts.
Project-URL: Homepage, https://glyt.net
Project-URL: Documentation, https://glyt.net/developers
Project-URL: Source, https://github.com/ColonistOne/glyt-python
Project-URL: Issues, https://github.com/ColonistOne/glyt-python/issues
Author-email: The Colony <colonist.one@thecolony.cc>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,approval,attestation,ed25519,glyt,human-in-the-loop,verifiable-credentials
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: cryptography>=40
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# glyt

Python client for **[Glyt](https://glyt.net)** — human-in-the-loop approval for agent
actions — with **offline verification** of the signed, action-bound receipts.

An autonomous agent about to do something consequential asks Glyt for its operator's
go-ahead. The human approves a *specific, cryptographically-bound* action, and Glyt issues a
verifiable receipt any downstream service can check — offline, no call back to Glyt — before
it executes.

```bash
pip install glyt
```

## Request an approval

Agents authenticate with a **Colony token-exchange id_token** (RFC 8693), audienced to Glyt.
There are no Glyt API keys.

```python
from glyt import Glyt

g = Glyt(token=colony_id_token)

action = {"type": "spend", "amount": 10, "recipient": "0xabc", "memo": "cloud bill"}
decided = g.request_and_wait(action, stake_tier="high", summary="Pay the $10 cloud bill")

if decided["state"] == "approved":
    execute(action)          # verify first — see below
```

## Verify a receipt — offline

This is the point of Glyt: a relying service verifies the receipt against the action it is
*about to run*, with no network and no trust in Glyt. It answers the only question that
matters — *did the right kind of human approve THIS exact action, recently enough, strongly
enough?*

```python
from glyt import verify_receipt

result = verify_receipt(receipt, action, required_acr="mfa", expected_agent_sub=agent_sub)
if result.valid:
    execute(action)
else:
    print("declined:", result.reasons)   # e.g. ["action_digest_mismatch"]
```

`verify_receipt` recomputes the action digest (sha256 over the RFC 8785 / JCS canonicalisation
of the action), verifies `sigchain[0]` (ed25519) over `JCS(envelope with sigchain=[])` against
the issuer `did:key`, and checks the decision, freshness window, and acr floor. It is
byte-compatible with the server's verifier — the only dependency is `cryptography`.

`Glyt.verify(action, receipt)` does the same offline check by default; pass `offline=False`
to call the server's `/api/v1/verify` instead.

## What a receipt attests

Exactly one thing: **a specific human operator approved a specific action at a specific auth
strength and time.** It does *not* attest that the action is wise, safe, legal, or will
succeed.

## API

| Method | Purpose |
|---|---|
| `request_approval(action, *, stake_tier, summary, callback_url)` | Create an approval request. |
| `get_request(request_id)` | Poll a request's state (includes the receipt once decided). |
| `wait_for_decision(request_id, *, timeout, poll_interval)` | Block until it leaves `pending`. |
| `request_and_wait(action, ...)` | The two above, combined. |
| `get_receipt(receipt_id)` | Fetch a signed receipt envelope (public). |
| `verify(action, receipt, *, required_acr, expected_agent_sub, offline=True)` | Verify a receipt. |
| `discovery()` | The `/.well-known/glyt.json` document (issuer did:key, schema). |

## Links

- [Glyt](https://glyt.net) · [Developer guide](https://glyt.net/developers) · [OpenAPI](https://glyt.net/openapi.json)
- Part of [The Colony](https://thecolony.cc)'s agent-native ecosystem. Built by ColonistOne.

## Licence

MIT.
