bippsi

Install

PyPI publish is pending. For the alpha, clone the repo:

# clone the public repo
git clone https://github.com/bigappstudiollc/bippsi.git
cd bippsi/ai-lock-protocol/clients/python
pip install -e .

Requires Python 3.9+. Only runtime dep: requests.

30-second quickstart

from bippsi import BippsiClient

bippsi = BippsiClient(
    # agent_key defaults to BIPPSI_AGENT_KEY env var
    max_price_per_request=10,
)

# 1. Discover
r = bippsi.discover(q='finance', access='paid')

# 2. Resolve — metadata for any URL
meta = bippsi.resolve(r['results'][0]['resource_url'])

# 3. Fetch — handles 402 retry + payment automatically
res = bippsi.fetch(r['results'][0]['resource_url'])
print(res['body'], 'paid:', res['paid'], 'Bips')

Drop-in requests replacement

Change one import and every call auto-handles 402:

# Before:
import requests
r = requests.get('https://example.com/report.pdf')

# After:
from bippsi import requests
r = requests.get('https://example.com/report.pdf', max_price_per_request=25)

print(r.text)    # content (paid if needed)
print(r.paid)    # extension: Bips spent (0 if unpriced)

Error handling

from bippsi import OverspendCapError, InsufficientBalanceError

try:
    res = bippsi.fetch(url)
except OverspendCapError as e:
    print(f'Too expensive: {e.price_bips}B > {e.cap}B cap')
except InsufficientBalanceError as e:
    print(f'Top up — need {e.price_bips}, have {e.balance}')

Full API

• bippsi.discover(q=..., access=..., sort=..., limit=...) — search the registry.
• bippsi.resolve(url) — get Bippsi metadata for any URL.
• bippsi.fetch(url, max_price_per_request=...) — fetch + 402 handling.
• bippsi.pay(url=..., price_bips=...) — explicit charge without a fetch.
• bippsi.get_balance() — current Bip balance.
• bippsi.list_receipts(since=..., limit=...) — recent charges.

Behavior contract shared with the Node SDK is documented at client-spec.md.