interhumanai 0.4.1__py3-none-any.whl

interhumanai/__init__.py

@@ -0,0 +1,181 @@
+"""First-party Python SDK for the Interhuman API.
+
+Quickstart::
+
+    import asyncio
+    from interhumanai import InterhumanClient
+
+    async def main() -> None:
+        client = InterhumanClient(key_id="...", key_secret="...")
+        result = await client.upload.analyze("meeting.mp4")
+        for signal in result.signals:
+            print(signal.type.value, signal.start, signal.end)
+
+    asyncio.run(main())
+"""
+
+from ._session_socket import CloseInfo, SessionSocketClient, UnknownEvent
+from ._version import __version__
+from .auth import (
+    DEFAULT_REFRESH_SKEW_SECONDS,
+    DEFAULT_SCOPES,
+    AuthClient,
+    ClientTokenResponse,
+    StaticTokenProvider,
+    TokenManager,
+    TokenProvider,
+    TokenResponse,
+)
+from .client import InterhumanClient
+from .config import HTTP_BASE_URLS, Environment, http_to_ws_base_url, resolve_http_base_url
+from .errors import InterhumanAPIError, InterhumanConfigError, InterhumanError
+from .realtime import (
+    NO_GUIDANCE,
+    RealtimeClient,
+    RealtimeEvent,
+    RealtimeSessionConfigOptions,
+    RealtimeSessionReadyData,
+    RealtimeSessionReadyEvent,
+    RealtimeSessionUpdatedData,
+    RealtimeSessionUpdatedEvent,
+    SynthesisGeneratedData,
+    SynthesisGeneratedEvent,
+    TranscriptGeneratedEvent,
+    TranscriptSegment,
+    parse_realtime_event,
+)
+from .stream import (
+    ConversationQualityUpdatedData,
+    ConversationQualityUpdatedEvent,
+    CoverageDroppedData,
+    CoverageDroppedEvent,
+    CoverageRange,
+    EngagementUpdatedData,
+    EngagementUpdatedEvent,
+    ErrorData,
+    ErrorEvent,
+    FeedbackGeneratedData,
+    FeedbackGeneratedEvent,
+    SessionClosingData,
+    SessionClosingEvent,
+    SessionConfigOptions,
+    SessionEndedData,
+    SessionEndedEvent,
+    SessionReadyData,
+    SessionReadyEvent,
+    SessionUpdatedData,
+    SessionUpdatedEvent,
+    SignalDetectedData,
+    SignalDetectedEvent,
+    SignalEndedData,
+    SignalEndedEvent,
+    SignalUpdatedData,
+    SignalUpdatedEvent,
+    StreamClient,
+    StreamEvent,
+    parse_stream_event,
+)
+from .types import (
+    AnalysisGroup,
+    AnalysisResult,
+    ConversationQuality,
+    ConversationQualityTimelineEntry,
+    ConversationQualityValues,
+    EngagementLevel,
+    EngagementStateEntry,
+    Feedback,
+    GoalDimension,
+    IncludeFlag,
+    InteractionFeedback,
+    NoFeedback,
+    Probability,
+    Scope,
+    Signal,
+    SignalType,
+    SynthesisFrequency,
+)
+from .upload import UploadClient, VideoInput
+
+__all__ = [
+    "DEFAULT_REFRESH_SKEW_SECONDS",
+    "DEFAULT_SCOPES",
+    "HTTP_BASE_URLS",
+    "NO_GUIDANCE",
+    "AnalysisGroup",
+    "AnalysisResult",
+    "AuthClient",
+    "ClientTokenResponse",
+    "CloseInfo",
+    "ConversationQuality",
+    "ConversationQualityTimelineEntry",
+    "ConversationQualityUpdatedData",
+    "ConversationQualityUpdatedEvent",
+    "ConversationQualityValues",
+    "CoverageDroppedData",
+    "CoverageDroppedEvent",
+    "CoverageRange",
+    "EngagementLevel",
+    "EngagementStateEntry",
+    "EngagementUpdatedData",
+    "EngagementUpdatedEvent",
+    "Environment",
+    "ErrorData",
+    "ErrorEvent",
+    "Feedback",
+    "FeedbackGeneratedData",
+    "FeedbackGeneratedEvent",
+    "GoalDimension",
+    "IncludeFlag",
+    "InteractionFeedback",
+    "InterhumanAPIError",
+    "InterhumanClient",
+    "InterhumanConfigError",
+    "InterhumanError",
+    "NoFeedback",
+    "Probability",
+    "RealtimeClient",
+    "RealtimeEvent",
+    "RealtimeSessionConfigOptions",
+    "RealtimeSessionReadyData",
+    "RealtimeSessionReadyEvent",
+    "RealtimeSessionUpdatedData",
+    "RealtimeSessionUpdatedEvent",
+    "Scope",
+    "SessionClosingData",
+    "SessionClosingEvent",
+    "SessionConfigOptions",
+    "SessionEndedData",
+    "SessionEndedEvent",
+    "SessionReadyData",
+    "SessionReadyEvent",
+    "SessionSocketClient",
+    "SessionUpdatedData",
+    "SessionUpdatedEvent",
+    "Signal",
+    "SignalDetectedData",
+    "SignalDetectedEvent",
+    "SignalEndedData",
+    "SignalEndedEvent",
+    "SignalType",
+    "SignalUpdatedData",
+    "SignalUpdatedEvent",
+    "StaticTokenProvider",
+    "StreamClient",
+    "StreamEvent",
+    "SynthesisFrequency",
+    "SynthesisGeneratedData",
+    "SynthesisGeneratedEvent",
+    "TokenManager",
+    "TokenProvider",
+    "TokenResponse",
+    "TranscriptGeneratedEvent",
+    "TranscriptSegment",
+    "UnknownEvent",
+    "UploadClient",
+    "VideoInput",
+    "__version__",
+    "http_to_ws_base_url",
+    "parse_realtime_event",
+    "parse_stream_event",
+    "resolve_http_base_url",
+]

