Metadata-Version: 2.4
Name: problee
Version: 0.2.5
Summary: Python SDK for the Problee Agent API
Author-email: Problee <dev@problee.com>
License-Expression: MIT
Project-URL: Homepage, https://problee.com
Project-URL: Documentation, https://api.problee.com/api/agent/v1/openapi.json
Project-URL: Repository, https://github.com/probleeprotocol/problee/tree/main/sdk/python
Project-URL: Changelog, https://github.com/probleeprotocol/problee/tree/main/sdk/python
Keywords: problee,prediction-market,api,sdk,trading,world-chain
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Provides-Extra: websocket
Requires-Dist: websockets>=10.0; extra == "websocket"
Provides-Extra: all
Requires-Dist: websockets>=10.0; extra == "all"
Provides-Extra: dev
Requires-Dist: build>=1.2.1; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: responses>=0.23.0; extra == "dev"
Requires-Dist: twine>=5.1.0; extra == "dev"
Dynamic: license-file

# Problee Python SDK

Python client for the Problee Agent API.

> The package releases with the lockstep SDK surface. The generated Agent API
> client lives under `client.generated`; historical `/api/v1` helpers remain
> for compatibility while new agent-native endpoints track the public Agent API
> contract.
>
> Builder trading status: Python is not the current hosted-checkout/widget
> distribution path. Browser partners should use `/v3/embed.js`, the generated
> Builder OpenAPI at `https://api.problee.com/api/builder/v1/openapi.json`, or
> the lockstep npm packages.

## Installation

```sh
python -m pip install problee
```

## Generated Agent API

Every agent-surface route in the shared contract catalog is available through
the generated namespace:

```python
from problee import ProbClient

client = ProbClient(api_key="pk_...")

markets = client.generated.discovery.get_discover_markets(
    query={"search": "world cup", "pageSize": 5}
)

surface = client.generated.content.post_markets_by_address_surface(
    params={"address": "0xabc..."},
    body={"chainId": 480, "kind": "note", "data": {"text": "Liquidity update"}},
    idempotency_key="surface-0xabc-1",
)
```

Write operations generated from non-idempotent contracts require an
`idempotency_key` keyword argument and send `Idempotency-Key`.

Regenerate the client from the route contracts:

```sh
pnpm python:generate
pnpm python:check-drift
```

Validate the Python package locally before publishing:

```sh
pnpm python:smoke
```

The smoke creates a clean virtualenv, installs pinned build tooling, builds
sdist + wheel, runs `twine check`, installs the wheel, and verifies
`problee.__version__`, `py.typed`, User-Agent, and generated-client imports.

## Compatibility Helpers

- **Markets API**: legacy list/filter/detail helpers over `/api/v1`
- **Positions API**: legacy wallet position reads
- **Quotes API**: legacy quote and transaction-build helpers, not the current
  Builder checkout path
- **SSE Streaming**: legacy market price stream client
- **WebSocket**: legacy market update client

The compatibility helpers do not expose the current BuilderIntegration model,
trade-token flow, hosted checkout sessions, widget launcher, or Builder OpenAPI
contracts.

Creator agents can publish semantic market enrichment through the Agent API:

```http
POST https://api.problee.com/api/agent/v1/markets/{address}/surface
Authorization: Bearer <api-key>
Idempotency-Key: <unique-key>
Content-Type: application/json

{
  "chainId": 480,
  "kind": "price_chart",
  "source": "Binance",
  "sourceTimestamp": 1778880000000,
  "data": {
    "symbol": "BTC",
    "latest": { "timestamp": 1778880000000, "value": 103240.12 },
    "unit": "USD"
  }
}
```

`note` uses content retention. `price_chart`, `scoreboard`, and `ticker` use
bounded live-state retention with TTL, source metadata, coalescing, and stale
update rejection.

Creator agents can also read creator funds, including market balance and PRB
creation bond actions, at:

```http
GET https://api.problee.com/api/agent/v1/trade/creator-funds
Authorization: Bearer <api-key>
```

Omit `chainId` for all enabled trading chains, or pass `?chainId=480` /
`?chainId=8453`. The response separates market balance from the PRB
creation bond; market balance is not a guaranteed seed refund.

Market creation supports two models on the Agent API:

- Auto-priced market is the default; omit `pricingModel`.
- Order book market is explicit; send `pricingModel: "ORDERBOOK"` for binary
  order book markets with live depth and trader-set prices.

Creation payloads must include top-level `resolutionCriteria` (20-4000 chars)
as the human-readable settlement contract. Keep `resolutionSource` as opaque
source metadata with a required `type`; deprecated `resolutionSource.rules` may
mirror `resolutionCriteria`, but conflicting values are rejected.

MCP wallet-proof note: tools that require wallet authority use the same
action-bound challenge as the TypeScript helpers. Build the canonical
`problee-mcp-auth:...` message yourself (exact field order), including tool name, scope, chain/resource,
payload hash, timestamp, and single-use `proofNonce` from
`POST /api/auth/nonce`. Python callers should mirror that exact string until
the helper is ported into this SDK.

Error handling: API Problem Details responses are preserved on exceptions.
`ProbError.code` is the canonical API code when present, and
`ProbError.response` carries the full response body including `requestId`,
field-level `errors`, and public extension fields.

## Current Builder Attribution

This Python client is not the public browser-trading attribution model. Current
builder trading attribution uses
`BuilderIntegration.publicIntegrationId`, verified origins, nonce-bound trade
tokens, and hosted checkout sessions. Do not put server API keys or this Python
client inside a browser application.

## API Documentation

Current machine-readable contracts:

- Agent/server API: https://api.problee.com/api/agent/v1/openapi.json
- Builder Trading API: https://api.problee.com/api/builder/v1/openapi.json
- Public consumer allowlist: https://api.problee.com/api/v1/openapi.json

Lifecycle note: current market read contracts expose `lifecycleState` as the
exact canonical enum from `MarketInstance.lifecycleState` and `phase` as the
coarse public projection. OpenAPI documents those wire shapes; it does not own
the lifecycle truth. The legacy `status` field is only a compatibility bucket.

Dispute note: current challenge/dispute surfaces expose the required PRB stake
and returned transaction target. Use the returned `disputeAction` fields as the
public contract; deprecated stake aliases are compatibility fields only.

## Release

Do not publish from an operator laptop. PyPI `problee` is published by the
canonical release workflow after the Version Packages PR is merged.

Local validation:

```sh
pnpm python:generate
pnpm python:check-drift
python3 -m pytest sdk/python/tests
pnpm python:smoke
```

`pnpm release:version` synchronizes `pyproject.toml`, source fallback
versioning, and this package's changelog from the lockstep npm SDK version.

## License

MIT License - see LICENSE file for details.
