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

fast_agent/core/validation.py

@@ -0,0 +1,326 @@
+"""
+Validation utilities for FastAgent configuration and dependencies.
+"""
+
+from typing import Any
+
+from fast_agent.agents.agent_types import AgentType
+from fast_agent.core.exceptions import (
+    AgentConfigError,
+    CircularDependencyError,
+    ServerConfigError,
+)
+from fast_agent.interfaces import LlmAgentProtocol
+from fast_agent.llm.fastagent_llm import FastAgentLLM
+
+
+def validate_server_references(context, agents: dict[str, dict[str, Any]]) -> None:
+    """
+    Validate that all server references in agent configurations exist in config.
+    Raises ServerConfigError if any referenced servers are not defined.
+
+    Args:
+        context: Application context
+        agents: Dictionary of agent configurations
+    """
+    if not context.config.mcp or not context.config.mcp.servers:
+        available_servers = set()
+    else:
+        available_servers = set(context.config.mcp.servers.keys())
+
+    # Check each agent's server references
+    for name, agent_data in agents.items():
+        config = agent_data["config"]
+        if config.servers:
+            missing = [s for s in config.servers if s not in available_servers]
+            if missing:
+                raise ServerConfigError(
+                    f"Missing server configuration for agent '{name}'",
+                    f"The following servers are referenced but not defined in config: {', '.join(missing)}",
+                )
+
+
+def validate_workflow_references(agents: dict[str, dict[str, Any]]) -> None:
+    """
+    Validate that all workflow references point to valid agents/workflows.
+    Also validates that referenced agents have required configuration.
+    Raises AgentConfigError if any validation fails.
+
+    Args:
+        agents: Dictionary of agent configurations
+    """
+    available_components = set(agents.keys())
+
+    for name, agent_data in agents.items():
+        agent_type = agent_data["type"]  # This is a string from config
+
+        # Note: Compare string values from config with the Enum's string value
+        if agent_type == AgentType.PARALLEL.value:
+            # Check fan_in exists
+            fan_in = agent_data["fan_in"]
+            if fan_in and fan_in not in available_components:
+                raise AgentConfigError(
+                    f"Parallel workflow '{name}' references non-existent fan_in component: {fan_in}"
+                )
+
+            # Check fan_out agents exist
+            fan_out = agent_data["fan_out"]
+            missing = [a for a in fan_out if a not in available_components]
+            if missing:
+                raise AgentConfigError(
+                    f"Parallel workflow '{name}' references non-existent fan_out components: {', '.join(missing)}"
+                )
+
+        elif agent_type == AgentType.ORCHESTRATOR.value:
+            # Check all child agents exist and are properly configured
+            child_agents = agent_data["child_agents"]
+            missing = [a for a in child_agents if a not in available_components]
+            if missing:
+                raise AgentConfigError(
+                    f"Orchestrator '{name}' references non-existent agents: {', '.join(missing)}"
+                )
+
+            # Validate child agents have required LLM configuration
+            for agent_name in child_agents:
+                child_data = agents[agent_name]
+                if child_data["type"] == AgentType.BASIC.value:
+                    # For basic agents, we'll validate LLM config during creation
+                    continue
+                # Check if it's a workflow type or has LLM capability
+                # Workflows like EvaluatorOptimizer and Parallel are valid for orchestrator
+                func = child_data["func"]
+                workflow_types = [
+                    AgentType.EVALUATOR_OPTIMIZER.value,
+                    AgentType.PARALLEL.value,
+                    AgentType.ROUTER.value,
+                    AgentType.CHAIN.value,
+                ]
+
+                if not (
+                    isinstance(func, FastAgentLLM)
+                    or child_data["type"] in workflow_types
+                    or (isinstance(func, LlmAgentProtocol) and func.llm is not None)
+                ):
+                    raise AgentConfigError(
+                        f"Agent '{agent_name}' used by orchestrator '{name}' lacks LLM capability",
+                        "All agents used by orchestrators must be LLM-capable (either an AugmentedLLM or implement LlmAgentProtocol)",
+                    )
+
+        elif agent_type == AgentType.ROUTER.value:
+            # Check all referenced agents exist
+            router_agents = agent_data["router_agents"]
+            missing = [a for a in router_agents if a not in available_components]
+            if missing:
+                raise AgentConfigError(
+                    f"Router '{name}' references non-existent agents: {', '.join(missing)}"
+                )
+
+        elif agent_type == AgentType.EVALUATOR_OPTIMIZER.value:
+            # Check both evaluator and optimizer exist
+            evaluator = agent_data["evaluator"]
+            generator = agent_data["generator"]
+            missing = []
+            if evaluator not in available_components:
+                missing.append(f"evaluator: {evaluator}")
+            if generator not in available_components:
+                missing.append(f"generator: {generator}")
+            if missing:
+                raise AgentConfigError(
+                    f"Evaluator-Optimizer '{name}' references non-existent components: {', '.join(missing)}"
+                )
+
+        elif agent_type == AgentType.CHAIN.value:
+            # Check that all agents in the sequence exist
+            sequence = agent_data.get("sequence", agent_data.get("agents", []))
+            missing = [a for a in sequence if a not in available_components]
+            if missing:
+                raise AgentConfigError(
+                    f"Chain '{name}' references non-existent agents: {', '.join(missing)}"
+                )
+
+
+def get_dependencies(
+    name: str,
+    agents: dict[str, dict[str, Any]],
+    visited: set,
+    path: set,
+    agent_type: AgentType = None,
+) -> list[str]:
+    """
+    Get dependencies for an agent in topological order.
+    Works for both Parallel and Chain workflows.
+
+    Args:
+        name: Name of the agent
+        agents: Dictionary of agent configurations
+        visited: Set of already visited agents
+        path: Current path for cycle detection
+        agent_type: Optional type filter (e.g., only check Parallel or Chain)
+
+    Returns:
+        List of agent names in dependency order
+
+    Raises:
+        CircularDependencyError: If circular dependency detected
+    """
+    if name in path:
+        path_str = " -> ".join(path)
+        raise CircularDependencyError(f"Path: {path_str} -> {name}")
+
+    if name in visited:
+        return []
+
+    if name not in agents:
+        return []
+
+    config = agents[name]
+
+    # Skip if not the requested type (when filtering)
+    if agent_type and config["type"] != agent_type.value:
+        return []
+
+    path.add(name)
+    deps = []
+
+    # Handle dependencies based on agent type
+    if config["type"] == AgentType.PARALLEL.value:
+        # Get dependencies from fan-out agents
+        for fan_out in config["fan_out"]:
+            deps.extend(get_dependencies(fan_out, agents, visited, path, agent_type))
+    elif config["type"] == AgentType.CHAIN.value:
+        # Get dependencies from sequence agents
+        sequence = config.get("sequence", config.get("router_agents", []))
+        for agent_name in sequence:
+            deps.extend(get_dependencies(agent_name, agents, visited, path, agent_type))
+
+    # Add this agent after its dependencies
+    deps.append(name)
+    visited.add(name)
+    path.remove(name)
+
+    return deps
+
+
+def get_agent_dependencies(agent_data: dict[str, Any]) -> set[str]:
+    deps: set[str] = set()
+    agent_dependency_attribute_names = {
+        AgentType.CHAIN: ("sequence",),
+        AgentType.EVALUATOR_OPTIMIZER: ("evaluator", "generator", "eval_optimizer_agents"),
+        AgentType.ITERATIVE_PLANNER: ("child_agents",),
+        AgentType.ORCHESTRATOR: ("child_agents",),
+        AgentType.BASIC: ("child_agents",),
+        AgentType.PARALLEL: ("fan_out", "fan_in", "parallel_agents"),
+        AgentType.ROUTER: ("router_agents",),
+    }
+    agent_type = agent_data["type"]
+    dependency_names = agent_dependency_attribute_names.get(agent_type, None)
+    if dependency_names is None:
+        return deps
+
+    for dependency_name in dependency_names:
+        dependency_value = agent_data.get(dependency_name)
+        if dependency_value is None:
+            continue
+        if isinstance(dependency_value, str):
+            deps.add(dependency_value)
+        else:
+            # here, we have an implicit assumption that if it is not a None or a string, then it is a list
+            deps.update(dependency_value)
+
+    return deps
+
+
+def get_dependencies_groups(
+    agents_dict: dict[str, dict[str, Any]], allow_cycles: bool = False
+) -> list[list[str]]:
+    """
+    Get dependencies between agents and group them into dependency layers.
+    Each layer can be initialized in parallel.
+
+    Args:
+        agents_dict: Dictionary of agent configurations
+        allow_cycles: Whether to allow cyclic dependencies
+
+    Returns:
+        List of lists, where each inner list is a group of agents that can be initialized together
+
+    Raises:
+        CircularDependencyError: If circular dependency detected and allow_cycles is False
+    """
+    # Get all agent names
+    agent_names = list(agents_dict.keys())
+
+    # Dictionary to store dependencies for each agent
+    dependencies = {
+        name: get_agent_dependencies(agent_data) for name, agent_data in agents_dict.items()
+    }
+
+    # Check for cycles if not allowed
+    if not allow_cycles:
+        visited = set()
+        path = set()
+
+        def visit(node) -> None:
+            if node in path:
+                path_str = " -> ".join(path) + " -> " + node
+                raise CircularDependencyError(f"Circular dependency detected: {path_str}")
+            if node in visited:
+                return
+
+            path.add(node)
+            for dep in dependencies[node]:
+                if dep in agent_names:  # Skip dependencies to non-existent agents
+                    visit(dep)
+            path.remove(node)
+            visited.add(node)
+
+        # Check each node
+        for name in agent_names:
+            if name not in visited:
+                visit(name)
+
+    # Group agents by dependency level
+    result = []
+    remaining = set(agent_names)
+
+    while remaining:
+        # Find all agents that have no remaining dependencies
+        current_level = set()
+        for name in remaining:
+            if not dependencies[name] & remaining:  # If no dependencies in remaining agents
+                current_level.add(name)
+
+        if not current_level:
+            if allow_cycles:
+                # If cycles are allowed, just add one remaining node to break the cycle
+                current_level.add(next(iter(remaining)))
+            else:
+                # This should not happen if we checked for cycles
+                raise CircularDependencyError("Unresolvable dependency cycle detected")
+
+        # Add the current level to the result
+        result.append(list(current_level))
+
+        # Remove current level from remaining
+        remaining -= current_level
+
+    return result
+
+
+def validate_provider_keys_post_creation(active_agents: dict[str, Any]) -> None:
+    """
+    Validate that API keys are available for all created agents with LLMs.
+
+    This runs after agent creation when we have actual agent instances.
+
+    Args:
+        active_agents: Dictionary of created agent instances
+
+    Raises:
+        ProviderKeyError: If any required API key is missing
+    """
+    for agent_name, agent in active_agents.items():
+        llm = getattr(agent, "_llm", None)
+        if llm:
+            # This throws a ProviderKeyError if the key is not present
+            llm._api_key()

