universal-mcp 0.1.24rc2__py3-none-any.whl → 0.1.24rc3__py3-none-any.whl

universal_mcp/agents/codeact/__init__.py

@@ -0,0 +1,243 @@
+import inspect
+import re
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Any, TypeVar
+
+from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import StructuredTool
+from langchain_core.tools import tool as create_tool
+from langgraph.graph import END, START, MessagesState, StateGraph
+from langgraph.types import Command
+
+from .utils import extract_and_combine_codeblocks
+
+EvalFunction = Callable[[str, dict[str, Any]], tuple[str, dict[str, Any]]]
+EvalCoroutine = Callable[[str, dict[str, Any]], Awaitable[tuple[str, dict[str, Any]]]]
+
+
+class CodeActState(MessagesState):
+    """State for CodeAct agent."""
+
+    script: str | None
+    """The Python code script to be executed."""
+    context: dict[str, Any]
+    """Dictionary containing the execution context with available tools and variables."""
+
+
+StateSchema = TypeVar("StateSchema", bound=CodeActState)
+StateSchemaType = type[StateSchema]
+
+
+def make_safe_function_name(name: str) -> str:
+    """Convert a tool name to a valid Python function name."""
+    # Replace non-alphanumeric characters with underscores
+    safe_name = re.sub(r"[^a-zA-Z0-9_]", "_", name)
+    # Ensure the name doesn't start with a digit
+    if safe_name and safe_name[0].isdigit():
+        safe_name = f"tool_{safe_name}"
+    # Handle empty name edge case
+    if not safe_name:
+        safe_name = "unnamed_tool"
+    return safe_name
+
+
+def create_default_prompt(tools: list[StructuredTool], base_prompt: str | None = None):
+    """Create default prompt for the CodeAct agent."""
+    tools = [t if isinstance(t, StructuredTool) else create_tool(t) for t in tools]
+    prompt = f"{base_prompt}\n\n" if base_prompt else ""
+    prompt += """You will be given a task to perform. You should output either
+- a Python code snippet that provides the solution to the task, or a step towards the solution. Any output you want to extract from the code should be printed to the console. Code should be output in a fenced code block.
+- text to be shown directly to the user, if you want to ask for more information or provide the final answer.
+
+In addition to the Python Standard Library, you can use the following functions:
+"""
+
+    for tool in tools:
+        # Use coroutine if it exists, otherwise use func
+        tool_callable = tool.coroutine if hasattr(tool, "coroutine") and tool.coroutine is not None else tool.func
+        # Create a safe function name
+        safe_name = make_safe_function_name(tool.name)
+        # Determine if it's an async function
+        is_async = inspect.iscoroutinefunction(tool_callable)
+        # Add appropriate function definition
+        prompt += f'''
+{"async " if is_async else ""}def {safe_name}{str(inspect.signature(tool_callable))}:
+    """{tool.description}"""
+    ...
+'''
+
+    prompt += """
+
+Variables defined at the top level of previous code snippets can be referenced in your code.
+
+Reminder: use Python code snippets to call tools"""
+    return prompt
+
+
+def create_codeact(
+    model: BaseChatModel,
+    tools: Sequence[StructuredTool | Callable],
+    eval_fn: EvalFunction | EvalCoroutine,
+    *,
+    prompt: str | None = None,
+    reflection_prompt: str | None = None,
+    reflection_model: BaseChatModel | None = None,
+    max_reflections: int = 3,
+    state_schema: StateSchemaType = CodeActState,
+) -> StateGraph:
+    """Create a CodeAct agent.
+
+    Args:
+        model: The language model to use for generating code
+        tools: List of tools available to the agent. Can be passed as python functions or StructuredTool instances.
+        eval_fn: Function or coroutine that executes code in a sandbox. Takes code string and locals dict,
+            returns a tuple of (stdout output, new variables dict)
+        prompt: Optional custom system prompt. If None, uses default prompt.
+            To customize default prompt you can use `create_default_prompt` helper:
+            `create_default_prompt(tools, "You are a helpful assistant.")`
+        reflection_prompt: Optional prompt for reflection. If provided, will be used to evaluate responses.
+            If the reflection output contains "NONE", the response is considered valid, otherwise the
+            reflection output is passed back to the model for regeneration.
+        reflection_model: Optional model to use for reflection. If None, uses the same model as for generation.
+        max_reflections: Maximum number of reflection iterations (default: 3).
+        state_schema: The state schema to use for the agent.
+
+    Returns:
+        A StateGraph implementing the CodeAct architecture
+    """
+    tools = [t if isinstance(t, StructuredTool) else create_tool(t) for t in tools]
+
+    if prompt is None:
+        prompt = create_default_prompt(tools)
+
+    # If no reflection model is provided, use the main model
+    if reflection_model is None:
+        reflection_model = model
+
+    # Make tools available to the code sandbox - use safe names for keys
+    tools_context = {}
+    for tool in tools:
+        safe_name = make_safe_function_name(tool.name)
+        # Use coroutine if it exists, otherwise use func (same as in create_default_prompt)
+        tool_callable = tool.coroutine if hasattr(tool, "coroutine") and tool.coroutine is not None else tool.func
+        # Only use the safe name for consistency with the prompt
+        tools_context[safe_name] = tool_callable
+
+    def call_model(state: StateSchema) -> Command:
+        messages = [{"role": "system", "content": prompt}] + state["messages"]
+
+        # Run the model and potentially loop for reflection
+        response = model.invoke(messages)
+
+        # Extract and combine all code blocks
+        code = extract_and_combine_codeblocks(response.content)
+
+        # Loop for reflection if needed and if code is present
+        if reflection_prompt and code:
+            reflection_count = 0
+            while reflection_count < max_reflections:
+                # Format conversation history with XML-style tags
+                conversation_history = "\n".join(
+                    [
+                        f'<message role="{("user" if m.type == "human" else "assistant")}">\n{m.content}\n</message>'
+                        for m in state["messages"]
+                    ]
+                )
+
+                # Add the current response
+                conversation_history += f'\n<message role="assistant">\n{response.content}\n</message>'
+
+                # Create the reflection prompt with the tagged conversation history
+                formatted_prompt = f"""
+Review the assistant's latest code for as per the quality rules:
+
+<conversation_history>
+{conversation_history}
+</conversation_history>
+
+If you find ANY of these issues, describe the problem briefly and clearly.
+If NO issues are found, respond with EXACTLY: "NONE"
+"""
+
+                # Create messages for reflection with correct ordering
+                reflection_messages = [
+                    {"role": "system", "content": reflection_prompt},
+                    # Include the formatted reflection prompt as the final user message
+                    {"role": "user", "content": formatted_prompt},
+                ]
+                reflection_result = reflection_model.invoke(reflection_messages)
+
+                # Check if reflection passed
+                if "NONE" in reflection_result.content:
+                    # Reflection passed, exit loop
+                    break
+
+                # Reflection didn't pass, regenerate response
+                reflection_messages = [
+                    {"role": "system", "content": prompt},
+                    *state["messages"],
+                    {"role": "assistant", "content": response.content},
+                    {
+                        "role": "user",
+                        "content": f"""
+I need you to completely regenerate your previous response based on this feedback:
+
+'''
+{reflection_result.content}
+'''
+
+DO NOT reference the feedback directly. Instead, provide a completely new response that addresses the issues.
+""",
+                    },
+                ]
+                response = model.invoke(reflection_messages)
+
+                # Extract code from the new response
+                code = extract_and_combine_codeblocks(response.content)
+
+                # If no code in the new response, exit the reflection loop
+                if not code:
+                    break
+
+                # Increment reflection count
+                reflection_count += 1
+
+        # Return appropriate command with only the latest response
+        if code:
+            return Command(goto="sandbox", update={"messages": [response], "script": code})
+        else:
+            # no code block, end the loop and respond to the user
+            return Command(update={"messages": [response], "script": None})
+
+    # If eval_fn is a async, we define async node function.
+    if inspect.iscoroutinefunction(eval_fn):
+
+        async def sandbox(state: StateSchema):
+            existing_context = state.get("context", {})
+            context = {**existing_context, **tools_context}
+            # Execute the script in the sandbox
+            output, new_vars = await eval_fn(state["script"], context)
+            new_context = {**existing_context, **new_vars}
+            return {
+                "messages": [{"role": "user", "content": output}],
+                "context": new_context,
+            }
+    else:
+
+        def sandbox(state: StateSchema):
+            existing_context = state.get("context", {})
+            context = {**existing_context, **tools_context}
+            # Execute the script in the sandbox
+            output, new_vars = eval_fn(state["script"], context)
+            new_context = {**existing_context, **new_vars}
+            return {
+                "messages": [{"role": "user", "content": output}],
+                "context": new_context,
+            }
+
+    agent = StateGraph(state_schema)
+    agent.add_node(call_model, destinations=(END, "sandbox"))
+    agent.add_node(sandbox)
+    agent.add_edge(START, "call_model")
+    agent.add_edge("sandbox", "call_model")
+    return agent

