# Simulacrum SDK
A lightweight Python client for the Simulacrum time-series forecasting API. The SDK wraps Simulacrum's REST endpoints with type-safe models, error handling, and convenience helpers so you can focus on building forecasting workflows instead of wiring HTTP requests.
---
## Features
- 🔐 **Authenticated client** with automatic bearer-token headers
- 📈 **Forecast API wrapper** that serialises NumPy arrays transparently
- ✅ **API key validation** to inspect key status, client ID, and expiry
- 🚫 **Rich exceptions** that map Simulacrum error codes to Python types
- 🧪 **Tested models** built on Pydantic for strict data validation
---
## Installation
### From PyPI (recommended)
> Requires Python 3.8 or newer
```bash
pip install simulacrum-sdk
```
### From GitHub source
Install directly from the latest commit on the main repository:
```bash
pip install git+https://github.com/Smlcrm/simulacrum-sdk.git
```
To work with the sources locally for development (Python 3.8+):
```bash
git clone https://github.com/Smlcrm/simulacrum-sdk.git
cd simulacrum-sdk
python -m venv .venv
source .venv/bin/activate # On Windows use: .venv\Scripts\activate
pip install -e .[dev]
```
---
## Usage Overview
### Creating a client
```python
from simulacrum import Simulacrum
client = Simulacrum(api_key="sp_your_api_key")
```
If you are running a local version of the Simulacrum API (i.e., on-premise model hosting), override the base URL:
```python
client = Simulacrum(api_key="sp_your_api_key", base_url="https://staging.api.smlcrm.com")
```
### Validating an API key
Your forecast requests will fail if your API key is invalid. To check your API key is valid run the following.
```python
validation = client.validate()
print("Valid:", validation.valid)
print("Client ID:", validation.client)
```
### Requesting a forecast
```python
import numpy as np
series = np.array([102.4, 106.0, 108.3, 111.9])
forecast = client.forecast(series=series, horizon=3, model="default")
print("Next periods:", forecast)
```
The SDK returns a `numpy.ndarray` so you can pipe results into downstream analytics or visualisations immediately.
### Handling errors
All API error codes are mapped to dedicated exceptions. Catch them to distinguish between authentication, quota, and request issues:
```python
from simulacrum.exceptions import AuthError, QuotaExceededError, SimulacrumError
try:
client.forecast(series=[1, 2, 3], horizon=5, model="default")
except AuthError:
print("Check that your API key is correct and active.")
except QuotaExceededError:
print("You have reached your usage limit for the current period.")
except SimulacrumError as exc:
print(f"Unhandled Simulacrum error: {exc}")
```
---
## Tutorial: Forecast a Time Series in Five Steps
1. **Install the SDK**
```bash
pip install simulacrum-sdk
```
2. **Create a project structure**
```bash
mkdir simulacrum-sample && cd simulacrum-sample
python -m venv .venv
source .venv/bin/activate
pip install simulacrum-sdk
```
3. **Write a forecast script (`forecast_example.py`)**
```python
from simulacrum import Simulacrum
def main() -> None:
client = Simulacrum(api_key="sp_your_api_key")
series = [24.5, 25.1, 25.7, 26.2, 26.9]
forecast = client.forecast(series=series, horizon=3, model="default")
print("Forecast:", forecast.tolist())
if __name__ == "__main__":
main()
```
4. **Validate your API key (optional)**
```python
validation = client.validate()
if validation.valid:
print("Key is active until", validation.expires_at)
```
5. **Run the script**
```bash
python forecast_example.py
```
This workflow demonstrates the complete loop: initialising the client, requesting a forecast, and checking key status.
---
## Documentation
The public API is intentionally small:
| Component | Description |
|-----------|-------------|
| `simulacrum.Simulacrum` | High-level client exposing `forecast()` and `validate()` methods. |
| `simulacrum.models.ForecastRequest` | Pydantic model ensuring forecast payloads are well-formed. |
| `simulacrum.models.ForecastResponse` | Wraps forecast results and exposes `get_forecast()` to return a `numpy.ndarray`. |
| `simulacrum.models.ValidateAPIKeyResponse` | Validation metadata returned by `Simulacrum.validate()`. |
| `simulacrum.exceptions.*` | Custom error hierarchy mapping Simulacrum error codes to Python exceptions. |
Explore inline docstrings for detailed parameter and return type information. The tests in [`tests/test_client.py`](tests/test_client.py) demonstrate advanced usage patterns and validation behavior.
If you are contributing, run the suite with:
```bash
pip install -e .[dev]
python -m pytest
```
---
## License
MIT © Simulacrum, Inc.
Raw data
{
"_id": null,
"home_page": null,
"name": "simulacrum-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Simulacrum, time-series, forecasting, sdk",
"author": null,
"author_email": "\"Simulacrum, Inc.\" <support@smlcrm.com>",
"download_url": "https://files.pythonhosted.org/packages/11/b8/de3be99dd2c0f9acce3f4064ef4cf7f269fdf05fbe1ac3b4d5205257298e/simulacrum_sdk-0.2.2.tar.gz",
"platform": null,
"description": "![Simulacrum Logo](https://github.com/Smlcrm/assets/blob/main/Asset%201@4x-8.png?raw=true \"Simulacrum SDK\")\n\n# Simulacrum SDK\n\nA lightweight Python client for the Simulacrum time-series forecasting API. The SDK wraps Simulacrum's REST endpoints with type-safe models, error handling, and convenience helpers so you can focus on building forecasting workflows instead of wiring HTTP requests.\n\n---\n\n## Features\n\n- \ud83d\udd10 **Authenticated client** with automatic bearer-token headers\n- \ud83d\udcc8 **Forecast API wrapper** that serialises NumPy arrays transparently\n- \u2705 **API key validation** to inspect key status, client ID, and expiry\n- \ud83d\udeab **Rich exceptions** that map Simulacrum error codes to Python types\n- \ud83e\uddea **Tested models** built on Pydantic for strict data validation\n\n---\n\n## Installation\n\n### From PyPI (recommended)\n\n> Requires Python 3.8 or newer\n\n```bash\npip install simulacrum-sdk\n```\n\n### From GitHub source\n\nInstall directly from the latest commit on the main repository:\n\n```bash\npip install git+https://github.com/Smlcrm/simulacrum-sdk.git\n```\n\nTo work with the sources locally for development (Python 3.8+):\n\n```bash\ngit clone https://github.com/Smlcrm/simulacrum-sdk.git\ncd simulacrum-sdk\npython -m venv .venv\nsource .venv/bin/activate # On Windows use: .venv\\Scripts\\activate\npip install -e .[dev]\n```\n\n---\n\n## Usage Overview\n\n### Creating a client\n\n```python\nfrom simulacrum import Simulacrum\n\nclient = Simulacrum(api_key=\"sp_your_api_key\")\n```\n\nIf you are running a local version of the Simulacrum API (i.e., on-premise model hosting), override the base URL:\n\n```python\nclient = Simulacrum(api_key=\"sp_your_api_key\", base_url=\"https://staging.api.smlcrm.com\")\n```\n\n### Validating an API key\n\nYour forecast requests will fail if your API key is invalid. To check your API key is valid run the following.\n\n```python\nvalidation = client.validate()\nprint(\"Valid:\", validation.valid)\nprint(\"Client ID:\", validation.client)\n```\n\n### Requesting a forecast\n\n```python\nimport numpy as np\n\nseries = np.array([102.4, 106.0, 108.3, 111.9])\nforecast = client.forecast(series=series, horizon=3, model=\"default\")\n\nprint(\"Next periods:\", forecast)\n```\n\nThe SDK returns a `numpy.ndarray` so you can pipe results into downstream analytics or visualisations immediately.\n\n\n\n### Handling errors\n\nAll API error codes are mapped to dedicated exceptions. Catch them to distinguish between authentication, quota, and request issues:\n\n```python\nfrom simulacrum.exceptions import AuthError, QuotaExceededError, SimulacrumError\n\ntry:\n client.forecast(series=[1, 2, 3], horizon=5, model=\"default\")\nexcept AuthError:\n print(\"Check that your API key is correct and active.\")\nexcept QuotaExceededError:\n print(\"You have reached your usage limit for the current period.\")\nexcept SimulacrumError as exc:\n print(f\"Unhandled Simulacrum error: {exc}\")\n```\n\n---\n\n## Tutorial: Forecast a Time Series in Five Steps\n\n1. **Install the SDK**\n ```bash\n pip install simulacrum-sdk\n ```\n\n2. **Create a project structure**\n ```bash\n mkdir simulacrum-sample && cd simulacrum-sample\n python -m venv .venv\n source .venv/bin/activate\n pip install simulacrum-sdk\n ```\n\n3. **Write a forecast script (`forecast_example.py`)**\n ```python\n from simulacrum import Simulacrum\n\n def main() -> None:\n client = Simulacrum(api_key=\"sp_your_api_key\")\n series = [24.5, 25.1, 25.7, 26.2, 26.9]\n forecast = client.forecast(series=series, horizon=3, model=\"default\")\n print(\"Forecast:\", forecast.tolist())\n\n if __name__ == \"__main__\":\n main()\n ```\n\n4. **Validate your API key (optional)**\n ```python\n validation = client.validate()\n if validation.valid:\n print(\"Key is active until\", validation.expires_at)\n ```\n \n5. **Run the script**\n ```bash\n python forecast_example.py\n ```\n\nThis workflow demonstrates the complete loop: initialising the client, requesting a forecast, and checking key status.\n\n---\n\n## Documentation\n\nThe public API is intentionally small:\n\n| Component | Description |\n|-----------|-------------|\n| `simulacrum.Simulacrum` | High-level client exposing `forecast()` and `validate()` methods. |\n| `simulacrum.models.ForecastRequest` | Pydantic model ensuring forecast payloads are well-formed. |\n| `simulacrum.models.ForecastResponse` | Wraps forecast results and exposes `get_forecast()` to return a `numpy.ndarray`. |\n| `simulacrum.models.ValidateAPIKeyResponse` | Validation metadata returned by `Simulacrum.validate()`. |\n| `simulacrum.exceptions.*` | Custom error hierarchy mapping Simulacrum error codes to Python exceptions. |\n\nExplore inline docstrings for detailed parameter and return type information. The tests in [`tests/test_client.py`](tests/test_client.py) demonstrate advanced usage patterns and validation behavior.\n\nIf you are contributing, run the suite with:\n\n```bash\npip install -e .[dev]\npython -m pytest\n```\n\n---\n\n## License\n\nMIT \u00a9 Simulacrum, Inc.\n",
"bugtrack_url": null,
"license": null,
"summary": "Official Python SDK for accessing the Simulacrum API.",
"version": "0.2.2",
"project_urls": {
"Homepage": "https://smlcrm-tempo-api.readme.io/reference",
"Issues": "https://github.com/Smlcrm/simulacrum-sdk/issues",
"Repository": "https://github.com/Smlcrm/simulacrum-sdk"
},
"split_keywords": [
"simulacrum",
" time-series",
" forecasting",
" sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f3c339c44f510c908ba3ce309788fec74dc33ca0d59510700c93ca29f816c795",
"md5": "abae577ae2d576bd2387b286f70bb0ea",
"sha256": "1905e9a57fd7cfbf5e920687f13c39ceec5b32d215de2b787bacf435559480a7"
},
"downloads": -1,
"filename": "simulacrum_sdk-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "abae577ae2d576bd2387b286f70bb0ea",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11485,
"upload_time": "2025-10-30T05:34:59",
"upload_time_iso_8601": "2025-10-30T05:34:59.159474Z",
"url": "https://files.pythonhosted.org/packages/f3/c3/39c44f510c908ba3ce309788fec74dc33ca0d59510700c93ca29f816c795/simulacrum_sdk-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "11b8de3be99dd2c0f9acce3f4064ef4cf7f269fdf05fbe1ac3b4d5205257298e",
"md5": "12f017341092e5c448ca124dbad9c89d",
"sha256": "9ac85eb0e4e620411d670ca15c1ad836c323f06eb78ca67809f18a53ee10dbcf"
},
"downloads": -1,
"filename": "simulacrum_sdk-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "12f017341092e5c448ca124dbad9c89d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 14024,
"upload_time": "2025-10-30T05:35:00",
"upload_time_iso_8601": "2025-10-30T05:35:00.042344Z",
"url": "https://files.pythonhosted.org/packages/11/b8/de3be99dd2c0f9acce3f4064ef4cf7f269fdf05fbe1ac3b4d5205257298e/simulacrum_sdk-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-30 05:35:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Smlcrm",
"github_project": "simulacrum-sdk",
"github_not_found": true,
"lcname": "simulacrum-sdk"
}
JSON
