universal-mcp-agents 0.1.7__py3-none-any.whl → 0.1.9__py3-none-any.whl

universal_mcp/agents/codeact/prompts.py

@@ -0,0 +1,92 @@
+import inspect
+import re
+from typing import Optional, Sequence
+
+from langchain_core.tools import StructuredTool, tool as create_tool
+
+
+def make_safe_function_name(name: str) -> str:
+    """Convert a tool name to a valid Python function name."""
+    # Replace non-alphanumeric characters with underscores
+    safe_name = re.sub(r"[^a-zA-Z0-9_]", "_", name)
+    # Ensure the name doesn't start with a digit
+    if safe_name and safe_name[0].isdigit():
+        safe_name = f"tool_{safe_name}"
+    # Handle empty name edge case
+    if not safe_name:
+        safe_name = "unnamed_tool"
+    return safe_name
+
+
+def create_default_prompt(
+    tools: Sequence[StructuredTool],
+    base_prompt: Optional[str] = None,
+):
+    """Create default prompt for the CodeAct agent."""
+    prompt = f"{base_prompt}\n\n" if base_prompt else ""
+    prompt += """You will be given a task to perform. You should output either
+- a Python code snippet that provides the solution to the task, or a step towards the solution. Any output you want to extract from the code should be printed to the console. Code should be output in a fenced code block.
+- text to be shown directly to the user, if you want to ask for more information or provide the final answer.
+
+In addition to the Python Standard Library, you can use the following functions:"""
+
+    for tool in tools:
+        # Use coroutine if it exists, otherwise use func
+        tool_callable = (
+            tool.coroutine
+            if hasattr(tool, "coroutine") and tool.coroutine is not None
+            else tool.func
+        )
+        # Create a safe function name
+        safe_name = make_safe_function_name(tool.name)
+        # Determine if it's an async function
+        is_async = inspect.iscoroutinefunction(tool_callable)
+        # Add appropriate function definition
+        prompt += f'''\n{"async " if is_async else ""}def {safe_name}{str(inspect.signature(tool_callable))}:
+    """{tool.description}"""
+    ... 
+'''
+
+    prompt += """
+
+Variables defined at the top level of previous code snippets can be referenced in your code.
+
+Always use print() statements to explore data structures and function outputs. Simply returning values will not display them back to you for inspection. For example, use print(result) instead of just 'result'.
+
+As you don't know the output schema of the additional Python functions you have access to, start from exploring their contents before building a final solution.
+
+IMPORTANT CODING STRATEGY:
+1. Only write code up to the point where you make an API call/tool usage with an output
+2. Print the type/shape and a sample entry of this output, and using that knowledge proceed to write the further code
+
+This means:
+- Write code that makes the API call or tool usage
+- Print the result with type information: print(f"Type: {type(result)}")
+- Print the shape/structure: print(f"Shape/Keys: {result.keys() if isinstance(result, dict) else len(result) if isinstance(result, (list, tuple)) else 'N/A'}")
+- Print a sample entry: print(f"Sample: {result[0] if isinstance(result, (list, tuple)) and len(result) > 0 else result}")
+- Then, based on this knowledge, write the code to process/use this data
+
+Reminder: use Python code snippets to call tools"""
+    return prompt
+
+
+REFLECTION_PROMPT = """
+Review the assistant's latest code for as per the quality rules:
+
+<conversation_history>
+{conversation_history}
+</conversation_history>
+
+If you find ANY of these issues, describe the problem briefly and clearly.
+If NO issues are found, respond with EXACTLY: "NONE"
+"""
+
+RETRY_PROMPT = """
+I need you to completely regenerate your previous response based on this feedback:
+
+'''
+{reflection_result}
+'''
+
+DO NOT reference the feedback directly. Instead, provide a completely new response that addresses the issues.
+"""

universal_mcp/agents/codeact/sandbox.py

@@ -1,27 +1,48 @@
+import asyncio
 import builtins
 import contextlib
 import io
 from typing import Any
 
 
-def eval_unsafe(code: str, _locals: dict[str, Any]) -> tuple[str, dict[str, Any]]:
-    # Store original keys before execution
-    original_keys = set(_locals.keys())
+async def eval_unsafe(code: str, _locals: dict[str, Any]) -> tuple[str, dict[str, Any]]:
+    """
+    Execute code in a non-blocking way and return the output and changed variables.
+    """
     result = f"Executing code...\n{code}\n\nOutput:\n"
     result += "=" * 50 + "\n"
