zarx 0.2.0__py3-none-any.whl

zarx/__init__.py

@@ -0,0 +1,64 @@
+"""Zarx: OpenAI-compatible inference from NPAW's own GPUs in Europe."""
+
+from . import audio, models, voices
+from ._client import AsyncZarx, Zarx
+from ._config import BETA_BASE_URL, ENVIRONMENTS, PRODUCTION_BASE_URL, STAGE_BASE_URL
+from ._version import __version__
+from .errors import (
+    APIConnectionError,
+    APIError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    InternalServerError,
+    NotFoundError,
+    OpenAIError,
+    PermissionDeniedError,
+    RateLimitError,
+    ZarxConfigError,
+)
+from .forecasting import Forecast, ForecastPoint, forecast, forecast_csv
+from .models import TIERS, Z_FAST, Z_FORECAST, Z_PRO, Z_SPEECH, Z_TRANSCRIBE, Z_TRANSLATE, Z_ULTRA, Z_VOICE, pin, tier_of
+from .reasoning import reasoning_text
+
+__all__ = [
+    "Zarx",
+    "AsyncZarx",
+    "PRODUCTION_BASE_URL",
+    "BETA_BASE_URL",
+    "STAGE_BASE_URL",
+    "ENVIRONMENTS",
+    "__version__",
+    "audio",
+    "models",
+    "voices",
+    "TIERS",
+    "Z_ULTRA",
+    "Z_PRO",
+    "Z_FAST",
+    "Z_TRANSCRIBE",
+    "Z_SPEECH",
+    "Z_TRANSLATE",
+    "Z_VOICE",
+    "Z_FORECAST",
+    "pin",
+    "tier_of",
+    "reasoning_text",
+    "forecast",
+    "forecast_csv",
+    "Forecast",
+    "ForecastPoint",
+    "APIConnectionError",
+    "APIError",
+    "APIStatusError",
+    "APITimeoutError",
+    "AuthenticationError",
+    "BadRequestError",
+    "InternalServerError",
+    "NotFoundError",
+    "OpenAIError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ZarxConfigError",
+]

zarx/__main__.py

@@ -0,0 +1,3 @@
+from .cli.main import main
+
+raise SystemExit(main())

zarx/_client.py

@@ -0,0 +1,66 @@
+"""Zarx clients: the official OpenAI clients pointed at Zarx with Zarx defaults."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import openai
+
+from ._config import DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, resolve_api_key, resolve_base_url
+from ._responses import AsyncZarxResponses, ZarxResponses
+from ._version import __version__
+
+
+def _zarx_kwargs(api_key: Optional[str], base_url: Optional[str], environment: Optional[str], kwargs: dict) -> dict:
+    kwargs.setdefault("timeout", DEFAULT_TIMEOUT)
+    kwargs.setdefault("max_retries", DEFAULT_MAX_RETRIES)
+    return {"api_key": resolve_api_key(api_key), "base_url": resolve_base_url(base_url, environment), **kwargs}
+
+
+def _user_agent() -> str:
+    return f"OpenAI/Python {openai.__version__} zarx-python/{__version__}"
+
+
+class Zarx(openai.OpenAI):
+    """Synchronous Zarx client. Everything the OpenAI client does, against Zarx.
+
+    Key: ``api_key`` or ``ZARX_API_KEY``. Endpoint: ``base_url``, then ``environment``
+    (``"production"``, the default, at https://api.zarx.ai/v1, or ``"beta"`` at
+    https://api-stage.zarx.ai/v1, which gets new models and features first), then
+    ``ZARX_BASE_URL``, then ``ZARX_ENVIRONMENT``. Responses default to ``store=False``.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        environment: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**_zarx_kwargs(api_key, base_url, environment, kwargs))
+        # Older openai releases build resources in __init__, newer ones lazily: assign after both.
+        self.responses = ZarxResponses(self)  # type: ignore[misc,assignment]
+
+    @property
+    def user_agent(self) -> str:
+        return _user_agent()
+
+
+class AsyncZarx(openai.AsyncOpenAI):
+    """Asynchronous Zarx client. Same defaults as :class:`Zarx`."""
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        environment: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**_zarx_kwargs(api_key, base_url, environment, kwargs))
+        self.responses = AsyncZarxResponses(self)  # type: ignore[misc,assignment]
+
+    @property
+    def user_agent(self) -> str:
+        return _user_agent()

zarx/_config.py

