universal-mcp-agents 0.1.21__py3-none-any.whl → 0.1.23__py3-none-any.whl

universal_mcp/agents/codeact0/prompts.py

@@ -1,99 +1,183 @@
 import inspect
 import re
-from collections.abc import Sequence
-
-from langchain_core.tools import StructuredTool
+from collections.abc import Callable
 
 uneditable_prompt = """
 You are **Ruzo**, an AI Assistant created by AgentR — a creative, straight-forward, and direct principal software engineer with access to tools.
 
 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 in the chat. NEVER write a string yourself and print it.
+- 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 in the chat. NEVER write a string or sequences of strings yourself and print it.
 - 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.
+- For writing, text/document generation (like HTML/markdown document generation) or language processing tasks DO NOT answer directly. Instead you MUST use `execute_ipython_cell` tool with the llm functions provided to you for tasks like summarizing, text generation, classification, data extraction from text or unstructured data, etc. Avoid hardcoded approaches to classification, data extraction, or creative writing.
 - You also have access to two tools for finding and loading more python functions- `search_functions` and `load_functions`, which you must use for finding functions for using different external applications or additional functionality.
-    - Prioritize connected applications over unconnected ones from the output of `search_functions`.
-    - When multiple apps are connected, or none of the apps are connected, YOU MUST ask the user to choose the application(s). The search results will inform you when such a case occurs, and you must stop and ask the user if multiple apps are relevant.
-- 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. Avoid hardcoded approaches to classification, data extraction, or creative writing.
-- The code you write will be executed in a sandbox environment, and you can use the output of previous executions in your code. variables, functions, imports are retained.
-- 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. Similarly, you should only use print/smart_print for your own analysis, the user does not get the output.
+    - Prioritize connected applications over unconnected ones from the output of `search_functions`. However, if the user specifically asks for an application, you MUST use that irrespective of connection status.
+    - When multiple relevant apps are connected, or none of the apps are connected, YOU MUST ask the user to choose the application(s). The search results may also inform you when such a case occurs, and you must stop and ask the user if multiple apps are relevant.
 - If needed, feel free to ask for more information from the user (without using the `execute_ipython_cell` tool) to clarify the task.
 
-**Code Execution Guidelines:**
-- The code you write will be executed in a sandbox environment, and you can use the output of previous executions in your code. Variables, functions, imports are retained.
-- 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. Similarly, you should only use print/smart_print for your own analysis, the user does not get the output.
-- If needed, feel free to ask for more information from the user (without using the `execute_ipython_cell` tool) to clarify the task.
-- Always describe in 2-3 lines about the current progress. In each step, mention what has been achieved and what you are planning to do next.
+**Code Design**: 
+- Structure your code into multiple small, well-defined functions within a single execution snippet. This ensures modularity and makes it easier to debug or update specific logic without rewriting or re-executing large portions of code. You can only rewrite the function/portion that you need to edit since the others are retained in context.
+- Every snippet you execute using `execute_ipython_cell` MUST follow this structure:
+    - Break down logic into 3-5 small helper functions (30 lines each max)
+    - Each helper function should do ONE thing
+    - Example:
+        def _helper_function_1(...):
+            ...
+
+        def _helper_function_2(...):
+            ...
+        result1 = _helper_function_1(...)
+        smart_print(result1[:1]) #As an example, to check if it has been processed correctly
+        result2 = _helper_function_2(...)
+        smart_print(result2[:1])
+        final_result = ...
+        smart_print(final_result)
+- Thus, while debugging, if you face an error in result2, you do not need to rewrite _helper_function_1. 
+
 
-**Coding Best Practices:**
-- Variables defined at the top level of previous code snippets can be referenced in your code.
+**Code Writing Rules:**
+- The code you write will be executed in a sandbox environment, and you can use the output of previous executions in your code. Variables, defined functions, imports, loaded functions are retained.
+- DO NOT use the code execution to communicate/show anything to the user. The user is not able to see the output of the code cells, it is only for your processing and actions. Similarly, you should only use print/smart_print for your own analysis, the user does not get the output.
+- Whenever you need to generate a large body of text, such as a document, an HTML file, or a report, use llm functions and save the output file using save/upload functions. Do not generate text yourself and do not print the entire text in order to save your memory.
 - 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. However, do consider searching for external functions first, using the search and load tools to access them in the code.
 - 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.
 - Call all functions using keyword arguments only, never positional arguments.
-
-**Async Functions (Critical Rules):**
-Use async functions only as follows:
-- Case 1: Top-level await without asyncio.run()
-    Wrap in async function and call with asyncio.run():
-    ```python
-    async def main():
-        result = await some_async_function()
-        return result
-    asyncio.run(main())
-    ```
-- Case 2: Using asyncio.run() directly
-    If code already contains asyncio.run(), use as-is — do not wrap again:
-    ```python
-    asyncio.run(some_async_function())
-    ```
-Rules:
-- Never use await outside an async function
-- Never use await asyncio.run()
-- Never nest asyncio.run() calls
+- NEVER use execute_ipython_cell for:
+    - Static analysis or commentary
+    - Text that could be written as markdown
+    - Final output summarization after analysis
+    - Anything that's just formatted print statements
 
 **Final Output Requirements:**
-- Once you have all the information about the task, return the text directly to user in markdown format. No need to call `execute_ipython_cell` again.
+- Once you have all the information about the task, return the text directly to user in markdown format. Do NOT call `execute_ipython_cell` or any LLM tools again just for summarization. Do NOT use llm__generate_text for this purpose.
 - Always respond in github flavoured markdown format.
 - For charts and diagrams, use mermaid chart in markdown directly.
 - Your final response should contain the complete answer to the user's request in a clear, well-formatted manner that directly addresses what they asked for.
+- For file types like images, audio, documents, etc., you must use the `upload_file` tool to upload the file to the server and render the link in the markdown response.
 """
 
