devsper 2.1.6__py3-none-any.whl

devsper/tools/experiments/model_benchmark_runner.py

@@ -0,0 +1,45 @@
+"""Run a simple benchmark: execute a function N times and report mean/std of runtimes (mock or real)."""
+
+import json
+import time
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class ModelBenchmarkRunnerTool(Tool):
+    """
+    Run a lightweight benchmark: repeat a no-op or fixed delay N times, report mean/std (for pipeline demos).
+    """
+
+    name = "model_benchmark_runner"
+    description = "Run a simple timing benchmark (N iterations, optional delay) and report mean/std."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "iterations": {"type": "integer", "description": "Number of iterations (default 5)"},
+            "delay_seconds": {"type": "number", "description": "Optional delay per iteration (default 0)"},
+        },
+        "required": [],
+    }
+
+    def run(self, **kwargs) -> str:
+        iterations = kwargs.get("iterations", 5)
+        delay_seconds = kwargs.get("delay_seconds", 0)
+        if not isinstance(iterations, int) or iterations < 1:
+            iterations = 5
+        if not isinstance(delay_seconds, (int, float)) or delay_seconds < 0:
+            delay_seconds = 0
+        times = []
+        for _ in range(iterations):
+            t0 = time.perf_counter()
+            if delay_seconds > 0:
+                time.sleep(delay_seconds)
+            times.append(time.perf_counter() - t0)
+        mean_t = sum(times) / len(times)
+        variance = sum((t - mean_t) ** 2 for t in times) / len(times)
+        std_t = variance ** 0.5
+        return json.dumps({"iterations": iterations, "mean_seconds": round(mean_t, 4), "std_seconds": round(std_t, 4), "times": [round(t, 4) for t in times]}, indent=2)
+
+
+register(ModelBenchmarkRunnerTool())

devsper/tools/experiments/monte_carlo_experiment.py

@@ -0,0 +1,38 @@
+"""Run a Monte Carlo experiment: sample N times from a simple distribution and report stats."""
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+import random
+
+
+class MonteCarloExperimentTool(Tool):
+    """
+    Run a Monte Carlo experiment: N random samples (e.g. uniform or from a list) and report mean/std.
+    """
+
+    name = "monte_carlo_experiment"
+    description = "Run Monte Carlo: N samples, report mean, std, min, max."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "n_samples": {"type": "integer", "description": "Number of samples (default 100)"},
+            "low": {"type": "number", "description": "Uniform low (default 0)"},
+            "high": {"type": "number", "description": "Uniform high (default 1)"},
+        },
+        "required": [],
+    }
+
+    def run(self, **kwargs) -> str:
+        n_samples = kwargs.get("n_samples", 100)
+        low = kwargs.get("low", 0.0)
+        high = kwargs.get("high", 1.0)
+        if not isinstance(n_samples, int) or n_samples < 1:
+            n_samples = 100
+        samples = [random.uniform(low, high) for _ in range(n_samples)]
+        mean = sum(samples) / len(samples)
+        variance = sum((x - mean) ** 2 for x in samples) / len(samples)
+        std = variance ** 0.5
+        return f"Monte Carlo (n={n_samples}, uniform [{low},{high}]): mean={mean:.4f}, std={std:.4f}, min={min(samples):.4f}, max={max(samples):.4f}"
+
+
+register(MonteCarloExperimentTool())

devsper/tools/experiments/parameter_sweep_runner.py

@@ -0,0 +1,51 @@
+"""Run a parameter sweep: generate (param_name, value) combinations and return as batch plan."""
+
+import json
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class ParameterSweepRunnerTool(Tool):
+    """
+    Generate parameter sweep combinations from named parameter lists (no actual execution).
+    """
+
+    name = "parameter_sweep_runner"
+    description = "Generate parameter sweep combinations from named parameter lists."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "params": {
+                "type": "object",
+                "description": "Map of param name -> list of values, e.g. {\"lr\": [0.01, 0.1], \"epochs\": [5, 10]}",
+            },
+            "max_combinations": {"type": "integer", "description": "Cap total combinations (default 100)"},
+        },
+        "required": ["params"],
+    }
+
+    def run(self, **kwargs) -> str:
+        params = kwargs.get("params")
+        max_combinations = kwargs.get("max_combinations", 100)
+        if not params or not isinstance(params, dict):
+            return "Error: params must be a dict of param name -> list of values"
+        if not isinstance(max_combinations, int) or max_combinations < 1:
+            max_combinations = 100
+        names = list(params.keys())
+        values = []
+        for n in names:
+            v = params[n]
+            if not isinstance(v, list):
+                v = [v]
+            values.append(v)
+        result = [{}]
+        for i, vlist in enumerate(values):
+            result = [r | {names[i]: x} for r in result for x in vlist]
+            if len(result) > max_combinations:
+                result = result[:max_combinations]
+                break
+        return json.dumps({"combinations": result, "total": len(result)}, indent=2)
+
+
+register(ParameterSweepRunnerTool())

