devsper 2.1.6__py3-none-any.whl

devsper/tools/scoring/store.py

@@ -0,0 +1,267 @@
+"""
+Persistent score store for tool reliability (SQLite at ~/.config/devsper/tool_scores.db).
+"""
+
+import sqlite3
+from dataclasses import dataclass
+from datetime import datetime, timezone, timedelta
+from pathlib import Path
+
+
+def _default_db_path() -> Path:
+    p = Path.home() / ".config" / "devsper" / "tool_scores.db"
+    p.parent.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+@dataclass
+class ToolScore:
+    tool_name: str
+    success_rate: float  # 0.0–1.0
+    avg_latency_ms: float
+    p95_latency_ms: float
+    total_calls: int
+    recent_failures: int
+    composite_score: float  # final blended score
+    last_updated: str
+    is_new: bool  # True if total_calls < 5 (no penalty for new tools)
+
+
+class ToolScoreStore:
+    """SQLite-backed store for tool results and materialized tool_scores."""
+
+    def __init__(self, db_path: str | Path | None = None) -> None:
+        self.db_path = Path(db_path) if db_path else _default_db_path()
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._init_schema()
+
+    def _conn(self) -> sqlite3.Connection:
+        return sqlite3.connect(str(self.db_path))
+
+    def _init_schema(self) -> None:
+        with self._conn() as c:
+            c.execute("""
+                CREATE TABLE IF NOT EXISTS tool_results (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    tool_name TEXT NOT NULL,
+                    task_type TEXT,
+                    success INTEGER NOT NULL,
+                    latency_ms INTEGER,
+                    error_type TEXT,
+                    timestamp TEXT NOT NULL
+                )
+            """)
+            c.execute("""
+                CREATE TABLE IF NOT EXISTS tool_scores (
+                    tool_name TEXT PRIMARY KEY,
+                    success_rate REAL,
+                    avg_latency_ms REAL,
+                    p95_latency_ms REAL,
+                    total_calls INTEGER,
+                    recent_failures INTEGER,
+                    composite_score REAL,
+                    last_updated TEXT
+                )
+            """)
+            c.execute(
+                "CREATE INDEX IF NOT EXISTS idx_tool_results_name ON tool_results(tool_name)"
+            )
+            c.execute(
+                "CREATE INDEX IF NOT EXISTS idx_tool_results_ts ON tool_results(timestamp)"
+            )
+
+    def record(
+        self,
+        tool_name: str,
+        task_type: str | None,
+        success: bool,
+        latency_ms: int | None = None,
+        error_type: str | None = None,
+    ) -> None:
+        """Insert one result and recompute/upsert tool_scores for this tool."""
+        ts = datetime.now(timezone.utc).isoformat()
+        with self._conn() as c:
+            c.execute(
+                """INSERT INTO tool_results
+                   (tool_name, task_type, success, latency_ms, error_type, timestamp)
+                   VALUES (?, ?, ?, ?, ?, ?)""",
+                (
+                    tool_name,
+                    task_type or "general",
+                    1 if success else 0,
+                    latency_ms,
+                    error_type,
+                    ts,
+                ),
+            )
+        self._recompute_scores(tool_name)
+
+    def _recompute_scores(self, tool_name: str) -> None:
+        from devsper.tools.scoring.scorer import compute_composite_score
+
+        with self._conn() as c:
+            rows = c.execute(
+                """SELECT success, latency_ms
+                   FROM tool_results
+                   WHERE tool_name = ?
+                   ORDER BY id DESC""",
+                (tool_name,),
+            ).fetchall()
+        if not rows:
+            return
+        total = len(rows)
+        successes = sum(1 for r in rows if r[0] == 1)
+        success_rate = successes / total if total else 0.0
+        latencies = [r[1] for r in rows if r[1] is not None]
+        avg_latency_ms = sum(latencies) / len(latencies) if latencies else 0.0
+        if latencies:
+            sorted_lat = sorted(latencies)
+            idx = max(0, int(len(sorted_lat) * 0.95) - 1)
+            p95_latency_ms = sorted_lat[idx]
+        else:
+            p95_latency_ms = 0.0
+        recent_20 = rows[:20]
+        recent_failures = sum(1 for r in recent_20 if r[0] == 0)
+        stats = {
+            "success_rate": success_rate,
+            "avg_latency_ms": avg_latency_ms,
+            "p95_latency_ms": p95_latency_ms,
+            "total_calls": total,
+            "recent_failures": recent_failures,
+        }
+        composite = compute_composite_score(stats)
+        with self._conn() as c2:
+            r = c2.execute(
+                "SELECT timestamp FROM tool_results WHERE tool_name = ? ORDER BY id DESC LIMIT 1",
+                (tool_name,),
+            ).fetchone()
+        last_ts = r[0] if r else datetime.now(timezone.utc).isoformat()
+        with self._conn() as c:
+            c.execute(
+                """INSERT INTO tool_scores
+                   (tool_name, success_rate, avg_latency_ms, p95_latency_ms,
+                    total_calls, recent_failures, composite_score, last_updated)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                   ON CONFLICT(tool_name) DO UPDATE SET
+                     success_rate = excluded.success_rate,
+                     avg_latency_ms = excluded.avg_latency_ms,
+                     p95_latency_ms = excluded.p95_latency_ms,
+                     total_calls = excluded.total_calls,
+                     recent_failures = excluded.recent_failures,
+                     composite_score = excluded.composite_score,
+                     last_updated = excluded.last_updated""",
+                (
+                    tool_name,
+                    success_rate,
+                    avg_latency_ms,
+                    p95_latency_ms,
+                    total,
+                    recent_failures,
+                    composite,
+                    last_ts,
+                ),
+            )
+
+    def get_score(self, tool_name: str) -> ToolScore | None:
+        row = None
+        with self._conn() as c:
+            row = c.execute(
+                "SELECT tool_name, success_rate, avg_latency_ms, p95_latency_ms,"
+                " total_calls, recent_failures, composite_score, last_updated"
+                " FROM tool_scores WHERE tool_name = ?",
+                (tool_name,),
+            ).fetchone()
+        if not row:
+            return None
+        return ToolScore(
+            tool_name=row[0],
+            success_rate=row[1],
+            avg_latency_ms=row[2],
+            p95_latency_ms=row[3],
+            total_calls=row[4],
+            recent_failures=row[5],
+            composite_score=row[6],
+            last_updated=row[7],
+            is_new=row[4] < 5,
+        )
+
+    def get_all_scores(self) -> list[ToolScore]:
+        with self._conn() as c:
+            rows = c.execute(
+                """SELECT tool_name, success_rate, avg_latency_ms, p95_latency_ms,
+                          total_calls, recent_failures, composite_score, last_updated
+                   FROM tool_scores
+                   ORDER BY composite_score DESC"""
+            ).fetchall()
+        return [
+            ToolScore(
+                tool_name=r[0],
+                success_rate=r[1],
+                avg_latency_ms=r[2],
+                p95_latency_ms=r[3],
+                total_calls=r[4],
+                recent_failures=r[5],
+                composite_score=r[6],
+                last_updated=r[7],
+                is_new=r[4] < 5,
+            )
+            for r in rows
+        ]
+
+    def get_scores_for_tools(self, tool_names: list[str]) -> dict[str, ToolScore]:
+        result: dict[str, ToolScore] = {}
+        for name in tool_names:
+            s = self.get_score(name)
+            if s is not None:
+                result[name] = s
+        return result
+
+    def reset(self, tool_name: str | None) -> None:
+        """Delete all records for a tool (or all tools if tool_name is None)."""
+        with self._conn() as c:
+            if tool_name is None:
+                c.execute("DELETE FROM tool_results")
+                c.execute("DELETE FROM tool_scores")
+            else:
+                c.execute("DELETE FROM tool_results WHERE tool_name = ?", (tool_name,))
+                c.execute("DELETE FROM tool_scores WHERE tool_name = ?", (tool_name,))
+
+    def prune(self, days: int = 90) -> int:
+        """Delete results older than N days. Returns number of rows deleted."""
+        cutoff = (datetime.now(timezone.utc) - timedelta(days=days)).isoformat()
+        with self._conn() as c:
+            cur = c.execute("DELETE FROM tool_results WHERE timestamp < ?", (cutoff,))
+            deleted = cur.rowcount
+        # Recompute scores for tools that still have results; drop scores for tools with no results left
+        with self._conn() as c:
+            remaining = {
+                r[0] for r in c.execute("SELECT DISTINCT tool_name FROM tool_results").fetchall()
+            }
+            all_scored = [
+                r[0] for r in c.execute("SELECT tool_name FROM tool_scores").fetchall()
+            ]
+        for name in all_scored:
+            if name in remaining:
+                self._recompute_scores(name)
+            else:
+                with self._conn() as c:
+                    c.execute("DELETE FROM tool_scores WHERE tool_name = ?", (name,))
+        return deleted
+
+    def result_count(self) -> int:
+        """Total number of result rows (for doctor)."""
+        with self._conn() as c:
+            r = c.execute("SELECT COUNT(*) FROM tool_results").fetchone()
+        return r[0] if r else 0
+
+    def tool_count(self) -> int:
+        """Number of tools with scores (for doctor)."""
+        with self._conn() as c:
+            r = c.execute("SELECT COUNT(*) FROM tool_scores").fetchone()
+        return r[0] if r else 0
+
+    def get_cached_tool_names(self) -> list[str]:
+        """Tool names with scores (warm cache for distributed routing)."""
+        with self._conn() as c:
+            rows = c.execute("SELECT tool_name FROM tool_scores ORDER BY composite_score DESC").fetchall()
+        return [r[0] for r in rows]

