first-forecast 0.1.0

Official Python SDK for the First Forecast B2B2C API.

first-forecast

Official Python SDK for the First Forecast B2B2C API.

pip install first-forecast

Quick start (sync)

import os

from first_forecast import FirstForecast

ff = FirstForecast(api_key=os.environ["FF_API_KEY"])  # ff_live_... or ff_test_...

result = ff.forecast("AAPL", persona="balanced")
print(result["compliance"]["jurisdiction"])  # 'US'
print(result["forecast"]["horizons"][0]["most_probable"])

Quick start (async)

import asyncio

from first_forecast import AsyncFirstForecast


async def main():
    async with AsyncFirstForecast(api_key=...) as ff:
        result = await ff.forecast("AAPL", jurisdiction="EU")
        print(result["compliance"]["rules_applied"])


asyncio.run(main())

Sandbox

ff = FirstForecast(
    api_key=os.environ["FF_SANDBOX_KEY"],            # ff_test_<...>
    base_url="https://api-sandbox.first-forecast.app",
)

Methods

Method	Endpoint
ff.forecast(ticker, ...)	GET /v1/forecast/{ticker}
ff.multi(tickers, ...)	GET /v1/multi
ff.tickers(...)	GET /v1/tickers
ff.usage()	GET /v1/usage

The SSE stream endpoint (/v1/forecast/{ticker}/stream) is not bundled — use httpx-sse or aiohttp directly.

Errors

from first_forecast import FirstForecast, FirstForecastError

try:
    ff.forecast("NOTAREAL")
except FirstForecastError as e:
    if e.kind == "auth":         # 401 / 403
        ...
    elif e.kind == "not_found":  # 404
        ...
    elif e.kind == "bad_request":
        ...
    elif e.kind == "rate_limited":
        wait = e.retry_after or 5
        ...
    elif e.kind == "server_error":
        ...
    elif e.kind == "network":    # httpx.HTTPError
        ...
    elif e.kind == "parse":      # server returned non-JSON
        ...
    print(e.status, e.body)

Versioning

Tracks packages/schemas/openapi.yml in the first-forecast monorepo. Major-version bumps indicate a breaking change to that contract.

License

MIT.