universal-mcp-agents 0.1.14__py3-none-any.whl → 0.1.16__py3-none-any.whl

universal_mcp/agents/codeact0/prompts.py

@@ -1,33 +1,112 @@
-uneditable_prompt = """
-You are Wingmen, an AI Assistant created by AgentR. You are a creative, straight-forward and direct principal software engineer.
-
-Your job is to answer the user's question or perform the task they ask for.
-- Answer simple questions (which do not require you to write any code or access any external resources) directly. Note that any operation that involves using ONLY print functions should be answered directly.
-- For task requiring operations or access to external resources, you should achieve the task by executing Python code snippets.
-- You have access to `execute_ipython_cell` tool that allows you to execute Python code in an IPython notebook cell.
-- In writing or natural language processing tasks DO NOT answer directly. Instead use `execute_ipython_cell` tool with the AI functions provided to you for tasks like summarizing, text generation, classification, data extraction from text or unstructured data, etc.
-- The code you write will be executed in a sandbox environment, and you can use the output of previous executions in your code.
-- Read and understand the output of the previous code snippet and use it to answer the user's request. Note that the code output is NOT visible to the user, so after the task is complete, you have to give the output to the user in a markdown format.
-- If needed, feel free to ask for more information from the user (without using the execute_ipython_cell tool) to clarify the task.
-
-GUIDELINES for writing code:
-- Variables defined at the top level of previous code snippets can be referenced in your code.
-- External functions which return a dict or list[dict] are ambiguous. Therefore, you MUST explore the structure of the returned data using `smart_print()` statements before using it, printing keys and values. `smart_print` truncates long strings from data, preventing huge output logs.
-- When an operation involves running a fixed set of steps on a list of items, run one run correctly and then use a for loop to run the steps on each item in the list.
-- In a single code snippet, try to achieve as much as possible.
-- You can only import libraries that come pre-installed with Python.
-- You must wrap await calls in an async function and call it using `asyncio.run`.
-- For displaying final results to the user, you must present your output in markdown format, including image links, so that they are rendered and displayed to the user. The code output is NOT visible to the user.
-
-"""
 import inspect
 import re
 from collections.abc import Sequence
-from datetime import datetime
 
 from langchain_core.tools import StructuredTool
+
 from universal_mcp.agents.codeact0.utils import schema_to_signature
 
