Metadata-Version: 2.4
Name: geneva-forecast
Version: 1.0.0
Summary: Python SDK for the Geneva Forecasting Engine API
Project-URL: Homepage, https://portal.roadmap-tech.com
Project-URL: Documentation, https://portal.roadmap-tech.com/docs
Author-email: "RoadMap Technologies, Inc." <dom@roadmap-tech.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api,forecasting,geneva,time-series
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Requires-Dist: matplotlib>=3.5
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install geneva-forecast
```

## Quick Start

```python
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:

```python
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`:

```python
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:

```python
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:

```python
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

```python
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
