cartesia-line 0.0.1__py3-none-any.whl

line/voice_agent_app.py

@@ -0,0 +1,147 @@
+from datetime import datetime, timezone
+import json
+import logging
+import os
+from typing import Awaitable, Callable, Optional
+from urllib.parse import urlencode
+
+from dotenv import load_dotenv
+from fastapi import FastAPI, HTTPException, Request, WebSocket, WebSocketDisconnect
+import uvicorn
+
+from line.call_request import CallRequest, PreCallResult
+from line.voice_agent_system import VoiceAgentSystem
+
+# Load environment variables from .env file
+load_dotenv()
+
+logger = logging.getLogger(__name__)
+
+
+class VoiceAgentApp:
+    """
+    VoiceAgentApp (name tbd) abstracts away the HTTP and websocket handling,
+    which should be invisible to developers, because this transport may change
+    in the future (eg to WebRTC).
+    """
+
+    def __init__(
+        self,
+        call_handler,
+        pre_call_handler: Optional[Callable[[CallRequest], Awaitable[Optional[PreCallResult]]]] = None,
+    ):
+        self.fastapi_app = FastAPI()
+        self.call_handler = call_handler
+        self.pre_call_handler = pre_call_handler
+        self.ws_route = "/ws"
+
+        self.fastapi_app.add_api_route("/chats", self.create_chat_session, methods=["POST"])
+        self.fastapi_app.add_api_route("/status", self.get_status, methods=["GET"])
+        self.fastapi_app.add_websocket_route(self.ws_route, self.websocket_endpoint)
+
+    async def create_chat_session(self, request: Request) -> dict:
+        """Create a new chat session and return the websocket URL."""
+        # Parse JSON body
+        body = await request.json()
+
+        # Create initial CallRequest
+        call_request = CallRequest(
+            call_id=body.get("call_id", "unknown"),
+            from_=body.get("from_", "unknown"),
+            to=body.get("to", "unknown"),
+            agent_call_id=body.get("agent_call_id", body.get("call_id", "unknown")),
+            metadata=body.get("metadata", {}),
+        )
+
+        # Run pre-call handler if provided
+        config = None
+        if self.pre_call_handler:
+            try:
+                result = await self.pre_call_handler(call_request)
+                if result is None:
+                    raise HTTPException(status_code=403, detail="Call rejected")
+
+                # Update call_request metadata with result
+                call_request.metadata.update(result.metadata)
+                config = result.config
+
+            except HTTPException:
+                raise
+            except Exception as e:
+                logger.error(f"Error in pre_call_handler: {str(e)}")
+                raise HTTPException(status_code=500, detail="Server error in call processing") from e
+
+        # Create URL parameters from processed call_request
+        url_params = {
+            "call_id": call_request.call_id,
+            "from": call_request.from_,
+            "to": call_request.to,
+            "agent_call_id": call_request.agent_call_id,
+            "metadata": json.dumps(call_request.metadata),  # JSON encode metadata
+        }
+
+        # Build websocket URL with parameters
+        query_string = urlencode(url_params)
+        websocket_url = f"{self.ws_route}?{query_string}"
+
+        response = {"websocket_url": websocket_url}
+        if config:
+            response["config"] = config
+        return response
+
+    async def get_status(self) -> dict:
+        """Status endpoint that returns OK if the server is running."""
+        logger.info("Health check endpoint called - voice agent is ready 🤖✅")
+        return {
+            "status": "ok",
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "service": "cartesia-line",
+        }
+
+    async def websocket_endpoint(self, websocket: WebSocket):
+        """Websocket endpoint that manages the complete call lifecycle."""
+        await websocket.accept()
+        logger.info("Client connected")
+
+        # Parse query parameters from WebSocket URL
+        query_params = dict(websocket.query_params)
+
+        # Parse metadata JSON
+        metadata = {}
+        if "metadata" in query_params:
+            try:
+                metadata = json.loads(query_params["metadata"])
+            except (json.JSONDecodeError, TypeError):
+                logger.warning(f"Invalid metadata JSON: {query_params['metadata']}")
+                metadata = {}
+
+        # Create CallRequest from URL parameters
+        call_request = CallRequest(
+            call_id=query_params.get("call_id", "unknown"),
+            from_=query_params.get("from", "unknown"),
+            to=query_params.get("to", "unknown"),
+            agent_call_id=query_params.get("agent_call_id", "unknown"),
+            metadata=metadata,
+        )
+
+        system = VoiceAgentSystem(websocket)
+
+        try:
+            # Handler configures nodes and bridges, then starts system
+            await self.call_handler(system, call_request)
+        except WebSocketDisconnect:
+            logger.info("Client disconnected")
+        except Exception as e:
+            logger.exception(f"Error: {str(e)}")
+            try:
+                await system.harness.send_error("System has encountered an error, please try again later.")
+                await system.harness.end_call()
+            except:  # noqa: E722
+                pass
+        finally:
+            await system.cleanup()
+
+    def run(self, host="0.0.0.0", port=None):
+        """Run the voice agent server."""
+        port = port or int(os.getenv("PORT", 8000))
+        uvicorn.run(self.fastapi_app, host=host, port=port)

