skelpr 0.1.0__py3-none-any.whl

skelpr/__init__.py

@@ -0,0 +1,5 @@
+"""Skelpr: Fully local, paid-API-free AI development assistant."""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

skelpr/agents/bug_fix_agent.py

@@ -0,0 +1,251 @@
+"""Bug-fix agent: issue -> grounded root-cause hypothesis + minimal edits.
+
+Flow:
+  1. Retrieve context from the hybrid index (chunks, symbols, graph).
+  2. Ask the model for a diagnosis + edits (first pass).
+  3. If edits are missing or any find-string doesn't match the real file,
+     read the actual file(s) in full and retry once with exact source injected.
+  4. If the model returned empty/garbage, extract candidate files from the
+     issue text and inject them for the retry pass.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ..models.model_router import ModelRouter, Task
+from ..models.prompt_templates import bug_fix_messages
+from ..patches.diff_generator import Edit
+from ..retrieval.context_builder import build_context, context_is_sufficient
+from ..retrieval.hybrid_retriever import HybridRetriever
+from ..utils.errors import ModelError
+from ..utils.logging import get_logger
+
+log = get_logger(__name__)
+
+_ERR_TERM = re.compile(r"[A-Za-z_][A-Za-z0-9_]{3,}")
+_TRACE_FILE = re.compile(r'File "([^"]+)", line (\d+)')
+
+# How many chars of each real file to inject on the retry pass.
+_MAX_FILE_INJECT_CHARS = 12_000
+
+# File extension pattern used to find candidate files in the issue text.
+_FILE_PATTERN = re.compile(
+    r"\b([\w/\\.-]+\.(?:js|ts|tsx|jsx|py|css|scss|sass|java|go|rs|vue|svelte))\b"
+)
+# CamelCase component/class names (e.g. CategoryManagement, AdminPanel)
+_COMPONENT_PATTERN = re.compile(r"\b([A-Z][a-zA-Z]{3,})\b")
+_CODE_EXTENSIONS = {".js", ".ts", ".tsx", ".jsx", ".py", ".css", ".scss",
+                    ".sass", ".java", ".go", ".rs", ".vue", ".svelte"}
+
+
+def _error_terms(issue: str, stack_trace: str | None) -> list[str]:
+    blob = f"{issue}\n{stack_trace or ''}"
+    quoted = re.findall(r"[\"'`]([^\"'`]{3,60})[\"'`]", blob)
+    errors = re.findall(r"\b(\w*(?:Error|Exception|Warning))\b", blob)
+    idents: list[str] = []
+    for m in _ERR_TERM.finditer(issue):
+        idents.append(m.group(0))
+    seen: list[str] = []
+    for t in errors + quoted + idents:
+        t = t.strip()
+        if t and t not in seen:
+            seen.append(t)
+    return seen[:12]
+
+
+def _parse_edits(raw: dict) -> list[Edit]:
+    return [
+        Edit(file=e.get("file", ""), find=e.get("find", ""),
+             replace=e.get("replace", ""), reason=e.get("reason", ""))
+        for e in raw.get("edits", []) if isinstance(e, dict)
+    ]
+
+
+def _extract_files_from_issue(issue: str, root: Path) -> list[str]:
+    """Find files that exist in the repo and are mentioned in the issue text.
+
+    Looks for:
+    - Explicit file paths with extensions (e.g. app/containers/Foo/index.js)
+    - CamelCase component/class names (e.g. CategoryManagement -> CategoryManagement/index.js)
+    """
+    result: list[str] = []
+
+    # 1. Explicit file references with extensions
+    for m in _FILE_PATTERN.finditer(issue):
+        name = Path(m.group(1)).name
+        for p in root.rglob(name):
+            try:
+                rel = str(p.relative_to(root)).replace("\\", "/")
+            except ValueError:
+                continue
+            if rel not in result:
+                result.append(rel)
+
+    # 2. CamelCase component/class names — search for files whose path contains the name
+    for m in _COMPONENT_PATTERN.finditer(issue):
+        name = m.group(1)
+        for p in root.rglob(f"*{name}*"):
+            if p.suffix in _CODE_EXTENSIONS:
+                try:
+                    rel = str(p.relative_to(root)).replace("\\", "/")
+                except ValueError:
+                    continue
+                if rel not in result:
+                    result.append(rel)
+
+    return result[:4]
+
+
+def _files_needing_injection(edits: list[Edit], affected: list[str],
+                              root: Path) -> list[str]:
+    """Return files that need full-source injection:
+    - any file in affected_files the model didn't produce edits for, OR
+    - any file whose find-string doesn't exist in the real file.
+    """
+    needed: list[str] = []
+
+    edit_files = {e.file for e in edits if e.file}
+    for f in affected:
+        if f not in edit_files and f not in needed:
+            needed.append(f)
+
+    for e in edits:
+        if not e.find or not e.file or e.file in needed:
+            continue
+        fp = root / e.file
+        if not fp.exists():
+            continue
+        try:
+            text = fp.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        # Simple check if find string exists (exact match only)
+        # The patching system will handle fuzzy matching if needed
+        if e.find not in text:
+            needed.append(e.file)
+
+    return needed
+
+
+def _inject_file_content(root: Path, files: list[str],
+                         base_context: str) -> str:
+    parts = [base_context]
+    for rel in files:
+        fp = root / rel
+        try:
+            src = fp.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        snippet = src[:_MAX_FILE_INJECT_CHARS]
+        if len(src) > _MAX_FILE_INJECT_CHARS:
+            snippet += f"\n... (file truncated at {_MAX_FILE_INJECT_CHARS} chars)"
+        parts.append(
+            f"\n\n# FULL SOURCE of {rel} "
+            f"(your find-strings MUST be verbatim substrings from this):\n{snippet}"
+        )
+    return "".join(parts)
+
+
+def _raw_is_empty(raw: dict) -> bool:
+    """True when the model returned a dict with no useful diagnosis content."""
+    return not (raw.get("root_cause") or raw.get("plan") or
+                raw.get("edits") or raw.get("affected_files"))
+
+
+@dataclass
+class Diagnosis:
+    root_cause: str
+    affected_files: list[str]
+    plan: str
+    risk: str
+    edits: list[Edit] = field(default_factory=list)
+    sufficient_context: bool = True
+    backends: dict[str, str] = field(default_factory=dict)
+
+
+class BugFixAgent:
+    def __init__(self, retriever: HybridRetriever, router: ModelRouter,
+                 max_context_tokens: int = 6000):
+        self._retriever = retriever
+        self._router = router
+        self._max_ctx = max_context_tokens
+
+    def _safe_complete_json(self, task: Task, messages: list) -> dict:
+        """Call complete_json and always return a dict (never raises)."""
+        try:
+            result = self._router.complete_json(task, messages)
+            if isinstance(result, dict):
+                return result
+            if isinstance(result, list):
+                # Model returned a bare list — treat it as affected_files so
+                # the retry logic can inject those files.
+                log.warning("complete_json returned list; treating as affected_files: %s",
+                            result[:4])
+                return {"affected_files": [r for r in result if isinstance(r, str)]}
+            log.warning("complete_json returned unexpected type %s; ignoring", type(result))
+            return {}
+        except ModelError as exc:
+            log.warning("complete_json ModelError: %s", exc)
+            return {}
+        except Exception as exc:
+            log.warning("complete_json unexpected error: %s", exc)
+            return {}
+
+    def diagnose(self, issue: str, stack_trace: str | None = None,
+                 root: Path | None = None) -> Diagnosis:
+        terms = _error_terms(issue, stack_trace)
+        trace_files = [m.group(1) for m in _TRACE_FILE.finditer(stack_trace or "")]
+
+        chunks = self._retriever.retrieve_for_diff(
+            changed_files=trace_files, changed_symbols=terms,
+            error_terms=terms, top_k=14)
+        chunks += self._retriever.retrieve_for_query(issue, top_k=6)
+        sufficient = context_is_sufficient(chunks)
+        ctx = build_context(
+            chunks, max_tokens=self._max_ctx,
+            header="# Code context for diagnosis (copy find-strings verbatim)")
+
+        # --- first pass ---
+        raw = self._safe_complete_json(
+            Task.fix, bug_fix_messages(issue, ctx.text, stack_trace))
+        edits = _parse_edits(raw)
+        affected = list(raw.get("affected_files", []) or [])
+
+        # --- retry: inject full file source ---
+        # Triggered when:
+        #   (a) model returned empty/garbage              -> inject files from issue text
+        #   (b) model listed affected_files but no edits  -> inject those files
+        #   (c) find-strings don't exist in real files   -> inject those files
+        if root is not None:
+            if _raw_is_empty(raw):
+                to_inject = _extract_files_from_issue(issue, root)
+                log.info("First pass empty; injecting issue-mentioned files: %s", to_inject)
+            else:
+                to_inject = _files_needing_injection(edits, affected, root)
+                if not to_inject and _raw_is_empty({"edits": edits}):
+                    # Got a diagnosis but no edits — inject affected files
+                    to_inject = affected[:3]
+
+            if to_inject:
+                enriched = _inject_file_content(root, to_inject, ctx.text)
+                retry_issue = (
+                    issue
+                    + "\n\nIMPORTANT: The complete source of the relevant files is "
+                    "appended above. The new patching system will use AST-based "
+                    "symbol resolution when possible, with fuzzy matching fallback."
+                )
+                raw2 = self._safe_complete_json(
+                    Task.fix, bug_fix_messages(retry_issue, enriched, stack_trace))
+                if not _raw_is_empty(raw2):
+                    edits2 = _parse_edits(raw2)
+                    if edits2 or raw2.get("root_cause"):
+                        raw, edits = raw2, edits2
+
+        return Diagnosis(
+            root_cause=str(raw.get("root_cause", "")),
+            affected_files=list(raw.get("affected_files", []) or []),
+            plan=str(raw.get("plan", "")), risk=str(raw.get("risk", "")),
+            edits=edits, sufficient_context=sufficient,
+            backends=self._retriever.backends())

skelpr/agents/patch_agent.py

@@ -0,0 +1,36 @@
+"""Patch agent: turn diagnosis edits into a validated, minimal unified diff."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..config.schema import CommandsConfig
+from ..patches.diff_generator import Edit, GeneratedPatch, generate_patch
+from ..patches.patch_validator import PatchCheck, check_patch
+from ..utils.errors import PatchError
+
+
+@dataclass
+class PatchOutcome:
+    patch: GeneratedPatch
+    check: PatchCheck
+    validation_recommendation: str
+
+
+class PatchAgent:
+    def __init__(self, root: Path, commands: CommandsConfig):
+        self._root = root
+        self._commands = commands
+
+    def build(self, edits: list[Edit]) -> PatchOutcome:
+        if not edits:
+            raise PatchError("No edits to apply; cannot generate a patch.")
+        patch = generate_patch(self._root, edits)
+        check = check_patch(self._root, patch.unified_diff)
+        cmds = self._commands.as_mapping()
+        rec = (
+            "After applying, validate with: "
+            + "; ".join(f"{name} (`{cmd}`)" for name, cmd in cmds.items())
+            + ". Do not consider the fix complete until validation passes."
+        )
+        return PatchOutcome(patch=patch, check=check, validation_recommendation=rec)