+uneditable_prompt = """
+You are **Wingmen**, an AI Assistant created by AgentR — a creative, straight-forward, and direct principal software engineer with access to tools.
+
+## Responsibilities
+
+- **Answer directly** if the task is simple (e.g. print, math, general knowledge).
+- For any task requiring logic, execution, or data handling, use `execute_ipython_cell`.
+- For writing or NLP tasks (summarizing, generating, extracting), always use AI functions via code — never respond directly.
+
+## Tool vs. Function: Required Separation
+
+You must clearly distinguish between tools (called via the tool calling API) and internal functions (used inside code blocks).
+
+### Tools — Must Be Called via Tool Calling API
+
+These must be called using **tool calling**, not from inside code blocks:
+
+- `execute_ipython_cell` — For running any Python code or logic.
+- `search_functions` — To discover available functions for a task.
+- `load_functions` — To load a specific function by full ID.
+
+**Do not attempt to call these inside `python` code.**
+Use tool calling syntax for these operations.
+
+### Functions — Must Be Used Inside Code Blocks
+
+All other functions, including LLM functions, must always be used within code executed by `execute_ipython_cell`. These include:
+
+- `smart_print()` — For inspecting unknown data structures before looping.
+- `asyncio.run()` — For wrapping and executing asynchronous logic. You must not use await outside an async function. And the async function must be called by `asyncio.run()`.
+- Any functions for applications loaded via `load_functions`.
+- Any logic, data handling, writing, NLP, generation, summarization, or extraction functionality of LLMs.
+
+These must be called **inside a Python code block**, and that block must be executed using `execute_ipython_cell`.
+
+## Tool/Function Usage Policy
+
+1. **Always Use Tools/Functions for Required Tasks**
+   Any searching, loading, or executing must be done using a tool/function call. Never answer manually if a tool/function is appropriate.
+
+2. **Use Existing Functions First**
+   Use existing functions if available. Otherwise, use `search_functions` with a concise query describing the task.
+
+3. **Load Only Relevant Tools**
+   When calling `load_functions`, include only relevant function IDs.
+   - Prefer connected applications over unconnected ones.
+   - If multiple functions match (i.e. if none are connected, or multiple are connected), ask the user to choose.
+   - After loading a tool, you do not need to import/declare it again. It can be called directly in further cells.
+
+4. **Follow First Turn Process Strictly**
+   On the **first turn**, do only **one** of the following:
+   - Handle directly (if trivial)
+   - Use a tool/function (`execute_ipython_cell`, `search_functions`, etc.)
+
+   **Do not extend the conversation on the first message.**
+
+## Coding Rules
+
+- Use `smart_print()` to inspect unknown structures, especially those received from function outputs, before looping or branching.
+- Validate logic with a single item before processing lists or large inputs.
+- Try to achieve as much as possible in a single code block.
+- Use only pre-installed Python libraries. Do import them once before using.
+- Outer level functions, variables, classes, and imports declared previously can be used in later cells.
+- For all functions, call using keyword arguments only. DO NOT use any positional arguments.
+
+### **Async Function Usage — Critical**
+
+When calling asynchronous functions:
+- You must define or use an **inner async function**.
+- Use `await` only **inside** that async function.
+- Run it using `asyncio.run(<function_name>())` **without** `await` at the outer level.
+
+**Wrong - Using `await` outside an async function**
+```
+result = await some_async_function()
+```
+**Wrong  - Attaching await before asyncio.run**.
+`await asyncio.run(main())`
+These will raise SyntaxError: 'await' outside async function
+The correct method is the following-
+```
+import asyncio
+async def some_async_function():
+    ...
+
+async def main():
+    result = await some_async_function()
+    print(result)
+
+asyncio.run(main())
+#or
+result = asyncio.run(some_async_function(arg1 = <arg1>))
+```
+## Output Formatting
+- All code results must be returned in **Markdown**.
+- The user cannot see raw output, so format results clearly:
+    - Use tables for structured data.
+    - Provide links for files or images.
+    - Be explicit in formatting to ensure readability.
+"""
+
 
 def make_safe_function_name(name: str) -> str:
     """Convert a tool name to a valid Python function name."""
@@ -119,24 +198,22 @@ def indent(text, prefix, predicate=None):
     return "".join(prefixed_lines)
 
 
-
 def create_default_prompt(
     tools: Sequence[StructuredTool],
-    additional_tools : Sequence[StructuredTool],
+    additional_tools: Sequence[StructuredTool],
     base_prompt: str | None = None,
 ):