devsper/tools/selector.py

@@ -0,0 +1,130 @@
+"""
+Smart tool selection: filter by category and select top_k tools by semantic similarity to the task.
+"""
+
+import os
+
+from devsper.memory.embeddings import embed_text
+from devsper.tools.base import Tool
+from devsper.tools.registry import list_tools
+
+
+def _tool_category(tool: Tool) -> str:
+    """Infer category from tool.category or from module path (e.g. devsper.tools.research -> research)."""
+    if getattr(tool, "category", "") and str(tool.category).strip():
+        return str(tool.category).strip().lower()
+    module = getattr(tool.__class__, "__module__", "") or ""
+    if "devsper.tools." in module:
+        parts = module.split(".")
+        for i, p in enumerate(parts):
+            if p == "tools" and i + 1 < len(parts):
+                return parts[i + 1].lower()
+    return "general"
+
+
+def _cosine_similarity(a: list[float], b: list[float]) -> float:
+    if not a or not b or len(a) != len(b):
+        return 0.0
+    dot = sum(x * y for x, y in zip(a, b))
+    na = sum(x * x for x in a) ** 0.5
+    nb = sum(x * x for x in b) ** 0.5
+    if na == 0 or nb == 0:
+        return 0.0
+    return dot / (na * nb)
+
+
+def _top_k_by_similarity(
+    task_description: str,
+    tools: list[Tool],
+    top_k: int,
+) -> list[Tool]:
+    """Return top_k tools from the list by semantic similarity to task_description."""
+    if not tools or top_k <= 0:
+        return tools
+    task_embedding = embed_text(task_description or " ")
+    tool_texts = [f"{t.name}: {t.description}" for t in tools]
+    tool_embeddings = [embed_text(t) for t in tool_texts]
+    scored = [
+        (t, _cosine_similarity(task_embedding, te))
+        for t, te in zip(tools, tool_embeddings)
+    ]
+    scored.sort(key=lambda x: -x[1])
+    return [t for t, _ in scored[:top_k]]
+
+
+def select_tools_for_task(
+    task_description: str,
+    top_k: int = 12,
+    enabled_categories: list[str] | None = None,
+) -> list[Tool]:
+    """
+    Return tools most relevant to the task: filter by enabled_categories (if set),
+    then by semantic similarity, return top_k. If top_k <= 0, return all (no limit).
+    """
+    all_tools = list_tools()
+    if enabled_categories is not None and len(enabled_categories) > 0:
+        allowed = {c.lower().strip() for c in enabled_categories}
+        all_tools = [t for t in all_tools if _tool_category(t) in allowed]
+    if not all_tools:
+        return []
+    if top_k <= 0:
+        return all_tools
+    return _top_k_by_similarity(task_description, all_tools, top_k)
+
+
+def get_tools_for_task(
+    task_description: str,
+    config: object | None = None,
+    role: str | None = None,
+    score_store: object | None = None,
+) -> list[Tool]:
+    """
+    Return tools for the agent: use selector when config has tools.top_k > 0,
+    otherwise return all tools. If role is set, filter by role's tool_categories.
+    When score_store is provided and DEVSPER_DISABLE_TOOL_SCORING is not set,
+    uses blended similarity + reliability ranking.
+    """
+    if config is None:
+        try:
+            from devsper.config import get_config
+            config = get_config()
+        except Exception:
+            config = None
+
+    tools_config = getattr(config, "tools", None) if config else None
+    top_k = getattr(tools_config, "top_k", 0) if tools_config else 0
+    enabled = getattr(tools_config, "enabled", None) if tools_config else None
+
+    if role:
+        from devsper.agents.roles import get_role_config
+        role_config = get_role_config(role)
+        if role_config.tool_categories:
+            enabled = role_config.tool_categories
+
+    all_tools = list_tools()
+    if enabled is not None and len(enabled) > 0:
+        allowed = {c.lower().strip() for c in enabled}
+        all_tools = [t for t in all_tools if _tool_category(t) in allowed]
+
+    if not all_tools:
+        return []
+    if top_k <= 0:
+        return all_tools
+
+    top_k_val = top_k
+    if top_k_val <= 0:
+        return all_tools
+
+    use_scoring = (
+        score_store is not None
+        and os.environ.get("DEVSPER_DISABLE_TOOL_SCORING", "").strip() != "1"
+    )
+    if use_scoring:
+        from devsper.tools.scoring.selector import select_tools_scored
+        return select_tools_scored(
+            task_description or "",
+            all_tools,
+            top_k_val,
+            score_store,
+        )
+    return _top_k_by_similarity(task_description or "", all_tools, top_k_val)

