devsper 2.1.6__py3-none-any.whl

devsper/tools/research_advanced/paper_trend_analyzer.py

@@ -0,0 +1,69 @@
+"""Analyze trends in papers by extracting years and term frequency over time (by document)."""
+
+import re
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+from devsper.tools.documents._docproc import run_docproc_to_markdown
+
+YEAR_PAT = re.compile(r"\b(19\d{2}|20\d{2})\b")
+STOP = frozenset("a an the and or but in on at to for of with by from as is was are were been be have has had do does did will would could should may might must can this that it its".split())
+
+
+class PaperTrendAnalyzerTool(Tool):
+    """
+    Extract publication years from documents and aggregate term frequency by year (filename or content).
+    """
+
+    name = "paper_trend_analyzer"
+    description = "Analyze trends: years and term frequency across papers."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "file_paths": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Paths to papers",
+            },
+            "top_terms": {"type": "integer", "description": "Top N terms overall (default 15)"},
+        },
+        "required": ["file_paths"],
+    }
+
+    def run(self, **kwargs) -> str:
+        file_paths = kwargs.get("file_paths")
+        top_terms = kwargs.get("top_terms", 15)
+        if not file_paths or not isinstance(file_paths, list):
+            return "Error: file_paths must be a non-empty list"
+        if not isinstance(top_terms, int) or top_terms < 1:
+            top_terms = 15
+        year_to_terms = {}
+        global_count = {}
+        for path in file_paths:
+            if not isinstance(path, str) or not path.strip():
+                continue
+            p = Path(path.strip()).resolve()
+            if not p.exists() or not p.is_file():
+                continue
+            content, err = run_docproc_to_markdown(str(p))
+            if err:
+                continue
+            text = content or ""
+            years = YEAR_PAT.findall(text)
+            year = years[0] if years else "unknown"
+            if year not in year_to_terms:
+                year_to_terms[year] = []
+            words = [w for w in re.findall(r"[a-z]+", text.lower()) if len(w) >= 4 and w not in STOP]
+            from collections import Counter
+
+            year_to_terms[year].extend(words)
+            for w in words:
+                global_count[w] = global_count.get(w, 0) + 1
+        sorted_terms = sorted(global_count.items(), key=lambda x: -x[1])[:top_terms]
+        lines = ["Trend analysis", "=" * 40, "Documents by year: " + ", ".join(sorted(year_to_terms.keys()))]
+        lines.append("Global top terms: " + ", ".join(t for t, _ in sorted_terms))
+        return "\n".join(lines)
+
+
+register(PaperTrendAnalyzerTool())

devsper/tools/research_advanced/parallel_document_analyzer.py

@@ -0,0 +1,56 @@
+"""Analyze multiple documents in batches (swarm-friendly: split into chunks for parallel workers)."""
+
+import json
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+from devsper.tools.documents._docproc import run_docproc_to_markdown, DOCPROC_EXTENSIONS
+
+
+class ParallelDocumentAnalyzerTool(Tool):
+    """
+    Split a list of documents into batches for parallel analysis (e.g. by a swarm).
+    Returns batch assignments and per-batch file lists; does not run docproc itself.
+    """
+
+    name = "parallel_document_analyzer"
+    description = "Split documents into batches for parallel/swarm analysis. Returns batch plan."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "file_paths": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Paths to documents",
+            },
+            "directory": {"type": "string", "description": "Or directory to scan for docs"},
+            "batch_size": {"type": "integer", "description": "Documents per batch (default 5)"},
+        },
+        "required": [],
+    }
+
+    def run(self, **kwargs) -> str:
+        file_paths = kwargs.get("file_paths")
+        directory = kwargs.get("directory")
+        batch_size = kwargs.get("batch_size", 5)
+        if not isinstance(batch_size, int) or batch_size < 1:
+            batch_size = 5
+        paths = []
+        if file_paths and isinstance(file_paths, list):
+            paths = [p for p in file_paths if isinstance(p, str) and p.strip()]
+        if directory and isinstance(directory, str):
+            d = Path(directory).resolve()
+            if d.exists() and d.is_dir():
+                for ext in DOCPROC_EXTENSIONS:
+                    paths.extend(str(p) for p in d.rglob(f"*{ext}"))
+        if not paths:
+            return "Error: provide file_paths or directory"
+        batches = []
+        for i in range(0, len(paths), batch_size):
+            batches.append(paths[i : i + batch_size])
+        result = {"total_documents": len(paths), "batch_size": batch_size, "num_batches": len(batches), "batches": batches}
+        return json.dumps(result, indent=2)
+
+
+register(ParallelDocumentAnalyzerTool())

devsper/tools/research_advanced/research_gap_finder.py