devsper/tools/experiments/result_comparator.py

@@ -0,0 +1,58 @@
+"""Compare two or more experiment results (metrics) and report best by a chosen metric."""
+
+import json
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class ResultComparatorTool(Tool):
+    """
+    Compare experiment results: pass list of {run_id, metrics}; choose metric and direction (max/min).
+    """
+
+    name = "result_comparator"
+    description = "Compare experiment results by a chosen metric; return best run and summary."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "results": {
+                "type": "array",
+                "items": {"type": "object"},
+                "description": "List of {run_id, metrics}",
+            },
+            "metric": {"type": "string", "description": "Metric name to compare (e.g. accuracy)"},
+            "higher_is_better": {"type": "boolean", "description": "True for accuracy, False for loss (default True)"},
+        },
+        "required": ["results", "metric"],
+    }
+
+    def run(self, **kwargs) -> str:
+        results = kwargs.get("results")
+        metric = kwargs.get("metric")
+        higher_is_better = kwargs.get("higher_is_better", True)
+        if not results or not isinstance(results, list):
+            return "Error: results must be a non-empty list of {run_id, metrics}"
+        if not metric or not isinstance(metric, str):
+            return "Error: metric must be a non-empty string"
+        comparable = []
+        for r in results:
+            if not isinstance(r, dict):
+                continue
+            run_id = r.get("run_id", "?")
+            metrics = r.get("metrics") or r
+            if metric not in metrics:
+                continue
+            try:
+                val = float(metrics[metric])
+                comparable.append((run_id, val, r))
+            except (TypeError, ValueError):
+                continue
+        if not comparable:
+            return f"No results with metric '{metric}' found."
+        comparable.sort(key=lambda x: x[1], reverse=higher_is_better)
+        best = comparable[0]
+        return json.dumps({"best_run_id": best[0], "best_value": best[1], "all_ranked": [{"run_id": x[0], "value": x[1]} for x in comparable]}, indent=2)
+
+
+register(ResultComparatorTool())

devsper/tools/experiments/simulation_runner.py

@@ -0,0 +1,43 @@
+"""Run a simple simulation: e.g. N steps of a deterministic recurrence and return final state."""
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+try:
+    import numpy as np
+except ImportError:
+    np = None
+
+
+class SimulationRunnerTool(Tool):
+    """
+    Run a simple numeric simulation: x_{n+1} = f(x_n) for N steps (e.g. linear growth).
+    """
+
+    name = "simulation_runner"
+    description = "Run a simple simulation: recurrence for N steps (e.g. linear growth)."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "initial_value": {"type": "number", "description": "Starting value (default 1)"},
+            "steps": {"type": "integer", "description": "Number of steps (default 10)"},
+            "growth_rate": {"type": "number", "description": "Multiplier per step (default 1.1)"},
+        },
+        "required": [],
+    }
+
+    def run(self, **kwargs) -> str:
+        initial = kwargs.get("initial_value", 1.0)
+        steps = kwargs.get("steps", 10)
+        growth_rate = kwargs.get("growth_rate", 1.1)
+        if not isinstance(steps, int) or steps < 1:
+            steps = 10
+        x = initial
+        trajectory = [x]
+        for _ in range(steps - 1):
+            x = x * growth_rate
+            trajectory.append(x)
+        return f"Simulation: initial={initial}, steps={steps}, growth_rate={growth_rate}. Final value: {x}. Trajectory (first 5, last 2): {trajectory[:5]} ... {trajectory[-2:]}"
+
+
+register(SimulationRunnerTool())

devsper/tools/experiments/statistical_significance_test.py

