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

fast_agent/mcp/prompts/prompt_template.py

@@ -0,0 +1,438 @@
+"""
+Prompt Template Module
+
+Handles prompt templating, variable extraction, and substitution for the prompt server.
+Provides clean, testable classes for managing template substitution.
+"""
+
+import re
+from pathlib import Path
+from typing import Any, Literal
+
+from mcp.types import (
+    EmbeddedResource,
+    TextContent,
+    TextResourceContents,
+)
+from pydantic import BaseModel, field_validator
+
+from fast_agent.mcp.prompt_serialization import (
+    multipart_messages_to_delimited_format,
+)
+from fast_agent.mcp.prompts.prompt_constants import (
+    ASSISTANT_DELIMITER,
+    DEFAULT_DELIMITER_MAP,
+    RESOURCE_DELIMITER,
+    USER_DELIMITER,
+)
+from fast_agent.types import PromptMessageExtended
+
+
+class PromptMetadata(BaseModel):
+    """Metadata about a prompt file"""
+
+    name: str
+    description: str
+    template_variables: set[str] = set()
+    resource_paths: list[str] = []
+    file_path: Path
+
+
+# Define valid message roles for better type safety
+MessageRole = Literal["user", "assistant"]
+
+
+class PromptContent(BaseModel):
+    """Content of a prompt, which may include template variables"""
+
+    text: str
+    role: str = "user"
+    resources: list[str] = []
+
+    @field_validator("role")
+    @classmethod
+    def validate_role(cls, role: str) -> str:
+        """Validate that the role is a known value"""
+        if role not in ("user", "assistant"):
+            raise ValueError(f"Invalid role: {role}. Must be one of: user, assistant")
+        return role
+
+    def apply_substitutions(self, context: dict[str, Any]) -> "PromptContent":
+        """Apply variable substitutions to the text and resources"""
+
+        # Define placeholder pattern once to avoid repetition
+        def make_placeholder(key: str) -> str:
+            return f"{{{{{key}}}}}"
+
+        # Apply substitutions to text
+        result = self.text
+        for key, value in context.items():
+            result = result.replace(make_placeholder(key), str(value))
+
+        # Apply substitutions to resource paths
+        substituted_resources = []
+        for resource in self.resources:
+            substituted = resource
+            for key, value in context.items():
+                substituted = substituted.replace(make_placeholder(key), str(value))
+            substituted_resources.append(substituted)
+
+        return PromptContent(text=result, role=self.role, resources=substituted_resources)
+
+
+class PromptTemplate:
+    """
+    A template for a prompt that can have variables substituted.
+    """
+
+    def __init__(
+        self,
+        template_text: str,
+        delimiter_map: dict[str, str] | None = None,
+        template_file_path: Path | None = None,
+    ) -> None:
+        """
+        Initialize a prompt template.
+
+        Args:
+            template_text: The text of the template
+            delimiter_map: Optional map of delimiters to roles (e.g. {"---USER": "user"})
+            template_file_path: Optional path to the template file (for resource resolution)
+        """
+        self.template_text = template_text
+        self.template_file_path = template_file_path
+        self.delimiter_map = delimiter_map or DEFAULT_DELIMITER_MAP
+        self._template_variables = self._extract_template_variables(template_text)
+        self._parsed_content = self._parse_template()
+
+    @classmethod
+    def from_multipart_messages(
+        cls,
+        messages: list[PromptMessageExtended],
+        delimiter_map: dict[str, str] | None = None,
+    ) -> "PromptTemplate":
+        """
+        Create a PromptTemplate from a list of PromptMessageExtended objects.
+
+        Args:
+            messages: List of PromptMessageExtended objects
+            delimiter_map: Optional map of delimiters to roles
+
+        Returns:
+            A new PromptTemplate object
+        """
+        # Use default delimiter map if none provided
+        delimiter_map = delimiter_map or DEFAULT_DELIMITER_MAP
+
+        # Convert to delimited format
+        delimited_content = multipart_messages_to_delimited_format(
+            messages,
+            user_delimiter=next(
+                (k for k, v in delimiter_map.items() if v == "user"), USER_DELIMITER
+            ),
+            assistant_delimiter=next(
+                (k for k, v in delimiter_map.items() if v == "assistant"),
+                ASSISTANT_DELIMITER,
+            ),
+        )
+
+        # Join into a single string
+        content = "\n".join(delimited_content)
+
+        # Create and return the template
+        return cls(content, delimiter_map)
+
+    @property
+    def template_variables(self) -> set[str]:
+        """Get the template variables in this template"""
+        return self._template_variables
+
+    @property
+    def content_sections(self) -> list[PromptContent]:
+        """Get the parsed content sections"""
+        return self._parsed_content
+
+    def apply_substitutions(self, context: dict[str, Any]) -> list[PromptContent]:
+        """
+        Apply variable substitutions to the template.
+
+        Args:
+            context: Dictionary of variable names to values
+
+        Returns:
+            List of PromptContent with substitutions applied
+        """
+        # Create a new list with substitutions applied to each section
+        return [section.apply_substitutions(context) for section in self._parsed_content]
+
+    def apply_substitutions_to_extended(
+        self, context: dict[str, Any]
+    ) -> list[PromptMessageExtended]:
+        """
+        Apply variable substitutions to the template and return PromptMessageExtended objects.
+
+        Args:
+            context: Dictionary of variable names to values
+
+        Returns:
+            List of PromptMessageExtended objects with substitutions applied
+        """
+        # First create a substituted template
+        content_sections = self.apply_substitutions(context)
+
+        # Convert content sections to multipart messages
+        multiparts = []
+        for section in content_sections:
+            # Handle text content
+            content_items = [TextContent(type="text", text=section.text)]
+
+            # Handle resources (if any)
+            for resource_path in section.resources:
+                # In a real implementation, you would load the resource here
+                # For now, we'll just create a placeholder
+                content_items.append(
+                    EmbeddedResource(
+                        type="resource",
+                        resource=TextResourceContents(
+                            uri=f"resource://fast-agent/{resource_path}",
+                            mimeType="text/plain",
+                            text=f"Content of {resource_path}",
+                        ),
+                    )
+                )
+
+            multiparts.append(PromptMessageExtended(role=section.role, content=content_items))
+
+        return multiparts
+
+    def _extract_template_variables(self, text: str) -> set[str]:
+        """Extract template variables from text using regex"""
+        variable_pattern = r"{{([^}]+)}}"
+        matches = re.findall(variable_pattern, text)
+        return set(matches)
+
+    def to_extended_messages(self) -> list[PromptMessageExtended]:
+        """
+        Convert this template to a list of PromptMessageExtended objects.
+
+        Returns:
+            List of PromptMessageExtended objects
+        """
+        multiparts = []
+
+        for section in self._parsed_content:
+            # Convert each section to a multipart message
+            content_items = [TextContent(type="text", text=section.text)]
+
+            # Add any resources as embedded resources
+            for resource_path in section.resources:
+                # In a real implementation, you would determine the MIME type
+                # and load the resource appropriately. Here we'll just use a placeholder.
+                content_items.append(
+                    EmbeddedResource(
+                        type="resource",
+                        resource=TextResourceContents(
+                            uri=f"resource://{resource_path}",
+                            mimeType="text/plain",
+                            text=f"Content of {resource_path}",
+                        ),
+                    )
+                )
+
+            multiparts.append(PromptMessageExtended(role=section.role, content=content_items))
+
+        return multiparts
+
+    def _parse_template(self) -> list[PromptContent]:
+        """
+        Parse the template into sections based on delimiters.
+        If no delimiters are found, treat the entire template as a single user message.
+
+        Resources are now collected within their parent sections, keeping the same role.
+        """
+        lines = self.template_text.split("\n")
+
+        # Check if we're in simple mode (no delimiters)
+        first_non_empty_line = next((line for line in lines if line.strip()), "")
+        delimiter_values = set(self.delimiter_map.keys())
+
+        is_simple_mode = first_non_empty_line and first_non_empty_line not in delimiter_values
+
+        if is_simple_mode:
+            # Simple mode: treat the entire content as a single user message
+            return [PromptContent(text=self.template_text, role="user", resources=[])]
+
+        # Standard mode with delimiters
+        sections = []
+        current_role = None
+        current_content = ""
+        current_resources = []
+
+        i = 0
+        while i < len(lines):
+            line = lines[i]
+
+            # Check if we hit a delimiter
+            if line.strip() in self.delimiter_map:
+                role_type = self.delimiter_map[line.strip()]
+
+                # If we're moving to a new user/assistant section (not resource)
+                if role_type != "resource":
+                    # Save the previous section if it exists
+                    if current_role is not None and current_content:
+                        sections.append(
+                            PromptContent(
+                                text=current_content.strip(),
+                                role=current_role,
+                                resources=current_resources,
+                            )
+                        )
+
+                    # Start a new section
+                    current_role = role_type
+                    current_content = ""
+                    current_resources = []
+
+                # Handle resource delimiters within sections
+                elif role_type == "resource" and i + 1 < len(lines):
+                    resource_path = lines[i + 1].strip()
+                    current_resources.append(resource_path)
+                    # Skip the resource path line
+                    i += 1
+
+            # If we're in a section, add to the current content
+            elif current_role is not None:
+                current_content += line + "\n"
+
+            i += 1
+
+        # Add the last section if there is one
+        if current_role is not None and current_content:
+            sections.append(
+                PromptContent(
+                    text=current_content.strip(),
+                    role=current_role,
+                    resources=current_resources,
+                )
+            )
+
+        return sections
+
+
+class PromptTemplateLoader:
+    """
+    Loads and processes prompt templates from files.
+    """
+
+    def __init__(self, delimiter_map: dict[str, str] | None = None) -> None:
+        """
+        Initialize the loader with optional custom delimiters.
+
+        Args:
+            delimiter_map: Optional map of delimiters to roles
+        """
+        self.delimiter_map = delimiter_map or DEFAULT_DELIMITER_MAP
+
+    def load_from_file(self, file_path: Path) -> PromptTemplate:
+        """
+        Load a prompt template from a file.
+
+        Args:
+            file_path: Path to the template file
+
+        Returns:
+            A PromptTemplate object
+        """
+        with open(file_path, "r", encoding="utf-8") as f:
+            content = f.read()
+
+        return PromptTemplate(content, self.delimiter_map, template_file_path=file_path)
+
+    def load_from_multipart(self, messages: list[PromptMessageExtended]) -> PromptTemplate:
+        """
+        Create a PromptTemplate from a list of PromptMessageExtended objects.
+
+        Args:
+            messages: List of PromptMessageExtended objects
+
+        Returns:
+            A PromptTemplate object
+        """
+        # Use the class method directly to avoid code duplication
+        return PromptTemplate.from_multipart_messages(messages, self.delimiter_map)
+
+    def get_metadata(self, file_path: Path) -> PromptMetadata:
+        """
+        Analyze a prompt file to extract metadata and template variables.
+
+        Args:
+            file_path: Path to the template file
+
+        Returns:
+            PromptMetadata with information about the template
+        """
+        template = self.load_from_file(file_path)
+
+        # Generate a description based on content
+        lines = template.template_text.split("\n")
+        first_non_empty_line = next((line for line in lines if line.strip()), "")
+
+        # Check if we're in simple mode
+        is_simple_mode = first_non_empty_line and first_non_empty_line not in self.delimiter_map
+
+        if is_simple_mode:
+            # In simple mode, use first line as description if it seems like one
+            first_line = lines[0].strip() if lines else ""
+            if len(first_line) < 60 and "{{" not in first_line and "}}" not in first_line:
+                description = first_line
+            else:
+                description = f"Simple prompt: {file_path.stem}"
+        else:
+            # Regular mode - find text after first delimiter for the description
+            description = file_path.stem
+
+            # Look for first delimiter and role
+            first_role = None
+            first_content_index = None
+
+            for i, line in enumerate(lines):
+                stripped = line.strip()
+                if stripped in self.delimiter_map:
+                    first_role = self.delimiter_map[stripped]
+                    first_content_index = i + 1
+                    break
+
+            if first_role and first_content_index and first_content_index < len(lines):
+                # Get up to 3 non-empty lines after the delimiter for a preview
+                preview_lines = []
+                for j in range(first_content_index, min(first_content_index + 10, len(lines))):
+                    stripped = lines[j].strip()
+                    if stripped and stripped not in self.delimiter_map:
+                        preview_lines.append(stripped)
+                        if len(preview_lines) >= 3:
+                            break
+
+                if preview_lines:
+                    preview = " ".join(preview_lines)
+                    if len(preview) > 50:
+                        preview = preview[:47] + "..."
+                    # Include role in the description but not the filename
+                    description = f"[{first_role.upper()}] {preview}"
+
+        # Extract resource paths from all sections that come after RESOURCE delimiters
+        resource_paths = []
+        resource_delimiter = next(
+            (k for k, v in self.delimiter_map.items() if v == "resource"), RESOURCE_DELIMITER
+        )
+        for i, line in enumerate(lines):
+            if line.strip() == resource_delimiter:
+                if i + 1 < len(lines) and lines[i + 1].strip():
+                    resource_paths.append(lines[i + 1].strip())
+
+        return PromptMetadata(
+            name=file_path.stem,
+            description=description,
+            template_variables=template.template_variables,
+            resource_paths=resource_paths,
+            file_path=file_path,
+        )

