simulacrum-sdk 0.2.0__py3-none-any.whl → 0.2.4__py3-none-any.whl

simulacrum/__init__.py

@@ -12,4 +12,4 @@ Example:
 from .client import Simulacrum
 
 __all__ = ["Simulacrum", "__version__"]
-__version__: str = "0.2.0"
+__version__: str = "0.1.0"

simulacrum/_errors.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from .exceptions import (
+    ConflictError,
+    ForbiddenError,
+    HTTPClientError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    SimulacrumError,
+    UnauthorizedError,
+    ValidationError,
+)
+
+
+def _parse_retry_after(value: str) -> Optional[float]:
+    try:
+        return float(value)
+    except Exception:
+        try:
+            dt = datetime.strptime(value, "%a, %d %b %Y %H:%M:%S %Z")
+            return max(
+                0.0,
+                (dt.replace(tzinfo=timezone.utc) - datetime.now(timezone.utc)).total_seconds(),
+            )
+        except Exception:
+            return None
+
+
+def parse_error(response, *, service: str, endpoint: str) -> SimulacrumError:
+    status = getattr(response, "status_code")
+    headers = getattr(response, "headers", {}) or {}
+    req_id = headers.get("X-Request-ID")
+
+    error_type = "http_error"
+    message = f"HTTP {status}"
+    details = None
+    trace_id = None
+
+    # Try parse JSON body according to ErrorEnvelope
+    try:
+        data = response.json()
+        err = (data or {}).get("error") or {}
+        error_type = str(err.get("type") or error_type)
+        message = str(err.get("message") or message)
+        details = err.get("details")
+        trace_id = (data or {}).get("trace_id")
+    except Exception:
+        try:
+            text = response.text
+        except Exception:
+            text = None
+        if text:
+            message = str(text).strip()[:500]
+
+    common = dict(
+        service=service,
+        endpoint=endpoint,
+        status_code=status,
+        error_type=error_type,
+        message=message,
+        details=details,
+        trace_id_body=trace_id,
+        request_id_header=req_id,
+        response=response,
+    )
+
+    if status == 401:
+        return UnauthorizedError(**common)
+    if status == 403:
+        return ForbiddenError(**common)
+    if status == 404:
+        return NotFoundError(**common)
+    if status == 409:
+        return ConflictError(**common)
+    if status in (400, 422):
+        return ValidationError(**common)
+    if status == 429:
+        ra = headers.get("Retry-After")
+        return RateLimitError(**common, retry_after_seconds=_parse_retry_after(ra) if ra else None)
+    if 500 <= status <= 599:
+        return ServerError(**common)
+    if 400 <= status <= 499:
+        return HTTPClientError(**common)
+    return HTTPClientError(**common)
+
+
+def is_retryable(exc: SimulacrumError) -> bool:
+    return exc.status_code in {429, 500, 502, 503, 504}
+
+
+def retry_after(exc: RateLimitError) -> Optional[float]:
+    return getattr(exc, "retry_after_seconds", None)
+
+
+def extract_trace_id(exc: SimulacrumError) -> Optional[str]:
+    return exc.trace_id()
+
+

simulacrum/api.py

@@ -2,47 +2,44 @@
 
 from typing import Any, Dict, Mapping, Optional
 
-import requests
+import uuid
+import httpx
 
-from simulacrum.exceptions import ApiError, AuthError, ERROR_CODE_MAP
+from simulacrum._errors import parse_error
+
+
+def _infer_service_from_url(url: str) -> str:
+    lowered = url.lower()
+    if "/onsiteiq/" in lowered:
+        return "onsiteiq"
+    if "/tempo/" in lowered:
+        return "tempo"
+    return "tempo"
 
 
 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.
+    """Execute an HTTP request against the Simulacrum API and raise rich typed errors on failure.
 
     Args:
-        method (str): HTTP method to invoke (``"GET"``, ``"POST"``, ...).
+        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")
+    # Ensure we always send an X-Request-ID
+    merged_headers: Dict[str, str] = dict(headers)
+    merged_headers.setdefault("X-Request-ID", str(uuid.uuid4()))
 
-            if error_code in ERROR_CODE_MAP:
-                raise ERROR_CODE_MAP[error_code](message)
+    with httpx.Client(timeout=30) as client:
+        response = client.request(method=method, url=url, headers=merged_headers, json=json)
 
-            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:
+    if 200 <= response.status_code < 300:
+        # Let JSON decode errors propagate as ValueError to be consistent with prior behavior
         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
+
+    service = _infer_service_from_url(url)
+    endpoint = httpx.URL(url).path
+    raise parse_error(response, service=service, endpoint=endpoint)

simulacrum/client.py

@@ -41,7 +41,7 @@ class Simulacrum:
         }
 
     def forecast(
-        self, series: Sequence[float] | np.ndarray, horizon: int, model: str = "default"
+        self, series: Sequence[float] | np.ndarray, horizon: int | None = None, model: str = "default"
     ) -> np.ndarray:
         """Request a forecast for the provided time series.
 
