devsper 2.1.6__py3-none-any.whl

devsper/tools/documents/extract_tables.py

@@ -0,0 +1,47 @@
+"""Extract table-like content from docproc markdown (pipe tables)."""
+
+import re
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+from devsper.tools.documents._docproc import run_docproc_to_markdown
+
+
+class ExtractTablesTool(Tool):
+    """Extract markdown tables from document (docproc output)."""
+
+    name = "extract_tables"
+    description = "Extract tables from document as markdown. Uses docproc output."
+    input_schema = {
+        "type": "object",
+        "properties": {"file_path": {"type": "string", "description": "Path to the document"}},
+        "required": ["file_path"],
+    }
+
+    def run(self, **kwargs) -> str:
+        file_path = kwargs.get("file_path")
+        if not file_path or not isinstance(file_path, str):
+            return "Error: file_path must be a non-empty string"
+        content, err = run_docproc_to_markdown(file_path)
+        if err:
+            return err
+        lines = content.splitlines()
+        tables = []
+        current = []
+        in_table = False
+        for line in lines:
+            if "|" in line and line.strip().startswith("|"):
+                current.append(line)
+                in_table = True
+            else:
+                if in_table and current:
+                    tables.append("\n".join(current))
+                    current = []
+                in_table = False
+        if current:
+            tables.append("\n".join(current))
+        if not tables:
+            return "No markdown tables found in extracted content."
+        return "\n\n---\n\n".join(tables[:10])
+
+
+register(ExtractTablesTool())

devsper/tools/documents/summarize_document.py

@@ -0,0 +1,42 @@
+"""Summarize document by truncating docproc markdown (first N chars + key sentences)."""
+
+import re
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+from devsper.tools.documents._docproc import run_docproc_to_markdown
+
+
+class SummarizeDocumentTool(Tool):
+    """Produce a short summary of a document: first 500 chars and first 3 sentences. No LLM."""
+
+    name = "summarize_document"
+    description = "Summarize document (heuristic: first N chars and first sentences). Uses docproc."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "file_path": {"type": "string", "description": "Path to the document"},
+            "max_chars": {"type": "integer", "description": "Max chars in summary (default 500)"},
+        },
+        "required": ["file_path"],
+    }
+
+    def run(self, **kwargs) -> str:
+        file_path = kwargs.get("file_path")
+        max_chars = kwargs.get("max_chars", 500)
+        if not file_path or not isinstance(file_path, str):
+            return "Error: file_path must be a non-empty string"
+        if not isinstance(max_chars, int) or max_chars < 1:
+            max_chars = 500
+        content, err = run_docproc_to_markdown(file_path)
+        if err:
+            return err
+        content = content.strip()
+        if not content:
+            return "(no content)"
+        head = content[:max_chars] + ("..." if len(content) > max_chars else "")
+        sentences = re.split(r"(?<=[.!?])\s+", content)
+        first = " ".join(sentences[:3]) if sentences else head
+        return f"Summary (first {max_chars} chars):\n{head}\n\nKey sentences:\n{first}"
+
+
+register(SummarizeDocumentTool())

devsper/tools/documents/write_latex_document.py

