omina-client 1.0.0__tar.gz

omina_client-1.0.0/.gitignore

@@ -0,0 +1,14 @@
+/target
+/keys/
+.venv/
+**/.venv/
+**/__pycache__/
+**/*.py[cod]
+**/.pytest_cache/
+**/dist/
+/training_runs/
+/data/telemetry_50k/
+/models/minilm-l6-h384/model.safetensors
+/bundles/compiled_from_cli.omina
+/bundles/drone_flight.omina
+/reports/**/predictions.jsonl

omina_client-1.0.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.5
+Name: omina-client
+Version: 1.0.0
+Summary: Official Python client SDK for the Omina edge intelligence daemon
+Author: Omina Project Maintainers
+License-Expression: Apache-2.0
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Omina Python Client SDK (`omina-client`)
+
+The official Python client SDK for the **Omina** intelligence daemon.
+
+Designed for downstream systems engineers, telemetry monitoring pipelines, robotics scripts, and automated control loops.
+
+## Features
+
+- **Type-Safe Primitive Extraction**: Direct extraction of continuous `Gauge`, binary `Gate`, categorical `Route`, semantic `Noul`, discrete `Choice`, and ordinal `Score` heads.
+- **Transparent Backpressure Resilience**: Automatic exponential backoff with full jitter on HTTP `429 OVERLOADED` and `503 DEADLINE_EXCEEDED` respecting `Retry-After` headers.
+- **Hardware Fallback Awareness**: Immediate detection of neural graph fallbacks (`response.is_fallback`, `fallback_triggered`).
+- **Synchronous & Asynchronous**: High-performance sync (`OminaClient`) and async (`AsyncOminaClient`) clients built on top of `httpx`.
+
+## Installation
+
+```sh
+pip install omina-client
+```
+
+## Quickstart
+
+```python
+from omina_client import OminaClient
+from omina_client.exceptions import OminaOverloadError
+
+client = OminaClient(
+    base_url="http://localhost:8080",
+    max_retries=3,
+    base_backoff_ms=50
+)
+
+try:
+    response = client.evaluate(
+        domain_id="drone_flight",
+        context_log="Winds at 40 knots. Vision sensor degraded. GPS altitude spiking."
+    )
+
+    # 1. Dictionary-like or attribute access
+    altitude = response.gauges["altitude"].predicted_value
+    sigma = response.gauges["altitude"].uncertainty_sigma
+    is_breached = response.gates["geofence_breach"].decision
+    maneuver = response.routes["maneuver"].selected
+
+    # 2. Direct helper access
+    alt = response.gauge("altitude").predicted_value
+    breached = response.gate("geofence_breach")  # returns bool
+    man = response.route("maneuver")            # returns str
+
+    # 3. Fallback inspection
+    if response.gauges["altitude"].fallback_triggered:
+        print("Warning: Altitude gauge executed safe fallback envelope!")
+    if response.is_fallback:
+        print("Degraded heads:", response.fallback_heads)
+
+    print(f"Maneuver: {maneuver}, Altitude: {altitude}m (±{sigma})")
+
+except OminaOverloadError as e:
+    print(f"Edge daemon saturated after {e.retries} retries: {e}")
+```
+
+## Async Usage
+
+```python
+import asyncio
+from omina_client import AsyncOminaClient
+
+async def main():
+    async with AsyncOminaClient("http://localhost:8080") as client:
+        response = await client.evaluate("drone_flight", "Clear skies, nominal telemetry")
+        print("Altitude:", response.gauge("altitude").predicted_value)
+
+asyncio.run(main())
+```

omina_client-1.0.0/README.md

