universal-mcp-agents 0.1.11__py3-none-any.whl → 0.1.12__py3-none-any.whl

universal_mcp/agents/codeact0/llm_tool.py

@@ -0,0 +1,379 @@
+import json
+from dataclasses import dataclass
+from typing import Any, Literal, cast
+
+from langchain.chat_models import init_chat_model
+from langchain_openai import AzureChatOpenAI
+
+from universal_mcp.agents.codeact0.utils import get_message_text, light_copy
+
+MAX_RETRIES = 3
+
+
+def get_context_str(source: Any | list[Any] | dict[str, Any]) -> str:
+    """Converts context to a string representation."""
+    if not isinstance(source, dict):
+        if isinstance(source, list):
+            source = {f"doc_{i + 1}": str(doc) for i, doc in enumerate(source)}
+        else:
+            source = {"content": str(source)}
+
+    return "\n".join(f"<{k}>\n{str(v)}\n</{k}>" for k, v in source.items())
+
+
+def smart_print(data: Any) -> None:
+    """Prints a dictionary or list of dictionaries with string values truncated to 30 characters.
+
+    Args:
+        data: Either a dictionary with string keys, or a list of such dictionaries
+    """
+    light_copy(data)
+
+
+def creative_writer(
+    task: str,
+    context: Any | list[Any] | dict[str, Any],
+    tone: str = "normal",
+    format: Literal["markdown", "html", "plain"] = "markdown",
+    length: Literal["very-short", "concise", "normal", "long"] = "concise",
+) -> str:
+    """
+    Given a high-level writing task and context, returns a well-written text
+    that achieves the task, given the context.
+
+    Example Call:
+        creative_writer("Summarize this website with the goal of making it easy to understand.", web_content)
+        creative_writer("Make a markdown table summarizing the key differences between doc_1 and doc_2.", {"doc_1": str(doc_1), "doc_2": str(doc_2)})
+        creative_writer("Summarize all the provided documents.", [doc_1, doc_2, doc_3])
+
+    Important:
+    - Include specifics of the goal in the context verbatim.
+    - Be precise and direct in the task, and include as much context as possible.
+    - Include relevant high-level goals or intent in the task.
+    - You can provide multiple documents as input, and reference them in the task.
+    - You MUST provide the contents of any source documents to `creative_writer`.
+    - NEVER use `creative_writer` to produce JSON for a Pydantic model.
+
+    Args:
+        task: The main writing task or directive.
+        context: A single string, list of strings, or dict mapping labels to content.
+        tone: The desired tone of the output (e.g., "normal", "flirty", "formal", "casual", "crisp", "poetic", "technical", "internet-chat", "smartass", etc.).
+        format: Output format ('markdown', 'html', 'plain-text').
+        length: Desired length of the output ('very-short', 'concise', 'normal', 'long').
+
+    Returns:
+        str: The generated text output.
+    """
+
+    context = get_context_str(context)
+
+    task = task.strip() + "\n\n"
+    if format == "markdown":
+        task += "Please write in Markdown format.\n\n"
+    elif format == "html":
+        task += "Please write in HTML format.\n\n"
+    else:
+        task += "Please write in plain text format. Don't use markdown or HTML.\n\n"
+
+    if tone not in ["normal", "default", ""]:
+        task = f"{task} (Tone instructions: {tone})"
+
+    if length not in ["normal", "default", ""]:
+        task = f"{task} (Length instructions: {length})"
+
+    prompt = f"{task}\n\nContext:\n{context}\n\n"
+
+    model = AzureChatOpenAI(model="gpt-4o", temperature=0.7)
+
+    response = model.with_retry(stop_after_attempt=MAX_RETRIES).invoke(prompt)
+    return get_message_text(response)
+
+
+def ai_classify(
+    classification_task_and_requirements: str,
+    context: Any | list[Any] | dict[str, Any],
+    class_descriptions: dict[str, str],
+) -> dict[str, Any]:
+    """
+    Classifies and compares data based on given requirements.
+
+    Use `ai_classify` for tasks which need to classify data into one of many categories.
+    If making multiple binary classifications, call `ai_classify` for each.
+
+    Guidance:
+    - Prefer to use ai_classify operations to compare strings, rather than string ops.
+    - Prefer to include an "Unsure" category for classification tasks.
+    - The `class_descriptions` dict argument MUST be a map from possible class names to a precise description.
+    - Use precise and specific class names and concise descriptions.
+    - Pass ALL relevant context, preferably as a dict mapping labels to content.
+    - Returned dict maps each possible class name to a probability.
+
+    Example Usage:
+        classification_task_and_requirements = "Does the document contain an address?"
+        class_descriptions = {
+            "Is_Address": "Valid addresses usually have street names, city, and zip codes.",
+            "Not_Address": "Not valid addresses."
+        }
+        classification = ai_classify(
+            classification_task_and_requirements,
+            {"address": extracted_address},
+            class_descriptions
+        )
+        if classification["probabilities"]["Is_Address"] > 0.5:
+            ...
+
+    Args:
+        classification_task_and_requirements: The classification question and rules.
+        context: The data to classify (string, list, or dict).
+        class_descriptions: Mapping from class names to descriptions.
+
+    Returns:
+        dict: {
+            probabilities: dict[str, float],
+            reason: str,
+            top_class: str,
+        }
+    """
+
+    context = get_context_str(context)
+
+    prompt = (
+        f"{classification_task_and_requirements}\n\n"
+        f"\nThis is classification task\nPossible classes and descriptions:\n"
+        f"{json.dumps(class_descriptions, indent=2)}\n"
+        f"\nContext:\n{context}\n\n"
+        "Return ONLY a valid JSON object, no extra text."
+    )
+
+    model = init_chat_model(model="claude-4-sonnet-20250514", temperature=0)
+
+    @dataclass
+    class ClassificationResult:
+        probabilities: dict[str, float]
+        reason: str
+        top_class: str
+
+    response = (
+        model.with_structured_output(schema=ClassificationResult, method="json_mode")
+        .with_retry(stop_after_attempt=MAX_RETRIES)
+        .invoke(prompt)
+    )
+    return cast(dict[str, Any], response)
+
+
+def call_llm(
+    task_instructions: str, context: Any | list[Any] | dict[str, Any], output_json_schema: dict[str, Any]
+) -> dict[str, Any]:
+    """
+    Call a Large Language Model (LLM) with an instruction and contextual information,
+    returning a dictionary matching the given output_json_schema.
+    Can be used for tasks like creative writing, llm reasoning based content generation, etc.
+
+    You MUST anticipate Exceptions in reasoning based tasks which will lead to some empty fields
+    in the returned output; skip this item if applicable.
+
+    General Guidelines:
+    - Be comprehensive, specific, and precise on the task instructions.
+    - Include as much context as possible.
+    - You can provide multiple items in context, and reference them in the task.
+    - Include relevant high-level goals or intent in the task.
+    - In the output_json_schema, use required field wherever necessary.
+    - The more specific your task instructions and output_json_schema are, the better the results.
+
+    Guidelines for content generation tasks:
+    - Feel free to add instructions for tone, length, and format (markdown, html, plain-text, xml)
+    - Some examples of tone are: "normal", "flirty", "formal", "casual", "crisp", "poetic", "technical", "internet-chat", "smartass", etc.
+    - Prefer length to be concise by default. Other examples are: "very-short", "concise", "normal", "long", "2-3 lines", etc.
+    - In format prefer plain-text but you can also use markdown and html wherever useful.
+
+    Args:
+        instruction: The main directive for the LLM (e.g., "Summarize the article" or "Extract key entities").
+        context:
+            A dictionary containing named text elements that provide additional
+            information for the LLM. Keys are labels (e.g., 'article', 'transcript'),
+            values are strings of content.
+        output_json_schema: must be a valid JSON schema with top-level 'title' and 'description' keys.
+
+    Returns:
+        dict: Parsed JSON object matching the desired output_json_schema.
+
+    """
+    context = get_context_str(context)
+
+    prompt = f"{task_instructions}\n\nContext:\n{context}\n\nReturn ONLY a valid JSON object, no extra text."
+
+    model = init_chat_model(model="claude-4-sonnet-20250514", temperature=0)
+
+    response = (
+        model.with_structured_output(schema=output_json_schema, method="json_mode")
+        .with_retry(stop_after_attempt=MAX_RETRIES)
+        .invoke(prompt)
+    )
+    return cast(dict[str, Any], response)
+
+
+def data_extractor(
+    extraction_task: str, source: Any | list[Any] | dict[str, Any], output_json_schema: dict[str, Any]
+) -> dict[str, Any]:
+    """
+    Extracts structured data from unstructured data (documents, webpages, images, large bodies of text),
+    returning a dictionary matching the given output_json_schema.
+
+    You MUST anticipate Exception raised for unextractable data; skip this item if applicable.
+
+    Strongly prefer to:
+    - Be comprehensive, specific, and precise on the data you want to extract.
+    - Use optional fields everywhere.
+    - Extract multiple items from each source unless otherwise specified.
+    - The more specific your extraction task and output_json_schema are, the better the results.
+
+    Args:
+        extraction_task: The directive describing what to extract.
+        source: The unstructured data to extract from.
+        output_json_schema: must be a valid JSON schema with top-level 'title' and 'description' keys.
+
+    Returns:
+        dict: Parsed JSON object matching the desired output_json_schema.
+
+    Example:
+        news_articles_schema = {
+            "title": "NewsArticleList",
+            "description": "A list of news articles with headlines and URLs",
+            "type": "object",
+            "properties": {
+                "articles": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "headline": {
+                                "type": "string"
+                            },
+                            "url": {
+                                "type": "string"
+                            }
+                        },
+                        "required": ["headline", "url"]
+                    }
+                }
+            },
+            "required": ["articles"]
+        }
+
+        news_articles = data_extractor("Extract headlines and their corresponding URLs.", content, news_articles_schema)
+    """
+
+    context = get_context_str(source)
+
+    prompt = f"{extraction_task}\n\nContext:\n{context}\n\nReturn ONLY a valid JSON object, no extra text."
+
+    model = init_chat_model(model="claude-4-sonnet-20250514", temperature=0)
+
+    response = (
+        model.with_structured_output(schema=output_json_schema, method="json_mode")
+        .with_retry(stop_after_attempt=MAX_RETRIES)
+        .invoke(prompt)
+    )
+    return cast(dict[str, Any], response)
+
+
+# news_articles_schema = {
+#     "type": "object",
+#     "properties": {
+#         "articles": {
+#             "type": "array",
+#             "title": "Articles",
+#             "description": "List of news articles",
+#             "items": {
+#                 "type": "object",
+#                 "properties": {
+#                     "headline": {
+#                         "type": "string",
+#                         "title": "Headline",
+#                         "description": "The headline of the news article"
+#                     },
+#                     "url": {
+#                         "type": "string",
+#                         "title": "URL",
+#                         "description": "The URL of the news article"
+#                     }
+#                 },
+#                 "required": ["headline", "url"],
+#             }
+#         }
+#     },
+#     "required": ["articles"],
+# }
+
+
+# news_articles_schema = {
+#   "title": "NewsArticleList",
+#   "description": "A list of news articles with headlines and URLs",
+#   "type": "object",
+#   "properties": {
+#     "articles": {
+#       "type": "array",
+#       "items": {
+#         "type": "object",
+#         "properties": {
+#           "headline": {
+#             "type": "string"
+#           },
+#           "url": {
+#             "type": "string"
+#           }
+#         },
+#         "required": ["headline", "url"]
+#       }
+#     }
+#   },
+#   "required": ["articles"]
+# }
+# model = init_chat_model(model="claude-4-sonnet-20250514", temperature=0)
+# structured_model = model.with_structured_output(news_articles_schema)
+
+
+# class TwitterComment(BaseModel):
+#     skip: bool
+#     reason: str
+#     comment: str
+
+# twitter_comment_schema = {
+#   "title": "TwitterComment",
+#   "description": "A twitter comment to engage with followers",
+#   "type": "object",
+#   "properties": {
+#     "skip": {
+#       "type": "boolean"
+#     },
+#     "reason": {
+#       "type": "string"
+#     },
+#     "comment": {
+#       "type": "string"
+#     },
+#     "tagged_profiles": {
+#       "type": "array",
+#       "items": {
+#         "type": "string"
+#       }
+#     }
+#   },
+#   "required": ["skip", "reason"]
+# }
+
+# comment = {
+#     "tweet_id": "08109402",
+#     "handle": "@iamnishant",
+#     "text": "Hey really loved this tweet! Well said 💯"
+# }
+
+# comment_instructions = (
+#     "Goal is to engage with my twitter followers who have commented on my tweets."
+#     "Please generate a single line, context-aware, conversational reply for the given comment."
+#     "- Use social media language (can use hinglish)."
+#     "- Skip the reply, if the comment is too generic."
+#     "- Also tag relevant people in the reply."
+# )
+
+# my_reply = call_llm(comment_instructions, comment, twitter_comment_schema)