-PLAYBOOK_PLANNING_PROMPT = """Now, you are tasked with creating a reusable playbook from the user's previous workflow.
+AGENT_BUILDER_PLANNING_PROMPT = """TASK: Analyze the conversation history and code execution to create a step-by-step non-technical plan for a reusable function.
+Rules:
+- Do NOT include the searching and loading of functions. Assume that the functions have already been loaded.
+- The plan is a sequence of steps corresponding to the key logical steps taken to achieve the user's task in the conversation history, without focusing on technical specifics.
+- You must output a JSON object with a single key "steps", which is a list of strings. Each string is a step in the agent.
+- Identify user-provided information as variables that should become the main agent input parameters using `variable_name` syntax, enclosed by backticks `...`. Intermediate variables should be highlighted using italics, i.e. *...*, NEVER `...`
+- Keep the logic generic and reusable. Avoid hardcoding any names/constants. Instead, keep them as variables with defaults. They should be represented as `variable_name(default = default_value)`.
+- Have a human-friendly plan and inputs format. That is, it must not use internal IDs or keys used by APIs as either inputs or outputs to the overall plan; using them internally is okay.
+- Be as concise as possible, especially for internal processing steps.
+- For steps where the assistant's intelligence was used outside of the code to infer/decide/analyse something, replace it with the use of *llm__* functions in the plan if required.
 
-TASK: Analyze the conversation history and code execution to create a step-by-step plan for a reusable function.
-Do not include the searching and loading of tools. Assume that the tools have already been loaded.
-The plan is a sequence of steps.
-You must output a JSON object with a single key "steps", which is a list of strings. Each string is a step in the playbook.
+Example Conversation History:
+User Message: "Create an image using Gemini for Marvel Cinematic Universe in comic style"
+Code snippet: image_result = await google_gemini__generate_image(prompt=prompt)
+Assistant Message: "The image has been successfully generated [image_result]."
+User Message: "Save the image in my OneDrive"
+Code snippet: image_data = base64.b64decode(image_result['data'])
+    temp_file_path = tempfile.mktemp(suffix='.png')
+    with open(temp_file_path, 'wb') as f:
+        f.write(image_data)
+    # Upload the image to OneDrive with a descriptive filename
+    onedrive_filename = "Marvel_Cinematic_Universe_Comic_Style.png"
 
-Your plan should:
-1. Identify the key steps in the workflow
-2. Mark user-specific variables that should become the main playbook function parameters using `variable_name` syntax. Intermediate variables should not be highlighted using ``
-3. Keep the logic generic and reusable
-4. Be clear and concise
+    print(f"Uploading to OneDrive as: {onedrive_filename}")
 
-Example:
-{
-    "steps": [
-        "Connect to database using `db_connection_string`",
-        "Query user data for `user_id`",
-        "Process results and calculate `metric_name`",
-        "Send notification to `email_address`"
-    ]
-}
+    # Upload to OneDrive root folder
+    upload_result = onedrive__upload_file(
+        file_path=temp_file_path,
+        parent_id='root',
+        file_name=onedrive_filename
+    )
 
