fast-agent-mcp 0.2.57__py3-none-any.whl → 0.3.0__py3-none-any.whl

fast_agent/tools/elicitation.py

@@ -0,0 +1,369 @@
+from __future__ import annotations
+
+import json
+import uuid
+from typing import Any, Awaitable, Callable, List, Literal, Optional, Union
+
+from mcp.server.fastmcp.tools import Tool as FastMCPTool
+from mcp.types import Tool as McpTool
+from pydantic import BaseModel, Field
+
+from fast_agent.constants import HUMAN_INPUT_TOOL_NAME
+
+"""
+Human-input (elicitation) tool models, schemas, and builders.
+
+This module lives in fast_agent to avoid circular imports and provides:
+- A centralized HUMAN_INPUT_TOOL_NAME constant (imported from fast_agent.constants)
+- Pydantic models for a simplified FormSpec (LLM-friendly)
+- MCP Tool schema builder (sanitized, provider-friendly)
+- FastMCP Tool builder sharing the same schema
+- A lightweight async callback registry for UI-specific elicitation handling
+"""
+
+# -----------------------
+# Pydantic models
+# -----------------------
+
+
+class OptionItem(BaseModel):
+    value: Union[str, int, float, bool]
+    label: Optional[str] = None
+
+
+class FormField(BaseModel):
+    name: str
+    type: Literal["text", "textarea", "number", "checkbox", "radio"]
+    label: Optional[str] = None
+    help: Optional[str] = None
+    default: Optional[Union[str, int, float, bool]] = None
+    required: Optional[bool] = None
+    # number constraints
+    min: Optional[float] = None
+    max: Optional[float] = None
+    # select options (for radio)
+    options: Optional[List[OptionItem]] = None
+
+
+class HumanFormArgs(BaseModel):
+    """Simplified form spec for human elicitation.
+
+    Preferred shape for LLMs.
+    """
+
+    title: Optional[str] = None
+    description: Optional[str] = None
+    message: Optional[str] = None
+    fields: List[FormField] = Field(default_factory=list, max_length=7)
+
+
+# -----------------------
+# MCP tool schema builder
+# -----------------------
+
+
+def get_elicitation_tool() -> McpTool:
+    """Build the MCP Tool schema for the elicitation-backed human input tool.
+
+    Uses Pydantic models to derive a clean, portable JSON Schema suitable for providers.
+    """
+
+    schema = HumanFormArgs.model_json_schema()
+
+    def _resolve_refs(fragment: Any, root: dict[str, Any]) -> Any:
+        """Inline $ref references within a JSON schema fragment using the given root schema.
+
+        Supports local references of the form '#/$defs/Name'.
+        """
+        if not isinstance(fragment, dict):
+            return fragment
+
+        if "$ref" in fragment:
+            ref_path: str = fragment["$ref"]
+            if ref_path.startswith("#/$defs/") and "$defs" in root:
+                key = (
+                    ref_path.split("/#/$defs/")[-1]
+                    if "/#/$defs/" in ref_path
+                    else ref_path[len("#/$defs/") :]
+                )
+                target = root.get("$defs", {}).get(key)
+                if isinstance(target, dict):
+                    return _resolve_refs(target, root)
+            fragment = {k: v for k, v in fragment.items() if k != "$ref"}
+            fragment.setdefault("type", "object")
+            fragment.setdefault("properties", {})
+            return fragment
+
+        resolved: dict[str, Any] = {}
+        for k, v in fragment.items():
+            if isinstance(v, dict):
+                resolved[k] = _resolve_refs(v, root)
+            elif isinstance(v, list):
+                resolved[k] = [
+                    _resolve_refs(item, root) if isinstance(item, (dict, list)) else item
+                    for item in v
+                ]
+            else:
+                resolved[k] = v
+        return resolved
+
+    sanitized: dict[str, Any] = {"type": "object"}
+    if "properties" in schema:
+        props = dict(schema["properties"])  # copy
+        if "form_schema" in props:
+            props["schema"] = props.pop("form_schema")
+        props = _resolve_refs(props, schema)
+        sanitized["properties"] = props
+    else:
+        sanitized["properties"] = {}
+    if "required" in schema:
+        sanitized["required"] = schema["required"]
+    sanitized["additionalProperties"] = True
+
+    return McpTool(
+        name=HUMAN_INPUT_TOOL_NAME,
+        description=(
+            "Collect structured input from a human via a simple form. "
+            "Provide up to 7 fields with types: text, textarea, number, checkbox, or radio. "
+            "Each field may include label, help, default; numbers may include min/max; radio may include options (value/label). "
+            "You may also add an optional message shown above the form."
+        ),
+        inputSchema=sanitized,
+    )
+
+
+# -----------------------
+# Elicitation input callback registry
+# -----------------------
+
+ElicitationCallback = Callable[[dict, Optional[str], Optional[str], Optional[dict]], Awaitable[str]]
+
+_elicitation_input_callback: ElicitationCallback | None = None
+
+
+def set_elicitation_input_callback(callback: ElicitationCallback) -> None:
+    """Register the UI/backend-specific elicitation handler.
+
+    The callback should accept a request dict with fields: prompt, description, request_id, metadata,
+    plus optional agent_name, server_name, and server_info, and return an awaited string response.
+    """
+
+    global _elicitation_input_callback
+    _elicitation_input_callback = callback
+
+
+def get_elicitation_input_callback() -> ElicitationCallback | None:
+    return _elicitation_input_callback
+
+
+# -----------------------
+# Runtime: run the elicitation
+# -----------------------
+
+
+async def run_elicitation_form(arguments: dict | str, agent_name: str | None = None) -> str:
+    """Parse arguments into a JSON Schema or simplified fields spec and invoke the registered callback.
+
+    Returns the response string from the callback. Raises if no callback is registered.
+    """
+
+    def parse_schema_string(val: str) -> dict | None:
+        if not isinstance(val, str):
+            return None
+        s = val.strip()
+        if s.startswith("```"):
+            lines = s.splitlines()
+            if lines:
+                lines = lines[1:]
+            if lines and lines[-1].strip().startswith("```"):
+                lines = lines[:-1]
+            s = "\n".join(lines)
+        try:
+            return json.loads(s)
+        except Exception:
+            return None
+
+    if not isinstance(arguments, dict):
+        if isinstance(arguments, str):
+            parsed = parse_schema_string(arguments)
+            if isinstance(parsed, dict):
+                arguments = parsed
+            else:
+                raise ValueError("Invalid arguments. Provide FormSpec or JSON Schema object.")
+        else:
+            raise ValueError("Invalid arguments. Provide FormSpec or JSON Schema object.")
+
+    schema: dict | None = None
+    message: str | None = None
+    title: str | None = None
+    description: str | None = None
+
+    if isinstance(arguments.get("fields"), list):
+        fields = arguments.get("fields")
+        if len(fields) > 7:
+            raise ValueError(
+                f"Error: form requests {len(fields)} fields; the maximum allowed is 7."
+            )
+
+        properties: dict[str, Any] = {}
+        required_fields: list[str] = []
+        for field in fields:
+            if not isinstance(field, dict):
+                continue
+            name = field.get("name")
+            ftype = field.get("type")
+            if not isinstance(name, str) or not isinstance(ftype, str):
+                continue
+            prop: dict[str, Any] = {}
+            label = field.get("label")
+            help_text = field.get("help")
+            default = field.get("default")
+            required_flag = field.get("required")
+
+            if ftype in ("text", "textarea"):
+                prop["type"] = "string"
+            elif ftype == "number":
+                prop["type"] = "number"
+                if isinstance(field.get("min"), (int, float)):
+                    prop["minimum"] = field.get("min")
+                if isinstance(field.get("max"), (int, float)):
+                    prop["maximum"] = field.get("max")
+            elif ftype == "checkbox":
+                prop["type"] = "boolean"
+            elif ftype == "radio":
+                prop["type"] = "string"
+                options = field.get("options") or []
+                enum_vals = []
+                enum_names = []
+                for opt in options:
+                    if isinstance(opt, dict) and "value" in opt:
+                        enum_vals.append(opt["value"])
+                        if isinstance(opt.get("label"), str):
+                            enum_names.append(opt.get("label"))
+                    elif opt is not None:
+                        enum_vals.append(opt)
+                if enum_vals:
+                    prop["enum"] = enum_vals
+                    if enum_names and len(enum_names) == len(enum_vals):
+                        prop["enumNames"] = enum_names
+            else:
+                continue
+
+            desc_parts = []
+            if isinstance(label, str) and label:
+                desc_parts.append(label)
+            if isinstance(help_text, str) and help_text:
+                desc_parts.append(help_text)
+            if desc_parts:
+                prop["description"] = " - ".join(desc_parts)
+            if default is not None:
+                prop["default"] = default
+            properties[name] = prop
+            if isinstance(required_flag, bool) and required_flag:
+                required_fields.append(name)
+
+        if len(properties) == 0:
+            raise ValueError("Invalid form specification: no valid fields provided.")
+
+        schema = {"type": "object", "properties": properties}
+        if required_fields:
+            schema["required"] = required_fields
+
+        title = arguments.get("title") if isinstance(arguments.get("title"), str) else None
+        description = (
+            arguments.get("description") if isinstance(arguments.get("description"), str) else None
+        )
+        msg = arguments.get("message")
+        if isinstance(msg, str):
+            message = msg
+        if title:
+            schema["title"] = title
+        if description:
+            schema["description"] = description
+
+    elif isinstance(arguments.get("schema"), (dict, str)):
+        schema = arguments.get("schema")
+        if isinstance(schema, str):
+            parsed = parse_schema_string(schema)
+            if isinstance(parsed, dict):
+                schema = parsed
+            else:
+                raise ValueError("Missing or invalid schema. Provide a JSON Schema object.")
+        msg = arguments.get("message")
+        if isinstance(msg, str):
+            message = msg
+        if isinstance(arguments.get("title"), str) and "title" not in schema:
+            schema["title"] = arguments.get("title")
+        if isinstance(arguments.get("description"), str) and "description" not in schema:
+            schema["description"] = arguments.get("description")
+        if isinstance(arguments.get("required"), list) and "required" not in schema:
+            schema["required"] = arguments.get("required")
+        if isinstance(arguments.get("properties"), dict) and "properties" not in schema:
+            schema["properties"] = arguments.get("properties")
+
+    elif ("type" in arguments and "properties" in arguments) or (
+        "$schema" in arguments and "properties" in arguments
+    ):
+        schema = arguments
+        message = None
+    else:
+        raise ValueError("Missing or invalid schema or fields in arguments.")
+
+    props = schema.get("properties", {}) if isinstance(schema.get("properties"), dict) else {}
+    if len(props) > 7:
+        raise ValueError(f"Error: schema requests {len(props)} fields; the maximum allowed is 7.")
+
+    request_payload: dict[str, Any] = {
+        "prompt": message or schema.get("title") or "Please complete this form:",
+        "description": schema.get("description"),
+        "request_id": f"__human_input__{uuid.uuid4()}",
+        "metadata": {
+            "agent_name": agent_name or "Unknown Agent",
+            "requested_schema": schema,
+        },
+    }
+
+    cb = get_elicitation_input_callback()
+    if not cb:
+        raise RuntimeError("No elicitation input callback registered")
+
+    response_text: str = await cb(
+        request_payload,
+        agent_name or "Unknown Agent",
+        "__human_input__",
+        None,
+    )
+
+    return response_text
+
+
+# -----------------------
+# FastMCP tool builder
+# -----------------------
+
+
+def get_elicitation_fastmcp_tool() -> FastMCPTool:
+    async def elicit(
+        title: Optional[str] = None,
+        description: Optional[str] = None,
+        message: Optional[str] = None,
+        fields: List[FormField] = Field(default_factory=list, max_length=7),
+    ) -> str:
+        args = {
+            "title": title,
+            "description": description,
+            "message": message,
+            "fields": [f.model_dump() if isinstance(f, BaseModel) else f for f in fields],
+        }
+        return await run_elicitation_form(args)
+
+    tool = FastMCPTool.from_function(elicit)
+    tool.name = HUMAN_INPUT_TOOL_NAME
+    tool.description = (
+        "Collect structured input from a human via a simple form. Provide up to 7 fields "
+        "(text, textarea, number, checkbox, radio). Fields can include label, help, default; "
+        "numbers support min/max; radio supports options (value/label); optional message is shown above the form."
+    )
+    # Harmonize input schema with the sanitized MCP schema for provider compatibility
+    tool.parameters = get_elicitation_tool().inputSchema
+    return tool

