Documentation Index
Fetch the complete documentation index at: https://docs.synthefy.com/llms.txt
Use this file to discover all available pages before exploring further.
API Client
The Synthefy Python SDK provides both synchronous and asynchronous API clients for making forecasting requests.
Synchronous Client
SynthefyAPIClient
class SynthefyAPIClient:
def __init__(
self,
api_key: str | None = None,
*,
timeout: float = 300.0,
max_retries: int = 2,
base_url: str = BASE_URL,
endpoint: str = ENDPOINT,
organization: Optional[str] = None,
user_agent: Optional[str] = None,
):
"""Initialize the Synthefy API client."""
Parameters
api_key
Type: str or None Default: None
API key for authentication. If not provided, will look for SYNTHEFY_API_KEY environment variable.
timeout
Type: float Default: 300.0
Request timeout in seconds.
max_retries
Type: int Default: 2
Maximum number of retry attempts for failed requests.
base_url
Type: str Default: "https://forecast.synthefy.com"
Base URL for the API.
endpoint
Type: str Default: "/v2/forecast"
API endpoint for forecasting requests.
organization
Type: str or None Default: None
Organization ID for multi-tenant setups.
user_agent
Type: str or None Default: None
Custom user agent string.
Methods
forecast
def forecast(
self,
request: ForecastV2Request,
*,
timeout: Optional[float] = None,
idempotency_key: Optional[str] = None,
extra_headers: Optional[Dict[str, str]] = None,
) -> ForecastV2Response:
"""Make a direct forecasting request."""
forecast_dfs
def forecast_dfs(
self,
history_dfs: List[pd.DataFrame],
target_dfs: List[pd.DataFrame],
target_col: str,
timestamp_col: str,
metadata_cols: List[str],
leak_cols: List[str],
model: str,
) -> List[pd.DataFrame]:
"""Make a forecasting request using pandas DataFrames."""
Asynchronous Client
SynthefyAsyncAPIClient
class SynthefyAsyncAPIClient:
def __init__(
self,
api_key: str | None = None,
*,
timeout: float = 300.0,
max_retries: int = 2,
base_url: str = BASE_URL,
endpoint: str = ENDPOINT,
organization: Optional[str] = None,
user_agent: Optional[str] = None,
):
"""Initialize the async Synthefy API client."""
Methods
forecast
async def forecast(
self,
request: ForecastV2Request,
*,
timeout: Optional[float] = None,
idempotency_key: Optional[str] = None,
extra_headers: Optional[Dict[str, str]] = None,
) -> ForecastV2Response:
"""Make a direct async forecasting request."""
forecast_dfs
async def forecast_dfs(
self,
history_dfs: List[pd.DataFrame],
target_dfs: List[pd.DataFrame],
target_col: str,
timestamp_col: str,
metadata_cols: List[str],
leak_cols: List[str],
model: str,
) -> List[pd.DataFrame]:
"""Make an async forecasting request using pandas DataFrames."""
Error Classes
SynthefyError
Base error for all Synthefy client exceptions.
APITimeoutError
The request timed out before completing.
APIConnectionError
The request failed due to a connection issue.
APIStatusError
Raised when the API returns a non-2xx status code.
BadRequestError
Invalid request data (400, 422 status codes).
AuthenticationError
Invalid API key (401 status code).
PermissionDeniedError
Access denied (403 status code).
NotFoundError
Resource not found (404 status code).
RateLimitError
Rate limit exceeded (429 status code).
InternalServerError
Server error (5xx status codes).
Examples
Basic Synchronous Usage
import pandas as pd
import numpy as np
from synthefy import SynthefyAPIClient
# Create sample data
history_data = pd.DataFrame({
'date': pd.date_range('2024-01-01', periods=100, freq='D'),
'sales': np.random.normal(100, 10, 100),
'store_id': 1,
'category_id': 101
})
target_data = pd.DataFrame({
'date': pd.date_range('2024-04-11', periods=30, freq='D'),
'sales': np.nan, # Values to forecast
'store_id': 1,
'category_id': 101
})
# Make forecast
with SynthefyAPIClient() as client:
forecast_dfs = client.forecast_dfs(
history_dfs=[history_data],
target_dfs=[target_data],
target_col='sales',
timestamp_col='date',
metadata_cols=['store_id', 'category_id'],
leak_cols=[],
model='Migas-1.0'
)
print(forecast_dfs[0].head())
Asynchronous Usage
import asyncio
import pandas as pd
import numpy as np
from synthefy import SynthefyAsyncAPIClient
async def main():
# Create sample data
history_data = pd.DataFrame({
'date': pd.date_range('2024-01-01', periods=100, freq='D'),
'sales': np.random.normal(100, 10, 100),
'store_id': 1,
'category_id': 101
})
target_data = pd.DataFrame({
'date': pd.date_range('2024-04-11', periods=30, freq='D'),
'sales': np.nan,
'store_id': 1,
'category_id': 101
})
# Make async forecast
async with SynthefyAsyncAPIClient() as client:
forecast_dfs = await client.forecast_dfs(
history_dfs=[history_data],
target_dfs=[target_data],
target_col='sales',
timestamp_col='date',
metadata_cols=['store_id', 'category_id'],
leak_cols=[],
model='Migas-1.0'
)
print(forecast_dfs[0].head())
# Run the async function
asyncio.run(main())
Error Handling
from synthefy import SynthefyAPIClient, BadRequestError, RateLimitError, APITimeoutError
try:
with SynthefyAPIClient() as client:
forecast_dfs = client.forecast_dfs(
history_dfs=[history_df],
target_dfs=[target_df],
target_col='sales',
timestamp_col='date',
metadata_cols=['store_id'],
leak_cols=[],
model='Migas-1.0'
)
except BadRequestError as e:
print(f"Invalid request: {e}")
print(f"Status code: {e.status_code}")
except RateLimitError as e:
print(f"Rate limited: {e}")
# Client automatically retries with exponential backoff
except APITimeoutError as e:
print(f"Request timed out: {e}")
See Also