skelpr/agents/pr_review_agent.py

@@ -0,0 +1,42 @@
+"""PR review agent: diff -> retrieval -> model -> filtered structured findings."""
+from __future__ import annotations
+
+from ..config.schema import ReviewConfig
+from ..models.model_router import ModelRouter, Task
+from ..models.prompt_templates import pr_review_messages
+from ..retrieval.context_builder import build_context
+from ..retrieval.hybrid_retriever import HybridRetriever
+from ..review.confidence_filter import filter_findings
+from ..review.diff_parser import ParsedDiff, changed_symbol_names, parse_unified_diff
+from ..review.finding_schema import ReviewResult, parse_findings
+from ..review.severity_ranker import rank_and_cap
+
+
+class PRReviewAgent:
+    def __init__(self, retriever: HybridRetriever, router: ModelRouter,
+                 review_config: ReviewConfig, max_context_tokens: int = 12000):
+        self._retriever = retriever
+        self._router = router
+        self._config = review_config
+        self._max_ctx = max_context_tokens
+
+    def review(self, diff_text: str, diff_range: str = "") -> ReviewResult:
+        parsed: ParsedDiff = parse_unified_diff(diff_text)
+        if not parsed.files:
+            return ReviewResult(diff_range=diff_range, backends=self._retriever.backends())
+
+        changed_files = parsed.changed_paths
+        changed_symbols = changed_symbol_names(parsed)
+        context_chunks = self._retriever.retrieve_for_diff(
+            changed_files=changed_files, changed_symbols=changed_symbols)
+        ctx = build_context(context_chunks, max_tokens=self._max_ctx,
+                            header="# Context for the change")
+
+        raw = self._router.complete_json(Task.review, pr_review_messages(diff_text, ctx.text))
+        findings = parse_findings(raw)
+
+        kept, suppressed = filter_findings(findings, self._config, parsed)
+        ranked = rank_and_cap(kept, self._config)
+        suppressed += len(kept) - len(ranked)
+        return ReviewResult(findings=ranked, suppressed=suppressed,
+                            diff_range=diff_range, backends=self._retriever.backends())

