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

fast_agent/mcp/prompts/prompt_helpers.py

@@ -0,0 +1,238 @@
+"""
+Helper functions for working with PromptMessage and PromptMessageExtended objects.
+
+These utilities simplify extracting content from nested message structures
+without repetitive type checking.
+"""
+
+from typing import Union, cast
+
+from mcp.types import (
+    EmbeddedResource,
+    PromptMessage,
+    TextContent,
+)
+
+from fast_agent.mcp.helpers.content_helpers import get_image_data, get_text
+
+# Forward reference for PromptMessageExtended, actual import happens at runtime
+PromptMessageExtendedType = Union[object]  # Will be replaced with actual type
+try:
+    from fast_agent.types import PromptMessageExtended
+
+    PromptMessageExtendedType = PromptMessageExtended
+except ImportError:
+    # During initialization, there might be a circular import.
+    # We'll handle this gracefully.
+    pass
+
+
+class MessageContent:
+    """
+    Helper class for working with message content in both PromptMessage and
+    PromptMessageExtended objects.
+    """
+
+    @staticmethod
+    def get_all_text(message: Union[PromptMessage, "PromptMessageExtended"]) -> list[str]:
+        """
+        Extract all text content from a message.
+
+        Args:
+            message: A PromptMessage or PromptMessageExtended
+
+        Returns:
+            List of text strings from all text content parts
+        """
+        if isinstance(message, PromptMessage):
+            text = get_text(message.content)
+            return [text] if text is not None else []
+
+        result = []
+        for content in message.content:
+            text = get_text(content)
+            if text is not None:
+                result.append(text)
+
+        return result
+
+    @staticmethod
+    def join_text(
+        message: Union[PromptMessage, "PromptMessageExtended"], separator: str = "\n\n"
+    ) -> str:
+        """
+        Join all text content in a message with a separator.
+
+        Args:
+            message: A PromptMessage or PromptMessageExtended
+            separator: String to use as separator (default: newlines)
+
+        Returns:
+            Joined text string
+        """
+        return separator.join(MessageContent.get_all_text(message))
+
+    @staticmethod
+    def get_first_text(message: Union[PromptMessage, "PromptMessageExtended"]) -> str | None:
+        """
+        Get the first available text content from a message.
+
+        Args:
+            message: A PromptMessage or PromptMessageExtended
+
+        Returns:
+            First text content or None if no text content exists
+        """
+        if isinstance(message, PromptMessage):
+            return get_text(message.content)
+
+        for content in message.content:
+            text = get_text(content)
+            if text is not None:
+                return text
+
+        return None
+
+    @staticmethod
+    def has_text_at_first_position(message: Union[PromptMessage, "PromptMessageExtended"]) -> bool:
+        """
+        Check if a message has a TextContent at the first position.
+        This is a common case when dealing with messages that start with text.
+
+        Args:
+            message: A PromptMessage or PromptMessageExtended
+
+        Returns:
+            True if the message has TextContent at first position, False otherwise
+        """
+        if isinstance(message, PromptMessage):
+            return isinstance(message.content, TextContent)
+
+        # For multipart messages, check if there's at least one item and the first is TextContent
+        return bool(message.content) and isinstance(message.content[0], TextContent)
+
+    @staticmethod
+    def get_text_at_first_position(
+        message: Union[PromptMessage, "PromptMessageExtended"],
+    ) -> str | None:
+        """
+        Get the text from the first position of a message if it's TextContent.
+
+        Args:
+            message: A PromptMessage or PromptMessageExtended
+
+        Returns:
+            The text content at the first position if it's TextContent,
+            None otherwise
+        """
+        if not MessageContent.has_text_at_first_position(message):
+            return None
+
+        if isinstance(message, PromptMessage):
+            return cast("TextContent", message.content).text
+
+        # Safe to cast since we've verified the first item is TextContent
+        return cast("TextContent", message.content[0]).text
+
+    @staticmethod
+    def get_all_images(message: Union[PromptMessage, "PromptMessageExtended"]) -> list[str]:
+        """
+        Extract all image data from a message.
+
+        Args:
+            message: A PromptMessage or PromptMessageExtended
+
+        Returns:
+            List of image data strings from all image content parts
+        """
+        if isinstance(message, PromptMessage):
+            img_data = get_image_data(message.content)
+            return [img_data] if img_data is not None else []
+
+        result = []
+        for content in message.content:
+            img_data = get_image_data(content)
+            if img_data is not None:
+                result.append(img_data)
+
+        return result
+
+    @staticmethod
+    def get_first_image(message: Union[PromptMessage, "PromptMessageExtended"]) -> str | None:
+        """
+        Get the first available image data from a message.
+
+        Args:
+            message: A PromptMessage or PromptMessageExtended
+
+        Returns:
+            First image data or None if no image content exists
+        """
+        if isinstance(message, PromptMessage):
+            return get_image_data(message.content)
+
+        for content in message.content:
+            img_data = get_image_data(content)
+            if img_data is not None:
+                return img_data
+
+        return None
+
+    @staticmethod
+    def get_all_resources(
+        message: Union[PromptMessage, "PromptMessageExtended"],
+    ) -> list[EmbeddedResource]:
+        """
+        Extract all embedded resources from a message.
+
+        Args:
+            message: A PromptMessage or PromptMessageExtended
+
+        Returns:
+            List of EmbeddedResource objects
+        """
+        if isinstance(message, PromptMessage):
+            if isinstance(message.content, EmbeddedResource):
+                return [message.content]
+            return []
+
+        return [content for content in message.content if isinstance(content, EmbeddedResource)]
+
+    @staticmethod
+    def has_text(message: Union[PromptMessage, "PromptMessageExtended"]) -> bool:
+        """
+        Check if the message has any text content.
+
+        Args:
+            message: A PromptMessage or PromptMessageExtended
+
+        Returns:
+            True if the message has text content, False otherwise
+        """
+        return len(MessageContent.get_all_text(message)) > 0
+
+    @staticmethod
+    def has_images(message: Union[PromptMessage, "PromptMessageExtended"]) -> bool:
+        """
+        Check if the message has any image content.
+
+        Args:
+            message: A PromptMessage or PromptMessageExtended
+
+        Returns:
+            True if the message has image content, False otherwise
+        """
+        return len(MessageContent.get_all_images(message)) > 0
+
+    @staticmethod
+    def has_resources(message: Union[PromptMessage, "PromptMessageExtended"]) -> bool:
+        """
+        Check if the message has any embedded resources.
+
+        Args:
+            message: A PromptMessage or PromptMessageExtended
+
+        Returns:
+            True if the message has embedded resources, False otherwise
+        """
+        return len(MessageContent.get_all_resources(message)) > 0

