Metadata-Version: 2.4
Name: polybridge
Version: 0.1.0
Summary: Python SDK for the PolyBridge public API.
Project-URL: Homepage, https://polybridge.ai
Project-URL: API, https://api.polybridge.ai/openapi-public.json
Author: PolyBridge
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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.10
Requires-Dist: httpx<1,>=0.25
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-httpx; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# PolyBridge Python SDK

Python SDK for the stable PolyBridge public API.

v0.1 scope is intentionally small: Search, Forecast, and Health only. It does
not include Markets, Situation Room, streaming Forecast, MCP, pandas helpers, or
analytics/timeseries utilities.

## Installation

After release:

```bash
pip install polybridge
```

From a local checkout:

```bash
python -m pip install -e .
```

## Anonymous Search

Search can be used without an API key.

```python
from polybridge import PolyBridge

client = PolyBridge()

response = client.search(
    "US recession risk",
    top_k_per_dimension=3,
    filters={"status": "active"},
)

for result in response.results.get("direct", []):
    print(result.question, result.platform_url)
```

## API-Key Search

When an API key is configured, the SDK sends it as
`Authorization: Bearer <api_key>`.

```python
from polybridge import PolyBridge

client = PolyBridge(api_key="YOUR_POLYBRIDGE_API_KEY")

response = client.search(
    "US recession risk",
    top_k_per_dimension=3,
    filters={"status": "active"},
)
```

You can also use the `POLYBRIDGE_API_KEY` environment variable.

```bash
export POLYBRIDGE_API_KEY="YOUR_POLYBRIDGE_API_KEY"
```

```python
from polybridge import PolyBridge

client = PolyBridge()
client.health()
```

## Forecast

Forecast requires an API key. If no key is configured, the SDK raises a local
`AuthenticationError` before making a network request.

```python
from polybridge import PolyBridge

client = PolyBridge(api_key="YOUR_POLYBRIDGE_API_KEY")

forecast = client.forecast(
    "Will there be a US recession in 2026?",
    include_graph=True,
)

print(forecast.probability)
print(forecast.reasoning)
```

## Raw Responses

Use `with_raw_response` when you need HTTP metadata such as response headers or
the raw body.

```python
from polybridge import PolyBridge

client = PolyBridge(api_key="YOUR_POLYBRIDGE_API_KEY")

raw = client.with_raw_response.forecast("Will the Fed cut rates?")
print(raw.status_code, raw.request_id)
print(raw.parsed.probability)
```

## Configuration

```python
from polybridge import PolyBridge

client = PolyBridge(
    api_key="YOUR_POLYBRIDGE_API_KEY",
    base_url="https://api.polybridge.ai",
    timeout=10.0,
    forecast_timeout=120.0,
    attribution_code="partner-code",
    referrer="https://example.com",
)
```

Attribution headers are only sent when values are provided.

## Errors And Rate Limits

All SDK exceptions inherit from `PolyBridgeError`.

```python
from polybridge import PolyBridge, RateLimitError

client = PolyBridge(api_key="YOUR_POLYBRIDGE_API_KEY")

try:
    client.forecast("Will the Fed cut rates?")
except RateLimitError as error:
    print(error.status_code)
    print(error.request_id)
    print(error.retry_after)
```

Status errors expose `status_code`, `detail`, `request_id`,
`response_headers`, `raw_body`, and for rate limits, `retry_after`.

## Security

Do not expose long-lived PolyBridge API keys in browser or mobile clients. Route
requests through a trusted backend you control.