@@ -0,0 +1,71 @@
+"""Identify potential research gaps by comparing question-like sentences and missing terms across papers."""
+
+import re
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+from devsper.tools.documents._docproc import run_docproc_to_markdown
+
+STOP = frozenset("a an the and or but in on at to for of with by from as is was are were been be have has had do does did will would could should may might must can this that it its we they".split())
+
+
+class ResearchGapFinderTool(Tool):
+    """
+    Suggest research gaps: question phrases in papers and terms that appear in few documents.
+    """
+
+    name = "research_gap_finder"
+    description = "Identify potential research gaps from question phrases and rare terms across papers."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "file_paths": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Paths to papers",
+            },
+            "min_doc_freq": {"type": "integer", "description": "Term in fewer than N docs = gap candidate (default 2)"},
+        },
+        "required": ["file_paths"],
+    }
+
+    def run(self, **kwargs) -> str:
+        file_paths = kwargs.get("file_paths")
+        min_doc_freq = kwargs.get("min_doc_freq", 2)
+        if not file_paths or not isinstance(file_paths, list):
+            return "Error: file_paths must be a non-empty list"
+        if not isinstance(min_doc_freq, int) or min_doc_freq < 1:
+            min_doc_freq = 2
+        question_pat = re.compile(r"[^.!?]*\?+[^.!?]*")
+        doc_terms = []
+        all_questions = []
+        for path in file_paths:
+            if not isinstance(path, str) or not path.strip():
+                continue
+            p = Path(path.strip()).resolve()
+            if not p.exists() or not p.is_file():
+                continue
+            content, err = run_docproc_to_markdown(str(p))
+            if err:
+                continue
+            text = content or ""
+            questions = question_pat.findall(text)
+            all_questions.extend(q.strip()[:100] for q in questions if len(q.strip()) > 10)
+            words = {w for w in re.findall(r"[a-z]+", text.lower()) if len(w) >= 4 and w not in STOP}
+            doc_terms.append((p.name, words))
+        term_doc_count = {}
+        for _, words in doc_terms:
+            for w in words:
+                term_doc_count[w] = term_doc_count.get(w, 0) + 1
+        gap_terms = [w for w, c in term_doc_count.items() if c < min_doc_freq][:20]
+        lines = ["Research gap indicators", "=" * 40]
+        if all_questions:
+            lines.append("Question phrases (research questions):")
+            for q in all_questions[:10]:
+                lines.append(f"  - {q}")
+        lines.append("\nRare terms (in few documents): " + ", ".join(gap_terms[:15]))
+        return "\n".join(lines)
+
+
+register(ResearchGapFinderTool())

devsper/tools/research_advanced/research_topic_mapper.py

@@ -0,0 +1,69 @@
+"""Map research topics across documents: term frequency and co-occurrence style groups."""
+
+import re
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+from devsper.tools.documents._docproc import run_docproc_to_markdown
+
+STOP = frozenset("a an the and or but in on at to for of with by from as is was are were been be have has had do does did will would could should may might must can this that it its".split())
+
+
+class ResearchTopicMapperTool(Tool):
+    """
+    Map topics across documents: high-frequency terms per doc and shared terms.
+    """
+
+    name = "research_topic_mapper"
+    description = "Map research topics across documents (term frequency and shared terms)."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "file_paths": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Paths to papers",
+            },
+            "top_per_doc": {"type": "integer", "description": "Top N terms per doc (default 10)"},
+        },
+        "required": ["file_paths"],
+    }
+
+    def run(self, **kwargs) -> str:
+        file_paths = kwargs.get("file_paths")
+        top_per_doc = kwargs.get("top_per_doc", 10)
+        if not file_paths or not isinstance(file_paths, list):
+            return "Error: file_paths must be a non-empty list"
+        if not isinstance(top_per_doc, int) or top_per_doc < 1:
+            top_per_doc = 10
+        doc_topics = {}
+        all_terms = set()
+        for path in file_paths:
+            if not isinstance(path, str) or not path.strip():
+                continue
+            p = Path(path.strip()).resolve()
+            if not p.exists() or not p.is_file():
+                continue
+            content, err = run_docproc_to_markdown(str(p))
+            if err:
+                continue
+            words = [w for w in re.findall(r"[a-z]+", (content or "").lower()) if len(w) >= 4 and w not in STOP]
+            from collections import Counter
+
+            top = [w for w, _ in Counter(words).most_common(top_per_doc)]
+            doc_topics[p.name] = top
+            all_terms.update(top)
+        shared = []
+        for t in all_terms:
+            count = sum(1 for tops in doc_topics.values() if t in tops)
+            if count > 1:
+                shared.append(t)
+        lines = ["Topic map", "=" * 40]
+        for name, topics in doc_topics.items():
+            lines.append(f"{name}: " + ", ".join(topics))
+        lines.append("\nShared topics: " + ", ".join(shared[:20]))
+        return "\n".join(lines)
+
+
+register(ResearchTopicMapperTool())