@@ -0,0 +1,67 @@
+"""Resolve where and how the client talks to Zarx: environment, base URL, key, timeouts, retries."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+
+import openai
+
+PRODUCTION_BASE_URL = "https://api.zarx.ai/v1"
+BETA_BASE_URL = "https://api-stage.zarx.ai/v1"
+# Beta is served by the stage environment; the old name stays for existing code.
+STAGE_BASE_URL = BETA_BASE_URL
+
+# Production is the default. Beta gets new models and features first and may change.
+ENVIRONMENTS: Dict[str, str] = {"production": PRODUCTION_BASE_URL, "beta": BETA_BASE_URL}
+_ENVIRONMENT_ALIASES = {"prod": "production", "stage": "beta"}
+
+API_KEY_ENV = "ZARX_API_KEY"
+BASE_URL_ENV = "ZARX_BASE_URL"
+ENVIRONMENT_ENV = "ZARX_ENVIRONMENT"
+
+# Reasoning tiers can think for a while before the first token: allow long reads,
+# but fail fast when the host cannot be reached.
+DEFAULT_TIMEOUT = openai.Timeout(300.0, connect=10.0)
+DEFAULT_MAX_RETRIES = 2
+
+
+class ZarxConfigError(openai.OpenAIError):
+    """Raised when the client cannot be configured (for example, no API key)."""
+
+
+def resolve_environment(environment: Optional[str]) -> str:
+    """Argument first, then ZARX_ENVIRONMENT, then production. Returns "production" or "beta"."""
+    raw = environment or os.environ.get(ENVIRONMENT_ENV) or "production"
+    name = str(raw).strip().lower()
+    name = _ENVIRONMENT_ALIASES.get(name, name)
+    if name not in ENVIRONMENTS:
+        source = "environment" if environment else ENVIRONMENT_ENV
+        valid = ", ".join(f'"{key}"' for key in ENVIRONMENTS)
+        raise ZarxConfigError(f"Unknown Zarx {source} {raw!r}. Use {valid} (aliases: \"prod\", \"stage\").")
+    return name
+
+
+def resolve_base_url(base_url: Optional[Any], environment: Optional[str] = None) -> str:
+    """base_url, then environment, then ZARX_BASE_URL, then ZARX_ENVIRONMENT, then production.
+
+    What the code says beats what the shell says. Never OPENAI_BASE_URL, so an
+    OpenAI setting never redirects Zarx traffic.
+    """
+    # client.copy() passes the current base URL back as a URL object, not a str.
+    value = str(base_url or "")
+    if not value and environment:
+        value = ENVIRONMENTS[resolve_environment(environment)]
+    if not value:
+        value = os.environ.get(BASE_URL_ENV) or ENVIRONMENTS[resolve_environment(None)]
+    return value.rstrip("/")
+
+
+def resolve_api_key(api_key: Optional[str]) -> str:
+    """Argument first, then ZARX_API_KEY. Never OPENAI_API_KEY, so an OpenAI key is never sent to Zarx."""
+    value = api_key or os.environ.get(API_KEY_ENV)
+    if not value:
+        raise ZarxConfigError(
+            f"No Zarx API key. Pass api_key=... or set the {API_KEY_ENV} environment variable."
+        )
+    return value

zarx/_forecast_result.py

@@ -0,0 +1,100 @@
+"""The typed result of a forecast: points with a value, an optional band and the percentiles."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterator, List, Mapping, Optional
+
+
+@dataclass(frozen=True)
+class ForecastPoint:
+    """One forecast period."""
+
+    timestamp: str
+    """ISO 8601 time of the period, as the API returned it."""
+    value: float
+    """The point forecast."""
+    low: Optional[float] = None
+    """Lower bound of the band (``include_band=True``), else None."""
+    high: Optional[float] = None
+    """Upper bound of the band (``include_band=True``), else None."""
+    percentiles: Dict[str, float] = field(default_factory=dict)
+    """Percentile values keyed by percentile (``"10"``, ``"50"``, ``"90"``, plus any requested)."""
+
+
+@dataclass(frozen=True)
+class Forecast:
+    """What ``zarx.forecast`` returns. Iterate it, index it, or read ``values``."""
+
+    points: List[ForecastPoint]
+    raw: Dict[str, Any]
+    """The response exactly as the API returned it."""
+    billable_points: int = 0
+    """Data points the call is billed for: ``usage.datapoints`` from the response when the API
+    sends it, otherwise computed as the API bills (the context points sent, capped by
+    ``data_points``, plus the forecast points)."""
+
+    @property
+    def values(self) -> List[float]:
+        return [p.value for p in self.points]
+
+    @property
+    def timestamps(self) -> List[str]:
+        return [p.timestamp for p in self.points]
+
+    @property
+    def lows(self) -> List[Optional[float]]:
+        return [p.low for p in self.points]
+
+    @property
+    def highs(self) -> List[Optional[float]]:
+        return [p.high for p in self.points]
+
+    def __len__(self) -> int:
+        return len(self.points)
+
+    def __iter__(self) -> Iterator[ForecastPoint]:
+        return iter(self.points)
+
+    def __getitem__(self, index: int) -> ForecastPoint:
+        return self.points[index]
+
+
+def _optional_float(value: Any) -> Optional[float]:
+    return None if value is None else float(value)
+
+
+def _usage_datapoints(raw: Mapping[str, Any]) -> Optional[int]:
+    """``usage.datapoints`` when the response carries a whole non-negative number there, else None."""
+    usage = raw.get("usage")
+    if not isinstance(usage, Mapping):
+        return None
+    value = usage.get("datapoints")
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    if value < 0 or value != int(value):
+        return None
+    return int(value)
+
+
+def parse_forecast(raw: Mapping[str, Any], context_points: int = 0) -> Forecast:
+    """Build a :class:`Forecast` from the JSON of ``POST /v1/forecasts``; ``context_points`` is
+    what was sent as context, used for ``billable_points`` when the response has no usage."""
+    rows = raw.get("forecast")
+    if not isinstance(rows, list):
+        raise ValueError("forecast response has no 'forecast' list")
+    points = [
+        ForecastPoint(
+            timestamp=str(row.get("timestamp", "")),
+            value=float(row["forecast"]),
+            low=_optional_float(row.get("p_low")),
+            high=_optional_float(row.get("p_high")),
+            percentiles={str(k): float(v) for k, v in (row.get("percentiles") or {}).items()},
+        )
+        for row in rows
+    ]
+    billed = _usage_datapoints(raw)
+    if billed is None:
+        billed = context_points + len(points)
+    return Forecast(points=points, raw=dict(raw), billable_points=billed)
+

