Skip to main content

​
Simulacrum client

The Simulacrum class is the primary entry point for the Python SDK. It wraps authentication, request routing, and response validation.

​
Constructor

Simulacrum(api_key: str, base_url: str = "https://api.smlcrm.com/")
ParameterTypeDescription
api_keystrRequired API key. Example: sim-key_id-secret.
base_urlstrOptional override for the API hostname. Defaults to the production endpoint defined in simulacrum.config.BASE_URL. Routes are model-scoped: https://api.smlcrm.com/{modelName}/v1/* (default modelName is tempo).
The constructor validates both arguments and raises TypeError when they are empty or not strings.

​
forecast

forecast(
    series: Sequence[float] | numpy.ndarray,
    horizon: int,
    model: str = "tempo"
) -> numpy.ndarray
ArgumentDescription
seriesOne-dimensional sequence of floats. Lists and numpy arrays are accepted.
horizonNumber of future steps to predict.
modelOptional model identifier exposed by Simulacrum. Defaults to "tempo".
Returns a numpy array ordered chronologically. The method converts sequences to floats, enforces one-dimensionality, and raises TypeError or ValueError before issuing the request when validation fails.

​
Exceptions

  • AuthError, ApiKeyExpiredError, ApiKeyInactiveError, ApiKeyInvalidError
  • InvalidRequestError, ForecastAlreadyRunningError, QuotaExceededError
  • ApiError for all other non-2xx responses

​
validate

validate() -> ValidateAPIKeyResponse
Executes a GET request to /{modelName}/v1/validate (e.g., /tempo/v1/validate) and returns a typed response with key metadata.

​
Response fields

FieldTypeMeaning
validboolWhether the key is active.
clientstrAccount identifier linked to the key.
expires_atdatetime | NoneOptional expiration timestamp.

​
Usage example

from simulacrum import Simulacrum
from simulacrum.exceptions import SimulacrumError

client = Simulacrum(api_key="sim-key_id-secret")
try:
    forecast = client.forecast(series=[122.5, 123.1, 125.0], horizon=3, model="tempo")
    print(forecast.tolist())
finally:
    metadata = client.validate()
    print("Valid:", metadata.valid)
Refer to the models reference for detailed schema of the request and response dataclasses.