universal_mcp/agents/codeact/sandbox.py

@@ -0,0 +1,27 @@
+import builtins
+import contextlib
+import io
+from typing import Any
+
+
+def eval_unsafe(code: str, _locals: dict[str, Any]) -> tuple[str, dict[str, Any]]:
+    # Store original keys before execution
+    original_keys = set(_locals.keys())
+    result = f"Executing code...\n{code}\n\nOutput:\n"
+    result += "=" * 50 + "\n"
+    try:
+        with contextlib.redirect_stdout(io.StringIO()) as f:
+            # Execute the code in the provided locals context
+            # Using exec to allow dynamic code execution
+            # This is a simplified version; in production, consider security implications
+            exec(code, builtins.__dict__, _locals)
+        result += f.getvalue()
+        if not result:
+            result = "<code ran, no output printed to stdout>"
+    except Exception as e:
+        result += f"Error during execution: {repr(e)}"
+
+    # Determine new variables created during execution
+    new_keys = set(_locals.keys()) - original_keys
+    new_vars = {key: _locals[key] for key in new_keys}
+    return result, new_vars

universal_mcp/agents/codeact/test.py

@@ -0,0 +1,15 @@
+from universal_mcp.agentr import Agentr
+from universal_mcp.agents.codeact import create_codeact
+from universal_mcp.agents.codeact.sandbox import eval_unsafe
+from universal_mcp.agents.llm import get_llm
+from universal_mcp.tools.adapters import ToolFormat
+
+model = get_llm("gpt-4.1")
+
+agentr = Agentr()
+agentr.load_tools(["google-mail_send_email"])
+
+tools = agentr.list_tools(format=ToolFormat.NATIVE)
+
+code_act = create_codeact(model, tools, eval_unsafe)
+agent = code_act.compile()

