falcon-tst 1.0.10__tar.gz

falcon_tst-1.0.10/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: falcon-tst
+Version: 1.0.10
+Summary: Python SDK for Falcon Studio prediction API.
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.23.0
+Requires-Dist: requests>=2.31.0
+
+# Falcon SDK
+
+The official Python SDK for the Falcon-TST Prediction API. Falcon-TST is a family of large-scale time-series foundation models developed by Ant International.
+
+## Install
+
+```bash
+pip install falcon-tst
+```
+
+## Usage
+
+```python
+import numpy as np
+
+from falcontst import FalconClient
+
+client = FalconClient()
+
+result = client.quantile_predict(
+    context=np.array([
+        [1.2, 3.4, 5.6, 7.8, 9.0],
+        [2.1, 4.3, 6.5, 8.7, 0.9],
+    ]),
+    prediction_length=3,
+    model_name="demo_model",
+    group_ids=np.array([0, 0]),
+    input_mask=np.array([
+        [1, 1, 1, 1, 1],
+        [1, 1, 1, 0, 0],
+    ]),
+    is_multivariate=False,
+)
+
+print(result)
+```
+
+Batch prediction uses the same object fields as `quantile_predict`, but sends
+multiple objects to the batch endpoint:
+
+```python
+result = client.batch_predict(
+    [
+        {
+            "context": np.array([[1.2, 3.4, 5.6, 7.8, 9.0]]),
+            "prediction_length": 3,
+            "model_name": "demo_model",
+            "group_ids": np.array([0]),
+            "input_mask": np.array([[1, 1, 1, 1, 1]]),
+            "is_multivariate": False,
+        },
+        {
+            "context": np.array([[2.1, 4.3, 6.5, 8.7, 0.9]]),
+            "prediction_length": 3,
+        },
+    ]
+)
+```
+
+Each `context` should be a two-dimensional `numpy.ndarray`. For a single time
+series, use `np.array([[1.2, 3.4, 5.6]])` instead of `np.array([1.2, 3.4, 5.6])`.

falcon_tst-1.0.10/README.md

@@ -0,0 +1,61 @@
+# Falcon SDK
+
+The official Python SDK for the Falcon-TST Prediction API. Falcon-TST is a family of large-scale time-series foundation models developed by Ant International.
+
+## Install
+
+```bash
+pip install falcon-tst
+```
+
+## Usage
+
+```python
+import numpy as np
+
+from falcontst import FalconClient
+
+client = FalconClient()
+
+result = client.quantile_predict(
+    context=np.array([
+        [1.2, 3.4, 5.6, 7.8, 9.0],
+        [2.1, 4.3, 6.5, 8.7, 0.9],
+    ]),
+    prediction_length=3,
+    model_name="demo_model",
+    group_ids=np.array([0, 0]),
+    input_mask=np.array([
+        [1, 1, 1, 1, 1],
+        [1, 1, 1, 0, 0],
+    ]),
+    is_multivariate=False,
+)
+
+print(result)
+```
+
+Batch prediction uses the same object fields as `quantile_predict`, but sends
+multiple objects to the batch endpoint:
+
+```python
+result = client.batch_predict(
+    [
+        {
+            "context": np.array([[1.2, 3.4, 5.6, 7.8, 9.0]]),
+            "prediction_length": 3,
+            "model_name": "demo_model",
+            "group_ids": np.array([0]),
+            "input_mask": np.array([[1, 1, 1, 1, 1]]),
+            "is_multivariate": False,
+        },
+        {
+            "context": np.array([[2.1, 4.3, 6.5, 8.7, 0.9]]),
+            "prediction_length": 3,
+        },
+    ]
+)
+```
+
+Each `context` should be a two-dimensional `numpy.ndarray`. For a single time
+series, use `np.array([[1.2, 3.4, 5.6]])` instead of `np.array([1.2, 3.4, 5.6])`.

falcon_tst-1.0.10/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "falcon-tst"
+version = "1.0.10"
+description = "Python SDK for Falcon Studio prediction API."
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "numpy>=1.23.0",
+    "requests>=2.31.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[dependency-groups]
+dev = [
+    "twine>=6.2.0",
+]

