fast-agent-mcp 0.2.45__py3-none-any.whl → 0.2.47__py3-none-any.whl

mcp_agent/human_input/__init__.py

@@ -0,0 +1,50 @@
+"""Human input modules for forms and elicitation."""
+
+# Export the simple form API
+# Export field types and schema builder
+from mcp_agent.human_input.form_fields import (
+    BooleanField,
+    EnumField,
+    FormSchema,
+    IntegerField,
+    NumberField,
+    # Field classes
+    StringField,
+    boolean,
+    choice,
+    date,
+    datetime,
+    email,
+    integer,
+    number,
+    # Convenience functions
+    string,
+    url,
+)
+from mcp_agent.human_input.simple_form import ask, ask_sync, form, form_sync
+
+__all__ = [
+    # Form functions
+    "form",
+    "form_sync",
+    "ask",
+    "ask_sync",
+    # Schema builder
+    "FormSchema",
+    # Field classes
+    "StringField",
+    "IntegerField",
+    "NumberField",
+    "BooleanField",
+    "EnumField",
+    # Field convenience functions
+    "string",
+    "email",
+    "url",
+    "date",
+    "datetime",
+    "integer",
+    "number",
+    "boolean",
+    "choice",
+]

mcp_agent/human_input/form_fields.py

@@ -0,0 +1,252 @@
+"""High-level field types for elicitation forms with default support."""
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Union
+
+
+@dataclass
+class StringField:
+    """String field with validation and default support."""
+
+    title: Optional[str] = None
+    description: Optional[str] = None
+    default: Optional[str] = None
+    min_length: Optional[int] = None
+    max_length: Optional[int] = None
+    format: Optional[str] = None  # email, uri, date, date-time
+
+    def to_schema(self) -> Dict[str, Any]:
+        """Convert to MCP elicitation schema format."""
+        schema: Dict[str, Any] = {"type": "string"}
+
+        if self.title:
+            schema["title"] = self.title
+        if self.description:
+            schema["description"] = self.description
+        if self.default is not None:
+            schema["default"] = self.default
+        if self.min_length is not None:
+            schema["minLength"] = self.min_length
+        if self.max_length is not None:
+            schema["maxLength"] = self.max_length
+        if self.format:
+            schema["format"] = self.format
+
+        return schema
+
+
+@dataclass
+class IntegerField:
+    """Integer field with validation and default support."""
+
+    title: Optional[str] = None
+    description: Optional[str] = None
+    default: Optional[int] = None
+    minimum: Optional[int] = None
+    maximum: Optional[int] = None
+
+    def to_schema(self) -> Dict[str, Any]:
+        """Convert to MCP elicitation schema format."""
+        schema: Dict[str, Any] = {"type": "integer"}
+
+        if self.title:
+            schema["title"] = self.title
+        if self.description:
+            schema["description"] = self.description
+        if self.default is not None:
+            schema["default"] = self.default
+        if self.minimum is not None:
+            schema["minimum"] = self.minimum
+        if self.maximum is not None:
+            schema["maximum"] = self.maximum
+
+        return schema
+
+
+@dataclass
+class NumberField:
+    """Number (float) field with validation and default support."""
+
+    title: Optional[str] = None
+    description: Optional[str] = None
+    default: Optional[float] = None
+    minimum: Optional[float] = None
+    maximum: Optional[float] = None
+
+    def to_schema(self) -> Dict[str, Any]:
+        """Convert to MCP elicitation schema format."""
+        schema: Dict[str, Any] = {"type": "number"}
+
+        if self.title:
+            schema["title"] = self.title
+        if self.description:
+            schema["description"] = self.description
+        if self.default is not None:
+            schema["default"] = self.default
+        if self.minimum is not None:
+            schema["minimum"] = self.minimum
+        if self.maximum is not None:
+            schema["maximum"] = self.maximum
+
+        return schema
+
+
+@dataclass
+class BooleanField:
+    """Boolean field with default support."""
+
+    title: Optional[str] = None
+    description: Optional[str] = None
+    default: Optional[bool] = None
+
+    def to_schema(self) -> Dict[str, Any]:
+        """Convert to MCP elicitation schema format."""
+        schema: Dict[str, Any] = {"type": "boolean"}
+
+        if self.title:
+            schema["title"] = self.title
+        if self.description:
+            schema["description"] = self.description
+        if self.default is not None:
+            schema["default"] = self.default
+
+        return schema
+
+
+@dataclass
+class EnumField:
+    """Enum/choice field with default support."""
+
+    choices: List[str]
+    choice_names: Optional[List[str]] = None  # Human-readable names
+    title: Optional[str] = None
+    description: Optional[str] = None
+    default: Optional[str] = None
+
+    def to_schema(self) -> Dict[str, Any]:
+        """Convert to MCP elicitation schema format."""
+        schema: Dict[str, Any] = {"type": "string", "enum": self.choices}
+
+        if self.title:
+            schema["title"] = self.title
+        if self.description:
+            schema["description"] = self.description
+        if self.default is not None:
+            schema["default"] = self.default
+        if self.choice_names:
+            schema["enumNames"] = self.choice_names
+
+        return schema
+
+
+# Field type union
+FieldType = Union[StringField, IntegerField, NumberField, BooleanField, EnumField]
+
+
+class FormSchema:
+    """High-level form schema builder."""
+
+    def __init__(self, **fields: FieldType):
+        """Create a form schema with named fields."""
+        self.fields = fields
+        self._required_fields: List[str] = []
+
+    def required(self, *field_names: str) -> "FormSchema":
+        """Mark fields as required."""
+        self._required_fields.extend(field_names)
+        return self
+
+    def to_schema(self) -> Dict[str, Any]:
+        """Convert to MCP ElicitRequestedSchema format."""
+        properties = {}
+
+        for field_name, field in self.fields.items():
+            properties[field_name] = field.to_schema()
+
+        schema: Dict[str, Any] = {"type": "object", "properties": properties}
+
+        if self._required_fields:
+            schema["required"] = self._required_fields
+
+        return schema
+
+
+# Convenience functions for creating fields
+def string(
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    default: Optional[str] = None,
+    min_length: Optional[int] = None,
+    max_length: Optional[int] = None,
+    format: Optional[str] = None,
+) -> StringField:
+    """Create a string field."""
+    return StringField(title, description, default, min_length, max_length, format)
+
+
+def email(
+    title: Optional[str] = None, description: Optional[str] = None, default: Optional[str] = None
+) -> StringField:
+    """Create an email field."""
+    return StringField(title, description, default, format="email")
+
+
+def url(
+    title: Optional[str] = None, description: Optional[str] = None, default: Optional[str] = None
+) -> StringField:
+    """Create a URL field."""
+    return StringField(title, description, default, format="uri")
+
+
+def date(
+    title: Optional[str] = None, description: Optional[str] = None, default: Optional[str] = None
+) -> StringField:
+    """Create a date field."""
+    return StringField(title, description, default, format="date")
+
+
+def datetime(
+    title: Optional[str] = None, description: Optional[str] = None, default: Optional[str] = None
+) -> StringField:
+    """Create a datetime field."""
+    return StringField(title, description, default, format="date-time")
+
+
+def integer(
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    default: Optional[int] = None,
+    minimum: Optional[int] = None,
+    maximum: Optional[int] = None,
+) -> IntegerField:
+    """Create an integer field."""
+    return IntegerField(title, description, default, minimum, maximum)
+
+
+def number(
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    default: Optional[float] = None,
+    minimum: Optional[float] = None,
+    maximum: Optional[float] = None,
+) -> NumberField:
+    """Create a number field."""
+    return NumberField(title, description, default, minimum, maximum)
+
+
+def boolean(
+    title: Optional[str] = None, description: Optional[str] = None, default: Optional[bool] = None
+) -> BooleanField:
+    """Create a boolean field."""
+    return BooleanField(title, description, default)
+
+
+def choice(
+    choices: List[str],
+    choice_names: Optional[List[str]] = None,
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    default: Optional[str] = None,
+) -> EnumField:
+    """Create a choice/enum field."""
+    return EnumField(choices, choice_names, title, description, default)

