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

universal_mcp/agents/codeact0/utils.py

@@ -0,0 +1,374 @@
+import re
+from collections.abc import Sequence
+from typing import Any
+
+from langchain_core.messages import BaseMessage
+from pydantic import ValidationError
+from requests import JSONDecodeError
+
+
+def light_copy(data):
+    """
+    Deep copy a dict[str, any] or Sequence[any] with string truncation.
+
+    Args:
+        data: Either a dictionary with string keys, or a sequence of such dictionaries
+
+    Returns:
+        A deep copy where all string values are truncated to 30 characters
+    """
+
+    def truncate_string(value):
+        """Truncate string to 30 chars, preserve other types"""
+        if isinstance(value, str) and len(value) > 30:
+            return value[:30] + "..."
+        return value
+
+    def copy_dict(d):
+        """Recursively copy a dictionary, truncating strings"""
+        result = {}
+        for key, value in d.items():
+            if isinstance(value, dict):
+                result[key] = copy_dict(value)
+            elif isinstance(value, Sequence) and not isinstance(value, str):
+                result[key] = [
+                    copy_dict(item) if isinstance(item, dict) else truncate_string(item) for item in value[:20]
+                ]  # Limit to first 20 items
+            else:
+                result[key] = truncate_string(value)
+        return result
+
+    # Handle the two main cases
+    if isinstance(data, dict):
+        return copy_dict(data)
+    elif isinstance(data, Sequence) and not isinstance(data, str):
+        return [
+            copy_dict(item) if isinstance(item, dict) else truncate_string(item) for item in data[:20]
+        ]  # Limit to first 20 items
+    else:
+        # For completeness, handle other types
+        return truncate_string(data)
+
+
+def get_message_text(msg: BaseMessage) -> str:
+    """Get the text content of a message."""
+    content = msg.content
+    if isinstance(content, str):
+        return content
+    elif isinstance(content, dict):
+        return content.get("text", "")
+    else:
+        txts = [c if isinstance(c, str) else (c.get("text") or "") for c in content]
+        return "".join(txts).strip()
+
+
+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 filter_retry_on(exc: Exception) -> bool:
+    import httpx
+    import requests
+
+    if isinstance(
+        exc,
+        (
+            ConnectionError,
+            JSONDecodeError,
+            ValidationError,
+        ),
+    ):
+        return True
+    if isinstance(
+        exc,
+        (
+            ValueError,
+            TypeError,
+            ArithmeticError,
+            ImportError,
+            LookupError,
+            NameError,
+            SyntaxError,
+            RuntimeError,
+            ReferenceError,
+            StopIteration,
+            StopAsyncIteration,
+            OSError,
+        ),
+    ):
+        return False
+    if isinstance(exc, httpx.HTTPStatusError):
+        return 500 <= exc.response.status_code < 600
+    if isinstance(exc, requests.HTTPError):
+        return 500 <= exc.response.status_code < 600 if exc.response else True
+    return True
+
+
+def derive_context(code: str, context: dict[str, Any]) -> dict[str, Any]:
+    """
+    Derive context from code by extracting classes, functions, and import statements.
+
+    Args:
+        code: Python code as a string
+        context: Existing context dictionary to append to
+
+    Returns:
+        Updated context dictionary with extracted entities
+    """
+    import ast
+    import re
+
+    # Initialize context keys if they don't exist
+    if "imports" not in context:
+        context["imports"] = []
+    if "classes" not in context:
+        context["classes"] = []
+    if "functions" not in context:
+        context["functions"] = []
+
+    try:
+        # Parse the code into an AST
+        tree = ast.parse(code)
+
+        # Extract imports
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    if alias.asname:
+                        import_stmt = f"import {alias.name} as {alias.asname}"
+                    else:
+                        import_stmt = f"import {alias.name}"
+                    if import_stmt not in context["imports"]:
+                        context["imports"].append(import_stmt)
+
+            elif isinstance(node, ast.ImportFrom):
+                module = node.module or ""
+                # Handle multiple imports in a single from statement
+                import_names = []
+                for alias in node.names:
+                    if alias.asname:
+                        import_names.append(f"{alias.name} as {alias.asname}")
+                    else:
+                        import_names.append(alias.name)
+
+                import_stmt = f"from {module} import {', '.join(import_names)}"
+                if import_stmt not in context["imports"]:
+                    context["imports"].append(import_stmt)
+
+        # Extract class definitions
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ClassDef):
+                # Get the class definition as a string
+                class_lines = code.split("\n")[node.lineno - 1 : node.end_lineno]
+                class_def = "\n".join(class_lines)
+
+                # Clean up the class definition (remove leading/trailing whitespace)
+                class_def = class_def.strip()
+
+                if class_def not in context["classes"]:
+                    context["classes"].append(class_def)
+
+        # Extract function definitions (only top-level functions, not class methods)
+        for node in ast.walk(tree):
+            if isinstance(node, ast.FunctionDef):
+                # Get the function definition as a string
+                func_lines = code.split("\n")[node.lineno - 1 : node.end_lineno]
+                func_def = "\n".join(func_lines)
+
+                # Check if this is a top-level function by looking at indentation
+                # Top-level functions should start at column 0 (no indentation)
+                if node.col_offset == 0:
+                    # Clean up the function definition (remove leading/trailing whitespace)
+                    func_def = func_def.strip()
+
+                    if func_def not in context["functions"]:
+                        context["functions"].append(func_def)
+
+    except SyntaxError:
+        # If the code has syntax errors, try a simpler regex-based approach
+
+        # Extract import statements using regex
+        import_patterns = [
+            r"import\s+(\w+(?:\.\w+)*)(?:\s+as\s+(\w+))?",
+            r"from\s+(\w+(?:\.\w+)*)\s+import\s+(\w+(?:\s+as\s+\w+)?)",
+        ]
+
+        for pattern in import_patterns:
+            matches = re.finditer(pattern, code)
+            for match in matches:
+                if "from" in pattern:
+                    module = match.group(1)
+                    imports = match.group(2).split(",")
+                    for imp in imports:
+                        imp = imp.strip()
+                        if " as " in imp:
+                            name, alias = imp.split(" as ")
+                            import_stmt = f"from {module} import {name.strip()} as {alias.strip()}"
+                        else:
+                            import_stmt = f"from {module} import {imp}"
+                        if import_stmt not in context["imports"]:
+                            context["imports"].append(import_stmt)
+                else:
+                    module = match.group(1)
+                    alias = match.group(2)
+                    if alias:
+                        import_stmt = f"import {module} as {alias}"
+                    else:
+                        import_stmt = f"import {module}"
+                    if import_stmt not in context["imports"]:
+                        context["imports"].append(import_stmt)
+
+        # Extract class definitions using regex
+        class_pattern = r"class\s+(\w+).*?(?=class\s+\w+|def\s+\w+|$)"
+        class_matches = re.finditer(class_pattern, code, re.DOTALL)
+        for match in class_matches:
+            class_def = match.group(0).strip()
+            if class_def not in context["classes"]:
+                context["classes"].append(class_def)
+
+        # Extract function definitions using regex
+        func_pattern = r"def\s+(\w+).*?(?=class\s+\w+|def\s+\w+|$)"
+        func_matches = re.finditer(func_pattern, code, re.DOTALL)
+        for match in func_matches:
+            func_def = match.group(0).strip()
+            if func_def not in context["functions"]:
+                context["functions"].append(func_def)
+
+    return context
+
+
+def inject_context(
+    context_dict: dict[str, list[str]], existing_namespace: dict[str, Any] | None = None
+) -> dict[str, Any]:
+    """
+    Inject Python entities from a dictionary into a namespace.
+
+    This function takes a dictionary where keys represent entity types (imports, classes, functions, etc.)
+    and values are lists of entity definitions. It attempts to import or create these entities and returns
+    them in a namespace dictionary. Can optionally build upon an existing namespace and apply additional aliases.
+
+    Args:
+        context_dict: Dictionary with entity types as keys and lists of entity definitions as values.
+                     Supported keys: 'imports', 'classes', 'functions'
+                     - 'imports': List of import statements as strings (e.g., ['import pandas', 'import numpy as np'])
+                     - 'classes': List of class definitions as strings
+                     - 'functions': List of function definitions as strings
+        existing_namespace: Optional existing namespace to build upon. If provided, new entities
+                          will be added to this namespace rather than creating a new one.
+
+    Returns:
+        Dictionary containing the injected entities as key-value pairs
+
+    Example:
+        context = {
+            'imports': ['import pandas as pd', 'import numpy as np'],
+            'classes': ['class MyClass:\n    def __init__(self, x):\n        self.x = x'],
+            'functions': ['def my_function(x):\n    return x * 2']
+        }
+        existing_ns = {'math': <math module>, 'data': [1, 2, 3]}
+        namespace = inject_context(context, existing_ns)
+        # namespace will contain: {'math': <math module>, 'data': [1, 2, 3], 'pandas': <module>, 'pd': <module>, 'numpy': <module>, 'np': <module>, 'MyClass': <class>, 'MC': <class>, 'my_function': <function>, ...}
+    """
+    import importlib
+    from typing import Any
+
+    # Start with existing namespace or create new one
+    namespace: dict[str, Any] = existing_namespace.copy() if existing_namespace is not None else {}
+
+    # Handle imports (execute import statements as strings)
+    if "imports" in context_dict:
+        for import_statement in context_dict["imports"]:
+            try:
+                # Execute the import statement in the current namespace
+                exec(import_statement, namespace)
+            except Exception as e:
+                # If execution fails, try to extract module name and create placeholder
+                import re
+
+                # Handle different import patterns
+                import_match = re.search(r"import\s+(\w+)(?:\s+as\s+(\w+))?", import_statement)
+                if import_match:
+                    module_name = import_match.group(1)
+                    alias_name = import_match.group(2)
+
+                    try:
+                        # Try to import the module manually
+                        module = importlib.import_module(module_name)
+                        namespace[module_name] = module
+                        if alias_name:
+                            namespace[alias_name] = module
+                    except ImportError:
+                        # Create placeholders for missing imports
+                        namespace[module_name] = f"<import '{module_name}' not available>"
+                        if alias_name:
+                            namespace[alias_name] = f"<import '{module_name}' as '{alias_name}' not available>"
+                else:
+                    # If we can't parse the import statement, create a generic placeholder
+                    namespace[f"import_{len(namespace)}"] = f"<import statement failed: {str(e)}>"
+
+    # Handle classes - execute class definitions as strings
+    if "classes" in context_dict:
+        for class_definition in context_dict["classes"]:
+            try:
+                # Execute the class definition in the current namespace
+                exec(class_definition, namespace)
+            except Exception:
+                # If execution fails, try to extract class name and create placeholder
+                import re
+
+                class_match = re.search(r"class\s+(\w+)", class_definition)
+                if class_match:
+                    class_name = class_match.group(1)
+
+                    # Create a placeholder class
+                    class PlaceholderClass:
+                        def __init__(self, *args, **kwargs):
+                            raise NotImplementedError(f"Class '{class_name}' failed to load: {str(e)}")
+
+                    namespace[class_name] = PlaceholderClass
+                else:
+                    # If we can't extract class name, create a generic placeholder
+                    class GenericPlaceholderClass:
+                        def __init__(self, *args, **kwargs):
+                            raise NotImplementedError(f"Class definition failed to load: {str(e)}")
+
+                    namespace[f"class_{len(namespace)}"] = GenericPlaceholderClass
+
+    # Handle functions - execute function definitions as strings
+    if "functions" in context_dict:
+        for function_definition in context_dict["functions"]:
+            try:
+                # Execute the function definition in the current namespace
+                exec(function_definition, namespace)
+            except Exception:
+                # If execution fails, try to extract function name and create placeholder
+                import re
+
+                func_match = re.search(r"def\s+(\w+)", function_definition)
+                if func_match:
+                    func_name = func_match.group(1)
+
+                    # Create a placeholder function
+                    def placeholder_func(*args, **kwargs):
+                        raise NotImplementedError(f"Function '{func_name}' failed to load: {str(e)}")
+
+                    placeholder_func.__name__ = func_name
+                    namespace[func_name] = placeholder_func
+                else:
+                    # If we can't extract function name, create a generic placeholder
+                    def generic_placeholder_func(*args, **kwargs):
+                        raise NotImplementedError(f"Function definition failed to load: {str(e)}")
+
+                    generic_placeholder_func.__name__ = f"func_{len(namespace)}"
+                    namespace[generic_placeholder_func.__name__] = generic_placeholder_func
+
+    return namespace

