cartesia-line 0.0.1__py3-none-any.whl

line/harness.py

@@ -0,0 +1,257 @@
+"""
+ConversationHarness - WebSocket communication layer for agents
+Handles input/output queues and event coordination
+"""
+
+import asyncio
+from asyncio import QueueEmpty
+import json
+from typing import Any, Dict, List, Optional
+
+from fastapi import WebSocket, WebSocketDisconnect
+from loguru import logger
+from pydantic import TypeAdapter
+
+from line.events import (
+    AgentSpeechSent,
+    AgentStartedSpeaking,
+    AgentStoppedSpeaking,
+    UserStartedSpeaking,
+    UserStoppedSpeaking,
+    UserTranscriptionReceived,
+    UserUnknownInputReceived,
+)
+from line.harness_types import (
+    AgentSpeechInput,
+    AgentStateInput,
+    EndCallOutput,
+    ErrorOutput,
+    InputMessage,
+    LogEventOutput,
+    LogMetricOutput,
+    MessageOutput,
+    OutputMessage,
+    ToolCallOutput,
+    TranscriptionInput,
+    TransferOutput,
+    UserStateInput,
+)
+
+
+class State:
+    """User voice states."""
+
+    SPEAKING = "speaking"
+    IDLE = "idle"
+
+
+class ConversationHarness:
+    """
+    Manages WebSocket communication, input/output queues, and coordination events
+    for reasoning agents. Handles message parsing and event triggering.
+    """
+
+    def __init__(
+        self,
+        websocket: WebSocket,
+        shutdown_event: asyncio.Event,
+    ):
+        """
+        Initialize the conversation harness
+
+        Args:
+            websocket: FastAPI WebSocket connection
+            shutdown_event: Event to signal shutdown
+        """
+        self.websocket = websocket
+
+        # Use provided queues and events
+        self.input_queue = asyncio.Queue()
+        self.shutdown_event = shutdown_event
+
+        # Task management
+        self.input_task: Optional[asyncio.Task] = None
+
+        # State tracking
+        self.is_running = False
+
+    async def start(self):
+        """
+        Start the harness tasks for input and output processing
+        """
+        if self.is_running:
+            logger.warning("ConversationHarness already running")
+            return
+
+        self.is_running = True
+        logger.debug("Starting ConversationHarness")
+
+        # Start input and output tasks
+        self.input_task = asyncio.create_task(self._input_processor())
+
+        logger.debug("ConversationHarness started with input/output processors")
+
+    async def _input_processor(self):
+        """
+        Continuously receive messages from WebSocket, parse them, and handle events
+        """
+        try:
+            while not self.shutdown_event.is_set():
+                try:
+                    # Receive message from WebSocket
+                    message = await self.websocket.receive_json()
+                    input = TypeAdapter(InputMessage).validate_python(message)
+                    # Process the message and handle events
+                    await self.input_queue.put(input)
+
+                except WebSocketDisconnect:
+                    logger.info("WebSocket disconnected")
+                    self.shutdown_event.set()
+                    break
+                except json.JSONDecodeError as e:
+                    logger.exception(f"Failed to parse JSON message: {e}")
+                    continue
+                except Exception as e:
+                    logger.exception(f"Error in input processor: {e}")
+                    if not self.shutdown_event.is_set():
+                        await asyncio.sleep(0.1)  # Brief pause before retry
+
+        except asyncio.CancelledError:
+            logger.info("Input processor cancelled")
+        except Exception as e:
+            logger.exception(f"Unexpected error in input processor: {e}")
+
+    async def get(self) -> InputMessage:
+        """Get a message from the input queue"""
+        return await self.input_queue.get()
+
+    async def _send(self, output: OutputMessage):
+        try:
+            if not self.shutdown_event.is_set():
+                await self.websocket.send_json(output.model_dump())
+        except Exception as e:
+            logger.warning(f"Failed to send message via WebSocket: {e}")
+            self.shutdown_event.set()
+
+    async def end_call(self):
+        """
+        Send end_call message and signal shutdown
+        """
+        await self._send(EndCallOutput())
+        logger.info("End call message sent")
+
+    async def transfer_call(self, destination: str = ""):
+        """
+        Send transfer_call message
+
+        Args:
+            destination: Optional destination for call transfer
+        """
+        await self._send(TransferOutput(target_phone_number=destination))
+        logger.info(f"Transfer call message sent to {destination}")
+        self.shutdown_event.set()
+
+    async def send_message(self, message: str):
+        """Send a message via WebSocket with connection state checking"""
+        logger.info(f'🤖 Agent said: "{message}"')
+        await self._send(MessageOutput(content=message))
+
+    async def send_error(self, error: str):
+        """Send an error message via WebSocket with connection state checking"""
+        await self._send(ErrorOutput(content=error))
+
+    async def send_tool_call(
+        self,
+        tool_name: str,
+        tool_args: Dict[str, Any],
+        tool_call_id: Optional[str] = None,
+        result: Optional[str] = None,
+    ):
+        """Send a tool call result via WebSocket with connection state checking"""
+        await self._send(
+            ToolCallOutput(
+                name=tool_name,
+                arguments=tool_args,
+                result=result,
+                id=tool_call_id,
+            )
+        )
+
+    async def log_event(self, event: str, metadata: Optional[Dict[str, Any]] = None):
+        """
+        Send a log event via WebSocket
+
+        Args:
+            event: The event name/type being logged
+            metadata: Optional metadata dictionary for the event
+        """
+        logger.debug(f"📊 Logging event: {event}" + (f" - {metadata}" if metadata else ""))
+        await self._send(LogEventOutput(event=event, metadata=metadata))
+
+    async def log_metric(self, name: str, value: Any):
+        """
+        Send a log metric via WebSocket
+
+        Args:
+            name: The metric name
+            value: The metric value (can be any JSON-serializable type)
+        """
+        logger.debug(f"📈 Logging metric: {name}={value}")
+        await self._send(LogMetricOutput(name=name, value=value))
+
+    async def cleanup(self):
+        """
+        Clean up resources and stop all tasks
+        """
+        logger.info("Cleaning up ConversationHarness")
+
+        # Signal shutdown
+        self.shutdown_event.set()
+        self.is_running = False
+
+        # Cancel tasks
+        if self.input_task and not self.input_task.done():
+            self.input_task.cancel()
+            try:
+                await self.input_task
+            except asyncio.CancelledError:
+                pass
+
+        # Clear any remaining messages in queues
+        while not self.input_queue.empty():
+            try:
+                self.input_queue.get_nowait()
+                self.input_queue.task_done()
+            except QueueEmpty:
+                break
+
+        logger.info("ConversationHarness cleanup completed")
+
+    def map_to_events(self, message: InputMessage) -> List[Any]:
+        """Convert harness-specific message to bus events."""
+        if isinstance(message, UserStateInput):
+            if message.value == State.SPEAKING:
+                logger.info("🎤 User started speaking")
+                return [UserStartedSpeaking()]
+            elif message.value == State.IDLE:
+                logger.info("🔇 User stopped speaking")
+                return [UserStoppedSpeaking()]
+        elif isinstance(message, TranscriptionInput):
+            logger.info(f'📝 User said: "{message.content}"')
+            return [UserTranscriptionReceived(content=message.content)]
+        elif isinstance(message, AgentStateInput):
+            if message.value == State.SPEAKING:
+                logger.info("🎤 Agent started speaking")
+                return [AgentStartedSpeaking()]
+            elif message.value == State.IDLE:
+                logger.info("🔇 Agent stopped speaking")
+                return [AgentStoppedSpeaking()]
+        elif isinstance(message, AgentSpeechInput):
+            logger.info(f'🗣️ Agent speech sent: "{message.content}"')
+            return [AgentSpeechSent(content=message.content)]
+        else:
+            # Fallback for unknown types.
+            logger.warning(f"Unknown message type: {type(message).__name__} ({message.model_dump_json()})")
+            return [UserUnknownInputReceived(input_data=message.model_dump_json())]
+
+        return []  # No events for unhandled states