mcp_agent/human_input/simple_form.py

@@ -0,0 +1,111 @@
+"""Simple form API for elicitation schemas without MCP wrappers."""
+
+import asyncio
+from typing import Any, Dict, Optional, Union
+
+from mcp.types import ElicitRequestedSchema
+
+from mcp_agent.human_input.elicitation_form import show_simple_elicitation_form
+from mcp_agent.human_input.form_fields import FormSchema
+
+
+async def form(
+    schema: Union[FormSchema, ElicitRequestedSchema, Dict[str, Any]],
+    message: str = "Please fill out the form",
+    title: str = "Form Input",
+) -> Optional[Dict[str, Any]]:
+    """
+    Simple form API that presents an elicitation form and returns results.
+
+    Args:
+        schema: FormSchema, ElicitRequestedSchema, or dict schema
+        message: Message to display to the user
+        title: Title for the form (used as agent_name)
+
+    Returns:
+        Dict with form data if accepted, None if cancelled/declined
+
+    Example:
+        from mcp_agent.human_input.form_fields import FormSchema, string, email, integer
+
+        schema = FormSchema(
+            name=string("Name", "Your full name", min_length=2),
+            email=email("Email", "Your email address"),
+            age=integer("Age", "Your age", minimum=0, maximum=120)
+        ).required("name", "email")
+
+        result = await form(schema, "Please enter your information")
+        if result:
+            print(f"Name: {result['name']}, Email: {result['email']}")
+    """
+    # Convert schema to ElicitRequestedSchema format
+    if isinstance(schema, FormSchema):
+        elicit_schema = schema.to_schema()
+    elif isinstance(schema, dict):
+        elicit_schema = schema
+    else:
+        elicit_schema = schema
+
+    # Show the form
+    action, result = await show_simple_elicitation_form(
+        schema=elicit_schema, message=message, agent_name=title, server_name="SimpleForm"
+    )
+
+    # Return results based on action
+    if action == "accept":
+        return result
+    else:
+        return None
+
+
+def form_sync(
+    schema: Union[FormSchema, ElicitRequestedSchema, Dict[str, Any]],
+    message: str = "Please fill out the form",
+    title: str = "Form Input",
+) -> Optional[Dict[str, Any]]:
+    """
+    Synchronous wrapper for the form function.
+
+    Args:
+        schema: FormSchema, ElicitRequestedSchema, or dict schema
+        message: Message to display to the user
+        title: Title for the form (used as agent_name)
+
+    Returns:
+        Dict with form data if accepted, None if cancelled/declined
+    """
+    return asyncio.run(form(schema, message, title))
+
+
+# Convenience function with a shorter name
+async def ask(
+    schema: Union[FormSchema, ElicitRequestedSchema, Dict[str, Any]],
+    message: str = "Please provide the requested information",
+) -> Optional[Dict[str, Any]]:
+    """
+    Short alias for form() function.
+
+    Example:
+        from mcp_agent.human_input.form_fields import FormSchema, string, email
+
+        schema = FormSchema(
+            name=string("Name", "Your name"),
+            email=email("Email", "Your email")
+        ).required("name")
+
+        result = await ask(schema, "What's your info?")
+    """
+    return await form(schema, message)
+
+
+def ask_sync(
+    schema: Union[FormSchema, ElicitRequestedSchema, Dict[str, Any]],
+    message: str = "Please provide the requested information",
+) -> Optional[Dict[str, Any]]:
+    """
+    Synchronous version of ask().
+
+    Example:
+        result = ask_sync(schema, "What's your info?")
+    """
+    return form_sync(schema, message)