fast_agent/mcp/prompts/prompt_load.py

@@ -0,0 +1,186 @@
+from pathlib import Path
+from typing import Literal
+
+from mcp.server.fastmcp.prompts.base import (
+    AssistantMessage,
+    Message,
+    UserMessage,
+)
+from mcp.types import PromptMessage, TextContent
+
+from fast_agent.core.logging.logger import get_logger
+from fast_agent.interfaces import AgentProtocol
+from fast_agent.mcp import mime_utils, resource_utils
+from fast_agent.mcp.prompts.prompt_template import (
+    PromptContent,
+)
+from fast_agent.types import PromptMessageExtended
+
+# Define message role type
+MessageRole = Literal["user", "assistant"]
+logger = get_logger("prompt_load")
+
+
+def cast_message_role(role: str) -> MessageRole:
+    """Cast a string role to a MessageRole literal type"""
+    if role == "user" or role == "assistant":
+        return role  # type: ignore
+    # Default to user if the role is invalid
+    logger.warning(f"Invalid message role: {role}, defaulting to 'user'")
+    return "user"
+
+
+def create_messages_with_resources(
+    content_sections: list[PromptContent], prompt_files: list[Path]
+) -> list[PromptMessage]:
+    """
+    Create a list of messages from content sections, with resources properly handled.
+
+    This implementation produces one message for each content section's text,
+    followed by separate messages for each resource (with the same role type
+    as the section they belong to).
+
+    Args:
+        content_sections: List of PromptContent objects
+        prompt_files: List of prompt files (to help locate resource files)
+
+    Returns:
+        List of Message objects
+    """
+
+    messages = []
+
+    for section in content_sections:
+        # Convert to our literal type for role
+        role = cast_message_role(section.role)
+
+        # Add the text message
+        messages.append(create_content_message(section.text, role))
+
+        # Add resource messages with the same role type as the section
+        for resource_path in section.resources:
+            try:
+                # Load resource with information about its type
+                resource_content, mime_type, is_binary = resource_utils.load_resource_content(
+                    resource_path, prompt_files
+                )
+
+                # Create and add the resource message
+                resource_message = create_resource_message(
+                    resource_path, resource_content, mime_type, is_binary, role
+                )
+                messages.append(resource_message)
+            except Exception as e:
+                logger.error(f"Error loading resource {resource_path}: {e}")
+
+    return messages
+
+
+def create_content_message(text: str, role: MessageRole) -> PromptMessage:
+    """Create a text content message with the specified role"""
+    return PromptMessage(role=role, content=TextContent(type="text", text=text))
+
+
+def create_resource_message(
+    resource_path: str, content: str, mime_type: str, is_binary: bool, role: MessageRole
+) -> Message:
+    """Create a resource message with the specified content and role"""
+    message_class = UserMessage if role == "user" else AssistantMessage
+
+    if mime_utils.is_image_mime_type(mime_type):
+        # For images, create an ImageContent
+        image_content = resource_utils.create_image_content(data=content, mime_type=mime_type)
+        return message_class(content=image_content)
+    else:
+        # For other resources, create an EmbeddedResource
+        embedded_resource = resource_utils.create_embedded_resource(
+            resource_path, content, mime_type, is_binary
+        )
+        return message_class(content=embedded_resource)
+
+
+def load_prompt(file: Path | str) -> list[PromptMessageExtended]:
+    """
+    Load a prompt from a file and return as PromptMessageExtended objects.
+
+    The loader uses file extension to determine the format:
+    - .json files are loaded using enhanced format that preserves tool_calls, channels, etc.
+    - All other files are loaded using the template-based delimited format with resource loading
+
+    Args:
+        file: Path to the prompt file (Path object or string)
+
+    Returns:
+        List of PromptMessageExtended objects with full conversation state
+    """
+    if isinstance(file, str):
+        file = Path(file)
+    path_str = str(file).lower()
+
+    if path_str.endswith(".json"):
+        # JSON files use the serialization module directly
+        from fast_agent.mcp.prompt_serialization import load_messages
+
+        return load_messages(str(file))
+    else:
+        # Non-JSON files need template processing for resource loading
+        from fast_agent.mcp.prompts.prompt_template import PromptTemplateLoader
+
+        loader = PromptTemplateLoader()
+        template = loader.load_from_file(file)
+
+        # Render the template without arguments to get the messages
+        messages = create_messages_with_resources(
+            template.content_sections,
+            [file],  # Pass the file path for resource resolution
+        )
+
+        # Convert to PromptMessageExtended
+        return PromptMessageExtended.to_extended(messages)
+
+
+def load_prompt_as_get_prompt_result(file: Path):
+    """
+    Load a prompt from a file and convert to GetPromptResult format for MCP compatibility.
+
+    This loses extended fields (tool_calls, channels, etc.) but provides
+    compatibility with MCP prompt servers.
+
+    Args:
+        file: Path to the prompt file
+
+    Returns:
+        GetPromptResult object for MCP compatibility
+    """
+    from fast_agent.mcp.prompt_serialization import to_get_prompt_result
+
+    # Load with full data
+    messages = load_prompt(file)
+
+    # Convert to GetPromptResult (loses extended fields)
+    return to_get_prompt_result(messages)
+
+
+def load_history_into_agent(agent: AgentProtocol, file_path: Path) -> None:
+    """
+    Load conversation history directly into agent without triggering LLM call.
+
+    This function restores saved conversation state by directly setting the
+    agent's _message_history. No LLM API calls are made.
+
+    Args:
+        agent: Agent instance to restore history into (FastAgentLLM or subclass)
+        file_path: Path to saved history file (JSON or template format)
+
+    Note:
+        - The agent's history is cleared before loading
+        - Provider diagnostic history will be updated on the next API call
+        - Templates are NOT cleared by this function
+    """
+    messages = load_prompt(file_path)
+
+    # Direct restoration - no LLM call
+    agent.clear(clear_prompts=True)
+    agent.message_history.extend(messages)
+
+    # Note: Provider diagnostic history will be updated on next API call