cartesia-line 0.1.1__tar.gz → 0.1.3__tar.gz

{cartesia_line-0.1.1 → cartesia_line-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cartesia-line
-Version: 0.1.1
+Version: 0.1.3
 Summary: Cartesia Voice Agents SDK
 Author-email: "Cartesia AI, Inc." <support@cartesia.ai>
 License: Apache 2.0
@@ -32,9 +32,11 @@ Requires-Dist: uvicorn<1,>=0.35.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-xdist==3.8.0; extra == "dev"
+Requires-Dist: pytest-repeat==0.9.4; extra == "dev"
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: ruff==0.12.8; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: google-genai<2,>=1.26.0; extra == "dev"
 Provides-Extra: gemini
 Requires-Dist: google-genai<2,>=1.26.0; python_version >= "3.9" and extra == "gemini"

{cartesia_line-0.1.1 → cartesia_line-0.1.3}/cartesia_line.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cartesia-line
-Version: 0.1.1
+Version: 0.1.3
 Summary: Cartesia Voice Agents SDK
 Author-email: "Cartesia AI, Inc." <support@cartesia.ai>
 License: Apache 2.0
@@ -32,9 +32,11 @@ Requires-Dist: uvicorn<1,>=0.35.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-xdist==3.8.0; extra == "dev"
+Requires-Dist: pytest-repeat==0.9.4; extra == "dev"
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: ruff==0.12.8; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: google-genai<2,>=1.26.0; extra == "dev"
 Provides-Extra: gemini
 Requires-Dist: google-genai<2,>=1.26.0; python_version >= "3.9" and extra == "gemini"

{cartesia_line-0.1.1 → cartesia_line-0.1.3}/cartesia_line.egg-info/SOURCES.txt

@@ -17,6 +17,10 @@ line/routes.py
 line/user_bridge.py
 line/voice_agent_app.py
 line/voice_agent_system.py
+line/evals/__init__.py
+line/evals/conversation_runner.py
+line/evals/similarity_utils.py
+line/evals/turn.py
 line/nodes/__init__.py
 line/nodes/base.py
 line/nodes/conversation_context.py
@@ -28,6 +32,8 @@ line/utils/__init__.py
 line/utils/aio.py
 line/utils/gemini_utils.py
 line/utils/openai_utils.py
+line/utils/str.py
 tests/test_bridge.py
 tests/test_bus.py
-tests/test_routes.py
+tests/test_routes.py
+tests/test_similarity_utils.py

{cartesia_line-0.1.1 → cartesia_line-0.1.3}/cartesia_line.egg-info/requires.txt

@@ -8,9 +8,11 @@ uvicorn<1,>=0.35.0
 [dev]
 pytest
 pytest-asyncio
+pytest-cov
+pytest-xdist==3.8.0
+pytest-repeat==0.9.4
 pre-commit
 ruff==0.12.8
-pytest-cov
 google-genai<2,>=1.26.0
 
 [gemini]

cartesia_line-0.1.3/line/evals/__init__.py

@@ -0,0 +1,10 @@
+# Evaluation components
+from line.evals.conversation_runner import ConversationRunner
+from line.evals.turn import AgentTurn, Turn, UserTurn
+
+__all__ = [
+    "ConversationRunner",
+    "AgentTurn",
+    "Turn",
+    "UserTurn",
+]

cartesia_line-0.1.3/line/evals/conversation_runner.py

@@ -0,0 +1,195 @@
+"""
+ConversationRunner - A testing wrapper around ReasoningNode for conversation flow validation.
+
+This class allows testing conversation flows by providing expected conversation traces
+and validating that the ReasoningNode produces similar responses.
+"""
+
+from typing import List, Optional
+
+from line.evals.similarity_utils import is_similar_str
+from line.evals.turn import Turn
+from line.events import EventInstance
+from line.nodes.conversation_context import ConversationContext
+from line.nodes.reasoning import ReasoningNode
+
+
+class ConversationRunner:
+    """
+    A testing wrapper for ReasoningNode that validates conversation flows.
+
+    This class takes an expected conversation trace and validates that a ReasoningNode
+    produces similar responses when given the same user inputs.
+    """
+
+    def __init__(
+        self,
+        reasoning_node: ReasoningNode,
+        expected_conversation: List[Turn],
+        initial_agent_message: Optional[str] = None,
+        test_note: Optional[str] = None,
+    ):
+        """
+        Initialize the test conversation.
+
+        Args:
+            reasoning_node: The ReasoningNode to test
+            expected_conversation: List of Turn objects representing the expected conversation flow,
+                                 alternating between user and agent turns
+            initial_agent_message: Optional initial message from agent to verify against first AgentTurn
+        """
+        self.reasoning_node = reasoning_node
+        self.expected_conversation = expected_conversation
+        self.initial_agent_message = initial_agent_message
+        self.test_note = test_note
+
+    def _verify_initial_agent_message(self) -> Optional[List[EventInstance]]:
+        """
+        Verify the initial agent message and return its events if it exists.
+
+        Returns:
+            List of EventInstance if conversation starts with agent turn, None otherwise
+
+        Raises:
+            AssertionError: If initial agent message doesn't match expected first AgentTurn
+        """
+        if not self.expected_conversation:
+            return None
+
+        first_turn = self.expected_conversation[0]
+        if not first_turn.is_agent:
+            return None
+
+        # If initial_agent_message is provided, verify it matches
+        if self.initial_agent_message is None:
+            return first_turn.to_events()
+
+        if first_turn.text == self.initial_agent_message:
+            return first_turn.to_events()
+
+        results = is_similar_str(self.initial_agent_message, first_turn.text)
+        if results.is_success:
+            return first_turn.to_events()
+
+        error_str = (
+            f"Initial agent message doesn't match expected first AgentTurn.\n"
+            f"Provided initial_agent_message: '{self.initial_agent_message}'\n"
+            f"Expected first AgentTurn text: '{first_turn.text}'\n"
+            f"Similarity error: {results.error}"
+        )
+
+        if self.test_note is not None:
+            error_str += f"\nTest notes: {self.test_note}"
+
+        raise AssertionError(error_str)
+
+    def _verify_conversation_pattern(self) -> None:
+        """
+        Validate that the conversation follows proper alternating user-assistant pattern.
+
+        Raises:
+            ValueError: If the conversation pattern is invalid
+        """
+        if not self.expected_conversation:
+            return
+
+        # Ensure conversation ends with agent turn
+        last_turn = self.expected_conversation[-1]
+        if not last_turn.is_agent:
+            error_str = "Conversation must end with agent turn."
+            if self.test_note is not None:
+                error_str += f"\nTest notes: {self.test_note}"
+            raise ValueError(error_str)
+
+        # Validate alternating pattern
+        for i in range(1, len(self.expected_conversation)):
+            current_turn = self.expected_conversation[i]
+            previous_turn = self.expected_conversation[i - 1]
+
+            same_type = (current_turn.is_user and previous_turn.is_user) or (
+                current_turn.is_agent and previous_turn.is_agent
+            )
+            if same_type:
+                error_str = (
+                    f"Invalid conversation pattern at position {i}: "
+                    f"Two consecutive '{current_turn.role}' turns. "
+                    f"Expected alternating user-assistant pattern."
+                )
+
+                if self.test_note is not None:
+                    error_str += f"\nTest notes: {self.test_note}"
+                raise ValueError(error_str)
+
+    async def run(self) -> None:
+        """
+        Run the conversation test, validating each agent response against expected.
+
+        This method processes the expected conversation turn by turn:
+        1. Process user turns by adding them to conversation history
+        2. For each user turn, get the expected agent response
+        3. Build ConversationContext and call process_context() on ReasoningNode
+        4. Convert actual response to Turn and validate similarity
+        5. Continue with next turn
+
+        Raises:
+            ValueError: If conversation pattern is invalid (non-alternating user-assistant turns)
+            AssertionError: If any agent response doesn't match expected
+        """
+        # Validate conversation pattern first
+        self._verify_conversation_pattern()
+
+        # Track conversation history
+        conversation_history: List[EventInstance] = []
+
+        # Handle initial agent message
+        initial_events = self._verify_initial_agent_message()
+        i = 0
+        if initial_events is not None:
+            # Add the first agent turn to conversation history and skip it
+            conversation_history.extend(initial_events)
+            i = 1
+
+        while i < len(self.expected_conversation):
+            user_turn = self.expected_conversation[i]
+
+            # Add user turn events to history
+            user_events = user_turn.to_events()
+            conversation_history.extend(user_events)
+            i += 1
+
+            # Get expected agent response from following turn
+            expected_agent_turn = self.expected_conversation[i]
+
+            # Build conversation context from history
+            ctx = ConversationContext(
+                events=conversation_history.copy(),
+                system_prompt=self.reasoning_node.system_prompt,
+            )
+
+            # Get actual response from reasoning node
+            actual_events = []
+            async for event in self.reasoning_node.process_context(ctx):
+                actual_events.append(event)
+
+            # Convert actual events to Turn
+            actual_turn = Turn.from_events(actual_events)
+
+            # Validate similarity
+            similarity_error = expected_agent_turn.is_similar(actual_turn)
+            if similarity_error is not None:
+                error_str = (
+                    f"Agent turn doesn't match expected.\n"
+                    f"  User message: {user_turn.text}\n"
+                    f"  Expected:     {expected_agent_turn}\n"
+                    f"  Actual:       {actual_turn}\n"
+                    f"  Reason:       {similarity_error}\n"
+                )
+
+                if self.test_note is not None:
+                    error_str += f"\nTest notes: {self.test_note}"
+
+                raise AssertionError(error_str)
+
+            # Add actual agent turn events to history for next iteration
+            conversation_history.extend(actual_events)
+            i += 1

cartesia_line-0.1.3/line/evals/similarity_utils.py

@@ -0,0 +1,279 @@
+"""
+Similarity checking utilities for conversation evaluation.
+
+This module provides functions for comparing strings and dictionaries with semantic
+similarity checking using AI models.
+"""
+
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Union  # noqa: F401
+
+from google.genai import Client
+from google.genai.types import GenerateContentConfig
+
+
+@dataclass
+class SimilarityResult:
+    is_success: Optional[bool]  # None = if not applicable
+    error: Optional[str]  # Error message if not successful
+
+
+def is_statement_pattern(s: str) -> bool:
+    """Check if string is a statement pattern like <mentions something>."""
+    return s.strip().startswith("<") and s.strip().endswith(">")
+
+
+def extract_statement(s: str) -> str:
+    """Extract statement content from pattern by removing < and >."""
+    return s.strip()[1:-1]
+
+
+def check_string_statement(statement: str, actual_text: str) -> SimilarityResult:
+    """Check if actual text matches a statement pattern.
+
+    Args:
+        statement: The statement description (without < >)
+        actual_text: The actual text to check against the statement
+
+    Returns:
+        None if text matches statement, error message string if not
+    """
+    client = Client()
+
+    prompt = f"""
+    Check if the following text matches this statement/requirement:
+
+    Statement: "{statement}"
+    Text: "{actual_text}"
+
+    Instructions:
+    - Respond with "YES" if the text matches the statement, or "NO: [reason]" if it doesn't.
+    - The text should contain or express the concept described in the statement.
+
+    Examples:
+    - Statement: "mentions SOC-2 compliance" vs Text: "Our security audit passed SOC-2 requirements" → YES
+    - Statement: "mentions SOC-2 compliance" vs Text: "We follow security best practices" → NO:
+        Doesn't mention SOC-2
+    - Statement: "asks for user name" vs Text: "What's your name?" → YES
+    - Statement: "asks for user name" vs Text: "How old are you?" → NO: Asks for age, not name
+    """
+
+    config = GenerateContentConfig(
+        temperature=0.1,
+    )
+
+    response = client.models.generate_content(model="gemini-2.5-flash-lite", contents=prompt, config=config)
+    response_text = response.text.strip() if response.text else ""
+
+    if response_text.upper().startswith("YES"):
+        return SimilarityResult(is_success=True, error=None)
+    elif response_text.upper().startswith("NO"):
+        reason = response_text[3:].strip().lstrip(":").strip()
+        return SimilarityResult(is_success=False, error=reason)
+    else:
+        return SimilarityResult(
+            is_success=False,
+            error=f"Unexpected response format from statement check: {response_text}",
+        )
+
+
+def is_similar_str(a: str, b: str) -> SimilarityResult:
+    """Check if two strings have the same meaning using Gemini with special rule support.
+
+    Special Rules:
+        - "*" wildcard: Matches any string content (either a or b can be "*")
+        - Statement patterns: Strings like "<mentions SOC-2 compliance>" match text containing that concept
+
+    Args:
+        a: First string to compare
+        b: Second string to compare
+
+    Returns:
+        None if strings are similar, error message string if not
+    """
+    # * means any string is allowed
+    if a == "*" or b == "*":
+        return SimilarityResult(is_success=True, error=None)
+
+    # Handle statement patterns
+    result = is_similar_via_statement_pattern(a, b)
+    if result.is_success is not None:
+        return result
+
+    # Handle single text comparision
+    return is_similar_via_single_text_comparison(a, b)
+
+
+def is_similar_via_statement_pattern(a: str, b: str) -> SimilarityResult:
+    a_is_statement = is_statement_pattern(a)
+    b_is_statement = is_statement_pattern(b)
+
+    if a_is_statement or b_is_statement:
+        # At least one is a statement pattern
+        if a_is_statement and b_is_statement:
+            # Both are statement patterns - compare the statements themselves
+            statement_a = extract_statement(a)
+            statement_b = extract_statement(b)
+            return is_similar_str(statement_a, statement_b)  # Recursive call without < >
+
+        # One is a statement, one is actual text
+        statement = extract_statement(a) if a_is_statement else extract_statement(b)
+        actual_text = b if a_is_statement else a
+
+        return check_string_statement(statement, actual_text)
+
+    return SimilarityResult(is_success=None, error=None)
+
+
+def is_similar_via_single_text_comparison(a: str, b: str) -> SimilarityResult:
+    # First check if strings are equal after basic normalization
+    if a.lower().strip() == b.lower().strip():
+        return SimilarityResult(is_success=True, error=None)
+
+    client = Client()
+
+    prompt = f"""
+    Compare these two strings and determine if they have the same or very similar meaning:
+
+    String A: "{a}"
+    String B: "{b}"
+
+    Rules:
+    - Respond with "YES" if they have the same meaning, or "NO: [reason]" if they don't.
+    - Consider paraphrasing, synonyms, and different ways of expressing the same concept.
+    - Ignore filler prefixes like "Now", "Okay", "Got it", "Thank you", "Finally", "Sounds good", etc.
+    - Affirmative phrases like "yes", "that is correct" or "correct" are similar
+    - For alphanumeric matching, you may allow mismatches on spacing
+    - For alphanumeric matching, you may allow matching when spelled out (e.g. 1 is equivalent to "one", 2 is equivalent to "two", etc.)
+    - For alphanumeric matching, you may allow semantic matching between spelled out numbers with spaces or concatenated string of digits
+
+    Examples:
+    - "What's your name?" vs "Can you tell me your name?" → YES
+    - "What's your name?" vs "What's your age?" → NO: Different information being requested
+    - "You are verified" vs "Your identity is confirmed" → YES
+    - "Now, what's your Name?" vs "Thank you, what's your name?" → YES
+    - "Hello" vs "Goodbye" → NO: Opposite greetings with different meanings
+    - "one    two three  four" versus "1234" → YES
+    """  # noqa: E501
+
+    config = GenerateContentConfig(
+        temperature=0.1,  # Low temperature for consistent results
+    )
+
+    response = client.models.generate_content(model="gemini-2.5-flash-lite", contents=prompt, config=config)
+
+    response_text = response.text.strip() if response.text else ""
+
+    if response_text.upper().startswith("YES"):
+        return SimilarityResult(is_success=True, error=None)
+    elif response_text.upper().startswith("NO"):
+        # Extract and return reason
+        reason = response_text[3:].strip().lstrip(":").strip()
+        return SimilarityResult(is_success=False, error=reason)
+    else:
+        # Fallback in case of unexpected response format
+        return SimilarityResult(
+            is_success=False,
+            error=f"Unexpected response format from similarity check: {response_text}\n"
+            f'String A: "{a}"\nString B: "{b}"',
+        )
+
+
+def is_similar_text(a: Union[List[str], str], b: Union[List[str], str]) -> SimilarityResult:
+    """Given two texts that are lists, check that at least one element from a is similar to one element from b.
+
+    Args:
+        a: First list of strings to compare
+        b: Second list of strings to compare
+
+    Returns:
+        SimilarityResult indicating if the lists are similar
+    """  # noqa: E501
+    a = [a] if isinstance(a, str) else a
+    b = [b] if isinstance(b, str) else b
+
+    if not a and not b:
+        raise RuntimeError("Both lists are empty")
+    if not a or not b:
+        return SimilarityResult(is_success=False, error=f"One list is empty: a={a}, b={b}")
+
+    # Check if any element from 'a' is similar to any element from 'b'
+    for a_item in a:
+        for b_item in b:
+            result = is_similar_str(a_item, b_item)
+            if result.is_success:
+                return SimilarityResult(is_success=True, error=None)
+
+    if len(a) == 1 and len(b) == 1:
+        return SimilarityResult(is_success=False, error=f"{a} != {b}")
+    else:
+        return SimilarityResult(
+            is_success=False, error=f"No similar elements found the following two lists: a={a}, b={b}"
+        )
+
+
+def is_similar_dict(actual: Dict, expected: Dict) -> SimilarityResult:
+    """Recursively check if two dictionaries are similar.
+
+    Uses string similarity checking for string values and recursive comparison for nested dicts.
+
+    Args:
+        actual: The actual dictionary
+        expected: The expected dictionary
+
+    Returns:
+        None if dictionaries are similar, error message string if not
+    """
+    # Check if keys match
+    actual_keys = set(actual.keys())
+    expected_keys = set(expected.keys())
+
+    if actual_keys != expected_keys:
+        missing_keys = expected_keys - actual_keys
+        extra_keys = actual_keys - expected_keys
+        error_parts = []
+        if missing_keys:
+            error_parts.append(f"missing keys: {list(missing_keys)}")
+        if extra_keys:
+            error_parts.append(f"extra keys: {list(extra_keys)}")
+        return SimilarityResult(
+            is_success=False,
+            error=f"Key mismatch - {', '.join(error_parts)}",
+        )
+
+    # Check each key-value pair
+    for key in expected_keys:
+        actual_value = actual[key]
+        expected_value = expected[key]
+
+        # Skip validation if expected value is None
+        if expected_value is None:
+            continue
+
+        # Handle string values with similarity checking
+        if isinstance(expected_value, str) and isinstance(actual_value, str):
+            result = is_similar_str(actual_value, expected_value)
+            if result.is_success is False:
+                return SimilarityResult(
+                    is_success=False,
+                    error=f"String value mismatch for key '{key}': {result.error}",
+                )
+
+        # Handle nested dictionaries
+        elif isinstance(expected_value, dict) and isinstance(actual_value, dict):
+            error = is_similar_dict(actual_value, expected_value)
+            if error.is_success is False:
+                return SimilarityResult(
+                    is_success=False,
+                    error=f"Nested dict mismatch for key '{key}': {error}",
+                )
+
+        # Handle other types with exact comparison
+        else:
+            if actual_value != expected_value:
+                return SimilarityResult(
+                    is_success=False,
+                    error=f"Value mismatch for key '{key}': expected {expected_value}, got {actual_value}",
+                )
+
+    return SimilarityResult(is_success=True, error=None)

cartesia_line-0.1.3/line/evals/turn.py

@@ -0,0 +1,236 @@
+"""
+Turn-based conversation representation for evaluation.
+
+This module provides Turn classes that represent conversation turns with automatic
+conversion to/from Event instances for use with ReasoningNode testing.
+"""
+
+import json
+from typing import Any, Dict, List, Literal, Optional, Union
+
+from pydantic import BaseModel, Field
+
+from line.evals.similarity_utils import is_similar_dict, is_similar_text
+from line.events import (
+    AgentResponse,
+    DTMFOutputEvent,
+    EndCall,
+    EventInstance,
+    ToolResult,
+    TransferCall,
+    UserTranscriptionReceived,
+)
+from line.events import (
+    ToolCall as EventToolCall,
+)
+
+
+class ToolCall(BaseModel):
+    """Tool call representation within a Turn."""
+
+    name: str
+    arguments: Dict[str, Any] = Field(default_factory=dict)
+    result: Any = None
+
+
+class Turn(BaseModel):
+    """Base class for conversation turns with event conversion capabilities."""
+
+    role: Literal["user", "assistant"]
+    text: Union[List[str], str] = ""
+    tool_calls: List[ToolCall] = Field(default_factory=list)
+    telephony_events: list[Union[DTMFOutputEvent, TransferCall, EndCall]] = Field(default_factory=list)
+
+    @property
+    def is_user(self) -> bool:
+        """Check if this is a user turn."""
+        return self.role == "user"
+
+    @property
+    def is_agent(self) -> bool:
+        """Check if this is an agent turn."""
+        return self.role == "assistant"
+
+    def to_events(self) -> List[EventInstance]:
+        """Convert this turn to a list of Event instances."""
+        events = []
+
+        if self.role == "user":
+            if isinstance(self.text, str):
+                events.append(UserTranscriptionReceived(content=self.text))
+                return events
+
+            # Otherwise, it must be a list
+            if len(self.text) != 1:
+                raise RuntimeError("Must include exactly one text element for user turn. {len(self.text)=}")
+            if self.text:
+                # Join all text elements with a space for user transcription
+                events.append(UserTranscriptionReceived(content=self.text[0]))
+        elif self.role == "assistant":
+            # Add tool calls first
+            for tool_call in self.tool_calls:
+                events.append(EventToolCall(tool_name=tool_call.name, tool_args=tool_call.arguments))
+                if tool_call.result is not None:
+                    events.append(
+                        ToolResult(
+                            tool_name=tool_call.name,
+                            tool_args=tool_call.arguments,
+                            result=tool_call.result,
+                        )
+                    )
+
+            # Add text response
+            if self.text:
+                if isinstance(self.text, str):
+                    events.append(AgentResponse(content=self.text))
+                elif isinstance(self.text, list):
+                    events.append(AgentResponse(content=self.text[0]))
+                else:
+                    raise RuntimeError(f"Unexpected text type: {type(self.text)=}")
+
+        return events
+
+    @classmethod
+    def from_events(cls, events: List[EventInstance]) -> "Turn":
+        """Create a Turn from a list of Event instances."""
+        text = ""
+        tool_calls = []
+        role = "assistant"  # Default to assistant
+
+        # Track tool calls and their results
+        tool_call_map = {}
+        telephony_events = []
+
+        for event in events:
+            if isinstance(event, UserTranscriptionReceived):
+                role = "user"
+                text += event.content
+            elif isinstance(event, AgentResponse):
+                role = "assistant"
+                text += event.content
+            elif isinstance(event, EventToolCall):
+                role = "assistant"
+                tool_call_map[event.tool_name] = ToolCall(name=event.tool_name, arguments=event.tool_args)
+            elif isinstance(event, ToolResult):
+                role = "assistant"
+                if event.tool_name in tool_call_map:
+                    tool_call_map[event.tool_name].result = event.result
+                else:
+                    # Create tool call if we only have the result
+                    tool_call_map[event.tool_name] = ToolCall(
+                        name=event.tool_name,
+                        arguments=event.tool_args,
+                        result=event.result,
+                    )
+            elif (
+                isinstance(event, DTMFOutputEvent)
+                or isinstance(event, TransferCall)
+                or isinstance(event, EndCall)
+            ):
+                role = "assistant"
+                telephony_events.append(event)
+
+        tool_calls = list(tool_call_map.values())
+        text = text.strip()
+
+        return cls(role=role, text=text, tool_calls=tool_calls, telephony_events=telephony_events)
+
+    def is_similar(self, other: "Turn") -> Optional[str]:
+        """Check if this turn is similar to another turn.
+
+        Returns:
+            None if turns are similar, error description string if not
+        """
+        # Check role matches
+        if self.role != other.role:
+            return f"Role mismatch: expected '{other.role}', got '{self.role}'"
+
+        # Check text similarity
+        if self.text or other.text:
+            results = is_similar_text(self.text, other.text)
+            if results.is_success is False:
+                return f"Text mismatch: {results.error}"
+
+        # Check tool calls match
+        if len(self.tool_calls) != len(other.tool_calls):
+            return f"Tool call count mismatch: expected {len(other.tool_calls)}, got {len(self.tool_calls)}"
+
+        # Sort tool calls by name for comparison
+        self_tools = sorted(self.tool_calls, key=lambda x: x.name)
+        other_tools = sorted(other.tool_calls, key=lambda x: x.name)
+
+        for self_tool, other_tool in zip(self_tools, other_tools):
+            if self_tool.name != other_tool.name:
+                return f"Tool name mismatch: expected '{other_tool.name}', got '{self_tool.name}'"
+
+            # Check arguments similarity
+            if self_tool.arguments or other_tool.arguments:
+                results = is_similar_dict(self_tool.arguments, other_tool.arguments)
+                if results.is_success is False:
+                    return f"Tool '{self_tool.name}' arguments mismatch: {results.error}"
+
+            # Check result similarity
+            if self_tool.result != other_tool.result:
+                return (
+                    f"Tool '{self_tool.name}' result mismatch: "
+                    f"expected {other_tool.result}, got {self_tool.result}"
+                )
+
+        if self.telephony_events != other.telephony_events:
+            return f"telephony_events mismatch: expected {other.telephony_events} to match {self.telephony_events}"  # noqa: E501
+
+        return None
+
+
+class UserTurn(Turn):
+    """User conversation turn."""
+
+    role: Literal["user"] = "user"
+
+
+class AgentTurn(Turn):
+    """Agent conversation turn."""
+
+    role: Literal["assistant"] = "assistant"
+
+
+def make_turn(data: Dict[str, Any]) -> Union[UserTurn, AgentTurn]:
+    """Create a UserTurn or AgentTurn from dictionary data.
+
+    Args:
+        data: Dictionary containing turn data with 'role' field and other turn properties
+
+    Returns:
+        UserTurn or AgentTurn instance based on the role
+
+    Raises:
+        ValueError: If role is not 'user' or 'assistant'
+    """
+    role = data.get("role")
+
+    if role == "user":
+        return UserTurn(**data)
+    elif role == "assistant":
+        return AgentTurn(**data)
+    else:
+        raise ValueError(f"Invalid role '{role}'. Must be 'user' or 'assistant'")
+
+
+def load_conversation_json(file_path: str) -> List[Union[UserTurn, AgentTurn]]:
+    """Load a conversation from a JSON file.
+
+    Args:
+        file_path: Path to JSON file containing conversation data
+
+    Returns:
+        List of Turn instances (UserTurn or AgentTurn)
+
+    Raises:
+        FileNotFoundError: If the file doesn't exist
+        json.JSONDecodeError: If the file contains invalid JSON
+        ValueError: If any turn has an invalid role
+    """
+    with open(file_path, "r") as f:
+        data = json.load(f)
+
+    return [make_turn(turn_data) for turn_data in data]

{cartesia_line-0.1.1 → cartesia_line-0.1.3}/line/events.py

@@ -134,8 +134,7 @@ class AgentError(BaseModel):
 class TransferCall(BaseModel):
     """Transfer call to destination."""
 
-    destination: str
-    reason: Optional[str] = None
+    target_phone_number: str
 
 
 class AgentHandoff(BaseModel):

{cartesia_line-0.1.1 → cartesia_line-0.1.3}/line/harness.py

@@ -143,15 +143,15 @@ class ConversationHarness:
         await self._send(EndCallOutput())
         logger.info("End call message sent")
 
-    async def transfer_call(self, destination: str = ""):
+    async def transfer_call(self, target_phone_number: str = ""):
         """
         Send transfer_call message
 
         Args:
-            destination: Optional destination for call transfer
+            target_phone_number: Optional target phone number for call transfer
         """
-        await self._send(TransferOutput(target_phone_number=destination))
-        logger.info(f"Transfer call message sent to {destination}")
+        await self._send(TransferOutput(target_phone_number=target_phone_number))
+        logger.info(f"Transfer call message sent to {target_phone_number}")
         self.shutdown_event.set()
 
     async def send_message(self, message: str):

{cartesia_line-0.1.1 → cartesia_line-0.1.3}/line/tools/system_tools.py

@@ -1,11 +1,12 @@
 """System tool definitions for Cartesia Voice Agents SDK."""
 
-from typing import AsyncGenerator, Dict, Union
+from typing import AsyncGenerator, Dict, List, Optional, Union
 
 from pydantic import BaseModel, Field
 
 from line.events import AgentResponse, EndCall
 from line.tools.tool_types import ToolDefinition
+from line.utils.str import is_e164_phone_number
 
 try:
     from google.genai import types as gemini_types
@@ -188,5 +189,71 @@ class DTMFToolCall(ToolDefinition):
         }
 
 
