# TSFM Python Client
A Python client library for the TSFM (Time Series Foundation Model) Inference Platform. Supports both univariate and multivariate time series forecasting with confidence intervals.
## Installation
```bash
pip install tsfm-client
```
## Quick Start
```python
import os
import numpy as np
from tsfm_client import TSFMClient
# Set your API key
os.environ['TSFM_API_KEY'] = 'your_api_key_here'
# Create client
client = TSFMClient(api_key=os.getenv('TSFM_API_KEY'))
# Make prediction with confidence intervals
data = np.array([10, 12, 13, 15, 17, 16, 18, 20, 22, 25])
response = client.predict(
data=data,
forecast_horizon=5,
num_samples=100,
confidence_intervals=[0.8, 0.95]
)
print(f"Forecast: {response.forecast}")
print(f"80% CI: {response.confidence_intervals['80%']}")
print(f"95% CI: {response.confidence_intervals['95%']}")
client.close()
```
## Supported Models
### [chronos-t5-small](https://huggingface.co/amazon/chronos-t5-small) (Amazon)
- **Type**: Univariate time series forecasting
- **Framework**: Chronos pipeline with T5 transformer architecture
- **Max forecast horizon**: 64 steps (recommended)
- **Optimal use**: Fast predictions for single time series
- **Default confidence intervals**: Uses 10 samples for CI calculation
- **Strengths**: Quick inference, good for short-term forecasting
### [toto-open-base-1.0](https://huggingface.co/Datadog/Toto-Open-Base-1.0) (Datadog)
- **Type**: Multivariate time series forecasting
- **Framework**: Zero-shot transformer model
- **Max forecast horizon**: 336 steps (recommended)
- **Optimal use**: Complex multivariate relationships, longer horizons
- **Default confidence intervals**: Uses 256 samples for CI calculation
- **Strengths**: Handles multiple correlated variables, robust uncertainty estimation
## Supported Input Formats
The client accepts multiple data formats for maximum flexibility:
- **Numpy arrays**: `np.array([1, 2, 3])` (most efficient)
- **Python lists**: `[1, 2, 3]` or `[[1, 10], [2, 11]]` (multivariate)
- **Pandas Series**: `pd.Series([1, 2, 3])`
- **Pandas DataFrame**: For multivariate data
## Features
- ✅ **Multiple confidence intervals**: Get 80%, 90%, 95% intervals in single request
- ✅ **Multivariate forecasting**: Predict with multiple related time series
- ✅ **Flexible sampling**: Control uncertainty estimation with num_samples
## Advanced Usage
### Multivariate Prediction
```python
# 2D numpy array: time steps × variables
multivariate_data = np.array([[20, 65], [21, 63], [22, 61], [19, 67]])
response = client.predict(
model_name='toto-open-base-1.0',
data=multivariate_data,
forecast_horizon=10,
confidence_intervals=[0.8, 0.9, 0.95],
num_samples=100
)
```
### Context Manager
```python
with TSFMClient() as client:
response = client.predict(data=np.array([1, 2, 3, 4, 5]))
print(response.forecast)
```
## Examples
For comprehensive examples including visualization and model comparison, see the [demo notebook](https://github.com/S-FM/tsfm-python-client/blob/main/examples/demo.ipynb).
## Requirements
- Python >= 3.10
- Valid TSFM API key
- Dependencies: numpy, pandas, httpx, pydantic
## API Reference
### TSFMClient.predict()
```python
predict(
model_name: str = "chronos-t5-small",
data: Union[np.ndarray, pd.Series, List[float], List[List[float]]],
forecast_horizon: int = 12,
confidence_intervals: Optional[List[float]] = None,
num_samples: Optional[int] = None,
time_interval_seconds: Optional[int] = None
) -> PredictionResponse
```
**Parameters:**
- `model_name`: Model to use ('chronos-t5-small' or 'toto-open-base-1.0')
- `data`: Time series data (1D for univariate, 2D for multivariate)
- `forecast_horizon`: Number of steps to predict
- `confidence_intervals`: List of confidence levels (e.g., [0.8, 0.95])
- `num_samples`: Number of samples for uncertainty estimation
- `time_interval_seconds`: Time between data points in seconds
**Returns:**
- `PredictionResponse` with forecast, confidence intervals, and metadata
## Roadmap
- 🔄 **Batch processing**: Process multiple time series in a single request
- 🎯 **More models**: Additional foundation models coming soon
- ⚙️ **Fine-tuning**: Support for domain-specific model adaptation
## License
MIT License
Raw data
{
"_id": null,
"home_page": "https://github.com/S-FM/tsfm-python-client",
"name": "tsfm-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "time-series, forecasting, foundation-models, api-client, numpy, multivariate, confidence-intervals, tsfm, chronos, toto",
"author": "Andrei Chernov",
"author_email": "chernov.andrey.998@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/01/ee/382b71301e518d42278e0245eed405ef366c9468a8815c4e7df4d0f32bb0/tsfm_client-0.2.2.tar.gz",
"platform": null,
"description": "# TSFM Python Client\n\nA Python client library for the TSFM (Time Series Foundation Model) Inference Platform. Supports both univariate and multivariate time series forecasting with confidence intervals.\n\n## Installation\n\n```bash\npip install tsfm-client\n```\n\n## Quick Start\n\n```python\nimport os\nimport numpy as np\nfrom tsfm_client import TSFMClient\n\n# Set your API key\nos.environ['TSFM_API_KEY'] = 'your_api_key_here'\n\n# Create client\nclient = TSFMClient(api_key=os.getenv('TSFM_API_KEY'))\n\n# Make prediction with confidence intervals\ndata = np.array([10, 12, 13, 15, 17, 16, 18, 20, 22, 25])\nresponse = client.predict(\n data=data,\n forecast_horizon=5,\n num_samples=100,\n confidence_intervals=[0.8, 0.95]\n)\n\nprint(f\"Forecast: {response.forecast}\")\nprint(f\"80% CI: {response.confidence_intervals['80%']}\")\nprint(f\"95% CI: {response.confidence_intervals['95%']}\")\n\nclient.close()\n```\n\n## Supported Models\n\n### [chronos-t5-small](https://huggingface.co/amazon/chronos-t5-small) (Amazon)\n- **Type**: Univariate time series forecasting\n- **Framework**: Chronos pipeline with T5 transformer architecture\n- **Max forecast horizon**: 64 steps (recommended)\n- **Optimal use**: Fast predictions for single time series\n- **Default confidence intervals**: Uses 10 samples for CI calculation\n- **Strengths**: Quick inference, good for short-term forecasting\n\n### [toto-open-base-1.0](https://huggingface.co/Datadog/Toto-Open-Base-1.0) (Datadog)\n- **Type**: Multivariate time series forecasting \n- **Framework**: Zero-shot transformer model\n- **Max forecast horizon**: 336 steps (recommended)\n- **Optimal use**: Complex multivariate relationships, longer horizons\n- **Default confidence intervals**: Uses 256 samples for CI calculation\n- **Strengths**: Handles multiple correlated variables, robust uncertainty estimation\n\n## Supported Input Formats\n\nThe client accepts multiple data formats for maximum flexibility:\n\n- **Numpy arrays**: `np.array([1, 2, 3])` (most efficient)\n- **Python lists**: `[1, 2, 3]` or `[[1, 10], [2, 11]]` (multivariate)\n- **Pandas Series**: `pd.Series([1, 2, 3])`\n- **Pandas DataFrame**: For multivariate data\n\n## Features\n\n- \u2705 **Multiple confidence intervals**: Get 80%, 90%, 95% intervals in single request\n- \u2705 **Multivariate forecasting**: Predict with multiple related time series\n- \u2705 **Flexible sampling**: Control uncertainty estimation with num_samples\n\n\n## Advanced Usage\n\n### Multivariate Prediction\n```python\n# 2D numpy array: time steps \u00d7 variables\nmultivariate_data = np.array([[20, 65], [21, 63], [22, 61], [19, 67]])\nresponse = client.predict(\n model_name='toto-open-base-1.0',\n data=multivariate_data,\n forecast_horizon=10,\n confidence_intervals=[0.8, 0.9, 0.95],\n num_samples=100\n)\n```\n\n### Context Manager\n```python\nwith TSFMClient() as client:\n response = client.predict(data=np.array([1, 2, 3, 4, 5]))\n print(response.forecast)\n```\n## Examples\n\nFor comprehensive examples including visualization and model comparison, see the [demo notebook](https://github.com/S-FM/tsfm-python-client/blob/main/examples/demo.ipynb).\n\n## Requirements\n\n- Python >= 3.10\n- Valid TSFM API key\n- Dependencies: numpy, pandas, httpx, pydantic\n\n## API Reference\n\n### TSFMClient.predict()\n\n```python\npredict(\n model_name: str = \"chronos-t5-small\",\n data: Union[np.ndarray, pd.Series, List[float], List[List[float]]],\n forecast_horizon: int = 12,\n confidence_intervals: Optional[List[float]] = None,\n num_samples: Optional[int] = None,\n time_interval_seconds: Optional[int] = None\n) -> PredictionResponse\n```\n\n**Parameters:**\n- `model_name`: Model to use ('chronos-t5-small' or 'toto-open-base-1.0')\n- `data`: Time series data (1D for univariate, 2D for multivariate)\n- `forecast_horizon`: Number of steps to predict\n- `confidence_intervals`: List of confidence levels (e.g., [0.8, 0.95])\n- `num_samples`: Number of samples for uncertainty estimation\n- `time_interval_seconds`: Time between data points in seconds\n\n**Returns:**\n- `PredictionResponse` with forecast, confidence intervals, and metadata\n\n## Roadmap\n\n- \ud83d\udd04 **Batch processing**: Process multiple time series in a single request\n- \ud83c\udfaf **More models**: Additional foundation models coming soon\n- \u2699\ufe0f **Fine-tuning**: Support for domain-specific model adaptation\n\n## License\n\nMIT License",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python client for TSFM time series forecasting with numpy support, confidence intervals, and multivariate predictions",
"version": "0.2.2",
"project_urls": {
"Homepage": "https://github.com/S-FM/tsfm-python-client",
"Repository": "https://github.com/S-FM/tsfm-python-client"
},
"split_keywords": [
"time-series",
" forecasting",
" foundation-models",
" api-client",
" numpy",
" multivariate",
" confidence-intervals",
" tsfm",
" chronos",
" toto"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "368b39f3a2ffa8a1d6f9685d08c6d25fa52945cd6b0c282a870a1c316f78c32d",
"md5": "668e4482e09cb94639e6c1a580cbe154",
"sha256": "1818bc1f93050e261cd55c08e03a6bc8627ac99f444367e5a80d3575a62db330"
},
"downloads": -1,
"filename": "tsfm_client-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "668e4482e09cb94639e6c1a580cbe154",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 8566,
"upload_time": "2025-08-07T18:12:15",
"upload_time_iso_8601": "2025-08-07T18:12:15.597944Z",
"url": "https://files.pythonhosted.org/packages/36/8b/39f3a2ffa8a1d6f9685d08c6d25fa52945cd6b0c282a870a1c316f78c32d/tsfm_client-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "01ee382b71301e518d42278e0245eed405ef366c9468a8815c4e7df4d0f32bb0",
"md5": "1275a8e18748f3b71763800e83106a41",
"sha256": "a7a9c1ff01ff85f9719f0a67931e026e18313c5c65930ed8985155babf661ba9"
},
"downloads": -1,
"filename": "tsfm_client-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "1275a8e18748f3b71763800e83106a41",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 7155,
"upload_time": "2025-08-07T18:12:17",
"upload_time_iso_8601": "2025-08-07T18:12:17.681421Z",
"url": "https://files.pythonhosted.org/packages/01/ee/382b71301e518d42278e0245eed405ef366c9468a8815c4e7df4d0f32bb0/tsfm_client-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 18:12:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "S-FM",
"github_project": "tsfm-python-client",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "tsfm-client"
}
JSON
