simulacrum-sdk 0.1.0__tar.gz → 0.2.1__tar.gz

{simulacrum_sdk-0.1.0/simulacrum_sdk.egg-info → simulacrum_sdk-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulacrum-sdk
-Version: 0.1.0
+Version: 0.2.1
 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.1.0 → simulacrum_sdk-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulacrum-sdk"
-version = "0.1.0"
+version = "0.2.1"
 description = "Official Python SDK for accessing the Simulacrum API."
 readme = "README.md"
 requires-python = ">=3.8"
@@ -27,7 +27,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Artificial Intelligence"
 ]
 dependencies = [
-    "requests>=2.28,<3",
+    "httpx>=0.27,<1",
     "pydantic>=2.0,<3",
     "numpy>=1.24"
 ]

simulacrum_sdk-0.2.1/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_sdk-0.2.1/simulacrum/api.py

@@ -0,0 +1,45 @@
+"""Low-level HTTP helpers used by the Simulacrum client."""
+
+from typing import Any, Dict, Mapping, Optional
+
+import uuid
+import httpx
+
+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 raise rich typed errors on failure.
+
+    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.
+    """
+    # Ensure we always send an X-Request-ID
+    merged_headers: Dict[str, str] = dict(headers)
+    merged_headers.setdefault("X-Request-ID", str(uuid.uuid4()))
+
+    with httpx.Client(timeout=30) as client:
+        response = client.request(method=method, url=url, headers=merged_headers, json=json)
+
+    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]
+
+    service = _infer_service_from_url(url)
+    endpoint = httpx.URL(url).path
+    raise parse_error(response, service=service, endpoint=endpoint)

{simulacrum_sdk-0.1.0 → simulacrum_sdk-0.2.1}/simulacrum/client.py

@@ -88,7 +88,7 @@ class Simulacrum:
         request_body: Dict[str, Any] = payload.model_dump()
         response_data: Dict[str, Any] = send_request(
             method="POST",
-            url=f"{self.base_url}/v1/forecast",
+            url=f"{self.base_url}/{model}/v1/forecast",
             headers=self.headers,
             json=request_body,
         )
@@ -97,7 +97,7 @@ class Simulacrum:
         )
         return validated_response.get_forecast()
 
-    def validate(self) -> ValidateAPIKeyResponse:
+    def validate(self, model: str = "tempo") -> ValidateAPIKeyResponse:
         """Validate the configured API key and return its metadata.
 
         Returns:
@@ -115,8 +115,9 @@ class Simulacrum:
         """
         response_data: Dict[str, Any] = send_request(
             method="GET",
-            url=f"{self.base_url}/v1/validate",
+            url=f"{self.base_url}/{model}/v1/validate",
             headers=self.headers,
             json=None,
         )
+
         return ValidateAPIKeyResponse.model_validate(response_data)

simulacrum_sdk-0.2.1/simulacrum/exceptions.py

@@ -0,0 +1,126 @@
+"""Custom exceptions raised by the Simulacrum SDK.
+
+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 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
+
+
+# Backward compatibility aliases/classes
+class AuthError(UnauthorizedError):
+    """Raised when authentication with the API fails (back-compat)."""
+
+
+class ApiKeyExpiredError(ForbiddenError):
+    """Raised when the API key has expired (back-compat)."""
+
+
+class ApiKeyInactiveError(ForbiddenError):
+    """Raised when the API key has been deactivated (back-compat)."""
+
+
+class ApiKeyInvalidError(UnauthorizedError):
+    """Raised when the API key is not recognised (back-compat)."""
+
+
+class ForecastAlreadyRunningError(ConflictError):
+    """Raised when a forecast job is already in progress (back-compat)."""
+
+
+class InvalidRequestError(ValidationError):
+    """Raised when the request payload is malformed (back-compat)."""
+
+
+class QuotaExceededError(RateLimitError):
+    """Raised when the API usage quota has been exhausted (back-compat)."""
+
+
+class ApiError(HTTPClientError):
+    """Catch-all for unclassified API errors (back-compat)."""
+
+
+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_sdk-0.2.1}/simulacrum/models.py

