simulacrum-sdk 0.1.0__tar.gz

simulacrum_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Simulacrum SDK contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

simulacrum_sdk-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include LICENSE
+include README.md

simulacrum_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: simulacrum-sdk
+Version: 0.1.0
+Summary: Official Python SDK for accessing the Simulacrum API.
+Author-email: "Simulacrum, Inc." <support@smlcrm.com>
+License-Expression: MIT
+Project-URL: Homepage, https://smlcrm-tempo-api.readme.io/reference
+Project-URL: Repository, https://github.com/Smlcrm/simulacrum-sdk
+Project-URL: Issues, https://github.com/Smlcrm/simulacrum-sdk/issues
+Keywords: Simulacrum,time-series,forecasting,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.28
+Requires-Dist: pydantic<3,>=2.0
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+![Simulacrum Logo](https://github.com/Smlcrm/assets/blob/main/Asset%201@4x-8.png?raw=true "Simulacrum SDK")
+
+# 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.

simulacrum_sdk-0.1.0/README.md

@@ -0,0 +1,179 @@
+![Simulacrum Logo](https://github.com/Smlcrm/assets/blob/main/Asset%201@4x-8.png?raw=true "Simulacrum SDK")
+
+# 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.

simulacrum_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "simulacrum-sdk"
+version = "0.1.0"
+description = "Official Python SDK for accessing the Simulacrum API."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+authors = [
+    { name = "Simulacrum, Inc.", email = "support@smlcrm.com" }
+]
+keywords = ["Simulacrum", "time-series", "forecasting", "sdk"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence"
+]
+dependencies = [
+    "requests>=2.28,<3",
+    "pydantic>=2.0,<3",
+    "numpy>=1.24"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "build>=1.2",
+    "twine>=5.0"
+]
+
+[project.urls]
+Homepage = "https://smlcrm-tempo-api.readme.io/reference"
+Repository = "https://github.com/Smlcrm/simulacrum-sdk"
+Issues = "https://github.com/Smlcrm/simulacrum-sdk/issues"
+
+[tool.setuptools.packages.find]
+include = ["simulacrum*"]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]

simulacrum_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

simulacrum_sdk-0.1.0/simulacrum/__init__.py

@@ -0,0 +1,15 @@
+"""Simulacrum SDK public interface.
+
+This package exposes the primary client you will use to interact with the
+Simulacrum forecasting API.
+
+Example:
+    >>> from simulacrum import Simulacrum
+    >>> client = Simulacrum(api_key="sp_your_api_key")
+    >>> forecast = client.forecast(series=[1.0, 1.5, 2.0], horizon=3, model="default")
+"""
+
+from .client import Simulacrum
+
+__all__ = ["Simulacrum", "__version__"]
+__version__: str = "0.1.0"

simulacrum_sdk-0.1.0/simulacrum/api.py

@@ -0,0 +1,48 @@
+"""Low-level HTTP helpers used by the Simulacrum client."""
+
+from typing import Any, Dict, Mapping, Optional
+
+import requests
+
+from simulacrum.exceptions import ApiError, AuthError, ERROR_CODE_MAP
+
+
+def send_request(method: str, url: str, headers: Mapping[str, str], json: Optional[Mapping[str, Any]]) -> Dict[str, Any]:
+    """Execute an HTTP request against the Simulacrum API and handle common errors.
+
+    Args:
+        method (str): HTTP method to invoke (``"GET"``, ``"POST"``, ...).
+        url (str): Fully-qualified endpoint URL.
+        headers (Mapping[str, str]): HTTP headers that include authorization and content type.
+        json (Mapping[str, Any] | None): JSON-serialisable payload for the request body.
+
+    Returns:
+        dict[str, Any]: Parsed JSON payload returned by the API.
+
+    Raises:
+        AuthError: Raised when the API reports an authentication failure.
+        ApiError: Raised for all other non-success responses or malformed data.
+    """
+    response = requests.request(method=method, url=url, headers=dict(headers), json=json)
+
+    if not response.ok:
+        try:
+            data: Dict[str, Any] = response.json()
+            error_code: Optional[str] = data.get("error_code")
+            message: str = data.get("message", "Unknown error")
+
+            if error_code in ERROR_CODE_MAP:
+                raise ERROR_CODE_MAP[error_code](message)
+
+            if response.status_code == 401:
+                raise AuthError(message)
+
+            raise ApiError(f"API error {response.status_code}: {message}")
+
+        except ValueError as exc:
+            raise ApiError(f"Unexpected API error: {response.text}") from exc
+
+    try:
+        return response.json()  # type: ignore[return-value]
+    except ValueError as exc:  # requests raises ValueError for JSON decode errors
+        raise ApiError(f"Failed to parse response JSON: {exc}") from exc

simulacrum_sdk-0.1.0/simulacrum/client.py

@@ -0,0 +1,122 @@
+"""High-level client for interacting with the Simulacrum forecasting API."""
+
+from typing import Any, Dict, Sequence
+
+import numpy as np
+
+from simulacrum.api import send_request
+from simulacrum.config import BASE_URL
+from simulacrum.exceptions import ApiError, AuthError
+from simulacrum.models import ForecastRequest, ForecastResponse, ValidateAPIKeyResponse
+
+
+class Simulacrum:
+    """Client wrapper around Simulacrum's REST API.
+
+    Example:
+        >>> from simulacrum import Simulacrum
+        >>> client = Simulacrum(api_key="sp_example_key")
+        >>> forecast = client.forecast(series=[1.0, 1.1, 1.2], horizon=2, model="default")
+        >>> forecast.shape
+        (2,)
+    """
+
+    def __init__(self, api_key: str, base_url: str = BASE_URL) -> None:
+        """Create a client that can issue authenticated requests to Simulacrum.
+
+        Args:
+            api_key (str): Simulacrum API key that authorizes requests.
+            base_url (str): Base URL for the API; defaults to the production endpoint.
+        """
+        if not isinstance(api_key, str) or not api_key.strip():
+            raise TypeError("api_key must be a non-empty string.")
+        if not isinstance(base_url, str) or not base_url.strip():
+            raise TypeError("base_url must be a non-empty string.")
+
+        self.api_key: str = api_key
+        self.base_url: str = base_url
+        self.headers: Dict[str, str] = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    def forecast(
+        self, series: Sequence[float] | np.ndarray, horizon: int, model: str = "default"
+    ) -> np.ndarray:
+        """Request a forecast for the provided time series.
+
+        Args:
+            series (Sequence[float] | numpy.ndarray): One-dimensional historical observations used as
+                forecast input.
+            horizon (int): Number of future periods to predict.
+            model (str): Identifier of the forecasting model, for example ``"default"``.
+
+        Returns:
+            numpy.ndarray: Array containing the forecasted values in chronological order.
+
+        Raises:
+            TypeError: ``series`` is not a numpy array or sequence of numeric values.
+            ValueError: ``series`` is a numpy array or sequence with dimensionality other than one.
+            ApiError: The API returned an error response.
+            AuthError: Authentication failed for the provided API key.
+        """
+        if isinstance(series, np.ndarray):
+            if series.ndim != 1:
+                raise ValueError("series must be a one-dimensional numpy array.")
+            series_to_send = series.astype(float)
+        elif isinstance(series, Sequence):
+            if isinstance(series, (str, bytes)):
+                raise TypeError(
+                    "series must be a one-dimensional numpy array or sequence of floats."
+                )
+            try:
+                series_to_send = np.asarray(list(series), dtype=float)
+            except (TypeError, ValueError) as exc:
+                raise TypeError(
+                    "series must be a one-dimensional numpy array or sequence of floats."
+                ) from exc
+            if series_to_send.ndim != 1:
+                raise ValueError("series must be one-dimensional.")
+        else:
+            raise TypeError(
+                "series must be a one-dimensional numpy array or sequence of floats."
+            )
+
+        payload: ForecastRequest = ForecastRequest(
+            series=series_to_send, horizon=horizon, model=model
+        )
+        request_body: Dict[str, Any] = payload.model_dump()
+        response_data: Dict[str, Any] = send_request(
+            method="POST",
+            url=f"{self.base_url}/v1/forecast",
+            headers=self.headers,
+            json=request_body,
+        )
+        validated_response: ForecastResponse = ForecastResponse.model_validate(
+            response_data
+        )
+        return validated_response.get_forecast()
+
+    def validate(self) -> ValidateAPIKeyResponse:
+        """Validate the configured API key and return its metadata.
+
+        Returns:
+            ValidateAPIKeyResponse: Structured validation details including key status and expiration date.
+
+        Raises:
+            AuthError: The API key is invalid or unauthorized.
+            ApiError: An unexpected API error occurred.
+
+        Example:
+            >>> client = Simulacrum(api_key="sp_example_key")
+            >>> validation = client.validate()
+            >>> validation.valid
+            True
+        """
+        response_data: Dict[str, Any] = send_request(
+            method="GET",
+            url=f"{self.base_url}/v1/validate",
+            headers=self.headers,
+            json=None,
+        )
+        return ValidateAPIKeyResponse.model_validate(response_data)

simulacrum_sdk-0.1.0/simulacrum/config.py

@@ -0,0 +1,4 @@
+"""Runtime configuration constants for the Simulacrum SDK."""
+
+BASE_URL: str = "https://api.smlcrm.com/"
+"""Default base URL for Simulacrum API requests."""

simulacrum_sdk-0.1.0/simulacrum/exceptions.py

@@ -0,0 +1,49 @@
+"""Custom exceptions raised by the Simulacrum SDK."""
+
+from typing import Dict, Type
+
+
+class SimulacrumError(Exception):
+    """Base exception for all SDK errors."""
+
+
+class AuthError(SimulacrumError):
+    """Raised when authentication with the API fails."""
+
+
+class ApiKeyExpiredError(SimulacrumError):
+    """Raised when the API key has expired."""
+
+
+class ApiKeyInactiveError(SimulacrumError):
+    """Raised when the API key has been deactivated."""
+
+
+class ApiKeyInvalidError(AuthError):
+    """Raised when the API key is not recognised."""
+
+
+class ForecastAlreadyRunningError(SimulacrumError):
+    """Raised when a forecast job is already in progress."""
+
+
+class InvalidRequestError(SimulacrumError):
+    """Raised when the request payload is malformed."""
+
+
+class QuotaExceededError(SimulacrumError):
+    """Raised when the API usage quota has been exhausted."""
+
+
+class ApiError(SimulacrumError):
+    """Catch-all for unclassified API errors."""
+
+
+ERROR_CODE_MAP: Dict[str, Type[SimulacrumError]] = {
+    "API_KEY_EXPIRED": ApiKeyExpiredError,
+    "API_KEY_INVALID": ApiKeyInvalidError,
+    "API_KEY_INACTIVE": ApiKeyInactiveError,
+    "API_USAGE_LIMIT": QuotaExceededError,
+    "REQUEST_INVALID": InvalidRequestError,
+    "FORECAST_ALREADY_RUNNING": ForecastAlreadyRunningError,
+}

simulacrum_sdk-0.1.0/simulacrum/models.py

@@ -0,0 +1,82 @@
+"""Data models that map request and response payloads for the Simulacrum API."""
+
+from datetime import datetime
+from typing import List, Optional, Sequence, Union
+
+import numpy as np
+from pydantic import BaseModel, field_validator
+
+
+class ForecastRequest(BaseModel):
+    """Payload submitted to the Simulacrum forecast endpoint.
+
+    Attributes:
+        series (list[float]): Historical observations used as forecast input.
+        horizon (int): Number of future periods to predict.
+        model (str | None): Identifier of the forecasting model, defaults to ``"default"``.
+
+    Example:
+        >>> from simulacrum.models import ForecastRequest
+        >>> payload = ForecastRequest(series=[1.0, 2.0, 3.0], horizon=2, model="default")
+        >>> payload.model_dump()
+        {'series': [1.0, 2.0, 3.0], 'horizon': 2, 'model': 'default'}
+    """
+
+    series: List[float]
+    horizon: int
+    model: Optional[str] = "default"
+
+    @field_validator("series", mode="before")
+    @classmethod
+    def _ensure_series_list(cls, value: Union[np.ndarray, Sequence[float]]) -> List[float]:  # type: ignore[override]
+        """Normalise the series field to ``list[float]``.
+
+        Args:
+            value (numpy.ndarray | Sequence[float]): Incoming value from caller.
+
+        Returns:
+            list[float]: Serialisable list of floats.
+        """
+        if isinstance(value, np.ndarray):
+            return value.astype(float).tolist()
+        return list(value)
+
+
+class ForecastResponse(BaseModel):
+    """Forecast output returned by the API.
+
+    Attributes:
+        forecast (list[float]): Forecasted values returned by the service.
+        model_used (str): Identifier of the model the backend selected.
+
+    Example:
+        >>> from simulacrum.models import ForecastResponse
+        >>> response = ForecastResponse(forecast=[4.2, 4.8], model_used="default")
+        >>> response.get_forecast().tolist()
+        [4.2, 4.8]
+    """
+
+    forecast: List[float]
+    model_used: str
+
+    def get_forecast(self) -> np.ndarray:
+        """Return forecast values as a numpy array for downstream processing.
+
+        Returns:
+            numpy.ndarray: Forecast data cast to an array of floats.
+        """
+        return np.array(self.forecast, dtype=float)
+
+
+class ValidateAPIKeyResponse(BaseModel):
+    """Metadata describing the validity of an API key.
+
+    Attributes:
+        valid (bool): Indicates whether the API key is currently valid.
+        client (str): Identifier of the owning client account.
+        expires_at (datetime | None): Expiration timestamp if provided by the API.
+    """
+
+    valid: bool
+    client: str
+    expires_at: Optional[datetime]

simulacrum_sdk-0.1.0/simulacrum_sdk.egg-info/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: simulacrum-sdk
+Version: 0.1.0
+Summary: Official Python SDK for accessing the Simulacrum API.
+Author-email: "Simulacrum, Inc." <support@smlcrm.com>
+License-Expression: MIT
+Project-URL: Homepage, https://smlcrm-tempo-api.readme.io/reference
+Project-URL: Repository, https://github.com/Smlcrm/simulacrum-sdk
+Project-URL: Issues, https://github.com/Smlcrm/simulacrum-sdk/issues
+Keywords: Simulacrum,time-series,forecasting,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.28
+Requires-Dist: pydantic<3,>=2.0
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+![Simulacrum Logo](https://github.com/Smlcrm/assets/blob/main/Asset%201@4x-8.png?raw=true "Simulacrum SDK")
+
+# 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.

simulacrum_sdk-0.1.0/simulacrum_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+simulacrum/__init__.py
+simulacrum/api.py
+simulacrum/client.py
+simulacrum/config.py
+simulacrum/exceptions.py
+simulacrum/models.py
+simulacrum_sdk.egg-info/PKG-INFO
+simulacrum_sdk.egg-info/SOURCES.txt
+simulacrum_sdk.egg-info/dependency_links.txt
+simulacrum_sdk.egg-info/requires.txt
+simulacrum_sdk.egg-info/top_level.txt
+tests/test_client.py

simulacrum_sdk-0.1.0/simulacrum_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

simulacrum_sdk-0.1.0/simulacrum_sdk.egg-info/requires.txt

@@ -0,0 +1,8 @@
+requests<3,>=2.28
+pydantic<3,>=2.0
+numpy>=1.24
+
+[dev]
+pytest>=8.0
+build>=1.2
+twine>=5.0

simulacrum_sdk-0.1.0/simulacrum_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+simulacrum

simulacrum_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,113 @@
+import numpy as np
+import pytest
+from pydantic import ValidationError
+
+import simulacrum.client as simulacrum_client
+
+
+@pytest.fixture
+def client():
+    return simulacrum_client.Simulacrum("super-secret-key", base_url="https://api.test")
+
+
+def test_client_initializes_expected_headers(client):
+    assert client.headers["Authorization"] == "Bearer super-secret-key"
+    assert client.headers["Content-Type"] == "application/json"
+
+
+def test_validate_invokes_send_request_and_parses_response(client, monkeypatch):
+    captured = {}
+
+    def fake_send_request(method, url, headers, json):
+        captured["method"] = method
+        captured["url"] = url
+        captured["headers"] = headers
+        captured["json"] = json
+        return {
+            "valid": True,
+            "client": "client-123",
+            "expires_at": "2024-01-01T00:00:00Z",
+        }
+
+    monkeypatch.setattr(simulacrum_client, "send_request", fake_send_request)
+
+    response = client.validate()
+
+    assert captured == {
+        "method": "GET",
+        "url": "https://api.test/v1/validate",
+        "headers": client.headers,
+        "json": None,
+    }
+    assert response.valid is True
+    assert response.client == "client-123"
+
+
+def test_forecast_builds_payload_and_returns_numpy_array(client, monkeypatch):
+    captured_payload = {}
+
+    class DummyRequest:
+        def __init__(self, *, series, horizon, model):
+            captured_payload["series"] = (
+                series.tolist() if hasattr(series, "tolist") else series
+            )
+            captured_payload["horizon"] = horizon
+            captured_payload["model"] = model
+
+        def model_dump(self):
+            return {
+                "series": captured_payload["series"],
+                "horizon": captured_payload["horizon"],
+                "model": captured_payload["model"],
+            }
+
+    def fake_send_request(method, url, headers, json):
+        captured_payload["method"] = method
+        captured_payload["url"] = url
+        captured_payload["headers"] = headers
+        captured_payload["json"] = json
+        return {
+            "forecast": [3.1, 3.9],
+            "model_used": "prophet",
+        }
+
+    monkeypatch.setattr(simulacrum_client, "ForecastRequest", DummyRequest)
+    monkeypatch.setattr(simulacrum_client, "send_request", fake_send_request)
+
+    series = np.array([1.0, 2.0, 3.0])
+
+    forecast = client.forecast(series=series, horizon=2, model="prophet")
+
+    assert captured_payload["series"] == [1.0, 2.0, 3.0]
+    assert captured_payload["horizon"] == 2
+    assert captured_payload["model"] == "prophet"
+    assert captured_payload["method"] == "POST"
+    assert captured_payload["url"] == "https://api.test/v1/forecast"
+    assert captured_payload["headers"] == client.headers
+    assert captured_payload["json"] == {
+        "series": [1.0, 2.0, 3.0],
+        "horizon": 2,
+        "model": "prophet",
+    }
+    assert isinstance(forecast, np.ndarray)
+    assert np.allclose(forecast, np.array([3.1, 3.9]))
+
+
+def test_forecast_rejects_non_numeric_series(client):
+    with pytest.raises(TypeError):
+        client.forecast(series=["a", "b"], horizon=2, model="default")
+
+
+def test_forecast_rejects_multidimensional_input(client):
+    with pytest.raises(ValueError):
+        client.forecast(series=[[1.0, 2.0], [3.0, 4.0]], horizon=2, model="default")
+
+
+def test_forecast_rejects_non_integer_horizon(client):
+    with pytest.raises(ValidationError):
+        client.forecast(series=[1.0, 2.0], horizon="two", model="default")
+
+
+def test_client_requires_string_api_key():
+    with pytest.raises(TypeError):
+        simulacrum_client.Simulacrum(api_key=None)  # type: ignore[arg-type]