@@ -0,0 +1,56 @@
+"""Simple statistical significance: compare two samples with a t-statistic (no scipy)."""
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+try:
+    import numpy as np
+except ImportError:
+    np = None
+
+
+class StatisticalSignificanceTestTool(Tool):
+    """
+    Compute pooled t-statistic for two samples (no p-value; report t and approximate interpretation).
+    """
+
+    name = "statistical_significance_test"
+    description = "Compare two samples with t-statistic (pooled)."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "sample_a": {"type": "array", "items": {"type": "number"}, "description": "First sample"},
+            "sample_b": {"type": "array", "items": {"type": "number"}, "description": "Second sample"},
+        },
+        "required": ["sample_a", "sample_b"],
+    }
+
+    def run(self, **kwargs) -> str:
+        sample_a = kwargs.get("sample_a")
+        sample_b = kwargs.get("sample_b")
+        if not sample_a or not isinstance(sample_a, list):
+            return "Error: sample_a must be a non-empty list of numbers"
+        if not sample_b or not isinstance(sample_b, list):
+            return "Error: sample_b must be a non-empty list of numbers"
+        if np is None:
+            return "Error: numpy is required for this tool"
+        try:
+            a = np.array(sample_a, dtype=float)
+            b = np.array(sample_b, dtype=float)
+            a, b = a[~np.isnan(a)], b[~np.isnan(b)]
+        except (ValueError, TypeError):
+            return "Error: values must be numeric"
+        if len(a) < 2 or len(b) < 2:
+            return "Error: need at least 2 values per sample"
+        n1, n2 = len(a), len(b)
+        m1, m2 = np.mean(a), np.mean(b)
+        s1, s2 = np.std(a, ddof=1), np.std(b, ddof=1)
+        if s1 == 0 and s2 == 0:
+            return "No variance in one or both samples; t-test not defined."
+        pooled = ((n1 - 1) * s1**2 + (n2 - 1) * s2**2) / (n1 + n2 - 2)
+        pooled = max(pooled ** 0.5, 1e-10)
+        t = (m1 - m2) / (pooled * (1 / n1 + 1 / n2) ** 0.5)
+        return f"Pooled t-statistic: {t:.4f}. Mean A: {m1:.4f}, Mean B: {m2:.4f}. |t|>2 often suggests difference at ~5% level."
+
+
+register(StatisticalSignificanceTestTool())

devsper/tools/experiments/swarm_map_reduce.py

@@ -0,0 +1,42 @@
+"""Map-reduce plan for swarm: split items into batches (map), then aggregate keys (reduce)."""
+
+import json
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class SwarmMapReduceTool(Tool):
+    """
+    Plan a map-reduce for swarm: split a list of items into map batches; suggest reduce keys.
+    """
+
+    name = "swarm_map_reduce"
+    description = "Plan map-reduce for swarm: split items into map batches; return batch plan."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "items": {
+                "type": "array",
+                "description": "List of items to process (e.g. file paths or IDs)",
+            },
+            "batch_size": {"type": "integer", "description": "Items per map batch (default 5)"},
+            "reduce_key": {"type": "string", "description": "Suggested key for reduce phase (e.g. sum, concat)"},
+        },
+        "required": ["items"],
+    }
+
+    def run(self, **kwargs) -> str:
+        items = kwargs.get("items")
+        batch_size = kwargs.get("batch_size", 5)
+        reduce_key = kwargs.get("reduce_key") or "concat"
+        if not items or not isinstance(items, list):
+            return "Error: items must be a non-empty list"
+        if not isinstance(batch_size, int) or batch_size < 1:
+            batch_size = 5
+        batches = [items[i : i + batch_size] for i in range(0, len(items), batch_size)]
+        result = {"total_items": len(items), "batch_size": batch_size, "map_batches": len(batches), "batches": batches, "reduce_key": reduce_key}
+        return json.dumps(result, indent=2)
+
+
+register(SwarmMapReduceTool())

devsper/tools/filesystem/__init__.py

@@ -0,0 +1,12 @@
+"""Filesystem tools: read, write, list, search, metadata, etc."""
+
+from devsper.tools.filesystem.read_file import ReadFileTool
+from devsper.tools.filesystem.write_file import WriteFileTool
+from devsper.tools.filesystem.append_file import AppendFileTool
+from devsper.tools.filesystem.list_directory import ListDirectoryTool
+from devsper.tools.filesystem.search_files import SearchFilesTool
+from devsper.tools.filesystem.find_large_files import FindLargeFilesTool
+from devsper.tools.filesystem.file_metadata import FileMetadataTool
+from devsper.tools.filesystem.file_hash import FileHashTool
+from devsper.tools.filesystem.file_line_count import FileLineCountTool
+from devsper.tools.filesystem.file_preview import FilePreviewTool

devsper/tools/filesystem/append_file.py