-    system_prompt = uneditable_prompt.strip()  + (
-        "\n\nIn addition to the Python Standard Library, you can use the following external functions:"
-        "\n"
+    system_prompt = uneditable_prompt.strip() + (
+        "\n\nIn addition to the Python Standard Library, you can use the following external functions:\n"
     )
     tools_context = {}
     for tool in tools:
-        if hasattr(tool, "coroutine") and tool.coroutine is not None:
-            tool_callable = tool.coroutine
-            is_async = True
-        elif hasattr(tool, "func") and tool.func is not None:
+        if hasattr(tool, "func") and tool.func is not None:
             tool_callable = tool.func
             is_async = False
+        elif hasattr(tool, "coroutine") and tool.coroutine is not None:
+            tool_callable = tool.coroutine
+            is_async = True
         system_prompt += f'''{"async " if is_async else ""}{schema_to_signature(tool.args, tool.name)}:
     """{tool.description}"""
     ...
@@ -145,12 +222,12 @@ def create_default_prompt(
         tools_context[safe_name] = tool_callable
 
     for tool in additional_tools:
-        if hasattr(tool, "coroutine") and tool.coroutine is not None:
-            tool_callable = tool.coroutine
-            is_async = True
-        elif hasattr(tool, "func") and tool.func is not None:
+        if hasattr(tool, "func") and tool.func is not None:
             tool_callable = tool.func
             is_async = False
+        elif hasattr(tool, "coroutine") and tool.coroutine is not None:
+            tool_callable = tool.coroutine
+            is_async = True
         system_prompt += f'''{"async " if is_async else ""}def {tool.name} {str(inspect.signature(tool_callable))}:
     """{tool.description}"""
     ...
@@ -162,6 +239,3 @@ def create_default_prompt(
         system_prompt += f"Your goal is to perform the following task:\n\n{base_prompt}"
 
     return system_prompt, tools_context
-
-
-

universal_mcp/agents/codeact0/sandbox.py

@@ -14,55 +14,66 @@ from universal_mcp.agents.codeact0.utils import derive_context
 
 
 def eval_unsafe(
-    code: str, _locals: dict[str, Any], add_context: dict[str, Any]
+    code: str, _locals: dict[str, Any], add_context: dict[str, Any], timeout: int = 180
 ) -> tuple[str, dict[str, Any], dict[str, Any]]:
-    # print(_locals)
+    """
+    Execute code safely with a timeout.
+    - Returns (output_str, filtered_locals_dict, new_add_context)
+    - Errors or timeout are returned as output_str.
+    - Previous variables in _locals persist across calls.
+    """
+
     EXCLUDE_TYPES = (
-        types.ModuleType,  # modules
+        types.ModuleType,
         type(re.match("", "")),
-        type(threading.Lock()),  # instead of threading.Lock
-        type(threading.RLock()),  # reentrant lock
-        threading.Event,  # events
-        threading.Condition,  # condition vars
-        threading.Semaphore,  # semaphores
-        queue.Queue,  # thread-safe queues
-        socket.socket,  # network sockets
-        io.IOBase,  # file handles (and StringIO/BytesIO)
+        type(threading.Lock()),
+        type(threading.RLock()),
+        threading.Event,
+        threading.Condition,
+        threading.Semaphore,
+        queue.Queue,
+        socket.socket,
+        io.IOBase,
     )
-    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, _locals, _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)}"
-
-    # Return all variables in locals except __builtins__ and unpicklable objects (including tools)
+
+    result_container = {"output": "<no output>"}
+
+    def target():
+        try:
+            with contextlib.redirect_stdout(io.StringIO()) as f:
+                exec(code, _locals, _locals)
+            result_container["output"] = f.getvalue() or "<code ran, no output printed to stdout>"
+        except Exception as e:
+            result_container["output"] = "Error during execution: " + str(e)
+
+    thread = threading.Thread(target=target)
+    thread.start()
+    thread.join(timeout)
+
+    if thread.is_alive():
+        result_container["output"] = f"Code timeout: code execution exceeded {timeout} seconds."
+
+    # Filter locals for picklable/storable variables
     all_vars = {}
     for key, value in _locals.items():
         if key == "__builtins__":
             continue
-
-        # Skip coroutines, async generators, and coroutine functions
         if inspect.iscoroutine(value) or inspect.iscoroutinefunction(value):
             continue
         if inspect.isasyncgen(value) or inspect.isasyncgenfunction(value):
             continue
-
-        # Skip "obviously unpicklable" types
         if isinstance(value, EXCLUDE_TYPES):
             continue
-
-        # Keep if it's not a callable OR if it has no __name__ attribute
         if not callable(value) or not hasattr(value, "__name__"):
             all_vars[key] = value
 
-    new_add_context = derive_context(code, add_context)
-    return result, all_vars, new_add_context
+    # Safely derive context
+    try:
+        new_add_context = derive_context(code, add_context)
+    except Exception:
+        new_add_context = add_context
+
+    return result_container["output"], all_vars, new_add_context
 
 
 @tool(parse_docstring=True)

universal_mcp/agents/codeact0/state.py

@@ -1,12 +1,38 @@
-from typing import Any
+from typing import Annotated, Any
 
