Metadata-Version: 2.3
Name: faim-sdk
Version: 0.1.2
Summary: Python SDK for FAIM time-series forecasting with foundation AI models
License: Apache-2.0
Author: FAIM
Author-email: info@faim.it.com
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: Apache Software 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
Requires-Dist: attrs (>=22.2.0)
Requires-Dist: httpx (>=0.23.0,<0.29.0)
Requires-Dist: numpy (>=1.20.0,<2.0.0)
Requires-Dist: pyarrow (>=10.0.0)
Description-Content-Type: text/markdown

# FAIM SDK

Python SDK for FAIM time-series forecasting with foundation AI models.

## Installation

```bash
pip install faim-sdk
```

## Quick Start

```python
import numpy as np
from faim_sdk import ForecastClient, FlowStateForecastRequest
from faim_client.models import ModelName

# Initialize client
client = ForecastClient(
    base_url="http://localhost:8003",
    timeout=60.0
)

# Prepare your time-series data
# Shape: (batch_size, sequence_length, features)
data = np.random.randn(1, 100, 1).astype(np.float32)

# Create forecast request
request = FlowStateForecastRequest(
    x=data,
    horizon=10,
    model_version="1"
)

# Generate forecast
response = client.forecast(ModelName.FLOWSTATE, request)

# Access predictions
print(response.point)  # Shape: (batch_size, horizon, features)
print(response.metadata)  # Model metadata
```

## Models

### FlowState

Point forecasting model optimized for deterministic predictions.

```python
from faim_sdk import FlowStateForecastRequest

request = FlowStateForecastRequest(
    x=data,
    horizon=10,
    model_version="1",
    output_type="point",  # Options: "point", "quantiles", "samples"
    scale_factor=1.0,  # Optional normalization
    prediction_type="mean"  # Options: "mean", "median", "quantile"
)
```

### ToTo

Probabilistic forecasting model with quantile and sample-based predictions.

```python
from faim_sdk import ToToForecastRequest

# Quantile predictions
request = ToToForecastRequest(
    x=data,
    horizon=10,
    model_version="1",
    output_type="quantiles",
    quantiles=[0.1, 0.5, 0.9]  # 10th, 50th, 90th percentiles
)

# Sample-based predictions
request = ToToForecastRequest(
    x=data,
    horizon=10,
    model_version="1",
    output_type="samples",
    num_samples=100
)
```

## Response Format

All forecasts return a `ForecastResponse` object:

```python
response = client.forecast(ModelName.TOTO, request)

# Access predictions based on output_type
if response.point is not None:
    predictions = response.point  # Shape: (batch_size, horizon, features)

if response.quantiles is not None:
    quantiles = response.quantiles  # Shape: (batch_size, horizon, num_quantiles)

if response.samples is not None:
    samples = response.samples  # Shape: (batch_size, horizon, num_samples)

# Access metadata
print(response.metadata)  # {'model_name': 'toto', 'model_version': '1'}
```

## Async Usage

```python
async with ForecastClient(base_url="http://localhost:8003") as client:
    response = await client.forecast_async(ModelName.FLOWSTATE, request)
    print(response.point)
```

## Examples

See the `examples/` directory for complete notebook examples:
- `flowstate_simple_example.ipynb` - Point forecasting with FlowState
- `toto_simple_example.ipynb` - Probabilistic forecasting with ToTo

## Error Handling

The SDK provides specific exception types for different error scenarios:

```python
from faim_sdk import (
    ModelNotFoundError,
    ValidationError,
    TimeoutError,
    NetworkError,
    SerializationError
)

try:
    response = client.forecast(ModelName.FLOWSTATE, request)
except ModelNotFoundError:
    print("Model or version not found")
except ValidationError:
    print("Invalid request parameters")
except TimeoutError:
    print("Request timed out")
except NetworkError:
    print("Network communication failed")
except SerializationError:
    print("Failed to serialize/deserialize data")
```

## Configuration

### Client Options

```python
# Without authentication
client = ForecastClient(
    base_url="https://api.example.com",
    timeout=120.0,  # Request timeout in seconds
    verify_ssl=True,  # SSL certificate verification
    **httpx_kwargs  # Additional httpx.Client arguments
)

# With API key authentication
client = ForecastClient(
    base_url="https://api.example.com",
    api_key="your-secret-api-key",  # API key for authentication
    timeout=120.0,
    verify_ssl=True
)
```

### Request Options

```python
request = FlowStateForecastRequest(
    x=data,
    horizon=10,
    model_version="1",
    compression="zstd",  # Options: "zstd", "lz4", None
)
```

## Requirements

- Python >= 3.10
- numpy >= 1.20.0
- pyarrow >= 10.0.0
- httpx >= 0.23.0

## Development

### Regenerating the Low-Level Client

The `faim_client` package is auto-generated from the OpenAPI specification. To regenerate after API changes:

```bash
# Get the latest OpenAPI spec from your server
curl http://your-server:8003/openapi.json > openapi.json

# Regenerate the client
openapi-python-client generate --path openapi.json --config client.config.yaml --meta none
```

The `--meta none` flag prevents creating an extra outer directory.

After regenerating, test that `faim_sdk` still works correctly:
```bash
poetry install
pytest tests/
```

## License

Apache 2.0
