decodingtrust-agent-sdk 0.1.0__py3-none-any.whl

agent/pocketflow/src/async_helper.py

@@ -0,0 +1,92 @@
+import asyncio
+import threading
+from typing import Any, Coroutine, TypeVar
+
+T = TypeVar("T")
+
+
+class AsyncHelper:
+    """
+    Helper class to run async operations in a sync context.
+
+    This is needed because PocketFlow nodes are synchronous, but MCP client
+    operations are asynchronous. We run async operations in a separate thread
+    with its own event loop to avoid "event loop already running" errors.
+    """
+
+    def __init__(self):
+        """Initialize the async helper."""
+        self._loop = None
+        self._thread = None
+        self._started = False
+
+    def start(self):
+        """Start the background event loop in a separate thread."""
+        if self._started:
+            return
+
+        def run_loop(loop):
+            """Run the event loop in the thread."""
+            asyncio.set_event_loop(loop)
+            loop.run_forever()
+
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(target=run_loop, args=(self._loop,), daemon=True)
+        self._thread.start()
+        self._started = True
+
+    def stop(self):
+        """Stop the background event loop."""
+        if not self._started:
+            return
+
+        if self._loop:
+            self._loop.call_soon_threadsafe(self._loop.stop)
+            self._thread.join(timeout=5.0)
+            self._loop.close()
+
+        self._loop = None
+        self._thread = None
+        self._started = False
+
+    def run_async(self, coro: Coroutine[Any, Any, T], timeout: float = 300.0) -> T:
+        """
+        Run an async coroutine and return its result synchronously.
+
+        Args:
+            coro: The coroutine to run
+            timeout: Timeout in seconds (default: 300s / 5 minutes)
+
+        Returns:
+            The result of the coroutine
+
+        Raises:
+            RuntimeError: If the helper is not started or loop is not running
+            TimeoutError: If the coroutine times out
+            concurrent.futures.CancelledError: If the future is cancelled
+        """
+        if not self._started:
+            raise RuntimeError("AsyncHelper not started. Call start() first.")
+
+        # Check if the loop and thread are still alive
+        if self._loop is None or self._loop.is_closed():
+            raise RuntimeError("AsyncHelper event loop is closed.")
+        if self._thread is None or not self._thread.is_alive():
+            raise RuntimeError("AsyncHelper thread is not running.")
+
+        future = asyncio.run_coroutine_threadsafe(coro, self._loop)
+        try:
+            return future.result(timeout=timeout)
+        except TimeoutError:
+            future.cancel()
+            raise TimeoutError(f"Async operation timed out after {timeout}s")
+
+    def __enter__(self):
+        """Context manager entry."""
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.stop()
+        return False

agent/pocketflow/src/mcp_react_agent.py