line/harness_types.py

@@ -0,0 +1,109 @@
+from typing import Dict, Literal, Optional, Union
+
+from pydantic import BaseModel
+
+########################################################
+#  Copied and adapted from Bifrost agent_types.py
+########################################################
+
+# Input messages to be sent over the websocket to the user code
+
+
+class TranscriptionInput(BaseModel):
+    content: str
+    type: Literal["message"] = "message"
+
+
+class DTMFInput(BaseModel):
+    button: str
+    type: Literal["dtmf"] = "dtmf"
+
+
+class UserStateInput(BaseModel):
+    value: str
+    type: Literal["user_state"] = "user_state"
+
+
+class AgentStateInput(BaseModel):
+    value: str
+    type: Literal["agent_state"] = "agent_state"
+
+
+class ValidationErrorInput(BaseModel):
+    error_message: str
+    error_type: str
+    type: Literal["validation_error"] = "validation_error"
+
+
+class AgentSpeechInput(BaseModel):
+    content: str
+    type: Literal["agent_speech"] = "agent_speech"
+
+
+InputMessage = Union[
+    TranscriptionInput,
+    DTMFInput,
+    UserStateInput,
+    AgentStateInput,
+    ValidationErrorInput,
+    AgentSpeechInput,
+]
+
+
+# Output messages to be received from the user code
+
+
+class ErrorOutput(BaseModel):
+    type: Literal["error"] = "error"
+    content: str
+
+
+class DTMFOutput(BaseModel):
+    type: Literal["dtmf"] = "dtmf"
+    button: str
+
+
+class MessageOutput(BaseModel):
+    type: Literal["message"] = "message"
+    content: str
+
+
+class ToolCallOutput(BaseModel):
+    type: Literal["tool_call"] = "tool_call"
+    name: str
+    arguments: Dict[str, object]
+    result: Optional[str] = None
+    id: Optional[str] = None
+
+
+class TransferOutput(BaseModel):
+    type: Literal["transfer"] = "transfer"
+    target_phone_number: str
+
+
+class EndCallOutput(BaseModel):
+    type: Literal["end_call"] = "end_call"
+
+
+class LogEventOutput(BaseModel):
+    type: Literal["log_event"] = "log_event"
+    event: str
+    metadata: Optional[Dict[str, object]] = None
+
+
+class LogMetricOutput(BaseModel):
+    type: Literal["log_metric"] = "log_metric"
+    name: str
+    value: object
+
+
+OutputMessage = Union[
+    ErrorOutput,
+    DTMFOutput,
+    MessageOutput,
+    ToolCallOutput,
+    TransferOutput,
+    EndCallOutput,
+    LogEventOutput,
+    LogMetricOutput,
+]

