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

mcp_agent/event_progress.py

@@ -0,0 +1,88 @@
+"""Module for converting log events to progress events."""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+from mcp_agent.logging.events import Event
+
+
+class ProgressAction(str, Enum):
+    """Progress actions available in the system."""
+
+    STARTING = "Starting"
+    INITIALIZED = "Initialized"
+    CHATTING = "Chatting"
+    READY = "Ready"
+    CALLING_TOOL = "Calling Tool"
+    FINISHED = "Finished"
+    SHUTDOWN = "Shutdown"
+    AGGREGATOR_INITIALIZED = "Running"
+    ROUTING = "Routing"
+
+
+@dataclass
+class ProgressEvent:
+    """Represents a progress event converted from a log event."""
+
+    action: ProgressAction
+    target: str
+    details: Optional[str] = None
+    agent_name: Optional[str] = None
+
+    def __str__(self) -> str:
+        """Format the progress event for display."""
+        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
+
+
+def convert_log_event(event: Event) -> Optional[ProgressEvent]:
+    """Convert a log event to a progress event if applicable."""
+
+    # Check to see if there is any additional data
+    if not event.data:
+        return None
+
+    event_data = event.data.get("data")
+    if not isinstance(event_data, dict):
+        return None
+
+    progress_action = event_data.get("progress_action")
+    if not progress_action:
+        return None
+
+    # Build target string based on the event type.
+    # Progress display is currently [time] [event] --- [target] [details]
+    namespace = event.namespace
+    agent_name = event_data.get("agent_name")
+    target = agent_name
+    details = ""
+    if "mcp_aggregator" in namespace:
+        server_name = event_data.get("server_name", "")
+        tool_name = event_data.get("tool_name")
+        if tool_name:
+            # fetch(fetch)
+            details = f"{server_name} ({tool_name})"
+        else:
+            details = f"{server_name}"
+
+    elif "augmented_llm" in namespace:
+        model = event_data.get("model", "")
+
+        details = f"{model}"
+        chat_turn = event_data.get("chat_turn")
+        if chat_turn is not None:
+            details = f"{model} turn {chat_turn}"
+    else:
+        target = event_data.get("target", "unknown")
+
+    return ProgressEvent(
+        ProgressAction(progress_action),
+        target,
+        details,
+        agent_name=event_data.get("agent_name"),
+    )

mcp_agent/executor/decorator_registry.py