@@ -0,0 +1,279 @@
+import asyncio
+from typing import Dict, Any, List, Optional, Tuple
+from pocketflow import Flow
+from .nodes import DecideActionNode, ExecuteToolNode, FinalAnswerNode
+from .async_helper import AsyncHelper
+
+
+class MCPReactAgent:
+    """
+    A ReAct (Reasoning and Acting) agent that uses MCP tools through FastMCP.
+
+    This agent follows the ReAct pattern:
+    1. Think: Reason about the current state and decide what to do
+    2. Act: Execute a tool through MCP
+    3. Observe: Process the tool's result
+    4. Repeat until the task is complete
+
+    The agent is built using PocketFlow for workflow orchestration and
+    FastMCP for MCP server communication.
+
+    Supports multiple MCP servers - tools from all servers are combined.
+    """
+
+    def __init__(
+        self,
+        system_prompt: str,
+        mcp_server_url: Optional[str] = None,
+        mcp_server_urls: Optional[List[str]] = None,
+        model: Optional[str] = None,
+        max_iterations: int = 50,
+        timeout: float = 30.0,
+    ):
+        """
+        Initialize the MCP ReAct Agent.
+
+        Args:
+            system_prompt: System prompt that defines the agent's role and behavior
+            mcp_server_url: URL of a single MCP server (for backward compatibility)
+            mcp_server_urls: List of MCP server URLs (preferred for multiple servers)
+            model: Optional LLM model name to use
+            max_iterations: Maximum number of reasoning iterations
+            timeout: Timeout for MCP operations in seconds
+        """
+        self.system_prompt = system_prompt
+
+        # Support both single URL (backward compat) and multiple URLs
+        if mcp_server_urls:
+            self.mcp_server_urls = mcp_server_urls
+        elif mcp_server_url:
+            self.mcp_server_urls = [mcp_server_url]
+        else:
+            self.mcp_server_urls = []
+
+        # Keep single URL for backward compatibility
+        self.mcp_server_url = self.mcp_server_urls[0] if self.mcp_server_urls else None
+
+        self.model = model
+        self.max_iterations = max_iterations
+        self.timeout = timeout
+
+        # MCP clients (will be initialized when needed) - one per server
+        self._mcp_clients: Dict[str, Any] = {}  # url -> client
+        self._tool_to_client: Dict[str, Any] = {}  # tool_name -> client (for routing)
+
+        # Build the ReAct flow
+        self._flow = self._build_flow()
+
+    def _build_flow(self) -> Flow:
+        """Build the ReAct workflow using PocketFlow."""
+        # Create nodes
+        decide_node = DecideActionNode()
+        execute_tool_node = ExecuteToolNode()
+        final_answer_node = FinalAnswerNode()
+
+        # Connect nodes based on actions
+        # From decide_node:
+        #   - "use_tool" -> execute_tool_node
+        #   - "answer" -> final_answer_node
+        #   - "retry" -> back to decide_node (for parse error recovery)
+        decide_node - "use_tool" >> execute_tool_node
+        decide_node - "answer" >> final_answer_node
+        decide_node - "retry" >> decide_node
+
+        # From execute_tool_node:
+        #   - "decide" -> back to decide_node (for next iteration)
+        execute_tool_node - "decide" >> decide_node
+
+        # final_answer_node doesn't connect to anything (ends the flow)
+
+        # Create and return the flow
+        return Flow(start=decide_node)
+
+    async def _initialize_mcp_client(self):
+        """Initialize MCP client connections for all configured servers."""
+        from fastmcp import Client
+
+        for url in self.mcp_server_urls:
+            try:
+                # Create client for this server
+                client = Client(url, timeout=self.timeout)
+
+                # Connect to the server
+                await client.__aenter__()
+
+                # Store the client
+                self._mcp_clients[url] = client
+                print(f"[MCP] Connected to server: {url}")
+
+            except Exception as e:
+                print(f"[MCP] Warning: Failed to connect to {url}: {e}")
+
+        # For backward compatibility, set _mcp_client to first client
+        if self._mcp_clients:
+            first_url = self.mcp_server_urls[0]
+            self._mcp_client = self._mcp_clients.get(first_url)
+
+        return self._mcp_clients
+
+    async def _close_mcp_client(self):
+        """Close all MCP client connections."""
+        for url, client in self._mcp_clients.items():
+            try:
+                await client.__aexit__(None, None, None)
+                print(f"[MCP] Disconnected from server: {url}")
+            except Exception as e:
+                print(f"[MCP] Warning: Error closing connection to {url}: {e}")
+
+        self._mcp_clients = {}
+        self._mcp_client = None
+        self._tool_to_client = {}
+
+    async def _get_available_tools(self) -> List[Dict[str, Any]]:
+        """Get the list of available tools from all MCP servers."""
+        all_tools = []
+
+        for url, client in self._mcp_clients.items():
+            try:
+                tools_response = await client.list_tools()
+
+                # Convert to our format and track which client owns each tool
+                for tool in tools_response:
+                    tool_name = tool.name
+                    # Store mapping from tool name to client for routing
+                    self._tool_to_client[tool_name] = client
+
+                    all_tools.append({
+                        "name": tool_name,
+                        "description": tool.description or "",
+                        "inputSchema": tool.inputSchema or {},
+                        "_mcp_server": url,  # Track source server (internal use)
+                    })
+
+                print(f"[MCP] Loaded {len(tools_response)} tools from {url}")
+
+            except Exception as e:
+                print(f"Warning: Failed to get tools from MCP server {url}: {e}")
+
+        return all_tools
+
+    def get_client_for_tool(self, tool_name: str) -> Optional[Any]:
+        """Get the MCP client that provides a specific tool."""
+        return self._tool_to_client.get(tool_name)
+
+
+
+    async def run_async(
+        self, user_query: str
+    ) -> Tuple[str, List[Dict[str, Any]]]:
+        """
+        Run the agent asynchronously with the given query.
+
+        Args:
+            user_query: The user's input query/task
+
+        Returns:
+            A tuple of (final_answer, trajectory)
+            - final_answer: The agent's final response
+            - trajectory: List of all reasoning steps, actions, and observations
+        """
+        # Initialize MCP client
+        await self._initialize_mcp_client()
+
+        # Create and start async helper
+        async_helper = AsyncHelper()
+        async_helper.start()
+
+        try:
+            # Get available tools
+            available_tools = await self._get_available_tools()
+
+            # Initialize shared store
+            shared = {
+                "system_prompt": self.system_prompt,
+                "user_query": user_query,
+                "trajectory": [],
+                "message_history": [],  # Initialize message history for conversational context
+                "available_tools": available_tools,
+                "max_iterations": self.max_iterations,
+                "model": self.model,
+                "mcp_client": self._mcp_client,  # Pass the first MCP client (backward compat)
+                "mcp_clients": self._mcp_clients,  # Pass all MCP clients
+                "tool_to_client": self._tool_to_client,  # Pass tool->client routing map
+                "async_helper": async_helper,     # Pass the async helper
+                "final_answer": None,
+                "current_decision": None,
+            }
+
+            # Run the flow using standard PocketFlow Flow.run()
+            self._flow.run(shared)
+
+            # Extract results
+            final_answer = shared.get("final_answer", "No answer provided")
+            trajectory = shared.get("trajectory", [])
+
+            return final_answer, trajectory
+
+        finally:
+            # Clean up
+            async_helper.stop()
+            await self._close_mcp_client()
+
+    def run(
+        self, user_query: str
+    ) -> Tuple[str, List[Dict[str, Any]]]:
+        """
+        Run the agent synchronously with the given query.
+
+        Args:
+            user_query: The user's input query/task
+
+        Returns:
+            A tuple of (final_answer, trajectory)
+            - final_answer: The agent's final response
+            - trajectory: List of all reasoning steps, actions, and observations
+        """
+        # Run the async version
+        return asyncio.run(self.run_async(user_query))
+
+
+    def format_trajectory(self, trajectory: List[Dict[str, Any]]) -> str:
+        """
+        Format the trajectory into a human-readable string.
+
+        Args:
+            trajectory: The trajectory list from run()
+
+        Returns:
+            A formatted string representation of the trajectory
+        """
+        lines = []
+        thought_count = 0
+        action_count = 0
+
+        for entry in trajectory:
+            entry_type = entry.get("type", "unknown")
+
+            if entry_type == "thought":
+                thought_count += 1
+                lines.append(f"\n{'='*60}")
+                lines.append(f"ITERATION {thought_count}")
+                lines.append(f"{'='*60}")
+                lines.append(f"Thought: {entry.get('content', '')}")
+
+            elif entry_type == "action":
+                action_count += 1
+                tool_name = entry.get("tool_name", "unknown")
+                tool_args = entry.get("tool_arguments", {})
+                lines.append(f"Action: {tool_name}({tool_args})")
+
+            elif entry_type == "observation":
+                lines.append(f"Observation: {entry.get('content', '')}")
+
+            elif entry_type == "final_answer":
+                lines.append(f"\n{'='*60}")
+                lines.append("FINAL ANSWER")
+                lines.append(f"{'='*60}")
+                lines.append(entry.get("content", ""))
+
+        return "\n".join(lines)

