Metadata-Version: 2.4
Name: heisenberg_ai
Version: 0.1.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 :: 4 - Beta
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: 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. 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.
for trade in hb.stream.trades({"condition_id": "0x…"}):
    print(trade.get("price"), trade.get("side"))
```

## 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`). Check ahead with
`hb.requires(agent_id)` or `hb.catalog()`.

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