@@ -0,0 +1,133 @@
+"""Write a structured LaTeX document with optional BibTeX references."""
+
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+def _latex_escape(s: str) -> str:
+    """Escape braces for use inside BibTeX/LaTeX strings."""
+    if not s:
+        return ""
+    return s.replace("\\", "\\\\").replace("{", "\\{").replace("}", "\\}")
+
+
+def _bib_entry(key: str, ref: dict) -> str:
+    """Build one BibTeX entry (article by default)."""
+    author = ref.get("authors") or ref.get("author") or "Unknown"
+    title = ref.get("title") or ""
+    year = ref.get("year") or ""
+    journal = ref.get("journal")
+    url = ref.get("url")
+    publisher = ref.get("publisher")
+    author = _latex_escape(str(author))
+    title = _latex_escape(str(title))
+    year = _latex_escape(str(year))
+    lines = [f"@article{{{key},"]
+    lines.append(f"  author = {{{author}}},")
+    lines.append(f"  title = {{{title}}},")
+    lines.append(f"  year = {{{year}}},")
+    if journal:
+        lines.append(f"  journal = {{{_latex_escape(str(journal))}}},")
+    if publisher:
+        lines.append(f"  publisher = {{{_latex_escape(str(publisher))}}},")
+    if url:
+        lines.append(f"  url = {{{_latex_escape(str(url))}}},")
+    lines.append("}")
+    return "\n".join(lines)
+
+
+class WriteLaTeXDocumentTool(Tool):
+    """Write a structured LaTeX document with optional references. Use \\cite{key} in content."""
+
+    name = "write_latex_document"
+    description = (
+        r"Write a structured LaTeX document with optional references. "
+        r"Use \cite{key} (LaTeX) in content; pass references array (key, authors, title, year, journal, url, publisher) for bibliography. Produces .tex and .bib files."
+    )
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Output path (e.g. report.tex)"},
+            "title": {"type": "string", "description": "Document title"},
+            "content": {"type": "string", "description": r"Body (LaTeX). Use \cite{key} for citations."},
+            "references": {
+                "type": "array",
+                "items": {"type": "object"},
+                "description": "Optional list of refs: key, authors, title, year, journal, url, publisher",
+            },
+        },
+        "required": ["path", "title", "content"],
+    }
+
+    def run(self, **kwargs) -> str:
+        path = kwargs.get("path")
+        title = kwargs.get("title")
+        content = kwargs.get("content")
+        references = kwargs.get("references")
+
+        if not path or not isinstance(path, str) or not path.strip():
+            return "Error: path must be a non-empty string"
+        if not title or not isinstance(title, str):
+            return "Error: title must be a non-empty string"
+        if content is None:
+            return "Error: content is required"
+        if not isinstance(content, str):
+            content = str(content)
+
+        path = path.strip()
+        if not path.endswith(".tex"):
+            path = path.rstrip("/") + ".tex"
+        p = Path(path).resolve()
+        try:
+            p.parent.mkdir(parents=True, exist_ok=True)
+        except Exception as e:
+            return f"Error creating directory: {e}"
+
+        basename = p.stem
+        title_esc = _latex_escape(title)
+
+        tex_parts = [
+            "\\documentclass{article}",
+            "\\begin{document}",
+            "\\title{" + title_esc + "}",
+            "\\maketitle",
+            "",
+            content.strip(),
+            "",
+        ]
+        if references and isinstance(references, list):
+            tex_parts.append("\\bibliographystyle{plain}")
+            tex_parts.append("\\bibliography{" + basename + "}")
+            tex_parts.append("")
+        tex_parts.append("\\end{document}")
+        tex_content = "\n".join(tex_parts)
+
+        try:
+            p.write_text(tex_content, encoding="utf-8")
+        except Exception as e:
+            return f"Error writing .tex file: {e}"
+
+        out_msg = f"Wrote {len(tex_content)} characters to {p}"
+
+        if references and isinstance(references, list):
+            bib_path = p.with_suffix(".bib")
+            bib_entries = []
+            for i, ref in enumerate(references):
+                if not isinstance(ref, dict):
+                    continue
+                key = ref.get("key") or f"ref{i+1}"
+                bib_entries.append(_bib_entry(key, ref))
+            if bib_entries:
+                bib_content = "\n\n".join(bib_entries)
+                try:
+                    bib_path.write_text(bib_content, encoding="utf-8")
+                except Exception as e:
+                    return f"{out_msg}. Error writing .bib file: {e}"
+                out_msg = f"Wrote {p} and {bib_path}. Compile with: pdflatex {basename} && bibtex {basename} && pdflatex {basename} && pdflatex {basename}."
+
+        return out_msg
+
+
+register(WriteLaTeXDocumentTool())