-from langgraph.graph import MessagesState
+from langgraph.prebuilt.chat_agent_executor import AgentState
 
 
-class CodeActState(MessagesState):
+def _enqueue(left: list, right: list) -> list:
+    """Treat left as a FIFO queue, append new items from right (preserve order),
+    keep items unique, and cap total size to 20 (drop oldest items)."""
+    max_size = 30
+    preferred_size = 20
+    if len(right) > preferred_size:
+        preferred_size = min(max_size, len(right))
+    queue = list(left or [])
+
+    for item in right[:preferred_size] or []:
+        if item in queue:
+            queue.remove(item)
+        queue.append(item)
+
+    if len(queue) > preferred_size:
+        queue = queue[-preferred_size:]
+
+    return queue
+
+
+class CodeActState(AgentState):
     """State for CodeAct agent."""
 
     context: dict[str, Any]
     """Dictionary containing the execution context with available tools and variables."""
     add_context: dict[str, Any]
     """Dictionary containing the additional context (functions, classes, imports) to be added to the execution context."""
+    playbook_mode: str | None
+    """State for the playbook agent."""
+    selected_tool_ids: Annotated[list[str], _enqueue]
+    """Queue for tools exported from registry"""
+    plan: str | None
+    """Plan for the playbook agent."""

universal_mcp/agents/codeact0/tools.py