@@ -0,0 +1,120 @@
+"""
+Keep track of all workflow decorator overloads indexed by executor backend.
+Different executors may have different ways of configuring workflows.
+"""
+
+from typing import Callable, Dict, Type, TypeVar
+
+R = TypeVar("R")
+
+
+class DecoratorRegistry:
+    """Centralized decorator management with validation and metadata."""
+
+    def __init__(self):
+        self._workflow_defn_decorators: Dict[str, Callable[[Type], Type]] = {}
+        self._workflow_run_decorators: Dict[
+            str, Callable[[Callable[..., R]], Callable[..., R]]
+        ] = {}
+
+    def register_workflow_defn_decorator(
+        self,
+        executor_name: str,
+        decorator: Callable[[Type], Type],
+    ):
+        """
+        Registers a workflow definition decorator for a given executor.
+
+        :param executor_name: Unique name of the executor.
+        :param decorator: The decorator to register.
+        """
+        if executor_name in self._workflow_defn_decorators:
+            print(
+                "Workflow definition decorator already registered for '%s'. Overwriting.",
+                executor_name,
+            )
+        self._workflow_defn_decorators[executor_name] = decorator
+
+    def get_workflow_defn_decorator(self, executor_name: str) -> Callable[[Type], Type]:
+        """
+        Retrieves a workflow definition decorator for a given executor.
+
+        :param executor_name: Unique name of the executor.
+        :return: The decorator function.
+        """
+        return self._workflow_defn_decorators.get(executor_name)
+
+    def register_workflow_run_decorator(
+        self,
+        executor_name: str,
+        decorator: Callable[[Callable[..., R]], Callable[..., R]],
+    ):
+        """
+        Registers a workflow run decorator for a given executor.
+
+        :param executor_name: Unique name of the executor.
+        :param decorator: The decorator to register.
+        """
+        if executor_name in self._workflow_run_decorators:
+            print(
+                "Workflow run decorator already registered for '%s'. Overwriting.",
+                executor_name,
+            )
+        self._workflow_run_decorators[executor_name] = decorator
+
+    def get_workflow_run_decorator(
+        self, executor_name: str
+    ) -> Callable[[Callable[..., R]], Callable[..., R]]:
+        """
+        Retrieves a workflow run decorator for a given executor.
+
+        :param executor_name: Unique name of the executor.
+        :return: The decorator function.
+        """
+        return self._workflow_run_decorators.get(executor_name)
+
+
+def default_workflow_defn(cls: Type, *args, **kwargs) -> Type:
+    """Default no-op workflow definition decorator."""
+    return cls
+
+
+def default_workflow_run(fn: Callable[..., R]) -> Callable[..., R]:
+    """Default no-op workflow run decorator."""
+
+    def wrapper(*args, **kwargs):
+        return fn(*args, **kwargs)
+
+    return wrapper
+
+
+def register_asyncio_decorators(decorator_registry: DecoratorRegistry):
+    """Registers default asyncio decorators."""
+    executor_name = "asyncio"
+    decorator_registry.register_workflow_defn_decorator(
+        executor_name, default_workflow_defn
+    )
+    decorator_registry.register_workflow_run_decorator(
+        executor_name, default_workflow_run
+    )
+
+
+def register_temporal_decorators(decorator_registry: DecoratorRegistry):
+    """Registers Temporal decorators if Temporal SDK is available."""
+    try:
+        import temporalio.workflow as temporal_workflow
+
+        TEMPORAL_AVAILABLE = True
+    except ImportError:
+        TEMPORAL_AVAILABLE = False
+
+    if not TEMPORAL_AVAILABLE:
+        return
+
+    executor_name = "temporal"
+    decorator_registry.register_workflow_defn_decorator(
+        executor_name, temporal_workflow.defn
+    )
+    decorator_registry.register_workflow_run_decorator(
+        executor_name, temporal_workflow.run
+    )

mcp_agent/executor/executor.py

