Metadata-Version: 2.4
Name: getstub
Version: 0.1.1
Summary: Issue verifiable allegiance receipts for AI agents
Author: Ankit Kumar
License: MIT
Project-URL: Homepage, https://getstub.dev
Project-URL: Registry, https://api.getstub.dev
Keywords: ai,agents,receipts,transparency,disclosure
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=41.0

# getstub

Issue verifiable allegiance receipts for AI agents, from Python.

When your agent acts for someone, this gives them a signed record of what it did and what influenced the result, checkable at a neutral registry. Three calls, and the third is one line per action.

Here is a live receipt before you install anything:

https://api.getstub.dev/check/72b4baee1719ec34acc5df5c514a12fd2e19b9a6776de4b45706988f765c77d8

## Install

```
pip install getstub
```

## Quickstart

```python
import os
from getstub import Stub, influenced

# 1. Declare your standing mandate, once. Policy level: who pays you, and
#    which kinds of conflict exist in your business at all.
stub = Stub(
    operator="Nimbus Assistant",
    declared={
        "paid_by": "the traveler, subscription",
        "conflicts": ["commission"],
    },
    principal_salt=os.environ["STUB_SALT"],
)

# 2. At the line where your ranking picks a winner, pass through the flags
#    it already computed. Nobody hand writes these.
inf = []
if pick.paid_placement:
    inf.append(influenced.placement(f"{pick.seller} paid for placement"))
if pick.commission_pct:
    inf.append(influenced.commission(f"{pick.commission_pct}% on a sale"))

# 3. One call per action.
receipt = stub.issue(
    principal=user.id,          # hashed on your side, never sent raw
    agent="nimbus",
    requested=query,
    done=f"booked {pick.name}",
    value_moved={"amount": pick.price, "currency": "GBP"},
    not_disclosed=inf,          # an empty list is signed proof none applied
)

print(receipt["url"])           # hand this to your user
```

## Where disclosures come from

Your ranking code already knows when a boost, a commission, or a partner filter applied, because it applied them. Pass the same flags through with `influenced` at the same line where the boost happens. Helpers: `placement`, `commission`, `partner_only`, `own_brand`, `data_share`, and `other(kind, detail)` for anything else.

An empty `not_disclosed` is not nothing. It is a signature saying conflicts exist in your business and none of them touched this action.

## Privacy by default

Pass your internal user id as `principal` and the client hashes it on your side with a salt only you hold. The registry rejects anything that is not an opaque digest, so no name or email can be stored even by accident.

Set the salt once so digests stay stable across restarts. If a user asks to be forgotten, drop their mapping to the salt and their digests become permanently meaningless, while the record stays append only.

Keep `requested` and `done` about the action, not the person. The client warns in development if free text looks like it carries an email or phone number.

## Keys

The client generates an Ed25519 keypair on first use. Save it if you want the same operator identity across restarts:

```python
kp = stub.export_keypair()          # store this somewhere safe
stub = Stub(operator="...", declared={...}, keypair=kp)
```

Your keys stay on your side. We cannot recover them for you.

## Compatibility

Stubs are signed over a canonical JSON form. This client produces byte identical output to the JavaScript client at `@getstub/agent`, which is verified in the test suite rather than assumed: the tests sign a stub in Python and have the actual registry code verify it.

```
python3 test_getstub.py     # 31 tests
```

## Pricing

Free tier: 1,000 stubs a month. Checking is always free.

## Links

- Docs and quickstart: https://getstub.dev
- Registry: https://api.getstub.dev
- Witness key: https://api.getstub.dev/witness
- JavaScript client: `npm install @getstub/agent`