devsper/tools/research_advanced/swarm_literature_review.py

@@ -0,0 +1,58 @@
+"""Plan a swarm-based literature review: assign document subsets and themes to batches."""
+
+import json
+import re
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+STOP = frozenset("a an the and or but in on at to for of with by from as is was are were been be have has had do does did will would could should may might must can this that it its".split())
+
+
+class SwarmLiteratureReviewTool(Tool):
+    """
+    Plan a literature review for a swarm: split documents into batches and suggest theme keywords per batch.
+    Accepts raw text list (e.g. from prior extraction); does not read files.
+    """
+
+    name = "swarm_literature_review"
+    description = "Plan swarm-based literature review: batch assignments and theme keywords per batch."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "texts": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Document texts or abstracts (one per item)",
+            },
+            "batch_size": {"type": "integer", "description": "Texts per batch (default 3)"},
+            "top_keywords_per_batch": {"type": "integer", "description": "Theme keywords per batch (default 5)"},
+        },
+        "required": ["texts"],
+    }
+
+    def run(self, **kwargs) -> str:
+        texts = kwargs.get("texts")
+        batch_size = kwargs.get("batch_size", 3)
+        top_k = kwargs.get("top_keywords_per_batch", 5)
+        if not texts or not isinstance(texts, list):
+            return "Error: texts must be a non-empty list of strings"
+        if not isinstance(batch_size, int) or batch_size < 1:
+            batch_size = 3
+        if not isinstance(top_k, int) or top_k < 1:
+            top_k = 5
+        batches = []
+        for i in range(0, len(texts), batch_size):
+            batch_texts = [t for t in texts[i : i + batch_size] if isinstance(t, str) and t.strip()]
+            combined = " ".join(batch_texts).lower()
+            words = [w for w in re.findall(r"[a-z]+", combined) if len(w) >= 4 and w not in STOP]
+            from collections import Counter
+
+            keywords = [w for w, _ in Counter(words).most_common(top_k)]
+            batches.append({"batch_index": len(batches), "num_docs": len(batch_texts), "theme_keywords": keywords})
+        result = {"total_documents": len(texts), "batch_size": batch_size, "batches": batches}
+        return json.dumps(result, indent=2)
+
+
+register(SwarmLiteratureReviewTool())

devsper/tools/scoring/__init__.py

@@ -0,0 +1,52 @@
+"""
+Tool reliability scoring: record results, get scores, blended selection.
+"""
+
+from devsper.tools.scoring.store import ToolScore, ToolScoreStore
+
+_default_store: ToolScoreStore | None = None
+
+
+def get_default_score_store() -> ToolScoreStore:
+    """Return the default tool score store (singleton)."""
+    global _default_store
+    if _default_store is None:
+        _default_store = ToolScoreStore()
+    return _default_store
+
+
+def record_tool_result(
+    tool_name: str,
+    task_type: str | None,
+    success: bool,
+    latency_ms: int | None = None,
+    error_type: str | None = None,
+) -> None:
+    """Record one tool execution result (success/failure, latency) into the score store."""
+    try:
+        get_default_score_store().record(
+            tool_name=tool_name,
+            task_type=task_type,
+            success=success,
+            latency_ms=latency_ms,
+            error_type=error_type,
+        )
+    except Exception:
+        pass
+
+
+def get_tool_score(tool_name: str) -> ToolScore | None:
+    """Return the current ToolScore for a tool, or None if not tracked."""
+    try:
+        return get_default_score_store().get_score(tool_name)
+    except Exception:
+        return None
+
+
+__all__ = [
+    "record_tool_result",
+    "get_tool_score",
+    "get_default_score_store",
+    "ToolScoreStore",
+    "ToolScore",
+]

devsper/tools/scoring/report.py