interhumanai/_http.py

@@ -0,0 +1,73 @@
+"""Internal HTTP helpers shared by the SDK's HTTP clients."""
+
+from typing import Any
+
+import httpx
+
+from .errors import InterhumanAPIError
+
+
+def _error_from_response(response: httpx.Response) -> InterhumanAPIError:
+    """Build an :class:`InterhumanAPIError` from a non-2xx HTTP response."""
+    body: dict[str, Any] | None = None
+    try:
+        parsed = response.json()
+    except ValueError:
+        parsed = None
+    if isinstance(parsed, dict) and isinstance(parsed.get("error_id"), str):
+        body = parsed
+    detail = None
+    if body is not None and isinstance(body.get("message"), str):
+        detail = body["message"]
+    error_id = body.get("error_id") if body else None
+    message = f"Interhuman API error ({error_id}): " if error_id else "Interhuman API error: "
+    message += detail or f"HTTP {response.status_code}"
+    return InterhumanAPIError(
+        message,
+        status=response.status_code,
+        error_id=error_id,
+        correlation_id=body.get("correlation_id") if body else None,
+        link=body.get("link") if body else None,
+        body=body,
+    )
+
+
+async def request_json(
+    client: httpx.AsyncClient,
+    method: str,
+    url: str,
+    *,
+    json: Any | None = None,
+    files: Any | None = None,
+    data: Any | None = None,
+    headers: dict[str, str] | None = None,
+) -> Any:
+    """Send a request and return the parsed JSON body.
+
+    Raises:
+        InterhumanAPIError: For non-2xx responses (with the API's canonical
+            error fields when present) and for transport failures (``status=0``).
+
+    Returns:
+        The parsed JSON response body, or ``None`` for empty bodies (e.g. 204).
+    """
+    try:
+        response = await client.request(
+            method, url, json=json, files=files, data=data, headers=headers
+        )
+    except httpx.HTTPError as exc:
+        raise InterhumanAPIError(
+            f"Interhuman API request failed before a response was received: {exc}",
+            status=0,
+        ) from exc
+    if response.status_code < 200 or response.status_code >= 300:
+        raise _error_from_response(response)
+    if not response.content:
+        return None
+    try:
+        return response.json()
+    except ValueError as exc:
+        raise InterhumanAPIError(
+            "Interhuman API returned a malformed JSON response.",
+            status=response.status_code,
+        ) from exc