universal_mcp/agents/codeact/utils.py

@@ -0,0 +1,61 @@
+import re
+
+BACKTICK_PATTERN = r"(?:^|\n)```(.*?)(?:```(?:\n|$))"
+
+
+def extract_and_combine_codeblocks(text: str) -> str:
+    """
+    Extracts all codeblocks from a text string and combines them into a single code string.
+
+    Args:
+        text: A string containing zero or more codeblocks, where each codeblock is
+            surrounded by triple backticks (```).
+
+    Returns:
+        A string containing the combined code from all codeblocks, with each codeblock
+        separated by a newline.
+
+    Example:
+        text = '''Here's some code:
+
+        ```python
+        print('hello')
+        ```
+        And more:
+
+        ```
+        print('world')
+        ```'''
+
+        result = extract_and_combine_codeblocks(text)
+
+        Result:
+
+        print('hello')
+
+        print('world')
+    """
+    # Find all code blocks in the text using regex
+    # Pattern matches anything between triple backticks, with or without a language identifier
+    code_blocks = re.findall(BACKTICK_PATTERN, text, re.DOTALL)
+
+    if not code_blocks:
+        return ""
+
+    # Process each codeblock
+    processed_blocks = []
+    for block in code_blocks:
+        # Strip leading and trailing whitespace
+        block = block.strip()
+
+        # If the first line looks like a language identifier, remove it
+        lines = block.split("\n")
+        if lines and (not lines[0].strip() or " " not in lines[0].strip()):
+            # First line is empty or likely a language identifier (no spaces)
+            block = "\n".join(lines[1:])
+
+        processed_blocks.append(block)
+
+    # Combine all codeblocks with newlines between them
+    combined_code = "\n\n".join(processed_blocks)
+    return combined_code