devsper/tools/documents/write_markdown_document.py

@@ -0,0 +1,89 @@
+"""Write a structured Markdown document with optional references section."""
+
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+def _format_ref_md(ref: dict, index: int) -> str:
+    """Format one reference as a Markdown list item."""
+    authors = ref.get("authors") or ref.get("author") or "Unknown"
+    title = ref.get("title") or ""
+    year = ref.get("year") or ""
+    journal = ref.get("journal")
+    url = ref.get("url")
+    parts = [f"**{authors} ({year})**. *{title}*."]
+    if journal:
+        parts.append(f" {journal}.")
+    if url:
+        parts.append(f" [{url}]({url})")
+    return "- " + " ".join(parts).strip()
+
+
+class WriteMarkdownDocumentTool(Tool):
+    """Write a structured Markdown document with optional references. Use [^1] or [Author (Year)] in content."""
+
+    name = "write_markdown_document"
+    description = (
+        "Write a structured Markdown document with optional references. "
+        "Use [1] / Author (Year) in content; pass references array (key, authors, title, year, journal, url, publisher) for bibliography. Produces .md file."
+    )
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Output path (e.g. report.md)"},
+            "title": {"type": "string", "description": "Document title"},
+            "content": {"type": "string", "description": "Body (markdown). Use [^1] or [Author (Year)] for citations."},
+            "references": {
+                "type": "array",
+                "items": {"type": "object"},
+                "description": "Optional list of refs: key, authors, title, year, journal, url, publisher",
+            },
+        },
+        "required": ["path", "title", "content"],
+    }
+
+    def run(self, **kwargs) -> str:
+        path = kwargs.get("path")
+        title = kwargs.get("title")
+        content = kwargs.get("content")
+        references = kwargs.get("references")
+
+        if not path or not isinstance(path, str) or not path.strip():
+            return "Error: path must be a non-empty string"
+        if not title or not isinstance(title, str):
+            return "Error: title must be a non-empty string"
+        if content is None:
+            return "Error: content is required"
+        if not isinstance(content, str):
+            content = str(content)
+
+        path = path.strip()
+        if not path.endswith(".md") and not path.endswith(".markdown"):
+            path = path.rstrip("/") + ".md"
+        p = Path(path).resolve()
+        try:
+            p.parent.mkdir(parents=True, exist_ok=True)
+        except Exception as e:
+            return f"Error creating directory: {e}"
+
+        parts = [f"# {title.strip()}", "", content.strip(), ""]
+        if references and isinstance(references, list):
+            parts.append("## References")
+            parts.append("")
+            for i, ref in enumerate(references):
+                if not isinstance(ref, dict):
+                    continue
+                parts.append(_format_ref_md(ref, i))
+            parts.append("")
+
+        full = "\n".join(parts)
+        try:
+            p.write_text(full, encoding="utf-8")
+        except Exception as e:
+            return f"Error writing file: {e}"
+        return f"Wrote {len(full)} characters to {p}"
+
+
+register(WriteMarkdownDocumentTool())

devsper/tools/documents/write_word_document.py

