modus-ai 0.1.0__py3-none-any.whl

modus/__init__.py

@@ -0,0 +1,3 @@
+from modus.agent import Agent
+
+__all__ = ["Agent"]

modus/actions/__init__.py

@@ -0,0 +1,12 @@
+from modus.actions.base import Actions
+from modus.actions.local import EchoTool, FunctionTool, tool
+from modus.actions.registry import LocalToolRegistry, ToolRegistry
+
+__all__ = [
+    "Actions",
+    "EchoTool",
+    "FunctionTool",
+    "LocalToolRegistry",
+    "ToolRegistry",
+    "tool",
+]

modus/actions/base.py

@@ -0,0 +1,145 @@
+import hashlib
+import json
+import logging
+import time
+from collections.abc import Callable
+from typing import Any
+
+from modus.actions.compaction import compact_result
+from modus.actions.mcp.client import MCPClientManager
+from modus.actions.registry import ToolRegistry
+from modus.core.protocols import Tool
+from modus.core.types import ToolDefinition
+
+logger = logging.getLogger(__name__)
+
+
+def _validate_args(parameters: dict[str, Any] | None, args: dict[str, Any]) -> None:
+    if not parameters:
+        return
+    required = parameters.get("required", [])
+    missing = [field for field in required if field not in args]
+    if missing:
+        raise ValueError(f"Missing required arguments: {', '.join(missing)}")
+
+
+def _normalize_result(result: Any) -> str:
+    if isinstance(result, str):
+        return result
+    return json.dumps(result, default=str)
+
+
+class Actions:
+    def __init__(
+        self,
+        on_tool_call: Callable[[str, dict[str, Any]], None] | None = None,
+        on_approval: Callable[[str, dict[str, Any]], bool] | None = None,
+    ) -> None:
+        self._registry = ToolRegistry()
+        self._mcp = MCPClientManager()
+        self._cache: dict[str, dict[str, Any]] = {}
+        self._on_tool_call = on_tool_call
+        self._on_approval = on_approval
+        self._middleware: list[Callable] = []
+
+    def use(self, middleware_fn: Callable) -> None:
+        self._middleware.append(middleware_fn)
+
+    def register(self, tool: Tool) -> None:
+        self._registry.register(tool)
+
+    def connect(
+        self,
+        server: str,
+        *,
+        command: str | None = None,
+        args: list[str] | None = None,
+        url: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._mcp.connect(
+            server,
+            command=command,
+            args=args,
+            url=url,
+            **kwargs,
+        )
+
+    def list_tools(self) -> list[ToolDefinition]:
+        tools = self._registry.list_tools()
+        tools.extend(self._mcp.list_tools())
+        return tools
+
+    def to_openai_schemas(self) -> list[dict[str, Any]]:
+        return self._registry.to_openai_schemas()
+
+    def to_anthropic_schemas(self) -> list[dict[str, Any]]:
+        return self._registry.to_anthropic_schemas()
+
+    def execute(
+        self,
+        tool_name: str,
+        args: dict[str, Any],
+        timeout: int = 30,
+        retry: int = 2,
+    ) -> dict[str, Any]:
+        if self._on_tool_call:
+            self._on_tool_call(tool_name, args)
+
+        cache_key = _cache_key(tool_name, args)
+        if cache_key in self._cache:
+            return self._cache[cache_key]
+
+        for attempt in range(retry + 1):
+            try:
+                result = self._execute_once(tool_name, args, timeout)
+                self._cache[cache_key] = result
+                return result
+            except Exception as exc:
+                if attempt == retry:
+                    return {"content": str(exc), "is_error": True}
+                time.sleep(0.5 * (attempt + 1))
+
+        return {"content": "Unexpected error", "is_error": True}
+
+    def _execute_once(self, tool_name: str, args: dict[str, Any], timeout: int) -> dict[str, Any]:
+        if self._registry.has(tool_name):
+            tool = self._registry.get(tool_name)
+
+            # Authorization check
+            require_approval = getattr(tool, "require_approval", False)
+            if require_approval and self._on_approval is not None:
+                approved = self._on_approval(tool_name, args)
+                if not approved:
+                    logger.info("Tool '%s' rejected by approval callback", tool_name)
+                    return {"content": f"Tool '{tool_name}' execution rejected", "is_error": True}
+
+            _validate_args(tool.parameters, args)
+
+            # Middleware chain
+            def call():
+                return tool.execute(**args)
+            for mw in reversed(self._middleware):
+                call = mw(call)
+            raw = call()
+
+            content = compact_result(_normalize_result(raw))
+            return {"content": content, "is_error": False}
+
+        if self._mcp.has_tool(tool_name):
+            raw = self._mcp.execute(tool_name, args, timeout=timeout)
+            content = compact_result(_normalize_result(raw))
+            return {"content": content, "is_error": False}
+
+        return {
+            "content": f"Unknown tool: {tool_name}",
+            "is_error": True,
+        }
+
+    def clear_cache(self) -> None:
+        self._cache.clear()
+
+
+def _cache_key(tool_name: str, args: dict[str, Any]) -> str:
+    raw = f"{tool_name}:{json.dumps(args, sort_keys=True)}"
+    return hashlib.sha256(raw.encode()).hexdigest()

modus/actions/compaction.py

@@ -0,0 +1,12 @@
+def compact_result(
+    content: str,
+    *,
+    max_chars: int = 12_000,
+) -> str:
+    """Shrink oversized tool output before returning it to the LLM."""
+    if len(content) <= max_chars:
+        return content
+    truncated = max_chars - 20
+    truncated = max(truncated, 0)
+    removed = len(content) - truncated
+    return f"{content[:truncated]}\n...[truncated {removed} chars]"

modus/actions/local.py

@@ -0,0 +1,47 @@
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class FunctionTool:
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    _fn: Callable[..., str] = field(repr=False)
+    require_approval: bool = False
+
+    def execute(self, **kwargs: Any) -> str:
+        return self._fn(**kwargs)
+
+
+def tool(
+    name: str,
+    description: str,
+    parameters: dict[str, Any],
+    require_approval: bool = False,
+) -> Callable[[Callable[..., str]], FunctionTool]:
+    def decorator(fn: Callable[..., str]) -> FunctionTool:
+        return FunctionTool(
+            name=name,
+            description=description,
+            parameters=parameters,
+            require_approval=require_approval,
+            _fn=fn,
+        )
+
+    return decorator
+
+
+class EchoTool:
+    name = "echo"
+    description = "Echo back the input message"
+    parameters = {
+        "type": "object",
+        "properties": {"message": {"type": "string"}},
+        "required": ["message"],
+    }
+    require_approval = False
+
+    def execute(self, *, message: str) -> str:
+        return message

modus/actions/mcp/__init__.py

@@ -0,0 +1,3 @@
+from modus.actions.mcp.client import MCPClientManager
+
+__all__ = ["MCPClientManager"]

modus/actions/mcp/_stdio.py

@@ -0,0 +1,79 @@
+import json
+import logging
+import subprocess
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class MCPStdioServer:
+    def __init__(self, command: str, args: list[str] | None = None) -> None:
+        self._command = command
+        self._args = args or []
+        self._process: subprocess.Popen | None = None
+
+    def start(self) -> None:
+        self._process = subprocess.Popen(
+            [self._command, *self._args],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+
+    def send(self, request: dict[str, Any]) -> dict[str, Any]:
+        if self._process is None or self._process.stdin is None:
+            raise RuntimeError("Server not started")
+        line = json.dumps(request) + "\n"
+        self._process.stdin.write(line)
+        self._process.stdin.flush()
+        raw = self._process.stdout.readline() if self._process.stdout else ""
+        if not raw:
+            raise ConnectionError("MCP server closed connection")
+        return json.loads(raw)
+
+    def close(self) -> None:
+        if self._process:
+            self._process.terminate()
+            self._process.wait(timeout=5)
+
+    def list_tools(self) -> list[dict[str, Any]]:
+        resp = self.send({"jsonrpc": "2.0", "method": "tools/list", "id": 1})
+        return resp.get("result", {}).get("tools", [])
+
+    def call_tool(self, name: str, args: dict[str, Any], timeout: int = 30) -> str:
+        if self._process is None or self._process.stdout is None:
+            raise RuntimeError("Server not started")
+        request = json.dumps({
+            "jsonrpc": "2.0",
+            "method": "tools/call",
+            "params": {"name": name, "arguments": args},
+            "id": 2,
+        }) + "\n"
+        self._process.stdin.write(request)
+        self._process.stdin.flush()
+        try:
+            self._process.stdout.flush()
+        except Exception:
+            logger.debug("Failed to flush stdout stream")
+        raw = self._read_line_with_timeout(timeout)
+        if not raw:
+            self.close()
+            raise TimeoutError(f"Tool '{name}' timed out after {timeout}s")
+        resp = json.loads(raw)
+        result = resp.get("result", {})
+        content = result.get("content", [])
+        parts = [c.get("text", "") for c in content if c.get("type") == "text"]
+        return "\n".join(parts)
+
+    def _read_line_with_timeout(self, timeout: int) -> str:
+        import select
+        if self._process is None or self._process.stdout is None:
+            return ""
+        import time
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            r, _, _ = select.select([self._process.stdout], [], [], 1.0)
+            if r:
+                return self._process.stdout.readline()
+        return ""

modus/actions/mcp/client.py

@@ -0,0 +1,103 @@
+import logging
+from typing import Any
+
+from modus.actions.mcp._stdio import MCPStdioServer
+from modus.core.types import ToolDefinition
+
+logger = logging.getLogger(__name__)
+
+
+class MCPClientManager:
+    def __init__(self) -> None:
+        self._servers: dict[str, MCPStdioServer] = {}
+        self._tool_routes: dict[str, str] = {}
+        self._tool_definitions: dict[str, ToolDefinition] = {}
+
+    def has_tool(self, name: str) -> bool:
+        return name in self._tool_routes
+
+    def list_tools(self) -> list[ToolDefinition]:
+        return list(self._tool_definitions.values())
+
+    def connect(
+        self,
+        server: str,
+        *,
+        command: str | None = None,
+        args: list[str] | None = None,
+        url: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if command is not None:
+            self._connect_stdio(server, command, args or [])
+        elif url is not None:
+            self._connect_http(server, url)
+        else:
+            raise ValueError("connect() requires either command or url")
+
+    def _connect_stdio(self, server_name: str, command: str, args: list[str]) -> None:
+        mcp_server = MCPStdioServer(command, args)
+        try:
+            mcp_server.start()
+            tools = mcp_server.list_tools()
+        except Exception as e:
+            mcp_server.close()
+            raise ConnectionError(f"Failed to connect to MCP server '{server_name}': {e}") from e
+
+        self._servers[server_name] = mcp_server
+        self._register_tools(server_name, tools)
+
+    def _connect_http(self, server_name: str, url: str) -> None:
+        try:
+            import httpx
+            resp = httpx.post(f"{url.rstrip('/')}/tools/list", json={"jsonrpc": "2.0", "method": "tools/list", "id": 1}, timeout=10)
+            resp.raise_for_status()
+            data = resp.json()
+            tools = data.get("result", {}).get("tools", [])
+        except ImportError:
+            raise ImportError("httpx is required for HTTP MCP transport. Install it with: pip install httpx")
+        except Exception as e:
+            raise ConnectionError(f"Failed to connect to MCP HTTP server '{server_name}' at {url}: {e}") from e
+
+        self._tool_routes["_http_" + server_name] = server_name
+        self._register_tools(server_name, tools)
+
+    def _register_tools(self, server_name: str, tools: list[dict]) -> None:
+        for t in tools:
+            name = t["name"]
+            self._tool_routes[name] = server_name
+            self._tool_definitions[name] = ToolDefinition(
+                name=name,
+                description=t.get("description", ""),
+                parameters=t.get("inputSchema"),
+            )
+        logger.info("MCP server '%s' registered %d tools", server_name, len(tools))
+
+    def execute(self, tool_name: str, args: dict[str, Any], timeout: int = 30) -> str:
+        if tool_name not in self._tool_routes:
+            raise KeyError(f"Unknown MCP tool: {tool_name}")
+        server_name = self._tool_routes[tool_name]
+        server = self._servers.get(server_name)
+        if server is None:
+            raise RuntimeError(f"MCP server '{server_name}' is not connected")
+        return server.call_tool(tool_name, args, timeout=timeout)
+
+    def refresh(self) -> int:
+        new_count = 0
+        for server_name, server in list(self._servers.items()):
+            try:
+                tools = server.list_tools()
+                for t in tools:
+                    name = t["name"]
+                    if name not in self._tool_routes:
+                        self._tool_routes[name] = server_name
+                        self._tool_definitions[name] = ToolDefinition(
+                            name=name,
+                            description=t.get("description", ""),
+                            parameters=t.get("inputSchema"),
+                        )
+                        new_count += 1
+            except Exception as e:
+                logger.warning("Failed to refresh tools from '%s': %s", server_name, e)
+        logger.info("Discovered %d new tools", new_count)
+        return new_count

modus/actions/mcp/transport.py

@@ -0,0 +1,10 @@
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Transport(Protocol):
+    async def connect(self) -> None: ...
+
+    async def close(self) -> None: ...
+
+    async def send_request(self, method: str, params: dict[str, Any]) -> dict[str, Any]: ...

modus/actions/registry.py

@@ -0,0 +1,63 @@
+from typing import Any
+
+from modus.core.protocols import Tool
+from modus.core.types import ToolDefinition
+
+
+class ToolRegistry:
+    """In-memory index of local (in-process) tools."""
+
+    def __init__(self) -> None:
+        self._tools: dict[str, Tool] = {}
+
+    def register(self, tool: Tool) -> None:
+        if not tool.name:
+            raise ValueError("Tool must have a name")
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> Tool:
+        if name not in self._tools:
+            raise KeyError(f"Unknown tool: {name}")
+        return self._tools[name]
+
+    def has(self, name: str) -> bool:
+        return name in self._tools
+
+    def list_tools(self) -> list[ToolDefinition]:
+        return [
+            ToolDefinition(
+                name=tool.name,
+                description=tool.description,
+                parameters=tool.parameters,
+                require_approval=getattr(tool, "require_approval", False),
+            )
+            for tool in self._tools.values()
+        ]
+
+    def to_openai_schemas(self) -> list[dict[str, Any]]:
+        return [
+            {
+                "type": "function",
+                "function": {
+                    "name": tool.name,
+                    "description": tool.description,
+                    "parameters": tool.parameters
+                    or {"type": "object", "properties": {}},
+                },
+            }
+            for tool in self._tools.values()
+        ]
+
+    def to_anthropic_schemas(self) -> list[dict[str, Any]]:
+        return [
+            {
+                "name": tool.name,
+                "description": tool.description,
+                "input_schema": tool.parameters
+                or {"type": "object", "properties": {}},
+            }
+            for tool in self._tools.values()
+        ]
+
+
+LocalToolRegistry = ToolRegistry