Metadata-Version: 2.4
Name: getstub
Version: 0.2.1
Summary: Verifiable disclosure receipts for AI agent actions. Show whose side your agent was on, checked at a neutral registry.
Author: Ankit Kumar
License: MIT
Project-URL: Homepage, https://getstub.dev
Project-URL: Documentation, https://getstub.dev
Project-URL: Repository, https://github.com/getstub/recipes
Project-URL: Issues, https://github.com/getstub/recipes/issues
Project-URL: Registry, https://api.getstub.dev
Project-URL: Examples, https://github.com/getstub/recipes
Keywords: ai-agents,llm-agents,agent-trust,agent-transparency,agentic-commerce,agent-disclosure,affiliate-disclosure,conflict-of-interest,sponsored-recommendation,ai-accountability,verifiable-receipts,audit-trail,ed25519,langchain,allegiance
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
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.

## The Stub Mark

Issue receipts for a few days and you earn a live mark you can put on your site, your docs, or your README. There is nothing to install, buy, or apply for. It is drawn by the registry from your own receipts, so you cannot set it and neither can we, and it goes quiet on its own if you stop issuing.

You do not have to go looking for it. `register()` hands you the embed line, and the client tells you once when you have earned it.

```python
out = stub.register()
print(out["mark"]["markdown"])
# [![Stub](https://api.getstub.dev/badge/op_yours.svg)](https://getstub.dev/o/op_yours)
```

Or ask at any time, including where you currently stand:

```python
m = stub.mark(live=True)
# badge_url, page_url, html, markdown, standing, stubsIssued, threshold, stubsToEarn
```

The badge is an image served by the registry. No script, no tracking, nothing loaded onto your users, and the same width in every state so nothing in your footer shifts when your standing changes.

Clicking it opens your operator page: the mandate you declared, when you last issued, how often your receipts carry a disclosure, and your most recent records. That page is not on your servers, which is the part that makes it worth anything to the person reading it.

Set `STUB_QUIET=1` if you would rather the client said nothing.

## 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

A keypair exported by either client works here. This one stores the raw Ed25519
private bytes and `@getstub/agent` stores a JWK, but they wrap the same 32 bytes,
so one identity moves between Python and JavaScript without regenerating a key
or abandoning your history.

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     # 44 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`