zarx/_realtime.py

@@ -0,0 +1,149 @@
+"""Realtime transcription over Zarx's WebSocket route (not the OpenAI Realtime API).
+
+Route: ``wss://<host>/v1/audio/transcriptions/realtime?model=<model>`` with the key as a bearer
+token. The client sends ``session.update``, then ``input_audio_buffer.append`` events with
+base64 PCM16 mono 16 kHz, then ``input_audio_buffer.commit`` with ``final: true``. The server
+answers ``transcript.delta`` (``text``), ``transcript.segment`` (``index``, ``text``) and
+``done`` with a ``summary`` whose ``final_text`` is the transcript. Verified on stage on
+2026-11-01. Needs the ``websockets`` package: ``pip install "zarx[realtime]"``.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import json
+import threading
+import wave
+from pathlib import Path
+from typing import IO, Any, Callable, Iterable, Iterator, List, Optional, Union
+from urllib.parse import quote
+
+import openai
+
+from ._client import Zarx
+
+REALTIME_PATH = "/audio/transcriptions/realtime"
+SAMPLE_RATE = 16_000
+CHUNK_BYTES = 3_200  # 100 ms of PCM16 mono at 16 kHz
+
+PcmSource = Union[str, Path, bytes, IO[bytes], Iterable[bytes]]
+
+
+class RealtimeError(openai.OpenAIError):
+    """The realtime route reported an error event or closed before the transcript was done."""
+
+
+def realtime_url(client: Zarx, model: str) -> str:
+    base = str(client.base_url).rstrip("/")
+    if base.startswith("https://"):
+        base = "wss://" + base[len("https://"):]
+    elif base.startswith("http://"):
+        base = "ws://" + base[len("http://"):]
+    return f"{base}{REALTIME_PATH}?model={quote(model, safe='')}"
+
+
+def pcm_chunks(audio: PcmSource) -> Iterator[bytes]:
+    """PCM16 mono 16 kHz chunks from a WAV path or file, raw PCM bytes, or an iterable of chunks."""
+    if isinstance(audio, (str, Path)):
+        with open(audio, "rb") as handle:
+            yield from _chunks(_wav_pcm(handle.read()))
+    elif isinstance(audio, (bytes, bytearray)):
+        data = bytes(audio)
+        yield from _chunks(_wav_pcm(data) if data[:4] == b"RIFF" else data)
+    elif hasattr(audio, "read"):
+        yield from _chunks(_wav_pcm(audio.read()))  # type: ignore[union-attr]
+    else:
+        for chunk in audio:  # type: ignore[union-attr]
+            if chunk:
+                yield bytes(chunk)
+
+
+def _source(audio: PcmSource) -> Iterable[bytes]:
+    """Files and bytes are read and checked before connecting; an iterable (a microphone) streams."""
+    if isinstance(audio, (str, Path, bytes, bytearray)) or hasattr(audio, "read"):
+        return list(pcm_chunks(audio))
+    return pcm_chunks(audio)
+
+
+def _wav_pcm(data: bytes) -> bytes:
+    if data[:4] != b"RIFF":
+        return data  # raw PCM
+    with wave.open(io.BytesIO(data)) as reader:
+        rate, channels, width = reader.getframerate(), reader.getnchannels(), reader.getsampwidth()
+        if (rate, channels, width) != (SAMPLE_RATE, 1, 2):
+            raise ValueError(
+                f"realtime transcription takes PCM16 mono {SAMPLE_RATE} Hz; this WAV is {rate} Hz, "
+                f"{channels} channel(s), {width * 8} bit. Convert it, for example: "
+                f"ffmpeg -i in.wav -ar {SAMPLE_RATE} -ac 1 -sample_fmt s16 out.wav"
+            )
+        return reader.readframes(reader.getnframes())
+
+
+def _chunks(pcm: bytes) -> Iterator[bytes]:
+    for start in range(0, len(pcm), CHUNK_BYTES):
+        yield pcm[start : start + CHUNK_BYTES]
+
+
+def _connect(url: str, api_key: str, timeout: float) -> Any:
+    try:
+        from websockets.sync.client import connect
+    except ImportError as exc:  # pragma: no cover - depends on the environment
+        raise ImportError('realtime transcription needs the websockets package: pip install "zarx[realtime]"') from exc
+    return connect(url, additional_headers={"Authorization": f"Bearer {api_key}"}, open_timeout=timeout)
+
+
+def transcribe_realtime(
+    audio: PcmSource,
+    *,
+    client: Zarx,
+    model: str,
+    on_delta: Optional[Callable[[str], None]] = None,
+    on_segment: Optional[Callable[[str], None]] = None,
+    timeout: float = 60.0,
+) -> str:
+    """Send the audio and return the final transcript. ``on_delta`` gets each piece of text as
+    it is recognised; ``on_segment`` gets each finished sentence. The audio is sent from a
+    thread while events are read, so text arrives while a long file or a microphone still plays."""
+    chunks = _source(audio)
+    segments: List[str] = []
+    send_errors: List[BaseException] = []
+    with _connect(realtime_url(client, model), client.api_key, timeout) as ws:
+        ws.send(json.dumps({"type": "session.update", "model": model}))
+
+        def send_audio() -> None:
+            try:
+                for chunk in chunks:
+                    ws.send(json.dumps({"type": "input_audio_buffer.append", "audio": base64.b64encode(chunk).decode("ascii")}))
+                ws.send(json.dumps({"type": "input_audio_buffer.commit", "final": True}))
+            except BaseException as exc:  # surfaced by the receiving loop
+                send_errors.append(exc)
+                ws.close()
+
+        sender = threading.Thread(target=send_audio, name="zarx-realtime-sender", daemon=True)
+        sender.start()
+        while True:
+            try:
+                message = ws.recv(timeout=timeout)
+            except TimeoutError as exc:
+                raise RealtimeError(f"no event from the realtime route in {timeout:g} s") from exc
+            except Exception as exc:  # the server closed the socket before 'done'
+                if send_errors:
+                    raise send_errors[0]
+                raise RealtimeError(f"realtime connection closed before the transcript was done: {exc}") from exc
+            event = json.loads(message)
+            kind = event.get("type")
+            if kind == "transcript.delta" and on_delta:
+                on_delta(event.get("text") or "")
+            elif kind == "transcript.segment":
+                segments.append(event.get("text") or "")
+                if on_segment:
+                    on_segment(event.get("text") or "")
+            elif kind == "error":
+                raise RealtimeError(str(event.get("message") or event))
+            elif kind == "done":
+                final = (event.get("summary") or {}).get("final_text")
+                return str(final).strip() if final else " ".join(s.strip() for s in segments)
+            elif kind == "session.closed":
+                raise RealtimeError("realtime session closed before the transcript was done")
+

zarx/_responses.py

@@ -0,0 +1,36 @@
+"""Responses resource that defaults to store=False, so no response is stored for retrieval unless asked."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from openai.resources.responses import AsyncResponses, Responses
+
+
+def _default_store(kwargs: dict) -> dict:
+    # Resuming a stream by response_id does not take a store flag.
+    if "response_id" not in kwargs:
+        kwargs.setdefault("store", False)
+    return kwargs
+
+
+class ZarxResponses(Responses):
+    def create(self, *args: Any, **kwargs: Any) -> Any:
+        return super().create(*args, **_default_store(kwargs))
+
+    def stream(self, *args: Any, **kwargs: Any) -> Any:
+        return super().stream(*args, **_default_store(kwargs))
+
+    def parse(self, *args: Any, **kwargs: Any) -> Any:
+        return super().parse(*args, **_default_store(kwargs))
+
+
+class AsyncZarxResponses(AsyncResponses):
+    async def create(self, *args: Any, **kwargs: Any) -> Any:
+        return await super().create(*args, **_default_store(kwargs))
+
+    def stream(self, *args: Any, **kwargs: Any) -> Any:
+        return super().stream(*args, **_default_store(kwargs))
+
+    async def parse(self, *args: Any, **kwargs: Any) -> Any:
+        return await super().parse(*args, **_default_store(kwargs))