line/nodes/__init__.py

@@ -0,0 +1,7 @@
+from line.nodes.base import Node
+from line.nodes.reasoning import ReasoningNode
+
+__all__ = [
+    "Node",
+    "ReasoningNode",
+]

line/nodes/base.py

@@ -0,0 +1,60 @@
+from typing import TYPE_CHECKING, AsyncGenerator, Optional
+from uuid import uuid4
+
+from loguru import logger
+
+from line.bus import Message
+from line.events import EventType
+
+if TYPE_CHECKING:
+    from line.bridge import Bridge
+
+
+class Node:
+    """A base class for all nodes.
+
+    Nodes are the building blocks of the agentic system. They are responsible for:
+    - Maintaining state
+    - Generating responses
+    - Handling tool calls
+    - Interrupting the generation process
+
+    Nodes are stateful, and can be used to build multi-agent workflows.
+
+    All nodes have an `id` that is used to identify them.
+    When a :class:`Bridge` is created from a node, the node's `id` is used to identify the node in the bridge.
+    It can be used when filtering by `source`.
+    We do not require that nodes have a unique `id`.
+    """
+
+    def __init__(self, node_id: Optional[str] = None):
+        self.id = node_id or uuid4().hex
+        self._bridge: Optional[Bridge] = None
+
+    async def start(self):
+        """Start the node, in an async context.
+
+        This method is called when the VoiceAgentSystem is started. Use this method to run
+        initialization logic that needs to run in an async context (eg, database connections).
+        """
+        pass
+
+    def __str__(self):
+        return f"{type(self).__name__}(id={self.id})"
+
+    async def cleanup(self):
+        """Clean up the node."""
+        logger.debug(f"{self} cleanup completed")
+
+    def on_interrupt_generate(self, message: Message) -> None:
+        """Handle interrupt event.
+
+        Args:
+            message: The interrupt message.
+        """
+        logger.debug(f"{self} interrupt received.")
+
+    async def generate(self, message: Message) -> AsyncGenerator[EventType, None]:
+        """Generate a response to the message."""
+        raise NotImplementedError("Subclasses must implement `generate`.")
+        yield

line/nodes/conversation_context.py

@@ -0,0 +1,66 @@
+"""
+ConversationContext - Data structure for conversation state in ReasoningNode template method.
+
+This class provides a clean abstraction for conversation data that gets passed
+to specialized processing methods in ReasoningNode subclasses.
+"""
+
+from dataclasses import dataclass
+from typing import Any, List, Optional
+
+from line.events import EventInstance, UserTranscriptionReceived
+
+
+@dataclass
+class ConversationContext:
+    """
+    Encapsulates conversation state for ReasoningNode template method pattern.
+
+    This standardizes how conversation data is passed between the template method
+    (ReasoningNode.generate) and specialized processing (process_context).
+
+    Attributes:
+        events: List of conversation events
+        system_prompt: The system prompt for this reasoning node
+        metadata: Additional context data for specialized processing
+    """
+
+    events: List[EventInstance]
+    system_prompt: str
+    metadata: dict = None
+
+    def __post_init__(self):
+        """Initialize metadata if not provided."""
+        if self.metadata is None:
+            self.metadata = {}
+
+    def format_events(self, max_messages: int = None) -> str:
+        """
+        Format conversation messages as a string for LLM prompts.
+
+        Args:
+            max_messages: Maximum number of recent messages to include
+
+        Returns:
+            Formatted conversation string
+        """
+        events = self.events
+        if max_messages is not None:
+            events = events[-max_messages:]
+
+        return "\n".join(f"{type(event)}: {event}" for event in events)
+
+    def get_latest_user_transcript_message(self) -> Optional[str]:
+        """Get the most recent user message content."""
+        for msg in reversed(self.events):
+            if isinstance(msg, UserTranscriptionReceived):
+                return msg.content
+        return None
+
+    def get_event_count(self) -> int:
+        """Get total number of messages in context."""
+        return len(self.events)
+
+    def add_metadata(self, key: str, value: Any) -> None:
+        """Add metadata for specialized processing."""
+        self.metadata[key] = value