# Synthefy Python Client
A Python client for the Synthefy API forecasting service. This package provides an easy-to-use interface for making time series forecasting requests.
## Features
- **Simple API Client**: Easy-to-use client for making forecasting requests
- **Pandas Integration**: Built-in support for pandas DataFrames
- **Type Safety**: Full type hints and Pydantic validation
- **Flexible Data Handling**: Support for multiple data sources and metadata columns
## Installation
```bash
pip install synthefy
```
## Quick Start
### Basic Usage
```python
from synthefy import SynthefyAPIClient
import pandas as pd
# Initialize the client
client = SynthefyAPIClient(api_key="your_api_key_here")
# Or use environment variable
# export SYNTHEFY_API_KEY="your_api_key_here"
client = SynthefyAPIClient()
```
### Making a Forecast Request
```python
from synthefy import SynthefyAPIClient
from synthefy.data_models import ForecastV2Request
import pandas as pd
# Create sample data
history_data = {
'timestamp': ['2024-01-01', '2024-01-02', '2024-01-03'],
'sales': [100, 120, 110],
'temperature': [20, 22, 21]
}
target_data = {
'timestamp': ['2024-01-04', '2024-01-05', '2024-01-06'],
'sales': [None, None, None], # Values to forecast
'temperature': [23, 24, 22] # Known future values
}
history_df = pd.DataFrame(history_data)
target_df = pd.DataFrame(target_data)
# Create request using the convenience method
response = client.forecast_dfs(
history_dfs=[history_df],
target_dfs=[target_df],
target_col='sales',
timestamp_col='timestamp',
metadata_cols=['temperature'],
leak_cols=[], # No leak columns in this example
model='sfm_moe'
)
# response is a list of DataFrames with forecasts
forecast_df = response[0]
print(forecast_df)
```
### Advanced Usage with Multiple Data Sources
```python
# Multiple data sources
history_dfs = [history_df1, history_df2, history_df3]
target_dfs = [target_df1, target_df2, target_df3]
response = client.forecast_dfs(
history_dfs=history_dfs,
target_dfs=target_dfs,
target_col='revenue',
timestamp_col='date',
metadata_cols=['marketing_spend', 'competitor_price'],
leak_cols=['marketing_spend'], # This column is known in the future
model='sfm_moe'
)
# Each DataFrame in response corresponds to one data source
for i, forecast_df in enumerate(response):
print(f"Forecast for data source {i}:")
print(forecast_df)
```
## API Reference
### SynthefyAPIClient
The main client class for interacting with the Synthefy API.
#### Methods
- `forecast(request: ForecastV2Request) -> ForecastV2Response`: Make a direct forecast request
- `forecast_dfs(...) -> List[pd.DataFrame]`: Convenience method for working with pandas DataFrames
#### Parameters
- `api_key`: Your Synthefy API key (can also be set via `SYNTHEFY_API_KEY` environment variable)
- `timeout`: Request timeout in seconds (default: 120.0)
## Configuration
### Environment Variables
- `SYNTHEFY_API_KEY`: Your Synthefy API key
## Support
For support and questions:
- Email: contact@synthefy.com
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "synthefy",
"maintainer": null,
"docs_url": null,
"requires_python": "==3.11.*",
"maintainer_email": "Synthefy <contact@synthefy.com>",
"keywords": "api, forecasting, machine-learning, time-series",
"author": null,
"author_email": "Synthefy <contact@synthefy.com>",
"download_url": "https://files.pythonhosted.org/packages/76/3b/daca20f2cafd88780611858f03190a00948f8c01003c01e9d25edd96b660/synthefy-0.1.2.tar.gz",
"platform": null,
"description": "# Synthefy Python Client\n\nA Python client for the Synthefy API forecasting service. This package provides an easy-to-use interface for making time series forecasting requests.\n\n## Features\n\n- **Simple API Client**: Easy-to-use client for making forecasting requests\n- **Pandas Integration**: Built-in support for pandas DataFrames\n- **Type Safety**: Full type hints and Pydantic validation\n- **Flexible Data Handling**: Support for multiple data sources and metadata columns\n\n## Installation\n\n```bash\npip install synthefy\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom synthefy import SynthefyAPIClient\nimport pandas as pd\n\n# Initialize the client\nclient = SynthefyAPIClient(api_key=\"your_api_key_here\")\n\n# Or use environment variable\n# export SYNTHEFY_API_KEY=\"your_api_key_here\"\nclient = SynthefyAPIClient()\n```\n\n### Making a Forecast Request\n\n```python\nfrom synthefy import SynthefyAPIClient\nfrom synthefy.data_models import ForecastV2Request\nimport pandas as pd\n\n# Create sample data\nhistory_data = {\n 'timestamp': ['2024-01-01', '2024-01-02', '2024-01-03'],\n 'sales': [100, 120, 110],\n 'temperature': [20, 22, 21]\n}\n\ntarget_data = {\n 'timestamp': ['2024-01-04', '2024-01-05', '2024-01-06'],\n 'sales': [None, None, None], # Values to forecast\n 'temperature': [23, 24, 22] # Known future values\n}\n\nhistory_df = pd.DataFrame(history_data)\ntarget_df = pd.DataFrame(target_data)\n\n# Create request using the convenience method\nresponse = client.forecast_dfs(\n history_dfs=[history_df],\n target_dfs=[target_df],\n target_col='sales',\n timestamp_col='timestamp',\n metadata_cols=['temperature'],\n leak_cols=[], # No leak columns in this example\n model='sfm_moe'\n)\n\n# response is a list of DataFrames with forecasts\nforecast_df = response[0]\nprint(forecast_df)\n```\n\n### Advanced Usage with Multiple Data Sources\n\n```python\n# Multiple data sources\nhistory_dfs = [history_df1, history_df2, history_df3]\ntarget_dfs = [target_df1, target_df2, target_df3]\n\nresponse = client.forecast_dfs(\n history_dfs=history_dfs,\n target_dfs=target_dfs,\n target_col='revenue',\n timestamp_col='date',\n metadata_cols=['marketing_spend', 'competitor_price'],\n leak_cols=['marketing_spend'], # This column is known in the future\n model='sfm_moe'\n)\n\n# Each DataFrame in response corresponds to one data source\nfor i, forecast_df in enumerate(response):\n print(f\"Forecast for data source {i}:\")\n print(forecast_df)\n```\n\n## API Reference\n\n### SynthefyAPIClient\n\nThe main client class for interacting with the Synthefy API.\n\n#### Methods\n\n- `forecast(request: ForecastV2Request) -> ForecastV2Response`: Make a direct forecast request\n- `forecast_dfs(...) -> List[pd.DataFrame]`: Convenience method for working with pandas DataFrames\n\n#### Parameters\n\n- `api_key`: Your Synthefy API key (can also be set via `SYNTHEFY_API_KEY` environment variable)\n- `timeout`: Request timeout in seconds (default: 120.0)\n\n## Configuration\n\n### Environment Variables\n\n- `SYNTHEFY_API_KEY`: Your Synthefy API key\n\n## Support\n\nFor support and questions:\n- Email: contact@synthefy.com\n\n## License\n\nMIT License - see LICENSE file for details. ",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python client for the Synthefy API forecasting service",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://synthefy.com"
},
"split_keywords": [
"api",
" forecasting",
" machine-learning",
" time-series"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "35a292316a3981da8f802a0dcfdce2c3fc80134a200a288c082d429c59549213",
"md5": "ff809c15d1f071ea84ba3e19ba6ba939",
"sha256": "ff8c96336872fc7d1da21cd472fcba18269db730fc7d68b42c8a31d962f8d3bc"
},
"downloads": -1,
"filename": "synthefy-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ff809c15d1f071ea84ba3e19ba6ba939",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "==3.11.*",
"size": 6332,
"upload_time": "2025-08-18T22:41:15",
"upload_time_iso_8601": "2025-08-18T22:41:15.162526Z",
"url": "https://files.pythonhosted.org/packages/35/a2/92316a3981da8f802a0dcfdce2c3fc80134a200a288c082d429c59549213/synthefy-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "763bdaca20f2cafd88780611858f03190a00948f8c01003c01e9d25edd96b660",
"md5": "f8d006f9aba81c0cba060f8f039664a5",
"sha256": "f60e811ef871c295e28359cf49220581e164758014a1c3aa595448d0652307f3"
},
"downloads": -1,
"filename": "synthefy-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "f8d006f9aba81c0cba060f8f039664a5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "==3.11.*",
"size": 5761,
"upload_time": "2025-08-18T22:41:16",
"upload_time_iso_8601": "2025-08-18T22:41:16.287719Z",
"url": "https://files.pythonhosted.org/packages/76/3b/daca20f2cafd88780611858f03190a00948f8c01003c01e9d25edd96b660/synthefy-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 22:41:16",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "synthefy"
}
JSON