devsper/tools/system/__init__.py

@@ -0,0 +1,12 @@
+"""System tools: shell, info, CPU, memory, disk, processes, env, pip."""
+
+from devsper.tools.system.run_shell_command import RunShellCommandTool
+from devsper.tools.system.system_info import SystemInfoTool
+from devsper.tools.system.cpu_usage import CpuUsageTool
+from devsper.tools.system.memory_usage import MemoryUsageTool
+from devsper.tools.system.disk_usage import DiskUsageTool
+from devsper.tools.system.process_list import ProcessListTool
+from devsper.tools.system.environment_variables import EnvironmentVariablesTool
+from devsper.tools.system.python_package_list import PythonPackageListTool
+from devsper.tools.system.pip_install import PipInstallTool
+from devsper.tools.system.pip_search import PipSearchTool

devsper/tools/system/cpu_usage.py

@@ -0,0 +1,22 @@
+"""Report CPU usage (basic). Uses psutil if available, else placeholder."""
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class CpuUsageTool(Tool):
+    """Return CPU usage percent. Uses psutil if installed."""
+
+    name = "cpu_usage"
+    description = "Get CPU usage percentage. Requires psutil or returns N/A."
+    input_schema = {"type": "object", "properties": {}, "required": []}
+
+    def run(self, **kwargs) -> str:
+        try:
+            import psutil
+            return f"CPU percent: {psutil.cpu_percent(interval=1)}%"
+        except ImportError:
+            return "psutil not installed. Install with: pip install psutil"
+
+
+register(CpuUsageTool())