falcon_tst-1.0.10/setup.cfg

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

falcon_tst-1.0.10/src/falcon_tst.egg-info/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: falcon-tst
+Version: 1.0.10
+Summary: Python SDK for Falcon Studio prediction API.
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.23.0
+Requires-Dist: requests>=2.31.0
+
+# Falcon SDK
+
+The official Python SDK for the Falcon-TST Prediction API. Falcon-TST is a family of large-scale time-series foundation models developed by Ant International.
+
+## Install
+
+```bash
+pip install falcon-tst
+```
+
+## Usage
+
+```python
+import numpy as np
+
+from falcontst import FalconClient
+
+client = FalconClient()
+
+result = client.quantile_predict(
+    context=np.array([
+        [1.2, 3.4, 5.6, 7.8, 9.0],
+        [2.1, 4.3, 6.5, 8.7, 0.9],
+    ]),
+    prediction_length=3,
+    model_name="demo_model",
+    group_ids=np.array([0, 0]),
+    input_mask=np.array([
+        [1, 1, 1, 1, 1],
+        [1, 1, 1, 0, 0],
+    ]),
+    is_multivariate=False,
+)
+
+print(result)
+```
+
+Batch prediction uses the same object fields as `quantile_predict`, but sends
+multiple objects to the batch endpoint:
+
+```python
+result = client.batch_predict(
+    [
+        {
+            "context": np.array([[1.2, 3.4, 5.6, 7.8, 9.0]]),
+            "prediction_length": 3,
+            "model_name": "demo_model",
+            "group_ids": np.array([0]),
+            "input_mask": np.array([[1, 1, 1, 1, 1]]),
+            "is_multivariate": False,
+        },
+        {
+            "context": np.array([[2.1, 4.3, 6.5, 8.7, 0.9]]),
+            "prediction_length": 3,
+        },
+    ]
+)
+```
+
+Each `context` should be a two-dimensional `numpy.ndarray`. For a single time
+series, use `np.array([[1.2, 3.4, 5.6]])` instead of `np.array([1.2, 3.4, 5.6])`.

falcon_tst-1.0.10/src/falcon_tst.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+src/falcon_tst.egg-info/PKG-INFO
+src/falcon_tst.egg-info/SOURCES.txt
+src/falcon_tst.egg-info/dependency_links.txt
+src/falcon_tst.egg-info/requires.txt
+src/falcon_tst.egg-info/top_level.txt
+src/falcontst/__init__.py
+src/falcontst/client.py
+tests/test_client.py

falcon_tst-1.0.10/src/falcon_tst.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

falcon_tst-1.0.10/src/falcon_tst.egg-info/requires.txt

@@ -0,0 +1,2 @@
+numpy>=1.23.0
+requests>=2.31.0

falcon_tst-1.0.10/src/falcon_tst.egg-info/top_level.txt

@@ -0,0 +1 @@
+falcontst

falcon_tst-1.0.10/src/falcontst/__init__.py

@@ -0,0 +1,3 @@
+from .client import FalconAPIError, FalconClient
+
+__all__ = ["FalconAPIError", "FalconClient"]

