sequenx-ai 0.1.0__py3-none-any.whl

sequenx/__init__.py

@@ -0,0 +1,59 @@
+"""Python client for the SequenxAI platform API."""
+
+from ._version import __version__
+from .client import SequenxClient
+from .errors import (
+    AuthenticationError,
+    ConflictError,
+    NotFoundError,
+    RateLimitedError,
+    SequenxError,
+    ServerError,
+    TransportError,
+    ValidationError,
+)
+from .types import (
+    BatchJobDetail,
+    BatchJobProgress,
+    BatchJobSummary,
+    CleanResponse,
+    DataQualityReport,
+    ForecastPoint,
+    ForecastResponse,
+    ForecastWarning,
+    ModelCapabilities,
+    ModelInfo,
+    ModelLimits,
+    ModelList,
+    RollingForecastPoint,
+    RollingForecastResponse,
+    UsageMetrics,
+)
+
+__all__ = [
+    "AuthenticationError",
+    "BatchJobDetail",
+    "BatchJobProgress",
+    "BatchJobSummary",
+    "CleanResponse",
+    "DataQualityReport",
+    "ConflictError",
+    "ForecastPoint",
+    "ForecastResponse",
+    "ForecastWarning",
+    "ModelCapabilities",
+    "ModelInfo",
+    "ModelLimits",
+    "ModelList",
+    "NotFoundError",
+    "RateLimitedError",
+    "RollingForecastPoint",
+    "RollingForecastResponse",
+    "SequenxClient",
+    "SequenxError",
+    "ServerError",
+    "TransportError",
+    "UsageMetrics",
+    "ValidationError",
+    "__version__",
+]

sequenx/_endpoints.py