skelpr/agents/repo_qa_agent.py

@@ -0,0 +1,36 @@
+"""Repo Q&A agent: grounded answers with file:line citations."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..models.model_router import ModelRouter, Task
+from ..models.prompt_templates import repo_qa_messages
+from ..retrieval.context_builder import build_context, context_is_sufficient
+from ..retrieval.hybrid_retriever import HybridRetriever
+
+
+@dataclass
+class Answer:
+    text: str
+    citations: list[str]
+    sufficient_context: bool
+    backends: dict[str, str]
+
+
+class RepoQAAgent:
+    def __init__(self, retriever: HybridRetriever, router: ModelRouter,
+                 max_context_tokens: int = 16000):
+        self._retriever = retriever
+        self._router = router
+        self._max_ctx = max_context_tokens
+
+    def ask(self, question: str, top_k: int = 12) -> Answer:
+        chunks = self._retriever.retrieve_for_query(question, top_k=top_k)
+        sufficient = context_is_sufficient(chunks)
+        ctx = build_context(chunks, max_tokens=self._max_ctx,
+                            header="# Retrieved context (cite these locations)")
+        messages = repo_qa_messages(question, ctx.text, insufficient=not sufficient)
+        result = self._router.complete(Task.qa, messages)
+        return Answer(text=result.text.strip(), citations=ctx.citations,
+                      sufficient_context=sufficient,
+                      backends=self._retriever.backends())

skelpr/agents/test_generation_agent.py

@@ -0,0 +1,46 @@
+"""Test-generation agent: propose minimal tests for changed behavior."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ..models.model_router import ModelRouter, Task
+from ..models.prompt_templates import test_gen_messages
+from ..retrieval.context_builder import build_context
+from ..retrieval.hybrid_retriever import HybridRetriever
+
+
+@dataclass
+class ProposedTest:
+    path: str
+    content: str
+    reason: str
+
+
+@dataclass
+class TestProposal:
+    tests: list[ProposedTest] = field(default_factory=list)
+    backends: dict[str, str] = field(default_factory=dict)
+
+
+class TestGenerationAgent:
+    def __init__(self, retriever: HybridRetriever, router: ModelRouter,
+                 max_context_tokens: int = 12000):
+        self._retriever = retriever
+        self._router = router
+        self._max_ctx = max_context_tokens
+
+    def generate(self, change_summary: str, changed_files: list[str],
+                 changed_symbols: list[str]) -> TestProposal:
+        chunks = self._retriever.retrieve_for_diff(
+            changed_files=changed_files, changed_symbols=changed_symbols, top_k=10)
+        ctx = build_context(chunks, max_tokens=self._max_ctx,
+                            header="# Code under test + existing tests")
+        raw = self._router.complete_json(
+            Task.test_gen, test_gen_messages(change_summary, ctx.text))
+        raw = raw if isinstance(raw, dict) else {}
+        tests = [
+            ProposedTest(path=t.get("path", ""), content=t.get("content", ""),
+                         reason=t.get("reason", ""))
+            for t in raw.get("tests", []) if isinstance(t, dict)
+        ]
+        return TestProposal(tests=tests, backends=self._retriever.backends())