@@ -0,0 +1,149 @@
+"""Write a structured Word document with optional references section and proper citation formatting."""
+
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+def _add_hyperlink(paragraph, text: str, url: str):
+    """Add a hyperlink run to a paragraph (python-docx has no built-in add_hyperlink)."""
+    from docx.oxml import OxmlElement
+    from docx.oxml.ns import qn
+
+    part = paragraph.part
+    r_id = part.relate_to(
+        url,
+        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink",
+        is_external=True,
+    )
+    hyperlink = OxmlElement("w:hyperlink")
+    hyperlink.set(qn("r:id"), r_id)
+    new_run = OxmlElement("w:r")
+    r_pr = OxmlElement("w:rPr")
+    u = OxmlElement("w:u")
+    u.set(qn("w:val"), "single")
+    color = OxmlElement("w:color")
+    color.set(qn("w:val"), "0563C1")
+    r_pr.append(u)
+    r_pr.append(color)
+    new_run.append(r_pr)
+    t = OxmlElement("w:t")
+    t.set(qn("xml:space"), "preserve")
+    t.text = text
+    new_run.append(t)
+    hyperlink.append(new_run)
+    paragraph._p.append(hyperlink)
+
+
+def _add_reference_paragraph(doc, number: int, ref: dict) -> None:
+    """Add one reference as a numbered paragraph with APA-like formatting and optional hyperlink."""
+    from docx.shared import Pt
+
+    authors = ref.get("authors") or ref.get("author") or "Unknown"
+    title = ref.get("title") or ""
+    year = ref.get("year") or ""
+    journal = ref.get("journal")
+    url = ref.get("url")
+    publisher = ref.get("publisher")
+
+    para = doc.add_paragraph()
+    para.paragraph_format.left_indent = Pt(18)
+    para.paragraph_format.first_line_indent = Pt(-18)
+    para.paragraph_format.space_after = Pt(6)
+
+    run = para.add_run(f"[{number}] ")
+    run.bold = True
+
+    para.add_run(f"{authors} ({year}). ")
+
+    r_title = para.add_run(f"{title}.")
+    r_title.italic = True
+    para.add_run(" ")
+
+    if journal:
+        r_journal = para.add_run(f" {journal}.")
+        r_journal.italic = True
+    if publisher:
+        para.add_run(f" {publisher}.")
+    if url:
+        para.add_run(" ")
+        _add_hyperlink(para, url if len(url) < 50 else "Link", url)
+
+
+class WriteWordDocumentTool(Tool):
+    """Write a structured Word document with optional references. Use [1], [2] in content to match numbered refs."""
+
+    name = "write_word_document"
+    description = (
+        "Write a structured Word document with optional references. "
+        "Use [1] / Author (Year) (Word/MD) in content; pass references array (key, authors, title, year, journal, url, publisher) for bibliography. Produces .docx. Requires: pip install devsper[document]."
+    )
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Output path (e.g. report.docx)"},
+            "title": {"type": "string", "description": "Document title"},
+            "content": {"type": "string", "description": "Body (plain or markdown-style newlines). Use [1], [2] for citations."},
+            "references": {
+                "type": "array",
+                "items": {"type": "object"},
+                "description": "Optional list of refs: key, authors, title, year, journal, url, publisher",
+            },
+        },
+        "required": ["path", "title", "content"],
+    }
+
+    def run(self, **kwargs) -> str:
+        try:
+            from docx import Document
+        except ImportError:
+            return "Word export requires the document extra: pip install devsper[document]"
+
+        path = kwargs.get("path")
+        title = kwargs.get("title")
+        content = kwargs.get("content")
+        references = kwargs.get("references")
+
+        if not path or not isinstance(path, str) or not path.strip():
+            return "Error: path must be a non-empty string"
+        if not title or not isinstance(title, str):
+            return "Error: title must be a non-empty string"
+        if content is None:
+            return "Error: content is required"
+        if not isinstance(content, str):
+            content = str(content)
+
+        path = path.strip()
+        if not path.endswith(".docx"):
+            path = path.rstrip("/") + ".docx"
+        p = Path(path).resolve()
+        try:
+            p.parent.mkdir(parents=True, exist_ok=True)
+        except Exception as e:
+            return f"Error creating directory: {e}"
+
+        doc = Document()
+        doc.add_heading(title.strip(), level=0)
+        for block in content.strip().split("\n\n"):
+            block = block.strip()
+            if block:
+                doc.add_paragraph(block)
+
+        if references and isinstance(references, list):
+            doc.add_heading("References", level=1)
+            num = 0
+            for ref in references:
+                if not isinstance(ref, dict):
+                    continue
+                num += 1
+                _add_reference_paragraph(doc, num, ref)
+
+        try:
+            doc.save(str(p))
+        except Exception as e:
+            return f"Error writing file: {e}"
+        return f"Wrote {p}"
+
+
+register(WriteWordDocumentTool())

