vision-agents-plugins-lemonslice 0.3.7__tar.gz

vision_agents_plugins_lemonslice-0.3.7/.gitignore

@@ -0,0 +1,96 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.cursor/*
+# Distribution / packaging
+.Python
+build/
+dist/
+downloads/
+develop-eggs/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+pip-wheel-metadata/
+MANIFEST
+*.egg-info/
+*.egg
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+coverage.xml
+nosetests.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Type checker / lint caches
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pytype/
+.pyre/
+.ruff_cache/
+
+# Environments
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.env
+.env.local
+.env.*.local
+.env.bak
+pyvenv.cfg
+.python-version
+
+# Editors / IDEs
+.vscode/
+.idea/
+
+# Jupyter Notebook
+.ipynb_checkpoints/
+
+# OS / Misc
+.DS_Store
+*.log
+
+# Tooling & repo-specific
+pyrightconfig.json
+shell.nix
+bin/*
+lib/*
+stream-py/
+
+# Example lock files (regenerated by uv sync)
+examples/*/uv.lock
+plugins/*/example/uv.lock
+
+# Artifacts / assets
+*.pt
+*.kef
+*.onnx
+profile.html
+
+/opencode.json
+.ralph-tui/
+.claude/

vision_agents_plugins_lemonslice-0.3.7/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: vision-agents-plugins-lemonslice
+Version: 0.3.7
+Summary: LemonSlice avatar plugin for Vision Agents
+Project-URL: Documentation, https://visionagents.ai/
+Project-URL: Website, https://visionagents.ai/
+Project-URL: Source, https://github.com/GetStream/Vision-Agents
+License-Expression: MIT
+Keywords: AI,agents,avatars,lemonslice,voice agents
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: livekit-api>=1.0.0
+Requires-Dist: livekit>=1.0.0
+Requires-Dist: vision-agents
+Description-Content-Type: text/markdown
+
+# LemonSlice Avatar Plugin for Vision Agents
+
+Add real-time interactive avatar video to your AI agents using LemonSlice's self-managed API.
+
+## Features
+
+- Real-time avatar video synchronized with TTS audio
+- Works with any TTS provider (Cartesia, ElevenLabs, etc.)
+- Supports both standard and Realtime LLMs
+- Customizable avatar expressions via agent prompts
+
+## Installation
+
+```bash
+pip install vision-agents[lemonslice]
+```
+
+Or with uv:
+
+```bash
+uv pip install vision-agents[lemonslice]
+```
+
+## Quick Start
+
+```python
+import asyncio
+from uuid import uuid4
+from dotenv import load_dotenv
+
+from vision_agents.core import User, Agent
+from vision_agents.plugins import cartesia, deepgram, getstream, gemini, lemonslice
+
+load_dotenv()
+
+
+async def start_avatar_agent():
+    agent = Agent(
+        edge=getstream.Edge(),
+        agent_user=User(name="AI Assistant with Avatar", id="agent"),
+        instructions="You're a friendly AI assistant.",
+
+        llm=gemini.LLM(),
+        tts=cartesia.TTS(),
+        stt=deepgram.STT(),
+
+        processors=[
+            lemonslice.LemonSliceAvatarPublisher(
+                agent_id="your-avatar-id",
+            )
+        ]
+    )
+
+    call = agent.edge.client.video.call("default", str(uuid4()))
+
+    async with agent.join(call):
+        await agent.simple_response("Hello! I'm your AI assistant with an avatar.")
+        await agent.finish()
+
+
+if __name__ == "__main__":
+    asyncio.run(start_avatar_agent())
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+LEMONSLICE_API_KEY=your_lemonslice_api_key
+# LemonSlice uses Livekit as a transport for audio and video
+LIVEKIT_URL=wss://your-livekit-server.com
+LIVEKIT_API_KEY=your_livekit_api_key
+LIVEKIT_API_SECRET=your_livekit_api_secret
+```
+
+### AvatarPublisher Options
+
+```python
+lemonslice.LemonSliceAvatarPublisher(
+    agent_id="your-avatar-id",  # LemonSlice agent ID
+    agent_image_url=None,  # Or provide a custom image URL (368x560px)
+    agent_prompt=None,  # Prompt to influence avatar expressions/movements
+    api_key=None,  # Optional: override LEMONSLICE_API_KEY env var
+    idle_timeout=None,  # Session timeout in seconds
+    livekit_url=None,  # Optional: override LIVEKIT_URL env var
+    livekit_api_key=None,  # Optional: override LIVEKIT_API_KEY env var
+    livekit_api_secret=None,  # Optional: override LIVEKIT_API_SECRET env var
+    width=1920,  # Output video width in pixels
+    height=1080,  # Output video height in pixels
+)
+```
+
+## How It Works
+
+1. **LemonSlice Session**: Creates a session via LemonSlice API, and joins the LiveKit room as a participant
+2. **Audio Forwarding**: TTS audio is captured and sent to LemonSlice via the room
+3. **Avatar Generation**: LemonSlice generates synchronized avatar video and audio
+4. **Video Streaming**: Avatar video is streamed to call participants via GetStream Edge
+
+## Requirements
+
+- Python 3.10+
+- LemonSlice API key (get one at [lemonslice.com](https://lemonslice.com))
+- LiveKit server (cloud or self-hosted)
+- GetStream account for video calls
+- TTS provider (Cartesia, ElevenLabs, etc.) or Realtime LLM
+
+## License
+
+MIT
+
+## Links
+
+- [Documentation](https://visionagents.ai/)
+- [GitHub](https://github.com/GetStream/Vision-Agents)
+- [LemonSlice Docs](https://lemonslice.com/docs/self-managed/overview)

vision_agents_plugins_lemonslice-0.3.7/README.md

@@ -0,0 +1,117 @@
+# LemonSlice Avatar Plugin for Vision Agents
+
+Add real-time interactive avatar video to your AI agents using LemonSlice's self-managed API.
+
+## Features
+
+- Real-time avatar video synchronized with TTS audio
+- Works with any TTS provider (Cartesia, ElevenLabs, etc.)
+- Supports both standard and Realtime LLMs
+- Customizable avatar expressions via agent prompts
+
+## Installation
+
+```bash
+pip install vision-agents[lemonslice]
+```
+
+Or with uv:
+
+```bash
+uv pip install vision-agents[lemonslice]
+```
+
+## Quick Start
+
+```python
+import asyncio
+from uuid import uuid4
+from dotenv import load_dotenv
+
+from vision_agents.core import User, Agent
+from vision_agents.plugins import cartesia, deepgram, getstream, gemini, lemonslice
+
+load_dotenv()
+
+
+async def start_avatar_agent():
+    agent = Agent(
+        edge=getstream.Edge(),
+        agent_user=User(name="AI Assistant with Avatar", id="agent"),
+        instructions="You're a friendly AI assistant.",
+
+        llm=gemini.LLM(),
+        tts=cartesia.TTS(),
+        stt=deepgram.STT(),
+
+        processors=[
+            lemonslice.LemonSliceAvatarPublisher(
+                agent_id="your-avatar-id",
+            )
+        ]
+    )
+
+    call = agent.edge.client.video.call("default", str(uuid4()))
+
+    async with agent.join(call):
+        await agent.simple_response("Hello! I'm your AI assistant with an avatar.")
+        await agent.finish()
+
+
+if __name__ == "__main__":
+    asyncio.run(start_avatar_agent())
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+LEMONSLICE_API_KEY=your_lemonslice_api_key
+# LemonSlice uses Livekit as a transport for audio and video
+LIVEKIT_URL=wss://your-livekit-server.com
+LIVEKIT_API_KEY=your_livekit_api_key
+LIVEKIT_API_SECRET=your_livekit_api_secret
+```
+
+### AvatarPublisher Options
+
+```python
+lemonslice.LemonSliceAvatarPublisher(
+    agent_id="your-avatar-id",  # LemonSlice agent ID
+    agent_image_url=None,  # Or provide a custom image URL (368x560px)
+    agent_prompt=None,  # Prompt to influence avatar expressions/movements
+    api_key=None,  # Optional: override LEMONSLICE_API_KEY env var
+    idle_timeout=None,  # Session timeout in seconds
+    livekit_url=None,  # Optional: override LIVEKIT_URL env var
+    livekit_api_key=None,  # Optional: override LIVEKIT_API_KEY env var
+    livekit_api_secret=None,  # Optional: override LIVEKIT_API_SECRET env var
+    width=1920,  # Output video width in pixels
+    height=1080,  # Output video height in pixels
+)
+```
+
+## How It Works
+
+1. **LemonSlice Session**: Creates a session via LemonSlice API, and joins the LiveKit room as a participant
+2. **Audio Forwarding**: TTS audio is captured and sent to LemonSlice via the room
+3. **Avatar Generation**: LemonSlice generates synchronized avatar video and audio
+4. **Video Streaming**: Avatar video is streamed to call participants via GetStream Edge
+
+## Requirements
+
+- Python 3.10+
+- LemonSlice API key (get one at [lemonslice.com](https://lemonslice.com))
+- LiveKit server (cloud or self-hosted)
+- GetStream account for video calls
+- TTS provider (Cartesia, ElevenLabs, etc.) or Realtime LLM
+
+## License
+
+MIT
+
+## Links
+
+- [Documentation](https://visionagents.ai/)
+- [GitHub](https://github.com/GetStream/Vision-Agents)
+- [LemonSlice Docs](https://lemonslice.com/docs/self-managed/overview)

vision_agents_plugins_lemonslice-0.3.7/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vision-agents-plugins-lemonslice"
+dynamic = ["version"]
+description = "LemonSlice avatar plugin for Vision Agents"
+readme = "README.md"
+keywords = ["lemonslice", "avatars", "AI", "voice agents", "agents"]
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "vision-agents",
+    "livekit>=1.0.0",
+    "livekit-api>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Documentation = "https://visionagents.ai/"
+Website = "https://visionagents.ai/"
+Source = "https://github.com/GetStream/Vision-Agents"
+
+[tool.hatch.version]
+source = "vcs"
+raw-options = { root = "..", search_parent_directories = true, fallback_version = "0.0.0" }
+
+[tool.hatch.build.targets.wheel]
+packages = [".", "vision_agents"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/vision_agents"]
+
+[tool.uv.sources]
+vision-agents = { workspace = true }
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.1",
+    "pytest-asyncio>=1.0.0",
+]

vision_agents_plugins_lemonslice-0.3.7/vision_agents/plugins/lemonslice/__init__.py

@@ -0,0 +1,5 @@
+from .lemonslice_avatar_publisher import LemonSliceAvatarPublisher
+
+__all__ = [
+    "LemonSliceAvatarPublisher",
+]

vision_agents_plugins_lemonslice-0.3.7/vision_agents/plugins/lemonslice/exceptions.py

@@ -0,0 +1,10 @@
+class LemonSliceError(Exception):
+    """Base exception for LemonSlice API errors."""
+
+
+class LemonSliceSessionError(LemonSliceError):
+    """Raised when session creation or management fails."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        self.status_code = status_code
+        super().__init__(message)

vision_agents_plugins_lemonslice-0.3.7/vision_agents/plugins/lemonslice/lemonslice_avatar_publisher.py

@@ -0,0 +1,160 @@
+import asyncio
+import logging
+from typing import Any
+
+import av
+from getstream.video.rtc import audio_track
+from getstream.video.rtc.track_util import PcmData
+from vision_agents.core.llm.events import (
+    RealtimeAudioOutputDoneEvent,
+    RealtimeAudioOutputEvent,
+)
+from vision_agents.core.processors.base_processor import AudioPublisher, VideoPublisher
+from vision_agents.core.tts.events import TTSAudioEvent
+from vision_agents.core.utils.video_track import QueuedVideoTrack
+
+from .lemonslice_client import LemonSliceClient
+from .lemonslice_rtc_manager import LemonSliceRTCManager
+
+logger = logging.getLogger(__name__)
+
+
+class LemonSliceAvatarPublisher(AudioPublisher, VideoPublisher):
+    """LemonSlice avatar video and audio publisher.
+
+    Sends TTS audio to LemonSlice over LiveKit and receives synchronized
+    avatar video and audio back.
+
+    For standard LLMs: LemonSlice provides both video and audio.
+    For Realtime LLMs: LemonSlice provides video only; LLM provides audio.
+    """
+
+    name = "lemonslice_avatar"
+
+    def __init__(
+        self,
+        agent_id: str | None = None,
+        agent_image_url: str | None = None,
+        agent_prompt: str | None = None,
+        idle_timeout: int | None = None,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        livekit_url: str | None = None,
+        livekit_api_key: str | None = None,
+        livekit_api_secret: str | None = None,
+        width: int = 1920,
+        height: int = 1080,
+    ):
+        """Initialize the LemonSlice avatar publisher.
+
+        Args:
+            agent_id: LemonSlice agent ID.
+            agent_image_url: URL of the agent's avatar image.
+            agent_prompt: Prompt describing the agent's persona.
+            idle_timeout: Seconds before an idle session is closed.
+            api_key: LemonSlice API key. Uses LEMONSLICE_API_KEY env var if not provided.
+            base_url: LemonSlice API base URL override.
+            livekit_url: LiveKit server URL. Uses LIVEKIT_URL env var if not provided.
+            livekit_api_key: LiveKit API key. Uses LIVEKIT_API_KEY env var if not provided.
+            livekit_api_secret: LiveKit API secret. Uses LIVEKIT_API_SECRET env var if not provided.
+            width: Output video width in pixels.
+            height: Output video height in pixels.
+        """
+        client_kwargs: dict[str, Any] = {
+            "agent_id": agent_id,
+            "agent_image_url": agent_image_url,
+            "agent_prompt": agent_prompt,
+            "idle_timeout": idle_timeout,
+            "api_key": api_key,
+        }
+        if base_url is not None:
+            client_kwargs["base_url"] = base_url
+
+        self._client = LemonSliceClient(**client_kwargs)
+        self._rtc_manager = LemonSliceRTCManager(
+            on_video=self._on_video_frame,
+            on_audio=self._on_audio_frame,
+            on_disconnect=self._on_disconnect,
+            livekit_url=livekit_url,
+            livekit_api_key=livekit_api_key,
+            livekit_api_secret=livekit_api_secret,
+        )
+        self._video_track = QueuedVideoTrack(width=width, height=height)
+        self._audio_track = audio_track.AudioStreamTrack(
+            sample_rate=48000, channels=2, format="s16"
+        )
+
+        self._connected = False
+        self._agent: Any = None
+        self._send_lock = asyncio.Lock()
+
+        logger.debug(f"LemonSlice AvatarPublisher initialized ({width}x{height})")
+
+    def publish_video_track(self) -> QueuedVideoTrack:
+        return self._video_track
+
+    def publish_audio_track(self) -> audio_track.AudioStreamTrack:
+        return self._audio_track
+
+    def attach_agent(self, agent: Any) -> None:
+        self._agent = agent
+        self._subscribe_to_audio_events()
+
+    async def start(self) -> None:
+        """Connect to LemonSlice. Called by Agent via _apply("start") during join()."""
+        await self._connect()
+
+    async def close(self) -> None:
+        self._video_track.stop()
+        try:
+            await self._rtc_manager.close()
+        except Exception as exc:
+            logger.warning(f"Failed to close LemonSlice RTC manager: {exc}")
+        finally:
+            await self._client.close()
+            self._connected = False
+            logger.debug("LemonSlice avatar publisher closed")
+
+    def _subscribe_to_audio_events(self) -> None:
+        @self._agent.events.subscribe
+        async def on_tts_audio(event: TTSAudioEvent):
+            # Use the lock because TTS events arrive asynchronously
+            async with self._send_lock:
+                if event.data is not None:
+                    await self._rtc_manager.send_audio(event.data)
+                if event.is_final_chunk:
+                    await self._rtc_manager.flush()
+
+        @self._agent.events.subscribe
+        async def on_realtime_audio(event: RealtimeAudioOutputEvent):
+            async with self._send_lock:
+                if event.data is not None:
+                    await self._rtc_manager.send_audio(event.data)
+
+        @self._agent.events.subscribe
+        async def on_realtime_audio_done(_: RealtimeAudioOutputDoneEvent):
+            async with self._send_lock:
+                await self._rtc_manager.flush()
+
+    async def _connect(self) -> None:
+        credentials = self._rtc_manager.generate_credentials()
+        await self._rtc_manager.connect(credentials)
+        try:
+            await self._client.create_session(
+                credentials.livekit_url, credentials.livekit_token
+            )
+            self._connected = True
+            logger.info("LemonSlice avatar connection established")
+        except Exception:
+            logger.exception("Failed to create a LemonSlice session")
+            await self._rtc_manager.close()
+
+    async def _on_video_frame(self, frame: av.VideoFrame) -> None:
+        await self._video_track.add_frame(frame)
+
+    async def _on_audio_frame(self, pcm: PcmData) -> None:
+        await self._audio_track.write(pcm)
+
+    async def _on_disconnect(self) -> None:
+        logger.info("LemonSlice disconnected")
+        self._connected = False

vision_agents_plugins_lemonslice-0.3.7/vision_agents/plugins/lemonslice/lemonslice_client.py

@@ -0,0 +1,118 @@
+import logging
+from os import getenv
+
+import httpx
+
+from .exceptions import LemonSliceSessionError
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_BASE_URL = "https://lemonslice.com/api/liveai"
+
+
+class LemonSliceClient:
+    """REST API client for LemonSlice session management.
+
+    Handles authentication and session creation with LemonSlice's
+    self-managed API for real-time avatar generation.
+    """
+
+    def __init__(
+        self,
+        agent_id: str | None = None,
+        agent_image_url: str | None = None,
+        agent_prompt: str | None = None,
+        idle_timeout: int | None = None,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+    ):
+        """Initialize the LemonSlice client.
+
+        Args:
+            agent_id: LemonSlice agent ID.
+            agent_image_url: Custom agent image URL (368x560px recommended).
+            agent_prompt: Prompt influencing avatar expressions and movements.
+            idle_timeout: Session timeout in seconds.
+            api_key: LemonSlice API key. Uses LEMONSLICE_API_KEY env var if not provided.
+            base_url: LemonSlice API base URL.
+        """
+        if not agent_id and not agent_image_url:
+            raise ValueError("Either agent_id or agent_image_url must be provided.")
+
+        self._api_key: str = api_key or getenv("LEMONSLICE_API_KEY") or ""
+        if not self._api_key:
+            raise ValueError(
+                "LemonSlice API key required. Set LEMONSLICE_API_KEY environment "
+                "variable or pass api_key parameter."
+            )
+
+        self._agent_id = agent_id
+        self._agent_image_url = agent_image_url
+        self._agent_prompt = agent_prompt
+        self._idle_timeout = idle_timeout
+        self._session_id: str | None = None
+        self._http_client = httpx.AsyncClient(
+            base_url=base_url,
+            headers={
+                "X-API-Key": self._api_key,
+                "Content-Type": "application/json",
+            },
+        )
+
+    @property
+    def session_id(self) -> str | None:
+        return self._session_id
+
+    async def create_session(self, livekit_url: str, livekit_token: str) -> str:
+        """Create a new LemonSlice avatar session.
+
+        Args:
+            livekit_url: LiveKit server URL for the avatar to connect to.
+            livekit_token: LiveKit access token for the avatar participant.
+
+        Returns:
+            The created session ID.
+        """
+        payload: dict[str, object] = {
+            "transport_type": "livekit",
+            "properties": {
+                "livekit_url": livekit_url,
+                "livekit_token": livekit_token,
+            },
+        }
+
+        if self._agent_id:
+            payload["agent_id"] = self._agent_id
+        if self._agent_image_url:
+            payload["agent_image_url"] = self._agent_image_url
+        if self._agent_prompt:
+            payload["agent_prompt"] = self._agent_prompt
+        if self._idle_timeout is not None:
+            payload["idle_timeout"] = self._idle_timeout
+
+        response = await self._http_client.post("/sessions", json=payload)
+
+        if response.status_code != 201:
+            raise LemonSliceSessionError(
+                f"Failed to create session: {response.status_code} - {response.text}",
+                status_code=response.status_code,
+            )
+
+        data = response.json()
+        self._session_id = data.get("session_id")
+
+        if not self._session_id:
+            raise LemonSliceSessionError(
+                f"Session creation returned no session_id: {data}"
+            )
+
+        logger.info(f"LemonSlice session created: {self._session_id}")
+        return self._session_id
+
+    async def close(self) -> None:
+        """Clean up client resources."""
+        try:
+            await self._http_client.aclose()
+        finally:
+            self._session_id = None
+            logger.debug("LemonSlice client closed")

vision_agents_plugins_lemonslice-0.3.7/vision_agents/plugins/lemonslice/lemonslice_rtc_manager.py

@@ -0,0 +1,268 @@
+import asyncio
+import logging
+from dataclasses import dataclass
+from os import getenv
+from typing import Callable, Coroutine
+from uuid import uuid4
+
+import av
+from getstream.video.rtc.track_util import AudioFormat, PcmData
+from livekit import api, rtc
+from PIL import Image
+from vision_agents.core.utils.utils import cancel_and_wait
+
+logger = logging.getLogger(__name__)
+
+_AUDIO_STREAM_TOPIC = "lk.audio_stream"
+_AVATAR_IDENTITY = "avatar"
+_PLUGIN_IDENTITY = "plugin"
+_SAMPLE_RATE = 16000
+_NUM_CHANNELS = 1
+
+
+@dataclass(frozen=True)
+class ConnectionCredentials:
+    """All credentials needed for a LemonSlice LiveKit session."""
+
+    room_name: str
+    agent_token: str
+    livekit_url: str
+    livekit_token: str
+
+
+class LemonSliceRTCManager:
+    """Manages a LiveKit room connection for LemonSlice avatar streaming.
+
+    Creates a LiveKit room, sends TTS audio to LemonSlice via data streams,
+    and receives synchronized avatar video and audio tracks.
+    """
+
+    def __init__(
+        self,
+        on_video: Callable[[av.VideoFrame], Coroutine[None, None, None]],
+        on_audio: Callable[[PcmData], Coroutine[None, None, None]],
+        on_disconnect: Callable[[], Coroutine[None, None, None]],
+        livekit_url: str | None = None,
+        livekit_api_key: str | None = None,
+        livekit_api_secret: str | None = None,
+    ):
+        self._livekit_url = livekit_url or getenv("LIVEKIT_URL") or ""
+        if not self._livekit_url:
+            raise ValueError(
+                "LiveKit URL required. Set LIVEKIT_URL environment variable "
+                "or pass livekit_url parameter."
+            )
+
+        self._livekit_api_key = livekit_api_key or getenv("LIVEKIT_API_KEY") or ""
+        self._livekit_api_secret = (
+            livekit_api_secret or getenv("LIVEKIT_API_SECRET") or ""
+        )
+        if not self._livekit_api_key or not self._livekit_api_secret:
+            raise ValueError(
+                "LiveKit API key and secret required. Set LIVEKIT_API_KEY and "
+                "LIVEKIT_API_SECRET environment variables or pass them as parameters."
+            )
+
+        self._on_video = on_video
+        self._on_audio = on_audio
+        self._on_disconnect = on_disconnect
+
+        self._room: rtc.Room | None = None
+        self._stream_writer: rtc.ByteStreamWriter | None = None
+        self._connected = False
+        self._tasks: set[asyncio.Task[None]] = set()
+
+    @property
+    def is_connected(self) -> bool:
+        return self._connected
+
+    def generate_credentials(self) -> ConnectionCredentials:
+        """Generate credentials for a new LiveKit room session.
+
+        Returns:
+            Credentials for both the agent and the LemonSlice participant.
+        """
+        room_name = f"lemonslice-{uuid4()}"
+        agent_token = self._generate_token(room_name, _PLUGIN_IDENTITY, kind="agent")
+        lemonslice_token = self._generate_token(
+            room_name, _AVATAR_IDENTITY, kind="agent"
+        )
+        return ConnectionCredentials(
+            room_name=room_name,
+            agent_token=agent_token,
+            livekit_url=self._livekit_url,
+            livekit_token=lemonslice_token,
+        )
+
+    async def connect(self, credentials: ConnectionCredentials) -> None:
+        """Connect to a LiveKit room.
+
+        Args:
+            credentials: Connection credentials from generate_credentials().
+        """
+        room = rtc.Room()
+
+        @room.on("connected")
+        def on_connected():
+            logger.info("Room connected")
+
+        @room.on("participant_connected")
+        def on_participant_connected(participant: rtc.RemoteParticipant):
+            if participant.identity == _AVATAR_IDENTITY:
+                logger.info("LemonSlice avatar entered the room")
+
+        @room.on("track_subscribed")
+        def on_track_subscribed(
+            track: rtc.Track,
+            publication: rtc.RemoteTrackPublication,
+            participant: rtc.RemoteParticipant,
+        ) -> None:
+            if participant.identity == _AVATAR_IDENTITY:
+                if track.kind == rtc.TrackKind.KIND_VIDEO:
+                    logger.info("Received video track from LemonSlice")
+                    video_stream = rtc.VideoStream(track)
+                    self._create_task(self._consume_video(video_stream))
+                elif track.kind == rtc.TrackKind.KIND_AUDIO:
+                    logger.info("Received audio track from LemonSlice")
+                    audio_stream = rtc.AudioStream(
+                        track, sample_rate=48000, num_channels=2
+                    )
+                    self._create_task(self._consume_audio(audio_stream))
+
+        @room.on("participant_disconnected")
+        def on_participant_disconnected(participant: rtc.RemoteParticipant) -> None:
+            logger.info(
+                f"Participant disconnected: {participant.identity}; "
+                f"reason: {participant.disconnect_reason}"
+            )
+            self._connected = False
+            self._create_task(self._on_disconnect())
+            if self._room is not None:
+                self._create_task(self._room.disconnect())
+
+        @room.on("disconnected")
+        def on_disconnected(reason: str) -> None:
+            # The "disconnected" callback may be triggered multiple times
+            # because we disconnect ourselves when the avatar leaves the call.
+            if self._connected:
+                logger.info(f"Room disconnected; reason: {reason}")
+                self._connected = False
+                self._create_task(self._on_disconnect())
+
+        logger.info(f"Connecting to LiveKit room {credentials.room_name}")
+        await room.connect(self._livekit_url, credentials.agent_token)
+        logger.info(f"Connected to LiveKit room {credentials.room_name}")
+
+        room.local_participant.register_rpc_method(
+            "lk.playback_finished", self._rpc_on_playback_finished
+        )
+
+        self._room = room
+        self._connected = True
+
+    async def send_audio(self, pcm: PcmData) -> None:
+        """Send a PCM audio chunk to LemonSlice via a LiveKit byte stream.
+
+        Args:
+            pcm: Audio data to send. Resampled to 16 kHz mono automatically.
+        """
+        if self._room is None or not self._room.isconnected():
+            return
+
+        if pcm.sample_rate != _SAMPLE_RATE or pcm.channels != _NUM_CHANNELS:
+            pcm = pcm.resample(
+                target_sample_rate=_SAMPLE_RATE,
+                target_channels=_NUM_CHANNELS,
+            )
+
+        if self._stream_writer is None:
+            self._stream_writer = await self._room.local_participant.stream_bytes(
+                name=f"AUDIO_{uuid4()}",
+                topic=_AUDIO_STREAM_TOPIC,
+                destination_identities=[_AVATAR_IDENTITY],
+                attributes={
+                    "sample_rate": str(pcm.sample_rate),
+                    "num_channels": str(pcm.channels),
+                },
+            )
+            logger.debug("Opened audio byte stream to LemonSlice")
+
+        await self._stream_writer.write(pcm.to_bytes())
+
+    async def flush(self) -> None:
+        """Close the current byte stream, signalling end of a TTS segment."""
+        if self._stream_writer is not None:
+            await self._stream_writer.aclose()
+            self._stream_writer = None
+            logger.debug("Closed audio byte stream (segment end)")
+
+    async def close(self) -> None:
+        """Disconnect from the LiveKit room and clean up resources."""
+        try:
+            if self._stream_writer is not None:
+                await self._stream_writer.aclose()
+
+            await cancel_and_wait(*self._tasks)
+            self._tasks.clear()
+
+            if self._room is not None:
+                await self._room.disconnect()
+        finally:
+            self._room = None
+            self._stream_writer = None
+            self._connected = False
+            logger.debug("LemonSlice RTC manager closed")
+
+    async def _consume_video(self, video_stream: rtc.VideoStream) -> None:
+        async for event in video_stream:
+            lk_frame = event.frame.convert(rtc.VideoBufferType.RGBA)
+            img = Image.frombuffer(
+                "RGBA", (lk_frame.width, lk_frame.height), lk_frame.data
+            )
+            frame = av.VideoFrame.from_image(img)
+            await self._on_video(frame)
+
+    async def _consume_audio(self, audio_stream: rtc.AudioStream) -> None:
+        async for event in audio_stream:
+            frame = event.frame
+            pcm = PcmData.from_bytes(
+                frame.data,  # type: ignore[arg-type]
+                sample_rate=frame.sample_rate,
+                format=AudioFormat.S16,
+                channels=frame.num_channels,
+            )
+            await self._on_audio(pcm)
+
+    def _rpc_on_playback_finished(self, data: rtc.RpcInvocationData) -> str:
+        logger.info(
+            "playback finished event received",
+            extra={"caller_identity": data.caller_identity},
+        )
+        return "ok"
+
+    def _generate_token(
+        self,
+        room_name: str,
+        identity: str,
+        kind: api.AccessToken.ParticipantKind,
+    ) -> str:
+        token = (
+            api.AccessToken(self._livekit_api_key, self._livekit_api_secret)
+            .with_kind(kind)
+            .with_identity(identity)
+            .with_name(identity)
+            .with_grants(
+                api.VideoGrants(
+                    room_join=True,
+                    room=room_name,
+                    can_publish=True,
+                    can_subscribe=True,
+                )
+            )
+        )
+        return token.to_jwt()
+
+    def _create_task(self, coro: Coroutine[None, None, None]) -> None:
+        task: asyncio.Task[None] = asyncio.create_task(coro)
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)