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

fast_agent/llm/internal/passthrough.py

@@ -0,0 +1,161 @@
+import json  # Import at the module level
+from typing import Any
+
+from mcp import CallToolRequest, Tool
+from mcp.types import CallToolRequestParams, PromptMessage
+
+from fast_agent.core.logging.logger import get_logger
+from fast_agent.core.prompt import Prompt
+from fast_agent.llm.fastagent_llm import (
+    FastAgentLLM,
+    RequestParams,
+)
+from fast_agent.llm.provider_types import Provider
+from fast_agent.llm.usage_tracking import create_turn_usage_from_messages
+from fast_agent.mcp.helpers.content_helpers import get_text
+from fast_agent.types import PromptMessageExtended
+from fast_agent.types.llm_stop_reason import LlmStopReason
+
+CALL_TOOL_INDICATOR = "***CALL_TOOL"
+FIXED_RESPONSE_INDICATOR = "***FIXED_RESPONSE"
+
+
+class PassthroughLLM(FastAgentLLM):
+    """
+    A specialized LLM implementation that simply passes through input messages without modification.
+
+    This is useful for cases where you need an object with the AugmentedLLM interface
+    but want to preserve the original message without any processing, such as in a
+    parallel workflow where no fan-in aggregation is needed.
+    """
+
+    def __init__(
+        self, provider=Provider.FAST_AGENT, name: str = "Passthrough", **kwargs: dict[str, Any]
+    ) -> None:
+        super().__init__(name=name, provider=provider, **kwargs)
+        self.logger = get_logger(__name__)
+        self._messages = [PromptMessage]
+        self._fixed_response: str | None = None
+        self._correlation_id: int = 0
+
+    async def initialize(self) -> None:
+        pass
+
+    def _parse_tool_command(self, command: str) -> tuple[str, dict | None]:
+        """
+        Parse a tool command string into tool name and arguments.
+
+        Args:
+            command: The command string in format "***CALL_TOOL <tool_name> [arguments_json]"
+
+        Returns:
+            Tuple of (tool_name, arguments_dict)
+
+        Raises:
+            ValueError: If command format is invalid
+        """
+        parts = command.split(" ", 2)
+        if len(parts) < 2:
+            raise ValueError("Invalid format. Expected '***CALL_TOOL <tool_name> [arguments_json]'")
+
+        tool_name = parts[1].strip()
+        arguments = None
+
+        if len(parts) > 2:
+            try:
+                arguments = json.loads(parts[2])
+            except json.JSONDecodeError:
+                raise ValueError(f"Invalid JSON arguments: {parts[2]}")
+
+        self.logger.info(f"Calling tool {tool_name} with arguments {arguments}")
+        return tool_name, arguments
+
+    async def _apply_prompt_provider_specific(
+        self,
+        multipart_messages: list["PromptMessageExtended"],
+        request_params: RequestParams | None = None,
+        tools: list[Tool] | None = None,
+        is_template: bool = False,
+    ) -> PromptMessageExtended:
+        # Add messages to history with proper is_prompt flag
+        self.history.extend(multipart_messages, is_prompt=is_template)
+
+        last_message = multipart_messages[-1]
+        # If the caller already provided an assistant reply (e.g., history replay), return it as-is.
+        if last_message.role == "assistant":
+            return last_message
+
+        tool_calls: dict[str, CallToolRequest] = {}
+        stop_reason: LlmStopReason = LlmStopReason.END_TURN
+        if self.is_tool_call(last_message):
+            tool_name, arguments = self._parse_tool_command(last_message.first_text())
+            tool_calls[f"correlationId{self._correlation_id}"] = CallToolRequest(
+                method="tools/call",
+                params=CallToolRequestParams(name=tool_name, arguments=arguments),
+            )
+            self._correlation_id += 1
+            stop_reason = LlmStopReason.TOOL_USE
+
+        if last_message.first_text().startswith(FIXED_RESPONSE_INDICATOR):
+            self._fixed_response = (
+                last_message.first_text().split(FIXED_RESPONSE_INDICATOR, 1)[1].strip()
+            )
+
+        if len(last_message.tool_results or {}) > 0:
+            assert last_message.tool_results
+            concatenated_content = " ".join(
+                [
+                    (get_text(tool_result.content[0]) or "<empty>")
+                    for tool_result in last_message.tool_results.values()
+                ]
+            )
+            result = Prompt.assistant(concatenated_content, stop_reason=stop_reason)
+
+        elif self._fixed_response:
+            result = Prompt.assistant(
+                self._fixed_response, tool_calls=tool_calls, stop_reason=stop_reason
+            )
+        else:
+            # Walk backwards through messages concatenating while role is "user"
+            user_messages = []
+            for message in reversed(multipart_messages):
+                if message.role != "user":
+                    break
+                user_messages.append(message.all_text())
+            concatenated_content = "\n".join(reversed(user_messages))
+
+            result = Prompt.assistant(
+                concatenated_content,
+                tool_calls=tool_calls,
+                stop_reason=stop_reason,
+            )
+
+        turn_usage = create_turn_usage_from_messages(
+            input_content=multipart_messages[-1].all_text(),
+            output_content=result.all_text(),
+            model="passthrough",
+            model_type="passthrough",
+            tool_calls=len(tool_calls),
+            delay_seconds=0.0,
+        )
+        self.usage_accumulator.add_turn(turn_usage)
+
+        return result
+
+    def _convert_extended_messages_to_provider(
+        self, messages: list[PromptMessageExtended]
+    ) -> list[Any]:
+        """
+        Convert PromptMessageExtended list to provider format.
+        For PassthroughLLM, we don't actually make API calls, so this just returns empty list.
+
+        Args:
+            messages: List of PromptMessageExtended objects
+
+        Returns:
+            Empty list (passthrough doesn't use provider-specific messages)
+        """
+        return []
+
+    def is_tool_call(self, message: PromptMessageExtended) -> bool:
+        return message.first_text().startswith(CALL_TOOL_INDICATOR)