mcp_agent/llm/augmented_llm.py

@@ -9,6 +9,7 @@ from typing import (
     Tuple,
     Type,
     TypeVar,
+    Union,
     cast,
 )
 
@@ -203,7 +204,7 @@ class AugmentedLLM(ContextDependent, AugmentedLLMProtocol, Generic[MessageParamT
 
     async def generate(
         self,
-        multipart_messages: List[PromptMessageMultipart],
+        multipart_messages: List[Union[PromptMessageMultipart, PromptMessage]],
         request_params: RequestParams | None = None,
     ) -> PromptMessageMultipart:
         """
@@ -212,6 +213,10 @@ class AugmentedLLM(ContextDependent, AugmentedLLMProtocol, Generic[MessageParamT
         # note - check changes here are mirrored in structured(). i've thought hard about
         # a strategy to reduce duplication etc, but aiming for simple but imperfect for the moment
 
+        # Convert PromptMessage to PromptMessageMultipart if needed
+        if multipart_messages and isinstance(multipart_messages[0], PromptMessage):
+            multipart_messages = PromptMessageMultipart.to_multipart(multipart_messages)
+
         # TODO -- create a "fast-agent" control role rather than magic strings
 
         if multipart_messages[-1].first_text().startswith("***SAVE_HISTORY"):
@@ -259,12 +264,16 @@ class AugmentedLLM(ContextDependent, AugmentedLLMProtocol, Generic[MessageParamT
 
     async def structured(
         self,
-        multipart_messages: List[PromptMessageMultipart],
+        multipart_messages: List[Union[PromptMessageMultipart, PromptMessage]],
         model: Type[ModelT],
         request_params: RequestParams | None = None,
     ) -> Tuple[ModelT | None, PromptMessageMultipart]:
         """Return a structured response from the LLM using the provided messages."""
 
+        # Convert PromptMessage to PromptMessageMultipart if needed
+        if multipart_messages and isinstance(multipart_messages[0], PromptMessage):
+            multipart_messages = PromptMessageMultipart.to_multipart(multipart_messages)
+
         self._precall(multipart_messages)
         result, assistant_response = await self._apply_prompt_provider_specific_structured(
             multipart_messages, model, request_params

mcp_agent/llm/augmented_llm_playback.py

@@ -1,4 +1,6 @@
-from typing import Any, List, Type
+from typing import Any, List, Type, Union
+
+from mcp.types import PromptMessage
 
 from mcp_agent.core.exceptions import ModelConfigError
 from mcp_agent.core.prompt import Prompt
@@ -51,7 +53,7 @@ class PlaybackLLM(PassthroughLLM):
 
     async def generate(
         self,
-        multipart_messages: List[PromptMessageMultipart],
+        multipart_messages: List[Union[PromptMessageMultipart, PromptMessage]],
         request_params: RequestParams | None = None,
     ) -> PromptMessageMultipart:
         """
@@ -106,7 +108,7 @@ class PlaybackLLM(PassthroughLLM):
 
     async def structured(
         self,
-        multipart_messages: List[PromptMessageMultipart],
+        multipart_messages: List[Union[PromptMessageMultipart, PromptMessage]],
         model: Type[ModelT],
         request_params: RequestParams | None = None,
     ) -> tuple[ModelT | None, PromptMessageMultipart]:

mcp_agent/llm/model_database.py

@@ -130,15 +130,11 @@ class ModelDatabase:
     )
 
     # FIXME: xAI has not documented the max output tokens for Grok 4. Using Grok 3 as a placeholder. Will need to update when available (if ever)
-    GROK_4 = ModelParameters(
-        context_window=256000, max_output_tokens=16385, tokenizes=XAI_VISION
-    )
+    GROK_4 = ModelParameters(context_window=256000, max_output_tokens=16385, tokenizes=XAI_VISION)
 
     # Source for Grok 3 max output: https://www.reddit.com/r/grok/comments/1j7209p/exploring_grok_3_beta_output_capacity_a_simple/
     # xAI does not document Grok 3 max output tokens, using the above source as a reference.
-    GROK_3 = ModelParameters(
-        context_window=131072, max_output_tokens=16385, tokenizes=TEXT_ONLY
-    )
+    GROK_3 = ModelParameters(context_window=131072, max_output_tokens=16385, tokenizes=TEXT_ONLY)
 
     # Model configuration database
     MODELS: Dict[str, ModelParameters] = {
@@ -193,7 +189,6 @@ class ModelDatabase:
         "claude-3-7-sonnet": ANTHROPIC_37_SERIES,
         "claude-3-7-sonnet-20250219": ANTHROPIC_37_SERIES,
         "claude-3-7-sonnet-latest": ANTHROPIC_37_SERIES,
-        "claude-sonnet-4": ANTHROPIC_SONNET_4_VERSIONED,
         "claude-sonnet-4-0": ANTHROPIC_SONNET_4_VERSIONED,
         "claude-sonnet-4-20250514": ANTHROPIC_SONNET_4_VERSIONED,
         "claude-opus-4": ANTHROPIC_OPUS_4_VERSIONED,

mcp_agent/llm/providers/augmented_llm_aliyun.py

@@ -18,7 +18,7 @@ class AliyunAugmentedLLM(OpenAIAugmentedLLM):
             model=chosen_model,
             systemPrompt=self.instruction,
             parallel_tool_calls=True,
-            max_iterations=10,
+            max_iterations=20,
             use_history=True,
         )
 

mcp_agent/llm/providers/augmented_llm_anthropic.py

@@ -46,7 +46,7 @@ from mcp_agent.llm.augmented_llm import (
 )
 from mcp_agent.logging.logger import get_logger
 
-DEFAULT_ANTHROPIC_MODEL = "claude-3-7-sonnet-latest"
+DEFAULT_ANTHROPIC_MODEL = "claude-sonnet-4-0"
 
 
 class AnthropicAugmentedLLM(AugmentedLLM[MessageParam, Message]):

mcp_agent/llm/providers/augmented_llm_deepseek.py

@@ -28,7 +28,7 @@ class DeepSeekAugmentedLLM(OpenAIAugmentedLLM):
             model=chosen_model,
             systemPrompt=self.instruction,
             parallel_tool_calls=True,
-            max_iterations=10,
+            max_iterations=20,
             use_history=True,
         )
 