@@ -0,0 +1,73 @@
+# Omina Python Client SDK (`omina-client`)
+
+The official Python client SDK for the **Omina** intelligence daemon.
+
+Designed for downstream systems engineers, telemetry monitoring pipelines, robotics scripts, and automated control loops.
+
+## Features
+
+- **Type-Safe Primitive Extraction**: Direct extraction of continuous `Gauge`, binary `Gate`, categorical `Route`, semantic `Noul`, discrete `Choice`, and ordinal `Score` heads.
+- **Transparent Backpressure Resilience**: Automatic exponential backoff with full jitter on HTTP `429 OVERLOADED` and `503 DEADLINE_EXCEEDED` respecting `Retry-After` headers.
+- **Hardware Fallback Awareness**: Immediate detection of neural graph fallbacks (`response.is_fallback`, `fallback_triggered`).
+- **Synchronous & Asynchronous**: High-performance sync (`OminaClient`) and async (`AsyncOminaClient`) clients built on top of `httpx`.
+
+## Installation
+
+```sh
+pip install omina-client
+```
+
+## Quickstart
+
+```python
+from omina_client import OminaClient
+from omina_client.exceptions import OminaOverloadError
+
+client = OminaClient(
+    base_url="http://localhost:8080",
+    max_retries=3,
+    base_backoff_ms=50
+)
+
+try:
+    response = client.evaluate(
+        domain_id="drone_flight",
+        context_log="Winds at 40 knots. Vision sensor degraded. GPS altitude spiking."
+    )
+
+    # 1. Dictionary-like or attribute access
+    altitude = response.gauges["altitude"].predicted_value
+    sigma = response.gauges["altitude"].uncertainty_sigma
+    is_breached = response.gates["geofence_breach"].decision
+    maneuver = response.routes["maneuver"].selected
+
+    # 2. Direct helper access
+    alt = response.gauge("altitude").predicted_value
+    breached = response.gate("geofence_breach")  # returns bool
+    man = response.route("maneuver")            # returns str
+
+    # 3. Fallback inspection
+    if response.gauges["altitude"].fallback_triggered:
+        print("Warning: Altitude gauge executed safe fallback envelope!")
+    if response.is_fallback:
+        print("Degraded heads:", response.fallback_heads)
+
+    print(f"Maneuver: {maneuver}, Altitude: {altitude}m (±{sigma})")
+
+except OminaOverloadError as e:
+    print(f"Edge daemon saturated after {e.retries} retries: {e}")
+```
+
+## Async Usage
+
+```python
+import asyncio
+from omina_client import AsyncOminaClient
+
+async def main():
+    async with AsyncOminaClient("http://localhost:8080") as client:
+        response = await client.evaluate("drone_flight", "Clear skies, nominal telemetry")
+        print("Altitude:", response.gauge("altitude").predicted_value)
+
+asyncio.run(main())
+```