universal_mcp/agents/hil.py

@@ -0,0 +1,104 @@
+from typing import Annotated, TypedDict
+
+from langchain_core.messages import HumanMessage
+from langgraph.constants import END, START
+from langgraph.graph import StateGraph
+from langgraph.graph.message import add_messages
+from langgraph.types import Interrupt, interrupt
+
+from .base import BaseAgent
+from .llm import get_llm
+
+
+class State(TypedDict):
+    messages: Annotated[list, add_messages]
+    name: str | None = None
+    favourite_color: str | None = None
+    human: bool | None = None
+
+
+def ask_name_node(state: State) -> State:
+    if state.get("name") is not None:
+        return state
+    name = interrupt({"question": "What is your name?", "type": "text"})
+    state.update(name=name, messages=[HumanMessage(content=f"My name is {name}")])
+    return state
+
+
+def ask_bool_node(state: State) -> State:
+    if state.get("human") is not None:
+        return state
+    bool = interrupt({"question": "Are you a human?", "type": "bool"})
+
+    if bool:
+        state.update(human=True, messages=[HumanMessage(content="I am human")])
+    else:
+        state.update(human=False, messages=[HumanMessage(content="I am AI agent")])
+    return state
+
+
+def ask_favourite_color_node(state: State) -> State:
+    if state.get("favourite_color") is not None:
+        return state
+    favourite_color = interrupt(
+        {"question": "What is your favourite color?", "type": "choice", "choices": ["red", "green", "blue"]}
+    )
+    state.update(
+        favourite_color=favourite_color, messages=[HumanMessage(content=f"My favourite color is {favourite_color}")]
+    )
+    return state
+
+
+def handle_interrupt(interrupt: Interrupt) -> str | bool:
+    interrupt_type = interrupt.value["type"]
+    if interrupt_type == "text":
+        value = input(interrupt.value["question"])
+        return value
+    elif interrupt_type == "bool":
+        value = input("Do you accept this? (y/n): " + interrupt.value["question"])
+        return value.lower() in ["y", "yes"]
+    elif interrupt_type == "choice":
+        value = input("Enter your choice: " + interrupt.value["question"] + " " + ", ".join(interrupt.value["choices"]))
+        if value in interrupt.value["choices"]:
+            return value
+        else:
+            return interrupt.value["choices"][0]
+    else:
+        raise ValueError(f"Invalid interrupt type: {interrupt.value['type']}")
+
+
+class HilAgent(BaseAgent):
+    def __init__(self, name: str, instructions: str, model: str):
+        super().__init__(name, instructions, model)
+        self.llm = get_llm(model)
+        self._graph = self._build_graph()
+
+    def chatbot(self, state: State):
+        return {"messages": [self.llm.invoke(state["messages"])]}
+
+    def _build_graph(self):
+        graph_builder = StateGraph(State)
+        graph_builder.add_node("ask_name_node", ask_name_node)
+        graph_builder.add_node("ask_bool_node", ask_bool_node)
+        graph_builder.add_node("ask_favourite_color_node", ask_favourite_color_node)
+        graph_builder.add_node("chatbot", self.chatbot)
+        graph_builder.add_edge(START, "ask_name_node")
+        graph_builder.add_edge("ask_name_node", "ask_bool_node")
+        graph_builder.add_edge("ask_bool_node", "ask_favourite_color_node")
+        graph_builder.add_edge("ask_favourite_color_node", "chatbot")
+        graph_builder.add_edge("chatbot", END)
+        return graph_builder.compile(checkpointer=self.memory)
+
+    @property
+    def graph(self):
+        return self._graph
+
+
+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"
+    )
+
+    asyncio.run(agent.run_interactive())