@@ -0,0 +1,293 @@
+import asyncio
+import functools
+from abc import ABC, abstractmethod
+from contextlib import asynccontextmanager
+from datetime import timedelta
+from typing import (
+    Any,
+    AsyncIterator,
+    Callable,
+    Coroutine,
+    Dict,
+    List,
+    Optional,
+    Type,
+    TypeVar,
+    TYPE_CHECKING,
+)
+
+from pydantic import BaseModel, ConfigDict
+
+from mcp_agent.context_dependent import ContextDependent
+from mcp_agent.executor.workflow_signal import (
+    AsyncioSignalHandler,
+    Signal,
+    SignalHandler,
+    SignalValueT,
+)
+from mcp_agent.logging.logger import get_logger
+
+if TYPE_CHECKING:
+    from mcp_agent.context import Context
+
+logger = get_logger(__name__)
+
+# Type variable for the return type of tasks
+R = TypeVar("R")
+
+
+class ExecutorConfig(BaseModel):
+    """Configuration for executors."""
+
+    max_concurrent_activities: int | None = None  # Unbounded by default
+    timeout_seconds: timedelta | None = None  # No timeout by default
+    retry_policy: Dict[str, Any] | None = None
+
+    model_config = ConfigDict(extra="allow", arbitrary_types_allowed=True)
+
+
+class Executor(ABC, ContextDependent):
+    """Abstract base class for different execution backends"""
+
+    def __init__(
+        self,
+        engine: str,
+        config: ExecutorConfig | None = None,
+        signal_bus: SignalHandler = None,
+        context: Optional["Context"] = None,
+        **kwargs,
+    ):
+        super().__init__(context=context, **kwargs)
+        self.execution_engine = engine
+
+        if config:
+            self.config = config
+        else:
+            # TODO: saqadri - executor config should be loaded from settings
+            # ctx = get_current_context()
+            self.config = ExecutorConfig()
+
+        self.signal_bus = signal_bus
+
+    @asynccontextmanager
+    async def execution_context(self):
+        """Context manager for execution setup/teardown."""
+        try:
+            yield
+        except Exception as e:
+            # TODO: saqadri - add logging or other error handling here
+            raise e
+
+    @abstractmethod
+    async def execute(
+        self,
+        *tasks: Callable[..., R] | Coroutine[Any, Any, R],
+        **kwargs: Any,
+    ) -> List[R | BaseException]:
+        """Execute a list of tasks and return their results"""
+
+    @abstractmethod
+    async def execute_streaming(
+        self,
+        *tasks: List[Callable[..., R] | Coroutine[Any, Any, R]],
+        **kwargs: Any,
+    ) -> AsyncIterator[R | BaseException]:
+        """Execute tasks and yield results as they complete"""
+
+    async def map(
+        self,
+        func: Callable[..., R],
+        inputs: List[Any],
+        **kwargs: Any,
+    ) -> List[R | BaseException]:
+        """
+        Run `func(item)` for each item in `inputs` with concurrency limit.
+        """
+        results: List[R, BaseException] = []
+
+        async def run(item):
+            if self.config.max_concurrent_activities:
+                semaphore = asyncio.Semaphore(self.config.max_concurrent_activities)
+                async with semaphore:
+                    return await self.execute(functools.partial(func, item), **kwargs)
+            else:
+                return await self.execute(functools.partial(func, item), **kwargs)
+
+        coros = [run(x) for x in inputs]
+        # gather all, each returns a single-element list
+        list_of_lists = await asyncio.gather(*coros, return_exceptions=True)
+
+        # Flatten results
+        for entry in list_of_lists:
+            if isinstance(entry, list):
+                results.extend(entry)
+            else:
+                # Means we got an exception at the gather level
+                results.append(entry)
+
+        return results
+
+    async def validate_task(
+        self, task: Callable[..., R] | Coroutine[Any, Any, R]
+    ) -> None:
+        """Validate a task before execution."""
+        if not (asyncio.iscoroutine(task) or asyncio.iscoroutinefunction(task)):
+            raise TypeError(f"Task must be async: {task}")
+
+    async def signal(
+        self,
+        signal_name: str,
+        payload: SignalValueT = None,
+        signal_description: str | None = None,
+    ) -> None:
+        """
+        Emit a signal.
+        """
+        signal = Signal[SignalValueT](
+            name=signal_name, payload=payload, description=signal_description
+        )
+        await self.signal_bus.signal(signal)
+
+    async def wait_for_signal(
+        self,
+        signal_name: str,
+        request_id: str | None = None,
+        workflow_id: str | None = None,
+        signal_description: str | None = None,
+        timeout_seconds: int | None = None,
+        signal_type: Type[SignalValueT] = str,
+    ) -> SignalValueT:
+        """
+        Wait until a signal with signal_name is emitted (or timeout).
+        Return the signal's payload when triggered, or raise on timeout.
+        """
+
+        # Notify any callbacks that the workflow is about to be paused waiting for a signal
+        if self.context.signal_notification:
+            self.context.signal_notification(
+                signal_name=signal_name,
+                request_id=request_id,
+                workflow_id=workflow_id,
+                metadata={
+                    "description": signal_description,
+                    "timeout_seconds": timeout_seconds,
+                    "signal_type": signal_type,
+                },
+            )
+
+        signal = Signal[signal_type](
+            name=signal_name, description=signal_description, workflow_id=workflow_id
+        )
+        return await self.signal_bus.wait_for_signal(signal)
+
+
+class AsyncioExecutor(Executor):
+    """Default executor using asyncio"""
+
+    def __init__(
+        self,
+        config: ExecutorConfig | None = None,
+        signal_bus: SignalHandler | None = None,
+    ):
+        signal_bus = signal_bus or AsyncioSignalHandler()
+        super().__init__(engine="asyncio", config=config, signal_bus=signal_bus)
+
+        self._activity_semaphore: asyncio.Semaphore | None = None
+        if self.config.max_concurrent_activities is not None:
+            self._activity_semaphore = asyncio.Semaphore(
+                self.config.max_concurrent_activities
+            )
+
+    async def _execute_task(
+        self, task: Callable[..., R] | Coroutine[Any, Any, R], **kwargs: Any
+    ) -> R | BaseException:
+        async def run_task(task: Callable[..., R] | Coroutine[Any, Any, R]) -> R:
+            try:
+                if asyncio.iscoroutine(task):
+                    return await task
+                elif asyncio.iscoroutinefunction(task):
+                    return await task(**kwargs)
+                else:
+                    # Execute the callable and await if it returns a coroutine
+                    loop = asyncio.get_running_loop()
+
+                    # If kwargs are provided, wrap the function with partial
+                    if kwargs:
+                        wrapped_task = functools.partial(task, **kwargs)
+                        result = await loop.run_in_executor(None, wrapped_task)
+                    else:
+                        result = await loop.run_in_executor(None, task)
+
+                    # Handle case where the sync function returns a coroutine
+                    if asyncio.iscoroutine(result):
+                        return await result
+
+                    return result
+            except Exception as e:
+                # TODO: saqadri - adding logging or other error handling here
+                return e
+
+        if self._activity_semaphore:
+            async with self._activity_semaphore:
+                return await run_task(task)
+        else:
+            return await run_task(task)
+
+    async def execute(
+        self,
+        *tasks: Callable[..., R] | Coroutine[Any, Any, R],
+        **kwargs: Any,
+    ) -> List[R | BaseException]:
+        # TODO: saqadri - validate if async with self.execution_context() is needed here
+        async with self.execution_context():
+            return await asyncio.gather(
+                *(self._execute_task(task, **kwargs) for task in tasks),
+                return_exceptions=True,
+            )
+
+    async def execute_streaming(
+        self,
+        *tasks: List[Callable[..., R] | Coroutine[Any, Any, R]],
+        **kwargs: Any,
+    ) -> AsyncIterator[R | BaseException]:
+        # TODO: saqadri - validate if async with self.execution_context() is needed here
+        async with self.execution_context():
+            # Create futures for all tasks
+            futures = [
+                asyncio.create_task(self._execute_task(task, **kwargs))
+                for task in tasks
+            ]
+            pending = set(futures)
+
+            while pending:
+                done, pending = await asyncio.wait(
+                    pending, return_when=asyncio.FIRST_COMPLETED
+                )
+                for future in done:
+                    yield await future
+
+    async def signal(
+        self,
+        signal_name: str,
+        payload: SignalValueT = None,
+        signal_description: str | None = None,
+    ) -> None:
+        await super().signal(signal_name, payload, signal_description)
+
+    async def wait_for_signal(
+        self,
+        signal_name: str,
+        request_id: str | None = None,
+        workflow_id: str | None = None,
+        signal_description: str | None = None,
+        timeout_seconds: int | None = None,
+        signal_type: Type[SignalValueT] = str,
+    ) -> SignalValueT:
+        return await super().wait_for_signal(
+            signal_name,
+            request_id,
+            workflow_id,
+            signal_description,
+            timeout_seconds,
+            signal_type,
+        )

mcp_agent/executor/task_registry.py

@@ -0,0 +1,34 @@
+"""
+Keep track of all activities/tasks that the executor needs to run.
+This is used by the workflow engine to dynamically orchestrate a workflow graph.
+The user just writes standard functions annotated with @workflow_task, but behind the scenes a workflow graph is built.
+"""
+
+from typing import Any, Callable, Dict, List
+
+
+class ActivityRegistry:
+    """Centralized task/activity management with validation and metadata."""
+
+    def __init__(self):
+        self._activities: Dict[str, Callable] = {}
+        self._metadata: Dict[str, Dict[str, Any]] = {}
+
+    def register(
+        self, name: str, func: Callable, metadata: Dict[str, Any] | None = None
+    ):
+        if name in self._activities:
+            raise ValueError(f"Activity '{name}' is already registered.")
+        self._activities[name] = func
+        self._metadata[name] = metadata or {}
+
+    def get_activity(self, name: str) -> Callable:
+        if name not in self._activities:
+            raise KeyError(f"Activity '{name}' not found.")
+        return self._activities[name]
+
+    def get_metadata(self, name: str) -> Dict[str, Any]:
+        return self._metadata.get(name, {})
+
+    def list_activities(self) -> List[str]:
+        return list(self._activities.keys())