@@ -85,7 +85,9 @@ class DeepSeekAugmentedLLM(OpenAIAugmentedLLM):
         return self._structured_from_multipart(result, model)
 
     @classmethod
-    def convert_message_to_message_param(cls, message: ChatCompletionMessage, **kwargs) -> ChatCompletionAssistantMessageParam:
+    def convert_message_to_message_param(
+        cls, message: ChatCompletionMessage, **kwargs
+    ) -> ChatCompletionAssistantMessageParam:
         """Convert a response object to an input parameter object to allow LLM calls to be chained."""
         if hasattr(message, "reasoning_content"):
             message = copy(message)

mcp_agent/llm/providers/augmented_llm_google_oai.py

@@ -18,7 +18,7 @@ class GoogleOaiAugmentedLLM(OpenAIAugmentedLLM):
             model=chosen_model,
             systemPrompt=self.instruction,
             parallel_tool_calls=False,
-            max_iterations=10,
+            max_iterations=20,
             use_history=True,
         )
 

mcp_agent/llm/providers/augmented_llm_openrouter.py

@@ -32,7 +32,7 @@ class OpenRouterAugmentedLLM(OpenAIAugmentedLLM):
             model=chosen_model,  # Will be validated by base class
             systemPrompt=self.instruction,
             parallel_tool_calls=True,  # Default based on OpenAI provider