falcon_tst-1.0.10/src/falcontst/client.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import math
+from typing import Any, Mapping, Optional, Sequence, Union
+
+import numpy as np
+import requests
+
+
+DEFAULT_PREDICT_URL = (
+    "https://falconstudio-pre.antglobal.com"
+    "/falconstudio/api/v1/openapi/predict"
+)
+DEFAULT_BATCH_PREDICT_URL = (
+    "https://falconstudio-pre.antglobal.com"
+    "/falconstudio/api/v1/openapi/batch-predict"
+)
+
+
+class FalconAPIError(Exception):
+    """Raised when Falcon Studio API returns a non-success code."""
+
+
+class FalconClient:
+    """Client for Falcon Studio prediction API."""
+
+    def __init__(
+        self,
+        endpoint: str = DEFAULT_PREDICT_URL,
+        batch_endpoint: str = DEFAULT_BATCH_PREDICT_URL,
+        timeout: float = 30.0,
+        session: Optional[requests.Session] = None,
+        verify: Optional[Union[bool, str]] = None,
+    ) -> None:
+        self.endpoint = endpoint
+        self.batch_endpoint = batch_endpoint
+        self.timeout = timeout
+        self.session = session or requests.Session()
+        self.verify = verify
+
+    def quantile_predict(
+        self,
+        context: np.ndarray,
+        prediction_length: int,
+        model_name: Optional[str] = None,
+        group_ids: Optional[np.ndarray] = None,
+        input_mask: Optional[np.ndarray] = None,
+        is_multivariate: bool = False,
+    ) -> Any:
+        """Quantile forecast inference."""
+        payload = self._build_predict_payload(
+            context=context,
+            prediction_length=prediction_length,
+            model_name=model_name,
+            group_ids=group_ids,
+            input_mask=input_mask,
+            is_multivariate=is_multivariate,
+        )
+
+        return self._post(self.endpoint, payload)
+
+    def batch_predict(self, objects: Sequence[Mapping[str, Any]]) -> Any:
+        """Batch quantile forecast inference."""
+        if not isinstance(objects, Sequence) or isinstance(objects, (str, bytes)):
+            raise TypeError(
+                f"Expected objects to be a sequence, got {type(objects).__name__}"
+            )
+
+        payload = []
+        for item in objects:
+            if not isinstance(item, Mapping):
+                raise TypeError(
+                    f"Expected batch item to be a mapping, got {type(item).__name__}"
+                )
+
+            payload.append(
+                self._build_predict_payload(
+                    context=item["context"],
+                    prediction_length=item["prediction_length"],
+                    model_name=item.get("model_name"),
+                    group_ids=item.get("group_ids"),
+                    input_mask=item.get("input_mask"),
+                    is_multivariate=item.get("is_multivariate", False),
+                )
+            )
+
+        return self._post(self.batch_endpoint, payload)
+
+    def _build_predict_payload(
+        self,
+        context: np.ndarray,
+        prediction_length: int,
+        model_name: Optional[str] = None,
+        group_ids: Optional[np.ndarray] = None,
+        input_mask: Optional[np.ndarray] = None,
+        is_multivariate: bool = False,
+    ) -> dict[str, Any]:
+        if not isinstance(prediction_length, int):
+            raise TypeError(
+                f"Expected prediction_length to be int, got {type(prediction_length).__name__}"
+            )
+        if prediction_length <= 0:
+            raise ValueError("prediction_length must be greater than 0")
+
+        payload = {
+            "context": self._array_to_list(context),
+            "prediction_length": prediction_length,
+            "is_multivariate": is_multivariate,
+        }
+
+        if model_name is not None:
+            payload["model_name"] = model_name
+        if group_ids is not None:
+            payload["group_ids"] = self._array_to_list(group_ids)
+        if input_mask is not None:
+            payload["input_mask"] = self._array_to_list(input_mask)
+
+        return payload
+
+    def _post(self, endpoint: str, payload: Any) -> dict[str, Any]:
+        request_kwargs = {
+            "json": payload,
+            "timeout": self.timeout,
+        }
+        if self.verify is not None:
+            request_kwargs["verify"] = self.verify
+
+        response = self.session.post(endpoint, **request_kwargs)
+        response.raise_for_status()
+
+        return self._format_response(response.json())
+
+    @staticmethod
+    def _array_to_list(array: np.ndarray) -> list[Any]:
+        if not isinstance(array, np.ndarray):
+            raise TypeError(f"Expected numpy.ndarray, got {type(array).__name__}")
+        return FalconClient._replace_nan(array.tolist())
+
+    @staticmethod
+    def _replace_nan(value: Any) -> Any:
+        if isinstance(value, list):
+            return [FalconClient._replace_nan(item) for item in value]
+        if isinstance(value, float) and math.isnan(value):
+            return None
+        return value
+
+    @staticmethod
+    def _format_response(data: Any) -> dict[str, Any]:
+        if not isinstance(data, dict):
+            raise FalconAPIError(f"Unexpected response format: {data}")
+
+        code = data.get("code")
+        message = data.get("message", "")
+        if code != 200:
+            raise FalconAPIError(f"Falcon API error: code={code}, message={message}")
+
+        return {"prob_prediction": data.get("data")}

