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

fast_agent/llm/provider/openai/openai_multipart.py

@@ -0,0 +1,169 @@
+# openai_multipart.py
+"""
+Clean utilities for converting between PromptMessageExtended and OpenAI message formats.
+Each function handles all content types consistently and is designed for simple testing.
+"""
+
+from typing import Any, Union
+
+from mcp.types import (
+    BlobResourceContents,
+    EmbeddedResource,
+    ImageContent,
+    TextContent,
+    TextResourceContents,
+)
+from openai.types.chat import (
+    ChatCompletionMessage,
+    ChatCompletionMessageParam,
+)
+
+from fast_agent.types import PromptMessageExtended
+
+
+def openai_to_extended(
+    message: Union[
+        ChatCompletionMessage,
+        ChatCompletionMessageParam,
+        list[Union[ChatCompletionMessage, ChatCompletionMessageParam]],
+    ],
+) -> Union[PromptMessageExtended, list[PromptMessageExtended]]:
+    """
+    Convert OpenAI messages to PromptMessageExtended format.
+
+    Args:
+        message: OpenAI Message, MessageParam, or list of them
+
+    Returns:
+        Equivalent message(s) in PromptMessageExtended format
+    """
+    if isinstance(message, list):
+        return [_openai_message_to_extended(m) for m in message]
+    return _openai_message_to_extended(message)
+
+
+def _openai_message_to_extended(
+    message: Union[ChatCompletionMessage, dict[str, Any]],
+) -> PromptMessageExtended:
+    """Convert a single OpenAI message to PromptMessageExtended."""
+    # Get role and content from message
+    if isinstance(message, dict):
+        role = message.get("role", "assistant")
+        content = message.get("content", "")
+    else:
+        role = message.role
+        content = message.content
+
+    mcp_contents = []
+
+    # Handle string content (simple case)
+    if isinstance(content, str):
+        mcp_contents.append(TextContent(type="text", text=content))
+
+    # Handle list of content parts
+    elif isinstance(content, list):
+        for part in content:
+            part_type = part.get("type") if isinstance(part, dict) else getattr(part, "type", None)
+
+            # Handle text content
+            if part_type == "text":
+                text = part.get("text") if isinstance(part, dict) else getattr(part, "text", "")
+
+                # Check if this is a resource marker
+                if (
+                    text
+                    and (text.startswith("[Resource:") or text.startswith("[Binary Resource:"))
+                    and "\n" in text
+                ):
+                    header, content_text = text.split("\n", 1)
+                    if "MIME:" in header:
+                        mime_match = header.split("MIME:", 1)[1].split("]")[0].strip()
+
+                        # If not text/plain, create an embedded resource
+                        if mime_match != "text/plain":
+                            if "Resource:" in header and "Binary Resource:" not in header:
+                                uri = header.split("Resource:", 1)[1].split(",")[0].strip()
+                                mcp_contents.append(
+                                    EmbeddedResource(
+                                        type="resource",
+                                        resource=TextResourceContents(
+                                            uri=uri,
+                                            mimeType=mime_match,
+                                            text=content_text,
+                                        ),
+                                    )
+                                )
+                                continue
+
+                # Regular text content
+                mcp_contents.append(TextContent(type="text", text=text))
+
+            # Handle image content
+            elif part_type == "image_url":
+                image_url = (
+                    part.get("image_url", {})
+                    if isinstance(part, dict)
+                    else getattr(part, "image_url", None)
+                )
+                if image_url:
+                    url = (
+                        image_url.get("url")
+                        if isinstance(image_url, dict)
+                        else getattr(image_url, "url", "")
+                    )
+                    if url and url.startswith("data:image/"):
+                        # Handle base64 data URLs
+                        mime_type = url.split(";")[0].replace("data:", "")
+                        data = url.split(",")[1]
+                        mcp_contents.append(
+                            ImageContent(type="image", data=data, mimeType=mime_type)
+                        )
+
+            # Handle explicit resource types
+            elif part_type == "resource" and isinstance(part, dict) and "resource" in part:
+                resource = part["resource"]
+                if isinstance(resource, dict):
+                    # Text resource
+                    if "text" in resource and "mimeType" in resource:
+                        mime_type = resource["mimeType"]
+                        uri = resource.get("uri", "resource://unknown")
+
+                        if mime_type == "text/plain":
+                            mcp_contents.append(TextContent(type="text", text=resource["text"]))
+                        else:
+                            mcp_contents.append(
+                                EmbeddedResource(
+                                    type="resource",
+                                    resource=TextResourceContents(
+                                        text=resource["text"],
+                                        mimeType=mime_type,
+                                        uri=uri,
+                                    ),
+                                )
+                            )
+                    # Binary resource
+                    elif "blob" in resource and "mimeType" in resource:
+                        mime_type = resource["mimeType"]
+                        uri = resource.get("uri", "resource://unknown")
+
+                        if mime_type.startswith("image/") and mime_type != "image/svg+xml":
+                            mcp_contents.append(
+                                ImageContent(
+                                    type="image",
+                                    data=resource["blob"],
+                                    mimeType=mime_type,
+                                )
+                            )
+                        else:
+                            mcp_contents.append(
+                                EmbeddedResource(
+                                    type="resource",
+                                    resource=BlobResourceContents(
+                                        blob=resource["blob"],
+                                        mimeType=mime_type,
+                                        uri=uri,
+                                    ),
+                                )
+                            )
+
+    return PromptMessageExtended(role=role, content=mcp_contents)

