fast-agent-mcp 0.4.7__py3-none-any.whl

fast_agent/types/conversation_summary.py

@@ -0,0 +1,294 @@
+"""
+Conversation statistics and analysis utilities.
+
+This module provides ConversationSummary for analyzing message history
+and extracting useful statistics like tool call counts, error rates, etc.
+"""
+
+import json
+from collections import Counter
+
+from pydantic import BaseModel, computed_field
+
+from fast_agent.constants import FAST_AGENT_TIMING
+from fast_agent.mcp.helpers.content_helpers import get_text
+from fast_agent.mcp.prompt_message_extended import PromptMessageExtended
+
+
+class ConversationSummary(BaseModel):
+    """
+    Analyzes a conversation's message history and provides computed statistics.
+
+    This class takes a list of PromptMessageExtended messages and provides
+    convenient computed properties for common statistics like tool call counts,
+    error rates, per-tool breakdowns, and timing information.
+
+    Example:
+        ```python
+        from fast_agent import ConversationSummary
+
+        # After running an agent
+        summary = ConversationSummary(agent.message_history)
+
+        # Access computed statistics
+        print(f"Tool calls: {summary.tool_calls}")
+        print(f"Tool errors: {summary.tool_errors}")
+        print(f"Error rate: {summary.tool_error_rate:.1%}")
+        print(f"Tool breakdown: {summary.tool_call_map}")
+
+        # Timing statistics
+        print(f"Total time: {summary.total_elapsed_time_ms}ms")
+        print(f"Avg response time: {summary.average_assistant_response_time_ms}ms")
+
+        # Export to dict for CSV/JSON
+        data = summary.model_dump()
+        ```
+
+    All computed properties are included in .model_dump() for easy serialization.
+    """
+
+    messages: list[PromptMessageExtended]
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def message_count(self) -> int:
+        """Total number of messages in the conversation."""
+        return len(self.messages)
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def user_message_count(self) -> int:
+        """Number of messages from the user."""
+        return sum(1 for msg in self.messages if msg.role == "user")
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def assistant_message_count(self) -> int:
+        """Number of messages from the assistant."""
+        return sum(1 for msg in self.messages if msg.role == "assistant")
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def tool_calls(self) -> int:
+        """Total number of tool calls made across all messages."""
+        return sum(
+            len(msg.tool_calls) for msg in self.messages if msg.tool_calls
+        )
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def tool_errors(self) -> int:
+        """Total number of tool calls that resulted in errors."""
+        return sum(
+            sum(1 for result in msg.tool_results.values() if result.isError)
+            for msg in self.messages if msg.tool_results
+        )
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def tool_successes(self) -> int:
+        """Total number of tool calls that completed successfully."""
+        return sum(
+            sum(1 for result in msg.tool_results.values() if not result.isError)
+            for msg in self.messages if msg.tool_results
+        )
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def tool_error_rate(self) -> float:
+        """
+        Proportion of tool calls that resulted in errors (0.0 to 1.0).
+        Returns 0.0 if there were no tool calls.
+        """
+        total_results = self.tool_errors + self.tool_successes
+        if total_results == 0:
+            return 0.0
+        return self.tool_errors / total_results
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def tool_call_map(self) -> dict[str, int]:
+        """
+        Mapping of tool names to the number of times they were called.
+
+        Example: {"fetch_weather": 3, "calculate": 1}
+        """
+        tool_names: list[str] = []
+        for msg in self.messages:
+            if msg.tool_calls:
+                tool_names.extend(
+                    call.params.name for call in msg.tool_calls.values()
+                )
+        return dict(Counter(tool_names))
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def tool_error_map(self) -> dict[str, int]:
+        """
+        Mapping of tool names to the number of errors they produced.
+
+        Example: {"fetch_weather": 1, "invalid_tool": 2}
+
+        Note: This maps tool call IDs back to their original tool names by
+        finding corresponding CallToolRequest entries in assistant messages.
+        """
+        # First, build a map from tool_id -> tool_name by scanning tool_calls
+        tool_id_to_name: dict[str, str] = {}
+        for msg in self.messages:
+            if msg.tool_calls:
+                for tool_id, call in msg.tool_calls.items():
+                    tool_id_to_name[tool_id] = call.params.name
+
+        # Then, count errors by tool name
+        error_names: list[str] = []
+        for msg in self.messages:
+            if msg.tool_results:
+                for tool_id, result in msg.tool_results.items():
+                    if result.isError:
+                        # Look up the tool name from the tool_id
+                        tool_name = tool_id_to_name.get(tool_id, "unknown")
+                        error_names.append(tool_name)
+
+        return dict(Counter(error_names))
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def has_tool_calls(self) -> bool:
+        """Whether any tool calls were made in this conversation."""
+        return self.tool_calls > 0
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def has_tool_errors(self) -> bool:
+        """Whether any tool errors occurred in this conversation."""
+        return self.tool_errors > 0
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def total_elapsed_time_ms(self) -> float:
+        """
+        Total elapsed time in milliseconds across all assistant message generations.
+
+        This sums the duration_ms from timing data stored in message channels.
+        Only messages with FAST_AGENT_TIMING channel data are included.
+
+        Returns:
+            Total time in milliseconds, or 0.0 if no timing data is available.
+        """
+        total = 0.0
+        for msg in self.messages:
+            if msg.role == "assistant" and msg.channels:
+                timing_blocks = msg.channels.get(FAST_AGENT_TIMING, [])
+                if timing_blocks:
+                    try:
+                        # Parse timing data from first block
+                        timing_text = get_text(timing_blocks[0])
+                        if timing_text:
+                            timing_data = json.loads(timing_text)
+                            total += timing_data.get("duration_ms", 0)
+                    except (json.JSONDecodeError, KeyError, IndexError):
+                        # Skip messages with invalid timing data
+                        continue
+        return total
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def assistant_message_timings(self) -> list[dict[str, float]]:
+        """
+        List of timing data for each assistant message.
+
+        Returns a list of dicts containing start_time, end_time, and duration_ms
+        for each assistant message that has timing data.
+
+        Example:
+            [
+                {"start_time": 1234567890.123, "end_time": 1234567892.456, "duration_ms": 2333.0},
+                {"start_time": 1234567893.789, "end_time": 1234567895.012, "duration_ms": 1223.0},
+            ]
+        """
+        timings = []
+        for msg in self.messages:
+            if msg.role == "assistant" and msg.channels:
+                timing_blocks = msg.channels.get(FAST_AGENT_TIMING, [])
+                if timing_blocks:
+                    try:
+                        timing_text = get_text(timing_blocks[0])
+                        if timing_text:
+                            timing_data = json.loads(timing_text)
+                            timings.append(timing_data)
+                    except (json.JSONDecodeError, KeyError, IndexError):
+                        # Skip messages with invalid timing data
+                        continue
+        return timings
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def average_assistant_response_time_ms(self) -> float:
+        """
+        Average response time in milliseconds for assistant messages.
+
+        Returns:
+            Average time in milliseconds, or 0.0 if no timing data is available.
+        """
+        timings = self.assistant_message_timings
+        if not timings:
+            return 0.0
+        total = sum(t.get("duration_ms", 0) for t in timings)
+        return total / len(timings)
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def first_llm_start_time(self) -> float | None:
+        """
+        Timestamp when the first LLM call started.
+
+        Returns:
+            Unix timestamp (from perf_counter) or None if no timing data.
+        """
+        timings = self.assistant_message_timings
+        if not timings:
+            return None
+        return timings[0].get("start_time")
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def last_llm_end_time(self) -> float | None:
+        """
+        Timestamp when the last LLM call ended.
+
+        Returns:
+            Unix timestamp (from perf_counter) or None if no timing data.
+        """
+        timings = self.assistant_message_timings
+        if not timings:
+            return None
+        return timings[-1].get("end_time")
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def conversation_span_ms(self) -> float:
+        """
+        Wall-clock time from first LLM call start to last LLM call end.
+
+        This represents the active conversation time, including:
+        - All LLM inference time
+        - All tool execution time between LLM calls
+        - Agent orchestration overhead between turns
+
+        This is different from total_elapsed_time_ms which only sums LLM call durations.
+
+        Example:
+            If you have 3 LLM calls (2s, 1.5s, 1s) with tool execution in between:
+            - total_elapsed_time_ms = 4500ms (sum of LLM times only)
+            - conversation_span_ms = 9000ms (first start to last end, includes everything)
+
+        Returns:
+            Time in milliseconds, or 0.0 if no timing data is available.
+        """
+        first_start = self.first_llm_start_time
+        last_end = self.last_llm_end_time
+
+        if first_start is None or last_end is None:
+            return 0.0
+
+        return round((last_end - first_start) * 1000, 2)