@@ -0,0 +1,42 @@
+"""Append content to a file."""
+
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class AppendFileTool(Tool):
+    """Append text to the end of a file. Creates the file if it does not exist."""
+
+    name = "append_file"
+    description = "Append content to a file. Creates file if it does not exist."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Path to the file"},
+            "content": {"type": "string", "description": "Content to append"},
+        },
+        "required": ["path", "content"],
+    }
+
+    def run(self, **kwargs) -> str:
+        path = kwargs.get("path")
+        content = kwargs.get("content")
+        if not path or not isinstance(path, str):
+            return "Error: path must be a non-empty string"
+        if content is None:
+            return "Error: content is required"
+        if not isinstance(content, str):
+            content = str(content)
+        p = Path(path)
+        try:
+            p.parent.mkdir(parents=True, exist_ok=True)
+            with open(p, "a", encoding="utf-8") as f:
+                f.write(content)
+            return f"Appended {len(content)} characters to {path}"
+        except Exception as e:
+            return f"Error appending to file: {e}"
+
+
+register(AppendFileTool())

devsper/tools/filesystem/file_hash.py

@@ -0,0 +1,40 @@
+"""Compute a hash of a file's contents."""
+
+import hashlib
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class FileHashTool(Tool):
+    """Compute SHA-256 hash of a file's contents."""
+
+    name = "file_hash"
+    description = "Compute SHA-256 hash of a file. Returns hex digest."
+    input_schema = {
+        "type": "object",
+        "properties": {"path": {"type": "string", "description": "Path to the file"}},
+        "required": ["path"],
+    }
+
+    def run(self, **kwargs) -> str:
+        path = kwargs.get("path")
+        if not path or not isinstance(path, str):
+            return "Error: path must be a non-empty string"
+        p = Path(path)
+        if not p.exists():
+            return f"Error: file not found: {path}"
+        if not p.is_file():
+            return f"Error: not a file: {path}"
+        try:
+            h = hashlib.sha256()
+            with open(p, "rb") as f:
+                for chunk in iter(lambda: f.read(65536), b""):
+                    h.update(chunk)
+            return h.hexdigest()
+        except Exception as e:
+            return f"Error: {e}"
+
+
+register(FileHashTool())

devsper/tools/filesystem/file_line_count.py

@@ -0,0 +1,36 @@
+"""Count lines in a text file."""
+
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class FileLineCountTool(Tool):
+    """Count the number of lines in a text file."""
+
+    name = "file_line_count"
+    description = "Count lines in a file. Uses universal newlines."
+    input_schema = {
+        "type": "object",
+        "properties": {"path": {"type": "string", "description": "Path to the file"}},
+        "required": ["path"],
+    }
+
+    def run(self, **kwargs) -> str:
+        path = kwargs.get("path")
+        if not path or not isinstance(path, str):
+            return "Error: path must be a non-empty string"
+        p = Path(path)
+        if not p.exists():
+            return f"Error: file not found: {path}"
+        if not p.is_file():
+            return f"Error: not a file: {path}"
+        try:
+            count = sum(1 for _ in p.open(encoding="utf-8", errors="replace"))
+            return str(count)
+        except Exception as e:
+            return f"Error: {e}"
+
+
+register(FileLineCountTool())

devsper/tools/filesystem/file_metadata.py

@@ -0,0 +1,38 @@
+"""Get file metadata (size, mtime, etc.)."""
+
+from pathlib import Path
+from datetime import datetime, timezone
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class FileMetadataTool(Tool):
+    """Return metadata for a file: size, modification time, and whether it is a file/dir."""
+
+    name = "file_metadata"
+    description = "Get file metadata: size in bytes, modification time, type."
+    input_schema = {
+        "type": "object",
+        "properties": {"path": {"type": "string", "description": "Path to the file or directory"}},
+        "required": ["path"],
+    }
+
+    def run(self, **kwargs) -> str:
+        path = kwargs.get("path")
+        if not path or not isinstance(path, str):
+            return "Error: path must be a non-empty string"
+        p = Path(path)
+        if not p.exists():
+            return f"Error: path not found: {path}"
+        try:
+            st = p.stat()
+            mtime = datetime.fromtimestamp(st.st_mtime, tz=timezone.utc).isoformat()
+            kind = "directory" if p.is_dir() else "file"
+            size = st.st_size if p.is_file() else 0
+            return f"path: {path}\ntype: {kind}\nsize: {size} bytes\nmtime: {mtime}"
+        except Exception as e:
+            return f"Error: {e}"
+
+
+register(FileMetadataTool())

