cartesia-line 0.1.0a1__py3-none-any.whl → 0.1.2__py3-none-any.whl

{cartesia_line-0.1.0a1.dist-info → cartesia_line-0.1.2.dist-info}/METADATA

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: cartesia-line
-Version: 0.1.0a1
+Version: 0.1.2
 Summary: Cartesia Voice Agents SDK
 Author-email: "Cartesia AI, Inc." <support@cartesia.ai>
 License: Apache 2.0
 Project-URL: Repository, https://github.com/cartesia-ai/line
-Project-URL: Documentation, https://docs.cartesia.ai/line
+Project-URL: Documentation, https://docs.cartesia.ai/line/
 Project-URL: Homepage, https://cartesia.ai/agents
 Keywords: voice,agents,ai,cartesia
 Classifier: Development Status :: 4 - Beta
@@ -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"
@@ -65,9 +67,9 @@ Build intelligent, low-latency voice agents with background reasoning.
 
 ## Quickstart (< 5 minutes)
 
-The Line SDK is designed to be used with the Cartesia [Line platform](https://cartesia.ai/line).
+The Line SDK is designed to be used with the Cartesia's voice agent platform [Line](https://cartesia.ai/agents).
 - Create a [Cartesia account](https://play.cartesia.ai).
-- Follow the [quickstart guide](https://docs.cartesia.ai/).
+- Follow the [quickstart guide](https://docs.cartesia.ai/line/start-building/talk-to-your-first-agent).
 
 And you'll be able to make your first voice call in a few minutes.
 
@@ -90,5 +92,9 @@ pip install cartesia-line
 ## Going Deeper
 
 - **More examples**: [examples/](examples/) - See all available examples and patterns
-- **Full API reference**: [docs.cartesia.ai/line](https://docs.cartesia.ai/)
+- **3rd party integrations**: [example_integrations/](example_integrations/) - See example integrations for external services
+
+  > [!NOTE]
+  > While Cartesia approves each example, they are implemented and maintained by our partners.
+- **Full API reference**: [docs.cartesia.ai/line](https://docs.cartesia.ai/line/)
 - **Get help**: [Discord community](https://discord.gg/cartesia)

cartesia_line-0.1.2.dist-info/RECORD

@@ -0,0 +1,32 @@
+cartesia_line-0.1.2.dist-info/licenses/LICENSE,sha256=ElpXuEGJlZ5XPeLe_tLbAmiEVE79EGxdy-aMw3JxE_Y,11347
+line/__init__.py,sha256=3gv8DHGZLy1wDWc7c07UWLIID-TojCvkslgzOjq_HAs,953
+line/bridge.py,sha256=KjaZxEA1QuqtTASej5mYhe6C9OJdpu85b9jcEsBxMvA,14233
+line/bus.py,sha256=AGMwHCNftVeWDzl0o1Jd2iDm51q1FTBEOlJzGZLub1Q,14324
+line/call_request.py,sha256=JfYS4bAicuwjTHMXdK_PYbvSPj1dht44282yZACGUbU,847
+line/events.py,sha256=ZHG1lJuRAACLyqUizqmntBkjAp1bxiEetiIuZBUfDpI,5897
+line/harness.py,sha256=vw6AhsQwODxtnHBW0Q-wTxnqxlUhV8KoZHMJMuTjTyg,9100
+line/harness_types.py,sha256=Lwu1n2fAA5o-b_PjLWDSMu4G-GYEpb3X1CAUy3pvelk,2214
+line/routes.py,sha256=jR_bl96ujx5MYzdVb9YLkcAITCboosM9UM7f4Et9eBc,24446
+line/user_bridge.py,sha256=Hwml4NC_tZbSPPG5rCOdtjBmlGa53rf4L4n5zpF8iUs,7888
+line/voice_agent_app.py,sha256=xlhtc9ZER2v5hOOWHz9W8e9jALlMAz_OvEcJL5QCNsQ,5421
+line/voice_agent_system.py,sha256=8yywrjKdO43s7UkKqIs0jqte27vOF96NYnuGILsJz7k,8002
+line/evals/__init__.py,sha256=zMvJkOMMhd19bcrkH0ZjR4nQ5vjKvPA0ncOFzDe5hv4,226
+line/evals/conversation_runner.py,sha256=lS4IX3pWNjcIEPJsFgfTCoy-CAo986ELYjUfEcC8J7g,7482
+line/evals/similarity_utils.py,sha256=U7LJiCM_dKUC1uOJkhpSS4kD7IZzdOrAisDqsujIIMc,10624
+line/evals/turn.py,sha256=IpEsqnON9JXlzStAcy9YUuE52X4o77V2kLXSJUsW_Tk,8271
+line/nodes/__init__.py,sha256=Rp-9gxMZ4hCTjbm6zaiTTBz6lg9d32UwxJgWTJfhnZU,128
+line/nodes/base.py,sha256=HKfv_j3H-E-cwhtK9La1DUNmYdtbGUNeo-c51TGIQKM,1897
+line/nodes/conversation_context.py,sha256=1ytf4q5GGy6tEjVD_KbKAkKLqosCkwi0kVWGymuLJhw,2138
+line/nodes/reasoning.py,sha256=kyXxk6xJHEA4zwkHzriRtOC6cjk13E-N736qDvR5o-A,8567
+line/tools/__init__.py,sha256=mYzcKIk1G_-EFQD6ugoCdcPjgywK_mC4dXu-ZyAtS7U,203
+line/tools/system_tools.py,sha256=1RkZv_iGAF2LvR3ddoa7Cz4VmC_Xh-BPjmQGKdCu5Fc,8680
+line/tools/tool_types.py,sha256=JJ6mfH9wB-dtaQFHkm8vsJIYsAiW6bIpgAh_nmDn744,1066
+line/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+line/utils/aio.py,sha256=l1YgZ8tf1KtOyq6A-6RA_kE-FKGafDfHERFnDx0-PxM,1899
+line/utils/gemini_utils.py,sha256=6YNyU3-I6Kn95j0qMroelO1WpjIPjIwhiub2lX34-kY,5396
+line/utils/openai_utils.py,sha256=I9nIpHTFC98ChWzRmV-enMSIcicRVF9KYjifsWkoPCE,3596
+line/utils/str.py,sha256=b0HCAMdqHh5S8KVulqLwT3x7dj6Tdgaw2WNPAw1gzEY,860
+cartesia_line-0.1.2.dist-info/METADATA,sha256=N5HIRt1IS6Xcr3WoEYH8gq6887LyrjtRNmeChZYzzR4,4402
+cartesia_line-0.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+cartesia_line-0.1.2.dist-info/top_level.txt,sha256=xztzr4hR6ekbxrTcEufazgor-5McHQuLNu82cxn1jNE,5
+cartesia_line-0.1.2.dist-info/RECORD,,

line/__init__.py

@@ -3,6 +3,7 @@
 from line.bridge import Bridge
 from line.bus import Bus, Message
 from line.call_request import CallRequest, PreCallResult
+from line.evals import AgentTurn, ConversationRunner, Turn, UserTurn
 from line.nodes.conversation_context import ConversationContext
 
 # Reasoning components
@@ -26,4 +27,9 @@ __all__ = [
     "VoiceAgentApp",
     "VoiceAgentSystem",
     "register_observability_event",
+    "AgentTurn",
+    "ConversationRunner",
+    "Turn",
+    "UserTurn",
+    "SimilarityUtils",
 ]

line/bridge.py

@@ -13,7 +13,11 @@ from typing import TYPE_CHECKING, Any, Callable, List, Optional, Type, TypeVar,
 from loguru import logger
 
 from line.bus import Bus, Message
-from line.events import EventInstance, EventsRegistry, EventTypeOrAlias
+from line.events import (
+    EventInstance,
+    EventsRegistry,
+    EventTypeOrAlias,
+)
 from line.routes import RouteBuilder, RouteHandler
 
 if TYPE_CHECKING:

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",
+]

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

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)

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]

line/events.py

@@ -38,6 +38,9 @@ __all__ = [
     "AgentSpeechSent",
     "UserUnknownInputReceived",
     "LogMetric",
+    "DTMFInputEvent",
+    "DTMFOutputEvent",
+    "DTMFStoppedEvent",
 ]
 
 
@@ -131,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):
@@ -183,6 +185,22 @@ class LogMetric(BaseModel):
     value: Any
 
 
+class DTMFInputEvent(BaseModel):
+    """DTMF event for tracking DTMF input."""
+
+    button: str
+
+
+class DTMFOutputEvent(BaseModel):
+    """DTMF event for tracking DTMF input."""
+
+    button: str
+
+
+class DTMFStoppedEvent(BaseModel):
+    """DTMF stopped event for tracking DTMF input."""
+
+
 class _EventsRegistry:
     """A singleton registry of all events.
 

line/harness.py

@@ -16,6 +16,7 @@ from line.events import (
     AgentSpeechSent,
     AgentStartedSpeaking,
     AgentStoppedSpeaking,
+    DTMFInputEvent,
     UserStartedSpeaking,
     UserStoppedSpeaking,
     UserTranscriptionReceived,
@@ -24,6 +25,8 @@ from line.events import (
 from line.harness_types import (
     AgentSpeechInput,
     AgentStateInput,
+    DTMFInput,
+    DTMFOutput,
     EndCallOutput,
     ErrorOutput,
     InputMessage,
@@ -140,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):
@@ -199,6 +202,15 @@ class ConversationHarness:
         logger.debug(f"📈 Logging metric: {name}={value}")
         await self._send(LogMetricOutput(name=name, value=value))
 
+    async def send_dtmf(self, button: str):
+        """
+        Send a DTMF event via WebSocket
+
+        Args:
+            button: The DTMF button to send
+        """
+        await self._send(DTMFOutput(button=button))
+
     async def cleanup(self):
         """
         Clean up resources and stop all tasks
@@ -249,6 +261,9 @@ class ConversationHarness:
         elif isinstance(message, AgentSpeechInput):
             logger.info(f'🗣️ Agent speech sent: "{message.content}"')
             return [AgentSpeechSent(content=message.content)]
+        elif isinstance(message, DTMFInput):
+            logger.info(f"🔔 DTMF received: {message.button}")
+            return [DTMFInputEvent(button=message.button)]
         else:
             # Fallback for unknown types.
             logger.warning(f"Unknown message type: {type(message).__name__} ({message.model_dump_json()})")

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
@@ -118,3 +119,141 @@ async def end_call(
 
     # End the call
     yield EndCall()
+
+
+class DTMFToolCall(ToolDefinition):
+    """Arguments for the dtmf_tool_call tool."""
+
+    @classmethod
+    def name(cls) -> str:
+        return "dtmf_tool_call"
+
+    @classmethod
+    def description(cls) -> str:
+        return (
+            "Send a DTMF tone to the user. Use this when you find the "
+            "appropriate selection and the voice system asks you to press a button"
+        )
+
+    @classmethod
+    def parameters_description(cls) -> str:
+        return "The DTMF button to send"
+
+    @classmethod
+    def to_gemini_tool(cls) -> "gemini_types.Tool":
+        """Convert to Gemini tool format"""
+        return gemini_types.Tool(
+            function_declarations=[
+                gemini_types.FunctionDeclaration(
+                    name=cls.name(),
+                    description=cls.description(),
+                    parameters={
+                        "type": "object",
+                        "properties": {
+                            "button": {
+                                "type": "string",
+                                "description": cls.parameters_description(),
+                                "enum": ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "*", "#"],
+                            }
+                        },
+                        "required": ["button"],
+                    },
+                )
+            ]
+        )
+
+    @classmethod
+    def to_openai_tool(cls) -> 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": cls.name(),
+            "description": cls.description(),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "button": {
+                        "type": "string",
+                        "enum": ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "*", "#"],
+                        "description": cls.parameters_description(),
+                    },
+                },
+                "required": ["button"],
+                "additionalProperties": False,
+                "strict": True,
+            },
+        }
+
+
+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,
+            },
+        }

