sequenx-ai 0.1.0__tar.gz

sequenx_ai-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,85 @@
+# 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/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sequenx-ai"
+dynamic = ["version"]
+description = "Python client for the SequenxAI time-series platform API"
+authors = [{ name = "SequenxAI", email = "lcw_1497007939@163.com" }]
+keywords = ["time-series", "forecasting", "sequenxai"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+readme = "README.md"
+requires-python = ">=3.10"
+license = "LicenseRef-Proprietary"
+dependencies = [
+    "httpx>=0.27,<1.0",
+]
+
+[project.optional-dependencies]
+pandas = ["pandas>=2.0"]
+polars = ["polars>=1.0"]
+
+[tool.setuptools.dynamic]
+version = { attr = "sequenx._version.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+sequenx = ["py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+# Same rule set as the other Python packages in the monorepo.
+select = ["E", "F", "I", "B", "W", "UP"]

sequenx_ai-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sequenx_ai-0.1.0/src/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_ai-0.1.0/src/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_ai-0.1.0/src/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_ai-0.1.0/src/sequenx/_version.py

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