fast_agent/mcp/resource_utils.py

@@ -0,0 +1,215 @@
+import base64
+from pathlib import Path
+
+from mcp.types import (
+    BlobResourceContents,
+    EmbeddedResource,
+    ImageContent,
+    TextResourceContents,
+)
+from pydantic import AnyUrl
+
+import fast_agent.mcp.mime_utils as mime_utils
+
+HTTP_TIMEOUT = 10  # Default timeout for HTTP requests
+
+# Define a type alias for resource content results
+ResourceContent = tuple[str, str, bool]
+
+
+def find_resource_file(resource_path: str, prompt_files: list[Path]) -> Path | None:
+    """Find a resource file relative to one of the prompt files"""
+    for prompt_file in prompt_files:
+        potential_path = prompt_file.parent / resource_path
+        if potential_path.exists():
+            return potential_path
+    return None
+
+
+def load_resource_content(resource_path: str, prompt_files: list[Path]) -> ResourceContent:
+    """
+    Load a resource's content and determine its mime type
+
+    Args:
+        resource_path: Path to the resource file
+        prompt_files: List of prompt files (to find relative paths)
+
+    Returns:
+        Tuple of (content, mime_type, is_binary)
+        - content: String content for text files, base64-encoded string for binary files
+        - mime_type: The MIME type of the resource
+        - is_binary: Whether the content is binary (and base64-encoded)
+
+    Raises:
+        FileNotFoundError: If the resource cannot be found
+    """
+    # Try to locate the resource file
+    resource_file = find_resource_file(resource_path, prompt_files)
+    if resource_file is None:
+        raise FileNotFoundError(f"Resource not found: {resource_path}")
+
+    # Determine mime type
+    mime_type = mime_utils.guess_mime_type(str(resource_file))
+    is_binary = mime_utils.is_binary_content(mime_type)
+
+    if is_binary:
+        # For binary files, read as binary and base64 encode
+        with open(resource_file, "rb") as f:
+            content = base64.b64encode(f.read()).decode("utf-8")
+    else:
+        # For text files, read as text
+        with open(resource_file, "r", encoding="utf-8") as f:
+            content = f.read()
+
+    return content, mime_type, is_binary
+
+
+# Create a safe way to generate resource URIs that Pydantic accepts
+def create_resource_uri(path: str) -> str:
+    """Create a resource URI from a path"""
+    return f"resource://fast-agent/{Path(path).name}"
+
+
+def create_resource_reference(uri: str, mime_type: str) -> "EmbeddedResource":
+    """
+    Create a reference to a resource without embedding its content directly.
+
+    This creates an EmbeddedResource that references another resource URI.
+    When the client receives this, it will make a separate request to fetch
+    the resource content using the provided URI.
+
+    Args:
+        uri: URI for the resource
+        mime_type: MIME type of the resource
+
+    Returns:
+        An EmbeddedResource object
+    """
+    from mcp.types import EmbeddedResource, TextResourceContents
+
+    # Create a resource reference
+    resource_contents = TextResourceContents(
+        uri=uri,
+        mimeType=mime_type,
+        text="",  # Empty text as we're just referencing
+    )
+
+    return EmbeddedResource(type="resource", resource=resource_contents)
+
+
+def create_embedded_resource(
+    resource_path: str, content: str, mime_type: str, is_binary: bool = False
+) -> EmbeddedResource:
+    """Create an embedded resource content object"""
+    # Format a valid resource URI string
+    resource_uri_str = create_resource_uri(resource_path)
+
+    # Create common resource args dict to reduce duplication
+    resource_args = {
+        "uri": resource_uri_str,  # type: ignore
+        "mimeType": mime_type,
+    }
+
+    if is_binary:
+        return EmbeddedResource(
+            type="resource",
+            resource=BlobResourceContents(
+                **resource_args,
+                blob=content,
+            ),
+        )
+    else:
+        return EmbeddedResource(
+            type="resource",
+            resource=TextResourceContents(
+                **resource_args,
+                text=content,
+            ),
+        )
+
+
+def create_image_content(data: str, mime_type: str) -> ImageContent:
+    """Create an image content object from base64-encoded data"""
+    return ImageContent(
+        type="image",
+        data=data,
+        mimeType=mime_type,
+    )
+
+
+def create_blob_resource(resource_path: str, content: str, mime_type: str) -> EmbeddedResource:
+    """Create an embedded resource for binary data"""
+    return EmbeddedResource(
+        type="resource",
+        resource=BlobResourceContents(
+            uri=resource_path,
+            mimeType=mime_type,
+            blob=content,  # Content should already be base64 encoded
+        ),
+    )
+
+
+def create_text_resource(resource_path: str, content: str, mime_type: str) -> EmbeddedResource:
+    """Create an embedded resource for text data"""
+    return EmbeddedResource(
+        type="resource",
+        resource=TextResourceContents(
+            uri=resource_path,
+            mimeType=mime_type,
+            text=content,
+        ),
+    )
+
+
+def normalize_uri(uri_or_filename: str) -> str:
+    """
+    Normalize a URI or filename to ensure it's a valid URI.
+    Converts simple filenames to file:// URIs if needed.
+
+    Args:
+        uri_or_filename: A URI string or simple filename
+
+    Returns:
+        A properly formatted URI string
+    """
+    if not uri_or_filename:
+        return ""
+
+    # Check if it's already a valid URI with a scheme
+    if "://" in uri_or_filename:
+        return uri_or_filename
+
+    # Handle Windows-style paths with backslashes
+    normalized_path = uri_or_filename.replace("\\", "/")
+
+    # If it's a simple filename or relative path, convert to file:// URI
+    # Make sure it has three slashes for an absolute path
+    if normalized_path.startswith("/"):
+        return f"file://{normalized_path}"
+    else:
+        return f"file:///{normalized_path}"
+
+
+def extract_title_from_uri(uri: AnyUrl) -> str:
+    """Extract a readable title from a URI."""
+    # Simple attempt to get filename from path
+    uri_str = uri._url
+    try:
+        # For HTTP(S) URLs
+        if uri.scheme in ("http", "https"):
+            # Get the last part of the path
+            path_parts = uri.path.split("/")
+            filename = next((p for p in reversed(path_parts) if p), "")
+            return filename if filename else uri_str
+
+        # For file URLs or other schemes
+        elif uri.path:
+            import os.path
+
+            return os.path.basename(uri.path)
+
+    except Exception:
+        pass
+
+    # Fallback to the full URI if parsing fails
+    return uri_str