zarx/_series.py

@@ -0,0 +1,121 @@
+"""Turn what a caller has (numbers, pairs, dicts, a mapping) into the points /v1/forecasts takes.
+
+The API wants ``[{"timestamp": <ISO 8601>, "value": <number>, ...covariates}]`` with at least
+three points. Bare numbers get generated timestamps so the simplest call stays one line.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import date, datetime, timedelta, timezone
+from numbers import Real
+from typing import Any, Dict, Iterable, List, Mapping, Sequence, Union
+
+Timestamp = Union[str, datetime, date, int, float]
+Point = Dict[str, Any]
+
+MIN_POINTS = 3
+DEFAULT_STEP = "1h"
+
+_STEP = re.compile(r"^\s*(\d+)\s*(s|sec|m|min|h|d|w)\s*$", re.IGNORECASE)
+_STEP_SECONDS = {"s": 1, "sec": 1, "m": 60, "min": 60, "h": 3600, "d": 86400, "w": 604800}
+
+
+def parse_step(step: Union[str, timedelta]) -> timedelta:
+    """``"15min"``, ``"1h"``, ``"1d"``, ``"30s"``, ``"1w"`` or a timedelta."""
+    if isinstance(step, timedelta):
+        if step <= timedelta(0):
+            raise ValueError("step must be positive")
+        return step
+    match = _STEP.match(str(step))
+    if not match:
+        raise ValueError(f"step must look like 30s, 15min, 1h, 1d or 1w, got {step!r}")
+    return timedelta(seconds=int(match.group(1)) * _STEP_SECONDS[match.group(2).lower()])
+
+
+def iso_timestamp(value: Timestamp) -> str:
+    """ISO 8601 text for a timestamp. Naive datetimes are taken as UTC, numbers as Unix seconds."""
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=timezone.utc)
+        return value.isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    if isinstance(value, bool):
+        raise TypeError("a timestamp cannot be a bool")
+    if isinstance(value, Real):
+        return datetime.fromtimestamp(float(value), tz=timezone.utc).isoformat()
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    raise TypeError(f"timestamp must be text, a datetime, a date or Unix seconds, got {type(value).__name__}")
+
+
+def _number(value: Any, where: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, Real):
+        raise TypeError(f"{where} must be a number, got {type(value).__name__}")
+    return float(value)
+
+
+def _generated_timestamps(count: int, step: Union[str, timedelta], start: Union[Timestamp, None]) -> List[str]:
+    delta = parse_step(step)
+    if start is None:
+        # The series ends now, on a whole step, so the forecast covers the coming periods.
+        now = datetime.now(timezone.utc).replace(microsecond=0)
+        whole = int(delta.total_seconds())
+        end = datetime.fromtimestamp((int(now.timestamp()) // whole) * whole, tz=timezone.utc)
+        first = end - delta * (count - 1)
+    else:
+        first = _as_datetime(start)
+    return [(first + delta * i).isoformat() for i in range(count)]
+
+
+def _as_datetime(value: Timestamp) -> datetime:
+    if isinstance(value, datetime):
+        return value if value.tzinfo else value.replace(tzinfo=timezone.utc)
+    if isinstance(value, date):
+        return datetime(value.year, value.month, value.day, tzinfo=timezone.utc)
+    if isinstance(value, Real) and not isinstance(value, bool):
+        return datetime.fromtimestamp(float(value), tz=timezone.utc)
+    text = str(value).strip().replace("Z", "+00:00")
+    parsed = datetime.fromisoformat(text)
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+
+
+def to_points(series: Any, *, step: Union[str, timedelta] = DEFAULT_STEP, start: Union[Timestamp, None] = None) -> List[Point]:
+    """Accepts bare numbers, ``(timestamp, value)`` pairs, dicts with ``timestamp`` and ``value``
+    (extra keys travel as covariates), or a mapping of timestamp to value (a dict, a pandas Series).
+
+    Bare numbers get one timestamp every ``step`` (default one hour), ending now unless ``start``
+    is given. At least three points are required.
+    """
+    if isinstance(series, (str, bytes)):
+        raise TypeError("series must be a sequence of numbers, pairs or points, not text")
+    items: Iterable[Any] = series.items() if hasattr(series, "items") else series
+    rows = list(items)
+    if len(rows) < MIN_POINTS:
+        raise ValueError(f"series must contain at least {MIN_POINTS} points, got {len(rows)}")
+
+    first = rows[0]
+    if isinstance(first, Mapping):
+        return [_point_from_mapping(row, i) for i, row in enumerate(rows)]
+    if isinstance(first, Sequence) and not isinstance(first, str):
+        return [_point_from_pair(row, i) for i, row in enumerate(rows)]
+    values = [_number(v, f"series[{i}]") for i, v in enumerate(rows)]
+    stamps = _generated_timestamps(len(values), step, start)
+    return [{"timestamp": ts, "value": v} for ts, v in zip(stamps, values)]
+
+
+def _point_from_mapping(row: Mapping[str, Any], index: int) -> Point:
+    if "timestamp" not in row or "value" not in row:
+        raise ValueError(f"series[{index}] needs 'timestamp' and 'value' keys")
+    point = dict(row)
+    point["timestamp"] = iso_timestamp(point["timestamp"])
+    point["value"] = _number(point["value"], f"series[{index}]['value']")
+    return point
+
+
+def _point_from_pair(row: Sequence[Any], index: int) -> Point:
+    if len(row) != 2:
+        raise ValueError(f"series[{index}] must be a (timestamp, value) pair, got {len(row)} items")
+    return {"timestamp": iso_timestamp(row[0]), "value": _number(row[1], f"series[{index}][1]")}
+

zarx/_speech_stream.py

@@ -0,0 +1,53 @@
+"""Speech that arrives in pieces: the server-sent events of ``stream_format="sse"``."""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any, Callable, ContextManager, Dict, Iterable, Iterator, Optional
+
+DELTA = "speech.audio.delta"
+DONE = "speech.audio.done"
+
+
+class SpeechStream:
+    """Iterate it to get the audio bytes piece by piece; ``usage`` is set once it is exhausted.
+
+    Where the endpoint does not stream (a deployment that ignores ``stream_format``),
+    the whole audio comes as a single piece and ``usage`` stays None.
+    """
+
+    def __init__(self, open_response: Callable[[], ContextManager[Any]]) -> None:
+        self._open = open_response
+        self.usage: Optional[Dict[str, Any]] = None
+
+    def __iter__(self) -> Iterator[bytes]:
+        with self._open() as response:
+            if "text/event-stream" not in response.headers.get("content-type", ""):
+                yield response.read()
+                return
+            for event in parse_events(response.iter_lines()):
+                if event.get("type") == DELTA and event.get("audio"):
+                    yield base64.b64decode(event["audio"])
+                elif event.get("type") == DONE:
+                    self.usage = event.get("usage")
+
+    def read(self) -> bytes:
+        """All the audio at once."""
+        return b"".join(self)
+
+
+def parse_events(lines: Iterable[str]) -> Iterator[Dict[str, Any]]:
+    """The JSON payload of every ``data:`` line; other lines (comments, blanks) are skipped."""
+    for line in lines:
+        if not line.startswith("data:"):
+            continue
+        payload = line[len("data:"):].strip()
+        if not payload or payload == "[DONE]":
+            continue
+        try:
+            event = json.loads(payload)
+        except ValueError:
+            continue
+        if isinstance(event, dict):
+            yield event

zarx/_version.py

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