@@ -0,0 +1,44 @@
+"""The v1 endpoint surface: one row per client method.
+
+Single source of truth shared by the client (method + path + policy) and the
+contract drift test, which asserts that every method/path row below exists in
+packages/contracts/openapi.yaml. Path templates use ``{param}`` placeholders
+filled in by the calling client method.
+
+Idempotency: the control plane claims an ``Idempotency-Key`` only on routes that
+run through ``_idempotent -> _admit -> _claim_idempotency``
+(services/api/src/sequenx_api/modules/public_api/router.py), i.e. ``POST
+/forecast``, ``POST /forecast/rolling`` and ``POST /forecast/batch``; the claim is
+settled with the response, and replaying an identical retry returns the stored
+response instead of charging again
+(services/api/tests/test_public_idempotency.py). That replay is what makes a
+retry safe, so only those rows are auto-retried; every other route would simply
+run again.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Endpoint:
+    """One HTTP endpoint: wire shape plus its idempotency/retry policy."""
+
+    method: str
+    path: str
+    claims_idempotency_key: bool
+    auto_retry: bool
+
+
+ENDPOINTS: dict[str, Endpoint] = {
+    # name: method, path, claims_key, auto_retry
+    "models": Endpoint("GET", "/models", False, True),
+    "forecast": Endpoint("POST", "/forecast", True, True),
+    "rolling": Endpoint("POST", "/forecast/rolling", True, True),
+    "batch": Endpoint("POST", "/forecast/batch", True, True),
+    "batch_job": Endpoint("GET", "/forecast/batch/{job_id}", False, True),
+    "cancel_batch_job": Endpoint("POST", "/forecast/batch/{job_id}/cancel", False, False),
+    "delete_batch_job": Endpoint("DELETE", "/forecast/batch/{job_id}", False, False),
+    "clean": Endpoint("POST", "/clean", False, False),
+}

sequenx/_http.py

@@ -0,0 +1,170 @@
+"""HTTP layer: auth header, retry policy and typed error mapping."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from ._endpoints import ENDPOINTS
+from ._version import __version__
+from .errors import (
+    AuthenticationError,
+    ConflictError,
+    NotFoundError,
+    RateLimitedError,
+    SequenxError,
+    ServerError,
+    TransportError,
+    ValidationError,
+)
+
+_RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+# 409 is the control plane's IDEMPOTENCY_IN_PROGRESS: the request that claimed
+# the key is still running. Retrying it with the same key returns the stored
+# response once it settles, so it is safe on the routes that carry a key.
+_CONFLICT_STATUS = 409
+_BACKOFF_SECONDS = 0.5
+
+
+def _error_from_response(
+    resp: httpx.Response, idempotency_key: str | None = None
+) -> SequenxError:
+    try:
+        body: Any = resp.json()
+    except ValueError:
+        body = {}
+    err: dict[str, Any] = {}
+    if isinstance(body, dict):
+        inner = body.get("error")
+        err = inner if isinstance(inner, dict) else {}
+    code = err.get("code")
+    message = err.get("message") or f"HTTP {resp.status_code}"
+    request_id = err.get("request_id") or resp.headers.get("x-request-id")
+    kw: dict[str, Any] = {
+        "code": code,
+        "request_id": request_id,
+        "status": resp.status_code,
+        "category": err.get("category"),
+        "retryable": err.get("retryable"),
+        "details": err.get("details"),
+        "idempotency_key": idempotency_key,
+    }
+    status = resp.status_code
+    if status in (401, 403):
+        return AuthenticationError(message, **kw)
+    if status == 404:
+        return NotFoundError(message, **kw)
+    if status == 409:
+        return ConflictError(message, **kw)
+    if status == 422:
+        return ValidationError(message, **kw)
+    if status == 429:
+        retry_after = resp.headers.get("retry-after")
+        limit_type = resp.headers.get("x-ratelimit-limit-type")
+        return RateLimitedError(
+            message,
+            retry_after=float(retry_after) if retry_after else None,
+            limit_type=limit_type,
+            **kw,
+        )
+    if status >= 500:
+        return ServerError(message, **kw)
+    return SequenxError(message, **kw)
+
+
+class _Http:
+    """Bearer-auth HTTP calls with per-endpoint retry policy and typed errors."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        *,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        transport: httpx.BaseTransport | None = None,
+        sleep: Any = time.sleep,
+    ) -> None:
+        self._client = httpx.Client(
+            base_url=base_url,
+            timeout=timeout,
+            transport=transport,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "User-Agent": f"sequenx-python/{__version__}",
+            },
+        )
+        self._max_retries = max(0, max_retries)
+        self._sleep = sleep
+
+    def close(self) -> None:
+        self._client.close()
+
+    def request(
+        self,
+        endpoint: str,
+        *,
+        path_args: Mapping[str, Any] | None = None,
+        json_body: Any = None,
+        params: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        """Call one endpoint of the contract by name.
+
+        The endpoint name selects the method, path and the idempotency/retry
+        policy from ``_endpoints.ENDPOINTS``; the key is generated once per call
+        and reused by every retry of that call.
+        """
+        spec = ENDPOINTS[endpoint]
+        if idempotency_key is not None and not spec.claims_idempotency_key:
+            raise ValueError(
+                f"{endpoint}: the control plane ignores Idempotency-Key on "
+                f"{spec.method} {spec.path}; it is not claimed for idempotency there"
+            )
+        headers: dict[str, str] = {}
+        key: str | None = None
+        if spec.claims_idempotency_key:
+            key = idempotency_key or uuid.uuid4().hex
+            headers["Idempotency-Key"] = key
+        path = spec.path.format(**(path_args or {}))
+        attempt = 0
+        while True:
+            try:
+                resp = self._client.request(
+                    spec.method, path, json=json_body, params=params, headers=headers or None
+                )
+            except httpx.TransportError as exc:
+                if spec.auto_retry and attempt < self._max_retries:
+                    attempt += 1
+                    self._sleep(_BACKOFF_SECONDS * attempt)
+                    continue
+                raise TransportError(
+                    f"{spec.method} {path} failed: {exc}", idempotency_key=key
+                ) from exc
+            retryable = (
+                spec.auto_retry
+                and attempt < self._max_retries
+                and (
+                    resp.status_code in _RETRYABLE_STATUS
+                    or (resp.status_code == _CONFLICT_STATUS and spec.claims_idempotency_key)
+                )
+            )
+            if retryable:
+                retry_after = resp.headers.get("retry-after")
+                self._sleep(float(retry_after) if retry_after else _BACKOFF_SECONDS * (attempt + 1))
+                attempt += 1
+                continue
+            if resp.is_success:
+                if resp.status_code == 204 or not resp.content:
+                    return None
+                try:
+                    return resp.json()
+                except ValueError as exc:
+                    raise ValidationError(
+                        f"the API returned a non-JSON body for {spec.method} {path}"
+                    ) from exc
+            raise _error_from_response(resp, key)

sequenx/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

sequenx/client.py

@@ -0,0 +1,226 @@
+"""Synchronous client for the SequenxAI platform API."""
+
+from __future__ import annotations
+
+import re
+import time
+from collections.abc import Mapping
+from typing import Any, cast
+
+from ._http import _Http
+from .errors import ValidationError
+from .models import to_rows
+from .types import (
+    BatchJobDetail,
+    BatchJobSummary,
+    CleanResponse,
+    ForecastResponse,
+    ModelList,
+    RollingForecastResponse,
+)
+
+DEFAULT_BASE_URL = "https://api.sequenxai.com/v1"
+
+# Batch job ids are opaque ids minted by the control plane; they are put into a
+# URL path, so anything that could change the path is refused up front.
+_JOB_ID = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
+
+_FORECAST_FIELDS = (
+    "model",
+    "model_options",
+    "joint_groups",
+    "future_covariates",
+    "freq",
+    "level",
+    "quantile_policy",
+    "point_quantile",
+    "clean_series",
+    "clean_exog",
+    "options",
+)
+
+
+def _forecast_body(series: Any, h: int, kwargs: dict[str, Any]) -> dict[str, Any]:
+    body: dict[str, Any] = {"series": to_rows(series), "h": h}
+    for field in _FORECAST_FIELDS:
+        value = kwargs.pop(field, None)
+        if value is not None:
+            body[field] = value
+    leftover = [k for k in kwargs if kwargs[k] is not None]
+    if leftover:
+        raise TypeError(f"unknown forecast arguments: {', '.join(sorted(leftover))}")
+    return body
+
+
+def _payload(value: Any, endpoint: str) -> dict[str, Any]:
+    """The response body as a dict.
+
+    An empty body is a broken answer, not an empty one: the SDK raises a typed
+    error instead of handing back None (or a TypeError at the caller's side).
+    """
+    if not isinstance(value, dict):
+        raise ValidationError(f"the API returned no JSON body for {endpoint}")
+    return value
+
+
+def _job_id(job_id: str) -> str:
+    if not _JOB_ID.match(job_id):
+        raise ValueError(f"invalid job id: {job_id!r}")
+    return job_id
+
+
+class SequenxClient:
+    """Synchronous client for the SequenxAI public API (contract: openapi.yaml)."""
+
+    DEFAULT_BASE_URL = DEFAULT_BASE_URL
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str | None = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        transport: Any = None,
+        sleep: Any = time.sleep,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._http = _Http(
+            api_key,
+            (base_url or DEFAULT_BASE_URL).rstrip("/"),
+            timeout=timeout,
+            max_retries=max_retries,
+            transport=transport,
+            sleep=sleep,
+        )
+
+    def close(self) -> None:
+        """Release the underlying HTTP connection pool."""
+        self._http.close()
+
+    # -- models ------------------------------------------------------------
+    def models(self) -> ModelList:
+        """GET /models: the public model catalog for this key."""
+        return cast(ModelList, _payload(self._http.request("models"), "GET /models"))
+
+    # -- forecast ------------------------------------------------------------
+    def forecast(
+        self, series: Any, *, h: int, idempotency_key: str | None = None, **kw: Any
+    ) -> ForecastResponse:
+        """POST /forecast: point + intervals for every series."""
+        return cast(
+            ForecastResponse,
+            _payload(
+                self._http.request(
+                    "forecast",
+                    json_body=_forecast_body(series, h, kw),
+                    idempotency_key=idempotency_key,
+                ),
+                "POST /forecast",
+            ),
+        )
+
+    def forecast_rolling(
+        self,
+        series: Any,
+        *,
+        rolling: Mapping[str, Any],
+        h: int,
+        idempotency_key: str | None = None,
+        **kw: Any,
+    ) -> RollingForecastResponse:
+        """POST /forecast/rolling: multiple backtest origins inside one series.
+
+        ``h`` and ``rolling`` are required by the contract
+        (``RollingForecastRequest.required``).
+        """
+        body = _forecast_body(series, h, kw)
+        body["rolling"] = dict(rolling)
+        return cast(
+            RollingForecastResponse,
+            _payload(
+                self._http.request(
+                    "rolling", json_body=body, idempotency_key=idempotency_key
+                ),
+                "POST /forecast/rolling",
+            ),
+        )
+
+    def forecast_batch(
+        self, series: Any, *, h: int, idempotency_key: str | None = None, **kw: Any
+    ) -> BatchJobSummary:
+        """POST /forecast/batch: submit an asynchronous batch job (poll with batch_job)."""
+        return cast(
+            BatchJobSummary,
+            _payload(
+                self._http.request(
+                    "batch",
+                    json_body=_forecast_body(series, h, kw),
+                    idempotency_key=idempotency_key,
+                ),
+                "POST /forecast/batch",
+            ),
+        )
+
+    def batch_job(self, job_id: str) -> BatchJobDetail:
+        """GET /forecast/batch/{job_id}: poll a batch job."""
+        return cast(
+            BatchJobDetail,
+            _payload(
+                self._http.request("batch_job", path_args={"job_id": _job_id(job_id)}),
+                "GET /forecast/batch/{job_id}",
+            ),
+        )
+
+    def cancel_batch_job(self, job_id: str) -> BatchJobDetail:
+        """POST /forecast/batch/{job_id}/cancel: cancel a queued or running job.
+
+        The control plane does not claim an idempotency key on this route, so the
+        call is not retried automatically: a repeat would run the cancellation
+        again. Call it again yourself if the outcome matters.
+        """
+        return cast(
+            BatchJobDetail,
+            _payload(
+                self._http.request("cancel_batch_job", path_args={"job_id": _job_id(job_id)}),
+                "POST /forecast/batch/{job_id}/cancel",
+            ),
+        )
+
+    def delete_batch_job(self, job_id: str) -> None:
+        """DELETE /forecast/batch/{job_id}: delete a finished job and its result file.
+
+        Not retried automatically: after a lost response the job may already be
+        gone, and the retry would answer 404 although the delete succeeded. Read
+        the job first when the outcome matters.
+        """
+        self._http.request("delete_batch_job", path_args={"job_id": _job_id(job_id)})
+
+    # -- clean ------------------------------------------------------------
+    def clean(
+        self,
+        series: Any,
+        *,
+        options: dict[str, Any] | None = None,
+        freq: str | None = None,
+        model: str | None = None,
+        clean_series: bool | None = None,
+    ) -> CleanResponse:
+        """POST /clean: free cleaning dry-run (report + decision, no forecast).
+
+        The optional arguments mirror the contract's CleanRequest: ``freq``,
+        ``model`` and ``clean_series`` next to ``options``.
+        """
+        body: dict[str, Any] = {"series": to_rows(series)}
+        if options is not None:
+            body["options"] = options
+        if freq is not None:
+            body["freq"] = freq
+        if model is not None:
+            body["model"] = model
+        if clean_series is not None:
+            body["clean_series"] = clean_series
+        return cast(
+            CleanResponse, _payload(self._http.request("clean", json_body=body), "POST /clean")
+        )

sequenx/errors.py

@@ -0,0 +1,84 @@
+"""Typed errors mapped from the contract's ErrorResponse (code/message/request_id)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class SequenxError(Exception):
+    """Base error: every API-level and transport failure the SDK raises.
+
+    ``idempotency_key`` is the key the call carried (None when the route does
+    not use one). It is the key to replay the request with, so the control
+    plane replays the stored response instead of charging again.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        request_id: str | None = None,
+        status: int | None = None,
+        category: str | None = None,
+        retryable: bool | None = None,
+        details: Any = None,
+        idempotency_key: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.request_id = request_id
+        self.status = status
+        self.category = category
+        self.retryable = retryable
+        self.details = details
+        self.idempotency_key = idempotency_key
+
+
+class AuthenticationError(SequenxError):
+    """401/403: missing, invalid or unauthorized API key."""
+
+
+class NotFoundError(SequenxError):
+    """404: unknown path or (batch) job id."""
+
+
+class ValidationError(SequenxError):
+    """422: request parsed but its content cannot be used as sent."""
+
+
+class RateLimitedError(SequenxError):
+    """429: RPM or daily-points quota exhausted.
+
+    ``retry_after`` is the ``Retry-After`` header in seconds and ``limit_type``
+    the ``X-RateLimit-Limit-Type`` header (``rpm`` / ``daily``): a daily quota
+    only frees up at the next reset, a minute quota in a minute.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_after: float | None = None,
+        limit_type: str | None = None,
+        **kw: Any,
+    ) -> None:
+        super().__init__(message, **kw)
+        self.retry_after = retry_after
+        self.limit_type = limit_type
+
+
+class ConflictError(SequenxError):
+    """409: a duplicate arrived while the first request with that key is still running.
+
+    A key reused with a different body is a 422 (ValidationError, code
+    ``IDEMPOTENCY_KEY_REUSED``), not a 409.
+    """
+
+
+class ServerError(SequenxError):
+    """5xx: control-plane or gateway failure."""
+
+
+class TransportError(SequenxError):
+    """Network-level failure (connection refused, timeout, DNS)."""