fast_agent/types/llm_stop_reason.py

@@ -0,0 +1,78 @@
+"""LLM-related type definitions for fast-agent."""
+
+from enum import Enum
+from typing import Union
+
+
+class LlmStopReason(str, Enum):
+    """
+    Enumeration of stop reasons for LLM message generation.
+
+    Extends the MCP SDK's standard stop reasons with additional custom values.
+    Inherits from str to ensure compatibility with string-based APIs.
+    Used primarily in PromptMessageExtended and LLM response handling.
+    """
+
+    # MCP SDK standard values (from mcp.types.StopReason)
+    END_TURN = "endTurn"
+    STOP_SEQUENCE = "stopSequence"
+    MAX_TOKENS = "maxTokens"
+    TOOL_USE = "toolUse"  # Used when LLM stops to call tools
+    PAUSE = "pause"
+
+    # Custom extensions for fast-agent
+    ERROR = "error"  # Used when there's an error in generation
+    CANCELLED = "cancelled"  # Used when generation is cancelled by user
+
+    TIMEOUT = "timeout"  # Used when generation times out
+    SAFETY = "safety"  # a safety or content warning was triggered
+
+    def __eq__(self, other: object) -> bool:
+        """
+        Allow comparison with both enum members and raw strings.
+
+        This enables code like:
+        - result.stopReason == LlmStopReason.END_TURN
+        - result.stopReason == "endTurn"
+        """
+        if isinstance(other, str):
+            return self.value == other
+        return super().__eq__(other)
+
+    @classmethod
+    def from_string(cls, value: Union[str, "LlmStopReason"]) -> "LlmStopReason":
+        """
+        Convert a string to a LlmStopReason enum member.
+
+        Args:
+            value: A string or LlmStopReason enum member
+
+        Returns:
+            The corresponding LlmStopReason enum member
+
+        Raises:
+            ValueError: If the string doesn't match any enum value
+        """
+        if isinstance(value, cls):
+            return value
+
+        for member in cls:
+            if member.value == value:
+                return member
+
+        raise ValueError(
+            f"Invalid stop reason: {value}. Valid values are: {[m.value for m in cls]}"
+        )
+
+    @classmethod
+    def is_valid(cls, value: str) -> bool:
+        """
+        Check if a string is a valid stop reason.
+
+        Args:
+            value: A string to check
+
+        Returns:
+            True if the string matches a valid stop reason, False otherwise
+        """
+        return value in [member.value for member in cls]