-class DTMFToolCallTool(ToolDefinition):
-    """DTMF tool call system tool definition."""
+class TransferToolCall(ToolDefinition):  # noqa: F811
+    """Arguments for the transfer_tool_call tool."""
+
+    def __init__(self, target_phone_numbers: List[str], description: Optional[str] = None):
+        for destination in target_phone_numbers:
+            if not is_e164_phone_number(destination):
+                raise ValueError(f"Invalid destination phone number. {destination=}")
+
+        self.target_phone_numbers = target_phone_numbers
+        self._description = description
+
+    @classmethod
+    def name(cls) -> str:
+        return "transfer_tool"
+
+    def description(self) -> str:
+        return self._description or "Initiates a transfer of the call to the destination phone number."
+
+    @classmethod
+    def parameters_description(cls) -> str:
+        return "The destination phone number to transfer the call to"
+
+    def to_gemini_tool(self) -> "gemini_types.Tool":
+        """Convert to Gemini tool format"""
+        return gemini_types.Tool(
+            function_declarations=[
+                gemini_types.FunctionDeclaration(
+                    name=self.name(),
+                    description=self.description(),
+                    parameters={
+                        "type": "object",
+                        "properties": {
+                            "target_phone_number": {
+                                "type": "string",
+                                "description": self.parameters_description(),
+                                "enum": self.target_phone_numbers,
+                            }
+                        },
+                        "required": ["target_phone_number"],
+                    },
+                )
+            ]
+        )
+
+    def to_openai_tool(self) -> Dict[str, object]:
+        """Convert to OpenAI tool format for Responses API.
+
+        Note: This returns the format expected by OpenAI's Responses API,
+        not the Chat Completions API format.
+        """
+        return {
+            "type": "function",
+            "name": self.name(),
+            "description": self.description(),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "target_phone_number": {
+                        "type": "string",
+                        "enum": self.target_phone_numbers,
+                        "description": self.parameters_description(),
+                    },
+                },
+                "required": ["target_phone_number"],
+                "additionalProperties": False,
+                "strict": True,
+            },
+        }

