getstub 0.1.0

Issue verifiable allegiance receipts for AI agents

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

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:

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