-            max_iterations=10,  # Default based on OpenAI provider
+            max_iterations=20,  # Default based on OpenAI provider
             use_history=True,  # Default based on OpenAI provider
         )
 

mcp_agent/llm/providers/augmented_llm_tensorzero.py

@@ -92,7 +92,7 @@ class TensorZeroAugmentedLLM(AugmentedLLM[Dict[str, Any], Any]):
             systemPrompt=self.instruction,
             maxTokens=4096,
             use_history=True,
-            max_iterations=10,  # Max iterations for tool use loop
+            max_iterations=20,  # Max iterations for tool use loop
             parallel_tool_calls=True,
         )
 

mcp_agent/llm/providers/augmented_llm_xai.py

@@ -22,7 +22,7 @@ class XAIAugmentedLLM(OpenAIAugmentedLLM):
             model=chosen_model,
             systemPrompt=self.instruction,
             parallel_tool_calls=False,
-            max_iterations=10,
+            max_iterations=20,
             use_history=True,
         )
 

mcp_agent/mcp/__init__.py

@@ -0,0 +1,50 @@
+"""
+MCP (Model Context Protocol) integration components.
+"""
+
+from mcp.types import PromptMessage
+
+from .helpers import (
+    get_image_data,
+    get_resource_text,
+    get_resource_uri,
+    get_text,
+    is_image_content,
+    is_resource_content,
+    is_resource_link,
+    is_text_content,
+)
+from .interfaces import (
+    AgentProtocol,
+    AugmentedLLMProtocol,
+    MCPConnectionManagerProtocol,
+    ModelFactoryClassProtocol,
+    ModelT,
+    ServerConnection,
+    ServerRegistryProtocol,
+)
+from .prompt_message_multipart import PromptMessageMultipart
+
+__all__ = [
+    # Types from mcp.types
+    "PromptMessage",
+    # Multipart message handling
+    "PromptMessageMultipart",
+    # Protocol interfaces
+    "AugmentedLLMProtocol",
+    "AgentProtocol",
+    "MCPConnectionManagerProtocol",
+    "ServerRegistryProtocol",
+    "ServerConnection",
+    "ModelFactoryClassProtocol",
+    "ModelT",
+    # Helper functions
+    "get_text",
+    "get_image_data",
+    "get_resource_uri",
+    "is_text_content",
+    "is_image_content",
+    "is_resource_content",
+    "is_resource_link",
+    "get_resource_text",
+]

mcp_agent/mcp/helpers/__init__.py

@@ -1,3 +1,25 @@
 """
 Helper modules for working with MCP content.
-"""
+"""
+
+from .content_helpers import (
+    get_image_data,
+    get_resource_text,
+    get_resource_uri,
+    get_text,
+    is_image_content,
+    is_resource_content,
+    is_resource_link,
+    is_text_content,
+)
+
+__all__ = [
+    "get_text",
+    "get_image_data",
+    "get_resource_uri",
+    "is_text_content",
+    "is_image_content",
+    "is_resource_content",
+    "is_resource_link",
+    "get_resource_text",
+]