omina_client-1.0.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "omina-client"
+version = "1.0.0"
+description = "Official Python client SDK for the Omina edge intelligence daemon"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+authors = [
+    { name = "Omina Project Maintainers" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/omina_client"]

omina_client-1.0.0/src/omina_client/__init__.py

@@ -0,0 +1,50 @@
+"""Omina Official Python Client SDK."""
+
+from omina_client.client import AsyncOminaClient, OminaClient
+from omina_client.exceptions import (
+    OminaBadRequestError,
+    OminaDeadlineError,
+    OminaError,
+    OminaHeadNotFoundError,
+    OminaInternalServerError,
+    OminaNotFoundError,
+    OminaOverloadError,
+    OminaSchemaError,
+    OminaUnprocessableEntityError,
+)
+from omina_client.models import (
+    ChoiceResult,
+    EvaluationResponse,
+    GateResult,
+    GaugeResult,
+    MultiDomainResponse,
+    NoulResult,
+    RouteResult,
+    ScoreResult,
+    SystemHealthResponse,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "OminaClient",
+    "AsyncOminaClient",
+    "EvaluationResponse",
+    "MultiDomainResponse",
+    "SystemHealthResponse",
+    "GaugeResult",
+    "GateResult",
+    "RouteResult",
+    "NoulResult",
+    "ChoiceResult",
+    "ScoreResult",
+    "OminaError",
+    "OminaOverloadError",
+    "OminaDeadlineError",
+    "OminaNotFoundError",
+    "OminaBadRequestError",
+    "OminaUnprocessableEntityError",
+    "OminaInternalServerError",
+    "OminaHeadNotFoundError",
+    "OminaSchemaError",
+]

omina_client-1.0.0/src/omina_client/client.py

@@ -0,0 +1,280 @@
+"""Synchronous and Asynchronous HTTP clients for the Omina Edge Serving Daemon."""
+
+import time
+import asyncio
+from typing import Any, Dict, List, Optional
+import httpx
+
+from omina_client.exceptions import (
+    OminaBadRequestError,
+    OminaDeadlineError,
+    OminaError,
+    OminaInternalServerError,
+    OminaNotFoundError,
+    OminaOverloadError,
+    OminaUnprocessableEntityError,
+)
+from omina_client.models import (
+    EvaluationResponse,
+    MultiDomainResponse,
+    SystemHealthResponse,
+)
+from omina_client.retry import compute_backoff, is_retryable_status, parse_retry_after
+
+
+def _extract_error_message(resp: httpx.Response) -> str:
+    try:
+        data = resp.json()
+        if isinstance(data, dict):
+            err = data.get("error")
+            details = data.get("details")
+            if err and details:
+                return f"{err}: {details}"
+            if err:
+                return str(err)
+    except Exception:
+        pass
+    text = resp.text.strip()
+    return text if text else f"HTTP {resp.status_code}"
+
+
+class OminaClient:
+    """Synchronous client for the Omina edge intelligence daemon with built-in backpressure handling."""
+
+    def __init__(
+        self,
+        base_url: str,
+        max_retries: int = 3,
+        base_backoff_ms: float = 50.0,
+        max_backoff_ms: float = 2000.0,
+        timeout: float = 10.0,
+        bearer_token: Optional[str] = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self.base_backoff_ms = base_backoff_ms
+        self.max_backoff_ms = max_backoff_ms
+        self.timeout = timeout
+        self.bearer_token = bearer_token
+
+        headers = {"Content-Type": "application/json"}
+        if self.bearer_token:
+            headers["Authorization"] = f"Bearer {self.bearer_token}"
+
+        self._client = httpx.Client(base_url=self.base_url, headers=headers, timeout=self.timeout)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "OminaClient":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
+
+    def evaluate(self, domain_id: str, context_log: str) -> EvaluationResponse:
+        """Evaluates a context text log against a registered domain head."""
+        payload = {"domain_id": domain_id, "context_log": context_log}
+        data = self._dispatch_post("/v1/evaluate", payload)
+        return EvaluationResponse.from_dict(data)
+
+    def evaluate_frame(
+        self, context_log: str, domains: Optional[List[str]] = None
+    ) -> MultiDomainResponse:
+        """Evaluates a context frame across multiple or all registered domains."""
+        payload: Dict[str, Any] = {"context_log": context_log}
+        if domains is not None:
+            payload["domains"] = domains
+        data = self._dispatch_post("/v1/evaluate/frame", payload)
+        return MultiDomainResponse.from_dict(data)
+
+    def health(self) -> SystemHealthResponse:
+        """Checks daemon health and resident encoder state via GET /system/health."""
+        data = self._dispatch_get("/system/health")
+        return SystemHealthResponse.from_dict(data)
+
+    def health_check(self) -> SystemHealthResponse:
+        """Alias for health()."""
+        return self.health()
+
+    def _dispatch_post(self, path: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        attempt = 0
+        while True:
+            try:
+                resp = self._client.post(path, json=payload)
+                if resp.is_success:
+                    return resp.json()
+
+                status = resp.status_code
+                if is_retryable_status(status):
+                    retry_after = parse_retry_after(resp.headers)
+                    err_msg = _extract_error_message(resp)
+
+                    if attempt >= self.max_retries:
+                        if status == 429:
+                            raise OminaOverloadError(err_msg, retries=attempt, retry_after=retry_after)
+                        else:
+                            raise OminaDeadlineError(err_msg, retries=attempt)
+
+                    delay = compute_backoff(
+                        attempt, self.base_backoff_ms, self.max_backoff_ms, retry_after
+                    )
+                    time.sleep(delay)
+                    attempt += 1
+                    continue
+
+                # Non-retryable error
+                err_msg = _extract_error_message(resp)
+                self._raise_for_status(status, err_msg)
+
+            except httpx.TransportError as e:
+                if attempt < self.max_retries:
+                    delay = compute_backoff(attempt, self.base_backoff_ms, self.max_backoff_ms)
+                    time.sleep(delay)
+                    attempt += 1
+                    continue
+                raise OminaError(f"HTTP transport failure: {e}") from e
+
+    def _dispatch_get(self, path: str) -> Dict[str, Any]:
+        try:
+            resp = self._client.get(path)
+            if resp.is_success:
+                return resp.json()
+            err_msg = _extract_error_message(resp)
+            self._raise_for_status(resp.status_code, err_msg)
+            return resp.json()
+        except httpx.TransportError as e:
+            raise OminaError(f"HTTP transport failure: {e}") from e
+
+    def _raise_for_status(self, status: int, err_msg: str) -> None:
+        if status == 404:
+            raise OminaNotFoundError(err_msg)
+        elif status == 400:
+            raise OminaBadRequestError(err_msg)
+        elif status == 422:
+            raise OminaUnprocessableEntityError(err_msg)
+        elif status == 500:
+            raise OminaInternalServerError(err_msg)
+        else:
+            raise OminaError(f"HTTP {status}: {err_msg}")
+
+
+class AsyncOminaClient:
+    """Asynchronous client for the Omina edge intelligence daemon with built-in backpressure handling."""
+
+    def __init__(
+        self,
+        base_url: str,
+        max_retries: int = 3,
+        base_backoff_ms: float = 50.0,
+        max_backoff_ms: float = 2000.0,
+        timeout: float = 10.0,
+        bearer_token: Optional[str] = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self.base_backoff_ms = base_backoff_ms
+        self.max_backoff_ms = max_backoff_ms
+        self.timeout = timeout
+        self.bearer_token = bearer_token
+
+        headers = {"Content-Type": "application/json"}
+        if self.bearer_token:
+            headers["Authorization"] = f"Bearer {self.bearer_token}"
+
+        self._client = httpx.AsyncClient(base_url=self.base_url, headers=headers, timeout=self.timeout)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncOminaClient":
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.aclose()
+
+    async def evaluate(self, domain_id: str, context_log: str) -> EvaluationResponse:
+        """Evaluates a context text log against a registered domain head."""
+        payload = {"domain_id": domain_id, "context_log": context_log}
+        data = await self._dispatch_post("/v1/evaluate", payload)
+        return EvaluationResponse.from_dict(data)
+
+    async def evaluate_frame(
+        self, context_log: str, domains: Optional[List[str]] = None
+    ) -> MultiDomainResponse:
+        """Evaluates a context frame across multiple or all registered domains."""
+        payload: Dict[str, Any] = {"context_log": context_log}
+        if domains is not None:
+            payload["domains"] = domains
+        data = await self._dispatch_post("/v1/evaluate/frame", payload)
+        return MultiDomainResponse.from_dict(data)
+
+    async def health(self) -> SystemHealthResponse:
+        """Checks daemon health and resident encoder state via GET /system/health."""
+        data = await self._dispatch_get("/system/health")
+        return SystemHealthResponse.from_dict(data)
+
+    async def health_check(self) -> SystemHealthResponse:
+        """Alias for health()."""
+        return await self.health()
+
+    async def _dispatch_post(self, path: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        attempt = 0
+        while True:
+            try:
+                resp = await self._client.post(path, json=payload)
+                if resp.is_success:
+                    return resp.json()
+
+                status = resp.status_code
+                if is_retryable_status(status):
+                    retry_after = parse_retry_after(resp.headers)
+                    err_msg = _extract_error_message(resp)
+
+                    if attempt >= self.max_retries:
+                        if status == 429:
+                            raise OminaOverloadError(err_msg, retries=attempt, retry_after=retry_after)
+                        else:
+                            raise OminaDeadlineError(err_msg, retries=attempt)
+
+                    delay = compute_backoff(
+                        attempt, self.base_backoff_ms, self.max_backoff_ms, retry_after
+                    )
+                    await asyncio.sleep(delay)
+                    attempt += 1
+                    continue
+
+                # Non-retryable error
+                err_msg = _extract_error_message(resp)
+                self._raise_for_status(status, err_msg)
+
+            except httpx.TransportError as e:
+                if attempt < self.max_retries:
+                    delay = compute_backoff(attempt, self.base_backoff_ms, self.max_backoff_ms)
+                    await asyncio.sleep(delay)
+                    attempt += 1
+                    continue
+                raise OminaError(f"HTTP transport failure: {e}") from e
+
+    async def _dispatch_get(self, path: str) -> Dict[str, Any]:
+        try:
+            resp = await self._client.get(path)
+            if resp.is_success:
+                return resp.json()
+            err_msg = _extract_error_message(resp)
+            self._raise_for_status(resp.status_code, err_msg)
+            return resp.json()
+        except httpx.TransportError as e:
+            raise OminaError(f"HTTP transport failure: {e}") from e
+
+    def _raise_for_status(self, status: int, err_msg: str) -> None:
+        if status == 404:
+            raise OminaNotFoundError(err_msg)
+        elif status == 400:
+            raise OminaBadRequestError(err_msg)
+        elif status == 422:
+            raise OminaUnprocessableEntityError(err_msg)
+        elif status == 500:
+            raise OminaInternalServerError(err_msg)
+        else:
+            raise OminaError(f"HTTP {status}: {err_msg}")

omina_client-1.0.0/src/omina_client/exceptions.py

@@ -0,0 +1,61 @@
+"""Exceptions emitted by the Omina Client SDK."""
+
+from typing import Optional
+
+
+class OminaError(Exception):
+    """Base exception for all Omina client errors."""
+    pass
+
+
+class OminaOverloadError(OminaError):
+    """Raised when the edge daemon's inference queue is saturated (HTTP 429)."""
+
+    def __init__(self, message: str, retries: int = 0, retry_after: Optional[float] = None):
+        super().__init__(f"{message} (exhausted {retries} retries)")
+        self.message = message
+        self.retries = retries
+        self.retry_after = retry_after
+
+
+class OminaDeadlineError(OminaError):
+    """Raised when an inference request exceeds the server-side deadline (HTTP 503/504)."""
+
+    def __init__(self, message: str, retries: int = 0):
+        super().__init__(f"{message} (exhausted {retries} retries)")
+        self.message = message
+        self.retries = retries
+
+
+class OminaNotFoundError(OminaError):
+    """Raised when the requested domain or endpoint does not exist on the daemon (HTTP 404)."""
+    pass
+
+
+class OminaBadRequestError(OminaError):
+    """Raised when the client request payload is malformed (HTTP 400)."""
+    pass
+
+
+class OminaUnprocessableEntityError(OminaError):
+    """Raised when the request payload cannot be processed (HTTP 422)."""
+    pass
+
+
+class OminaInternalServerError(OminaError):
+    """Raised when the daemon encounters an unhandled internal error (HTTP 500)."""
+    pass
+
+
+class OminaHeadNotFoundError(OminaError):
+    """Raised when attempting to retrieve an unknown head ID from an evaluation response."""
+
+    def __init__(self, head_id: str, domain_id: str):
+        super().__init__(f"Head '{head_id}' not found in domain '{domain_id}' response")
+        self.head_id = head_id
+        self.domain_id = domain_id
+
+
+class OminaSchemaError(OminaError):
+    """Raised when a response fails schema validation or JSON decoding."""
+    pass