devsper/tools/system/disk_usage.py

@@ -0,0 +1,35 @@
+"""Report disk usage for a path. Uses stdlib shutil."""
+
+import shutil
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class DiskUsageTool(Tool):
+    """Return disk usage for a path: total, used, free (in bytes)."""
+
+    name = "disk_usage"
+    description = "Get disk usage for a path. Returns total, used, free in bytes."
+    input_schema = {
+        "type": "object",
+        "properties": {"path": {"type": "string", "description": "Path (default: current dir)"}},
+        "required": [],
+    }
+
+    def run(self, **kwargs) -> str:
+        path = kwargs.get("path", ".")
+        if path is not None and not isinstance(path, str):
+            return "Error: path must be a string"
+        p = Path(path or ".").resolve()
+        if not p.exists():
+            return f"Error: path not found: {p}"
+        try:
+            usage = shutil.disk_usage(p)
+            return f"total = {usage.total} bytes\nused = {usage.used} bytes\nfree = {usage.free} bytes"
+        except Exception as e:
+            return f"Error: {e}"
+
+
+register(DiskUsageTool())

devsper/tools/system/environment_variables.py

@@ -0,0 +1,29 @@
+"""List environment variable names (and optionally values)."""
+
+import os
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class EnvironmentVariablesTool(Tool):
+    """List environment variable names. Optionally include values (may be sensitive)."""
+
+    name = "environment_variables"
+    description = "List environment variable names. Optionally show values."
+    input_schema = {
+        "type": "object",
+        "properties": {"show_values": {"type": "boolean", "description": "If true, include values"}},
+        "required": [],
+    }
+
+    def run(self, **kwargs) -> str:
+        show = kwargs.get("show_values", False)
+        names = sorted(os.environ.keys())
+        if not show:
+            return "\n".join(names)
+        lines = [f"{k}={os.environ[k]}" for k in names]
+        return "\n".join(lines)
+
+
+register(EnvironmentVariablesTool())

devsper/tools/system/memory_usage.py

@@ -0,0 +1,23 @@
+"""Report memory usage. Uses psutil if available."""
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class MemoryUsageTool(Tool):
+    """Return memory usage (total, used, percent). Uses psutil if installed."""
+
+    name = "memory_usage"
+    description = "Get memory usage. Requires psutil or returns N/A."
+    input_schema = {"type": "object", "properties": {}, "required": []}
+
+    def run(self, **kwargs) -> str:
+        try:
+            import psutil
+            v = psutil.virtual_memory()
+            return f"total = {v.total} bytes\nused = {v.used} bytes\npercent = {v.percent}%"
+        except ImportError:
+            return "psutil not installed. Install with: pip install psutil"
+
+
+register(MemoryUsageTool())

