spatialreal 0.1.0__tar.gz → 0.2.0__tar.gz

{spatialreal-0.1.0 → spatialreal-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: spatialreal
-Version: 0.1.0
+Version: 0.2.0
 Summary: SpatialReal Python SDK — realtime avatar sessions (audio in, animation/egress out)
 Project-URL: Documentation, https://docs.spatialreal.com
 Project-URL: Website, https://www.spatialreal.ai/
@@ -45,8 +45,6 @@ session = new_avatar_session(
     api_key="...",
     app_id="...",
     avatar_id="...",
-    console_endpoint_url="https://api.spatialreal.cloud",  # OpenAPI root: session tokens
-    ingress_endpoint_url="wss://driven.us-west.spatialreal.cloud/v2/driveningress",
     expire_at=datetime.now(timezone.utc) + timedelta(hours=1),
     sample_rate=16000,
     livekit_egress=LiveKitEgressConfig(url=..., api_token=..., room_name=..., publisher_id=...),
@@ -82,6 +80,19 @@ as `pause_timeout`). Older servers never send it and ignore pause/resume.
 
 Session objects are single-use: on a dropped connection, create a fresh one
 (request state is deliberately not reusable across connections).
+## Endpoints
+
+Endpoints come from the environment you name, so callers write no URLs:
+
+```python
+session = new_avatar_session(..., environment="us-west")  # the default
+```
+
+They are resolved from SpatialReal's config service (built-in presets cover it being
+unreachable), which is what lets a deployment move, or a region be added, without an
+SDK release. Pass `console_endpoint_url` / `ingress_endpoint_url` to override either one
+— useful against a local or private deployment.
+
 `AvatarSDKError.retryable` tells you whether reconnecting can succeed — it
 implements the server's WebSocket close-code contract (40xx: don't retry,
 45xx: retry with backoff).
@@ -91,6 +102,8 @@ implements the server's WebSocket close-code contract (40xx: don't retry,
 - `on_playback(PlaybackSignal)` — structured playback lifecycle; no protobuf
   parsing in caller code (`transport_frames(raw, is_last)` still exists).
 - `CloseCode` + `AvatarSDKError.retryable` — the reconnect contract as API.
+- `environment="us-west"` — endpoints resolved from the config service instead of
+  hard-coded URLs; new regions need no SDK release.
 - `session.capabilities` — server-declared capabilities from the handshake
   (feature-detect, don't version-detect).
 - `pause()` / `resume()` + `on_playback_state(PlaybackStateEvent)` — egress-mode

{spatialreal-0.1.0 → spatialreal-0.2.0}/README.md

@@ -15,8 +15,6 @@ session = new_avatar_session(
     api_key="...",
     app_id="...",
     avatar_id="...",
-    console_endpoint_url="https://api.spatialreal.cloud",  # OpenAPI root: session tokens
-    ingress_endpoint_url="wss://driven.us-west.spatialreal.cloud/v2/driveningress",
     expire_at=datetime.now(timezone.utc) + timedelta(hours=1),
     sample_rate=16000,
     livekit_egress=LiveKitEgressConfig(url=..., api_token=..., room_name=..., publisher_id=...),
@@ -52,6 +50,19 @@ as `pause_timeout`). Older servers never send it and ignore pause/resume.
 
 Session objects are single-use: on a dropped connection, create a fresh one
 (request state is deliberately not reusable across connections).
+## Endpoints
+
+Endpoints come from the environment you name, so callers write no URLs:
+
+```python
+session = new_avatar_session(..., environment="us-west")  # the default
+```
+
+They are resolved from SpatialReal's config service (built-in presets cover it being
+unreachable), which is what lets a deployment move, or a region be added, without an
+SDK release. Pass `console_endpoint_url` / `ingress_endpoint_url` to override either one
+— useful against a local or private deployment.
+
 `AvatarSDKError.retryable` tells you whether reconnecting can succeed — it
 implements the server's WebSocket close-code contract (40xx: don't retry,
 45xx: retry with backoff).
@@ -61,6 +72,8 @@ implements the server's WebSocket close-code contract (40xx: don't retry,
 - `on_playback(PlaybackSignal)` — structured playback lifecycle; no protobuf
   parsing in caller code (`transport_frames(raw, is_last)` still exists).
 - `CloseCode` + `AvatarSDKError.retryable` — the reconnect contract as API.