{cartesia_line-0.1.1 → cartesia_line-0.1.3}/line/user_bridge.py

@@ -105,7 +105,7 @@ def create_user_bridge(harness: "ConversationHarness", authorized_node: str) ->
     async def send_transfer_call(message: Message):
         """Transfer call to destination."""
         event: TransferCall = message.event
-        return await harness.transfer_call(event.destination)
+        return await harness.transfer_call(event.target_phone_number)
 
     async def send_log_metric(message: Message):
         """Log metric via harness."""

cartesia_line-0.1.3/line/utils/str.py

@@ -0,0 +1,30 @@
+def is_e164_phone_number(phone: str) -> bool:
+    """Check if a string is a valid E.164 compliant phone number.
+
+    E.164 format requirements:
+    - Must start with '+'
+    - Followed by 5-15 digits
+    - No spaces, hyphens, or other characters
+
+    Args:
+        phone: The phone number string to validate
+
+    Returns:
+        bool: True if the string is E.164 compliant, False otherwise
+
+
+    Note: 1+4=5 is practically the mininum number of digits. A country can have
+    a short national phone number code (len=4) if they are small (e.g. Falkland Islands)
+    """
+    # Must start with '+'
+    if not phone.startswith("+"):
+        return False
+
+    # Remove the '+' and check the rest
+    digits = phone[1:]
+
+    # Must be between 1 and 15 digits
+    if not digits.isdigit() or len(digits) < 5 or len(digits) > 15:
+        return False
+
+    return True