sequenx/models.py

@@ -0,0 +1,25 @@
+"""Lightweight helpers for request/response payloads."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+
+def to_rows(data: Any) -> list[dict[str, Any]]:
+    """Normalize series input to a list of row mappings.
+
+    Accepts a list of mappings (unique_id/ds/y) or a pandas/polars DataFrame
+    (the extra is optional; it is only used when installed and passed in).
+    """
+    if isinstance(data, Mapping):
+        raise TypeError("series must be a list of rows or a DataFrame, not a single mapping")
+    if isinstance(data, list):
+        return list(data)
+    to_records = getattr(data, "to_dict", None)
+    if callable(to_records):  # pandas
+        return [dict(r) for r in data.to_dict("records")]
+    rows = getattr(data, "rows", None)
+    if callable(rows):  # polars
+        return [dict(r) for r in data.rows(named=True)]
+    raise TypeError("series must be a list of mappings or a pandas/polars DataFrame")

sequenx/types.py

@@ -0,0 +1,214 @@
+"""Typed response shapes, mirroring the contract's schemas.
+
+Every class below mirrors one schema of packages/contracts/openapi.yaml; the
+drift test asserts that the required keys are exactly the contract's required
+keys and that the optional keys are exactly the contract's remaining
+properties, in both directions. Nested objects the contract
+does not model in the SDK (intervals, cleaning report, effective policy,
+quantile report, rolling windows, and the rolling response's ``data_quality`` /
+``usage``) stay ``dict[str, Any]``: the wire format is the contract's, not the
+SDK's.
+
+Python 3.10 has no ``typing.NotRequired``, so the optional keys live in a
+``total=False`` base class.
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+
+class _UsageMetricsOptional(TypedDict, total=False):
+    forecast_data_points: int
+    billable_points: int
+
+
+class UsageMetrics(_UsageMetricsOptional):
+    """Contract: UsageMetrics."""
+
+    series_count: int
+    input_data_points: int
+    latency_ms: int
+
+
+class _DataQualityReportOptional(TypedDict, total=False):
+    inferred_freq: str | None
+    imputed_points: int
+    outlier_points_suppressed: int
+    timezone_normalized: bool
+    notes: list[str]
+
+
+class DataQualityReport(_DataQualityReportOptional):
+    """Contract: DataQualityReport."""
+
+    status: str
+    missing_ratio: float
+
+
+class _ForecastPointOptional(TypedDict, total=False):
+    intervals: dict[str, Any]
+
+
+class ForecastPoint(_ForecastPointOptional):
+    """Contract: ForecastResultPoint."""
+
+    unique_id: str
+    ds: str
+    y_hat: float
+
+
+class _ForecastWarningOptional(TypedDict, total=False):
+    unique_id: str
+    count: int
+    used: int
+    dropped: int
+    tail_handling: str
+    impact: str
+    confirmed: bool
+    version: str
+    columns: list[Any]
+    native_horizon: int
+
+
+class ForecastWarning(_ForecastWarningOptional):
+    """Contract: ForecastWarning."""
+
+    code: str
+    message: str
+
+
+class _ModelLimitsOptional(TypedDict, total=False):
+    freq: str
+
+
+class _RollingForecastPointOptional(TypedDict, total=False):
+    intervals: dict[str, Any]
+
+
+class RollingForecastPoint(_RollingForecastPointOptional):
+    """Contract: RollingForecastPoint (a row of the rolling response)."""
+
+    unique_id: str
+    cutoff: str
+    step: int
+    ds: str
+    y_hat: float
+
+
+class ModelLimits(_ModelLimitsOptional):
+    """Contract: ModelLimits."""
+
+    min_context: int | None
+    max_context: int | None
+    max_horizon: int | None
+    context_horizon_budget: int | None
+
+
+class ModelCapabilities(TypedDict):
+    """Contract: ModelCapabilities."""
+
+    covariates: str
+    joint: str
+
+
+class ModelInfo(TypedDict):
+    """Contract: ModelInfo."""
+
+    id: str
+    aliases: list[str]
+    limits: ModelLimits
+    quantiles: list[float]
+    capabilities: ModelCapabilities
+
+
+class ModelList(TypedDict):
+    """Contract: ModelList."""
+
+    default: str | None
+    models: list[ModelInfo]
+    request_id: str
+
+
+class _ForecastResponseOptional(TypedDict, total=False):
+    freq: str
+    point_quantile: float
+    cleaning_report: dict[str, Any]
+    effective_policy: dict[str, Any]
+    model_input: list[dict[str, Any]]
+    quantile_report: dict[str, Any]
+    warnings: list[ForecastWarning]
+
+
+class ForecastResponse(_ForecastResponseOptional):
+    """Contract: ForecastResponse."""
+
+    request_id: str
+    model_used: str
+    forecast: list[ForecastPoint]
+    data_quality: DataQualityReport
+    usage: UsageMetrics
+
+
+class _RollingForecastResponseOptional(TypedDict, total=False):
+    point_quantile: float
+    effective_policy: dict[str, Any]
+    quantile_report: dict[str, Any]
+    warnings: list[ForecastWarning]
+
+
+class RollingForecastResponse(_RollingForecastResponseOptional):
+    """Contract: RollingForecastResponse."""
+
+    request_id: str
+    model_used: str
+    freq: str
+    rolling: dict[str, Any]
+    forecast: list[RollingForecastPoint]
+    windows: list[dict[str, Any]]
+    data_quality: dict[str, Any]
+    usage: dict[str, Any]
+
+
+class BatchJobProgress(TypedDict):
+    """Contract: BatchJobProgress."""
+
+    done_series: int
+    total_series: int
+
+
+class BatchJobSummary(TypedDict):
+    """Contract: BatchJobSummary."""
+
+    job_id: str
+    status: str
+    progress: BatchJobProgress
+    created_at: str
+
+
+class BatchJobDetail(TypedDict):
+    """Contract: BatchJobDetail."""
+
+    job_id: str
+    status: str
+    model: str
+    h: int
+    progress: BatchJobProgress
+    created_at: str
+    started_at: str | None
+    finished_at: str | None
+    result: dict[str, Any] | None
+    error: dict[str, Any] | None
+
+
+class _CleanResponseOptional(TypedDict, total=False):
+    warnings: list[ForecastWarning]
+
+
+class CleanResponse(_CleanResponseOptional):
+    """Contract: CleanResponse."""
+
+    request_id: str
+    freq: str
+    cleaning_report: dict[str, Any]
+    effective_policy: dict[str, Any]

