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

fast_agent/human_input/form_elements.py

@@ -0,0 +1,59 @@
+"""Custom form elements for elicitation forms."""
+
+from typing import Optional, Sequence, TypeVar
+
+from prompt_toolkit.formatted_text import AnyFormattedText
+from prompt_toolkit.validation import ValidationError
+from prompt_toolkit.widgets import CheckboxList
+
+_T = TypeVar("_T")
+
+
+class ValidatedCheckboxList(CheckboxList[_T]):
+    """CheckboxList with min/max items validation."""
+
+    def __init__(
+        self,
+        values: Sequence[tuple[_T, AnyFormattedText]],
+        default_values: Optional[Sequence[_T]] = None,
+        min_items: Optional[int] = None,
+        max_items: Optional[int] = None,
+    ):
+        """
+        Initialize checkbox list with validation.
+
+        Args:
+            values: List of (value, label) tuples
+            default_values: Initially selected values
+            min_items: Minimum number of items that must be selected
+            max_items: Maximum number of items that can be selected
+        """
+        super().__init__(values, default_values=default_values)
+        self.min_items = min_items
+        self.max_items = max_items
+
+    @property
+    def validation_error(self) -> Optional[ValidationError]:
+        """
+        Check if current selection is valid.
+
+        Returns:
+            ValidationError if invalid, None if valid
+        """
+        selected_count = len(self.current_values)
+
+        if self.min_items is not None and selected_count < self.min_items:
+            if self.min_items == 1:
+                message = "At least 1 selection required"
+            else:
+                message = f"At least {self.min_items} selections required"
+            return ValidationError(message=message)
+
+        if self.max_items is not None and selected_count > self.max_items:
+            if self.max_items == 1:
+                message = "Only 1 selection allowed"
+            else:
+                message = f"Maximum {self.max_items} selections allowed"
+            return ValidationError(message=message)
+
+        return None

fast_agent/human_input/form_fields.py

@@ -0,0 +1,256 @@
+"""High-level field types for elicitation forms with default support."""
+
+from dataclasses import dataclass
+from typing import Any, Union
+
+
+@dataclass
+class StringField:
+    """String field with validation and default support."""
+
+    title: str | None = None
+    description: str | None = None
+    default: str | None = None
+    min_length: int | None = None
+    max_length: int | None = None
+    pattern: str | None = None
+    format: str | None = 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.pattern is not None:
+            schema["pattern"] = self.pattern
+        if self.format:
+            schema["format"] = self.format
+
+        return schema
+
+
+@dataclass
+class IntegerField:
+    """Integer field with validation and default support."""
+
+    title: str | None = None
+    description: str | None = None
+    default: int | None = None
+    minimum: int | None = None
+    maximum: int | None = 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: str | None = None
+    description: str | None = None
+    default: float | None = None
+    minimum: float | None = None
+    maximum: float | None = 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: str | None = None
+    description: str | None = None
+    default: bool | None = 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: list[str] | None = None  # Human-readable names
+    title: str | None = None
+    description: str | None = None
+    default: str | None = 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: str | None = None,
+    description: str | None = None,
+    default: str | None = None,
+    min_length: int | None = None,
+    max_length: int | None = None,
+    pattern: str | None = None,
+    format: str | None = None,
+) -> StringField:
+    """Create a string field."""
+    return StringField(title, description, default, min_length, max_length, pattern, format)
+
+
+def email(
+    title: str | None = None, description: str | None = None, default: str | None = None
+) -> StringField:
+    """Create an email field."""
+    return StringField(title, description, default, format="email")
+
+
+def url(
+    title: str | None = None, description: str | None = None, default: str | None = None
+) -> StringField:
+    """Create a URL field."""
+    return StringField(title, description, default, format="uri")
+
+
+def date(
+    title: str | None = None, description: str | None = None, default: str | None = None
+) -> StringField:
+    """Create a date field."""
+    return StringField(title, description, default, format="date")
+
+
+def datetime(
+    title: str | None = None, description: str | None = None, default: str | None = None
+) -> StringField:
+    """Create a datetime field."""
+    return StringField(title, description, default, format="date-time")
+
+
+def integer(
+    title: str | None = None,
+    description: str | None = None,
+    default: int | None = None,
+    minimum: int | None = None,
+    maximum: int | None = None,
+) -> IntegerField:
+    """Create an integer field."""
+    return IntegerField(title, description, default, minimum, maximum)
+
+
+def number(
+    title: str | None = None,
+    description: str | None = None,
+    default: float | None = None,
+    minimum: float | None = None,
+    maximum: float | None = None,
+) -> NumberField:
+    """Create a number field."""
+    return NumberField(title, description, default, minimum, maximum)
+
+
+def boolean(
+    title: str | None = None, description: str | None = None, default: bool | None = None
+) -> BooleanField:
+    """Create a boolean field."""
+    return BooleanField(title, description, default)
+
+
+def choice(
+    choices: list[str],
+    choice_names: list[str] | None = None,
+    title: str | None = None,
+    description: str | None = None,
+    default: str | None = None,
+) -> EnumField:
+    """Create a choice/enum field."""
+    return EnumField(choices, choice_names, title, description, default)

fast_agent/human_input/simple_form.py

@@ -0,0 +1,113 @@
+"""Simple form API for elicitation schemas without MCP wrappers."""
+
+import asyncio
+from typing import Any, Union
+
+from mcp.types import ElicitRequestedSchema
+
+from fast_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",
+) -> dict[str, Any] | None:
+    """
+    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 fast_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
+
+    # Import here to avoid import-time cycles via package __init__
+    from fast_agent.ui.elicitation_form import show_simple_elicitation_form
+
+    # 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",
+) -> dict[str, Any] | None:
+    """
+    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",
+) -> dict[str, Any] | None:
+    """
+    Short alias for form() function.
+
+    Example:
+        from fast_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",
+) -> dict[str, Any] | None:
+    """
+    Synchronous version of ask().
+
+    Example:
+        result = ask_sync(schema, "What's your info?")
+    """
+    return form_sync(schema, message)

fast_agent/human_input/types.py

@@ -0,0 +1,40 @@
+from typing import Any
+
+from pydantic import BaseModel
+
+HUMAN_INPUT_SIGNAL_NAME = "__human_input__"
+
+
+class HumanInputRequest(BaseModel):
+    """Represents a request for human input."""
+
+    prompt: str
+    """The prompt to show to the user"""
+
+    description: str | None = None
+    """Optional description of what the input is for"""
+
+    request_id: str | None = None
+    """Unique identifier for this request"""
+
+    workflow_id: str | None = None
+    """Optional workflow ID if using workflow engine"""
+
+    timeout_seconds: int | None = None
+    """Optional timeout in seconds"""
+
+    metadata: dict | None = None
+    """Additional request payload"""
+
+
+class HumanInputResponse(BaseModel):
+    """Represents a response to a human input request"""
+
+    request_id: str
+    """ID of the original request"""
+
+    response: str
+    """The input provided by the human"""
+
+    metadata: dict[str, Any] | None = None
+    """Additional response payload"""