tazo-sdk 0.1.0__py3-none-any.whl

tazo/__init__.py

@@ -0,0 +1,45 @@
+"""Tazo's typed SDK for uploaded and streaming audio decisions."""
+
+from ._audio import wav_chunks
+from ._version import __version__
+from .client import AsyncTazo, Tazo
+from .errors import (
+    AuthenticationError,
+    ConnectionError,
+    DecisionPendingError,
+    IdempotencyConflictError,
+    InvalidRequestError,
+    NotFoundError,
+    PermissionDeniedError,
+    ProtocolError,
+    RateLimitError,
+    RequestTooLargeError,
+    ServiceError,
+    StreamingError,
+    TazoError,
+    TimeoutError,
+)
+from .types import ChoiceQuestion, NoulQuestion
+
+__all__ = [
+    "AsyncTazo",
+    "AuthenticationError",
+    "ChoiceQuestion",
+    "ConnectionError",
+    "DecisionPendingError",
+    "IdempotencyConflictError",
+    "InvalidRequestError",
+    "NotFoundError",
+    "NoulQuestion",
+    "PermissionDeniedError",
+    "ProtocolError",
+    "RateLimitError",
+    "RequestTooLargeError",
+    "ServiceError",
+    "StreamingError",
+    "Tazo",
+    "TazoError",
+    "TimeoutError",
+    "__version__",
+    "wav_chunks",
+]

tazo/_audio.py

@@ -0,0 +1,87 @@
+"""Bounded, replayable uploads and standard-library WAV helpers."""
+
+from __future__ import annotations
+
+import mimetypes
+import os
+import wave
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import BinaryIO
+
+from .errors import InvalidRequestError, RequestTooLargeError
+
+AudioInput = str | os.PathLike[str] | bytes | BinaryIO
+MAX_UPLOAD_BYTES = 16 * 1024 * 1024
+
+
+@dataclass(frozen=True, repr=False)
+class Upload:
+    """One immutable snapshot, reused unchanged for every HTTP attempt."""
+
+    data: bytes
+    filename: str
+    content_type: str
+
+
+def snapshot_audio(audio: AudioInput, filename: str | None, content_type: str | None) -> Upload:
+    name = "audio"
+    if isinstance(audio, bytes):
+        data = audio
+    elif isinstance(audio, (str, os.PathLike)):
+        path = Path(audio)
+        name = path.name
+        with path.open("rb") as handle:
+            data = handle.read(MAX_UPLOAD_BYTES + 1)
+    else:
+        candidate = getattr(audio, "name", None)
+        if isinstance(candidate, str):
+            name = Path(candidate).name
+        position = audio.tell() if audio.seekable() else None
+        try:
+            data = audio.read(MAX_UPLOAD_BYTES + 1)
+        finally:
+            if position is not None:
+                audio.seek(position)
+        if not isinstance(data, bytes):
+            raise InvalidRequestError("Audio must be a binary file, bytes, or a filesystem path.")
+    if not data:
+        raise InvalidRequestError("Audio must not be empty.")
+    if len(data) > MAX_UPLOAD_BYTES:
+        raise RequestTooLargeError("Audio uploads are limited to 16 MiB.")
+    name = Path(filename).name if filename else name
+    media_type = content_type or mimetypes.guess_type(name)[0] or "application/octet-stream"
+    return Upload(data, name, media_type)
+
+
+def wav_chunks(path: str | os.PathLike[str], *, chunk_ms: int = 100) -> Iterator[bytes]:
+    """Yield raw mono 16 kHz PCM16 from a WAV, without headers or real-time pacing.
+
+    Args:
+        path: PCM16 WAV recording. Compressed WAV and other formats are rejected.
+        chunk_ms: Chunk size from 1 to 200 milliseconds.
+
+    Yields:
+        Binary audio frames suitable for ``session.send_audio``.
+    """
+    if isinstance(chunk_ms, bool) or not isinstance(chunk_ms, int) or not 1 <= chunk_ms <= 200:
+        raise InvalidRequestError("chunk_ms must be an integer between 1 and 200.")
+    with wave.open(str(path), "rb") as handle:
+        if (
+            handle.getnchannels(),
+            handle.getsampwidth(),
+            handle.getframerate(),
+            handle.getcomptype(),
+        ) != (1, 2, 16000, "NONE"):
+            raise InvalidRequestError("Streaming requires a mono, 16 kHz, PCM16 WAV.")
+        if handle.getnframes() == 0:
+            raise InvalidRequestError("Audio must not be empty.")
+        remaining = handle.getnframes()
+        while remaining:
+            frames = min(chunk_ms * 16, remaining)
+            data = handle.readframes(frames)
+            if len(data) != frames * 2:
+                raise InvalidRequestError("The WAV file is truncated.")
+            remaining -= frames
+            yield data