+Generated Steps:
+"steps": [
+    "Generate an image using Gemini model with `image_prompt` and `style(default = 'comic')`",
+    "Upload the obtained image to OneDrive using `onedrive_filename(default = 'generated_image.png')` and `onedrive_parent_folder(default = 'root')`",
+    "Return confirmation of upload including file name and destination path, and link to the upload"
+  ]
+Note that internal variables like upload_result, image_result are not highlighted in the plan, and intermediate processing details are skipped.
 Now create a plan based on the conversation history. Do not include any other text or explanation in your response. Just the JSON object.
+Note that the following tools are pre-loaded for the agent's use, and can be inluded in your plan if needed as internal variables (especially the llm tools)-\n
 """
 
 
-PLAYBOOK_GENERATING_PROMPT = """Now, you are tasked with generating the playbook function.
-Your response must be ONLY the Python code for the function.
-Do not include any other text, markdown, or explanations in your response.
-Your response should start with `def` or `async def`.
-The function should be a single, complete piece of code that can be executed independently, based on previously executed code snippets that executed correctly.
-The parameters of the function should be the same as the final confirmed playbook plan.
+AGENT_BUILDER_GENERATING_PROMPT = """
+You are tasked with generating granular, reusable Python code for an agent based on the final confirmed plan and the conversation history (user messages, assistant messages, and code executions).
+
+Produce a set of small, single-purpose functions—typically one function per plan step—plus one top-level orchestrator function that calls the step functions in order to complete the task.
+
+Rules-
+- Do NOT include the searching and loading of functions. Assume required functions have already been loaded. Include imports you need.
+- Your response must be **ONLY Python code**. No markdown or explanations.
+- Define multiple top-level functions:
+  1) One small, clear function for each plan step (as granular as practical).
+  2) One top-level orchestrator function that calls the step functions in sequence to achieve the plan objectives.
+- The orchestrator function's parameters **must exactly match the external variables** in the agent plan (the ones marked with backticks `` `variable_name` ``). Provide defaults exactly as specified in the plan when present. Variables in italics (i.e. enclosed in *...*) are internal and must not be orchestrator parameters.
+- The orchestrator function MUST be declared with `def` or `async def` and be directly runnable with a single Python command (e.g., `image_generator(...)`). If it is async, assume the caller will `await` it.
+- Step functions should accept only the inputs they need, return explicit outputs, and pass intermediate results forward via return values—not globals.
+- Name functions in snake_case derived from their purpose/step. Use keyword arguments in calls; avoid positional-only calls.
+- Keep the code self-contained and executable. Put imports at the top of the code. Do not nest functions unless strictly necessary.
+- If previously executed code snippets exist, adapt and reuse their validated logic inside the appropriate step functions.
+- Do not print the final output; return it from the orchestrator.
+
+Example:
+
+If the plan has:
+
+"steps": [
+"Receive creative description as image_prompt",
+"Generate image using Gemini with style(default = 'comic')",
+"Save temporary image internally as *temp_file_path*",
+"Upload *temp_file_path* to OneDrive folder onedrive_parent_folder(default = 'root')"
+]
+
+Then the functions should look like:
+
+```python
+from typing import Dict
+
+def generate_image(image_prompt: str, style: str = "comic") -> Dict:
+    # previously validated code to call Gemini
+    ...
+
+def save_temp_image(image_result: Dict) -> str:
+    # previously validated code to write bytes to a temp file
+    ...
+
+def upload_to_onedrive(temp_file_path: str, onedrive_parent_folder: str = "root") -> Dict:
+    # previously validated code to upload
+    ...
+
+def image_generator(image_prompt: str, style: str = "comic", onedrive_parent_folder: str = "root") -> Dict:
+    image_result = generate_image(image_prompt=image_prompt, style=style)
+    temp_file_path = save_temp_image(image_result=image_result)
+    upload_result = upload_to_onedrive(temp_file_path=temp_file_path, onedrive_parent_folder=onedrive_parent_folder)
+    return upload_result
+```
+
+Use this convention consistently to generate the final code.
+Note that the following tools are pre-loaded for the agent's use, and can be included in your code-\n
+"""
+
+
+AGENT_BUILDER_META_PROMPT = """
+You are preparing metadata for a reusable agent based on the confirmed step-by-step plan.
+
+TASK: Create a concise, human-friendly name and a short description for the agent.
+
+INPUTS:
+- Conversation context and plan steps will be provided in prior messages
+
+REQUIREMENTS:
+1. Name: 3-6 words, Title Case, no punctuation except hyphens if needed
+2. Description: Single sentence, <= 140 characters, clearly states what the agent does
+
+OUTPUT: Return ONLY a JSON object with exactly these keys:
+{
+  "name": "...",
+  "description": "..."
+}
 """
 
 