{cartesia_line-0.1.1 → cartesia_line-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cartesia-line"
-version = "0.1.1"
+version = "0.1.3"
 description = "Cartesia Voice Agents SDK"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -43,11 +43,15 @@ dependencies = [
 dev = [
     "pytest",
     "pytest-asyncio",
+    "pytest-cov",
+    "pytest-xdist==3.8.0",
+    "pytest-repeat==0.9.4",
     "pre-commit",
     "ruff==0.12.8",
-    "pytest-cov",
     "google-genai>=1.26.0,<2",
 ]
+
+
 gemini = [
     "google-genai>=1.26.0,<2; python_version>='3.9'",
     "aiohttp>=3.12.0",

cartesia_line-0.1.3/tests/test_similarity_utils.py

@@ -0,0 +1,99 @@
+import os
+
+import pytest
+
+from line.evals.similarity_utils import is_similar_dict, is_similar_str, is_similar_text
+
+# Skip tests if GEMINI_API_KEY is not set
+pytestmark = pytest.mark.skipif(
+    not os.getenv("GEMINI_API_KEY"),
+    reason="GEMINI_API_KEY environment variable not set",
+)
+
+
+def test_wildcard_matching():
+    """Test wildcard (*) matches any string."""
+    result = is_similar_str("*", "Hello world")
+    assert result.is_success
+    assert result.error is None
+
+
+def test_statement_pattern_matching():
+    """Test statement patterns like <mentions something>."""
+    result = is_similar_str("<mentions compliance>", "We are SOC-2 compliant")
+    assert result.is_success
+    assert result.error is None
+
+    result = is_similar_str("<mentions SOC-2>", "We follow general security practices")
+    assert not result.is_success
+    assert result.error is not None
+
+
+def test_semantic_similarity():
+    """Test AI-powered semantic matching."""
+    result = is_similar_str("What's your name?", "Can you tell me your name?")
+    assert result.is_success
+    assert result.error is None
+
+    result = is_similar_str("What's your name?", "What's your age?")
+    assert not result.is_success
+    assert result.error is not None
+
+
+def test_dict_similarity():
+    """Test dictionary comparison with nested structures."""
+    actual = {"user": {"name": "John"}, "status": "active"}
+    expected = {"user": {"name": "John"}, "status": "active"}
+    result = is_similar_dict(actual, expected)
+    assert result.is_success
+    assert result.error is None
+
+    # Test mismatch
+    actual_bad = {"user": {"name": "Jane"}, "status": "active"}
+    result = is_similar_dict(actual_bad, expected)
+    assert not result.is_success
+    assert result.error is not None
+
+
+def test_list_similarity():
+    """Test list comparison with at least one matching element."""
+    # Matches itself, via str
+    result = is_similar_text("Hello", "Hello")
+    assert result.is_success
+    assert result.error is None
+
+    # Matches itself via list
+    result = is_similar_text(["Hello"], ["Hello"])
+    assert result.is_success
+    assert result.error is None
+
+    # Should not match itself
+    result = is_similar_text("Hello", "Bye")
+    assert not result.is_success
+    assert result.error is not None
+
+    # Matches similarity
+    result = is_similar_text(["Hello"], ["Hi"])
+    assert result.is_success
+    assert result.error is None
+
+    # Tests matches wildcard
+    result = is_similar_text(["Hello"], ["*"])
+    assert result.is_success
+    assert result.error is None
+
+    # Matches similar with multiple
+    result = is_similar_text(
+        ["Hello", "oranges"],
+        [
+            "apples",
+            "Hi",
+        ],
+    )
+    assert result.is_success
+    assert result.error is None
+
+    # Test no match
+    result = is_similar_text(["apples", "oranges"], ["cats", "dogs"])
+    assert not result.is_success
+    assert result.error is not None