universal_mcp/agents/hil.py

@@ -74,7 +74,7 @@ def handle_interrupt(interrupt: Interrupt) -> str | bool:
 
 class HilAgent(BaseAgent):
     def __init__(self, name: str, instructions: str, model: str):
-        super().__init__(name, instructions, model)
+        super().__init__(name=name, instructions=instructions, model=model)
         self.llm = load_chat_model(model)
         self._graph = self._build_graph()
 
@@ -103,9 +103,9 @@ if __name__ == "__main__":
     import asyncio
 
     agent = HilAgent(
-        "Hil Agent",
-        "You are a friendly agent that asks for the user's name and greets them.",
-        "openrouter/auto",
+        name="Hil Agent",
+        instructions="You are a friendly agent that asks for the user's name and greets them.",
+        model="openrouter/auto",
     )
 
     asyncio.run(agent.run_interactive())

universal_mcp/agents/planner/__init__.py

@@ -20,7 +20,13 @@ class PlannerAgent(BaseAgent):
         executor_agent_cls: type[BaseAgent] = ReactAgent,
         **kwargs,
     ):
-        super().__init__(name, instructions, model, memory, **kwargs)
+        super().__init__(
+            name=name,
+            instructions=instructions,
+            model=model,
+            memory=memory,
+            **kwargs,
+        )
         self.app_registry = registry
         self.llm = load_chat_model(model)
         self.executor_agent_cls = executor_agent_cls