sequenx_ai-0.1.0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: sequenx-ai
+Version: 0.1.0
+Summary: Python client for the SequenxAI time-series platform API
+Author-email: SequenxAI <lcw_1497007939@163.com>
+License-Expression: LicenseRef-Proprietary
+Keywords: time-series,forecasting,sequenxai
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1.0,>=0.27
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == "pandas"
+Provides-Extra: polars
+Requires-Dist: polars>=1.0; extra == "polars"
+
+# sequenx (SequenxAI Python client)
+
+Python client for the SequenxAI platform API (`packages/contracts/openapi.yaml` is the single
+source of truth for the wire format). Install locally:
+
+```bash
+pip install -e packages/sequenx-py
+```
+
+```python
+from sequenx import SequenxClient
+
+client = SequenxClient("sqx_live_...")
+result = client.forecast(series, h=96)      # series: list[dict] with unique_id/ds/y
+print(result["model_used"], result["usage"]["billable_points"])
+client.close()
+```
+
+Covered endpoints (v1): `POST /forecast`, `POST /forecast/rolling`, `POST /forecast/batch`
+(+ get / cancel / delete job), `POST /clean` (dry-run), `GET /models`. `POST /anomaly-detection`
+is intentionally not covered (endpoint not open). PyPI publishing is a separate decision.
+
+## Idempotency and retries
+
+The control plane claims an `Idempotency-Key` on `POST /forecast`, `POST /forecast/rolling` and
+`POST /forecast/batch` only: a repeated identical request replays the stored response instead of
+charging again. The SDK sends the key on exactly those three routes and reuses it across retries,
+so a transport error or a 429/5xx is retried safely (`max_retries=0` disables retries).
+
+A retry that races the original request can answer 409 (`IDEMPOTENCY_IN_PROGRESS`): the request
+that claimed the key is still running. The SDK retries it with the same key (the control plane
+replays the stored response once it settles). If it still cannot finish, the raised
+`ConflictError` carries the `idempotency_key` it used, so the call can be replayed safely:
+
+```python
+from sequenx import ConflictError
+
+try:
+    out = client.forecast(series, h=96)
+except ConflictError as exc:
+    out = client.forecast(series, h=96, idempotency_key=exc.idempotency_key)
+```
+
+The SDK generates one key per call; pass your own `idempotency_key=` to `forecast`,
+`forecast_rolling` or `forecast_batch` when you want to hold on to it yourself.
+
+Every other route is re-run by the control plane, so the SDK neither sends a key nor retries it
+automatically: `POST /clean` (a free dry-run), `POST /forecast/batch/{job_id}/cancel` and
+`DELETE /forecast/batch/{job_id}` (a repeated delete would answer 404 although the first delete
+succeeded — read the job with `batch_job()` when the outcome matters). `GET` requests are retried.
+
+## Batch jobs
+
+`forecast_batch()` submits a job; `batch_job()` polls it, `cancel_batch_job()` cancels it and
+`delete_batch_job()` removes a finished job and its result file. Polling is the caller's loop.
+
+## Errors
+
+Errors are typed (`AuthenticationError`, `ValidationError`, `RateLimitedError`, `ServerError`,
+`TransportError`, ...) and carry the contract's `code` / `request_id` / `status`.
+
+## Response types
+
+Responses are typed too (`ForecastResponse`, `RollingForecastResponse`, `ModelList`,
+`BatchJobSummary`, `BatchJobDetail`, `CleanResponse`, ...); the shapes mirror the contract
+schemas and the package ships `py.typed`. Nested objects the SDK does not model (intervals,
+cleaning report, effective policy) stay plain dictionaries.
+
+## DataFrames
+
+`pandas` and `polars` frames are accepted as input (`pip install -e "packages/sequenx-py[pandas]"`
+or `[polars]`); neither is required.
+
+## Development
+
+```bash
+pip install -e packages/sequenx-py -r packages/sequenx-py/requirements-dev.txt
+python -m pytest -q          # unit + contract drift tests
+python -m ruff check src tests
+SEQUENX_SDK_LIVE_SMOKE=1 SEQUENX_API_KEY=sqx_live_... python scripts/live_smoke.py
+```
+
+The live smoke is opt-in and never passes silently: without the flag and key it exits 2 with
+instructions. The contract drift test reads `packages/contracts/openapi.yaml` and fails when the
+SDK and the contract disagree; Gitee Go runs it via `scripts/ci/gitee-verify.sh sdk`.