fast_agent/llm/provider/openai/openai_utils.py

@@ -0,0 +1,67 @@
+"""
+Utility functions for OpenAI integration with MCP.
+
+This file provides backward compatibility with the existing API while
+delegating to the proper implementations in the providers/ directory.
+"""
+
+from typing import Any, Union
+
+from openai.types.chat import (
+    ChatCompletionMessage,
+    ChatCompletionMessageParam,
+)
+
+from fast_agent.llm.provider.openai.multipart_converter_openai import OpenAIConverter
+from fast_agent.llm.provider.openai.openai_multipart import (
+    openai_to_extended,
+)
+from fast_agent.types import PromptMessageExtended
+
+
+def openai_message_to_prompt_message_multipart(
+    message: Union[ChatCompletionMessage, dict[str, Any]],
+) -> PromptMessageExtended:
+    """
+    Convert an OpenAI ChatCompletionMessage to a PromptMessageExtended.
+
+    Args:
+        message: The OpenAI message to convert (can be an actual ChatCompletionMessage
+                or a dictionary with the same structure)
+
+    Returns:
+        A PromptMessageExtended representation
+    """
+    return openai_to_extended(message)
+
+
+def openai_message_param_to_prompt_message_multipart(
+    message_param: ChatCompletionMessageParam,
+) -> PromptMessageExtended:
+    """
+    Convert an OpenAI ChatCompletionMessageParam to a PromptMessageExtended.
+
+    Args:
+        message_param: The OpenAI message param to convert
+
+    Returns:
+        A PromptMessageExtended representation
+    """
+    return openai_to_extended(message_param)
+
+
+def prompt_message_multipart_to_openai_message_param(
+    multipart: PromptMessageExtended,
+) -> ChatCompletionMessageParam:
+    """
+    Convert a PromptMessageExtended to an OpenAI ChatCompletionMessageParam.
+
+    Args:
+        multipart: The PromptMessageExtended to convert
+
+    Returns:
+        An OpenAI ChatCompletionMessageParam representation
+    """
+    # convert_to_openai now returns a list, return the first element for backward compatibility
+    messages = OpenAIConverter.convert_to_openai(multipart)
+    return messages[0] if messages else {"role": multipart.role, "content": ""}

fast_agent/llm/provider/openai/responses.py