line/voice_agent_system.py

@@ -0,0 +1,230 @@
+"""
+VoiceAgentSystem
+
+A utility for building voice agent systems.
+
+- Manages bus and harness setup automatically.
+- Lets you add and customize components easily.
+"""
+
+import sys
+from typing import Dict, Optional
+
+from loguru import logger
+
+from line.bridge import Bridge
+from line.bus import Bus, Message
+from line.events import AgentResponse
+from line.harness import ConversationHarness
+from line.nodes.reasoning import ReasoningNode
+from line.user_bridge import create_user_bridge
+
+# Configure logging to filter out DEBUG messages from line modules
+logger.configure(
+    handlers=[
+        {
+            "sink": sys.stderr,
+            "filter": lambda record: not (
+                record["name"].startswith("line") and record["level"].name == "DEBUG"
+            ),
+        }
+    ]
+)
+
+
+class VoiceAgentSystem:
+    """
+    System builder for voice agent applications.
+
+    Automatically manages Bus and ConversationHarness lifecycle
+    while providing fluent API for adding bridges and components.
+    """
+
+    def __init__(self, websocket):
+        """
+        Create voice agent system with websocket.
+
+        Args:
+            websocket: FastAPI WebSocket connection for voice communication.
+        """
+        self.websocket = websocket
+        self.bus = Bus()
+        self.harness = ConversationHarness(websocket, self.bus.shutdown_event)
+        self.bridges: Dict[str, Bridge] = {}
+        self.components = {}  # Store nodes and other components.
+        self.authorized_node = None
+        self.main_node: Optional[ReasoningNode] = None  # Track the main reasoning node.
+
+        self._add_logging_bridge()
+
+    def _add_logging_bridge(self):
+        """Add a bridge that logs all messages to the console."""
+        bridge = Bridge("logging")
+
+        def log_message(msg):
+            logger.debug(f"Logger Bridge:\n\n{msg}")
+
+        bridge.on("*").map(log_message)
+        self.bridges["logging"] = bridge
+
+    def _setup_authorized_infrastructure(self, authorized_node: str):
+        """Setup user bridge for the authorized agent."""
+
+        # Auto-add user bridge for WebSocket communication.
+        user_bridge = create_user_bridge(self.harness, authorized_node)
+        self.bridges["user"] = user_bridge
+
+    def with_node(self, node: ReasoningNode, bridge: Optional[Bridge] = None):
+        """
+        Add reasoning node and optional bridge.
+
+        Args:
+            name: Node identifier.
+            node: Reasoning node instance.
+            bridge: Optional NodeBridge instance for the node.
+
+        Returns:
+            Self for method chaining.
+        """
+        self.components[node.id] = node
+
+        # Track the main/authorized node.
+        if self.authorized_node == node.id:
+            self.main_node = node
+        if bridge:
+            self.with_bridge(node.id, bridge)
+        return self
+
+    def with_speaking_node(self, node: ReasoningNode, bridge: Bridge) -> "VoiceAgentSystem":
+        """
+        Add the speaking reasoning node and optional bridge, setting it as the authorized agent.
+
+        Args:
+            node: Reasoning node instance.
+            bridge: Optional NodeBridge instance for the speaking node.
+
+        Returns:
+            Self for method chaining.
+        """
+        if self.authorized_node is None:
+            self.authorized_node = bridge.node_id
+            self._setup_authorized_infrastructure(authorized_node=bridge.node_id)
+            logger.info(f"VoiceAgentSystem: Set authorized agent to '{bridge.node_id}'")
+        elif self.authorized_node != bridge.node_id:
+            logger.warning(
+                f"VoiceAgentSystem: Authorized agent already set to '{self.authorized_node}', "
+                f"ignoring '{bridge.node_id}'"
+            )
+
+        result = self.with_node(node)
+        if bridge:
+            result = result.with_bridge(bridge.node_id, bridge)
+        return result
+
+    def with_main_bridge(self, bridge: Bridge) -> "VoiceAgentSystem":
+        """
+        Add the main bridge using the authorized agent name.
+
+        Args:
+            bridge: Configured NodeBridge instance.
+
+        Returns:
+            Self for method chaining.
+        """
+        if self.authorized_node is None:
+            raise ValueError("Must call with_main_node() before with_main_bridge()")
+        return self.with_bridge(self.authorized_node, bridge)
+
+    def with_bridge(self, name: str, bridge: Bridge) -> "VoiceAgentSystem":
+        """
+        Add bridge to the system.
+
+        Args:
+            name: Bridge identifier for bus registration.
+            bridge: Configured NodeBridge instance.
+
+        Returns:
+            Self for method chaining.
+        """
+        self.bridges[name] = bridge
+        return self
+
+    async def start(self):
+        """Start the voice agent system."""
+
+        # Register all bridges quietly first
+        for name, bridge in self.bridges.items():
+            logger.debug(f"VoiceAgentSystem: Registering bridge '{name}'")
+            self.bus.register_bridge(name, bridge)
+
+        # Initialize all reasoning nodes quietly
+        for name, component in self.components.items():
+            if hasattr(component, "start"):
+                logger.debug(f"VoiceAgentSystem: Starting component '{name}'")
+                await component.start()
+
+        # Start bus (which will show the summary) then other components
+        await self.bus.start()
+        await self.harness.start()
+
+        # Start all bridges quietly
+        for _, bridge in self.bridges.items():
+            await bridge.start()
+
+        logger.info("VoiceAgentSystem: All components started successfully")
+
+    async def cleanup(self):
+        """Clean shutdown of the voice agent system."""
+        logger.info("VoiceAgentSystem: Starting system cleanup")
+
+        # Stop bridges first.
+        logger.debug(f"VoiceAgentSystem: Stopping {len(self.bridges)} bridges")
+        for name, bridge in self.bridges.items():
+            logger.debug(f"VoiceAgentSystem: Stopping bridge '{name}'")
+            try:
+                await bridge.stop()
+            except Exception as e:
+                logger.error(f"VoiceAgentSystem: Error stopping bridge '{name}': {e}")
+                raise e
+
+        # Cleanup reasoning nodes.
+        logger.debug(f"VoiceAgentSystem: Cleaning up {len(self.components)} components")
+        for name, component in self.components.items():
+            if hasattr(component, "cleanup"):
+                logger.debug(f"VoiceAgentSystem: Cleaning up component '{name}'")
+                await component.cleanup()
+
+        # Then stop infrastructure.
+        logger.debug("VoiceAgentSystem: Cleaning up ConversationHarness")
+        await self.harness.cleanup()
+
+        logger.debug("VoiceAgentSystem: Cleaning up Bus")
+        await self.bus.cleanup()
+
+        logger.info("VoiceAgentSystem: System cleanup completed")
+
+    async def wait_for_shutdown(self):
+        """Wait until system should shut down (WebSocket disconnect)."""
+        await self.bus.shutdown_event.wait()
+
+    async def send_initial_message(self, message: str):
+        """
+        Send initial message to user and add as a message to the main node's conversation.
+
+        Args:
+            message (str): Initial greeting message.
+        """
+        logger.info(f"VoiceAgentSystem: Sending initial message: '{message[:50]}...'")
+        await self.bus.broadcast(Message(source=self.authorized_node, event=AgentResponse(content=message)))
+
+        # Add to main node conversation history.
+        if self.main_node and hasattr(self.main_node, "add_event"):
+            logger.debug("VoiceAgentSystem: Adding initial message to main node conversation history")
+            self.main_node.add_event(AgentResponse(content=message))
+
+    @property
+    def user_bridge(self) -> Bridge:
+        """Get the user bridge."""
+        if "user" not in self.bridges:
+            raise ValueError("User bridge not found. Must call with_speaking_node() first.")
+        return self.bridges["user"]