@@ -86,6 +86,8 @@ class Simulacrum:
             series=series_to_send, horizon=horizon, model=model
         )
         request_body: Dict[str, Any] = payload.model_dump()
+        # Exclude optional fields that are None (e.g., horizon for onsiteiq)
+        request_body = payload.model_dump(exclude_none=True)
         response_data: Dict[str, Any] = send_request(
             method="POST",
             url=f"{self.base_url}/{model}/v1/forecast",
@@ -120,14 +122,4 @@ class Simulacrum:
             json=None,
         )
 
-        validation: ValidateAPIKeyResponse = ValidateAPIKeyResponse.model_validate(
-            response_data
-        )
-
-        status_message = "valid" if validation.valid else "invalid"
-        print(
-            "Simulacrum API key validation: "
-            f"{status_message} (status={validation.status.value}, env={validation.env}) "
-        )
-
-        return validation
+        return ValidateAPIKeyResponse.model_validate(response_data)

simulacrum/exceptions.py

@@ -1,42 +1,119 @@
-"""Custom exceptions raised by the Simulacrum SDK."""
+"""Custom exceptions raised by the Simulacrum SDK.
 
-from typing import Dict, Type
+This module defines a rich, typed hierarchy aligned with Simulacrum services' ErrorEnvelope
+and preserves backward compatibility with previously exported exception names.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Type
 
 
 class SimulacrumError(Exception):
-    """Base exception for all SDK errors."""
+    """Base exception for all SDK errors with structured fields."""
+
+    def __init__(
+        self,
+        *,
+        service: str,
+        endpoint: str,
+        status_code: int,
+        error_type: str,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+        trace_id_body: Optional[str] = None,
+        request_id_header: Optional[str] = None,
+        response: Any = None,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.service = service
+        self.endpoint = endpoint
+        self.status_code = status_code
+        self.error_type = error_type
+        self.message = message
+        self.details = details
+        self.trace_id_body = trace_id_body
+        self.request_id_header = request_id_header
+        self.response = response
+        self.context = context or {}
+
+    def trace_id(self) -> Optional[str]:
+        return self.trace_id_body or self.request_id_header
+
+    def __str__(self) -> str:
+        tid = self.trace_id()
+        tid_str = f" trace_id={tid}" if tid else ""
+        return f"[{self.service}] {self.status_code} {self.error_type}: {self.message}{tid_str}"
+
+
+class UnauthorizedError(SimulacrumError):
+    pass
+
+
+class ForbiddenError(SimulacrumError):
+    pass
+
+
+class NotFoundError(SimulacrumError):
+    pass
+
+
+class ConflictError(SimulacrumError):
+    pass
+
+
+class ValidationError(SimulacrumError):
+    pass
+
+
+class RateLimitError(SimulacrumError):
+    def __init__(
+        self, *args, retry_after_seconds: Optional[float] = None, **kwargs: Any
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self.retry_after_seconds = retry_after_seconds
+
+
+class ServerError(SimulacrumError):
+    pass
+
+
+class HTTPClientError(SimulacrumError):
+    pass
 
 
-class AuthError(SimulacrumError):
-    """Raised when authentication with the API fails."""
+# Backward compatibility aliases/classes
+class AuthError(UnauthorizedError):
+    """Raised when authentication with the API fails (back-compat)."""
 
 
-class ApiKeyExpiredError(SimulacrumError):
-    """Raised when the API key has expired."""
+class ApiKeyExpiredError(ForbiddenError):
+    """Raised when the API key has expired (back-compat)."""
 
 
-class ApiKeyInactiveError(SimulacrumError):
-    """Raised when the API key has been deactivated."""
+class ApiKeyInactiveError(ForbiddenError):
+    """Raised when the API key has been deactivated (back-compat)."""
 
 
-class ApiKeyInvalidError(AuthError):
-    """Raised when the API key is not recognised."""
+class ApiKeyInvalidError(UnauthorizedError):
+    """Raised when the API key is not recognised (back-compat)."""
 
 
-class ForecastAlreadyRunningError(SimulacrumError):
-    """Raised when a forecast job is already in progress."""
+class ForecastAlreadyRunningError(ConflictError):
+    """Raised when a forecast job is already in progress (back-compat)."""
 
 
-class InvalidRequestError(SimulacrumError):
-    """Raised when the request payload is malformed."""
+class InvalidRequestError(ValidationError):
+    """Raised when the request payload is malformed (back-compat)."""
 
 
-class QuotaExceededError(SimulacrumError):
-    """Raised when the API usage quota has been exhausted."""
+class QuotaExceededError(RateLimitError):
+    """Raised when the API usage quota has been exhausted (back-compat)."""
 
 
-class ApiError(SimulacrumError):
-    """Catch-all for unclassified API errors."""
+class ApiError(HTTPClientError):
+    """Catch-all for unclassified API errors (back-compat)."""
 
 
 ERROR_CODE_MAP: Dict[str, Type[SimulacrumError]] = {

simulacrum/models.py

@@ -2,10 +2,9 @@
 
 from datetime import datetime
 from typing import List, Optional, Sequence, Union
-from enum import Enum
 
 import numpy as np
-from pydantic import BaseModel, field_validator, Field, constr
+from pydantic import BaseModel, field_validator, model_validator
 
 
 class ForecastRequest(BaseModel):
@@ -13,7 +12,7 @@ class ForecastRequest(BaseModel):
 
     Attributes:
         series (list[float]): Historical observations used as forecast input.
-        horizon (int): Number of future periods to predict.
+        horizon (int | None): Number of future periods to predict. Optional for the ``"onsiteiq"`` model.
         model (str | None): Identifier of the forecasting model, defaults to ``"default"``.
 
     Example:
@@ -23,8 +22,9 @@ class ForecastRequest(BaseModel):
         {'series': [1.0, 2.0, 3.0], 'horizon': 2, 'model': 'default'}
     """
 