universal_mcp/agents/react.py

@@ -1,10 +1,10 @@
 from langgraph.checkpoint.base import BaseCheckpointSaver
 from langgraph.prebuilt import create_react_agent
 from loguru import logger
+from rich import print
 from universal_mcp.agentr.registry import AgentrRegistry
 from universal_mcp.tools.registry import ToolRegistry
 from universal_mcp.types import ToolConfig, ToolFormat
-from rich import print
 
 from universal_mcp.agents.base import BaseAgent
 from universal_mcp.agents.llm import load_chat_model
@@ -37,7 +37,13 @@ class ReactAgent(BaseAgent):
         max_iterations: int = 10,
         **kwargs,
     ):
-        super().__init__(name, instructions, model, memory, **kwargs)
+        super().__init__(
+            name=name,
+            instructions=instructions,
+            model=model,
+            memory=memory,
+            **kwargs,
+        )
         self.llm = load_chat_model(model)
         self.tools = tools or {}
         if "ui" not in self.tools:
@@ -52,6 +58,8 @@ class ReactAgent(BaseAgent):
                 "http_delete",
                 "http_patch",
                 "read_file",
+                "web_search",
+                "web_content",
             ]
         self.max_iterations = max_iterations
         self.registry = registry
@@ -80,7 +88,7 @@ class ReactAgent(BaseAgent):
 
 async def main():
     agent = ReactAgent(
-        "Universal React Agent",
+        name="Universal React Agent",
         instructions="Be very concise in your answers.",
         model="azure/gpt-4o",
         tools={"google-mail": ["send_email"]},

universal_mcp/agents/simple.py

@@ -32,7 +32,13 @@ class SimpleAgent(BaseAgent):
         memory: BaseCheckpointSaver = None,
         **kwargs,
     ):
