Metadata-Version: 2.5
Name: poe-edge
Version: 1.0.0
Summary: Official Python client SDK for the POE edge intelligence daemon
Author: POE 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

# POE Python Client SDK (`poe-py` / `poe-client`)

The official Python client SDK for the **POE (Predictive Operational Edge)** 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 (`PoeClient`) and async (`AsyncPoeClient`) clients built on top of `httpx`.

## Installation

```sh
pip install poe-edge
```

## Quickstart

```python
from poe_client import PoeClient
from poe_client.exceptions import PoeOverloadError

client = PoeClient(
    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 PoeOverloadError as e:
    print(f"Edge daemon saturated after {e.retries} retries: {e}")
```

## Async Usage

```python
import asyncio
from poe_client import AsyncPoeClient

async def main():
    async with AsyncPoeClient("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())
```
