> ## Documentation Index
> Fetch the complete documentation index at: https://docs.smlcrm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulacrum client

> Public methods on the high-level `Simulacrum` Python class.

# `Simulacrum` client

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

## Constructor

```python theme={null}
Simulacrum(api_key: str, base_url: str = "https://api.smlcrm.com/")
```

| Parameter  | Type  | Description                                                                                                                                                                                                               |
| ---------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api_key`  | `str` | Required API key. Example: `sim-key_id-secret`.                                                                                                                                                                           |
| `base_url` | `str` | Optional 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`

```python theme={null}
forecast(
    series: Sequence[float] | numpy.ndarray,
    horizon: int,
    model: str = "tempo"
) -> numpy.ndarray
```

| Argument  | Description                                                              |
| --------- | ------------------------------------------------------------------------ |
| `series`  | One-dimensional sequence of floats. Lists and numpy arrays are accepted. |
| `horizon` | Number of future steps to predict.                                       |
| `model`   | Optional 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`

```python theme={null}
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

| Field        | Type                   | Meaning                               |
| ------------ | ---------------------- | ------------------------------------- |
| `valid`      | `bool`                 | Whether the key is active.            |
| `client`     | `str`                  | Account identifier linked to the key. |
| `expires_at` | `datetime | None` | Optional expiration timestamp.        |

## Usage example

```python theme={null}
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](reference/models) for detailed schema of the request and response dataclasses.