falcon_tst-1.0.10/tests/test_client.py

@@ -0,0 +1,238 @@
+import numpy as np
+import pytest
+
+from falcontst import FalconAPIError, FalconClient
+
+
+class DummyResponse:
+    def __init__(self, data):
+        self.data = data
+
+    def raise_for_status(self):
+        return None
+
+    def json(self):
+        return self.data
+
+
+class DummySession:
+    def __init__(self, data):
+        self.data = data
+        self.calls = []
+
+    def post(self, url, **kwargs):
+        self.calls.append({"url": url, **kwargs})
+        return DummyResponse(self.data)
+
+
+def test_quantile_predict_posts_expected_payload_and_returns_json():
+    session = DummySession(
+        {
+            "code": 200,
+            "message": "success",
+            "data": [[[1.6039936542510986, -0.09775638580322266, -1.3819665908813477]]],
+        }
+    )
+    client = FalconClient(endpoint="https://example.test/predict", timeout=5, session=session)
+
+    result = client.quantile_predict(
+        context=np.array([[1.2, 3.4, 5.6, 7.8, 9.0], [2.1, 4.3, 6.5, 8.7, 0.9]]),
+        prediction_length=3,
+        model_name="demo_model",
+        group_ids=np.array([0, 0]),
+        input_mask=np.array([[1, 1, 1, 1, 1], [1, 1, 1, 0, 0]]),
+        is_multivariate=False,
+    )
+
+    assert session.calls == [
+        {
+            "url": "https://example.test/predict",
+            "json": {
+                "context": [[1.2, 3.4, 5.6, 7.8, 9.0], [2.1, 4.3, 6.5, 8.7, 0.9]],
+                "prediction_length": 3,
+                "model_name": "demo_model",
+                "group_ids": [0, 0],
+                "input_mask": [[1, 1, 1, 1, 1], [1, 1, 1, 0, 0]],
+                "is_multivariate": False,
+            },
+            "timeout": 5,
+        }
+    ]
+    assert result == {
+        "prob_prediction": [
+            [[1.6039936542510986, -0.09775638580322266, -1.3819665908813477]]
+        ]
+    }
+
+
+def test_batch_predict_posts_expected_payload_and_returns_json():
+    session = DummySession(
+        {
+            "code": 200,
+            "message": "success",
+            "data": [
+                [[[1.1, 1.2, 1.3]]],
+                [[[2.1, 2.2, 2.3]]],
+            ],
+        }
+    )
+    client = FalconClient(
+        batch_endpoint="https://example.test/batch-predict",
+        timeout=5,
+        session=session,
+    )
+
+    result = client.batch_predict(
+        [
+            {
+                "context": np.array([[1.2, 3.4, 5.6]]),
+                "prediction_length": 3,
+                "model_name": "demo_model",
+                "group_ids": np.array([0]),
+                "input_mask": np.array([[1, 1, 1]]),
+                "is_multivariate": False,
+            },
+            {
+                "context": np.array([[2.1, np.nan, 6.5]]),
+                "prediction_length": 3,
+            },
+        ]
+    )
+
+    assert session.calls == [
+        {
+            "url": "https://example.test/batch-predict",
+            "json": [
+                {
+                    "context": [[1.2, 3.4, 5.6]],
+                    "prediction_length": 3,
+                    "model_name": "demo_model",
+                    "group_ids": [0],
+                    "input_mask": [[1, 1, 1]],
+                    "is_multivariate": False,
+                },
+                {
+                    "context": [[2.1, None, 6.5]],
+                    "prediction_length": 3,
+                    "is_multivariate": False,
+                },
+            ],
+            "timeout": 5,
+        }
+    ]
+    assert result == {
+        "prob_prediction": [
+            [[[1.1, 1.2, 1.3]]],
+            [[[2.1, 2.2, 2.3]]],
+        ]
+    }
+
+
+def test_batch_predict_requires_sequence_of_objects():
+    client = FalconClient(session=DummySession({"data": []}))
+
+    with pytest.raises(TypeError, match="Expected objects to be a sequence"):
+        client.batch_predict("not a batch")
+
+    with pytest.raises(TypeError, match="Expected batch item to be a mapping"):
+        client.batch_predict([["not", "a", "mapping"]])
+
+
+def test_optional_arguments_are_omitted_when_none():
+    session = DummySession({"code": 200, "message": "success", "data": [1, 2, 3]})
+    client = FalconClient(endpoint="https://example.test/predict", session=session)
+
+    client.quantile_predict(
+        context=np.array([[1.0, 2.0]]),
+        prediction_length=1,
+    )
+
+    payload = session.calls[0]["json"]
+    assert "model_name" not in payload
+    assert "group_ids" not in payload
+    assert "input_mask" not in payload
+
+
+def test_verify_is_passed_when_configured():
+    session = DummySession({"code": 200, "message": "success", "data": [1, 2, 3]})
+    client = FalconClient(
+        endpoint="https://example.test/predict",
+        session=session,
+        verify=False,
+    )
+
+    client.quantile_predict(
+        context=np.array([[1.0, 2.0]]),
+        prediction_length=1,
+    )
+
+    assert session.calls[0]["verify"] is False
+
+
+def test_nan_values_are_sent_as_json_null():
+    session = DummySession({"code": 200, "message": "success", "data": [1, 2, 3]})
+    client = FalconClient(endpoint="https://example.test/predict", session=session)
+
+    client.quantile_predict(
+        context=np.array([[1.0, np.nan], [np.nan, 4.0]]),
+        prediction_length=1,
+        group_ids=np.array([0, np.nan]),
+        input_mask=np.array([[1.0, np.nan], [1.0, 0.0]]),
+    )
+
+    payload = session.calls[0]["json"]
+    assert payload["context"] == [[1.0, None], [None, 4.0]]
+    assert payload["group_ids"] == [0.0, None]
+    assert payload["input_mask"] == [[1.0, None], [1.0, 0.0]]
+
+
+def test_context_must_be_numpy_array():
+    client = FalconClient(session=DummySession({"data": []}))
+
+    with pytest.raises(TypeError, match="Expected numpy.ndarray"):
+        client.quantile_predict(
+            context=[[1.0, 2.0]],
+            prediction_length=1,
+        )
+
+
+def test_prediction_length_must_be_int():
+    client = FalconClient(session=DummySession({"data": []}))
+
+    with pytest.raises(TypeError, match="Expected prediction_length to be int"):
+        client.quantile_predict(
+            context=np.array([[1.0, 2.0]]),
+            prediction_length=None,
+        )
+
+
+def test_prediction_length_must_be_positive():
+    client = FalconClient(session=DummySession({"data": []}))
+
+    with pytest.raises(ValueError, match="prediction_length must be greater than 0"):
+        client.quantile_predict(
+            context=np.array([[1.0, 2.0]]),
+            prediction_length=0,
+        )
+
+
+def test_api_error_is_raised_when_code_is_not_200():
+    client = FalconClient(
+        session=DummySession({"code": 500, "message": "model not found", "data": None})
+    )
+
+    with pytest.raises(FalconAPIError, match="code=500, message=model not found"):
+        client.quantile_predict(
+            context=np.array([[1.0, 2.0]]),
+            prediction_length=1,
+        )
+
+
+def test_unexpected_response_format_raises_api_error():
+    client = FalconClient(session=DummySession([1, 2, 3]))
+
+    with pytest.raises(FalconAPIError, match="Unexpected response format"):
+        client.quantile_predict(
+            context=np.array([[1.0, 2.0]]),
+            prediction_length=1,
+        )