livekit-api 1.2.1__tar.gz → 1.2.2__tar.gz

{livekit_api-1.2.1 → livekit_api-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: livekit-api
-Version: 1.2.1
+Version: 1.2.2
 Summary: Python Server API for LiveKit
 Project-URL: Documentation, https://docs.livekit.io
 Project-URL: Website, https://livekit.io/
@@ -21,10 +21,13 @@ Classifier: Topic :: Multimedia :: Sound/Audio
 Classifier: Topic :: Multimedia :: Video
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.9.0
-Requires-Dist: aiohttp>=3.9.0
-Requires-Dist: livekit-protocol<2.0.0,>=1.1.25
+Requires-Dist: aiohttp>=3.13.5; python_version < '3.10'
+Requires-Dist: aiohttp>=3.14.4; python_version >= '3.10'
+Requires-Dist: idna>=3.15
+Requires-Dist: livekit-protocol<2.0.0,>=1.1.27
+Requires-Dist: multidict>=6.9.1; python_version >= '3.10'
 Requires-Dist: protobuf>=4
-Requires-Dist: pyjwt>=2.0.0
+Requires-Dist: pyjwt>=2.15.1
 Requires-Dist: types-protobuf>=4
 Description-Content-Type: text/markdown
 

{livekit_api-1.2.1 → livekit_api-1.2.2}/livekit/api/__init__.py

@@ -47,6 +47,9 @@ from .livekit_api import LiveKitAPI
 from .access_token import (
     InferenceGrants,
     ObservabilityGrants,
+    AgentGrants,
+    AgentEndpointGrants,
+    AgentThreadGrants,
     VideoGrants,
     SIPGrants,
     AccessToken,
@@ -65,6 +68,9 @@ __all__ = [
     "connector_service",
     "InferenceGrants",
     "ObservabilityGrants",
+    "AgentGrants",
+    "AgentEndpointGrants",
+    "AgentThreadGrants",
     "VideoGrants",
     "SIPGrants",
     "AccessToken",

{livekit_api-1.2.1 → livekit_api-1.2.2}/livekit/api/_failover.py

@@ -44,11 +44,11 @@ def failover_attempts(
     timeout: Optional[float] = None,
 ) -> int:
     """Total request attempts for a host; 1 means no failover. Failover only
-    engages when enabled, the host is a LiveKit Cloud domain, and the request
-    timeout is long enough to retry. ``force`` bypasses the cloud-host check and
-    is for internal testing only.
+    engages when enabled, the host is a LiveKit Cloud project or Cloud API
+    domain, and the request timeout is long enough to retry. ``force`` bypasses
+    the cloud-host check and is for internal testing only.
     """
-    if not (enabled and (force or (host is not None and is_cloud(host)))):
+    if not (enabled and (force or (host is not None and (is_cloud(host) or is_cloud_api(host))))):
         return 1
     if timeout is not None and 0 < timeout < MIN_FAILOVER_TIMEOUT:
         return 1
@@ -60,6 +60,12 @@ def is_cloud(host: str) -> bool:
     return host.endswith(".livekit.cloud")
 
 
+def is_cloud_api(host: str) -> bool:
+    # cloud-api.livekit.io or a cloud-api.<env>.livekit.io variant; hostnames are case-insensitive.
+    host = host.lower()
+    return host.startswith("cloud-api.") and host.endswith(".livekit.io")
+
+
 def to_http(url: str) -> str:
     """Normalizes a region URL to an http(s) scheme (ws -> http, wss -> https)."""
     if url.startswith("ws"):

{livekit_api-1.2.1 → livekit_api-1.2.2}/livekit/api/access_token.py

@@ -19,7 +19,7 @@ import os
 import jwt
 import dataclasses
 from dataclasses import dataclass
-from typing import Optional, List, Literal
+from typing import Optional, List, Literal, Type, TypeVar
 from google.protobuf.json_format import MessageToDict, ParseDict
 
 from livekit.protocol.room import RoomConfiguration
@@ -71,6 +71,9 @@ class VideoGrants:
     # allow participant to manage an agent session via RemoteSession
     can_manage_agent_session: Optional[bool] = None
 
+    # allow participant to subscribe to metrics
+    can_subscribe_metrics: Optional[bool] = None
+
 
 @dataclass
 class SIPGrants:
@@ -92,6 +95,43 @@ class ObservabilityGrants:
     write: bool = False
 
 
+@dataclass
+class AgentGrants:
+    # create/update/delete Cloud Agents
+    admin: bool = False
+    # manage simulations and scenarios for evaluating agents
+    simulation_admin: bool = False
+    # access the project's agent databases
+    database_admin: bool = False
+    # manage the project's agent dispatch queue
+    dispatch_admin: bool = False
+
+
+@dataclass
+class AgentEndpointGrants:
+    # invoke an agent's non-public HTTP endpoints
+    call: bool = False
+    # restrict to one agent; empty grants every agent in the project
+    agent_name: str = ""
+    # restrict to one deployment; empty grants every deployment
+    deployment: str = ""
+
+
+@dataclass
+class AgentThreadGrants:
+    # every thread and scope of the project; the action flags still apply
+    all: bool = False
+    # scope in which threads may be listed and created
+    scope: str = ""
+    # threads that may be read, written and deleted
+    thread_ids: Optional[List[str]] = None
+    list: bool = False
+    create: bool = False
+    write: bool = False
+    read: bool = False
+    delete: bool = False
+
+
 @dataclass
 class Claims:
     identity: str = ""
@@ -102,6 +142,9 @@ class Claims:
     sip: Optional[SIPGrants] = None
     inference: Optional[InferenceGrants] = None
     observability: Optional[ObservabilityGrants] = None
+    agent: Optional[AgentGrants] = None
+    agent_endpoint: Optional[AgentEndpointGrants] = None
+    agent_thread: Optional[AgentThreadGrants] = None
     attributes: Optional[dict[str, str]] = None
     sha256: Optional[str] = None
     room_preset: Optional[str] = None
@@ -162,6 +205,18 @@ class AccessToken:
         self.claims.inference = grants
         return self
 
+    def with_agent_grants(self, grants: AgentGrants) -> "AccessToken":
+        self.claims.agent = grants
+        return self
+
+    def with_agent_endpoint_grants(self, grants: AgentEndpointGrants) -> "AccessToken":
+        self.claims.agent_endpoint = grants
+        return self
+
+    def with_agent_thread_grants(self, grants: AgentThreadGrants) -> "AccessToken":
+        self.claims.agent_thread = grants
+        return self
+
     def with_identity(self, identity: str) -> "AccessToken":
         self.identity = identity
         return self
@@ -270,15 +325,29 @@ class TokenVerifier:
         }
         inference = InferenceGrants(**inference_dict)
 
+        observability_dict = claims.get("observability", dict())
+        observability_dict = {camel_to_snake(k): v for k, v in observability_dict.items()}
+        observability_dict = {
+            k: v
+            for k, v in observability_dict.items()
+            if k in ObservabilityGrants.__dataclass_fields__
+        }
+        observability = ObservabilityGrants(**observability_dict)
+
         grant_claims = Claims(
             identity=claims.get("sub", ""),
             name=claims.get("name", ""),
+            kind=claims.get("kind", ""),
             video=video,
             sip=sip,
             inference=inference,
+            observability=observability,
             attributes=claims.get("attributes", {}),
             metadata=claims.get("metadata", ""),
             sha256=claims.get("sha256", ""),
+            agent=_parse_grants(claims, "agent", AgentGrants),
+            agent_endpoint=_parse_grants(claims, "agentEndpoint", AgentEndpointGrants),
+            agent_thread=_parse_grants(claims, "agentThread", AgentThreadGrants),
         )
 
         if claims.get("roomPreset"):
@@ -294,6 +363,17 @@ class TokenVerifier:
         return grant_claims
 
 
+_G = TypeVar("_G")
+
+
+def _parse_grants(claims: dict, key: str, cls: Type[_G]) -> Optional[_G]:
+    grants = claims.get(key)
+    if grants is None:
+        return None
+    fields = cls.__dataclass_fields__  # type: ignore[attr-defined]
+    return cls(**{camel_to_snake(k): v for k, v in grants.items() if camel_to_snake(k) in fields})
+
+
 def camel_to_snake(t: str) -> str:
     return re.sub(r"(?<!^)(?=[A-Z])", "_", t).lower()
 

{livekit_api-1.2.1 → livekit_api-1.2.2}/livekit/api/sip_service.py

@@ -49,9 +49,10 @@ SVC = "SIP"
 
 
 def _as_sip_error(err: ServerError) -> ServerError:
-    """Surface a SIP dialing failure as a SipCallError so callers can branch on
-    the SIP status; other failures (auth, validation) are returned unchanged."""
-    if "sip_status_code" in err.metadata:
+    """Surface a SIP dialing or transfer failure as a SipCallError so callers can
+    branch on the SIP status or the transfer reason; other failures (auth,
+    validation) are returned unchanged."""
+    if "sip_status_code" in err.metadata or "sip_transfer_reason" in err.metadata:
         return SipCallError.from_server_error(err)
     return err
 

{livekit_api-1.2.1 → livekit_api-1.2.2}/livekit/api/twirp_client.py

@@ -26,6 +26,7 @@ from ._failover import (
     RegionCache,
     failover_attempts,
     host_key,
+    is_cloud_api,
     origin_of,
     pick_next,
 )
@@ -87,10 +88,19 @@ class ServerError(Exception):
         return result
 
 
+_SIP_META_KEYS = (
+    "sip_status_code",
+    "sip_status",
+    "sip_transfer_reason",
+    "error_details",
+)
+
+
 class SipCallError(ServerError):
     """A :class:`ServerError` from a SIP dialing call (``create_sip_participant`` /
-    ``transfer_sip_participant``) that failed with a SIP response status. The SIP
-    code and reason are exposed as properties; any other error metadata remains
+    ``transfer_sip_participant``) that failed with a SIP response status, or a
+    transfer that failed for any other reason. The SIP code and reason, and the
+    transfer reason, are exposed as properties; any other error metadata remains
     available via :attr:`metadata`."""
 
     @property
@@ -109,25 +119,36 @@ class SipCallError(ServerError):
         """The SIP reason phrase of the failed call, e.g. "Busy Here"."""
         return self.metadata.get("sip_status")
 
+    @property
+    def sip_transfer_reason(self) -> Optional[str]:
+        """Why a transfer failed, e.g. "STR_RINGING_TIMEOUT". Only set for
+        ``transfer_sip_participant``."""
+        return self.metadata.get("sip_transfer_reason")
+
+    @property
+    def sip_transfer_id(self) -> Optional[str]:
+        """The id of the failed transfer, for matching against SIP transfer logs."""
+        return self.metadata.get("sip_transfer_id")
+
     @classmethod
     def from_server_error(cls, err: ServerError) -> "SipCallError":
         return cls(err.code, err.message, status=err.status, metadata=err.metadata)
 
     def __str__(self) -> str:
         code = self.metadata.get("sip_status_code")
-        if code is None:
+        transfer_reason = self.metadata.get("sip_transfer_reason")
+        if code is None and transfer_reason is None:
             return super().__str__()
         # A clear, SIP-specific representation, including any extra metadata.
-        reason = self.metadata.get("sip_status")
-        result = f"SIP call failed: {code}"
-        if reason:
-            result += f" {reason}"
-        result += f" ({self.code})"
-        extra = {
-            k: v
-            for k, v in self.metadata.items()
-            if k not in ("sip_status_code", "sip_status", "error_details")
-        }
+        parts = []
+        if transfer_reason is not None:
+            parts.append(transfer_reason)
+        if code is not None:
+            reason = self.metadata.get("sip_status")
+            parts.append(f"{code} {reason}" if reason else str(code))
+        what = "SIP transfer failed" if transfer_reason is not None else "SIP call failed"
+        result = f"{what}: {', '.join(parts)} ({self.code})"
+        extra = {k: v for k, v in self.metadata.items() if k not in _SIP_META_KEYS}
         if extra:
             result += " [" + ", ".join(f"{k}={v}" for k, v in extra.items()) + "]"
         return result
@@ -182,7 +203,7 @@ class TwirpClient:
         if scheme.startswith("ws"):
             scheme = scheme.replace("ws", "http")
 
-        host = f"{scheme}://{parse_res.netloc}/{parse_res.path}"
+        host = f"{scheme}://{parse_res.netloc}{parse_res.path}"
         self.host = host.rstrip("/")
         self.pkg = pkg
         self.prefix = prefix
@@ -226,12 +247,16 @@ class TwirpClient:
             self._failover, host, self._failover_force, effective_timeout
         )
         attempted = {host_key(self._origin)}
-        region_origins: Optional[List[str]] = None
+        # A Cloud API host has a single origin; region discovery is never consulted.
+        region_origins: Optional[List[str]] = [] if host and is_cloud_api(host) else None
         current_origin = self._origin
+        # The configured host may carry a base path (e.g. behind a reverse
+        # proxy); fallback regions are bare origins.
+        current_base = self.host
 
         for attempt in range(max_attempts):
             is_last = attempt + 1 >= max_attempts
-            url = f"{current_origin}/{path}"
+            url = f"{current_base}/{path}"
 
             transport_exc: Optional[BaseException] = None
             retryable_status: Optional[int] = None
@@ -264,9 +289,12 @@ class TwirpClient:
                 next_origin = pick_next(region_origins, attempted)
 
             if next_origin is None:
-                if transport_exc is not None:
-                    raise transport_exc
-                raise self._server_error(error_data, retryable_status or 500)
+                if is_last:
+                    if transport_exc is not None:
+                        raise transport_exc
+                    raise self._server_error(error_data, retryable_status or 500)
+                # With no fallback origin, a retryable failure is retried against the same host.
+                next_origin = current_origin
 
             reason = transport_exc if transport_exc is not None else f"status {retryable_status}"
             logger.warning(
@@ -278,6 +306,7 @@ class TwirpClient:
             await asyncio.sleep(self._failover_backoff * (2**attempt))
             attempted.add(host_key(next_origin))
             current_origin = next_origin
+            current_base = next_origin
 
         raise RuntimeError("failover loop exited without returning")  # unreachable
 

livekit_api-1.2.2/livekit/api/version.py

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

{livekit_api-1.2.1 → livekit_api-1.2.2}/livekit/api/webhook.py

@@ -11,7 +11,7 @@ class WebhookReceiver:
 
     def receive(self, body: str, auth_token: str) -> WebhookEvent:
         claims = self._verifier.verify(auth_token)
-        if claims.sha256 is None:
+        if not claims.sha256:
             raise Exception("sha256 was not found in the token")
 
         body_hash = hashlib.sha256(body.encode()).digest()

{livekit_api-1.2.1 → livekit_api-1.2.2}/pyproject.toml

@@ -28,11 +28,16 @@ classifiers = [
     "Programming Language :: Python :: 3 :: Only",
 ]
 dependencies = [
-    "pyjwt>=2.0.0",
-    "aiohttp>=3.9.0",
+    "pyjwt>=2.15.1",
+    # aiohttp 3.14 dropped Python 3.9; keep its final compatible release there.
+    "aiohttp>=3.13.5; python_version < '3.10'",
+    "aiohttp>=3.14.4; python_version >= '3.10'",
+    # Security floors for aiohttp's transitive dependencies.
+    "idna>=3.15",
+    "multidict>=6.9.1; python_version >= '3.10'",
     "protobuf>=4",
     "types-protobuf>=4",
-    "livekit-protocol>=1.1.25,<2.0.0",
+    "livekit-protocol>=1.1.27,<2.0.0",
 ]
 
 [project.urls]

livekit_api-1.2.1/livekit/api/version.py

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