fast_agent/event_progress.py

@@ -0,0 +1,62 @@
+"""Module for converting log events to progress events."""
+
+from enum import Enum
+
+from pydantic import BaseModel
+
+
+class ProgressAction(str, Enum):
+    """Progress actions available in the system."""
+
+    STARTING = "Starting"
+    LOADED = "Loaded"
+    INITIALIZED = "Initialized"
+    CHATTING = "Chatting"
+    STREAMING = "Streaming"  # Special action for real-time streaming updates
+    THINKING = "Thinking"  # Special action for real-time thinking updates
+    ROUTING = "Routing"
+    PLANNING = "Planning"
+    READY = "Ready"
+    CALLING_TOOL = "Calling Tool"
+    TOOL_PROGRESS = "Tool Progress"
+    UPDATED = "Updated"
+    FINISHED = "Finished"
+    SHUTDOWN = "Shutdown"
+    AGGREGATOR_INITIALIZED = "Running"
+    SERVER_OFFLINE = "Offline"
+    SERVER_RECONNECTING = "Reconnecting"
+    SERVER_ONLINE = "Online"
+    FATAL_ERROR = "Error"
+
+
+class ProgressEvent(BaseModel):
+    """Represents a progress event converted from a log event."""
+
+    action: ProgressAction
+    target: str
+    details: str | None = None
+    agent_name: str | None = None
+    correlation_id: str | None = None
+    instance_name: str | None = None
+    tool_name: str | None = None
+    streaming_tokens: str | None = None  # Special field for streaming token count
+    progress: float | None = None  # Current progress value
+    total: float | None = None  # Total value for progress calculation
+
+    def __str__(self) -> str:
+        """Format the progress event for display."""
+        # Special handling for streaming - show token count in action position
+        if self.action == ProgressAction.STREAMING and self.streaming_tokens:
+            # For streaming, show just the token count instead of "Streaming"
+            action_display = self.streaming_tokens.ljust(11)
+            base = f"{action_display}. {self.target}"
+            if self.details:
+                base += f" - {self.details}"
+        else:
+            base = f"{self.action.ljust(11)}. {self.target}"
+            if self.details:
+                base += f" - {self.details}"
+
+        if self.agent_name:
+            base = f"[{self.agent_name}] {base}"
+        return base

