create-spatius-app 0.1.0-beta.0

package/templates/cloudflare-livekit/agent/src/dispatch_metadata.py

@@ -0,0 +1,64 @@
+import json
+from dataclasses import dataclass
+
+AGENT_DISPATCH_METADATA_VERSION = 1
+DEFAULT_VOICE_ID = "9626c31c-bec5-4cca-baa8-f8ba9e84c8bc"  # Jacqueline
+
+
+class DispatchMetadataError(ValueError):
+    """Raised when LiveKit dispatch metadata does not match the contract."""
+
+
+@dataclass(frozen=True)
+class AgentDispatchMetadata:
+    avatar_id: str
+    voice_id: str = DEFAULT_VOICE_ID
+
+
+def parse_agent_dispatch_metadata(raw_metadata: str) -> AgentDispatchMetadata:
+    if not raw_metadata:
+        raise DispatchMetadataError("Agent dispatch metadata is required.")
+
+    try:
+        payload = json.loads(raw_metadata)
+    except json.JSONDecodeError as error:
+        raise DispatchMetadataError(
+            "Agent dispatch metadata must be valid JSON."
+        ) from error
+
+    if not isinstance(payload, dict):
+        raise DispatchMetadataError("Agent dispatch metadata must be a JSON object.")
+
+    version = payload.get("version")
+    if type(version) is not int or version != AGENT_DISPATCH_METADATA_VERSION:
+        raise DispatchMetadataError(
+            f"Unsupported agent dispatch metadata version: {version!r}."
+        )
+
+    avatar = payload.get("avatar")
+    if not isinstance(avatar, dict):
+        raise DispatchMetadataError(
+            "Agent dispatch metadata must include an avatar object."
+        )
+
+    avatar_id = avatar.get("id")
+    if not isinstance(avatar_id, str) or not avatar_id.strip():
+        raise DispatchMetadataError(
+            "Agent dispatch metadata must include a non-empty avatar.id."
+        )
+
+    # Optional in v1 so older Workers keep their original standard female voice.
+    voice_id = DEFAULT_VOICE_ID
+    if "voice" in payload:
+        voice = payload["voice"]
+        if not isinstance(voice, dict):
+            raise DispatchMetadataError(
+                "Agent dispatch metadata voice must be an object."
+            )
+        voice_id = voice.get("id")
+        if not isinstance(voice_id, str) or not voice_id.strip():
+            raise DispatchMetadataError(
+                "Agent dispatch metadata needs a non-empty voice.id."
+            )
+
+    return AgentDispatchMetadata(avatar_id=avatar_id.strip(), voice_id=voice_id.strip())

package/templates/cloudflare-livekit/agent/tests/test_agent_startup.py