fast_agent/llm/internal/playback.py

@@ -0,0 +1,129 @@
+from typing import Any, Type, Union
+
+from mcp import Tool
+from mcp.types import PromptMessage
+
+from fast_agent.core.exceptions import ModelConfigError
+from fast_agent.core.prompt import Prompt
+from fast_agent.interfaces import ModelT
+from fast_agent.llm.internal.passthrough import PassthroughLLM
+from fast_agent.llm.provider_types import Provider
+from fast_agent.llm.usage_tracking import create_turn_usage_from_messages
+from fast_agent.mcp.helpers.content_helpers import normalize_to_extended_list
+from fast_agent.mcp.prompts.prompt_helpers import MessageContent
+from fast_agent.types import PromptMessageExtended, RequestParams
+
+# TODO -- support tool usage/replay
+
+
+class PlaybackLLM(PassthroughLLM):
+    """
+    A specialized LLM implementation that plays back assistant messages when loaded with prompts.
+
+    Unlike the PassthroughLLM which simply passes through messages without modification,
+    PlaybackLLM is designed to simulate a conversation by playing back prompt messages
+    in sequence when loaded with prompts through apply_prompt_template.
+
+    After apply_prompts has been called, each call to generate_str returns the next
+    "ASSISTANT" message in the loaded messages. If no messages are set or all messages have
+    been played back, it returns a message indicating that messages are exhausted.
+    """
+
+    def __init__(self, name: str = "Playback", **kwargs: dict[str, Any]) -> None:
+        super().__init__(name=name, provider=Provider.FAST_AGENT, **kwargs)
+        self._messages: list[PromptMessageExtended] = []
+        self._current_index = -1
+        self._overage = -1
+
+    def _get_next_assistant_message(self) -> PromptMessageExtended:
+        """
+        Get the next assistant message from the loaded messages.
+        Increments the current message index and skips user messages.
+        """
+        # Find next assistant message
+        while self._current_index < len(self._messages):
+            message = self._messages[self._current_index]
+            self._current_index += 1
+            if "assistant" != message.role:
+                continue
+
+            return message
+
+        self._overage += 1
+        return Prompt.assistant(
+            f"MESSAGES EXHAUSTED (list size {len(self._messages)}) ({self._overage} overage)"
+        )
+
+    async def generate(
+        self,
+        messages: Union[
+            str,
+            PromptMessage,
+            PromptMessageExtended,
+            list[Union[str, PromptMessage, PromptMessageExtended]],
+        ],
+        request_params: RequestParams | None = None,
+        tools: list[Tool] | None = None,
+    ) -> PromptMessageExtended:
+        """
+        Handle playback of messages in two modes:
+        1. First call: store messages for playback and return "HISTORY LOADED"
+        2. Subsequent calls: return the next assistant message
+        """
+        # Normalize all input types to a list of PromptMessageExtended
+        multipart_messages = normalize_to_extended_list(messages)
+
+        # If this is the first call (initialization) or we're loading a prompt template
+        # with multiple messages (comes from apply_prompt)
+        if -1 == self._current_index:
+            if len(multipart_messages) > 1:
+                self._messages = multipart_messages
+            else:
+                self._messages.extend(multipart_messages)
+
+            # Reset the index to the beginning for proper playback
+            self._current_index = 0
+
+            # In PlaybackLLM, we always return "HISTORY LOADED" on initialization,
+            # regardless of the prompt content. The next call will return messages.
+            return Prompt.assistant(f"HISTORY LOADED ({len(self._messages)}) messages")
+
+        response = self._get_next_assistant_message()
+
+        # Track usage for this playback "turn"
+        try:
+            input_content = str(multipart_messages) if multipart_messages else ""
+            output_content = MessageContent.get_first_text(response) or ""
+
+            turn_usage = create_turn_usage_from_messages(
+                input_content=input_content,
+                output_content=output_content,
+                model="playback",
+                model_type="playback",
+                tool_calls=0,
+                delay_seconds=0.0,
+            )
+            self.usage_accumulator.add_turn(turn_usage)
+
+        except Exception as e:
+            self.logger.warning(f"Failed to track usage: {e}")
+
+        return response
+
+    async def structured(
+        self,
+        messages: list[PromptMessageExtended],
+        model: Type[ModelT],
+        request_params: RequestParams | None = None,
+    ) -> tuple[ModelT | None, PromptMessageExtended]:
+        """
+        Handle structured requests by returning the next assistant message.
+        """
+
+        if -1 == self._current_index:
+            raise ModelConfigError("Use generate() to load playback history")
+
+        return self._structured_from_multipart(
+            self._get_next_assistant_message(),
+            model,
+        )

