devsper 2.1.6__py3-none-any.whl

devsper/tools/math/histogram.py

@@ -0,0 +1,53 @@
+"""Compute histogram (count per bin) for a list of numbers."""
+
+from collections import defaultdict
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class HistogramTool(Tool):
+    """Compute histogram: bin edges and counts. Optional number of bins."""
+
+    name = "histogram"
+    description = "Compute histogram of values. Returns bin ranges and counts."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "values": {"type": "array", "description": "List of numbers"},
+            "bins": {"type": "integer", "description": "Number of bins (default 10)"},
+        },
+        "required": ["values"],
+    }
+
+    def run(self, **kwargs) -> str:
+        values = kwargs.get("values")
+        bins = kwargs.get("bins", 10)
+        if not isinstance(values, list):
+            return "Error: values must be an array"
+        if not isinstance(bins, int) or bins < 1:
+            bins = 10
+        try:
+            nums = [float(v) for v in values]
+        except (TypeError, ValueError):
+            return "Error: all elements must be numbers"
+        if not nums:
+            return "Error: empty list"
+        lo = min(nums)
+        hi = max(nums)
+        if hi == lo:
+            return f"All values equal: {lo}\ncount: {len(nums)}"
+        width = (hi - lo) / bins
+        counts = [0] * bins
+        for v in nums:
+            idx = min(int((v - lo) / width), bins - 1) if width > 0 else 0
+            counts[idx] += 1
+        lines = []
+        for i in range(bins):
+            left = lo + i * width
+            right = lo + (i + 1) * width
+            lines.append(f"[{left:.2f}, {right:.2f}): {counts[i]}")
+        return "\n".join(lines)
+
+
+register(HistogramTool())

devsper/tools/math/linear_regression.py

@@ -0,0 +1,47 @@
+"""Simple linear regression: y = mx + b from lists of x and y."""
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class LinearRegressionTool(Tool):
+    """Fit y = mx + b to x and y lists. Returns slope and intercept."""
+
+    name = "linear_regression"
+    description = "Fit linear regression to x and y data. Returns slope m and intercept b."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "x": {"type": "array", "description": "List of x values (numbers)"},
+            "y": {"type": "array", "description": "List of y values (numbers)"},
+        },
+        "required": ["x", "y"],
+    }
+
+    def run(self, **kwargs) -> str:
+        x = kwargs.get("x")
+        y = kwargs.get("y")
+        if not isinstance(x, list) or not isinstance(y, list):
+            return "Error: x and y must be arrays"
+        if len(x) != len(y) or len(x) < 2:
+            return "Error: x and y must have same length >= 2"
+        try:
+            import numpy as np
+            X = np.array(x, dtype=float)
+            Y = np.array(y, dtype=float)
+            n = len(X)
+            sx = X.sum()
+            sy = Y.sum()
+            sxy = (X * Y).sum()
+            sxx = (X * X).sum()
+            denom = n * sxx - sx * sx
+            if abs(denom) < 1e-12:
+                return "Error: singular (collinear) data"
+            m = (n * sxy - sx * sy) / denom
+            b = (sy - m * sx) / n
+            return f"slope m = {m}\nintercept b = {b}\ny = {m}*x + {b}"
+        except (ImportError, ValueError, TypeError) as e:
+            return f"Error: {e}"
+
+
+register(LinearRegressionTool())

devsper/tools/math/matrix_multiply.py

@@ -0,0 +1,38 @@
+"""Multiply two matrices (lists of lists). Uses numpy if available."""
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class MatrixMultiplyTool(Tool):
+    """Multiply two matrices given as JSON arrays. Uses numpy."""
+
+    name = "matrix_multiply"
+    description = "Multiply two matrices (list of lists). Requires numpy."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "matrix_a": {"type": "array", "description": "First matrix (list of rows)"},
+            "matrix_b": {"type": "array", "description": "Second matrix (list of rows)"},
+        },
+        "required": ["matrix_a", "matrix_b"],
+    }
+
+    def run(self, **kwargs) -> str:
+        a = kwargs.get("matrix_a")
+        b = kwargs.get("matrix_b")
+        if not isinstance(a, list) or not isinstance(b, list):
+            return "Error: matrix_a and matrix_b must be arrays"
+        try:
+            import numpy as np
+            A = np.array(a)
+            B = np.array(b)
+            C = A @ B
+            return str(C.tolist())
+        except ImportError:
+            return "Error: numpy required"
+        except Exception as e:
+            return f"Error: {e}"
+
+
+register(MatrixMultiplyTool())