-        super().__init__(name, instructions, model, memory, **kwargs)
+        super().__init__(
+            name=name,
+            instructions=instructions,
+            model=model,
+            memory=memory,
+            **kwargs,
+        )
         self.llm = load_chat_model(model)
 
     def _build_system_message(self):
@@ -55,7 +61,11 @@ class SimpleAgent(BaseAgent):
 
 
 async def main():
-    agent = SimpleAgent("Simple Agent", "Act as a 14 year old kid, reply in Gen-Z lingo", "azure/gpt-5-mini")
+    agent = SimpleAgent(
+        name="Simple Agent",
+        instructions="Act as a 14 year old kid, reply in Gen-Z lingo",
+        model="azure/gpt-5-mini",
+    )
     output = await agent.invoke("What is the capital of France?")
     print(messages_to_list(output["messages"]))
 

universal_mcp/agents/utils.py

@@ -2,6 +2,7 @@ import json
 from contextlib import contextmanager
 
 from langchain_core.messages.base import BaseMessage
+from loguru import logger
 from rich.console import Console
 from rich.live import Live
 from rich.markdown import Markdown
@@ -126,3 +127,19 @@ Available commands:
 
 def messages_to_list(messages: list[BaseMessage]):
     return [{"type": message.type, "content": message.content} for message in messages]
+
+
+def get_message_text(message: BaseMessage):
+    try:
+        if isinstance(message.content, str):
+            return message.content
+        elif isinstance(message.content, dict):
+            return message.content.get("text", "")
+        elif isinstance(message.content, list):
+            return " ".join([c.get("text", "") for c in message.content])
+        else:
+            return ""
+    except Exception as e:
+        logger.error(f"Error getting message text: {e}")
+        logger.error(f"Message: {message}")
+        raise e

universal_mcp/applications/llm/__init__.py

@@ -0,0 +1,3 @@
+from .app import LLMApp
+
+__all__ = ["LLMApp"]

universal_mcp/applications/llm/app.py