devsper/tools/experiments/__init__.py

@@ -0,0 +1,13 @@
+"""Experimentation tools: parameter sweep, grid search, tracking, benchmarks, Monte Carlo."""
+
+from devsper.tools.experiments.parameter_sweep_runner import ParameterSweepRunnerTool
+from devsper.tools.experiments.grid_search_runner import GridSearchRunnerTool
+from devsper.tools.experiments.experiment_tracker import ExperimentTrackerTool
+from devsper.tools.experiments.result_comparator import ResultComparatorTool
+from devsper.tools.experiments.model_benchmark_runner import ModelBenchmarkRunnerTool
+from devsper.tools.experiments.simulation_runner import SimulationRunnerTool
+from devsper.tools.experiments.monte_carlo_experiment import MonteCarloExperimentTool
+from devsper.tools.experiments.statistical_significance_test import StatisticalSignificanceTestTool
+from devsper.tools.experiments.bootstrap_estimator import BootstrapEstimatorTool
+from devsper.tools.experiments.experiment_report_generator import ExperimentReportGeneratorTool
+from devsper.tools.experiments.swarm_map_reduce import SwarmMapReduceTool

devsper/tools/experiments/bootstrap_estimator.py

@@ -0,0 +1,54 @@
+"""Bootstrap estimate: resample with replacement B times and report mean and CI (percentile)."""
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+import random
+
+
+class BootstrapEstimatorTool(Tool):
+    """
+    Bootstrap: resample with replacement B times, compute statistic (mean) each time; report mean and percentile CI.
+    """
+
+    name = "bootstrap_estimator"
+    description = "Bootstrap resampling: report mean and percentile confidence interval."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "values": {"type": "array", "items": {"type": "number"}, "description": "Sample data"},
+            "n_bootstrap": {"type": "integer", "description": "Number of bootstrap samples (default 200)"},
+            "confidence": {"type": "number", "description": "CI level (default 0.95)"},
+        },
+        "required": ["values"],
+    }
+
+    def run(self, **kwargs) -> str:
+        values = kwargs.get("values")
+        n_bootstrap = kwargs.get("n_bootstrap", 200)
+        confidence = kwargs.get("confidence", 0.95)
+        if not values or not isinstance(values, list):
+            return "Error: values must be a non-empty list of numbers"
+        if not isinstance(n_bootstrap, int) or n_bootstrap < 1:
+            n_bootstrap = 200
+        if not isinstance(confidence, (int, float)) or confidence <= 0 or confidence >= 1:
+            confidence = 0.95
+        try:
+            data = [float(x) for x in values]
+        except (ValueError, TypeError):
+            return "Error: all values must be numeric"
+        if len(data) < 2:
+            return "Error: need at least 2 values"
+        n = len(data)
+        means = []
+        for _ in range(n_bootstrap):
+            sample = random.choices(data, k=n)
+            means.append(sum(sample) / n)
+        means.sort()
+        alpha = 1 - confidence
+        lo = means[int(alpha / 2 * n_bootstrap)]
+        hi = means[int((1 - alpha / 2) * n_bootstrap)]
+        point = sum(data) / len(data)
+        return f"Bootstrap (n={len(data)}, B={n_bootstrap}): point estimate={point:.4f}, {int(confidence*100)}% CI = [{lo:.4f}, {hi:.4f}]"
+
+
+register(BootstrapEstimatorTool())

devsper/tools/experiments/experiment_report_generator.py