devsper/tools/filesystem/file_preview.py

@@ -0,0 +1,55 @@
+"""Preview the first N lines or bytes of a file."""
+
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class FilePreviewTool(Tool):
+    """Return the first N lines (default 20) or first N bytes of a file."""
+
+    name = "file_preview"
+    description = "Preview the start of a file: first N lines or first N bytes."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Path to the file"},
+            "lines": {"type": "integer", "description": "Number of lines to show (default 20). Ignored if bytes is set."},
+            "bytes": {"type": "integer", "description": "If set, show first N bytes instead of lines"},
+        },
+        "required": ["path"],
+    }
+
+    def run(self, **kwargs) -> str:
+        path = kwargs.get("path")
+        lines = kwargs.get("lines", 20)
+        bytes_limit = kwargs.get("bytes")
+        if not path or not isinstance(path, str):
+            return "Error: path must be a non-empty string"
+        if not isinstance(lines, int) or lines < 1:
+            lines = 20
+        p = Path(path)
+        if not p.exists():
+            return f"Error: file not found: {path}"
+        if not p.is_file():
+            return f"Error: not a file: {path}"
+        try:
+            if bytes_limit is not None:
+                if not isinstance(bytes_limit, int) or bytes_limit < 1:
+                    return "Error: bytes must be a positive integer"
+                data = p.read_bytes()[:bytes_limit]
+                return data.decode("utf-8", errors="replace")
+            with p.open(encoding="utf-8", errors="replace") as f:
+                out = []
+                for _ in range(lines):
+                    line = f.readline()
+                    if not line:
+                        break
+                    out.append(line.rstrip("\n"))
+                return "\n".join(out)
+        except Exception as e:
+            return f"Error: {e}"
+
+
+register(FilePreviewTool())

devsper/tools/filesystem/find_large_files.py

@@ -0,0 +1,50 @@
+"""Find files larger than a given size."""
+
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class FindLargeFilesTool(Tool):
+    """Find files under a directory that are larger than a given size in bytes."""
+
+    name = "find_large_files"
+    description = "Find files larger than min_size bytes in a directory. Returns paths and sizes."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Root directory to search"},
+            "min_size": {"type": "integer", "description": "Minimum file size in bytes"},
+        },
+        "required": ["path", "min_size"],
+    }
+
+    def run(self, **kwargs) -> str:
+        path = kwargs.get("path")
+        min_size = kwargs.get("min_size")
+        if not path or not isinstance(path, str):
+            return "Error: path must be a non-empty string"
+        if not isinstance(min_size, int) or min_size < 0:
+            return "Error: min_size must be a non-negative integer"
+        p = Path(path)
+        if not p.exists() or not p.is_dir():
+            return f"Error: path must be an existing directory: {path}"
+        try:
+            results = []
+            for f in p.rglob("*"):
+                if f.is_file():
+                    try:
+                        size = f.stat().st_size
+                        if size >= min_size:
+                            results.append((str(f), size))
+                    except OSError:
+                        pass
+            results.sort(key=lambda x: -x[1])
+            lines = [f"{size}\t{fp}" for fp, size in results]
+            return "\n".join(lines) if lines else "No files found"
+        except Exception as e:
+            return f"Error: {e}"
+
+
+register(FindLargeFilesTool())

devsper/tools/filesystem/list_directory.py

@@ -0,0 +1,39 @@
+"""List contents of a directory."""
+
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class ListDirectoryTool(Tool):
+    """List files and subdirectories in a directory."""
+
+    name = "list_directory"
+    description = "List entries in a directory. Returns names of files and subdirs."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Path to the directory"},
+        },
+        "required": ["path"],
+    }
+
+    def run(self, **kwargs) -> str:
+        path = kwargs.get("path")
+        if not path or not isinstance(path, str):
+            return "Error: path must be a non-empty string"
+        p = Path(path)
+        if not p.exists():
+            return f"Error: path not found: {path}"
+        if not p.is_dir():
+            return f"Error: not a directory: {path}"
+        try:
+            entries = sorted(p.iterdir(), key=lambda x: (not x.is_dir(), x.name.lower()))
+            lines = [f"{'[dir] ' if e.is_dir() else ''}{e.name}" for e in entries]
+            return "\n".join(lines) if lines else "(empty)"
+        except Exception as e:
+            return f"Error listing directory: {e}"
+
+
+register(ListDirectoryTool())