devsper/tools/math/mean_std.py

@@ -0,0 +1,35 @@
+"""Compute mean and standard deviation of a list of numbers."""
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class MeanStdTool(Tool):
+    """Compute mean and standard deviation of a list of numbers."""
+
+    name = "mean_std"
+    description = "Compute mean and standard deviation of a list of numbers."
+    input_schema = {
+        "type": "object",
+        "properties": {"values": {"type": "array", "description": "List of numbers"}},
+        "required": ["values"],
+    }
+
+    def run(self, **kwargs) -> str:
+        values = kwargs.get("values")
+        if not isinstance(values, list):
+            return "Error: values must be an array"
+        try:
+            nums = [float(v) for v in values]
+        except (TypeError, ValueError):
+            return "Error: all elements must be numbers"
+        if not nums:
+            return "Error: empty list"
+        n = len(nums)
+        mean = sum(nums) / n
+        variance = sum((x - mean) ** 2 for x in nums) / n
+        std = variance ** 0.5
+        return f"mean = {mean}\nstd = {std}\nn = {n}"
+
+
+register(MeanStdTool())

devsper/tools/math/monte_carlo_simulation.py

@@ -0,0 +1,43 @@
+"""Simple Monte Carlo: sample random values and report mean/std."""
+
+import random
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class MonteCarloSimulationTool(Tool):
+    """Run a simple Monte Carlo: N samples from uniform(a,b), return mean and std."""
+
+    name = "monte_carlo_simulation"
+    description = "Monte Carlo: N uniform samples in [a,b]. Returns mean and std."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "n": {"type": "integer", "description": "Number of samples"},
+            "a": {"type": "number", "description": "Lower bound"},
+            "b": {"type": "number", "description": "Upper bound"},
+        },
+        "required": ["n", "a", "b"],
+    }
+
+    def run(self, **kwargs) -> str:
+        n = kwargs.get("n")
+        a = kwargs.get("a")
+        b = kwargs.get("b")
+        if not isinstance(n, int) or n < 1:
+            return "Error: n must be a positive integer"
+        try:
+            a, b = float(a), float(b)
+        except (TypeError, ValueError):
+            return "Error: a and b must be numbers"
+        if a >= b:
+            return "Error: a must be less than b"
+        values = [random.uniform(a, b) for _ in range(n)]
+        mean = sum(values) / n
+        variance = sum((x - mean) ** 2 for x in values) / n
+        std = variance ** 0.5
+        return f"n = {n}\nmean = {mean}\nstd = {std}"
+
+
+register(MonteCarloSimulationTool())

devsper/tools/math/polynomial_fit.py

@@ -0,0 +1,40 @@
+"""Fit a polynomial of given degree to x, y data. Uses numpy."""
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class PolynomialFitTool(Tool):
+    """Fit polynomial coefficients to x and y. Returns coefficients (highest degree first)."""
+
+    name = "polynomial_fit"
+    description = "Fit polynomial of given degree to x, y. Returns coefficients."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "x": {"type": "array", "description": "x values"},
+            "y": {"type": "array", "description": "y values"},
+            "degree": {"type": "integer", "description": "Polynomial degree (default 2)"},
+        },
+        "required": ["x", "y"],
+    }
+
+    def run(self, **kwargs) -> str:
+        x = kwargs.get("x")
+        y = kwargs.get("y")
+        degree = kwargs.get("degree", 2)
+        if not isinstance(x, list) or not isinstance(y, list):
+            return "Error: x and y must be arrays"
+        if len(x) != len(y) or len(x) < 2:
+            return "Error: x and y must have same length >= 2"
+        if not isinstance(degree, int) or degree < 1:
+            degree = 2
+        try:
+            import numpy as np
+            coefs = np.polyfit(x, y, degree)
+            return "coefficients (high to low): " + str(coefs.tolist())
+        except (ImportError, Exception) as e:
+            return f"Error: {e}"
+
+
+register(PolynomialFitTool())

devsper/tools/math/random_sample.py

@@ -0,0 +1,36 @@
+"""Draw a random sample from a list of values."""
+
+import random
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class RandomSampleTool(Tool):
+    """Return k random items from a list (without replacement)."""
+
+    name = "random_sample"
+    description = "Draw k random elements from a list without replacement."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "values": {"type": "array", "description": "List of values"},
+            "k": {"type": "integer", "description": "Number of items to sample"},
+        },
+        "required": ["values", "k"],
+    }
+
+    def run(self, **kwargs) -> str:
+        values = kwargs.get("values")
+        k = kwargs.get("k")
+        if not isinstance(values, list):
+            return "Error: values must be an array"
+        if not isinstance(k, int) or k < 1:
+            return "Error: k must be a positive integer"
+        if k > len(values):
+            return "Error: k cannot exceed list length"
+        sample = random.sample(values, k)
+        return str(sample)
+
+
+register(RandomSampleTool())