universal_mcp/agents/codeact0/prompts.py

@@ -0,0 +1,156 @@
+uneditable_prompt = """
+You are Wingman, 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.
+- Ensure to not print large amounts of data, use string truncation to limit the output to a few lines when checking the data structure.
+- 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, and these have to be imported at the top of every code snippet where required.
+- Wrap await calls in a function and call it using `asyncio.run` to use async functions.
+
+NOTE: If any function throws an error requiring authentication, provide the user with a Markdown link to the authentication page and prompt them to authenticate.
+"""
+import inspect
+import re
+from collections.abc import Sequence
+from datetime import datetime
+
+from langchain_core.tools import StructuredTool
+
+
+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 dedent(text):
+    """Remove any common leading whitespace from every line in `text`.
+
+    This can be used to make triple-quoted strings line up with the left
+    edge of the display, while still presenting them in the source code
+    in indented form.
+
+    Note that tabs and spaces are both treated as whitespace, but they
+    are not equal: the lines "  hello" and "\\thello" are
+    considered to have no common leading whitespace.
+
+    Entirely blank lines are normalized to a newline character.
+    """
+    # Look for the longest leading string of spaces and tabs common to
+    # all lines.
+    margin = None
+    _whitespace_only_re = re.compile("^[ \t]+$", re.MULTILINE)
+    _leading_whitespace_re = re.compile("(^[ \t]*)(?:[^ \t\n])", re.MULTILINE)
+    text = _whitespace_only_re.sub("", text)
+    indents = _leading_whitespace_re.findall(text)
+    for indent in indents:
+        if margin is None:
+            margin = indent
+
+        # Current line more deeply indented than previous winner:
+        # no change (previous winner is still on top).
+        elif indent.startswith(margin):
+            pass
+
+        # Current line consistent with and no deeper than previous winner:
+        # it's the new winner.
+        elif margin.startswith(indent):
+            margin = indent
+
+        # Find the largest common whitespace between current line and previous
+        # winner.
+        else:
+            for i, (x, y) in enumerate(zip(margin, indent)):
+                if x != y:
+                    margin = margin[:i]
+                    break
+
+    # sanity check (testing/debugging only)
+    if 0 and margin:
+        for line in text.split("\n"):
+            assert not line or line.startswith(margin), f"line = {line!r}, margin = {margin!r}"
+
+    if margin:
+        text = re.sub(r"(?m)^" + margin, "", text)
+    return text
+
+
+def indent(text, prefix, predicate=None):
+    """Adds 'prefix' to the beginning of selected lines in 'text'.
+
+    If 'predicate' is provided, 'prefix' will only be added to the lines
+    where 'predicate(line)' is True. If 'predicate' is not provided,
+    it will default to adding 'prefix' to all non-empty lines that do not
+    consist solely of whitespace characters.
+    """
+    if predicate is None:
+        # str.splitlines(True) doesn't produce empty string.
+        #  ''.splitlines(True) => []
+        #  'foo\n'.splitlines(True) => ['foo\n']
+        # So we can use just `not s.isspace()` here.
+        def predicate(s):
+            return not s.isspace()
+
+    prefixed_lines = []
+    for line in text.splitlines(True):
+        if predicate(line):
+            prefixed_lines.append(prefix)
+        prefixed_lines.append(line)
+
+    return "".join(prefixed_lines)
+
+
+def create_default_prompt(
+    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"
+    )
+    tools_context = {}
+    for tool in tools:
+        # Create a safe function name
+        safe_name = make_safe_function_name(tool.name)
+        # Use coroutine if it exists, otherwise use func
+        if hasattr(tool, "coroutine") and tool.coroutine is not None:
+            tool_callable = tool.coroutine
+            signature = inspect.signature(tool_callable)
+            is_async = True
+        elif hasattr(tool, "func") and tool.func is not None:
+            tool_callable = tool.func
+            signature = inspect.signature(tool_callable)
+            is_async = False
+        else:
+            raise ValueError(f"Tool {tool.name} does not have a callable coroutine or function.")
+        tools_context[safe_name] = tool_callable
+        system_prompt += f'''
+{"async " if is_async else ""}def {safe_name}{str(signature)}:
+    """
+{indent(dedent(tool.description), "    ")}
+    """
+    ...
+'''
+    system_prompt += f"\n\nThe current time is {datetime.now().strftime('%H:%M:%S')}"
+    if base_prompt and base_prompt.strip():
+        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