tazo/_http.py

@@ -0,0 +1,327 @@
+"""Shared request policy with native sync and async HTTP adapters."""
+
+from __future__ import annotations
+
+import asyncio
+import builtins
+import math
+import os
+import random
+import time
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+from typing import TypeVar
+from urllib.parse import urlsplit
+
+import httpx
+from pydantic import BaseModel, ValidationError
+
+from ._audio import Upload
+from ._version import __version__
+from .errors import (
+    AuthenticationError,
+    ConnectionError,
+    DecisionPendingError,
+    IdempotencyConflictError,
+    InvalidRequestError,
+    NotFoundError,
+    PermissionDeniedError,
+    ProtocolError,
+    RateLimitError,
+    RequestTooLargeError,
+    ServiceError,
+    TazoError,
+    TimeoutError,
+)
+from .types import DecisionResponse
+
+ResponseT = TypeVar("ResponseT", bound=BaseModel)
+DEFAULT_TIMEOUT = httpx.Timeout(connect=5, read=65, write=30, pool=5)
+
+
+def retry_after(value: str | None) -> float | None:
+    if not value:
+        return None
+    try:
+        delay = float(value)
+    except ValueError:
+        try:
+            instant = parsedate_to_datetime(value)
+            if instant.tzinfo is None:
+                instant = instant.replace(tzinfo=UTC)
+            delay = (instant - datetime.now(UTC)).total_seconds()
+        except (TypeError, ValueError, OverflowError):
+            return None
+    return max(0, delay) if math.isfinite(delay) else None
+
+
+def response_error(response: httpx.Response, key: str | None) -> TazoError:
+    code = None
+    message = f"Tazo returned HTTP {response.status_code}."
+    retryable = response.status_code in {408, 429, 500, 502, 503, 504}
+    request_id = response.headers.get("X-Tazo-Request-Id")
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+    if isinstance(body, dict):
+        request_id = request_id or (
+            body.get("request_id") if isinstance(body.get("request_id"), str) else None
+        )
+        error = body.get("error")
+        if isinstance(error, dict):
+            code = error.get("code") if isinstance(error.get("code"), str) else None
+            if isinstance(error.get("message"), str):
+                message = error["message"]
+            if isinstance(error.get("retryable"), bool):
+                retryable = error["retryable"]
+    cls: type[TazoError] = {
+        400: InvalidRequestError,
+        401: AuthenticationError,
+        403: PermissionDeniedError,
+        404: NotFoundError,
+        409: IdempotencyConflictError,
+        413: RequestTooLargeError,
+        422: InvalidRequestError,
+        429: RateLimitError,
+    }.get(response.status_code, ServiceError)
+    # Authentication and invalid input must never cause retry loops, even if a
+    # malformed server response sets retryable=true.
+    if response.status_code in {400, 401, 403, 404, 409, 413, 422}:
+        retryable = False
+    if code == "decision_pending":
+        cls = DecisionPendingError
+    return cls(
+        message,
+        status_code=response.status_code,
+        code=code,
+        request_id=request_id,
+        idempotency_key=key,
+        retryable=retryable,
+        retry_after=retry_after(response.headers.get("Retry-After")),
+    )
+
+
+class HTTPPolicy:
+    def __init__(
+        self,
+        *,
+        api_key: str | None,
+        base_url: str,
+        timeout: float | httpx.Timeout,
+        max_retries: int,
+        operation_timeout: float,
+    ) -> None:
+        parsed = urlsplit(base_url)
+        if (
+            parsed.scheme not in {"http", "https"}
+            or not parsed.netloc
+            or parsed.username
+            or parsed.password
+            or parsed.query
+            or parsed.fragment
+        ):
+            raise ValueError(
+                "base_url must be an HTTP(S) URL without credentials, query, or fragment."
+            )
+        if isinstance(max_retries, bool) or not isinstance(max_retries, int) or max_retries < 0:
+            raise ValueError("max_retries must be a nonnegative integer.")
+        if not math.isfinite(operation_timeout) or operation_timeout <= 0:
+            raise ValueError("operation_timeout must be positive and finite.")
+        self.base_url = parsed.geturl().rstrip("/")
+        self._api_key = api_key if api_key is not None else os.getenv("TAZO_API_KEY")
+        if self._api_key is not None and (
+            not self._api_key.strip()
+            or not self._api_key.isascii()
+            or any(ord(c) < 32 or ord(c) == 127 for c in self._api_key)
+        ):
+            raise ValueError("api_key must contain printable ASCII characters.")
+        self.timeout = timeout if isinstance(timeout, httpx.Timeout) else httpx.Timeout(timeout)
+        self.max_retries = max_retries
+        self.operation_timeout = operation_timeout
+        self.closed = False
+
+    def credential(self) -> str:
+        if not self._api_key:
+            raise AuthenticationError("Set TAZO_API_KEY or pass api_key to the client.")
+        return self._api_key
+
+    def headers(self, *, authenticated: bool, key: str | None) -> dict[str, str]:
+        if self.closed:
+            raise TazoError("This client is closed.")
+        headers = {"User-Agent": f"tazo-python/{__version__}", "Accept": "application/json"}
+        if authenticated:
+            headers["Authorization"] = f"Bearer {self.credential()}"
+        if key is not None:
+            headers["Idempotency-Key"] = key
+        return headers
+
+    def attempt_timeout(self, remaining: float) -> httpx.Timeout:
+        def cap(value: float | None) -> float:
+            return remaining if value is None else min(value, remaining)
+
+        return httpx.Timeout(
+            **{
+                name: cap(getattr(self.timeout, name))
+                for name in ("connect", "read", "write", "pool")
+            }
+        )
+
+    def delay(self, error: TazoError, attempt: int) -> float:
+        if error.retry_after is not None:
+            return error.retry_after
+        return random.uniform(0, min(8, 0.5 * 2 ** min(attempt, 8)))
+
+    @staticmethod
+    def decode(response: httpx.Response, model: type[ResponseT], key: str | None) -> ResponseT:
+        try:
+            result = model.model_validate_json(response.content)
+        except ValidationError:
+            raise ProtocolError(
+                "Tazo returned an invalid response.",
+                status_code=response.status_code,
+                request_id=response.headers.get("X-Tazo-Request-Id"),
+                idempotency_key=key,
+            ) from None
+        if isinstance(result, DecisionResponse):
+            result.request_id = response.headers.get("X-Tazo-Request-Id")
+            result.idempotency_key = key
+        return result
+
+    @staticmethod
+    def deadline_error(key: str | None, last: TazoError | None) -> TazoError:
+        if last is not None:
+            return last
+        return TimeoutError(
+            "The operation deadline was reached; accepted decision work may continue.",
+            idempotency_key=key,
+            retryable=True,
+        )
+
+
+class HTTPClient(HTTPPolicy):
+    def __init__(self, *, http_client: httpx.Client | None = None, **kwargs: object) -> None:
+        # Public constructors provide the typed policy arguments explicitly.
+        super().__init__(**kwargs)  # type: ignore[arg-type]
+        self._client = http_client or httpx.Client()
+        self._owns_client = http_client is None
+
+    def close(self) -> None:
+        if not self.closed and self._owns_client:
+            self._client.close()
+        self.closed = True
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        model: type[ResponseT],
+        *,
+        authenticated: bool = True,
+        key: str | None = None,
+        request_json: str | None = None,
+        upload: Upload | None = None,
+        health: bool = False,
+    ) -> ResponseT:
+        headers = self.headers(authenticated=authenticated, key=key)
+        deadline = time.monotonic() + self.operation_timeout
+        last: TazoError | None = None
+        for attempt in range(self.max_retries + 1):
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise self.deadline_error(key, last)
+            try:
+                response = self._client.request(
+                    method,
+                    f"{self.base_url}{path}",
+                    headers=headers,
+                    timeout=self.attempt_timeout(remaining),
+                    follow_redirects=False,
+                    files=None
+                    if upload is None
+                    else {
+                        "request": (None, request_json or "", "application/json"),
+                        "audio": (upload.filename, upload.data, upload.content_type),
+                    },
+                )
+            except httpx.TimeoutException:
+                last = TimeoutError("Tazo request timed out.", idempotency_key=key, retryable=True)
+            except httpx.TransportError:
+                last = ConnectionError(
+                    "Could not connect to Tazo.", idempotency_key=key, retryable=True
+                )
+            else:
+                if response.status_code == 200 or (health and response.status_code == 503):
+                    return self.decode(response, model, key)
+                last = response_error(response, key)
+            if not last.retryable or attempt == self.max_retries:
+                raise last
+            delay = self.delay(last, attempt)
+            if delay >= deadline - time.monotonic():
+                raise last
+            time.sleep(delay)
+        raise AssertionError("Unreachable retry state")
+
+
+class AsyncHTTPClient(HTTPPolicy):
+    def __init__(self, *, http_client: httpx.AsyncClient | None = None, **kwargs: object) -> None:
+        super().__init__(**kwargs)  # type: ignore[arg-type]
+        self._client = http_client or httpx.AsyncClient()
+        self._owns_client = http_client is None
+
+    async def close(self) -> None:
+        if not self.closed and self._owns_client:
+            await self._client.aclose()
+        self.closed = True
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        model: type[ResponseT],
+        *,
+        authenticated: bool = True,
+        key: str | None = None,
+        request_json: str | None = None,
+        upload: Upload | None = None,
+        health: bool = False,
+    ) -> ResponseT:
+        headers = self.headers(authenticated=authenticated, key=key)
+        deadline = time.monotonic() + self.operation_timeout
+        last: TazoError | None = None
+        for attempt in range(self.max_retries + 1):
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise self.deadline_error(key, last)
+            try:
+                async with asyncio.timeout(remaining):
+                    response = await self._client.request(
+                        method,
+                        f"{self.base_url}{path}",
+                        headers=headers,
+                        timeout=self.attempt_timeout(remaining),
+                        follow_redirects=False,
+                        files=None
+                        if upload is None
+                        else {
+                            "request": (None, request_json or "", "application/json"),
+                            "audio": (upload.filename, upload.data, upload.content_type),
+                        },
+                    )
+            except (httpx.TimeoutException, builtins.TimeoutError):
+                last = TimeoutError("Tazo request timed out.", idempotency_key=key, retryable=True)
+            except httpx.TransportError:
+                last = ConnectionError(
+                    "Could not connect to Tazo.", idempotency_key=key, retryable=True
+                )
+            else:
+                if response.status_code == 200 or (health and response.status_code == 503):
+                    return self.decode(response, model, key)
+                last = response_error(response, key)
+            if not last.retryable or attempt == self.max_retries:
+                raise last
+            delay = self.delay(last, attempt)
+            if delay >= deadline - time.monotonic():
+                raise last
+            await asyncio.sleep(delay)
+        raise AssertionError("Unreachable retry state")

