polybridge 0.1.0

Python SDK for the PolyBridge public API.

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:

pip install polybridge

From a local checkout:

python -m pip install -e .

Anonymous Search

Search can be used without an API key.

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

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.

export POLYBRIDGE_API_KEY="YOUR_POLYBRIDGE_API_KEY"

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.

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.

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

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.

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.