@@ -0,0 +1,90 @@
+import contextlib
+import inspect
+import io
+import queue
+import re
+import socket
+import threading
+import types
+from typing import Any
+
+from langchain_core.tools import tool
+
+from universal_mcp.agents.codeact0.utils import derive_context
+
+
+def eval_unsafe(
+    code: str, _locals: dict[str, Any], add_context: dict[str, Any]
+) -> tuple[str, dict[str, Any], dict[str, Any]]:
+    # print(_locals)
+    EXCLUDE_TYPES = (
+        types.ModuleType,  # modules
+        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)
+    )
+    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)
+    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
+
+
+@tool(parse_docstring=True)
+def execute_ipython_cell(snippet: str) -> str:
+    """
+    Executes Python code in an IPython notebook cell:
+    * The output generated by the notebook cell is returned by this tool
+    * State is persistent across executions and discussions with the user
+    * The input code may reference variables created in previous executions
+
+    Args:
+        snippet: The Python code to execute.
+
+    Returns:
+        String containing the execution output or error message.
+
+    Raises:
+        ValueError: If snippet is empty.
+    """
+    # Validate required parameters
+    if not snippet or not snippet.strip():
+        raise ValueError("Parameter 'snippet' is required and cannot be empty or whitespace")
+
+    # Your actual execution logic would go here
+    return f"Successfully executed {len(snippet)} characters of Python code"