devsper/tools/mcp/__init__.py

@@ -0,0 +1,23 @@
+"""
+MCP (Model Context Protocol) integration: client, tool adapter, discovery.
+"""
+
+from devsper.config.schema import MCPServerConfig
+from devsper.tools.mcp.client import (
+    MCPClient,
+    MCPToolDefinition,
+)
+from devsper.tools.mcp.adapter import MCPToolAdapter
+from devsper.tools.mcp.discovery import (
+    discover_mcp_tools,
+    register_mcp_server,
+)
+
+__all__ = [
+    "MCPClient",
+    "MCPToolAdapter",
+    "MCPServerConfig",
+    "MCPToolDefinition",
+    "discover_mcp_tools",
+    "register_mcp_server",
+]

devsper/tools/mcp/adapter.py

@@ -0,0 +1,53 @@
+"""
+MCPToolAdapter: wrap an MCP tool as a devsper Tool for the tool registry.
+"""
+
+import asyncio
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+from devsper.tools.mcp.client import MCPClient, MCPToolDefinition
+
+
+class MCPToolAdapter(Tool):
+    """
+    Wraps an MCPToolDefinition as a devsper Tool so it appears in the
+    existing tool registry and selection pipeline unchanged.
+    """
+
+    def __init__(
+        self,
+        server_name: str,
+        definition: MCPToolDefinition,
+        client: MCPClient,
+    ) -> None:
+        # "{server_name}.{tool_name}" to avoid collisions
+        self.name = f"{server_name}.{definition.name}"
+        self.description = definition.description or f"MCP tool: {definition.name}"
+        self.category = "mcp"
+        self.input_schema = definition.input_schema
+        self._client = client
+        self._mcp_tool_name = definition.name
+        # Register in tool registry on adapter creation
+        register(self)
+
+    def run(self, **kwargs) -> str:
+        """Execute the MCP tool via client.call_tool; sync wrapper around async."""
+        try:
+            loop = asyncio.get_event_loop()
+        except RuntimeError:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+        if loop.is_running():
+            # If we're already inside an async context, run in a new loop (e.g. sync call from sync code)
+            import concurrent.futures
+            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+                future = pool.submit(
+                    asyncio.run,
+                    self._client.call_tool(self._mcp_tool_name, kwargs),
+                )
+                return future.result()
+        return loop.run_until_complete(
+            self._client.call_tool(self._mcp_tool_name, kwargs)
+        )

devsper/tools/mcp/client.py