universal_mcp/agents/llm.py

@@ -0,0 +1,10 @@
+from langchain_openai import AzureChatOpenAI
+
+
+def get_llm(model: str, tags: list[str] | None = None):
+    return AzureChatOpenAI(model=model, api_version="2024-12-01-preview", azure_deployment=model, tags=tags)
+
+
+if __name__ == "__main__":
+    llm = get_llm("gpt-4.1")
+    print(llm.invoke("Hello, world!"))

universal_mcp/agents/react.py

@@ -0,0 +1,58 @@
+from langgraph.prebuilt import create_react_agent
+from loguru import logger
+
+from universal_mcp.agentr.registry import AgentrRegistry
+from universal_mcp.tools.adapters import ToolFormat
+from universal_mcp.tools.manager import ToolManager
+
+from .base import BaseAgent
+from .llm import get_llm
+
+
+class ReactAgent(BaseAgent):
+    def __init__(
+        self, name: str, instructions: str, model: str, tools: list[str] | None = None, max_iterations: int = 10
+    ):
+        super().__init__(name, instructions, model)
+        self.llm = get_llm(model)
+        self.max_iterations = max_iterations
+        self.tool_manager = ToolManager()
+        registry = AgentrRegistry()
+        if tools:
+            registry.load_tools(tools, self.tool_manager)
+        logger.debug(f"Initialized ReactAgent: name={name}, model={model}")
+        self._graph = self._build_graph()
+
+    @property
+    def graph(self):
+        return self._graph
+
+    def _build_graph(self):
+        tools = self.tool_manager.list_tools(format=ToolFormat.LANGCHAIN) if self.tool_manager else []
+        return create_react_agent(
+            self.llm,
+            tools,
+            prompt=self._build_system_message(),
+            checkpointer=self.memory,
+        )
+
+    def _build_system_message(self) -> str:
+        system_message = f"""You are {self.name}. {self.instructions}
+
+You have access to various tools that can help you answer questions and complete tasks. When you need to use a tool:
+
+1. Think about what information you need
+2. Call the appropriate tool with the right parameters
+3. Use the tool results to provide a comprehensive answer
+
+Always explain your reasoning and be thorough in your responses. If you need to use multiple tools to answer a question completely, do so."""
+        return system_message
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    agent = ReactAgent(
+        "Universal React Agent", "You are a helpful assistant", "gpt-4.1", tools=["google-mail_send_email"]
+    )
+    asyncio.run(agent.run_interactive())

universal_mcp/agents/simple.py

@@ -0,0 +1,40 @@
+import asyncio
+from typing import Annotated
+
+from langgraph.graph import END, START, StateGraph
+from langgraph.graph.message import add_messages
+from typing_extensions import TypedDict
+
+from .base import BaseAgent
+from .llm import get_llm
+
+
+class State(TypedDict):
+    messages: Annotated[list, add_messages]
+
+
+class SimpleAgent(BaseAgent):
+    def __init__(self, name: str, instructions: str, model: str):
+        super().__init__(name, instructions, model)
+        self.llm = get_llm(model)
+        self._graph = self._build_graph()
+
+    def _build_graph(self):
+        graph_builder = StateGraph(State)
+
+        def chatbot(state: State):
+            return {"messages": [self.llm.invoke(state["messages"])]}
+
+        graph_builder.add_node("chatbot", chatbot)
+        graph_builder.add_edge(START, "chatbot")
+        graph_builder.add_edge("chatbot", END)
+        return graph_builder.compile(checkpointer=self.memory)
+
+    @property
+    def graph(self):
+        return self._graph
+
+
+if __name__ == "__main__":
+    agent = SimpleAgent("Simple Agent", "You are a helpful assistant", "openrouter/auto")
+    asyncio.run(agent.run_interactive())