fast_agent/types/__init__.py

@@ -0,0 +1,32 @@
+"""Shared type definitions and helpers for fast-agent.
+
+Goals:
+- Provide a stable import path for commonly used public types and helpers
+- Keep dependencies minimal to reduce import-time cycles
+"""
+
+# Re-export common enums/types
+# Public request parameters used to configure LLM calls
+from fast_agent.llm.request_params import RequestParams
+
+# Content helpers commonly used by users to build messages
+from fast_agent.mcp.helpers.content_helpers import (
+    ensure_multipart_messages,
+    normalize_to_extended_list,
+    text_content,
+)
+
+# Public message model used across providers and MCP integration
+from fast_agent.mcp.prompt_message_extended import PromptMessageExtended
+from fast_agent.types.llm_stop_reason import LlmStopReason
+
+__all__ = [
+    # Enums / types
+    "LlmStopReason",
+    "PromptMessageExtended",
+    "RequestParams",
+    # Content helpers
+    "text_content",
+    "ensure_multipart_messages",
+    "normalize_to_extended_list",
+]

fast_agent/types/llm_stop_reason.py

@@ -0,0 +1,77 @@
+"""LLM-related type definitions for fast-agent."""
+
+from enum import Enum
+from typing import Union
+
+
+class LlmStopReason(str, Enum):
+    """
+    Enumeration of stop reasons for LLM message generation.
+
+    Extends the MCP SDK's standard stop reasons with additional custom values.
+    Inherits from str to ensure compatibility with string-based APIs.
+    Used primarily in PromptMessageExtended and LLM response handling.
+    """
+
+    # MCP SDK standard values (from mcp.types.StopReason)
+    END_TURN = "endTurn"
+    STOP_SEQUENCE = "stopSequence"
+    MAX_TOKENS = "maxTokens"
+    TOOL_USE = "toolUse"  # Used when LLM stops to call tools
+    PAUSE = "pause"
+
+    # Custom extensions for fast-agent
+    ERROR = "error"  # Used when there's an error in generation
+
+    TIMEOUT = "timeout"  # Used when generation times out
+    SAFETY = "safety"  # a safety or content warning was triggered
+
+    def __eq__(self, other: object) -> bool:
+        """
+        Allow comparison with both enum members and raw strings.
+
+        This enables code like:
+        - result.stopReason == LlmStopReason.END_TURN
+        - result.stopReason == "endTurn"
+        """
+        if isinstance(other, str):
+            return self.value == other
+        return super().__eq__(other)
+
+    @classmethod
+    def from_string(cls, value: Union[str, "LlmStopReason"]) -> "LlmStopReason":
+        """
+        Convert a string to a LlmStopReason enum member.
+
+        Args:
+            value: A string or LlmStopReason enum member
+
+        Returns:
+            The corresponding LlmStopReason enum member
+
+        Raises:
+            ValueError: If the string doesn't match any enum value
+        """
+        if isinstance(value, cls):
+            return value
+
+        for member in cls:
+            if member.value == value:
+                return member
+
+        raise ValueError(
+            f"Invalid stop reason: {value}. Valid values are: {[m.value for m in cls]}"
+        )
+
+    @classmethod
+    def is_valid(cls, value: str) -> bool:
+        """
+        Check if a string is a valid stop reason.
+
+        Args:
+            value: A string to check
+
+        Returns:
+            True if the string matches a valid stop reason, False otherwise
+        """
+        return value in [member.value for member in cls]

fast_agent/ui/__init__.py

@@ -0,0 +1,38 @@
+"""UI utilities and primitives for interactive console features.
+
+Design goals:
+- Keep import side-effects minimal to avoid circular imports.
+- Make primitives easy to access with lazy attribute loading.
+"""
+
+from typing import Any
+
+__all__ = [
+    "ElicitationForm",
+    "show_simple_elicitation_form",
+    "form_dialog",
+    "ELICITATION_STYLE",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy attribute loader to avoid importing heavy modules at package import time."""
+    if name == "ELICITATION_STYLE":
+        from .elicitation_style import ELICITATION_STYLE as _STYLE
+
+        return _STYLE
+    if name in ("ElicitationForm", "show_simple_elicitation_form", "form_dialog"):
+        from .elicitation_form import (
+            ElicitationForm as _Form,
+        )
+        from .elicitation_form import (
+            show_simple_elicitation_form as _show,
+        )
+
+        if name == "ElicitationForm":
+            return _Form
+        if name == "show_simple_elicitation_form":
+            return _show
+        if name == "form_dialog":
+            return _show
+    raise AttributeError(name)