+- `environment="us-west"` — endpoints resolved from the config service instead of
+  hard-coded URLs; new regions need no SDK release.
 - `session.capabilities` — server-declared capabilities from the handshake
   (feature-detect, don't version-detect).
 - `pause()` / `resume()` + `on_playback_state(PlaybackStateEvent)` — egress-mode

spatialreal-0.2.0/proto/SHARED_PROTO_COMMIT

@@ -0,0 +1 @@
+845c7f2b2b5c39994bffea3e589bbde51d80f379

{spatialreal-0.1.0 → spatialreal-0.2.0}/spatialreal/config.py

@@ -7,6 +7,7 @@ from dataclasses import dataclass, field
 from datetime import datetime
 from enum import Enum
 
+from .environments import DEFAULT_ENVIRONMENT
 from .events import PlaybackSignal, PlaybackStateEvent
 
 
@@ -83,6 +84,10 @@ class SessionConfig:
     sample_rate: int = 16000
     bitrate: int = 0
     audio_format: AudioFormat = AudioFormat.PCM_S16LE
+    # Which deployment to talk to. Endpoints are resolved from it (config service,
+    # then built-in presets), so callers normally set neither URL below.
+    environment: str = DEFAULT_ENVIRONMENT
+    # Explicit overrides; each one given wins over the environment's.
     console_endpoint_url: str = ""
     ingress_endpoint_url: str = ""
     livekit_egress: LiveKitEgressConfig | None = None

spatialreal-0.2.0/spatialreal/environments.py

@@ -0,0 +1,95 @@
+"""Where a deployment lives, and how the SDK finds it.
+
+Callers name an environment (``us-west``) instead of writing URLs, so adding a
+region or moving a deployment is a config-service change rather than an SDK
+release. The built-in presets below are only a fallback for when that service
+cannot be reached — they are a copy, not the source of truth.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass
+
+import aiohttp
+
+CONFIG_SERVICE_URL = "https://config.spatialreal.cloud/sdk"
+# The session must not hang on a config lookup; the presets cover the timeout.
+CONFIG_SERVICE_TIMEOUT = 3.0
+DEFAULT_ENVIRONMENT = "us-west"
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class EnvironmentEndpoints:
+    """Origins for one environment; the SDK appends the routes itself."""
+
+    # OpenAPI root — where session tokens come from.
+    api: str
+    # driven-ingress origin, without the /v2/driveningress path.
+    driveningress: str
+
+
+# Public deployments only. Internal ones are reached by passing console_endpoint_url /
+# ingress_endpoint_url explicitly, so naming them here cannot expose them to callers.
+BUILTIN_ENVIRONMENTS: dict[str, EnvironmentEndpoints] = {
+    "us-west": EnvironmentEndpoints(
+        api="https://api.spatialreal.cloud",
+        driveningress="https://driven.us-west.spatialreal.cloud",
+    ),
+}
+
+# Fetched once per process: every session in it resolves against the same answer.
+_cache: dict[str, dict[str, str]] | None = None
+_lock = asyncio.Lock()
+
+
+def reset_cache() -> None:
+    """Forget the fetched config (tests, or a long-lived process that must re-read)."""
+    global _cache
+    _cache = None
+
+
+async def _fetch() -> dict[str, dict[str, str]]:
+    """The config service's environments, or {} if it cannot be read."""
+    timeout = aiohttp.ClientTimeout(total=CONFIG_SERVICE_TIMEOUT)
+    async with aiohttp.ClientSession(timeout=timeout) as session:
+        async with session.get(CONFIG_SERVICE_URL) as response:
+            if response.status != 200:
+                raise RuntimeError(f"config service returned {response.status}")
+            body = await response.json(content_type=None)
+    environments = body.get("environments") if isinstance(body, dict) else None
+    return environments if isinstance(environments, dict) else {}
+
+
+async def resolve(environment: str) -> EnvironmentEndpoints:
+    """Endpoints for ``environment``: the config service's, else the built-in preset.
+
+    Raises ValueError when neither knows the name, since a wrong environment is a
+    caller mistake worth surfacing rather than silently defaulting elsewhere.
+    """
+    global _cache
+
+    if _cache is None:
+        async with _lock:
+            if _cache is None:
+                try:
+                    _cache = await _fetch()
+                except Exception as e:
+                    # Not fatal: the presets are exactly what this service would serve
+                    # today; a session should not fail because config lookup did.
+                    logger.debug("SpatialReal config service unavailable (%s); using presets", e)
+                    _cache = {}
+
+    preset = BUILTIN_ENVIRONMENTS.get(environment)
+    remote = _cache.get(environment) or {}
+    if not preset and not remote:
+        known = sorted(set(BUILTIN_ENVIRONMENTS) | set(_cache))
+        raise ValueError(f"Unknown environment {environment!r}; known environments: {known}")
+
+    return EnvironmentEndpoints(
+        api=remote.get("api") or (preset.api if preset else ""),
+        driveningress=remote.get("driveningress") or (preset.driveningress if preset else ""),
+    )

{spatialreal-0.1.0 → spatialreal-0.2.0}/spatialreal/session.py

@@ -21,6 +21,7 @@ from urllib.parse import parse_qs, urlencode, urlparse, urlunparse
 import aiohttp
 import websockets
 
+from . import environments
 from .config import AudioFormat, SessionConfig
 from .errors import (
     AvatarSDKError,
@@ -37,6 +38,7 @@ from .proto.generated import message_pb2
 SESSION_TOKEN_PATH = "/v1/auth/session-token"
 # Accepted for back-compat: callers used to pass the cp root with this suffix already on it.
 LEGACY_CONSOLE_SUFFIX = "/v1/console"
+DRIVENINGRESS_PATH = "/v2/driveningress"
 INGRESS_WEBSOCKET_PATH = "/websocket"
 
 logger = logging.getLogger(__name__)
@@ -62,6 +64,7 @@ class AvatarSession:
         self._last_req_id: str | None = None
         self._read_task: asyncio.Task | None = None
         self._close_notified = False
+        self._resolved_endpoints: environments.EnvironmentEndpoints | None = None
 
     # ------------------------------------------------------------------ props
 
@@ -83,18 +86,36 @@ class AvatarSession:
         """
         return self._capabilities
 
+    # ------------------------------------------------------------- endpoints
+
+    async def _endpoints(self) -> environments.EnvironmentEndpoints:
+        if self._resolved_endpoints is None:
+            self._resolved_endpoints = await environments.resolve(self._config.environment)
+        return self._resolved_endpoints
+
+    async def _console_endpoint(self) -> str:
+        """The OpenAPI root: the caller's if given, else the environment's."""
+        if self._config.console_endpoint_url:
+            return self._config.console_endpoint_url
+        return (await self._endpoints()).api
+
+    async def _ingress_endpoint(self) -> str:
+        """The driven-ingress WebSocket URL, built from the environment's origin."""
+        if self._config.ingress_endpoint_url:
+            return self._config.ingress_endpoint_url
+        origin = (await self._endpoints()).driveningress.rstrip("/")
+        return origin + DRIVENINGRESS_PATH
+
     # ------------------------------------------------------------------ init
 
     async def init(self) -> None:
         """Exchange the API key for a session token via the console API."""
         if not self._config.api_key:
             raise ValueError("Missing API key")
-        if not self._config.console_endpoint_url:
-            raise ValueError("Missing console endpoint URL")
         if not self._config.expire_at:
             raise ValueError("Missing expire_at")
 
-        endpoint = _session_token_endpoint(self._config.console_endpoint_url)
+        endpoint = _session_token_endpoint(await self._console_endpoint())
         payload = {"expireAt": int(self._config.expire_at.timestamp())}
         headers = {"X-Api-Key": self._config.api_key, "Content-Type": "application/json"}
         timeout = aiohttp.ClientTimeout(total=self._config.token_request_timeout)
@@ -132,8 +153,6 @@ class AvatarSession:
             raise ValueError("Session already started")
         if not self._session_token:
             raise ValueError("Session not initialized (call init() first)")
-        if not self._config.ingress_endpoint_url:
-            raise ValueError("Missing ingress endpoint URL")
         if not self._config.avatar_id:
             raise ValueError("Missing avatar ID")
         if not self._config.app_id:
@@ -141,7 +160,7 @@ class AvatarSession:
         if self._config.livekit_egress is not None and self._config.agora_egress is not None:
             raise ValueError("Cannot configure both livekit_egress and agora_egress")
 
-        ws_url, headers = self._build_ws_target()
+        ws_url, headers = self._build_ws_target(await self._ingress_endpoint())
 
         try:
             self._connection = await _ws_connect(ws_url, headers)
@@ -163,8 +182,8 @@ class AvatarSession:
         self._read_task = asyncio.create_task(self._read_loop())
         return self._connection_id
 
-    def _build_ws_target(self) -> tuple[str, dict[str, str]]:
-        endpoint = self._config.ingress_endpoint_url.rstrip("/") + INGRESS_WEBSOCKET_PATH
+    def _build_ws_target(self, ingress_endpoint_url: str) -> tuple[str, dict[str, str]]:
+        endpoint = ingress_endpoint_url.rstrip("/") + INGRESS_WEBSOCKET_PATH
         parsed = urlparse(endpoint)
         scheme = parsed.scheme.lower()
         ws_scheme = {"http": "ws", "https": "wss", "ws": "ws", "wss": "wss"}.get(scheme)

spatialreal-0.2.0/spatialreal/version.py

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

spatialreal-0.1.0/proto/SHARED_PROTO_COMMIT

@@ -1 +0,0 @@
-40f98c99c79c6a52fda9cac4b578a5bccc3f8542

spatialreal-0.1.0/spatialreal/version.py

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