skelpr/cli/commands/ask.py

@@ -0,0 +1,76 @@
+"""`skelpr ask` - grounded Q&A over the repo."""
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import typer
+
+from ...engine import Engine
+from ...utils.errors import ModelError
+from ...utils.tracing import (
+    build_retrieval_meta,
+    build_timing,
+    traced_operation,
+)
+from ..console import console, fail
+
+
+def run(
+    question: str = typer.Argument(..., help="Your question about the repository."),
+    top_k: int = typer.Option(12, "--top-k", help="Number of context chunks."),
+    path: Path = typer.Option(None, "--path"),
+) -> None:
+    t0 = time.perf_counter()
+    try:
+        engine = Engine.from_path(path)
+    except Exception as exc:
+        fail(str(exc))
+
+    with traced_operation("skelpr_ask", engine, {"query": question, "top_k": top_k}) as span:
+        try:
+            t_retrieval = time.perf_counter()
+            answer = engine.ask(question, top_k=top_k)
+            retrieval_ms = (time.perf_counter() - t_retrieval) * 1000
+
+            # Get retrieval metrics if available
+            rm = getattr(engine, '_last_retriever', None)
+            rm = rm.last_retrieval_metrics if rm else None
+
+            # Build full metadata
+            retrieval_meta = build_retrieval_meta(rm, [])
+            timing = build_timing(rm, 0.0, retrieval_ms, 0.0, (time.perf_counter() - t0) * 1000)
+
+            span.finish(
+                output={
+                    "text": answer.text,
+                    "sufficient_context": answer.sufficient_context,
+                    "citations": answer.citations,
+                    "final_context_char_count": len(answer.text),
+                    "context_token_estimate": len(answer.text) // 4,
+                },
+                metadata={
+                    "success": True,
+                    "top_k": top_k,
+                    **retrieval_meta,
+                    **timing,
+                },
+            )
+        except ModelError as exc:
+            span.finish(metadata={"success": False, "error_type": "ModelError", "error": str(exc)})
+            fail(str(exc), code=3)
+        except Exception as exc:
+            span.finish(metadata={"success": False, "error_type": "Exception", "error": str(exc)})
+            fail(str(exc))
+
+    elapsed = time.perf_counter() - t0
+    from rich.panel import Panel
+
+    console.print(f"[dim] {elapsed:.1f}s[/dim]")
+    console.print(Panel(answer.text, title="Answer", border_style="cyan"))
+    if not answer.sufficient_context:
+        console.print("[yellow]Note:[/yellow] retrieved context was thin; "
+                      "answer may be incomplete.")
+    if answer.citations:
+        console.print("[dim]Context:[/dim] " + ", ".join(answer.citations))
+    engine.close()