@@ -0,0 +1,50 @@
+"""Generate a text report from experiment results (runs and metrics)."""
+
+import json
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class ExperimentReportGeneratorTool(Tool):
+    """
+    Generate a human-readable experiment report from a list of runs with params and metrics.
+    """
+
+    name = "experiment_report_generator"
+    description = "Generate a text report from experiment results (runs, params, metrics)."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "runs": {
+                "type": "array",
+                "items": {"type": "object"},
+                "description": "List of {run_id, params, metrics}",
+            },
+            "title": {"type": "string", "description": "Report title"},
+        },
+        "required": ["runs"],
+    }
+
+    def run(self, **kwargs) -> str:
+        runs = kwargs.get("runs")
+        title = kwargs.get("title") or "Experiment Report"
+        if not runs or not isinstance(runs, list):
+            return "Error: runs must be a non-empty list of {run_id, params, metrics}"
+        lines = [title, "=" * 40, f"Total runs: {len(runs)}", ""]
+        for i, r in enumerate(runs):
+            if not isinstance(r, dict):
+                continue
+            run_id = r.get("run_id", f"run_{i}")
+            params = r.get("params", {})
+            metrics = r.get("metrics", r)
+            lines.append(f"Run: {run_id}")
+            if params:
+                lines.append("  Params: " + json.dumps(params))
+            if metrics and isinstance(metrics, dict):
+                lines.append("  Metrics: " + json.dumps(metrics))
+            lines.append("")
+        return "\n".join(lines)
+
+
+register(ExperimentReportGeneratorTool())

devsper/tools/experiments/experiment_tracker.py

@@ -0,0 +1,36 @@
+"""Track experiments: append or list experiment runs (in-memory or structured output for logging)."""
+
+import json
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class ExperimentTrackerTool(Tool):
+    """
+    Track experiment runs: record run_id, params, metric and return a log entry. Stateless; returns structured log.
+    """
+
+    name = "experiment_tracker"
+    description = "Record an experiment run (run_id, params, metrics) and return log entry."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "run_id": {"type": "string", "description": "Run identifier"},
+            "params": {"type": "object", "description": "Parameters used"},
+            "metrics": {"type": "object", "description": "Metrics (e.g. accuracy, loss)"},
+        },
+        "required": ["run_id"],
+    }
+
+    def run(self, **kwargs) -> str:
+        run_id = kwargs.get("run_id")
+        params = kwargs.get("params") or {}
+        metrics = kwargs.get("metrics") or {}
+        if not run_id or not isinstance(run_id, str):
+            return "Error: run_id must be a non-empty string"
+        entry = {"run_id": run_id, "params": params, "metrics": metrics}
+        return json.dumps({"logged": entry}, indent=2)
+
+
+register(ExperimentTrackerTool())

devsper/tools/experiments/grid_search_runner.py

@@ -0,0 +1,50 @@
+"""Grid search: same as parameter sweep, return grid of (param, value) combinations."""
+
+import json
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class GridSearchRunnerTool(Tool):
+    """
+    Generate grid search combinations (full Cartesian product of parameter values).
+    """
+
+    name = "grid_search_runner"
+    description = "Generate grid search parameter combinations (Cartesian product)."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "param_grid": {
+                "type": "object",
+                "description": "Map of param name -> list of values",
+            },
+            "max_combinations": {"type": "integer", "description": "Cap (default 50)"},
+        },
+        "required": ["param_grid"],
+    }
+
+    def run(self, **kwargs) -> str:
+        param_grid = kwargs.get("param_grid")
+        max_combinations = kwargs.get("max_combinations", 50)
+        if not param_grid or not isinstance(param_grid, dict):
+            return "Error: param_grid must be a dict of param name -> list of values"
+        if not isinstance(max_combinations, int) or max_combinations < 1:
+            max_combinations = 50
+        names = list(param_grid.keys())
+        values = []
+        for n in names:
+            v = param_grid[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]
+        return json.dumps({"grid_size": len(result), "combinations": result}, indent=2)
+
+
+register(GridSearchRunnerTool())