Metadata-Version: 2.4
Name: heisenberg_ai
Version: 1.0.0
Summary: Python SDK for the Heisenberg prediction-market intelligence API.
Author-email: Seshat Labs <info@seshatlabs.xyz>
License: MIT
Project-URL: Homepage, https://prediction.heisenberg.so
Project-URL: Documentation, https://prediction.heisenberg.so/docs/sdk
Project-URL: Repository, https://github.com/SeshatLabs/heisenberg-sdk
Keywords: heisenberg,polymarket,kalshi,hyperliquid,prediction-markets,intelligence
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
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: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: stream
Requires-Dist: websocket-client>=1.7; extra == "stream"
Provides-Extra: dev
Requires-Dist: websocket-client>=1.7; extra == "dev"

# Heisenberg Python SDK

Python client for the Heisenberg prediction-market intelligence API — generated from
the same spec snapshot as the TypeScript SDK, with the same resource model, venue
abstraction, gating semantics, and streaming.

Read-only and **synchronous** (no async client yet). The REST client uses only the Python
standard library (no required deps).

## Install

```bash
pip install heisenberg_ai            # REST
pip install "heisenberg_ai[stream]"  # + real-time streaming (websocket-client)
```

## Quickstart

```python
from heisenberg import Heisenberg

hb = Heisenberg(token="…")  # or set HEISENBERG_TOKEN

# Free tier — no subscription needed.
markets = hb.polymarket.markets({"min_volume": 1000, "closed": False, "limit": 5}).page()
profile = hb.wallets.profile("0xabc…", {"window_days": 15}).page()

# Iterate a Query to auto-paginate every row.
for trade in hb.polymarket.trades({"condition_id": "0x…"}):
    ...

# Real-time trades (Polymarket only; needs the [stream] extra).
for trade in hb.stream.trades({"condition_id": "0x…"}):
    print(trade.get("price"), trade.get("side"))
```

## Pagination & rate limits

Iterating a `Query` auto-paginates. The API is rate limited (≈50 req/window); each `Page`
carries `page.rate_limit` (`{"limit","remaining","reset"}`, `reset` in seconds) so you can
pace bulk `.all()` calls, and the client backs off by `x-ratelimit-reset` on a `429`.

## Two axes

- **Venues** — `hb.polymarket`, `hb.kalshi`, `hb.hyperliquid`; each exposes the
  capabilities the spec says it supports (`hb.polymarket.supports("orderbook")`).
- **Intelligence** — `hb.wallets`, `hb.smart_money`, `hb.leaderboards`, `hb.markets`,
  `hb.sports`, `hb.audience`, `hb.social`.

Escape hatch for anything not wrapped: `hb.query(agent_id, params)`.

## Gated endpoints

Sport/audience endpoints require a subscription and raise a typed `PlanError`
(preserving the API message, plus `.required_plan` / `.endpoint`). `hb.requires(agent_id)`
and `hb.catalog()` report the sport/audience add-on plans — but they are **not** an
exhaustive pre-flight check: access is a property of your token, so some venues (e.g.
Hyperliquid) and endpoints can still return `PlanError`. Always be ready to catch it.

## Develop

```bash
python -m unittest discover -s tests
```

Generated code lives in `heisenberg/_generated/` (produced by `../scripts/generate.mjs`
from `../spec/source`). Never edit it by hand.