@@ -0,0 +1,133 @@
+# from openai.types.beta.chat import
+
+from mcp import Tool
+from mcp.types import ContentBlock, TextContent
+from openai import AsyncOpenAI
+from openai.types.chat import (
+    ChatCompletionMessage,
+    ChatCompletionMessageParam,
+)
+from openai.types.responses import (
+    ResponseReasoningItem,
+    ResponseReasoningSummaryTextDeltaEvent,
+    ResponseTextDeltaEvent,
+)
+
+from fast_agent.constants import REASONING
+from fast_agent.core.logging.logger import get_logger
+from fast_agent.event_progress import ProgressAction
+from fast_agent.llm.fastagent_llm import FastAgentLLM
+from fast_agent.llm.provider_types import Provider
+from fast_agent.llm.request_params import RequestParams
+from fast_agent.llm.stream_types import StreamChunk
+from fast_agent.mcp.prompt_message_extended import PromptMessageExtended
+from fast_agent.types.llm_stop_reason import LlmStopReason
+
+_logger = get_logger(__name__)
+
+DEFAULT_RESPONSES_MODEL = "gpt-5-mini"
+DEFAULT_REASONING_EFFORT = "medium"
+
+
+# model selection
+# system prompt
+# usage info
+# reasoning/thinking display and summary
+# encrypted tokens
+
+
+class ResponsesLLM(FastAgentLLM[ChatCompletionMessageParam, ChatCompletionMessage]):
+    """LLM implementation for OpenAI's Responses models."""
+
+    # OpenAI-specific parameter exclusions
+
+    def __init__(self, provider=Provider.RESPONSES, *args, **kwargs):
+        super().__init__(*args, provider=provider, **kwargs)
+
+    async def _responses_client(self) -> AsyncOpenAI:
+        return AsyncOpenAI(api_key=self._api_key())
+
+    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:
+        responses_client = await self._responses_client()
+
+        async with responses_client.responses.stream(
+            model="gpt-5-mini",
+            instructions="You are a helpful assistant.",
+            input=multipart_messages[-1].all_text(),
+            reasoning={"summary": "auto", "effort": DEFAULT_REASONING_EFFORT},
+        ) as stream:
+            reasoning_chars: int = 0
+            text_chars: int = 0
+
+            async for event in stream:
+                if isinstance(event, ResponseReasoningSummaryTextDeltaEvent):
+                    reasoning_chars += len(event.delta)
+                    await self._emit_streaming_progress(
+                        model="gpt-5-mini (thinking)",
+                        new_total=reasoning_chars,
+                        type=ProgressAction.THINKING,
+                    )
+                if isinstance(event, ResponseTextDeltaEvent):
+                    # Notify stream listeners with the delta text
+                    self._notify_stream_listeners(StreamChunk(text=event.delta, is_reasoning=False))
+                    text_chars += len(event.delta)
+                    await self._emit_streaming_progress(
+                        model="gpt-5-mini",
+                        new_total=text_chars,
+                    )
+
+            final_response = await stream.get_final_response()
+            reasoning_content: list[ContentBlock] = []
+            for output_item in final_response.output:
+                if isinstance(output_item, ResponseReasoningItem):
+                    summary_text = "\n".join(part.text for part in output_item.summary if part.text)
+                    # reasoning text is not supplied by openai - leaving for future use with other providers
+                    reasoning_text = "".join(
+                        chunk.text
+                        for chunk in (output_item.content or [])
+                        if chunk.type == "reasoning_text"
+                    )
+                    if summary_text.strip():
+                        reasoning_content.append(TextContent(type="text", text=summary_text.strip()))
+                    if reasoning_text.strip():
+                        reasoning_content.append(
+                            TextContent(type="text", text=reasoning_text.strip())
+                        )
+        channels = {REASONING: reasoning_content} if reasoning_content else None
+
+        return PromptMessageExtended(
+            role="assistant",
+            channels=channels,
+            content=[TextContent(type="text", text=final_response.output_text)],
+            stop_reason=LlmStopReason.END_TURN,
+        )
+
+    async def _emit_streaming_progress(
+        self,
+        model: str,
+        new_total: int,
+        type: ProgressAction = ProgressAction.STREAMING,
+    ) -> None:
+        """Emit a streaming progress event.
+
+        Args:
+            model: The model being used.
+            new_total: The new total token count.
+        """
+        token_str = str(new_total).rjust(5)
+
+        # Emit progress event
+        data = {
+            "progress_action": type,
+            "model": model,
+            "agent_name": self.name,
+            "chat_turn": self.chat_turn(),
+            "details": token_str.strip(),  # Token count goes in details for STREAMING action
+        }
+        self.logger.info("Streaming progress", data=data)

fast_agent/llm/provider_key_manager.py

