elevenagents-livekit-plugin 0.1.0__tar.gz

elevenagents_livekit_plugin-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: elevenagents-livekit-plugin
+Version: 0.1.0
+Summary: Bridge between LiveKit Agents and ElevenAgents Voice Orchestration
+Requires-Python: >=3.10
+Requires-Dist: livekit>=1.0.0
+Requires-Dist: livekit-api>=1.0.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.20.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"

elevenagents_livekit_plugin-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "elevenagents-livekit-plugin"
+version = "0.1.0"
+description = "Bridge between LiveKit Agents and ElevenAgents Voice Orchestration"
+requires-python = ">=3.10"
+dependencies = [
+    "livekit>=1.0.0",
+    "livekit-api>=1.0.0",
+    "fastapi>=0.100.0",
+    "uvicorn>=0.20.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

elevenagents_livekit_plugin-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

elevenagents_livekit_plugin-0.1.0/src/elevenagents_livekit_plugin/__init__.py

@@ -0,0 +1,5 @@
+from .bridge import ElevenAgentsBridge
+from .tools import elevenagents_tools
+
+__all__ = ["ElevenAgentsBridge", "elevenagents_tools"]
+__version__ = "0.1.0"

elevenagents_livekit_plugin-0.1.0/src/elevenagents_livekit_plugin/adapter.py

@@ -0,0 +1,93 @@
+"""Converts LiveKit text chunks and tool calls into OpenAI-compatible SSE format."""
+
+import json
+import time
+import uuid
+
+
+def _make_id() -> str:
+    return f"chatcmpl-{uuid.uuid4().hex[:12]}"
+
+
+def format_chunk(content: str, model: str = "livekit-agent") -> str:
+    """Format a text chunk as an OpenAI chat completion SSE chunk."""
+    chunk = {
+        "id": _make_id(),
+        "object": "chat.completion.chunk",
+        "created": int(time.time()),
+        "model": model,
+        "choices": [
+            {
+                "index": 0,
+                "delta": {"content": content},
+                "finish_reason": None,
+            }
+        ],
+    }
+    return f"data: {json.dumps(chunk)}\n\n"
+
+
+def format_first_chunk(model: str = "livekit-agent") -> str:
+    """Format the initial SSE chunk with the role."""
+    chunk = {
+        "id": _make_id(),
+        "object": "chat.completion.chunk",
+        "created": int(time.time()),
+        "model": model,
+        "choices": [
+            {
+                "index": 0,
+                "delta": {"role": "assistant", "content": ""},
+                "finish_reason": None,
+            }
+        ],
+    }
+    return f"data: {json.dumps(chunk)}\n\n"
+
+
+def format_tool_call(tool_name: str, tool_args: dict, model: str = "livekit-agent") -> str:
+    """Format a tool call as an OpenAI chat completion SSE chunk."""
+    chunk = {
+        "id": _make_id(),
+        "object": "chat.completion.chunk",
+        "created": int(time.time()),
+        "model": model,
+        "choices": [
+            {
+                "index": 0,
+                "delta": {
+                    "tool_calls": [
+                        {
+                            "index": 0,
+                            "id": f"call_{uuid.uuid4().hex[:8]}",
+                            "type": "function",
+                            "function": {
+                                "name": tool_name,
+                                "arguments": json.dumps(tool_args),
+                            },
+                        }
+                    ]
+                },
+                "finish_reason": None,
+            }
+        ],
+    }
+    return f"data: {json.dumps(chunk)}\n\n"
+
+
+def format_done_chunk(model: str = "livekit-agent") -> str:
+    """Format the final SSE chunk with finish_reason=stop."""
+    chunk = {
+        "id": _make_id(),
+        "object": "chat.completion.chunk",
+        "created": int(time.time()),
+        "model": model,
+        "choices": [
+            {
+                "index": 0,
+                "delta": {},
+                "finish_reason": "stop",
+            }
+        ],
+    }
+    return f"data: {json.dumps(chunk)}\n\ndata: [DONE]\n\n"

elevenagents_livekit_plugin-0.1.0/src/elevenagents_livekit_plugin/bridge.py

@@ -0,0 +1,83 @@
+"""Main entry point — wires up the LiveKit client and HTTP server."""
+
+import asyncio
+import logging
+import os
+
+import uvicorn
+from dotenv import load_dotenv
+
+from .livekit_client import LiveKitClient
+from .server import create_app
+
+logger = logging.getLogger("elevenagents-livekit-plugin")
+
+
+class ElevenAgentsBridge:
+    def __init__(
+        self,
+        *,
+        livekit_url: str | None = None,
+        api_key: str | None = None,
+        api_secret: str | None = None,
+        room_name: str = "elevenagents-bridge",
+        identity: str = "elevenagents-bridge",
+        port: int = 8013,
+        host: str = "0.0.0.0",
+        buffer_words: str = "... ",
+    ):
+        load_dotenv()
+
+        self.livekit_url = livekit_url or os.getenv("LIVEKIT_URL", "")
+        self.api_key = api_key or os.getenv("LIVEKIT_API_KEY", "")
+        self.api_secret = api_secret or os.getenv("LIVEKIT_API_SECRET", "")
+        self.room_name = room_name
+        self.identity = identity
+        self.port = port
+        self.host = host
+
+        if not all([self.livekit_url, self.api_key, self.api_secret]):
+            raise ValueError(
+                "LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET must be "
+                "set via arguments or environment variables."
+            )
+
+        self.lk_client = LiveKitClient(
+            url=self.livekit_url,
+            api_key=self.api_key,
+            api_secret=self.api_secret,
+            room_name=self.room_name,
+            identity=self.identity,
+        )
+        self.app = create_app(self.lk_client, buffer_words=buffer_words)
+
+    def run(self) -> None:
+        """Start the bridge (blocking)."""
+        asyncio.run(self._run())
+
+    async def _run(self) -> None:
+        # Connect to LiveKit room
+        await self.lk_client.connect()
+        logger.info(
+            "Bridge connected to LiveKit at %s, room '%s'",
+            self.livekit_url,
+            self.room_name,
+        )
+
+        # Start HTTP server
+        config = uvicorn.Config(
+            self.app, host=self.host, port=self.port, log_level="info"
+        )
+        server = uvicorn.Server(config)
+
+        logger.info("Starting server on %s:%d", self.host, self.port)
+        logger.info(
+            "ElevenLabs custom LLM endpoint: http://%s:%d/v1",
+            self.host,
+            self.port,
+        )
+
+        try:
+            await server.serve()
+        finally:
+            await self.lk_client.disconnect()

elevenagents_livekit_plugin-0.1.0/src/elevenagents_livekit_plugin/livekit_client.py

@@ -0,0 +1,190 @@
+"""Connects to a LiveKit room and relays text to/from the agent."""
+
+import asyncio
+import datetime
+import json
+import logging
+from dataclasses import dataclass
+from typing import AsyncGenerator, Optional
+
+from livekit.api import AccessToken, LiveKitAPI, VideoGrants
+from livekit.protocol import agent_dispatch
+from livekit.rtc import Room, TextStreamReader
+
+from .tools import TOOL_SIGNAL_PREFIX
+
+logger = logging.getLogger("elevenagents-livekit-plugin.client")
+
+
+@dataclass
+class StreamEvent:
+    """An event in the response stream — either a text chunk or a tool call."""
+
+    type: str  # "text" or "tool_call"
+    content: str = ""
+    tool_name: str = ""
+    tool_args: dict = None
+
+    def __post_init__(self):
+        if self.tool_args is None:
+            self.tool_args = {}
+
+
+class LiveKitClient:
+    def __init__(
+        self,
+        url: str,
+        api_key: str,
+        api_secret: str,
+        room_name: str = "elevenagents-bridge",
+        identity: str = "elevenagents-bridge",
+    ):
+        self.url = url
+        self.api_key = api_key
+        self.api_secret = api_secret
+        self.room_name = room_name
+        self.identity = identity
+        self.room: Optional[Room] = None
+        self._response_queue: asyncio.Queue[Optional[StreamEvent]] = asyncio.Queue()
+        self._connected = False
+
+    def _generate_token(self) -> str:
+        token = AccessToken(
+            api_key=self.api_key,
+            api_secret=self.api_secret,
+        )
+        token.with_identity(self.identity)
+        token.with_grants(
+            VideoGrants(
+                room_join=True,
+                room=self.room_name,
+                can_publish=True,
+                can_subscribe=True,
+            )
+        )
+        token.with_ttl(datetime.timedelta(hours=24))
+        return token.to_jwt()
+
+    async def connect(self) -> None:
+        """Connect to the LiveKit room and register text stream handlers."""
+        self.room = Room()
+
+        def on_stream(reader: TextStreamReader, participant_identity: str) -> None:
+            # Skip our own messages (echo from send_text)
+            if participant_identity == self.identity:
+                return
+            logger.debug("Stream from %s", participant_identity)
+            asyncio.ensure_future(self._handle_stream(reader))
+
+        self.room.register_text_stream_handler("lk.chat", on_stream)
+        self.room.register_text_stream_handler("lk.transcription", on_stream)
+
+        token = self._generate_token()
+        await self.room.connect(self.url, token)
+        self._connected = True
+        logger.info(
+            "Connected to room '%s' as '%s'", self.room_name, self.identity
+        )
+        await self._dispatch_agent()
+
+    async def _dispatch_agent(self) -> None:
+        """Dispatch a LiveKit agent to join this room."""
+        http_url = self.url.replace("ws://", "http://").replace("wss://", "https://")
+        api = LiveKitAPI(http_url, self.api_key, self.api_secret)
+        try:
+            await api.agent_dispatch.create_dispatch(
+                agent_dispatch.CreateAgentDispatchRequest(room=self.room_name)
+            )
+            logger.info("Dispatched agent to room '%s'", self.room_name)
+        except Exception as e:
+            logger.warning("Failed to dispatch agent: %s", e)
+        finally:
+            await api.aclose()
+
+    async def _handle_stream(self, reader: TextStreamReader) -> None:
+        """Handle a text stream — detect tool signals, otherwise stream text."""
+        first = True
+        is_tool = False
+        tool_chunks: list[str] = []
+
+        async for chunk in reader:
+            if first:
+                first = False
+                if chunk.startswith(TOOL_SIGNAL_PREFIX):
+                    is_tool = True
+                    tool_chunks.append(chunk)
+                    continue
+
+            if is_tool:
+                tool_chunks.append(chunk)
+            else:
+                await self._response_queue.put(
+                    StreamEvent(type="text", content=chunk)
+                )
+
+        if is_tool:
+            full = "".join(tool_chunks)
+            json_str = full[len(TOOL_SIGNAL_PREFIX):]
+            try:
+                data = json.loads(json_str)
+                tool_name = data.pop("tool")
+                await self._response_queue.put(
+                    StreamEvent(type="tool_call", tool_name=tool_name, tool_args=data)
+                )
+                logger.info("Tool call: %s", tool_name)
+            except (json.JSONDecodeError, KeyError) as e:
+                logger.warning("Bad tool signal: %s", e)
+        else:
+            # Text stream done
+            await self._response_queue.put(None)
+
+    async def _ensure_agent_in_room(self) -> None:
+        """Re-dispatch agent if none present."""
+        for p in self.room.remote_participants.values():
+            if p.kind == 4:
+                return
+        logger.info("No agent in room, re-dispatching...")
+        await self._dispatch_agent()
+        for _ in range(20):
+            await asyncio.sleep(0.5)
+            for p in self.room.remote_participants.values():
+                if p.kind == 4:
+                    logger.info("Agent joined: %s", p.identity)
+                    return
+        logger.warning("Agent did not join after re-dispatch")
+
+    async def send_and_stream(
+        self, text: str, timeout: float = 30.0, tool_wait: float = 0.5
+    ) -> AsyncGenerator[StreamEvent, None]:
+        """Send text to the agent and yield streamed response events."""
+        if not self._connected or self.room is None:
+            raise RuntimeError("Not connected to LiveKit room")
+
+        await self._ensure_agent_in_room()
+
+        # Drain stale events
+        while not self._response_queue.empty():
+            self._response_queue.get_nowait()
+
+        await self.room.local_participant.send_text(text, topic="lk.chat")
+        logger.info("Sent: %s", text[:100])
+
+        text_done = False
+        while True:
+            try:
+                wait = tool_wait if text_done else timeout
+                event = await asyncio.wait_for(
+                    self._response_queue.get(), timeout=wait
+                )
+            except asyncio.TimeoutError:
+                break
+            if event is None:
+                text_done = True
+                continue
+            yield event
+
+    async def disconnect(self) -> None:
+        if self.room:
+            await self.room.disconnect()
+            self._connected = False
+            logger.info("Disconnected from room")

elevenagents_livekit_plugin-0.1.0/src/elevenagents_livekit_plugin/server.py

@@ -0,0 +1,92 @@
+"""FastAPI server exposing an OpenAI-compatible /v1/chat/completions endpoint."""
+
+import json
+import logging
+
+import fastapi
+from fastapi.responses import StreamingResponse
+
+from .adapter import format_chunk, format_done_chunk, format_first_chunk, format_tool_call
+from .livekit_client import LiveKitClient
+
+logging.basicConfig(level=logging.DEBUG)
+logger = logging.getLogger("elevenagents-livekit-plugin.server")
+
+
+def extract_text(content) -> str:
+    """Extract text from content that may be a string or a list of content parts."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for part in content:
+            if isinstance(part, dict) and part.get("type") == "text":
+                parts.append(part.get("text", ""))
+            elif isinstance(part, str):
+                parts.append(part)
+        return " ".join(parts)
+    return str(content) if content else ""
+
+
+DEFAULT_BUFFER_WORDS = "... "
+
+
+def create_app(lk_client: LiveKitClient, buffer_words: str = DEFAULT_BUFFER_WORDS) -> fastapi.FastAPI:
+    app = fastapi.FastAPI(title="ElevenAgents LiveKit Plugin")
+
+    @app.post("/v1/chat/completions")
+    async def chat_completions(request: fastapi.Request) -> StreamingResponse:
+        body = await request.json()
+        logger.debug("Incoming request body: %s", json.dumps(body, indent=2))
+
+        messages = body.get("messages", [])
+        if not messages:
+            return fastapi.responses.JSONResponse(
+                {"error": "No messages provided"}, status_code=400
+            )
+
+        # Extract the latest user message (content can be string or list)
+        user_message = None
+        for msg in reversed(messages):
+            if msg.get("role") == "user":
+                user_message = extract_text(msg.get("content", ""))
+                break
+
+        if not user_message:
+            return fastapi.responses.JSONResponse(
+                {"error": "No user message found"}, status_code=400
+            )
+
+        logger.debug("Extracted user message: %s", user_message)
+        model = body.get("model", "livekit-agent")
+
+        async def event_stream():
+            yield format_first_chunk(model)
+            # Send buffer words immediately so ElevenLabs doesn't time out
+            if buffer_words:
+                yield format_chunk(buffer_words, model)
+            try:
+                async for event in lk_client.send_and_stream(user_message):
+                    if event.type == "text":
+                        yield format_chunk(event.content, model)
+                    elif event.type == "tool_call":
+                        yield format_tool_call(
+                            event.tool_name, event.tool_args, model
+                        )
+                        logger.info(
+                            "Forwarding tool call to ElevenLabs: %s",
+                            event.tool_name,
+                        )
+                yield format_done_chunk(model)
+            except Exception as e:
+                logger.error("Error streaming response: %s", str(e))
+                yield format_chunk(f"Error: {str(e)}", model)
+                yield format_done_chunk(model)
+
+        return StreamingResponse(event_stream(), media_type="text/event-stream")
+
+    @app.get("/health")
+    async def health():
+        return {"status": "ok", "connected": lk_client._connected}
+
+    return app

elevenagents_livekit_plugin-0.1.0/src/elevenagents_livekit_plugin/tools.py

@@ -0,0 +1,99 @@
+"""
+Pre-built ElevenLabs tools for LiveKit agents.
+
+Usage:
+    from elevenagents_livekit_plugin import elevenagents_tools
+
+    class MyAgent(Agent):
+        def __init__(self):
+            super().__init__(
+                instructions="...",
+                tools=[*elevenagents_tools()],
+            )
+
+When the agent's LLM calls these tools, they signal back to the bridge
+via the lk.chat TextStream topic. The bridge picks up the signal and
+includes the tool call in the SSE response back to ElevenLabs Voice Engine.
+"""
+
+import json
+import logging
+
+from livekit.agents import RunContext, function_tool
+
+logger = logging.getLogger("elevenagents-livekit-plugin.tools")
+
+TOOL_SIGNAL_PREFIX = "__ELEVENAGENTS_TOOL__:"
+
+
+async def _send_tool_signal(ctx: RunContext, tool_name: str, args: dict) -> None:
+    """Send a tool call signal to the bridge via TextStream on lk.chat topic."""
+    room = ctx.session.room_io.room
+    payload = TOOL_SIGNAL_PREFIX + json.dumps({"tool": tool_name, **args})
+    await room.local_participant.send_text(payload, topic="lk.chat")
+    logger.info("Sent tool signal: %s", tool_name)
+
+
+@function_tool(name="end_call")
+async def _end_call(
+    ctx: RunContext, reason: str, system__message_to_speak: str = ""
+) -> str:
+    """End the current voice call. Call this when:
+    1. The user says goodbye or wants to end the conversation.
+    2. The main task has been completed and the user is satisfied.
+    3. The conversation has reached a natural conclusion.
+
+    Args:
+        reason: Why the call is ending.
+        system__message_to_speak: A farewell message to speak before ending.
+    """
+    await _send_tool_signal(
+        ctx,
+        "end_call",
+        {"reason": reason, "system__message_to_speak": system__message_to_speak},
+    )
+    return system__message_to_speak if system__message_to_speak else "Ending the call."
+
+
+@function_tool(name="skip_turn")
+async def _skip_turn(ctx: RunContext, reason: str = "") -> str:
+    """Skip the agent's turn and wait silently for the user to speak.
+    Call this when the user says they need a moment to think, are
+    looking something up, or otherwise need a pause.
+
+    Args:
+        reason: Why the pause is needed.
+    """
+    await _send_tool_signal(ctx, "skip_turn", {"reason": reason})
+    return ""
+
+
+@function_tool(name="language_detection")
+async def _language_detection(ctx: RunContext, reason: str, language: str) -> str:
+    """Switch the conversation language. ONLY call this tool by itself with
+    NO text response. ONLY call ONCE when the user FIRST speaks in a different
+    language or explicitly requests a language change. Do NOT call again if you
+    are already responding in the target language.
+
+    Args:
+        reason: Why the language switch is needed.
+        language: The language code to switch to (e.g. 'es', 'fr', 'de', 'ja').
+    """
+    await _send_tool_signal(
+        ctx, "language_detection", {"reason": reason, "language": language}
+    )
+    return ""
+
+
+def elevenagents_tools() -> list:
+    """Return all ElevenLabs tools for use in a LiveKit agent.
+
+    Example:
+        class MyAgent(Agent):
+            def __init__(self):
+                super().__init__(
+                    instructions="You are a helpful assistant.",
+                    tools=[*elevenagents_tools()],
+                )
+    """
+    return [_end_call, _skip_turn, _language_detection]

elevenagents_livekit_plugin-0.1.0/src/elevenagents_livekit_plugin.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: elevenagents-livekit-plugin
+Version: 0.1.0
+Summary: Bridge between LiveKit Agents and ElevenAgents Voice Orchestration
+Requires-Python: >=3.10
+Requires-Dist: livekit>=1.0.0
+Requires-Dist: livekit-api>=1.0.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.20.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"

elevenagents_livekit_plugin-0.1.0/src/elevenagents_livekit_plugin.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+pyproject.toml
+src/elevenagents_livekit_plugin/__init__.py
+src/elevenagents_livekit_plugin/adapter.py
+src/elevenagents_livekit_plugin/bridge.py
+src/elevenagents_livekit_plugin/livekit_client.py
+src/elevenagents_livekit_plugin/server.py
+src/elevenagents_livekit_plugin/tools.py
+src/elevenagents_livekit_plugin.egg-info/PKG-INFO
+src/elevenagents_livekit_plugin.egg-info/SOURCES.txt
+src/elevenagents_livekit_plugin.egg-info/dependency_links.txt
+src/elevenagents_livekit_plugin.egg-info/requires.txt
+src/elevenagents_livekit_plugin.egg-info/top_level.txt

elevenagents_livekit_plugin-0.1.0/src/elevenagents_livekit_plugin.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

elevenagents_livekit_plugin-0.1.0/src/elevenagents_livekit_plugin.egg-info/requires.txt

@@ -0,0 +1,9 @@
+livekit>=1.0.0
+livekit-api>=1.0.0
+fastapi>=0.100.0
+uvicorn>=0.20.0
+python-dotenv>=1.0.0
+
+[dev]
+pytest
+pytest-asyncio

elevenagents_livekit_plugin-0.1.0/src/elevenagents_livekit_plugin.egg-info/top_level.txt

@@ -0,0 +1 @@
+elevenagents_livekit_plugin