fast_agent/llm/internal/silent.py

@@ -0,0 +1,41 @@
+"""Silent LLM implementation that suppresses display output while maintaining functionality."""
+
+from typing import Any
+
+from fast_agent.llm.internal.passthrough import PassthroughLLM
+from fast_agent.llm.provider_types import Provider
+from fast_agent.llm.usage_tracking import TurnUsage, UsageAccumulator
+
+
+class ZeroUsageAccumulator(UsageAccumulator):
+    """Usage accumulator that always reports zero usage."""
+
+    def add_turn(self, turn: TurnUsage) -> None:
+        """Override to do nothing - no usage accumulation."""
+        pass
+
+
+# TODO -- this won't work anymore
+class SilentLLM(PassthroughLLM):
+    """
+    A specialized LLM that processes messages like PassthroughLLM but suppresses all display output.
+
+    This is particularly useful for parallel agent workflows where the fan-in agent
+    should aggregate results without polluting the console with intermediate output.
+    Token counting is disabled - the model always reports zero usage.
+    """
+
+    def __init__(
+        self, provider=Provider.FAST_AGENT, name: str = "Silent", **kwargs: dict[str, Any]
+    ) -> None:
+        super().__init__(name=name, provider=provider, **kwargs)
+        # Override with zero usage accumulator - silent model reports no usage
+        self.usage_accumulator = ZeroUsageAccumulator()
+
+    def show_tool_calls(self, tool_calls: Any, **kwargs) -> None:
+        """Override to suppress tool call display."""
+        pass
+
+    def show_tool_results(self, tool_results: Any, **kwargs) -> None:
+        """Override to suppress tool result display."""
+        pass

fast_agent/llm/internal/slow.py

@@ -0,0 +1,38 @@
+import asyncio
+from typing import Any
+
+from mcp import Tool
+
+from fast_agent.llm.fastagent_llm import (
+    RequestParams,
+)
+from fast_agent.llm.internal.passthrough import PassthroughLLM
+from fast_agent.llm.provider_types import Provider
+from fast_agent.types import PromptMessageExtended
+
+
+class SlowLLM(PassthroughLLM):
+    """
+    A specialized LLM implementation that sleeps for 3 seconds before responding like PassthroughLLM.
+
+    This is useful for testing scenarios where you want to simulate slow responses
+    or for debugging timing-related issues in parallel workflows.
+    """
+
+    def __init__(
+        self, provider=Provider.FAST_AGENT, name: str = "Slow", **kwargs: dict[str, Any]
+    ) -> None:
+        super().__init__(name=name, provider=provider, **kwargs)
+
+    async def _apply_prompt_provider_specific(
+        self,
+        multipart_messages: list["PromptMessageExtended"],
+        request_params: RequestParams | None = None,
+        tools: list[Tool] | None = None,
+        is_template: bool = False,
+    ) -> PromptMessageExtended:
+        """Sleep for 3 seconds then apply prompt like PassthroughLLM."""
+        await asyncio.sleep(3)
+        return await super()._apply_prompt_provider_specific(
+            multipart_messages, request_params, tools, is_template
+        )