@@ -110,52 +194,88 @@ def make_safe_function_name(name: str) -> str:
     return safe_name
 
 
+# Compile regex once for better performance
+_RAISES_PATTERN = re.compile(r"\n\s*[Rr]aises\s*:.*$", re.DOTALL)
+
+
+def _clean_docstring(docstring: str | None) -> str:
+    """Remove the 'Raises:' section and everything after it from a docstring."""
+    if not docstring:
+        return ""
+
+    # Use pre-compiled regex for better performance
+    cleaned = _RAISES_PATTERN.sub("", docstring)
+    return cleaned.strip()
+
+
+def build_tool_definitions(tools: list[Callable]) -> tuple[list[str], dict[str, Callable]]:
+    tool_definitions = []
+    context = {}
+
+    # Pre-allocate lists for better performance
+    tool_definitions = [None] * len(tools)
+
+    for i, tool in enumerate(tools):
+        tool_name = tool.__name__
+        cleaned_docstring = _clean_docstring(tool.__doc__)
+
+        # Pre-compute string parts to avoid repeated string operations
+        async_prefix = "async " if inspect.iscoroutinefunction(tool) else ""
+        signature = str(inspect.signature(tool))
+
+        tool_definitions[i] = f'''{async_prefix}def {tool_name} {signature}:
+    """{cleaned_docstring}"""
+    ...'''
+        context[tool_name] = tool
+
+    return tool_definitions, context
+
+
 def create_default_prompt(
-    tools: Sequence[StructuredTool],
-    additional_tools: Sequence[StructuredTool],
+    tools: list[Callable],
+    additional_tools: list[Callable],
     base_prompt: str | None = None,
-    playbook: object | None = None,
+    apps_string: str | None = None,
+    agent: object | None = None,
+    is_initial_prompt: bool = False,
 ):
-    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 + additional_tools:
-        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}"""
-    ...
-    '''
-        safe_name = make_safe_function_name(tool.name)
-        tools_context[safe_name] = tool_callable
-
-    if base_prompt and base_prompt.strip():
-        system_prompt += f"Your goal is to perform the following task:\n\n{base_prompt}"
-
-    # Append existing playbook (plan + code) if provided
-    try:
-        if playbook and hasattr(playbook, "instructions"):
-            pb = playbook.instructions or {}
-            plan = pb.get("playbookPlan")
-            code = pb.get("playbookScript")
-            if plan or code:
-                system_prompt += "\n\nExisting Playbook Provided:\n"
-                if plan:
-                    if isinstance(plan, list):
-                        plan_block = "\n".join(f"- {str(s)}" for s in plan)
-                    else:
-                        plan_block = str(plan)
-                    system_prompt += f"Plan Steps:\n{plan_block}\n"
-                if code:
-                    system_prompt += f"\nScript:\n```python\n{str(code)}\n```\n"
-    except Exception:
-        # Silently ignore formatting issues
-        pass
+    if is_initial_prompt:
+        system_prompt = uneditable_prompt.strip()
+        if apps_string:
+            system_prompt += f"\n\n**Connected external applications (These apps have been logged into by the user):**\n{apps_string}\n\n Use `search_functions` to search for functions you can perform using the above. You can also discover more applications using the `search_functions` tool to find additional tools and integrations, if required. However, you MUST not assume the application when multiple apps are connected for a particular usecase.\n"
+        system_prompt += "\n\nIn addition to the Python Standard Library, you can use the following external functions:\n Carefully note which functions are normal and which functions are async. CRITICAL: Use `await` with async functions and async functions ONLY."
+    else:
+        system_prompt = ""
+
+    tool_definitions, tools_context = build_tool_definitions(tools + additional_tools)
+    system_prompt += "\n".join(tool_definitions)
+
+    if is_initial_prompt:
+        if base_prompt and base_prompt.strip():
+            system_prompt += (
+                f"\n\nUse the following information/instructions while completing your tasks:\n\n{base_prompt}"
+            )
+
+        # Append existing agent (plan + code) if provided
+        try:
+            if agent and hasattr(agent, "instructions"):
+                pb = agent.instructions or {}
+                plan = pb.get("plan")
+                code = pb.get("script")
+                if plan or code:
+                    system_prompt += (
+                        "\n\nYou have been provided an existing agent plan and code for performing a task.:\n"
+                    )
+                    if plan:
+                        if isinstance(plan, list):
+                            plan_block = "\n".join(f"- {str(s)}" for s in plan)
+                        else:
+                            plan_block = str(plan)
+                        system_prompt += f"Plan Steps:\n{plan_block}\n"
+                    if code:
+                        system_prompt += f"\nScript:\n```python\n{str(code)}\n```\nThis function can be called by you using `execute_ipython_code`. Do NOT redefine the function, unless it has to be modified. For modifying it, you must enter agent_builder mode first so that it is modified in the database and not just the chat locally."
+        except Exception:
+            # Silently ignore formatting issues
+            pass
 
     return system_prompt, tools_context

universal_mcp/agents/codeact0/sandbox.py

@@ -1,6 +1,8 @@
+import ast
 import contextlib
 import inspect
 import io
+import pickle
 import queue
 import re
 import socket
@@ -13,7 +15,7 @@ from langchain_core.tools import tool
 from universal_mcp.agents.codeact0.utils import derive_context, inject_context, smart_truncate
 
 
-def eval_unsafe(
+async def eval_unsafe(
     code: str, _locals: dict[str, Any], add_context: dict[str, Any], timeout: int = 180
 ) -> tuple[str, dict[str, Any], dict[str, Any]]:
     """
