The same /v1 surface the CLI and TypeScript SDK speak, in Python. Sync and async clients, typed results, zero magic — MIT licensed and published straight from CI with PyPI trusted publishing.
Python 3.9+. One runtime dependency (httpx). The client reads YSAERE_API_KEY from the environment — there is deliberately no key argument in the quickstart path, so a key never lands in a notebook cell you later share.
pip install ysaere export YSAERE_API_KEY=ysa_prod_YOUR_KEY
from ysaere import Ysaere
y = Ysaere() # reads YSAERE_API_KEY
report = y.run_and_wait("dd-report", "Acme Corp") # submit, then poll
print(report.text) # markdown
print(report.sources) # what it actually read
print(report.content_hashes) # section -> v2:sha512:...
Swarm runs take minutes and hand back a run_id you wait on. Sync micro-SKUs return the payload in a single response — there is no run_id and nothing to poll. run() refuses a sync endpoint outright rather than handing back an empty run.
run = y.company_intelligence("Acme Corp") # 202, queued — 100 credits
print(run.credits_consumed, run.balance_remaining)
report = y.wait(run) # blocks until terminal
chain = y.provenance(run.run_id) # free
y.vault_search("cap table") # 5 credits
y.classify("Acme Corp") # 10
y.quick_brief("Acme Corp", focus="key risks") # 20
y.sourced_brief("Acme Corp", sources=["web", "vault"]) # 40, with citations
Check the price before you spend: y.estimate("ci-report") and y.balance() both cost 0 credits.
Same methods, awaited. Use it when you are fanning a screen out across a list rather than running one target at a time.
import asyncio
from ysaere import AsyncYsaere
async def screen(targets):
async with AsyncYsaere() as y:
runs = [await y.angel_intelligence(t) for t in targets]
return await asyncio.gather(*(y.wait(r) for r in runs))
asyncio.run(screen(["Acme Robotics", "Beacon Bio"]))
Every completed run carries a Trust Receipt — a hash chain over each agent's inputs and outputs, signed with both Ed25519 and ML-DSA-65 (FIPS 204, post-quantum). Anyone can check it against the public keys at /.well-known/trust-keys. Provenance attests pipeline integrity, not that every claim is verified fact.