fast_agent/types/message_search.py

@@ -0,0 +1,249 @@
+"""
+Utilities for searching and extracting content from message histories.
+
+This module provides functions to search through PromptMessageExtended lists
+for content matching patterns, with filtering by message role and content type.
+
+Search Scopes:
+--------------
+- "user": Searches in user message content blocks (text content only)
+- "assistant": Searches in assistant message content blocks (text content only)
+- "tool_calls": Searches in tool call names AND stringified arguments
+- "tool_results": Searches in tool result content blocks (text content)
+- "all": Searches all of the above (default)
+
+Note: The search looks at text content extracted with get_text(), not raw ContentBlock objects.
+"""
+
+import re
+from typing import Literal
+
+from fast_agent.mcp.helpers.content_helpers import get_text
+from fast_agent.mcp.prompt_message_extended import PromptMessageExtended
+
+SearchScope = Literal["user", "assistant", "tool_calls", "tool_results", "all"]
+
+
+def search_messages(
+    messages: list[PromptMessageExtended],
+    pattern: str | re.Pattern,
+    scope: SearchScope = "all",
+) -> list[PromptMessageExtended]:
+    """
+    Find messages containing content that matches a pattern.
+
+    Args:
+        messages: List of messages to search
+        pattern: String or compiled regex pattern to search for
+        scope: Where to search - "user", "assistant", "tool_calls", "tool_results", or "all"
+
+    Returns:
+        List of messages that contain at least one match
+
+    Example:
+        ```python
+        # Find messages with error content
+        error_messages = search_messages(
+            agent.message_history,
+            r"error|failed",
+            scope="tool_results"
+        )
+        ```
+    """
+    compiled_pattern = re.compile(pattern) if isinstance(pattern, str) else pattern
+    matching_messages = []
+
+    for msg in messages:
+        if _message_contains_pattern(msg, compiled_pattern, scope):
+            matching_messages.append(msg)
+
+    return matching_messages
+
+
+def find_matches(
+    messages: list[PromptMessageExtended],
+    pattern: str | re.Pattern,
+    scope: SearchScope = "all",
+) -> list[tuple[PromptMessageExtended, re.Match]]:
+    """
+    Find all pattern matches in messages, returning match objects.
+
+    This is useful when you need access to match groups or match positions.
+
+    Args:
+        messages: List of messages to search
+        pattern: String or compiled regex pattern to search for
+        scope: Where to search - "user", "assistant", "tool_calls", "tool_results", or "all"
+
+    Returns:
+        List of (message, match) tuples for each match found
+
+    Example:
+        ```python
+        # Extract job IDs with capture groups
+        matches = find_matches(
+            agent.message_history,
+            r"Job started: ([a-f0-9]+)",
+            scope="tool_results"
+        )
+        for msg, match in matches:
+            job_id = match.group(1)
+            print(f"Found job: {job_id}")
+        ```
+    """
+    compiled_pattern = re.compile(pattern) if isinstance(pattern, str) else pattern
+    results = []
+
+    for msg in messages:
+        matches = _find_in_message(msg, compiled_pattern, scope)
+        for match in matches:
+            results.append((msg, match))
+
+    return results
+
+
+def extract_first(
+    messages: list[PromptMessageExtended],
+    pattern: str | re.Pattern,
+    scope: SearchScope = "all",
+    group: int = 0,
+) -> str | None:
+    """
+    Extract the first match from messages.
+
+    This is a convenience function for the common case of extracting a single value.
+
+    Args:
+        messages: List of messages to search
+        pattern: String or compiled regex pattern to search for
+        scope: Where to search - "user", "assistant", "tool_calls", "tool_results", or "all"
+        group: Regex group to extract (0 = whole match, 1+ = capture groups)
+
+    Returns:
+        Extracted string or None if no match found
+
+    Example:
+        ```python
+        # Extract job ID in one line
+        job_id = extract_first(
+            agent.message_history,
+            r"Job started: ([a-f0-9]+)",
+            scope="tool_results",
+            group=1
+        )
+        ```
+    """
+    matches = find_matches(messages, pattern, scope)
+    if not matches:
+        return None
+
+    _, match = matches[0]
+    return match.group(group)
+
+
+def extract_last(
+    messages: list[PromptMessageExtended],
+    pattern: str | re.Pattern,
+    scope: SearchScope = "all",
+    group: int = 0,
+) -> str | None:
+    """
+    Extract the last match from messages.
+
+    This is useful when you want the most recent occurrence of a pattern,
+    such as the final status update or most recent job ID.
+
+    Args:
+        messages: List of messages to search
+        pattern: String or compiled regex pattern to search for
+        scope: Where to search - "user", "assistant", "tool_calls", "tool_results", or "all"
+        group: Regex group to extract (0 = whole match, 1+ = capture groups)
+
+    Returns:
+        Extracted string or None if no match found
+
+    Example:
+        ```python
+        # Extract the most recent status update
+        final_status = extract_last(
+            agent.message_history,
+            r"Status: (\\w+)",
+            scope="tool_results",
+            group=1
+        )
+        ```
+    """
+    matches = find_matches(messages, pattern, scope)
+    if not matches:
+        return None
+
+    _, match = matches[-1]
+    return match.group(group)
+
+
+def _message_contains_pattern(
+    msg: PromptMessageExtended,
+    pattern: re.Pattern,
+    scope: SearchScope,
+) -> bool:
+    """Check if a message contains the pattern in the specified scope."""
+    texts = _extract_searchable_text(msg, scope)
+    for text in texts:
+        if pattern.search(text):
+            return True
+    return False
+
+
+def _find_in_message(
+    msg: PromptMessageExtended,
+    pattern: re.Pattern,
+    scope: SearchScope,
+) -> list[re.Match]:
+    """Find all matches of pattern in a message."""
+    texts = _extract_searchable_text(msg, scope)
+    matches = []
+    for text in texts:
+        for match in pattern.finditer(text):
+            matches.append(match)
+    return matches
+
+
+def _extract_searchable_text(
+    msg: PromptMessageExtended,
+    scope: SearchScope,
+) -> list[str]:
+    """Extract text from message based on scope."""
+    texts = []
+
+    # User content
+    if scope in ("user", "all") and msg.role == "user":
+        for content in msg.content:
+            text = get_text(content)
+            if text:
+                texts.append(text)
+
+    # Assistant content
+    if scope in ("assistant", "all") and msg.role == "assistant":
+        for content in msg.content:
+            text = get_text(content)
+            if text:
+                texts.append(text)
+
+    # Tool calls (search in tool names and serialized arguments)
+    if scope in ("tool_calls", "all") and msg.tool_calls:
+        for tool_call in msg.tool_calls.values():
+            # Add tool name
+            texts.append(tool_call.params.name)
+            # Add stringified arguments
+            if tool_call.params.arguments:
+                texts.append(str(tool_call.params.arguments))
+
+    # Tool results
+    if scope in ("tool_results", "all") and msg.tool_results:
+        for tool_result in msg.tool_results.values():
+            for content in tool_result.content:
+                text = get_text(content)
+                if text:
+                    texts.append(text)
+
+    return texts

fast_agent/ui/__init__.py

@@ -0,0 +1,38 @@
+"""UI utilities and primitives for interactive console features.
+
+Design goals:
+- Keep import side-effects minimal to avoid circular imports.
+- Make primitives easy to access with lazy attribute loading.
+"""
+
+from typing import Any
+
+__all__ = [
+    "ElicitationForm",
+    "show_simple_elicitation_form",
+    "form_dialog",
+    "ELICITATION_STYLE",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy attribute loader to avoid importing heavy modules at package import time."""
+    if name == "ELICITATION_STYLE":
+        from .elicitation_style import ELICITATION_STYLE as _STYLE
+
+        return _STYLE
+    if name in ("ElicitationForm", "show_simple_elicitation_form", "form_dialog"):
+        from .elicitation_form import (
+            ElicitationForm as _Form,
+        )
+        from .elicitation_form import (
+            show_simple_elicitation_form as _show,
+        )
+
+        if name == "ElicitationForm":
+            return _Form
+        if name == "show_simple_elicitation_form":
+            return _show
+        if name == "form_dialog":
+            return _show
+    raise AttributeError(name)