universal_mcp/agents/utils.py

@@ -0,0 +1,111 @@
+import json
+from contextlib import contextmanager
+
+from rich.console import Console
+from rich.live import Live
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.prompt import Prompt
+from rich.table import Table
+
+
+class RichCLI:
+    def __init__(self):
+        self.console = Console()
+
+    def display_welcome(self, agent_name: str):
+        """Display welcome message"""
+        welcome_text = f"""
+# Welcome to {agent_name}!
+
+Available commands:
+- Type your questions naturally
+- `/help` - Show help
+- `/tools` - List available tools
+- `/exit` - Exit the application
+        """
+        self.console.print(Panel(Markdown(welcome_text), title="🤖 AI Agent CLI", border_style="blue"))
+
+    def display_agent_response(self, response: str, agent_name: str):
+        """Display agent response with formatting"""
+        self.console.print(Panel(Markdown(response), title=f"🤖 {agent_name}", border_style="green", padding=(1, 2)))
+
+    @contextmanager
+    def display_agent_response_streaming(self, agent_name: str):
+        """Context manager for streaming agent response updates."""
+
+        with Live(refresh_per_second=10, console=self.console) as live:
+
+            class StreamUpdater:
+                content = []
+
+                def update(self, chunk: str):
+                    self.content.append(chunk)
+                    panel = Panel(
+                        Markdown("".join(self.content)),
+                        title=f"🤖 {agent_name}",
+                        border_style="green",
+                        padding=(1, 2),
+                    )
+                    live.update(panel)
+
+            yield StreamUpdater()
+
+    def display_thinking(self, thought: str):
+        """Display agent's thinking process"""
+        if thought:
+            self.console.print(Panel(thought, title="💭 Thinking", border_style="yellow", padding=(1, 2)))
+
+    def display_tools(self, tools: list):
+        """Display available tools in a table"""
+        table = Table(title="🛠️ Available Tools")
+        table.add_column("Tool Name", style="cyan")
+        table.add_column("Description", style="white")
+
+        for tool in tools:
+            func_info = tool["function"]
+            table.add_row(func_info["name"], func_info["description"])
+
+        self.console.print(table)
+
+    def display_tool_call(self, tool_call: dict):
+        """Display tool call"""
+        tool_call_str = json.dumps(tool_call, indent=2)
+        self.console.print(Panel(tool_call_str, title="🛠️ Tool Call", border_style="green", padding=(1, 2)))
+
+    def display_tool_result(self, tool_result: dict):
+        """Display tool result"""
+        tool_result_str = json.dumps(tool_result, indent=2)
+        self.console.print(Panel(tool_result_str, title="🛠️ Tool Result", border_style="green", padding=(1, 2)))
+
+    def display_error(self, error: str):
+        """Display error message"""
+        self.console.print(Panel(error, title="❌ Error", border_style="red"))
+
+    def get_user_input(self) -> str:
+        """Get user input with rich prompt"""
+        return Prompt.ask("[bold blue]You[/bold blue]", console=self.console)
+
+    def display_info(self, message: str):
+        """Display info message"""
+        self.console.print(f"[bold cyan]ℹ️ {message}[/bold cyan]")
+
+    def clear_screen(self):
+        """Clear the screen"""
+        self.console.clear()
+
+    def handle_interrupt(self, interrupt) -> str | bool:
+        interrupt_type = interrupt.value["type"]
+        if interrupt_type == "text":
+            value = Prompt.ask(interrupt.value["question"])
+            return value
+        elif interrupt_type == "bool":
+            value = Prompt.ask(interrupt.value["question"], choices=["y", "n"], default="y")
+            return value
+        elif interrupt_type == "choice":
+            value = Prompt.ask(
+                interrupt.value["question"], choices=interrupt.value["choices"], default=interrupt.value["choices"][0]
+            )
+            return value
+        else:
+            raise ValueError(f"Invalid interrupt type: {interrupt.value['type']}")