fast_agent/history/history_exporter.py

@@ -0,0 +1,49 @@
+"""
+History export utilities for agents.
+
+Provides a minimal, type-friendly way to save an agent's message history
+without using control strings. Uses the existing serialization helpers
+to choose JSON (for .json files) or Markdown-like delimited text otherwise.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fast_agent.mcp.prompt_serialization import save_messages
+
+if TYPE_CHECKING:
+    from fast_agent.interfaces import AgentProtocol
+
+
+class HistoryExporter:
+    """Utility for exporting agent history to a file."""
+
+    @staticmethod
+    async def save(agent: AgentProtocol, filename: str | None = None) -> str:
+        """
+        Save the given agent's message history to a file.
+
+        If filename ends with ".json", the history is saved in MCP JSON format.
+        Otherwise, it is saved in a human-readable Markdown-style format.
+
+        Args:
+            agent: The agent whose history will be saved.
+            filename: Optional filename. If None, a default timestamped name is generated.
+
+        Returns:
+            The path that was written to.
+        """
+        # Determine a default filename when not provided
+        if not filename:
+            from datetime import datetime
+            timestamp = datetime.now().strftime("%y_%m_%d_%H_%M")
+            target = f"{timestamp}-conversation.json"
+        else:
+            target = filename
+
+        messages = agent.message_history
+        save_messages(messages, target)
+
+        # Return and optionally print a small confirmation
+        return target

fast_agent/human_input/__init__.py

@@ -0,0 +1,47 @@
+"""Human input modules for forms and elicitation.
+
+Keep __init__ lightweight to avoid circular imports during submodule import.
+Exports schema builders directly and defers simple form API imports.
+"""
+
+from fast_agent.human_input.form_fields import (
+    BooleanField,
+    EnumField,
+    FormSchema,
+    IntegerField,
+    NumberField,
+    StringField,
+    boolean,
+    choice,
+    date,
+    datetime,
+    email,
+    integer,
+    number,
+    string,
+    url,
+)
+
+__all__ = [
+    # Schema builder
+    "FormSchema",
+    # Field classes
+    "StringField",
+    "IntegerField",
+    "NumberField",
+    "BooleanField",
+    "EnumField",
+    # Field convenience functions
+    "string",
+    "email",
+    "url",
+    "date",
+    "datetime",
+    "integer",
+    "number",
+    "boolean",
+    "choice",
+]
+
+# Note: form(), ask() helpers are available via fast_agent.human_input.simple_form;
+# intentionally not imported here to avoid import-time cycles.

fast_agent/human_input/elicitation_handler.py

@@ -0,0 +1,123 @@
+from typing import Any
+
+from fast_agent.human_input.elicitation_state import elicitation_state
+from fast_agent.human_input.types import (
+    HumanInputRequest,
+    HumanInputResponse,
+)
+from fast_agent.tools.elicitation import set_elicitation_input_callback
+from fast_agent.ui.elicitation_form import (
+    show_simple_elicitation_form,
+)
+from fast_agent.ui.elicitation_style import (
+    ELICITATION_STYLE,
+)
+from fast_agent.ui.progress_display import progress_display
+
+
+async def elicitation_input_callback(
+    request: HumanInputRequest,
+    agent_name: str | None = None,
+    server_name: str | None = None,
+    server_info: dict[str, Any] | None = None,
+) -> HumanInputResponse:
+    """Request input from a human user for MCP server elicitation requests."""
+
+    # Extract effective names
+    effective_agent_name = agent_name or (
+        request.metadata.get("agent_name", "Unknown Agent") if request.metadata else "Unknown Agent"
+    )
+    effective_server_name = server_name or "Unknown Server"
+
+    # Start tracking elicitation operation
+    try:
+        from fast_agent.ui import notification_tracker
+        notification_tracker.start_elicitation(effective_server_name)
+    except Exception:
+        # Don't let notification tracking break elicitation
+        pass
+
+    try:
+        # Check if elicitation is disabled for this server
+        if elicitation_state.is_disabled(effective_server_name):
+            return HumanInputResponse(
+                request_id=request.request_id,
+                response="__CANCELLED__",
+                metadata={"auto_cancelled": True, "reason": "Server elicitation disabled by user"},
+            )
+
+        # Get the elicitation schema from metadata
+        schema: dict[str, Any] | None = None
+        if request.metadata and "requested_schema" in request.metadata:
+            schema = request.metadata["requested_schema"]
+
+        # Use the context manager to pause the progress display while getting input
+        with progress_display.paused():
+            try:
+                if schema:
+                    form_action, form_data = await show_simple_elicitation_form(
+                        schema=schema,
+                        message=request.prompt,
+                        agent_name=effective_agent_name,
+                        server_name=effective_server_name,
+                    )
+
+                    if form_action == "accept" and form_data is not None:
+                        # Convert form data to JSON string
+                        import json
+
+                        response = json.dumps(form_data)
+                    elif form_action == "decline":
+                        response = "__DECLINED__"
+                    elif form_action == "disable":
+                        response = "__DISABLE_SERVER__"
+                    else:  # cancel
+                        response = "__CANCELLED__"
+                else:
+                    # No schema, fall back to text input using prompt_toolkit only
+                    from prompt_toolkit.shortcuts import input_dialog
+
+                    response = await input_dialog(
+                        title="Input Requested",
+                        text=f"Agent: {effective_agent_name}\nServer: {effective_server_name}\n\n{request.prompt}",
+                        style=ELICITATION_STYLE,
+                    ).run_async()
+
+                    if response is None:
+                        response = "__CANCELLED__"
+
+            except KeyboardInterrupt:
+                response = "__CANCELLED__"
+            except EOFError:
+                response = "__CANCELLED__"
+
+        return HumanInputResponse(
+            request_id=request.request_id,
+            response=response.strip() if isinstance(response, str) else response,
+            metadata={"has_schema": schema is not None},
+        )
+    finally:
+        # End tracking elicitation operation
+        try:
+            from fast_agent.ui import notification_tracker
+            notification_tracker.end_elicitation(effective_server_name)
+        except Exception:
+            # Don't let notification tracking break elicitation
+            pass
+
+
+# Register adapter with fast_agent tools so they can invoke this UI handler without importing types
+async def _elicitation_adapter(
+    request_payload: dict,
+    agent_name: str | None = None,
+    server_name: str | None = None,
+    server_info: dict[str, Any] | None = None,
+) -> str:
+    req = HumanInputRequest(**request_payload)
+    resp = await elicitation_input_callback(
+        request=req, agent_name=agent_name, server_name=server_name, server_info=server_info
+    )
+    return resp.response if isinstance(resp.response, str) else str(resp.response)
+
+
+set_elicitation_input_callback(_elicitation_adapter)

fast_agent/human_input/elicitation_state.py

@@ -0,0 +1,33 @@
+"""Simple state management for elicitation Cancel All functionality."""
+
+
+
+class ElicitationState:
+    """Manages global state for elicitation requests, including disabled servers."""
+
+    def __init__(self):
+        self.disabled_servers: set[str] = set()
+
+    def disable_server(self, server_name: str) -> None:
+        """Disable elicitation requests for a specific server."""
+        self.disabled_servers.add(server_name)
+
+    def is_disabled(self, server_name: str) -> bool:
+        """Check if elicitation is disabled for a server."""
+        return server_name in self.disabled_servers
+
+    def enable_server(self, server_name: str) -> None:
+        """Re-enable elicitation requests for a specific server."""
+        self.disabled_servers.discard(server_name)
+
+    def clear_all(self) -> None:
+        """Clear all disabled servers."""
+        self.disabled_servers.clear()
+
+    def get_disabled_servers(self) -> set[str]:
+        """Get a copy of all disabled servers."""
+        return self.disabled_servers.copy()
+
+
+# Global instance for session-scoped Cancel All functionality
+elicitation_state = ElicitationState()