spe.client.SPEClient is a thin, typed client for a running SPE engine server. It is a context manager.

from spe import SPEClient

with SPEClient("http://127.0.0.1:5000") as client:
    client.health()

Constructor

SPEClient(
    base_url: str = "http://127.0.0.1:5000",
    *,
    timeout: float = 30.0,
    retries: int = 2,
    backoff: float = 0.5,
    user_agent: str | None = None,
    transport: Transport | None = None,
) -> None

Raises SPEValidationError when base_url is empty or not a string.

Lifecycle

Health and state

Sources

source may be bytes, bytearray, memoryview, str/os.PathLike path, or a binary file object.

Calibration

ROI and grid

Spatial queries

transform_points

transform_points(
    points,
    *,
    homography=None,
    calibration=None,
    direction="image_to_reference",
) -> dict

Posts to POST /api/calibration/transform. Provide a homography or a calibration mapping.

inspect_point

inspect_point(
    point=None,
    *,
    x=None, y=None,
    calibration=None,
    grid=None,
    source_dimensions=None,
    spatial_state=None,
) -> dict

Posts to POST /api/spatial/inspect-point. Supply either point or both x and y (otherwise SPEValidationError). When spatial_state is given it is used directly; otherwise calibration/grid/source_dimensions are sent.

Rendering

The rendering methods return {"image": ..., "metadata": {...}}.

Models

Analysis

detect

detect(*, model_id="model-a", confidence=0.4, classes=None, source_id=None) -> dict

POST /api/analysis/detect.

detect_frame

detect_frame(
    frame,
    *,
    filename="frame.jpg",
    model_id="model-a",
    confidence=0.4,
    classes=None,
    analysis_id="analysis",
    source_id="source",
    timestamp=0.0,
    frame_index=0,
    tracking=False,
    tracking_mode=None,
    target_track_id=None,
    target_detection=None,
    inference_context=None,
    spatial_context=None,
    interval_ms=None,
    effective_fps=None,
) -> dict

POST /api/analysis/detect-frame. Detects and (optionally) tracks, spatializes, and timestamps a single frame.

Session methods

spe.aio.AsyncSPEClient mirrors SPEClient. Every method is a coroutine; the synchronous client runs in a worker thread (asyncio.to_thread).

import asyncio
from spe import AsyncSPEClient


async def main() -> None:
    async with AsyncSPEClient("http://127.0.0.1:5000") as client:
        await client.health()


asyncio.run(main())

Constructor arguments are forwarded verbatim to SPEClient. Additional members:

Async methods (all coroutines; signatures match SPEClient):

health, get_state, create_source, get_source, delete_source, source_media_url (sync), get_source_media, calibrate, get_calibration, update_calibration, delete_calibration, get_roi, create_roi, delete_roi, get_grid, set_grid, delete_grid, transform_points, inspect_point, generate_grid, generate_calibrated_grid, video_metadata, list_models, get_model, model_status, load_model, unload_model, model_classes, detect, detect_frame, start_analysis_session, update_analysis_status, complete_analysis_session.

spe.transport. A transport performs exactly one request and never retries; retries, timeouts, and error mapping live in the client. Transport-level failures are raised as SPEConnectionError or SPETimeoutError.

Transport (protocol)

class Transport(Protocol):
    def request(
        self,
        method: str,
        url: str,
        *,
        headers: Mapping[str, str],
        data: bytes | None,
        timeout: float,
    ) -> tuple[int, Mapping[str, str], bytes]: ...
    def close(self) -> None: ...

Backends

get_default_transport

get_default_transport(prefer: str | None = None) -> Transport

With prefer=None, returns HttpxTransport if httpx is importable, then RequestsTransport if requests is importable, otherwise UrllibTransport. Pass "urllib", "requests", or "httpx" to force a backend; an unknown name raises ValueError.

All errors derive from SPEError.

SPEAPIError exposes status_code: int | None, payload: Any | None, url: str | None, retry_after: float | None, and response_headers: dict. The status-specific subclasses keep except SPEAPIError handlers valid.