cartesia-line 0.1.0a1__tar.gz → 0.1.2__tar.gz

{cartesia_line-0.1.0a1 → cartesia_line-0.1.2}/PKG-INFO

@@ -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.0a1 → cartesia_line-0.1.2}/README.md

@@ -20,9 +20,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.
 
@@ -45,5 +45,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.0a1 → cartesia_line-0.1.2}/cartesia_line.egg-info/PKG-INFO

@@ -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.0a1 → cartesia_line-0.1.2}/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.0a1 → cartesia_line-0.1.2}/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.0a1 → cartesia_line-0.1.2}/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",
 ]

{cartesia_line-0.1.0a1 → cartesia_line-0.1.2}/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:

cartesia_line-0.1.2/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.2/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.2/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)