tazo/_version.py

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

tazo/client.py

@@ -0,0 +1,99 @@
+"""Public client configuration and connection ownership."""
+
+from __future__ import annotations
+
+import httpx
+
+from ._http import DEFAULT_TIMEOUT, AsyncHTTPClient, HTTPClient
+from .resources import AsyncDecisions, AsyncHealth, AsyncModels, Decisions, Health, Models
+
+
+class Tazo:
+    """Synchronous client for the four public Tazo operations.
+
+    Args:
+        api_key: Bearer credential, or read TAZO_API_KEY. May be omitted for health.
+        base_url: API origin, optionally with a proxy path prefix; no /v1 suffix.
+        timeout: Per-network-phase timeout in seconds, or an httpx.Timeout.
+        max_retries: Additional HTTP attempts after the first (default two).
+        operation_timeout: HTTP retry budget in seconds (default 180). Each network
+            phase is capped by the remaining budget. A synchronous in-flight request
+            can outlast this budget across multiple network phases/body chunks.
+        http_client: Optional caller-owned HTTPX client; the SDK will not close it.
+
+    Use as a context manager, or call close. Streaming sockets have their own
+    context managers and must be closed before closing this client.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str = "https://api.tazolabs.com",
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = 2,
+        operation_timeout: float = 180,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._http = HTTPClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            operation_timeout=operation_timeout,
+            http_client=http_client,
+        )
+        self.decisions = Decisions(self._http)
+        self.models = Models(self._http)
+        self.health = Health(self._http)
+
+    def close(self) -> None:
+        """Release the SDK-owned HTTP pool. Safe to call more than once."""
+        self._http.close()
+
+    def __enter__(self) -> Tazo:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class AsyncTazo:
+    """Native async client with the same configuration as Tazo.
+
+    Await create, list, and check. Use async with for streaming sessions.
+    operation_timeout also enforces an async deadline during each HTTP attempt.
+    Supplied HTTPX clients remain caller-owned.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str = "https://api.tazolabs.com",
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = 2,
+        operation_timeout: float = 180,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._http = AsyncHTTPClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            operation_timeout=operation_timeout,
+            http_client=http_client,
+        )
+        self.decisions = AsyncDecisions(self._http)
+        self.models = AsyncModels(self._http)
+        self.health = AsyncHealth(self._http)
+
+    async def close(self) -> None:
+        """Release the SDK-owned HTTP pool."""
+        await self._http.close()
+
+    async def __aenter__(self) -> AsyncTazo:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