interhumanai/_session_socket.py

@@ -0,0 +1,314 @@
+"""Shared asyncio WebSocket engine for the stream and real-time clients."""
+
+import asyncio
+import json
+from typing import Any, ClassVar, Generic, TypeVar
+
+from pydantic import BaseModel, ValidationError
+from websockets.asyncio.client import connect as ws_connect
+from websockets.exceptions import ConnectionClosed, InvalidHandshake
+
+from .auth import TokenProvider
+from .config import Environment, http_to_ws_base_url, resolve_http_base_url
+from .errors import InterhumanConfigError, InterhumanError
+
+
+class CloseInfo(BaseModel):
+    """Close code and reason of a finished WebSocket session."""
+
+    code: int
+    reason: str
+
+
+class UnknownEvent(BaseModel):
+    """A server envelope whose ``type`` this SDK version does not know.
+
+    Newer API versions may add event types; they are surfaced as-is instead of
+    failing the session.
+
+    Attributes:
+        type: The envelope's ``type`` discriminator.
+        raw: The full envelope payload as received.
+    """
+
+    type: str
+    raw: dict[str, Any]
+
+
+EventT = TypeVar("EventT")
+
+_QUEUE_END = object()
+
+
+class SessionSocketClient(Generic[EventT]):
+    """One live analysis session over a WebSocket.
+
+    Connect with :meth:`connect` (or ``async with``), send binary video chunks
+    with :meth:`send_video`, and consume typed server events by iterating the
+    client with ``async for``. Iteration ends when the connection closes;
+    :attr:`close_info` then holds the close code and reason.
+
+    Args:
+        token_provider: Source of bearer tokens for authentication.
+        environment: Named environment to connect to. Defaults to
+            ``production``.
+        base_url: Explicit HTTP base URL override; converted to ``ws(s)://``.
+    """
+
+    _endpoint_path: ClassVar[str]
+    _display_name: ClassVar[str]
+    _scope_hint: ClassVar[str]
+
+    def __init__(
+        self,
+        *,
+        token_provider: TokenProvider,
+        environment: Environment | None = None,
+        base_url: str | None = None,
+    ) -> None:
+        """Initialize the client (see class docstring for arguments)."""
+        self._token_provider = token_provider
+        self._ws_base_url = http_to_ws_base_url(
+            resolve_http_base_url(base_url=base_url, environment=environment)
+        )
+        self._ws: Any = None
+        self._open = False
+        self._close_info: CloseInfo | None = None
+        self._events: asyncio.Queue[Any] = asyncio.Queue()
+        self._session_ready: asyncio.Future[EventT] | None = None
+        self._receiver: asyncio.Task[None] | None = None
+
+    def _parse_event(self, payload: dict[str, Any]) -> EventT:
+        """Parse one server envelope into a typed event (subclass hook)."""
+        raise NotImplementedError
+
+    @property
+    def url(self) -> str:
+        """The WebSocket URL this client connects to."""
+        return self._ws_base_url + self._endpoint_path
+
+    @property
+    def is_open(self) -> bool:
+        """Whether the connection is currently open."""
+        return self._open
+
+    @property
+    def close_info(self) -> CloseInfo | None:
+        """Close code and reason once the connection has ended, else ``None``."""
+        return self._close_info
+
+    async def connect(self) -> "SessionSocketClient[EventT]":
+        """Open the WebSocket connection and start receiving events.
+
+        Returns:
+            This client, for chaining.
+
+        Raises:
+            InterhumanConfigError: If the client was already connected.
+            InterhumanError: If the handshake fails (bad credentials or scope,
+                unreachable host).
+        """
+        if self._ws is not None:
+            raise InterhumanConfigError(
+                f"{self._display_name} client is already connected; "
+                "create a new client for a new session."
+            )
+        token = await self._token_provider.get_token()
+        try:
+            self._ws = await ws_connect(
+                self.url,
+                additional_headers={"Authorization": f"Bearer {token}"},
+            )
+        except InvalidHandshake as exc:
+            raise InterhumanError(
+                f"{self._display_name} WebSocket handshake failed: {exc}. {self._scope_hint}"
+            ) from exc
+        except OSError as exc:
+            raise InterhumanError(
+                f"{self._display_name} WebSocket connection failed: {exc}"
+            ) from exc
+        self._open = True
+        self._session_ready = asyncio.get_running_loop().create_future()
+        self._receiver = asyncio.create_task(self._receive_loop())
+        return self
+
+    async def __aenter__(self) -> "SessionSocketClient[EventT]":
+        """Connect on entering an ``async with`` block."""
+        return await self.connect()
+
+    async def __aexit__(self, exc_type: object, exc: object, tb: object) -> None:
+        """Close the connection on leaving an ``async with`` block."""
+        await self.close()
+
+    def __aiter__(self) -> "SessionSocketClient[EventT]":
+        """Iterate over typed server events until the connection closes."""
+        return self
+
+    async def __anext__(self) -> EventT:
+        """Return the next server event.
+
+        Raises:
+            StopAsyncIteration: When the connection has closed and every
+                buffered event has been consumed.
+            InterhumanError: When the server sent a frame that is not a valid
+                JSON envelope. The connection stays open and later events are
+                preserved, but the raise exits an ``async for`` loop - start a
+                new ``async for`` (or call ``__anext__``) to keep consuming.
+        """
+        item = await self._events.get()
+        if item is _QUEUE_END:
+            self._events.put_nowait(_QUEUE_END)
+            raise StopAsyncIteration
+        if isinstance(item, InterhumanError):
+            raise item
+        return item
+
+    async def wait_for_session_ready(self) -> EventT:
+        """Wait for the server's ``session.ready`` event.
+
+        The event is also delivered through iteration; this helper simply
+        awaits it (or returns it if it already arrived).
+
+        Returns:
+            The ``session.ready`` event.
+
+        Raises:
+            InterhumanError: If the connection closes before the session
+                becomes ready (typically an auth or scope failure).
+        """
+        if self._session_ready is None:
+            raise InterhumanConfigError(
+                f"{self._display_name} client is not connected; call connect() first."
+            )
+        return await asyncio.shield(self._session_ready)
+
+    async def send_video(self, chunk: bytes | bytearray | memoryview) -> None:
+        """Send one binary video chunk.
+
+        The first chunk must carry the container's init header; later chunks
+        are continuation fragments of the same WebM or fragmented-MP4 stream.
+        The SDK does not enforce a chunk size; the server rejects chunks above
+        its limit (32 MB by default, reported in ``session.ready`` as
+        ``max_segment_size_bytes``) with an ``ih6002`` error.
+
+        Args:
+            chunk: The raw video bytes to send.
+        """
+        await self._send(bytes(chunk))
+
+    async def request_close(self) -> None:
+        """Ask the server to drain in-flight analysis and end the session.
+
+        The server acknowledges with ``session.closing``, emits any final
+        events, sends ``session.ended``, and closes the socket normally. Keep
+        iterating to observe the drain; for an immediate teardown use
+        :meth:`close` instead.
+        """
+        await self._send_json({"type": "session.close"})
+
+    async def close(self, code: int = 1000, reason: str = "") -> None:
+        """Close the WebSocket immediately, discarding in-flight analysis.
+
+        Args:
+            code: WebSocket close code to send.
+            reason: Optional close reason.
+        """
+        if self._ws is None:
+            return
+        await self._ws.close(code, reason)
+        if self._receiver is not None:
+            await self._receiver
+
+    async def wait_closed(self) -> CloseInfo:
+        """Wait until the connection has fully closed.
+
+        Returns:
+            The session's close code and reason.
+        """
+        if self._ws is None:
+            raise InterhumanConfigError(f"{self._display_name} client was never connected.")
+        if self._receiver is not None:
+            await asyncio.shield(self._receiver)
+        assert self._close_info is not None
+        return self._close_info
+
+    async def _send(self, message: bytes | str) -> None:
+        """Send a raw frame, translating closed-connection errors."""
+        if self._ws is None:
+            raise InterhumanConfigError(
+                f"{self._display_name} client is not connected; call connect() first."
+            )
+        if not self._open:
+            raise InterhumanConfigError(
+                f"{self._display_name} connection is closed; nothing can be sent."
+            )
+        try:
+            await self._ws.send(message)
+        except ConnectionClosed as exc:
+            raise InterhumanError(f"{self._display_name} connection closed while sending.") from exc
+
+    async def _send_json(self, payload: dict[str, Any]) -> None:
+        """Serialize ``payload`` and send it as a text frame."""
+        await self._send(json.dumps(payload))
+
+    def _dispatch(self, raw: str | bytes) -> None:
+        """Parse one inbound frame and enqueue the resulting event or error."""
+        if isinstance(raw, bytes):
+            self._events.put_nowait(
+                InterhumanError(f"{self._display_name} server sent an unexpected binary frame.")
+            )
+            return
+        try:
+            payload = json.loads(raw)
+        except ValueError:
+            self._events.put_nowait(
+                InterhumanError(f"{self._display_name} server sent a malformed JSON frame.")
+            )
+            return
+        if not isinstance(payload, dict) or not isinstance(payload.get("type"), str):
+            self._events.put_nowait(
+                InterhumanError(
+                    f"{self._display_name} server sent an envelope without a string 'type'."
+                )
+            )
+            return
+        try:
+            event = self._parse_event(payload)
+        except ValidationError as exc:
+            self._events.put_nowait(
+                InterhumanError(
+                    f"{self._display_name} server sent an invalid '{payload['type']}' "
+                    f"envelope: {exc}"
+                )
+            )
+            return
+        ready = self._session_ready
+        if payload["type"] == "session.ready" and ready is not None and not ready.done():
+            ready.set_result(event)
+        self._events.put_nowait(event)
+
+    async def _receive_loop(self) -> None:
+        """Receive frames until the connection closes, then finalize state."""
+        assert self._ws is not None
+        try:
+            async for raw in self._ws:
+                self._dispatch(raw)
+        except ConnectionClosed:
+            pass
+        finally:
+            self._open = False
+            code = self._ws.close_code if self._ws.close_code is not None else 1006
+            reason = self._ws.close_reason or ""
+            self._close_info = CloseInfo(code=code, reason=reason)
+            ready = self._session_ready
+            if ready is not None and not ready.done():
+                ready.set_exception(
+                    InterhumanError(
+                        f"{self._display_name} connection closed before the session became "
+                        f"ready (code {code}, reason {reason!r}). {self._scope_hint}"
+                    )
+                )
+                # Mark the exception as observed so sessions that never await
+                # readiness do not log "Future exception was never retrieved".
+                ready.exception()
+            self._events.put_nowait(_QUEUE_END)

interhumanai/_version.py

@@ -0,0 +1,3 @@
+"""Package version (single source of truth, read by hatchling at build time)."""
+
+__version__ = "0.4.1"