@@ -0,0 +1,235 @@
+"""
+MCP client: connect to MCP servers over stdio, HTTP, or SSE.
+Implements initialize handshake, tools/list, tools/call.
+"""
+
+import asyncio
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+from devsper.protocols import MCP_PROTOCOL_VERSION
+from devsper.types.exceptions import MCPToolError
+
+
+@dataclass
+class MCPToolDefinition:
+    """One tool as returned by MCP tools/list."""
+    name: str
+    description: str
+    input_schema: dict  # JSON Schema as returned by MCP server
+
+
+def _next_id() -> int:
+    """Simple monotonic id for JSON-RPC requests."""
+    _next_id._n = getattr(_next_id, "_n", 0) + 1
+    return _next_id._n
+
+
+class MCPClient:
+    """
+    Connects to an MCP server over stdio, HTTP, or SSE transport.
+    Implements MCP protocol: initialize handshake, tools/list, tools/call.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        transport: str,
+        *,
+        command: list[str] | None = None,
+        url: str | None = None,
+        env: dict[str, str] | None = None,
+        timeout_seconds: int = 30,
+        auto_reconnect: bool = True,
+    ) -> None:
+        self.name = name
+        self.transport = transport
+        self.command = command or []
+        self.url = (url or "").rstrip("/")
+        self.env = dict(env or {})
+        self.timeout_seconds = timeout_seconds
+        self.auto_reconnect = auto_reconnect
+        self._server_capabilities: dict[str, Any] = {}
+        self._stdio_process: asyncio.subprocess.Process | None = None
+        self._stdio_reader: asyncio.StreamReader | None = None
+        self._stdio_writer: asyncio.StreamWriter | None = None
+        self._connected = False
+
+    async def connect(self) -> None:
+        """Send initialize request, await initialized notification, cache server capabilities."""
+        if self.transport == "stdio":
+            await self._connect_stdio()
+        elif self.transport in ("http", "sse"):
+            await self._connect_http_sse()
+        else:
+            raise ValueError(f"Unsupported MCP transport: {self.transport}")
+
+        req = {
+            "jsonrpc": "2.0",
+            "id": _next_id(),
+            "method": "initialize",
+            "params": {
+                "protocolVersion": MCP_PROTOCOL_VERSION,
+                "capabilities": {},
+                "clientInfo": {"name": "devsper", "version": "1.10.5"},
+            },
+        }
+        resp = await self._request(req)
+        if "result" in resp:
+            self._server_capabilities = resp["result"].get("capabilities", {})
+        # Send initialized notification (no response expected)
+        await self._send_notification("notifications/initialized", {})
+        self._connected = True
+
+    async def _connect_stdio(self) -> None:
+        if not self.command:
+            raise ValueError("stdio transport requires command")
+        env = os.environ.copy()
+        env.update(self.env)
+        self._stdio_process = await asyncio.create_subprocess_exec(
+            *self.command,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.DEVNULL,
+            env=env,
+        )
+        assert self._stdio_process.stdin and self._stdio_process.stdout
+        self._stdio_reader = self._stdio_process.stdout
+        self._stdio_writer = self._stdio_process.stdin
+
+    async def _connect_http_sse(self) -> None:
+        if not self.url:
+            raise ValueError("http/sse transport requires url")
+        # HTTP: no persistent connection for initialize; we'll use POST per request
+        self._connected = True
+
+    def _get_http_client(self):
+        import httpx
+        return httpx.AsyncClient(timeout=float(self.timeout_seconds))  # type: ignore[return-value]
+
+    async def _request(self, req: dict) -> dict:
+        if self.transport == "stdio":
+            return await self._request_stdio(req)
+        return await self._request_http(req)
+
+    async def _request_stdio(self, req: dict) -> dict:
+        if not self._stdio_writer or not self._stdio_reader:
+            raise RuntimeError("stdio not connected")
+        msg = json.dumps(req) + "\n"
+        self._stdio_writer.write(msg.encode("utf-8"))
+        await self._stdio_writer.drain()
+        line = await asyncio.wait_for(
+            self._stdio_reader.readline(),
+            timeout=self.timeout_seconds,
+        )
+        if not line:
+            raise ConnectionError("MCP server closed stdin")
+        data = json.loads(line.decode("utf-8").strip())
+        if "error" in data:
+            raise MCPToolError(data["error"].get("message", str(data["error"])))
+        return data
+
+    async def _request_http(self, req: dict) -> dict:
+        import httpx
+        client = self._get_http_client()
+        try:
+            # MCP over HTTP: POST JSON-RPC to endpoint
+            endpoint = self.url if self.url.endswith("/") else f"{self.url}/"
+            r = await client.post(endpoint, json=req)
+            r.raise_for_status()
+            out = r.json()
+            if "error" in out:
+                raise MCPToolError(out["error"].get("message", str(out["error"])))
+            return out
+        except httpx.HTTPError as e:
+            raise MCPToolError(str(e))
+        finally:
+            await client.aclose()
+
+    async def _send_notification(self, method: str, params: dict) -> None:
+        """Send a notification (no id, no response)."""
+        msg = {"jsonrpc": "2.0", "method": method, "params": params or {}}
+        if self.transport == "stdio" and self._stdio_writer:
+            self._stdio_writer.write((json.dumps(msg) + "\n").encode("utf-8"))
+            await self._stdio_writer.drain()
+        elif self.transport in ("http", "sse"):
+            async with self._get_http_client() as client:
+                await client.post(
+                    self.url if self.url.endswith("/") else f"{self.url}/",
+                    json=msg,
+                )
+
+    async def list_tools(self) -> list[MCPToolDefinition]:
+        """Send tools/list request; return list of MCPToolDefinition."""
+        req = {
+            "jsonrpc": "2.0",
+            "id": _next_id(),
+            "method": "tools/list",
+            "params": {},
+        }
+        resp = await self._request(req)
+        result = resp.get("result") or {}
+        tools_data = result.get("tools", [])
+        return [
+            MCPToolDefinition(
+                name=t.get("name", ""),
+                description=t.get("description", ""),
+                input_schema=t.get("inputSchema", {}),
+            )
+            for t in tools_data
+        ]
+
+    async def call_tool(self, name: str, arguments: dict) -> str:
+        """Send tools/call request; extract text from result.content; on error raise MCPToolError."""
+        req = {
+            "jsonrpc": "2.0",
+            "id": _next_id(),
+            "method": "tools/call",
+            "params": {"name": name, "arguments": arguments or {}},
+        }
+        resp = await self._request(req)
+        result = resp.get("result")
+        if result is None:
+            raise MCPToolError(resp.get("error", {}).get("message", "Unknown error"))
+        if result.get("isError"):
+            content = result.get("content", [])
+            parts = [
+                c.get("text", str(c))
+                for c in content
+                if isinstance(c, dict)
+            ]
+            raise MCPToolError("\n".join(parts) if parts else "Tool returned error")
+        content = result.get("content") or []
+        texts = [
+            c.get("text", "") if isinstance(c, dict) else str(c)
+            for c in content
+        ]
+        return "\n".join(texts)
+
+    async def disconnect(self) -> None:
+        """Close connection."""
+        if self.transport == "stdio" and self._stdio_writer:
+            try:
+                self._stdio_writer.close()
+                await self._stdio_writer.wait_closed()
+            except Exception:
+                pass
+            self._stdio_writer = None
+            self._stdio_reader = None
+        if self._stdio_process and self._stdio_process.returncode is None:
+            self._stdio_process.terminate()
+            try:
+                await asyncio.wait_for(self._stdio_process.wait(), timeout=2.0)
+            except asyncio.TimeoutError:
+                self._stdio_process.kill()
+            self._stdio_process = None
+        self._connected = False
+
+    async def reconnect(self) -> None:
+        """Disconnect and connect again."""
+        await self.disconnect()
+        await self.connect()
+
+

devsper/tools/mcp/discovery.py

@@ -0,0 +1,53 @@
+"""
+MCP discovery: connect to server, list tools, wrap as MCPToolAdapter and optionally register.
+"""
+
+from devsper.config.schema import MCPServerConfig
+from devsper.tools.mcp.client import MCPClient, MCPToolDefinition
+from devsper.tools.mcp.adapter import MCPToolAdapter
+
+
+def _config_to_client(config: MCPServerConfig) -> MCPClient:
+    """Build MCPClient from config model."""
+    return MCPClient(
+        name=config.name,
+        transport=config.transport,
+        command=config.command,
+        url=config.url,
+        env=config.env,
+        timeout_seconds=config.timeout_seconds,
+        auto_reconnect=config.auto_reconnect,
+    )
+
+
+async def discover_mcp_tools_async(server_config: MCPServerConfig) -> list[MCPToolAdapter]:
+    """Connect client, list tools, wrap each as MCPToolAdapter, return list."""
+    client = _config_to_client(server_config)
+    await client.connect()
+    definitions = await client.list_tools()
+    adapters = [
+        MCPToolAdapter(server_config.name, defn, client)
+        for defn in definitions
+    ]
+    return adapters
+
+
+def discover_mcp_tools(server_config: MCPServerConfig) -> list[MCPToolAdapter]:
+    """Synchronous wrapper: connect, list tools, wrap as MCPToolAdapter."""
+    import asyncio
+    return asyncio.run(discover_mcp_tools_async(server_config))
+
+
+async def register_mcp_server_async(server_config: MCPServerConfig) -> int:
+    """Discover MCP tools and register each adapter in the tool registry. Return count."""
+    adapters = await discover_mcp_tools_async(server_config)
+    from devsper.tools.registry import register
+    for adapter in adapters:
+        register(adapter)
+    return len(adapters)
+
+
+def register_mcp_server(server_config: MCPServerConfig) -> int:
+    """Synchronous: discover and register MCP tools; return count registered."""
+    import asyncio
+    return asyncio.run(register_mcp_server_async(server_config))

devsper/tools/memory/__init__.py

@@ -0,0 +1,16 @@
+"""Memory tools: store, search, list, delete, tag, summarize memory."""
+
+from devsper.tools.memory.store_memory import StoreMemoryTool
+from devsper.tools.memory.search_memory import SearchMemoryTool
+from devsper.tools.memory.list_memory import ListMemoryTool
+from devsper.tools.memory.delete_memory import DeleteMemoryTool
+from devsper.tools.memory.tag_memory import TagMemoryTool
+from devsper.tools.memory.summarize_memory import SummarizeMemoryTool
+from devsper.tools.registry import register
+
+register(StoreMemoryTool())
+register(SearchMemoryTool())
+register(ListMemoryTool())
+register(DeleteMemoryTool())
+register(TagMemoryTool())
+register(SummarizeMemoryTool())