geneva-forecast 1.0.0

Python SDK for the Geneva Forecasting Engine API

geneva-forecast

Forecast any time series in 3 lines of Python. A typed SDK for the Geneva Forecasting Engine — a high-performance time series forecasting API with automated model selection, conformal prediction intervals, and built-in charting.

Installation

pip install geneva-forecast

Quick Start

from geneva_forecast import GenevaClient

client = GenevaClient(
    api_url="https://api.roadmap-tech.com",
    api_key="gva_your_api_key_here",
)

# Monthly sales data (6 years)
monthly_sales = [
    112.0, 118.4, 132.1, 124.3, 121.1, 140.2,
    148.9, 153.7, 136.2, 119.0, 104.0, 118.5,
    121.3, 129.8, 138.5, 146.7, 128.4, 155.3,
    162.8, 149.1, 141.7, 119.5, 108.2, 126.3,
    133.9, 142.7, 156.1, 137.8, 145.2, 161.4,
    178.3, 168.0, 149.5, 125.3, 113.7, 132.8,
    139.5, 155.8, 148.2, 163.4, 152.7, 175.9,
    194.1, 181.3, 162.8, 140.6, 129.3, 148.7,
    157.2, 149.8, 171.6, 158.3, 168.9, 189.4,
    210.7, 195.2, 174.3, 153.1, 141.8, 163.9,
    172.4, 181.9, 195.7, 178.3, 183.5, 204.6,
    226.3, 213.8, 188.7, 165.4, 155.2, 179.8,
]

result = client.forecast(
    data=monthly_sales,
    horizon=12,
    wave_periods=[12],
)

for point in result.forecast:
    print(f"  Period {point.period}: {point.value:.2f}")

print(f"Model: {result.model_info.method_name}")
print(f"MAPE:  {result.metrics.mape:.2f}%")

The client can also be used as a context manager:

with GenevaClient(api_url="https://api.roadmap-tech.com", api_key="gva_...") as client:
    result = client.forecast(data=monthly_sales, horizon=12)

Prediction Intervals

Get conformal prediction intervals by setting confidence_level:

result = client.forecast(
    data=monthly_sales,
    horizon=12,
    confidence_level=0.95,
    include=["forecast", "prediction_intervals", "metrics", "model_info"],
)

for pt in result.prediction_intervals:
    print(f"  Period {pt.period}: {pt.forecast:.2f}  [{pt.lower:.2f}, {pt.upper:.2f}]")

Batch Forecasting

Forecast multiple time series in a single request:

result = client.batch_forecast(series=[
    {
        "id": "product_a",
        "data": [100, 120, 115, 130, 125, 140, 135, 150, 145, 160, 155, 170],
        "horizon": 6,
    },
    {
        "id": "product_b",
        "data": [200, 210, 205, 220, 215, 230, 225, 240, 235, 250, 245, 260],
        "horizon": 6,
    },
])

print(f"Batch: {result.successful}/{result.total_series} succeeded in {result.elapsed_ms:.0f}ms")

for sr in result.results:
    if sr.status == "success":
        values = [f"{p.value:.1f}" for p in sr.forecast.forecast]
        print(f"  {sr.id}: {', '.join(values)}")

Visualization

Built-in charting is included — no extra install needed:

from geneva_forecast.plot import plot_forecast

result = client.forecast(
    data=monthly_sales,
    horizon=12,
    confidence_level=0.95,
    include=["forecast", "fitted", "prediction_intervals", "metrics", "model_info"],
)

# One-liner chart with historical data, fitted values, forecast, and prediction intervals
plot_forecast(monthly_sales, result)

# Calendar date labels on x-axis (format: YYYY-MM-DD)
plot_forecast(monthly_sales, result, start_date="2020-01-01", freq="MS")
# Supported: "MS" (monthly), "QS" (quarterly), "W" (weekly),
#            "D" (daily), "H" (hourly), "YS" (yearly)

# Save to file
plot_forecast(monthly_sales, result, show=False, save="forecast.png")

Parameters

Parameter	Type	Default	Description
data	list[float]	required	Time series values (min 3, max 10,000)
method	int | None	None	Forecasting method (0–9). None = auto-select best
wave_periods	list[int]	[12]	Seasonal cycle lengths (e.g. [12] for monthly, [52] for weekly)
horizon	int | None	None	Number of periods ahead to forecast
confidence_level	float | None	None	Prediction interval confidence (e.g. 0.95)
include	list[str]	["forecast", "metrics", "model_info"]	Response sections to return

Available include Sections

"forecast" · "fitted" · "seasonal_factors" · "metrics" · "model_info" · "prediction_intervals" · "all"

Tip: Set method=None (the default) to let the Expert System automatically select the best-performing model for your data.

Error Handling

from geneva_forecast import GenevaAPIError, GenevaConnectionError, GenevaTimeoutError

try:
    result = client.forecast(data=[1.0, 2.0, 3.0])
except GenevaAPIError as e:
    print(f"API error {e.status_code}: {e.message}")
except GenevaTimeoutError:
    print("Request timed out")
except GenevaConnectionError:
    print("Could not connect to the Geneva API")

License

MIT