@@ -0,0 +1,158 @@
+import json
+from typing import Any, Literal, cast
+
+from langchain.chat_models import init_chat_model
+from langchain_openai import AzureChatOpenAI
+from pydantic import BaseModel, Field
+from universal_mcp.applications.application import BaseApplication
+
+MAX_RETRIES = 3
+
+
+def _get_context_as_string(source: Any | list[Any] | dict[str, Any]) -> str:
+    """Converts context to a string representation.
+
+    Args:
+        source: The source data to be converted. Can be a single value, a list of values, or a dictionary.
+
+    Returns:
+        A string representation of the source data, formatted with XML-like tags for dictionaries.
+    """
+
+    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())
+
+
+class LLMApp(BaseApplication):
+    """
+    An application for leveraging Large Language Models (LLMs) for advanced text processing tasks.
+    """
+
+    def __init__(self, **kwargs):
+        """Initialize the LLMApp."""
+        super().__init__(name="llm")
+
+    def generate_text(
+        self,
+        task: str,
+        context: Any | list[Any] | dict[str, Any],
+        tone: str = "normal",
+        output_format: Literal["markdown", "html", "plain"] = "markdown",
+        length: Literal["very-short", "concise", "normal", "long"] = "concise",
+    ) -> str:
+        """
+        Generates well-written text for a high-level task using the provided context.
+
+        Use this function for creative writing, summarization, and other text generation tasks.
+
+        Args:
+            task: The main writing task or directive.
+            context: A single string, list of strings, or dictionary mapping labels to content.
+            tone: The desired tone of the output (e.g., "formal", "casual", "technical").
+            output_format: The desired output format ('markdown', 'html', 'plain').
+            length: The desired length of the output ('very-short', 'concise', 'normal', 'long').
+
+        Returns:
+            The generated text as a string.
+        """
+        context_str = _get_context_as_string(context)
+
+        prompt = f"{task.strip()}\n\n"
+        if output_format == "markdown":
+            prompt += "Please write in Markdown format.\n\n"
+        elif output_format == "html":
+            prompt += "Please write in HTML format.\n\n"
+        else:
+            prompt += "Please write in plain text format. Do not use markdown or HTML.\n\n"
+
+        if tone not in ["normal", "default", ""]:
+            prompt = f"{prompt} (Tone instructions: {tone})"
+
+        if length not in ["normal", "default", ""]:
+            prompt = f"{prompt} (Length instructions: {length})"
+
+        full_prompt = f"{prompt}\n\nContext:\n{context_str}\n\n"
+
+        model = AzureChatOpenAI(model="gpt-4o", temperature=0.7)
+        response = model.with_retry(stop_after_attempt=MAX_RETRIES).invoke(full_prompt)
+        return str(response.content)
+
+    def classify_data(
+        self,
+        task: str,
+        context: Any | list[Any] | dict[str, Any],
+        class_descriptions: dict[str, str],
+    ) -> dict[str, Any]:
+        """
+        Classifies data into one of several categories based on a given task and context.
+
+        Args:
+            task: The classification question and any specific rules or requirements.
+            context: The data to be classified, provided as a string, list, or dictionary.
+            class_descriptions: A dictionary mapping class names to their descriptions.
+
+        Returns:
+            A dictionary containing the classification probabilities, the reasoning, and the top class.
+        """
+        context_str = _get_context_as_string(context)
+
+        prompt = (
+            f"{task}\n\n"
+            f"This is a classification task.\nPossible classes and descriptions:\n"
+            f"{json.dumps(class_descriptions, indent=2)}\n\n"
+            f"Context:\n{context_str}\n\n"
+            "Return ONLY a valid JSON object, no extra text."
+        )
+
+        model = init_chat_model(model="claude-4-sonnet-20250514", temperature=0)
+
+        class ClassificationResult(BaseModel):
+            probabilities: dict[str, float] = Field(..., description="The probabilities for each class.")
+            reason: str = Field(..., description="The reasoning behind the classification.")
+            top_class: str = Field(..., description="The class with the highest probability.")
+
+        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 extract_data(
+        self,
+        task: str,
+        source: Any | list[Any] | dict[str, Any],
+        output_schema: dict[str, Any],
+    ) -> dict[str, Any]:
+        """
+        Extracts structured data from unstructured text based on a provided JSON schema.
+
+        Args:
+            task: A description of the data to be extracted.
+            source: The unstructured data to extract from (e.g., document, webpage content).
+            output_schema: A valid JSON schema with a 'title' and 'description'.
+
+        Returns:
+            A dictionary containing the extracted data, matching the provided schema.
+        """
+        context_str = _get_context_as_string(source)
+
+        prompt = (
+            f"{task}\n\n"
+            f"Context:\n{context_str}\n\n"
+            "Return ONLY a valid JSON object that conforms to the provided schema, with no extra text."
+        )
+
+        model = init_chat_model(model="claude-4-sonnet-20250514", temperature=0)
+
+        response = (
+            model.with_structured_output(schema=output_schema, method="json_mode")
+            .with_retry(stop_after_attempt=MAX_RETRIES)
+            .invoke(prompt)
+        )
+        return cast(dict[str, Any], response)