line/user_bridge.py

@@ -44,6 +44,7 @@ from line.events import (
     AgentError,
     AgentResponse,
     Authorize,
+    DTMFOutputEvent,
     EndCall,
     EventType,
     LogMetric,
@@ -104,13 +105,18 @@ 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."""
         event: LogMetric = message.event
         return await harness.log_metric(event.name, event.value)
 
+    async def send_dtmf(message: Message):
+        """Send DTMF event to harness."""
+        event: DTMFOutputEvent = message.event
+        return await harness.send_dtmf(event.button)
+
     bridge = (
         Bridge(harness)
         .with_input_routing(harness)  # Enable WebSocket → bus event routing
@@ -132,6 +138,8 @@ def create_user_bridge(harness: "ConversationHarness", authorized_node: str) ->
         .map(send_transfer_call)
         .on(LogMetric)
         .map(send_log_metric)
+        .on(DTMFOutputEvent)
+        .map(send_dtmf)
     )
 
     # Add authorization handler after creation.

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.0a1.dist-info/RECORD

@@ -1,27 +0,0 @@
-cartesia_line-0.1.0a1.dist-info/licenses/LICENSE,sha256=ElpXuEGJlZ5XPeLe_tLbAmiEVE79EGxdy-aMw3JxE_Y,11347
-line/__init__.py,sha256=glA0fvCL2xBmgC1cXZbiv6wcXS-yod7ctcL3EnoeEIk,790
-line/bridge.py,sha256=53N5UizGKjrb6iR27OQbTtjgQZ-rNLjEJT0HqQiLa-M,14216
-line/bus.py,sha256=AGMwHCNftVeWDzl0o1Jd2iDm51q1FTBEOlJzGZLub1Q,14324
-line/call_request.py,sha256=JfYS4bAicuwjTHMXdK_PYbvSPj1dht44282yZACGUbU,847
-line/events.py,sha256=d_CtDTGvLyMwFjdO97FtpTwyBO8uSmCzB2CC7hYagiQ,5565
-line/harness.py,sha256=_4TJV3J2Sxdhz5JSuWXlthZLNmhfNlddHANzOLGjtec,8620
-line/harness_types.py,sha256=Lwu1n2fAA5o-b_PjLWDSMu4G-GYEpb3X1CAUy3pvelk,2214
-line/routes.py,sha256=jR_bl96ujx5MYzdVb9YLkcAITCboosM9UM7f4Et9eBc,24446
-line/user_bridge.py,sha256=etnvSMALCDB7JOguW0imd41RSH3sHJ-oBHH2Hr7kSeQ,7620
-line/voice_agent_app.py,sha256=xlhtc9ZER2v5hOOWHz9W8e9jALlMAz_OvEcJL5QCNsQ,5421
-line/voice_agent_system.py,sha256=8yywrjKdO43s7UkKqIs0jqte27vOF96NYnuGILsJz7k,8002
-line/nodes/__init__.py,sha256=Rp-9gxMZ4hCTjbm6zaiTTBz6lg9d32UwxJgWTJfhnZU,128
-line/nodes/base.py,sha256=HKfv_j3H-E-cwhtK9La1DUNmYdtbGUNeo-c51TGIQKM,1897
-line/nodes/conversation_context.py,sha256=1ytf4q5GGy6tEjVD_KbKAkKLqosCkwi0kVWGymuLJhw,2138
-line/nodes/reasoning.py,sha256=kyXxk6xJHEA4zwkHzriRtOC6cjk13E-N736qDvR5o-A,8567
-line/tools/__init__.py,sha256=mYzcKIk1G_-EFQD6ugoCdcPjgywK_mC4dXu-ZyAtS7U,203
-line/tools/system_tools.py,sha256=Z0tDoaAtZ9GziBLSDklhE6NS91OoHrmGkgToP5nZD_o,3765
-line/tools/tool_types.py,sha256=JJ6mfH9wB-dtaQFHkm8vsJIYsAiW6bIpgAh_nmDn744,1066
-line/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-line/utils/aio.py,sha256=l1YgZ8tf1KtOyq6A-6RA_kE-FKGafDfHERFnDx0-PxM,1899
-line/utils/gemini_utils.py,sha256=6YNyU3-I6Kn95j0qMroelO1WpjIPjIwhiub2lX34-kY,5396
-line/utils/openai_utils.py,sha256=I9nIpHTFC98ChWzRmV-enMSIcicRVF9KYjifsWkoPCE,3596
-cartesia_line-0.1.0a1.dist-info/METADATA,sha256=_47ursMi_LDtkwhqeKmOjbQFy51r6JQMzL_iptiVf1M,4001
-cartesia_line-0.1.0a1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-cartesia_line-0.1.0a1.dist-info/top_level.txt,sha256=xztzr4hR6ekbxrTcEufazgor-5McHQuLNu82cxn1jNE,5
-cartesia_line-0.1.0a1.dist-info/RECORD,,