@@ -57,7 +57,6 @@ class ForecastResponse(BaseModel):
     """
 
     forecast: List[float]
-    model_used: str
 
     def get_forecast(self) -> np.ndarray:
         """Return forecast values as a numpy array for downstream processing.

{simulacrum_sdk-0.1.0 → simulacrum_sdk-0.2.1/simulacrum_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulacrum-sdk
-Version: 0.1.0
+Version: 0.2.1
 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.1.0 → simulacrum_sdk-0.2.1}/simulacrum_sdk.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ MANIFEST.in
 README.md
 pyproject.toml
 simulacrum/__init__.py
+simulacrum/_errors.py
 simulacrum/api.py
 simulacrum/client.py
 simulacrum/config.py
@@ -13,4 +14,5 @@ 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
+tests/test_client.py
+tests/test_errors.py

{simulacrum_sdk-0.1.0 → simulacrum_sdk-0.2.1}/simulacrum_sdk.egg-info/requires.txt

@@ -1,4 +1,4 @@
-requests<3,>=2.28
+httpx<1,>=0.27
 pydantic<3,>=2.0
 numpy>=1.24
 

{simulacrum_sdk-0.1.0 → simulacrum_sdk-0.2.1}/tests/test_client.py

@@ -1,5 +1,7 @@
-import numpy as np
+import os
 import pytest
+import numpy as np
+
 from pydantic import ValidationError
 
 import simulacrum.client as simulacrum_client
@@ -7,11 +9,12 @@ import simulacrum.client as simulacrum_client
 
 @pytest.fixture
 def client():
-    return simulacrum_client.Simulacrum("super-secret-key", base_url="https://api.test")
+    base_url = os.environ.get("TEST_API")
+    return simulacrum_client.Simulacrum(os.environ.get("TEST_API_KEY"), base_url=base_url)
 
 
 def test_client_initializes_expected_headers(client):
-    assert client.headers["Authorization"] == "Bearer super-secret-key"
+    assert client.headers["Authorization"] == f"Bearer {os.environ.get('TEST_API_KEY')}"
     assert client.headers["Content-Type"] == "application/json"
 
 
@@ -35,7 +38,7 @@ def test_validate_invokes_send_request_and_parses_response(client, monkeypatch):
 
     assert captured == {
         "method": "GET",
-        "url": "https://api.test/v1/validate",
+        "url": f"{client.base_url}/tempo/v1/validate",
         "headers": client.headers,
         "json": None,
     }