@@ -0,0 +1,139 @@
+"""
+Provider API key management for various LLM providers.
+Centralizes API key handling logic to make provider implementations more generic.
+"""
+
+import os
+from typing import Any
+
+from pydantic import BaseModel
+
+from fast_agent.core.exceptions import ProviderKeyError
+
+PROVIDER_ENVIRONMENT_MAP: dict[str, str] = {
+    # default behaviour in _get_env_key_name is to capitalize the
+    # provider name and suffix "_API_KEY" - so no specific mapping needed unless overriding
+    "hf": "HF_TOKEN",
+    "responses": "OPENAI_API_KEY",  # Temporary workaround
+}
+PROVIDER_CONFIG_KEY_ALIASES: dict[str, tuple[str, ...]] = {
+    # HuggingFace historically used "huggingface" (full name) in config files,
+    # while the provider id is "hf". Support both spellings.
+    "hf": ("hf", "huggingface"),
+    "huggingface": ("huggingface", "hf"),
+}
+API_KEY_HINT_TEXT = "<your-api-key-here>"
+
+
+class ProviderKeyManager:
+    """
+    Manages API keys for different providers centrally.
+    This class abstracts away the provider-specific key access logic,
+    making the provider implementations more generic.
+    """
+
+    @staticmethod
+    def get_env_var(provider_name: str) -> str | None:
+        return os.getenv(ProviderKeyManager.get_env_key_name(provider_name))
+
+    @staticmethod
+    def get_env_key_name(provider_name: str) -> str:
+        return PROVIDER_ENVIRONMENT_MAP.get(provider_name, f"{provider_name.upper()}_API_KEY")
+
+    @staticmethod
+    def get_config_file_key(provider_name: str, config: Any) -> str | None:
+        api_key = None
+        if isinstance(config, BaseModel):
+            config = config.model_dump()
+        provider_name = provider_name.lower()
+        provider_keys = ProviderKeyManager._get_provider_config_keys(provider_name)
+        for key in provider_keys:
+            provider_settings = config.get(key)
+            if not provider_settings:
+                continue
+            api_key = provider_settings.get("api_key", API_KEY_HINT_TEXT)
+            if api_key == API_KEY_HINT_TEXT:
+                api_key = None
+            break
+
+        return api_key
+
+    @staticmethod
+    def _get_provider_config_keys(provider_name: str) -> list[str]:
+        """Return config key candidates for a provider (provider id + aliases)."""
+        keys = [provider_name]
+        for alias in PROVIDER_CONFIG_KEY_ALIASES.get(provider_name, ()):
+            if alias not in keys:
+                keys.append(alias)
+        return keys
+
+    @staticmethod
+    def get_api_key(provider_name: str, config: Any) -> str:
+        """
+        Gets the API key for the specified provider.
+
+        Args:
+            provider_name: Name of the provider (e.g., "anthropic", "openai")
+            config: The application configuration object
+
+        Returns:
+            The API key as a string
+
+        Raises:
+            ProviderKeyError: If the API key is not found or is invalid
+        """
+
+        from fast_agent.llm.provider_types import Provider
+
+        provider_name = provider_name.lower()
+
+        # Fast-agent provider doesn't need external API keys
+        if provider_name == "fast-agent":
+            return ""
+
+        # Google Vertex AI uses ADC/IAM and does not require an API key.
+        if provider_name == "google":
+            try:
+                cfg = config.model_dump() if isinstance(config, BaseModel) else config
+                if isinstance(cfg, dict) and bool((cfg.get("google") or {}).get("vertex_ai", {}).get("enabled")):
+                    return ""
+            except Exception:
+                pass
+
+        api_key = ProviderKeyManager.get_config_file_key(provider_name, config)
+        if not api_key:
+            api_key = ProviderKeyManager.get_env_var(provider_name)
+
+        # HuggingFace: also support tokens managed by huggingface_hub (e.g. `hf auth login`)
+        # even when HF_TOKEN isn't explicitly set in the environment or config.
+        if not api_key and provider_name in {"hf", "huggingface"}:
+            try:
+                from huggingface_hub import get_token  # type: ignore
+
+                api_key = get_token()
+            except Exception:
+                pass
+
+        if not api_key and provider_name == "generic":
+            api_key = "ollama"  # Default for generic provider
+
+        if not api_key:
+            # Get proper display name for error message
+            try:
+                provider_enum = Provider(provider_name)
+                display_name = provider_enum.display_name
+            except ValueError:
+                # Invalid provider name
+                raise ProviderKeyError(
+                    f"Invalid provider: {provider_name}",
+                    f"'{provider_name}' is not a valid provider name.",
+                )
+
+            raise ProviderKeyError(
+                f"{display_name} API key not configured",
+                f"The {display_name} API key is required but not set.\n"
+                f"Add it to your configuration file under {provider_name}.api_key "
+                f"or set the {ProviderKeyManager.get_env_key_name(provider_name)} environment variable.",
+            )
+
+        return api_key