-    try:
-        with contextlib.redirect_stdout(io.StringIO()) as f:
-            # Execute the code in the provided locals context
-            # Using exec to allow dynamic code execution
-            # This is a simplified version; in production, consider security implications
-            exec(code, builtins.__dict__, _locals)
-        result += f.getvalue()
-        if not result:
-            result = "<code ran, no output printed to stdout>"
-    except Exception as e:
-        result += f"Error during execution: {repr(e)}"
-
-    # Determine new variables created during execution
-    new_keys = set(_locals.keys()) - original_keys
-    new_vars = {key: _locals[key] for key in new_keys}
-    return result, new_vars
+
+    # Create a combined globals/locals environment that includes builtins
+    # and the provided context. This allows nested functions to access tools.
+    execution_env = {**builtins.__dict__, **_locals}
+
+    def sync_eval_in_thread():
+        """Synchronously execute code and capture output."""
+        try:
+            with contextlib.redirect_stdout(io.StringIO()) as f:
+                exec(code, execution_env)
+            output = f.getvalue()
+            if not output:
+                output = "<code ran, no output printed to stdout>"
+            return output
+        except Exception as e:
+            return f"Error during execution: {repr(e)}"
+
+    # Run the synchronous exec in a separate thread to avoid blocking the event loop.
+    output = await asyncio.to_thread(sync_eval_in_thread)
+    result += output
+
+    # Identify all variables that are not part of the original builtins
+    # and were not in the initial _locals, or were changed.
+    changed_vars = {}
+    builtin_keys = set(builtins.__dict__.keys())
+
+    for key, value in execution_env.items():
+        if key in builtin_keys:
+            continue  # Skip builtins
+
+        # Check if the key is new or if the value has changed
+        if key not in _locals or _locals[key] is not value:
+            changed_vars[key] = value
+
+    return result, changed_vars

universal_mcp/agents/codeact/state.py

@@ -0,0 +1,12 @@
+from typing import Any, Optional
+
+from langgraph.graph import MessagesState
+
+
+class CodeActState(MessagesState):
+    """State for CodeAct agent."""
+
+    script: Optional[str]
+    """The Python code script to be executed."""
+    context: dict[str, Any]
+    """Dictionary containing the execution context with available tools and variables."""

universal_mcp/agents/llm.py