-    series: List[float]
-    horizon: int
+    # TODO: It must be List[List[float]] (num_steps, num_series) remove after refactoring
+    series: Union[List[float], List[List[float]]]
+    horizon: Optional[int] = None
     model: Optional[str] = "default"
 
     @field_validator("series", mode="before")
@@ -42,6 +42,23 @@ class ForecastRequest(BaseModel):
             return value.astype(float).tolist()
         return list(value)
 
+    @model_validator(mode="after")
+    def _validate_horizon_requirement(self):
+        # Horizon is required for all models except onsiteiq
+        model_name = (self.model or "").lower()
+        if model_name != "onsiteiq" and self.horizon is None:
+            raise ValueError("horizon is required and must be a positive integer for this model")
+
+        # When provided, horizon must be an integer >= 1
+        if self.horizon is not None:
+            if not isinstance(self.horizon, int):
+                raise ValueError(
+                    f"horizon must be an integer (got {type(self.horizon).__name__})"
+                )
+            if self.horizon < 1:
+                raise ValueError("horizon must be >= 1")
+        return self
+
 
 class ForecastResponse(BaseModel):
     """Forecast output returned by the API.
@@ -57,7 +74,7 @@ class ForecastResponse(BaseModel):
         [4.2, 4.8]
     """
 
-    forecast: List[float]
+    forecast: Union[List[float], List[List[float]]]
 
     def get_forecast(self) -> np.ndarray:
         """Return forecast values as a numpy array for downstream processing.
@@ -68,39 +85,23 @@ class ForecastResponse(BaseModel):
         return np.array(self.forecast, dtype=float)
 
 
-class ApiKeyStatus(str, Enum):
-    """Possible statuses for an API key."""
-
-    active = "active"
-    deprecated = "deprecated"
-    disabled = "disabled"
-
-
-class ApiKeyStatusHistoryEntry(BaseModel):
-    """API key status history entry."""
-
-    status: ApiKeyStatus
-    changed_at: datetime
-
-    class Config:
-        extra = "forbid"
-
-
 class ValidateAPIKeyResponse(BaseModel):
-    """Structured representation of an API key validation response."""
+    """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
-    key_id: constr(pattern=r"^[A-Za-z0-9]+$")
-    status: ApiKeyStatus
-    env: constr(pattern=r"^(live|test)$")
-    project_id: str
-    organization_id: str
-    user_id: str
-    product_id: str
-    name: constr(min_length=1, max_length=255)
-    expires_at: Optional[datetime] = None
-    rate_limit_per_minute: int = Field(ge=1)
-    rate_limit_per_hour: int = Field(ge=1)
-
-    class Config:
-        extra = "forbid"
+    client: Optional[str] = None
+    key_id: Optional[str] = None
+    expires_at: Optional[datetime]
+
+    @model_validator(mode="after")
+    def _coalesce_client(self):
+        # Prefer explicit client; fall back to key_id when provided by API
+        if not self.client and self.key_id:
+            self.client = self.key_id
+        return self