@@ -0,0 +1,44 @@
+"""
+Formatting for devsper tools CLI output and analytics summary.
+"""
+
+from devsper.tools.scoring.scorer import score_label
+from devsper.tools.scoring.store import ToolScore
+
+
+def generate_tools_report(scores: list[ToolScore]) -> str:
+    """
+    Summary header: total tools, % excellent/good/degraded/poor;
+    highlight top 3 and bottom 3 tools.
+    """
+    if not scores:
+        return "No tool scores recorded."
+    total = len(scores)
+    excellent = sum(1 for s in scores if s.composite_score >= 0.85)
+    good = sum(1 for s in scores if 0.65 <= s.composite_score < 0.85)
+    degraded = sum(1 for s in scores if 0.40 <= s.composite_score < 0.65)
+    poor = sum(1 for s in scores if s.composite_score < 0.40)
+    p_ex = (excellent / total * 100) if total else 0
+    p_good = (good / total * 100) if total else 0
+    p_deg = (degraded / total * 100) if total else 0
+    p_poor = (poor / total * 100) if total else 0
+    lines = [
+        f"Tool reliability: {total} tools tracked",
+        f"  excellent: {p_ex:.0f}%  good: {p_good:.0f}%  degraded: {p_deg:.0f}%  poor: {p_poor:.0f}%",
+        "",
+    ]
+    sorted_scores = sorted(scores, key=lambda s: -s.composite_score)
+    top3 = sorted_scores[:3]
+    bottom3 = sorted_scores[-3:] if len(sorted_scores) >= 3 else sorted_scores
+    if top3:
+        lines.append("Top 3:")
+        for s in top3:
+            label = score_label(s.composite_score)
+            lines.append(f"  {s.tool_name}: {s.composite_score:.2f} ({label})")
+        lines.append("")
+    if bottom3 and (len(bottom3) < len(top3) or bottom3[0].tool_name != top3[0].tool_name):
+        lines.append("Bottom 3:")
+        for s in reversed(bottom3):
+            label = score_label(s.composite_score)
+            lines.append(f"  {s.tool_name}: {s.composite_score:.2f} ({label})")
+    return "\n".join(lines)

devsper/tools/scoring/scorer.py

@@ -0,0 +1,39 @@
+"""
+ToolScorer: compute composite score from raw stats.
+"""
+
+
+def _clamp(x: float, lo: float, hi: float) -> float:
+    return max(lo, min(hi, x))
+
+
+def compute_composite_score(stats: dict) -> float:
+    """
+    Compute composite reliability score from stats dict with keys:
+    success_rate, avg_latency_ms, total_calls, recent_failures.
+    Returns 0.05--1.0.
+    """
+    total_calls = stats.get("total_calls", 0)
+    if total_calls < 5:
+        return 0.75
+    success_rate = stats.get("success_rate", 0.0)
+    if success_rate == 0.0 and total_calls >= 10:
+        return 0.05
+    avg_latency_ms = stats.get("avg_latency_ms", 0.0)
+    recent_failures = stats.get("recent_failures", 0)
+    reliability = success_rate
+    speed = 1.0 - _clamp(avg_latency_ms / 10000.0, 0.0, 1.0)
+    recency = 1.0 - (recent_failures / 20.0)
+    composite = (reliability * 0.50) + (speed * 0.30) + (recency * 0.20)
+    return _clamp(composite, 0.05, 1.0)
+
+
+def score_label(score: float) -> str:
+    """Return label for a composite score."""
+    if score >= 0.85:
+        return "excellent"
+    if score >= 0.65:
+        return "good"
+    if score >= 0.40:
+        return "degraded"
+    return "poor"

devsper/tools/scoring/selector.py

@@ -0,0 +1,61 @@
+"""
+Updated top-k selection: similarity × reliability (blended score).
+"""
+
+import os
+
+from devsper.memory.embeddings import embed_text
+from devsper.tools.base import Tool
+
+from devsper.tools.scoring.store import ToolScoreStore, ToolScore
+
+
+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 select_tools_scored(
+    task_description: str,
+    available_tools: list[Tool],
+    top_k: int,
+    score_store: ToolScoreStore | None,
+) -> list[Tool]:
+    """
+    Select top_k tools by blended score: 70% similarity + 30% reliability.
+    New tools (< 5 calls) get neutral 0.75 reliability. If DEVSPER_DISABLE_TOOL_SCORING=1
+    or score_store is None, ranking is similarity-only.
+    """
+    if not available_tools:
+        return []
+    if top_k <= 0:
+        return available_tools
+
+    disable = os.environ.get("DEVSPER_DISABLE_TOOL_SCORING", "").strip() == "1"
+    use_reliability = not disable and score_store is not None
+
+    task_embedding = embed_text(task_description or " ")
+    tool_texts = [f"{t.name}: {t.description}" for t in available_tools]
+    tool_embeddings = [embed_text(t) for t in tool_texts]
+
+    scored: list[tuple[Tool, float]] = []
+    for tool, te in zip(available_tools, tool_embeddings):
+        sim = _cosine_similarity(task_embedding, te)
+        if use_reliability:
+            ts = score_store.get_score(tool.name)
+            reliability = (
+                ts.composite_score if ts and not ts.is_new else 0.75
+            )
+            blended = (sim * 0.70) + (reliability * 0.30)
+        else:
+            blended = sim
+        scored.append((tool, blended))
+
+    scored.sort(key=lambda x: -x[1])
+    return [t for t, _ in scored[:top_k]]