@@ -26,6 +28,7 @@ def eval_unsafe(
     EXCLUDE_TYPES = (
         types.ModuleType,
         type(re.match("", "")),
+        type(re.compile("")),
         type(threading.Lock()),
         type(threading.RLock()),
         threading.Event,
@@ -38,20 +41,16 @@ def eval_unsafe(
 
     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."
+    try:
+        compiled_code = compile(code, "<string>", "exec", flags=ast.PyCF_ALLOW_TOP_LEVEL_AWAIT)
+        with contextlib.redirect_stdout(io.StringIO()) as f:
+            coroutine = eval(compiled_code, _locals, _locals)
+            # Await the coroutine to run the code if it's async
+            if coroutine:
+                await coroutine
+        result_container["output"] = f.getvalue() or "<code ran, no output printed to stdout>"
+    except Exception as e:
+        result_container["output"] = f"Error during execution: {type(e).__name__}: {e}"
 
     # If NameError for provider__tool occurred, append guidance (no retry)
     try:
@@ -64,7 +63,7 @@ def eval_unsafe(
     # Filter locals for picklable/storable variables
     all_vars = {}
     for key, value in _locals.items():
-        if key == "__builtins__":
+        if key.startswith("__"):
             continue
         if inspect.iscoroutine(value) or inspect.iscoroutinefunction(value):
             continue
@@ -73,7 +72,12 @@ def eval_unsafe(
         if isinstance(value, EXCLUDE_TYPES):
             continue
         if not callable(value) or not hasattr(value, "__name__"):
-            all_vars[key] = value
+            # Only keep if it can be pickled (serialized) successfully
+            try:
+                pickle.dumps(value)
+                all_vars[key] = value
+            except Exception:
+                pass
 
     # Safely derive context
     try:

universal_mcp/agents/codeact0/state.py

@@ -1,15 +1,20 @@
-from typing import Annotated, Any, List
+from typing import Annotated, Any
 
-from langgraph.prebuilt.chat_agent_executor import AgentState
+from langchain.agents import AgentState
 from pydantic import BaseModel, Field
 
 
-class PlaybookPlan(BaseModel):
-    steps: List[str] = Field(description="The steps of the playbook.")
+class AgentBuilderPlan(BaseModel):
+    steps: list[str] = Field(description="The steps of the agent.")
 
 
-class PlaybookCode(BaseModel):
-    code: str = Field(description="The Python code for the playbook.")
+class AgentBuilderCode(BaseModel):
+    code: str = Field(description="The Python code for the agent.")
+
+
+class AgentBuilderMeta(BaseModel):
+    name: str = Field(description="Concise, title-cased agent name (3-6 words).")
+    description: str = Field(description="Short, one-sentence description (<= 140 chars).")
 
 
 def _enqueue(left: list, right: list) -> list:
@@ -41,9 +46,13 @@ class CodeActState(AgentState):
     """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."""
+    agent_builder_mode: str | None
+    """State for the agent builder agent."""
     selected_tool_ids: Annotated[list[str], _enqueue]
     """Queue for tools exported from registry"""
     plan: list[str] | None
-    """Plan for the playbook agent."""
+    """Plan for the agent builder agent."""
+    agent_name: str | None
+    """Generated agent name after confirmation."""
+    agent_description: str | None
+    """Generated short description after confirmation."""