tazo/errors.py

@@ -0,0 +1,84 @@
+"""Exceptions shared by the sync and async clients."""
+
+from __future__ import annotations
+
+
+class TazoError(Exception):
+    """Base SDK error with recovery metadata and no stored credentials or audio."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        code: str | None = None,
+        request_id: str | None = None,
+        idempotency_key: str | None = None,
+        retryable: bool = False,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.request_id = request_id
+        self.idempotency_key = idempotency_key
+        self.retryable = retryable
+        self.retry_after = retry_after
+
+
+class AuthenticationError(TazoError):
+    """Missing or rejected bearer credential."""
+
+
+class PermissionDeniedError(TazoError):
+    """The authenticated caller lacks access."""
+
+
+class InvalidRequestError(TazoError):
+    """Invalid local input or an HTTP 400/422 rejection."""
+
+
+class NotFoundError(TazoError):
+    """The requested model was not found."""
+
+
+class RequestTooLargeError(InvalidRequestError):
+    """Audio or request exceeds the service's size limit."""
+
+
+class RateLimitError(TazoError):
+    """Account admission limit reached; inspect retry_after."""
+
+
+class IdempotencyConflictError(TazoError):
+    """An operation key was reused with different input."""
+
+
+class DecisionPendingError(TazoError):
+    """Accepted work continues. Retain the key and retry the same input later."""
+
+
+class ConnectionError(TazoError):
+    """Transport connection failed; acceptance may be uncertain for writes."""
+
+
+class TimeoutError(TazoError):
+    """A network timeout or the overall operation deadline was reached."""
+
+
+class ProtocolError(TazoError):
+    """The server response doesn't match the public contract."""
+
+
+class ServiceError(TazoError):
+    """The service returned an unsuccessful response."""
+
+
+class StreamingError(TazoError):
+    """A fatal streaming failure or unexpected disconnect; audio is never replayed."""
+
+    def __init__(
+        self, message: str, *, code: str | None = None, close_code: int | None = None
+    ) -> None:
+        super().__init__(message, code=code)
+        self.close_code = close_code