universal_mcp/agents/codeact0/state.py

@@ -0,0 +1,12 @@
+from typing import Any
+
+from langgraph.graph import MessagesState
+
+
+class CodeActState(MessagesState):
+    """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."""

universal_mcp/agents/codeact0/usecases/1-unsubscribe.yaml

@@ -0,0 +1,4 @@
+base_prompt: 'Find and extract unsubscribe links from all emails in my inbox from the last 7 days. List all unsubscribe links found with the email subject and sender.'
+tools:
+- google_mail__list_messages
+- google_mail__get_message_details

universal_mcp/agents/codeact0/usecases/10-reddit2.yaml

@@ -0,0 +1,10 @@
+base_prompt: 'Process rows 2-5 from the Google Sheet (ID: 1nnnCp3_IWcdHv4UVgXtwYF5wedxbqF4RIeyjN6mCKD8). For each unprocessed row, extract Reddit post links, fetch post details and comments, analyze content relevance to AgentR/Wingmen products, classify into tiers 1-4, generate appropriate response drafts, and update the sheet with all findings.'
+tools:
+- google_sheet__add_table
+- google_sheet__append_values
+- google_sheet__update_values
+- reddit__get_post_comments_details
+- google_mail__list_messages
+- google_sheet__format_cells
+- google_sheet__get_spreadsheet_metadata
+- google_sheet__batch_get_values_by_range

universal_mcp/agents/codeact0/usecases/11-github.yaml

@@ -0,0 +1,13 @@
+base_prompt: 'Fetch all open issues from the GitHub repository "microsoft/vscode" and add them to a new Google Sheet. Then create corresponding tasks in ClickUp for each issue with descriptions, tags, and "In Progress" status. Delete processed rows from the sheet after creating ClickUp tasks.'
+tools:
+- google_sheet__get_values
+- clickup__tasks_create_new_task
+- clickup__spaces_get_details
+- clickup__lists_get_list_details
+- clickup__tasks_get_list_tasks
+- google_sheet__delete_dimensions
+- google_sheet__update_values
+- google_sheet__get_spreadsheet_metadata
+- google_sheet__batch_get_values_by_range
+- github__list_issues
+- github__update_issue