fast_agent/llm/provider_types.py

@@ -0,0 +1,34 @@
+"""
+Type definitions for LLM providers.
+"""
+
+from enum import Enum
+
+
+class Provider(Enum):
+    """Supported LLM providers"""
+
+    display_name: str
+
+    def __new__(cls, config_name, display_name=None):
+        obj = object.__new__(cls)
+        obj._value_ = config_name
+        obj.display_name = display_name or config_name.title()
+        return obj
+
+    ANTHROPIC = ("anthropic", "Anthropic")
+    DEEPSEEK = ("deepseek", "Deepseek")
+    FAST_AGENT = ("fast-agent", "fast-agent-internal")
+    GENERIC = ("generic", "Generic")
+    GOOGLE_OAI = ("googleoai", "GoogleOAI")  # For Google through OpenAI libraries
+    GOOGLE = ("google", "Google")  # For Google GenAI native library
+    OPENAI = ("openai", "OpenAI")
+    OPENROUTER = ("openrouter", "OpenRouter")
+    TENSORZERO = ("tensorzero", "TensorZero")  # For TensorZero Gateway
+    AZURE = ("azure", "Azure")  # Azure OpenAI Service
+    ALIYUN = ("aliyun", "Aliyun")  # Aliyun Bailian OpenAI Service
+    HUGGINGFACE = ("hf", "HuggingFace")  # For HuggingFace MCP connections
+    XAI = ("xai", "XAI")  # For xAI Grok models
+    BEDROCK = ("bedrock", "Bedrock")
+    GROQ = ("groq", "Groq")
+    RESPONSES = ("responses", "responses")

fast_agent/llm/request_params.py

@@ -0,0 +1,61 @@
+"""
+Request parameters definitions for LLM interactions.
+"""
+
+from typing import Any
+
+from mcp import SamplingMessage
+from mcp.types import CreateMessageRequestParams
+from pydantic import Field
+
+from fast_agent.constants import DEFAULT_MAX_ITERATIONS
+
+
+class RequestParams(CreateMessageRequestParams):
+    """
+    Parameters to configure the FastAgentLLM 'generate' requests.
+    """
+
+    messages: list[SamplingMessage] = Field(exclude=True, default=[])
+    """
+    Ignored. 'messages' are removed from CreateMessageRequestParams 
+    to avoid confusion with the 'message' parameter on 'generate' method.
+    """
+
+    maxTokens: int = 2048
+    """The maximum number of tokens to sample, as requested by the server."""
+
+    model: str | None = None
+    """
+    The model to use for the LLM generation. This can only be set during Agent creation.
+    If specified, this overrides the 'modelPreferences' selection criteria.
+    """
+
+    use_history: bool = True
+    """
+    Agent/LLM maintains conversation history. Does not include applied Prompts
+    """
+
+    max_iterations: int = DEFAULT_MAX_ITERATIONS
+    """
+    The maximum number of tool calls allowed in a conversation turn
+    """
+
+    parallel_tool_calls: bool = True
+    """
+    Whether to allow simultaneous tool calls
+    """
+    response_format: Any | None = None
+    """
+    Override response format for structured calls. Prefer sending pydantic model - only use in exceptional circumstances
+    """
+
+    template_vars: dict[str, Any] = Field(default_factory=dict)
+    """
+    Optional dictionary of template variables for dynamic templates. Currently only works for TensorZero inference backend
+    """
+
+    mcp_metadata: dict[str, Any] | None = None
+    """
+    Metadata to pass through to MCP tool calls via the _meta field.
+    """