fast_agent/llm/memory.py

@@ -0,0 +1,275 @@
+from typing import Generic, Protocol, TypeVar
+
+# Define our own type variable for implementation use
+MessageParamT = TypeVar("MessageParamT")
+
+
+class Memory(Protocol, Generic[MessageParamT]):
+    """
+    Simple memory management for storing past interactions in-memory.
+
+    IMPORTANT: As of the conversation history architecture refactor,
+    provider history is DIAGNOSTIC ONLY. Messages are generated fresh
+    from _message_history on each API call via _convert_to_provider_format().
+
+    The get() method should NOT be called by provider code for API calls.
+    It may still be used for debugging/inspection purposes.
+    """
+
+    # TODO: saqadri - add checkpointing and other advanced memory capabilities
+
+    def __init__(self) -> None: ...
+
+    def extend(self, messages: list[MessageParamT], is_prompt: bool = False) -> None: ...
+
+    def set(self, messages: list[MessageParamT], is_prompt: bool = False) -> None: ...
+
+    def append(self, message: MessageParamT, is_prompt: bool = False) -> None: ...
+
+    def get(self, include_completion_history: bool = True) -> list[MessageParamT]: ...
+
+    def clear(self, clear_prompts: bool = False) -> None: ...
+
+    def pop(self, *, from_prompts: bool = False) -> MessageParamT | None: ...
+
+
+class SimpleMemory(Memory, Generic[MessageParamT]):
+    """
+    Simple memory management for storing past interactions in-memory.
+
+    Maintains both prompt messages (which are always included) and
+    generated conversation history (which is included based on use_history setting).
+    """
+
+    def __init__(self) -> None:
+        self.history: list[MessageParamT] = []
+        self.prompt_messages: list[MessageParamT] = []  # Always included
+        self.conversation_cache_positions: list[
+            int
+        ] = []  # Track active conversation cache positions
+        self.cache_walk_distance: int = 6  # Messages between cache blocks
+        self.max_conversation_cache_blocks: int = 2  # Maximum conversation cache blocks
+
+    def extend(self, messages: list[MessageParamT], is_prompt: bool = False) -> None:
+        """
+        Add multiple messages to history.
+
+        Args:
+            messages: Messages to add
+            is_prompt: If True, add to prompt_messages instead of regular history
+        """
+        if is_prompt:
+            self.prompt_messages.extend(messages)
+        else:
+            self.history.extend(messages)
+
+    def set(self, messages: list[MessageParamT], is_prompt: bool = False) -> None:
+        """
+        Replace messages in history.
+
+        Args:
+            messages: Messages to set
+            is_prompt: If True, replace prompt_messages instead of regular history
+        """
+        if is_prompt:
+            self.prompt_messages = messages.copy()
+        else:
+            self.history = messages.copy()
+
+    def append(self, message: MessageParamT, is_prompt: bool = False) -> None:
+        """
+        Add a single message to history.
+
+        Args:
+            message: Message to add
+            is_prompt: If True, add to prompt_messages instead of regular history
+        """
+        if is_prompt:
+            self.prompt_messages.append(message)
+        else:
+            self.history.append(message)
+
+    def get(self, include_completion_history: bool = True) -> list[MessageParamT]:
+        """
+        Get all messages in memory.
+
+        DEPRECATED: Provider history is now diagnostic only. This method returns
+        a diagnostic snapshot and should NOT be used for API calls. Messages for
+        API calls are generated fresh from _message_history via
+        _convert_to_provider_format().
+
+        Args:
+            include_history: If True, include regular history messages
+                             If False, only return prompt messages
+
+        Returns:
+            Combined list of prompt messages and optionally history messages
+            (for diagnostic/inspection purposes only)
+        """
+        # Note: We don't emit a warning here because this method is still
+        # legitimately used for diagnostic purposes and by some internal code.
+        # The important change is that provider completion methods no longer
+        # call this for API message construction.
+        if include_completion_history:
+            return self.prompt_messages + self.history
+        else:
+            return self.prompt_messages.copy()
+
+    def clear(self, clear_prompts: bool = False) -> None:
+        """
+        Clear history and optionally prompt messages.
+
+        Args:
+            clear_prompts: If True, also clear prompt messages
+        """
+        self.history = []
+        self.conversation_cache_positions = []  # Reset cache positions
+        if clear_prompts:
+            self.prompt_messages = []
+
+    def pop(self, *, from_prompts: bool = False) -> MessageParamT | None:
+        """
+        Remove and return the most recent message from history or prompt messages.
+
+        Args:
+            from_prompts: If True, pop from prompt_messages instead of history
+
+        Returns:
+            The removed message if available, otherwise None
+        """
+        if from_prompts:
+            if not self.prompt_messages:
+                return None
+            return self.prompt_messages.pop()
+
+        if not self.history:
+            return None
+
+        removed = self.history.pop()
+        # Recalculate cache positions now that the history shrank
+        self.conversation_cache_positions = self._calculate_cache_positions(len(self.history))
+        return removed
+
+    def should_apply_conversation_cache(self) -> bool:
+        """
+        Determine if conversation caching should be applied based on walking algorithm.
+
+        Returns:
+            True if we should add or update cache blocks
+        """
+        total_messages = len(self.history)
+
+        # Need at least cache_walk_distance messages to start caching
+        if total_messages < self.cache_walk_distance:
+            return False
+
+        # Check if we need to add a new cache block
+        return len(self._calculate_cache_positions(total_messages)) != len(
+            self.conversation_cache_positions
+        )
+
+    def _calculate_cache_positions(self, total_conversation_messages: int) -> list[int]:
+        """
+        Calculate where cache blocks should be placed using walking algorithm.
+
+        Args:
+            total_conversation_messages: Number of conversation messages (not including prompts)
+
+        Returns:
+            List of positions (relative to conversation start) where cache should be placed
+        """
+        positions = []
+
+        # Place cache blocks every cache_walk_distance messages
+        for i in range(
+            self.cache_walk_distance - 1, total_conversation_messages, self.cache_walk_distance
+        ):
+            positions.append(i)
+            if len(positions) >= self.max_conversation_cache_blocks:
+                break
+
+        # Keep only the most recent cache blocks (walking behavior)
+        if len(positions) > self.max_conversation_cache_blocks:
+            positions = positions[-self.max_conversation_cache_blocks :]
+
+        return positions
+
+    def get_conversation_cache_updates(self) -> dict:
+        """
+        Get cache position updates needed for the walking algorithm.
+
+        Returns:
+            Dict with 'add', 'remove', and 'active' position lists (relative to full message array)
+        """
+        total_conversation_messages = len(self.history)
+        new_positions = self._calculate_cache_positions(total_conversation_messages)
+
+        # Convert to absolute positions (including prompt messages)
+        prompt_offset = len(self.prompt_messages)
+        new_absolute_positions = [pos + prompt_offset for pos in new_positions]
+
+        old_positions_set = set(self.conversation_cache_positions)
+        new_positions_set = set(new_absolute_positions)
+
+        return {
+            "add": sorted(new_positions_set - old_positions_set),
+            "remove": sorted(old_positions_set - new_positions_set),
+            "active": sorted(new_absolute_positions),
+        }
+
+    def apply_conversation_cache_updates(self, updates: dict) -> None:
+        """
+        Apply cache position updates.
+
+        Args:
+            updates: Dict from get_conversation_cache_updates()
+        """
+        self.conversation_cache_positions = updates["active"].copy()
+
+    def remove_cache_control_from_messages(
+        self, messages: list[MessageParamT], positions: list[int]
+    ) -> None:
+        """
+        Remove cache control from specified message positions.
+
+        Args:
+            messages: The message array to modify
+            positions: List of positions to remove cache control from
+        """
+        for pos in positions:
+            if pos < len(messages):
+                message = messages[pos]
+                if isinstance(message, dict) and "content" in message:
+                    content_list = message["content"]
+                    if isinstance(content_list, list):
+                        for content_block in content_list:
+                            if isinstance(content_block, dict) and "cache_control" in content_block:
+                                del content_block["cache_control"]
+
+    def add_cache_control_to_messages(
+        self, messages: list[MessageParamT], positions: list[int]
+    ) -> int:
+        """
+        Add cache control to specified message positions.
+
+        Args:
+            messages: The message array to modify
+            positions: List of positions to add cache control to
+
+        Returns:
+            Number of cache blocks successfully applied
+        """
+        applied_count = 0
+        for pos in positions:
+            if pos < len(messages):
+                message = messages[pos]
+                if isinstance(message, dict) and "content" in message:
+                    content_list = message["content"]
+                    if isinstance(content_list, list) and content_list:
+                        # Apply cache control to the last content block
+                        for content_block in reversed(content_list):
+                            if isinstance(content_block, dict):
+                                content_block["cache_control"] = {"type": "ephemeral"}
+                                applied_count += 1
+                                break
+        return applied_count