livekit-api 0.7.0__tar.gz → 0.8.0__tar.gz

{livekit_api-0.7.0 → livekit_api-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: livekit-api
-Version: 0.7.0
+Version: 0.8.0
 Summary: Python Server API for LiveKit
 Home-page: https://github.com/livekit/python-sdks
 License: Apache-2.0
@@ -25,7 +25,7 @@ Requires-Dist: pyjwt>=2.0.0
 Requires-Dist: aiohttp>=3.9.0
 Requires-Dist: protobuf>=3
 Requires-Dist: types-protobuf<5,>=4
-Requires-Dist: livekit-protocol<2,>=0.5.1
+Requires-Dist: livekit-protocol<2,>=0.7.0
 
 # LiveKit Server APIs
 

{livekit_api-0.7.0 → livekit_api-0.8.0}/livekit/api/__init__.py

@@ -16,6 +16,8 @@
 
 # flake8: noqa
 # re-export packages from protocol
+from livekit.protocol.agent_dispatch import *
+from livekit.protocol.agent import *
 from livekit.protocol.egress import *
 from livekit.protocol.ingress import *
 from livekit.protocol.models import *

{livekit_api-0.7.0 → livekit_api-0.8.0}/livekit/api/_service.py

@@ -18,11 +18,13 @@ class Service(ABC):
         self.api_secret = api_secret
 
     def _auth_header(
-        self, grants: VideoGrants, sip: SIPGrants | None = None
+        self, grants: VideoGrants | None, sip: SIPGrants | None = None
     ) -> Dict[str, str]:
-        tok = AccessToken(self.api_key, self.api_secret).with_grants(grants)
+        tok = AccessToken(self.api_key, self.api_secret)
+        if grants:
+            tok.with_grants(grants)
         if sip is not None:
-            tok = tok.with_sip_grants(sip)
+            tok.with_sip_grants(sip)
 
         token = tok.to_jwt()
 

{livekit_api-0.7.0 → livekit_api-0.8.0}/livekit/api/access_token.py

@@ -18,7 +18,10 @@ import re
 import datetime
 import os
 import jwt
-from typing import Optional, List
+from typing import Optional, List, Literal
+from google.protobuf.json_format import MessageToDict, ParseDict
+
+from livekit.protocol.room import RoomConfiguration
 
 DEFAULT_TTL = datetime.timedelta(hours=6)
 DEFAULT_LEEWAY = datetime.timedelta(minutes=1)
@@ -27,13 +30,13 @@ DEFAULT_LEEWAY = datetime.timedelta(minutes=1)
 @dataclasses.dataclass
 class VideoGrants:
     # actions on rooms
-    room_create: bool = False
-    room_list: bool = False
-    room_record: bool = False
+    room_create: Optional[bool] = None
+    room_list: Optional[bool] = None
+    room_record: Optional[bool] = None
 
     # actions on a particular room
-    room_admin: bool = False
-    room_join: bool = False
+    room_admin: Optional[bool] = None
+    room_join: Optional[bool] = None
     room: str = ""
 
     # permissions within a room
@@ -42,25 +45,24 @@ class VideoGrants:
     can_publish_data: bool = True
 
     # TrackSource types that a participant may publish.
-    # When set, it supercedes CanPublish. Only sources explicitly set here can be
+    # When set, it supersedes CanPublish. Only sources explicitly set here can be
     # published
-    can_publish_sources: List[str] = dataclasses.field(default_factory=list)
+    can_publish_sources: Optional[List[str]] = None
 
     # by default, a participant is not allowed to update its own metadata
-    can_update_own_metadata: bool = False
+    can_update_own_metadata: Optional[bool] = None
 
     # actions on ingresses
-    ingress_admin: bool = False  # applies to all ingress
+    ingress_admin: Optional[bool] = None  # applies to all ingress
 
     # participant is not visible to other participants (useful when making bots)
-    hidden: bool = False
+    hidden: Optional[bool] = None
 
-    # indicates to the room that current participant is a recorder
-    recorder: bool = False
+    # [deprecated] indicates to the room that current participant is a recorder
+    recorder: Optional[bool] = None
 
     # indicates that the holder can register as an Agent framework worker
-    # it is also set on all participants that are joining as Agent
-    agent: bool = False
+    agent: Optional[bool] = None
 
 
 @dataclasses.dataclass
@@ -75,14 +77,33 @@ class SIPGrants:
 class Claims:
     identity: str = ""
     name: str = ""
-    video: VideoGrants = dataclasses.field(default_factory=VideoGrants)
-    sip: SIPGrants = dataclasses.field(default_factory=SIPGrants)
-    attributes: dict[str, str] = dataclasses.field(default_factory=dict)
+    kind: str = ""
     metadata: str = ""
-    sha256: str = ""
+    video: Optional[VideoGrants] = None
+    sip: Optional[SIPGrants] = None
+    attributes: Optional[dict[str, str]] = None
+    sha256: Optional[str] = None
+    room_preset: Optional[str] = None
+    room_config: Optional[RoomConfiguration] = None
+
+    def asdict(self) -> dict:
+        # in order to produce minimal JWT size, exclude None or empty values
+        claims = dataclasses.asdict(
+            self,
+            dict_factory=lambda items: {
+                snake_to_lower_camel(k): v
+                for k, v in items
+                if v is not None and v != ""
+            },
+        )
+        if self.room_config:
+            claims["roomConfig"] = MessageToDict(self.room_config)
+        return claims
 
 
 class AccessToken:
+    ParticipantKind = Literal["standard", "egress", "ingress", "sip", "agent"]
+
     def __init__(
         self,
         api_key: Optional[str] = None,
@@ -118,6 +139,10 @@ class AccessToken:
         self.identity = identity
         return self
 
+    def with_kind(self, kind: ParticipantKind) -> "AccessToken":
+        self.claims.kind = kind
+        return self
+
     def with_name(self, name: str) -> "AccessToken":
         self.claims.name = name
         return self
@@ -134,26 +159,36 @@ class AccessToken:
         self.claims.sha256 = sha256
         return self
 
+    def with_room_preset(self, preset: str) -> "AccessToken":
+        self.claims.room_preset = preset
+        return self
+
+    def with_room_config(self, config: RoomConfiguration) -> "AccessToken":
+        self.claims.room_config = config
+        return self
+
     def to_jwt(self) -> str:
         video = self.claims.video
-        if video.room_join and (not self.identity or not video.room):
+        if video and video.room_join and (not self.identity or not video.room):
             raise ValueError("identity and room must be set when joining a room")
 
-        claims = dataclasses.asdict(
-            self.claims,
-            dict_factory=lambda items: {snake_to_lower_camel(k): v for k, v in items},
-        )
-        claims.update(
+        # we want to exclude None values from the token
+        jwt_claims = self.claims.asdict()
+        jwt_claims.update(
             {
                 "sub": self.identity,
                 "iss": self.api_key,
-                "nbf": calendar.timegm(datetime.datetime.utcnow().utctimetuple()),
+                "nbf": calendar.timegm(
+                    datetime.datetime.now(datetime.timezone.utc).utctimetuple()
+                ),
                 "exp": calendar.timegm(
-                    (datetime.datetime.utcnow() + self.ttl).utctimetuple()
+                    (
+                        datetime.datetime.now(datetime.timezone.utc) + self.ttl
+                    ).utctimetuple()
                 ),
             }
         )
-        return jwt.encode(claims, self.api_secret, algorithm="HS256")
+        return jwt.encode(jwt_claims, self.api_secret, algorithm="HS256")
 
 
 class TokenVerifier:
@@ -197,7 +232,7 @@ class TokenVerifier:
         }
         sip = SIPGrants(**sip_dict)
 
-        return Claims(
+        grant_claims = Claims(
             identity=claims.get("sub", ""),
             name=claims.get("name", ""),
             video=video,
@@ -207,6 +242,17 @@ class TokenVerifier:
             sha256=claims.get("sha256", ""),
         )
 
+        if claims.get("roomPreset"):
+            grant_claims.room_preset = claims.get("roomPreset")
+        if claims.get("roomConfig"):
+            grant_claims.room_config = ParseDict(
+                claims.get("roomConfig"),
+                RoomConfiguration(),
+                ignore_unknown_fields=True,
+            )
+
+        return grant_claims
+
 
 def camel_to_snake(t: str):
     return re.sub(r"(?<!^)(?=[A-Z])", "_", t).lower()

livekit_api-0.8.0/livekit/api/agent_dispatch_service.py

@@ -0,0 +1,108 @@
+import aiohttp
+from typing import Optional
+from livekit.protocol import agent_dispatch as proto_agent_dispatch
+from ._service import Service
+from .access_token import VideoGrants
+
+SVC = "AgentDispatchService"
+
+
+class AgentDispatchService(Service):
+    """Manage agent dispatches. Service APIs require roomAdmin permissions.
+
+    An easier way to construct this service is via LiveKitAPI.agent_dispatch.
+    """
+
+    def __init__(
+        self, session: aiohttp.ClientSession, url: str, api_key: str, api_secret: str
+    ):
+        super().__init__(session, url, api_key, api_secret)
+
+    async def create_dispatch(
+        self, req: proto_agent_dispatch.CreateAgentDispatchRequest
+    ) -> proto_agent_dispatch.AgentDispatch:
+        """Create an explicit dispatch for an agent to join a room.
+
+        To use explicit dispatch, your agent must be registered with an `agentName`.
+
+        Args:
+            req (CreateAgentDispatchRequest): Request containing dispatch creation parameters
+
+        Returns:
+            AgentDispatch: The created agent dispatch object
+        """
+        return await self._client.request(
+            SVC,
+            "CreateDispatch",
+            req,
+            self._auth_header(VideoGrants(room_admin=True, room=req.room)),
+            proto_agent_dispatch.AgentDispatch,
+        )
+
+    async def delete_dispatch(
+        self, dispatch_id: str, room_name: str
+    ) -> proto_agent_dispatch.AgentDispatch:
+        """Delete an explicit dispatch for an agent in a room.
+
+        Args:
+            dispatch_id (str): ID of the dispatch to delete
+            room_name (str): Name of the room containing the dispatch
+
+        Returns:
+            AgentDispatch: The deleted agent dispatch object
+        """
+        return await self._client.request(
+            SVC,
+            "DeleteDispatch",
+            proto_agent_dispatch.DeleteAgentDispatchRequest(
+                dispatch_id=dispatch_id,
+                room=room_name,
+            ),
+            self._auth_header(VideoGrants(room_admin=True, room=room_name)),
+            proto_agent_dispatch.AgentDispatch,
+        )
+
+    async def list_dispatch(
+        self, room_name: str
+    ) -> list[proto_agent_dispatch.AgentDispatch]:
+        """List all agent dispatches in a room.
+
+        Args:
+            room_name (str): Name of the room to list dispatches from
+
+        Returns:
+            list[AgentDispatch]: List of agent dispatch objects in the room
+        """
+        res = await self._client.request(
+            SVC,
+            "ListDispatch",
+            proto_agent_dispatch.ListAgentDispatchRequest(room=room_name),
+            self._auth_header(VideoGrants(room_admin=True, room=room_name)),
+            proto_agent_dispatch.ListAgentDispatchResponse,
+        )
+        return list(res.agent_dispatches)
+
+    async def get_dispatch(
+        self, dispatch_id: str, room_name: str
+    ) -> Optional[proto_agent_dispatch.AgentDispatch]:
+        """Get an Agent dispatch by ID
+
+        Args:
+            dispatch_id (str): ID of the dispatch to retrieve
+            room_name (str): Name of the room containing the dispatch
+
+        Returns:
+            Optional[AgentDispatch]: The requested agent dispatch object if found, None otherwise
+        """
+        res = await self._client.request(
+            SVC,
+            "ListDispatch",
+            proto_agent_dispatch.ListAgentDispatchRequest(
+                dispatch_id=dispatch_id, room=room_name
+            ),
+            self._auth_header(VideoGrants(room_admin=True, room=room_name)),
+            proto_agent_dispatch.ListAgentDispatchResponse,
+        )
+        if len(res.agent_dispatches) > 0:
+            return res.agent_dispatches[0]
+        return None

{livekit_api-0.7.0 → livekit_api-0.8.0}/livekit/api/livekit_api.py

@@ -4,6 +4,7 @@ from .room_service import RoomService
 from .egress_service import EgressService
 from .ingress_service import IngressService
 from .sip_service import SipService
+from .agent_dispatch_service import AgentDispatchService
 from typing import Optional
 
 
@@ -31,6 +32,13 @@ class LiveKitAPI:
         self._ingress = IngressService(self._session, url, api_key, api_secret)
         self._egress = EgressService(self._session, url, api_key, api_secret)
         self._sip = SipService(self._session, url, api_key, api_secret)
+        self._agent_dispatch = AgentDispatchService(
+            self._session, url, api_key, api_secret
+        )
+
+    @property
+    def agent_dispatch(self):
+        return self._agent_dispatch
 
     @property
     def room(self):

{livekit_api-0.7.0 → livekit_api-0.8.0}/livekit/api/sip_service.py

@@ -132,3 +132,20 @@ class SipService(Service):
             self._auth_header(VideoGrants(), sip=SIPGrants(call=True)),
             proto_sip.SIPParticipantInfo,
         )
+
+    async def transfer_sip_participant(
+        self, transfer: proto_sip.TransferSIPParticipantRequest
+    ) -> proto_sip.SIPParticipantInfo:
+        return await self._client.request(
+            SVC,
+            "TransferSIPParticipant",
+            transfer,
+            self._auth_header(
+                VideoGrants(
+                    room_admin=True,
+                    room=transfer.room_name,
+                ),
+                sip=SIPGrants(call=True),
+            ),
+            proto_sip.SIPParticipantInfo,
+        )

livekit_api-0.8.0/livekit/api/version.py

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

{livekit_api-0.7.0 → livekit_api-0.8.0}/livekit/api/webhook.py

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

{livekit_api-0.7.0 → livekit_api-0.8.0}/livekit_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: livekit-api
-Version: 0.7.0
+Version: 0.8.0
 Summary: Python Server API for LiveKit
 Home-page: https://github.com/livekit/python-sdks
 License: Apache-2.0
@@ -25,7 +25,7 @@ Requires-Dist: pyjwt>=2.0.0
 Requires-Dist: aiohttp>=3.9.0
 Requires-Dist: protobuf>=3
 Requires-Dist: types-protobuf<5,>=4
-Requires-Dist: livekit-protocol<2,>=0.5.1
+Requires-Dist: livekit-protocol<2,>=0.7.0
 
 # LiveKit Server APIs
 

{livekit_api-0.7.0 → livekit_api-0.8.0}/livekit_api.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ setup.py
 livekit/api/__init__.py
 livekit/api/_service.py
 livekit/api/access_token.py
+livekit/api/agent_dispatch_service.py
 livekit/api/egress_service.py
 livekit/api/ingress_service.py
 livekit/api/livekit_api.py

{livekit_api-0.7.0 → livekit_api-0.8.0}/livekit_api.egg-info/requires.txt

@@ -2,4 +2,4 @@ pyjwt>=2.0.0
 aiohttp>=3.9.0
 protobuf>=3
 types-protobuf<5,>=4
-livekit-protocol<2,>=0.5.1
+livekit-protocol<2,>=0.7.0

{livekit_api-0.7.0 → livekit_api-0.8.0}/setup.py

@@ -53,7 +53,7 @@ setuptools.setup(
         "aiohttp>=3.9.0",
         "protobuf>=3",
         "types-protobuf>=4,<5",
-        "livekit-protocol>=0.5.1,<2",
+        "livekit-protocol>=0.7.0,<2",
     ],
     package_data={
         "livekit.api": ["py.typed", "*.pyi", "**/*.pyi"],

{livekit_api-0.7.0 → livekit_api-0.8.0}/tests/test_access_token.py

@@ -2,6 +2,8 @@ import datetime
 
 import pytest  # type: ignore
 from livekit.api import AccessToken, TokenVerifier, VideoGrants, SIPGrants
+from livekit.protocol.room import RoomConfiguration
+from livekit.protocol.agent_dispatch import RoomAgentDispatch
 
 TEST_API_KEY = "myapikey"
 TEST_API_SECRET = "thiskeyistotallyunsafe"
@@ -32,6 +34,46 @@ def test_verify_token():
     assert claims.attributes["key2"] == "value2"
 
 
+def test_agent_config():
+    token = (
+        AccessToken(TEST_API_KEY, TEST_API_SECRET)
+        .with_identity("test_identity")
+        .with_grants(VideoGrants(room_join=True, room="test_room"))
+        .with_room_config(
+            RoomConfiguration(
+                agents=[RoomAgentDispatch(agent_name="test-agent")],
+            ),
+        )
+        .to_jwt()
+    )
+
+    token_verifier = TokenVerifier(TEST_API_KEY, TEST_API_SECRET)
+    claims = token_verifier.verify(token)
+    # Verify the decoded claims match
+    assert claims.room_config.agents[0].agent_name == "test-agent"
+
+    # Split token into header.payload.signature
+    parts = token.split(".")
+    import base64
+    import json
+
+    # Decode the payload (middle part)
+    payload = parts[1]
+    # Add padding if needed
+    padding = len(payload) % 4
+    if padding:
+        payload += "=" * (4 - padding)
+    decoded = base64.b64decode(payload)
+    payload_json = json.loads(decoded)
+    print(decoded)
+
+    # Verify the room_config and agents were encoded correctly
+    assert "roomConfig" in payload_json
+    assert "agents" in payload_json["roomConfig"]
+    assert len(payload_json["roomConfig"]["agents"]) == 1
+    assert payload_json["roomConfig"]["agents"][0]["agentName"] == "test-agent"
+
+
 def test_verify_token_invalid():
     token = (
         AccessToken(TEST_API_KEY, TEST_API_SECRET)

livekit_api-0.7.0/livekit/api/version.py

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