@@ -0,0 +1,211 @@
+import asyncio
+import json
+import unittest
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, patch
+
+from src.dispatch_metadata import DispatchMetadataError
+
+# Import the real entrypoint without loading local development credentials.
+with patch("dotenv.load_dotenv"):
+    from src import agent as agent_module
+
+
+class AgentStartupTests(unittest.IsolatedAsyncioTestCase):
+    def setUp(self) -> None:
+        self.events: list[str] = []
+        self.connected = False
+        self.room = SimpleNamespace(name="test-room")
+        self.browser_joined = asyncio.Event()
+        self.browser_joined.set()
+        self.waiting_for_browser = asyncio.Event()
+        self.ctx = SimpleNamespace(
+            room=self.room,
+            job=SimpleNamespace(
+                metadata=json.dumps({"version": 1, "avatar": {"id": "avatar-test"}})
+            ),
+            connect=AsyncMock(side_effect=self.connect),
+            wait_for_participant=AsyncMock(side_effect=self.wait_for_browser),
+        )
+        self.session = SimpleNamespace(
+            start=AsyncMock(side_effect=self.start_session),
+            say=AsyncMock(side_effect=self.say_greeting),
+        )
+        self.avatar = SimpleNamespace(start=AsyncMock(side_effect=self.start_avatar))
+        self.session_factory = self.enterContext(
+            patch.object(agent_module, "AgentSession", return_value=self.session)
+        )
+        self.avatar_factory = self.enterContext(
+            patch.object(
+                agent_module.spatius, "AvatarSession", return_value=self.avatar
+            )
+        )
+        self.assistant_factory = self.enterContext(
+            patch.object(agent_module, "Assistant")
+        )
+        self.inference = self.enterContext(patch.object(agent_module, "inference"))
+        self.bvc = self.enterContext(
+            patch.object(agent_module.noise_cancellation, "BVC")
+        )
+        self.enterContext(patch.object(agent_module, "TurnHandlingOptions"))
+
+    async def connect(self) -> None:
+        # Ensure startup waits for connection completion, not just invocation.
+        await asyncio.sleep(0)
+        self.connected = True
+        self.events.append("connect")
+
+    async def start_avatar(self, session, *, room) -> None:
+        self.assertTrue(self.connected, "Spatius started before the room connected")
+        self.assertIs(session, self.session)
+        self.assertIs(room, self.room)
+        await asyncio.sleep(0)
+        self.events.append("avatar")
+
+    async def start_session(self, *, agent, room, room_options) -> None:
+        self.assertEqual(self.events, ["connect", "avatar"])
+        self.assertIs(agent, self.assistant_factory.return_value)
+        self.assertIs(room, self.room)
+        self.assertIs(
+            room_options.audio_input.noise_cancellation, self.bvc.return_value
+        )
+        self.events.append("session")
+
+    async def wait_for_browser(self, *, kind):
+        self.assertEqual(
+            kind, agent_module.rtc.ParticipantKind.PARTICIPANT_KIND_STANDARD
+        )
+        self.assertEqual(self.events, ["connect", "avatar", "session"])
+        self.waiting_for_browser.set()
+        await self.browser_joined.wait()
+        self.events.append("browser")
+
+    async def say_greeting(self, text, *, allow_interruptions) -> None:
+        self.assertEqual(self.events, ["connect", "avatar", "session", "browser"])
+        self.assertTrue(allow_interruptions)
+        self.events.append("greeting")
+
+    async def test_connects_before_avatar_and_voice_session_startup(self) -> None:
+        await agent_module.spatius_agent(self.ctx)
+
+        self.assertEqual(
+            self.events, ["connect", "avatar", "session", "browser", "greeting"]
+        )
+        self.session.say.assert_awaited_once_with(
+            "Hi! I'm here to help. What would you like to talk about?",
+            allow_interruptions=True,
+        )
+        self.ctx.connect.assert_awaited_once_with()
+        self.avatar_factory.assert_called_once_with(avatar_id="avatar-test")
+        self.avatar.start.assert_awaited_once_with(self.session, room=self.room)
+        self.session.start.assert_awaited_once_with(
+            agent=self.assistant_factory.return_value,
+            room=self.room,
+            room_options=self.session.start.call_args.kwargs["room_options"],
+        )
+        self.bvc.assert_called_once_with()
+        self.inference.TTS.assert_called_once_with(
+            model="cartesia/sonic-3.6",
+            voice="9626c31c-bec5-4cca-baa8-f8ba9e84c8bc",
+            language="en",
+        )
+        self.assertTrue(self.session_factory.call_args.kwargs["expressive"])
+        self.assertTrue(
+            self.session_factory.call_args.kwargs["use_tts_aligned_transcript"]
+        )
+
+    async def test_connection_failure_prevents_avatar_and_voice_startup(self) -> None:
+        self.ctx.connect.side_effect = ConnectionError("room connection failed")
+
+        with self.assertRaisesRegex(ConnectionError, "room connection failed"):
+            await agent_module.spatius_agent(self.ctx)
+
+        self.avatar_factory.assert_not_called()
+        self.avatar.start.assert_not_awaited()
+        self.session.start.assert_not_awaited()
+
+    async def test_connection_cancellation_prevents_avatar_and_voice_startup(
+        self,
+    ) -> None:
+        self.ctx.connect.side_effect = asyncio.CancelledError()
+
+        with self.assertRaises(asyncio.CancelledError):
+            await agent_module.spatius_agent(self.ctx)
+
+        self.avatar_factory.assert_not_called()
+        self.avatar.start.assert_not_awaited()
+        self.session.start.assert_not_awaited()
+
+    async def test_invalid_metadata_is_rejected_before_connecting(self) -> None:
+        self.ctx.job.metadata = "invalid-json"
+
+        with self.assertRaises(DispatchMetadataError):
+            await agent_module.spatius_agent(self.ctx)
+
+        self.ctx.connect.assert_not_awaited()
+        self.session_factory.assert_not_called()
+        self.avatar_factory.assert_not_called()
+
+    async def test_avatar_failure_prevents_voice_session_startup(self) -> None:
+        self.avatar.start.side_effect = RuntimeError("avatar startup failed")
+
+        with self.assertRaisesRegex(RuntimeError, "avatar startup failed"):
+            await agent_module.spatius_agent(self.ctx)
+
+        self.ctx.connect.assert_awaited_once_with()
+        self.session.start.assert_not_awaited()
+        self.session.say.assert_not_awaited()
+
+    async def test_session_failure_does_not_greet(self) -> None:
+        self.session.start.side_effect = RuntimeError("session startup failed")
+        with self.assertRaisesRegex(RuntimeError, "session startup failed"):
+            await agent_module.spatius_agent(self.ctx)
+        self.session.say.assert_not_awaited()
+
+    async def test_slow_browser_delays_greeting_until_it_joins(self) -> None:
+        self.browser_joined.clear()
+        task = asyncio.create_task(agent_module.spatius_agent(self.ctx))
+        try:
+            await asyncio.wait_for(self.waiting_for_browser.wait(), timeout=1)
+            self.session.start.assert_awaited_once()
+            self.avatar.start.assert_awaited_once()
+            self.session.say.assert_not_awaited()
+            self.browser_joined.set()
+            await asyncio.wait_for(task, timeout=1)
+            self.session.say.assert_awaited_once()
+        finally:
+            task.cancel()
+            await asyncio.gather(task, return_exceptions=True)
+
+    async def test_cancellation_while_waiting_never_greets(self) -> None:
+        self.browser_joined.clear()
+        task = asyncio.create_task(agent_module.spatius_agent(self.ctx))
+        try:
+            await asyncio.wait_for(self.waiting_for_browser.wait(), timeout=1)
+            task.cancel()
+            with self.assertRaises(asyncio.CancelledError):
+                await task
+            self.session.say.assert_not_awaited()
+        finally:
+            task.cancel()
+            await asyncio.gather(task, return_exceptions=True)
+
+    async def test_uses_the_business_layer_selected_masculine_voice(self) -> None:
+        voice_id = "a167e0f3-df7e-4d52-a9c3-f949145efdab"
+        self.ctx.job.metadata = json.dumps(
+            {
+                "version": 1,
+                "avatar": {"id": "avatar-test"},
+                "voice": {"id": voice_id},
+            }
+        )
+        await agent_module.spatius_agent(self.ctx)
+        self.inference.TTS.assert_called_once_with(
+            model="cartesia/sonic-3.6",
+            voice=voice_id,
+            language="en",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

package/templates/cloudflare-livekit/agent/tests/test_dispatch_metadata.py

@@ -0,0 +1,97 @@
+import json
+import unittest
+
+from src.dispatch_metadata import (
+    AGENT_DISPATCH_METADATA_VERSION,
+    DEFAULT_VOICE_ID,
+    DispatchMetadataError,
+    parse_agent_dispatch_metadata,
+)
+
+
+class AgentDispatchMetadataTests(unittest.TestCase):
+    def test_parses_avatar_id(self) -> None:
+        metadata = parse_agent_dispatch_metadata(
+            json.dumps(
+                {
+                    "version": AGENT_DISPATCH_METADATA_VERSION,
+                    "avatar": {"id": "avatar-123"},
+                }
+            )
+        )
+
+        self.assertEqual(metadata.avatar_id, "avatar-123")
+        self.assertEqual(metadata.voice_id, DEFAULT_VOICE_ID)
+
+    def test_parses_selected_voice(self) -> None:
+        for voice_id in [DEFAULT_VOICE_ID, "a167e0f3-df7e-4d52-a9c3-f949145efdab"]:
+            with self.subTest(voice_id=voice_id):
+                metadata = parse_agent_dispatch_metadata(
+                    json.dumps(
+                        {
+                            "version": 1,
+                            "avatar": {"id": "avatar-123"},
+                            "voice": {"id": voice_id},
+                        }
+                    )
+                )
+                self.assertEqual(metadata.voice_id, voice_id)
+
+    def test_rejects_invalid_voice_without_silently_using_a_different_voice(
+        self,
+    ) -> None:
+        for voice in [None, "masculine", {}, {"id": " "}, {"id": 123}]:
+            with self.subTest(voice=voice), self.assertRaises(DispatchMetadataError):
+                parse_agent_dispatch_metadata(
+                    json.dumps(
+                        {
+                            "version": 1,
+                            "avatar": {"id": "avatar-123"},
+                            "voice": voice,
+                        }
+                    )
+                )
+
+    def test_allows_future_optional_fields(self) -> None:
+        metadata = parse_agent_dispatch_metadata(
+            json.dumps(
+                {
+                    "version": AGENT_DISPATCH_METADATA_VERSION,
+                    "avatar": {"id": "avatar-123", "style": "friendly"},
+                    "session": {"locale": "en-US"},
+                }
+            )
+        )
+
+        self.assertEqual(metadata.avatar_id, "avatar-123")
+
+    def test_rejects_invalid_json(self) -> None:
+        with self.assertRaisesRegex(DispatchMetadataError, "valid JSON"):
+            parse_agent_dispatch_metadata("not-json")
+
+    def test_rejects_unsupported_version(self) -> None:
+        with self.assertRaisesRegex(DispatchMetadataError, "Unsupported"):
+            parse_agent_dispatch_metadata(
+                json.dumps({"version": 2, "avatar": {"id": "avatar-123"}})
+            )
+
+    def test_rejects_missing_avatar_id(self) -> None:
+        with self.assertRaisesRegex(DispatchMetadataError, "avatar.id"):
+            parse_agent_dispatch_metadata(
+                json.dumps({"version": AGENT_DISPATCH_METADATA_VERSION, "avatar": {}})
+            )
+
+    def test_rejects_blank_avatar_id(self) -> None:
+        with self.assertRaisesRegex(DispatchMetadataError, "avatar.id"):
+            parse_agent_dispatch_metadata(
+                json.dumps(
+                    {
+                        "version": AGENT_DISPATCH_METADATA_VERSION,
+                        "avatar": {"id": "   "},
+                    }
+                )
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()