@@ -0,0 +1,186 @@
+import asyncio
+from collections import defaultdict
+from typing import Any
+
+from langchain_core.tools import tool
+from universal_mcp.tools.registry import ToolRegistry
+from universal_mcp.types import ToolFormat
+
+MAX_LENGHT=100
+
+def enter_playbook_mode():
+    """Call this function to enter playbook mode. Playbook mode is when the user wants to store a repeated task as a script with some inputs for the future."""
+    return
+
+def exit_playbook_mode():
+    """Call this function to exit playbook mode. Playbook mode is when the user wants to store a repeated task as a script with some inputs for the future."""
+    return
+
+
+
+def create_meta_tools(tool_registry: ToolRegistry) -> dict[str, Any]:
+    """Create the meta tools for searching and loading tools"""
+
+    @tool
+    async def search_functions(queries: list[str]) -> str:
+        """Search for relevant functions given list of queries.
+        Each single query should be atomic (doable with a single function).
+        For tasks requiring multiple functions, add separate queries for each subtask"""
+        try:
+            # Fetch all connections
+            connections = await tool_registry.list_connected_apps()
+            connected_apps = {connection["app_id"] for connection in connections}
+
+            app_tools = defaultdict(set)
+            MAX_LENGTH = 20
+
+            # Process all queries concurrently
+            search_tasks = []
+            for query in queries:
+                search_tasks.append(_search_query_tools(query))
+
+            query_results = await asyncio.gather(*search_tasks)
+
+            # Aggregate results with limit per app and automatic deduplication
+            for tools_list in query_results:
+                for tool in tools_list:
+                    app = tool["id"].split("__")[0]
+                    tool_id = tool["id"]
+                    
+                    # Check if within limit and add to set (automatically deduplicates)
+                    if len(app_tools[app]) < MAX_LENGTH:
+                        cleaned_desc = tool["description"].split("Context:")[0].strip()
+                        app_tools[app].add(f"{tool_id}: {cleaned_desc}")
+
+            # Build result string efficiently
+            result_parts = []
+            for app, tools in app_tools.items():
+                app_status = "connected" if app in connected_apps else "NOT connected"
+                result_parts.append(f"Tools from {app} (status: {app_status} by user):")
+                # Convert set to sorted list for consistent output
+                for tool in sorted(tools):
+                    result_parts.append(f" - {tool}")
+                result_parts.append("")  # Empty line between apps
+
+            result_parts.append("Call load_functions to select the required functions only.")
+            return "\n".join(result_parts)
+
+        except Exception as e:
+            return f"Error: {e}"
+
+    async def _search_query_tools(query: str) -> list[dict]:
+        """Helper function to search apps and tools for a single query."""
+        # Start both searches concurrently
+        tools_search_task = tool_registry.search_tools(query, limit=10)
+        apps_search_task = tool_registry.search_apps(query, limit=4)
+
+        # Wait for both to complete
+        tools_from_general_search, apps_list = await asyncio.gather(tools_search_task, apps_search_task)
+
+        # Create tasks for searching tools from each app
+        app_tool_tasks = [tool_registry.search_tools(query, limit=5, app_id=app["id"]) for app in apps_list]
+
+        # Wait for all app-specific tool searches to complete
+        app_tools_results = await asyncio.gather(*app_tool_tasks)
+
+        # Combine all results
+        tools_list = list(tools_from_general_search)
+        for app_tools in app_tools_results:
+            tools_list.extend(app_tools)
+
+        return tools_list
+
+    @tool
+    async def load_functions(tool_ids: list[str]) -> str:
+        """Load specific functions by their IDs for use in subsequent steps.
+
+        Args:
+            tool_ids: Function ids in the form 'app__function'. Example: 'google_mail__send_email'
+
+        Returns:
+            Confirmation message about loaded functions
+        """
+        return f"Successfully loaded {len(tool_ids)} functions: {tool_ids}"
+
+    @tool
+    async def web_search(query: str) -> list:
+        """Search the web for the given query and return structured search results.
+
+        Do not use for app-specific searches (for example, reddit or linkedin searches
+
+        Returns:
+            list: A list of up to 10 search result dictionaries, each containing:
+                - id (str): Unique identifier, typically the URL
+                - title (str): The title/headline of the search result
+                - url (str): The web URL of the result
+                - publishedDate (str): ISO 8601 formatted date (e.g., "2025-01-01T00:00:00.000Z")
+                - author (str): Author name (may be empty string)
+                - summary (str): Text summary/snippet of the content
+                - image (str): URL to associated image (if available)
+
+        Example:
+            results = await web_search(query="python programming")
+        """
+        await tool_registry.export_tools(["exa__search_with_filters"], ToolFormat.LANGCHAIN)
+        response = await tool_registry.call_tool(
+            "exa__search_with_filters", {"query": query, "contents": {"summary": True}}
+        )
+        return response["results"]
+
+    return {"search_functions": search_functions, "load_functions": load_functions, "web_search": web_search}
+
+
+async def get_valid_tools(tool_ids: list[str], registry: ToolRegistry) -> tuple[list[str], list[str]]:
+    """For a given list of tool_ids, validates the tools and returns a list of links for the apps that have not been logged in"""
+    correct, incorrect = [], []
+    connections = await registry.list_connected_apps()
+    connected_apps = {connection["app_id"] for connection in connections}
+    unconnected = set()
+    unconnected_links = []
+    app_tool_list: dict[str, set[str]] = {}
+
+    # Group tool_ids by app for fewer registry calls
+    app_to_tools: dict[str, list[tuple[str, str]]] = {}
+    for tool_id in tool_ids:
+        if "__" not in tool_id:
+            incorrect.append(tool_id)
+            continue
+        app, tool_name = tool_id.split("__", 1)
+        app_to_tools.setdefault(app, []).append((tool_id, tool_name))
+
+    # Fetch all apps concurrently
+    async def fetch_tools(app: str):
+        try:
+            tools_dict = await registry.list_tools(app)
+            return app, {tool_unit["name"] for tool_unit in tools_dict}
+        except Exception:
+            return app, None
+
+    results = await asyncio.gather(*(fetch_tools(app) for app in app_to_tools))
+
+    # Build map of available tools per app
+    for app, tools in results:
+        if tools is not None:
+            app_tool_list[app] = tools
+
+    # Validate tool_ids
+    for app, tool_entries in app_to_tools.items():
+        available = app_tool_list.get(app)
+        if available is None:
+            incorrect.extend(tool_id for tool_id, _ in tool_entries)
+            continue
+        if app not in connected_apps and app not in unconnected:
+            unconnected.add(app)
+            text = registry.client.get_authorization_url(app)
+            start = text.find(":") + 1
+            end = text.find(". R", start)
+            url = text[start:end].strip()
+            markdown_link = f"[{app}]({url})"
+            unconnected_links.append(markdown_link)
+        for tool_id, tool_name in tool_entries:
+            if tool_name in available:
+                correct.append(tool_id)
+            else:
+                incorrect.append(tool_id)
+
+    return correct, unconnected_links