agent/pocketflow/src/native_agent.py

@@ -0,0 +1,74 @@
+from dataclasses import dataclass, field
+from typing import Dict, List, Any, Optional
+from pocketflow import Flow
+from agent.pocketflow.src.agent import MCPServerInfo
+
+
+@dataclass
+class NativeMCPReactAgent:
+    """
+    User-customizable PocketFlow Native Agent.
+    """
+
+    # Required: MCP server configurations
+    mcp_servers: Dict[str, 'MCPServerInfo']
+    # Optional: Custom PocketFlow Flow (None = use default ReAct Flow)
+    flow: Optional['Flow'] = None
+
+    # Auto-computed attributes (populated in __post_init__)
+    tool_to_server: Dict[str, str] = field(default_factory=dict)
+    all_tools: List[Dict[str, Any]] = field(default_factory=list)
+
+    def __post_init__(self):
+        """
+        Build tool_to_server mapping and all_tools list from mcp_servers.
+
+        This method is automatically called after dataclass initialization.
+        It iterates through all MCP servers and their tools to build:
+        - tool_to_server: Maps each tool name to its server name
+        - all_tools: Flat list of all tools from all servers
+
+        Raises:
+            ValueError: If duplicate tool names are found across servers.
+        """
+        # Reset computed fields to ensure clean state
+        self.tool_to_server = {}
+        self.all_tools = []
+
+        for server_name, server_info in self.mcp_servers.items():
+            for tool in server_info.tools:
+                # Get tool name (support both dict and object-like access)
+                tool_name = tool.get("name") if isinstance(tool, dict) else getattr(tool, "name", None)
+
+                if not tool_name:
+                    continue
+
+                # Check for duplicate tool names
+                if tool_name in self.tool_to_server:
+                    existing_server = self.tool_to_server[tool_name]
+                    raise ValueError(
+                        f"Duplicate tool name '{tool_name}' found in servers "
+                        f"'{existing_server}' and '{server_name}'"
+                    )
+
+                # Map tool to server
+                self.tool_to_server[tool_name] = server_name
+
+                # Add to all_tools list
+                if isinstance(tool, dict):
+                    # Ensure server field is set
+                    tool_copy = dict(tool)
+                    tool_copy["server"] = server_name
+                    self.all_tools.append(tool_copy)
+                else:
+                    # Convert object to dict
+                    self.all_tools.append({
+                        "name": tool_name,
+                        "server": server_name,
+                        "description": getattr(tool, "description", ""),
+                        "inputSchema": getattr(tool, "inputSchema", {}),
+                    })
+
+    def has_custom_flow(self) -> bool:
+        """Check if a custom flow is defined."""
+        return self.flow is not None