@@ -8,7 +8,7 @@ from langchain_openai import AzureChatOpenAI
 
 @lru_cache(maxsize=8)
 def load_chat_model(
-    fully_specified_name: str, temperature: float = 1.0, tags: list[str] | None = None, thinking: bool = False
+    fully_specified_name: str, temperature: float = 1.0, tags: list[str] | None = None, thinking: bool = True
 ) -> BaseChatModel:
     """Load a chat model from a fully specified name.
     Args:

universal_mcp/agents/planner/graph.py

@@ -19,7 +19,7 @@ def build_graph(llm, registry, instructions, model, executor_agent_cls):
         logger.info(f"Running tool finder for task: {task}")
         tool_finder_graph = build_tool_node_graph(llm, registry)
         tool_finder_state = await tool_finder_graph.ainvoke(
-            {"task": task, "messages": state["messages"]}
+            {"original_task": task, "messages": state["messages"]}
         )
 
         if not tool_finder_state.get("apps_required"):

universal_mcp/agents/shared/prompts.py

@@ -0,0 +1,132 @@
+TASK_DECOMPOSITION_PROMPT = """
+You are an expert planner. Your goal is to consolidate a complex user request into the minimum number of high-level sub-tasks required. Each sub-task should correspond to a major, consolidated action within a single target application.
+
+**CORE PRINCIPLES:**
+1.  **App-Centric Grouping:** Group all related actions for a single application into ONE sub-task.
+2.  **Focus on Data Handoffs:** A good decomposition often involves one sub-task to *retrieve* information and a subsequent sub-task to *use* that information.
+3.  **Assume Internal Capabilities:** Do NOT create sub-tasks for abstract cognitive work like 'summarize' or 'analyze'.
+4.  **Simplify Single Actions:** If the user's task is already a single, simple action, the output should be a single sub-task that concisely describes that action. Do not make it identical to the user's input.
+5.  **General purpose sub tasks:** You also need to realise that these subtasks are going to be used to search for tools and apps. And the names and description of these tools and apps are going to be general in nature so the sub tasks should not be too specific. The task which you will get may be specific in nature but the sub taks must be general. 
+**--- EXAMPLES ---**
+
+**EXAMPLE 1:**
+- **User Task:** "Create a Google Doc summarizing the last 5 merged pull requests in my GitHub repo universal-mcp/universal-mcp."
+- **CORRECT DECOMPOSITION:**
+    - "Fetch the last 5 merged pull requests from the GitHub repository 'universal-mcp/universal-mcp'."
+    - "Create a new Google Doc containing the summary of the pull requests."
+
+**EXAMPLE 2:**
+- **User Task:** "Find the best restaurants in Goa using perplexity web search."
+- **CORRECT DECOMPOSITION:**
+    - "Perform a web search using Perplexity to find the best restaurants in Goa."
+
+**--- YOUR TASK ---**
+
+**USER TASK:**
+"{task}"
+
+**YOUR DECOMPOSITION (as a list of strings):**
+"""
+
+
+APP_SEARCH_QUERY_PROMPT = """
+You are an expert at selecting an application to perform a specific sub-task. Your goal is to generate a concise query for an app search engine.
+
+Analyze the current sub-task in the context of the original user goal and the ENTIRE PLAN so far.
+
+**CORE INSTRUCTION:** If any application already used in the plan is capable of performing the current sub-task, your query MUST BE the name of that application to ensure continuity and efficiency. Otherwise, generate a concise query for the category of application needed.
+
+**--- EXAMPLES ---**
+
+**EXAMPLE 1: Reusing an app from two steps ago**
+- **Original User Task:** "Find my latest order confirmation in Gmail, search for reviews of the main product on perplexity, and then send an email to ankit@agentr.dev telling about the reviews"
+- **Plan So Far:**
+  - The sub-task 'Find order confirmation in Gmail' was assigned to app 'google_mail'.
+  - The sub-task 'Search for product reviews on perplexity' was assigned to app 'perplexity'.
+- **Current Sub-task:** "send an email to ankit@agentr.dev"
+- **CORRECT QUERY:** "google_mail"
+
+**EXAMPLE 2: First Step (No previous context)**
+- **Original User Task:** "Find the best restaurants in Goa."
+- **Plan So Far:** None. This is the first step.
+- **Current Sub-task:** "Perform a web search to find the best restaurants in Goa."
+- **CORRECT QUERY:** "web search"
+
+**--- YOUR TASK ---**
+
+**Original User Task:**
+"{original_task}"
+
+**Plan So Far:**
+{plan_context}
+
+**Current Sub-task:**
+"{sub_task}"
+
+**YOUR CONCISE APP SEARCH QUERY:**
+"""
+
+
+TOOL_SEARCH_QUERY_PROMPT = """
+You are an expert at summarizing the core *action* of a sub-task into a concise query for finding a tool. This query should ignore any application names.
+
+**INSTRUCTIONS:**
+1.  Focus only on the verb or action being performed in the sub-task.
+2.  Include key entities related to the action.
+3.  Do NOT include the names of applications (e.g., "Perplexity", "Gmail").
+4.  You also need to realise that this query is going to be used to search for tools in a particular app. And the names and description of these tools are going to be general in nature so the query should not be too specific. The sub task which you will get may be specific in nature but the query must be general.
+
+**EXAMPLES:**
+- **Sub-task:** "Perform a web search using Perplexity to find the best restaurants in Goa."
+- **Query:** "web search for restaurants"
+
+- **Sub-task:** "Fetch all marketing emails received from Gmail in the last 7 days."
+- **Query:** "get emails by date"
+
+- **Sub-task:** "Create a new Google Doc and append a summary."
+- **Query:** "create document, append text"
+
+**SUB-TASK:**
+"{sub_task}"
+
+**YOUR CONCISE TOOL SEARCH QUERY:**
+"""
+
+REVISE_DECOMPOSITION_PROMPT = """
+You are an expert planner who revises plans that have failed. Your previous attempt to break down a task resulted in a sub-task that could not be matched with any available tools.
+
+**INSTRUCTIONS:**
+1.  Analyze the original user task and the failed sub-task.
+2.  Generate a NEW, alternative decomposition of the original task.
+3.  This new plan should try to achieve the same overall goal but with different, perhaps broader or more combined, sub-tasks to increase the chance of finding a suitable tool.
+
+**ORIGINAL USER TASK:**
+"{task}"
+
+**FAILED SUB-TASK FROM PREVIOUS PLAN:**
+"{failed_sub_task}"
+
+**YOUR NEW, REVISED DECOMPOSITION (as a list of strings):**
+"""
+
+
+TOOL_SELECTION_PROMPT = """
+You are an AI assistant that selects the most appropriate tool(s) from a list to accomplish a specific sub-task.
+
+**INSTRUCTIONS:**
+1.  Carefully review the sub-task to understand the required action.
+2.  Examine the list of available tools and their descriptions.
+3.  Select the best tool ID that matches the sub-task. You are encouraged to select multiple tools if there are multiple tools with similar capabilties 
+or names. It is always good to have more tools than having insufficent tools.
+4.  If no tool is a good fit, return an empty list.
+5.  Only return the tool IDs.
+6. You should understand that the sub task maybe specific in nature but the tools are made to be general purpose and therefore the tool_candidates you will get will be very general purpose but that should not stop you from selecting the tools as these tools will be given to a very smart agent who will be able to use these tools for the specific sub-taks
+
+**SUB-TASK:**
+"{sub_task}"
+
+**AVAILABLE TOOLS:**
+{tool_candidates}
+
+**YOUR SELECTED TOOL ID(s):**
+"""