sequenx_ai-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+sequenx/__init__.py,sha256=cvviZRp1e4gIB-wJZZs6wgoHtFlTivN6mENZlYC76xA,1211
+sequenx/_endpoints.py,sha256=SHpF2cBfnwbLWQvMQBHpeipJfMb57FArCPq8_SnuxHs,1822
+sequenx/_http.py,sha256=Hw2-UTlBo-5-VbBF6X0DQsjBc9dYaKktDcRQxmcXUSM,5786
+sequenx/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+sequenx/client.py,sha256=cN33eMU7PgyNDQPJZt45eSRlgfp_HAXSFIjJAQEnzBI,7385
+sequenx/errors.py,sha256=MJKFOxQd3Dar2b7qxo5FVUvHSNfjkZq14watc3elbzs,2443
+sequenx/models.py,sha256=jP4nhfp5fZl4-MQoT0-xRw5m6PKRDD8lcOlWIOHzLMA,965
+sequenx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sequenx/types.py,sha256=DTlmQ1t_56L0WuriIsOU6M_ArTedb09hQ7ay9SlTFAQ,4851
+sequenx_ai-0.1.0.dist-info/METADATA,sha256=QmUm6CEY7RLrFdzS2QTVwNov7RJgQD8DTO4syDGLVNM,4550
+sequenx_ai-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+sequenx_ai-0.1.0.dist-info/top_level.txt,sha256=2p30V9_RZheJb1EdRGxBitsBbeArMYUU4uwdIUb1eQ0,8
+sequenx_ai-0.1.0.dist-info/RECORD,,

sequenx_ai-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sequenx_ai-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sequenx