@@ -82,7 +85,7 @@ def test_forecast_builds_payload_and_returns_numpy_array(client, monkeypatch):
     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["url"] == "https://api.test/prophet/v1/forecast"
     assert captured_payload["headers"] == client.headers
     assert captured_payload["json"] == {
         "series": [1.0, 2.0, 3.0],

simulacrum_sdk-0.2.1/tests/test_errors.py

@@ -0,0 +1,112 @@
+import json
+from datetime import datetime, timedelta, timezone
+
+from simulacrum._errors import parse_error
+from simulacrum.exceptions import (
+    ConflictError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    UnauthorizedError,
+    ValidationError,
+)
+
+
+class DummyResponse:
+    def __init__(self, *, status_code: int, headers: dict | None = None, body: object | None = None, text: str | None = None):
+        self.status_code = status_code
+        self.headers = headers or {}
+        self._body = body
+        self._text = text
+
+    def json(self):
+        if self._body is None:
+            raise ValueError("no json body")
+        return self._body
+
+    @property
+    def text(self):
+        if self._text is not None:
+            return self._text
+        return json.dumps(self._body) if self._body is not None else ""
+
+
+def mk_envelope(error_type: str, message: str, details: dict | None = None, trace_id: str | None = "t-123"):
+    return {
+        "error": {"type": error_type, "message": message, "details": details},
+        "trace_id": trace_id,
+    }
+
+
+def test_401_unauthorized_json_and_plain_text():
+    r1 = DummyResponse(status_code=401, headers={"X-Request-ID": "abc"}, body=mk_envelope("unauthorized", "bad key"))
+    exc = parse_error(r1, service="tempo", endpoint="/v1/validate")
+    assert isinstance(exc, UnauthorizedError)
+    assert exc.trace_id() in {"t-123", "abc"}
+
+    r2 = DummyResponse(status_code=401, headers={}, body=None, text="Unauthorized")
+    exc2 = parse_error(r2, service="tempo", endpoint="/v1/validate")
+    assert isinstance(exc2, UnauthorizedError)
+
+
+def test_403_forbidden_variations():
+    r = DummyResponse(status_code=403, headers={}, body=mk_envelope("forbidden", "revoked"))
+    exc = parse_error(r, service="tempo", endpoint="/v1/validate")
+    assert isinstance(exc, ForbiddenError)
+
+
+def test_422_and_400_validation_details_list():
+    details = {"problems": [
+        {"field": "series[5]", "message": "invalid value"},
+        {"field": "horizon", "message": "too large"},
+    ]}
+    r = DummyResponse(status_code=422, headers={}, body=mk_envelope("validation_error", "schema error", details))
+    exc = parse_error(r, service="tempo", endpoint="/v1/forecast")
+    assert isinstance(exc, ValidationError)
+    s = str(exc)
+    assert "validation_error" in s and "schema error" in s
+
+
+def test_400_domain_validation_details_specific_keys():
+    details = {"invalid_index": 7, "invalid_value": -1}
+    r = DummyResponse(status_code=400, headers={}, body=mk_envelope("validation_error", "domain error", details))
+    exc = parse_error(r, service="tempo", endpoint="/v1/forecast")
+    assert isinstance(exc, ValidationError)
+
+
+def test_404_and_409_mapping():
+    r404 = DummyResponse(status_code=404, headers={}, body=mk_envelope("http_error", "not found"))
+    r409 = DummyResponse(status_code=409, headers={}, body=mk_envelope("http_error", "conflict"))
+    assert isinstance(parse_error(r404, service="tempo", endpoint="/x"), NotFoundError)
+    assert isinstance(parse_error(r409, service="tempo", endpoint="/x"), ConflictError)
+
+
+def test_429_retry_after_seconds_and_date():
+    r = DummyResponse(status_code=429, headers={"Retry-After": "30"}, body=mk_envelope("rate_limit", "slow down"))
+    exc = parse_error(r, service="tempo", endpoint="/v1/forecast")
+    assert isinstance(exc, RateLimitError)
+    assert exc.retry_after_seconds == 30.0
+
+    http_date = (datetime.now(timezone.utc) + timedelta(seconds=45)).strftime("%a, %d %b %Y %H:%M:%S %Z")
+    r2 = DummyResponse(status_code=429, headers={"Retry-After": http_date}, body=mk_envelope("rate_limit", "slow down"))
+    exc2 = parse_error(r2, service="tempo", endpoint="/v1/forecast")
+    assert isinstance(exc2, RateLimitError)
+    assert exc2.retry_after_seconds is not None and exc2.retry_after_seconds >= 0.0
+
+
+def test_500_server_error_json_and_plain():
+    r1 = DummyResponse(status_code=500, headers={}, body=mk_envelope("internal_error", "boom"))
+    r2 = DummyResponse(status_code=500, headers={}, body=None, text="internal error")
+    assert isinstance(parse_error(r1, service="tempo", endpoint="/x"), ServerError)
+    assert isinstance(parse_error(r2, service="tempo", endpoint="/x"), ServerError)
+
+
+def test_trace_id_from_body_or_header_and_str_formatting():
+    r = DummyResponse(status_code=401, headers={"X-Request-ID": "rid-1"}, body=mk_envelope("unauthorized", "bad key", trace_id=None))
+    exc = parse_error(r, service="onsiteiq", endpoint="/v1/validate")
+    assert exc.trace_id() == "rid-1"
+    s = str(exc)
+    assert "[onsiteiq]" in s and "401 unauthorized".split()[1] in s.lower()
+
+

simulacrum_sdk-0.1.0/simulacrum/api.py

@@ -1,48 +0,0 @@
-"""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/exceptions.py

@@ -1,49 +0,0 @@
-"""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,
-}