devsper/tools/system/pip_install.py

@@ -0,0 +1,44 @@
+"""Install a package with pip."""
+
+import subprocess
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class PipInstallTool(Tool):
+    """Install a package using pip. Returns pip output."""
+
+    name = "pip_install"
+    description = "Install a package with pip (e.g. pip install <package>)."
+    input_schema = {
+        "type": "object",
+        "properties": {"package": {"type": "string", "description": "Package name to install"}},
+        "required": ["package"],
+    }
+
+    def run(self, **kwargs) -> str:
+        package = kwargs.get("package")
+        if not package or not isinstance(package, str):
+            return "Error: package must be a non-empty string"
+        try:
+            result = subprocess.run(
+                ["pip", "install", package],
+                capture_output=True,
+                text=True,
+                timeout=120,
+            )
+            out = result.stdout or ""
+            err = result.stderr or ""
+            if err:
+                out = out + "\n" + err
+            if result.returncode != 0:
+                out = f"[exit {result.returncode}]\n" + out
+            return out.strip() or "Done"
+        except subprocess.TimeoutExpired:
+            return "Error: pip install timed out"
+        except Exception as e:
+            return f"Error: {e}"
+
+
+register(PipInstallTool())

devsper/tools/system/pip_search.py

@@ -0,0 +1,29 @@
+"""Search PyPI (pip search is deprecated; use simple message or run pip index)."""
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class PipSearchTool(Tool):
+    """Search PyPI. pip search is disabled; suggests using web or pip index versions."""
+
+    name = "pip_search"
+    description = "Search PyPI. Note: pip search is disabled; returns instructions."
+    input_schema = {
+        "type": "object",
+        "properties": {"query": {"type": "string", "description": "Search query"}},
+        "required": ["query"],
+    }
+
+    def run(self, **kwargs) -> str:
+        query = kwargs.get("query")
+        if not query or not isinstance(query, str):
+            return "Error: query must be a non-empty string"
+        return (
+            "pip search is disabled on PyPI. To find packages:\n"
+            "1. Visit https://pypi.org/search/?q=" + query.replace(" ", "+") + "\n"
+            "2. Or run: pip index versions <package> for a known package name"
+        )
+
+
+register(PipSearchTool())

devsper/tools/system/process_list.py

@@ -0,0 +1,34 @@
+"""List running processes. Uses psutil if available."""
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class ProcessListTool(Tool):
+    """List running processes (pid, name). Uses psutil; limited to first N."""
+
+    name = "process_list"
+    description = "List running processes. Requires psutil. Returns pid and name for first N."
+    input_schema = {
+        "type": "object",
+        "properties": {"limit": {"type": "integer", "description": "Max processes to list (default 20)"}},
+        "required": [],
+    }
+
+    def run(self, **kwargs) -> str:
+        try:
+            import psutil
+        except ImportError:
+            return "psutil not installed. Install with: pip install psutil"
+        limit = kwargs.get("limit", 20)
+        if not isinstance(limit, int) or limit < 1:
+            limit = 20
+        try:
+            procs = list(psutil.process_iter(["pid", "name"]))[:limit]
+            lines = [f"{p.info.get('pid')} {p.info.get('name', '')}" for p in procs]
+            return "\n".join(lines)
+        except Exception as e:
+            return f"Error: {e}"
+
+
+register(ProcessListTool())

devsper/tools/system/python_package_list.py

@@ -0,0 +1,40 @@
+"""List installed Python packages (pip list)."""
+
+import subprocess
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class PythonPackageListTool(Tool):
+    """Run pip list and return output."""
+
+    name = "python_package_list"
+    description = "List installed Python packages (pip list)."
+    input_schema = {
+        "type": "object",
+        "properties": {"limit": {"type": "integer", "description": "Max lines to return (default 100)"}},
+        "required": [],
+    }
+
+    def run(self, **kwargs) -> str:
+        limit = kwargs.get("limit", 100)
+        if not isinstance(limit, int) or limit < 1:
+            limit = 100
+        try:
+            result = subprocess.run(
+                ["pip", "list"],
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+            out = result.stdout or result.stderr or ""
+            lines = out.strip().splitlines()
+            return "\n".join(lines[:limit])
+        except FileNotFoundError:
+            return "pip not found"
+        except Exception as e:
+            return f"Error: {e}"
+
+
+register(PythonPackageListTool())