{simulacrum_sdk-0.2.0.dist-info → simulacrum_sdk-0.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulacrum-sdk
-Version: 0.2.0
+Version: 0.2.4
 Summary: Official Python SDK for accessing the Simulacrum API.
 Author-email: "Simulacrum, Inc." <support@smlcrm.com>
 License-Expression: MIT
@@ -22,7 +22,7 @@ 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: httpx<1,>=0.27
 Requires-Dist: pydantic<3,>=2.0
 Requires-Dist: numpy>=1.24
 Provides-Extra: dev

simulacrum_sdk-0.2.4.dist-info/RECORD

@@ -0,0 +1,12 @@
+simulacrum/__init__.py,sha256=RUetyuqgZ35UgPPcKHJAxqyh8aNkuB8AMWIevCc3iew,437
+simulacrum/_errors.py,sha256=lE6I8c4uL7HC6orHBJ5B1kz7x5NKDHd3mP2yjpQjeIg,2803
+simulacrum/api.py,sha256=dj1xF6KfBLHMML0AicnoHElRzaNjPxooQxBARX219c0,1645
+simulacrum/client.py,sha256=uV3OlCCetni-O3-ESYtQcT8SR3MMj5MercatbH6YkrI,5026
+simulacrum/config.py,sha256=n3iN-cVUF3ucINS3iydDgMnFoMtVxDeVBIQwGiMKNk8,157
+simulacrum/exceptions.py,sha256=YrqoQjaPcZI31PmXd5evOl4fQjzxmz2sc8a3dSzkAMI,3408
+simulacrum/models.py,sha256=_lRcIc0kSwrlTkJmsfj2SK9O2fB7oQz9FACbS_s8B2o,3906
+simulacrum_sdk-0.2.4.dist-info/licenses/LICENSE,sha256=A7B9zAs2uCAzJoZPPyJW0G86yM-BTyum90vD4nSsOe0,1084
+simulacrum_sdk-0.2.4.dist-info/METADATA,sha256=hPAAYiBNWUrnvozwCrCGsir1c8M1sS9Nxagbi0iQVjk,6326
+simulacrum_sdk-0.2.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+simulacrum_sdk-0.2.4.dist-info/top_level.txt,sha256=CLUzfwEa7vZDf6zBAH8eXC2lZLMtj92MlXHOc3-V16o,11
+simulacrum_sdk-0.2.4.dist-info/RECORD,,

simulacrum_sdk-0.2.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-simulacrum/__init__.py,sha256=yzQa-yO8unFv9uKF0gj-o3VoYT_t51-SAatr-KTKyzk,437
-simulacrum/api.py,sha256=IZ8qNikv81Wd2l3VuaiGcLTjLOIzoxMfrbkQLwK0usg,1889
-simulacrum/client.py,sha256=kjPnb0nAuf9djDCR8DNJ3VtPASrr7aFGDx6upN48ygk,5183
-simulacrum/config.py,sha256=n3iN-cVUF3ucINS3iydDgMnFoMtVxDeVBIQwGiMKNk8,157
-simulacrum/exceptions.py,sha256=6VjdyJaFx9c8nE8iIezJH6pWkdRBHRs5ORdEZUrbJmg,1289
-simulacrum/models.py,sha256=V14jf_dcRGaBbYyKdy8c9w0yDLD5yqqE5qYvgG0ocTk,3157
-simulacrum_sdk-0.2.0.dist-info/licenses/LICENSE,sha256=A7B9zAs2uCAzJoZPPyJW0G86yM-BTyum90vD4nSsOe0,1084
-simulacrum_sdk-0.2.0.dist-info/METADATA,sha256=gFjEmlvV5UALjRP2M5NZpzm6sdIJQdKBlka8cd5NPmY,6329
-simulacrum_sdk-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-simulacrum_sdk-0.2.0.dist-info/top_level.txt,sha256=CLUzfwEa7vZDf6zBAH8eXC2lZLMtj92MlXHOc3-V16o,11
-simulacrum_sdk-0.2.0.dist-info/RECORD,,