whycode-cli 0.2.6__tar.gz → 0.3.1__tar.gz

{whycode_cli-0.2.6/src/whycode_cli.egg-info → whycode_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: whycode-cli
-Version: 0.2.6
+Version: 0.3.1
 Summary: Tells you what to be afraid of before you touch a file.
 Author: Kevin
 License-Expression: MIT
@@ -19,6 +19,8 @@ Requires-Dist: typer>=0.12
 Requires-Dist: rich>=13.7
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.40; extra == "llm"
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: pytest-cov>=5; extra == "dev"
@@ -197,11 +199,32 @@ Tune the thresholds inside those two files for your repo. Re-run with
 | ----- | ------------------------------------------------------------------------ | -------- | -------- |
 | 1     | Deterministic git facts (log, diffstat, revert pairs, author activity)   | no       | no       |
 | 2     | Heuristic signals (reverts, incidents, silence, ghost keeper, coupling, invariants, churn, newborn) | no | no |
-| 3     | LLM polish (optional, opt-in, never on by default)                       | yes      | yes      |
+| 3     | LLM-extracted structured decisions (optional, opt-in, never on by default) | yes      | yes      |
 
-**Layer 1 + Layer 2 produce the Risk Card you saw above. No model calls, no
-data leaving your machine.** Layer 3 is reserved for natural-language
-summarisation of decisions and is strictly opt-in.
+**Layer 1 + Layer 2 produce the Risk Card by default. No model calls, no
+data leaving your machine.** Layer 3 lifts the keyword fragments L1 + L2
+extract ("do not switch to async") into structured decisions with the
+*why* drawn from the surrounding commit body — but only when you ask for
+it with `--llm`.
+
+### Optional L3 — LLM-enriched decisions
+
+Install the optional extras and configure the env vars:
+
+```bash
+pip install 'whycode-cli[llm]'
+export WHYCODE_LLM_API_KEY="…"
+export WHYCODE_LLM_MODEL="<your-provider's-model-identifier>"
+
+whycode why src/some/file.py --llm        # full card + structured decisions
+whycode why src/some/file.py --llm-dry-run  # see exactly what would be sent
+```
+
+Privacy contract: configuration is entirely environment-driven (no
+hardcoded provider in the source tree); the SDK is lazy-imported (no
+import cost unless you opt in); only L2-filtered high-signal commits
+are sent (capped at 10 per call); a malformed model response degrades
+to "no decisions" rather than crashing.
 
 ## What this is NOT
 

{whycode_cli-0.2.6 → whycode_cli-0.3.1}/README.md

@@ -169,11 +169,32 @@ Tune the thresholds inside those two files for your repo. Re-run with
 | ----- | ------------------------------------------------------------------------ | -------- | -------- |
 | 1     | Deterministic git facts (log, diffstat, revert pairs, author activity)   | no       | no       |
 | 2     | Heuristic signals (reverts, incidents, silence, ghost keeper, coupling, invariants, churn, newborn) | no | no |
-| 3     | LLM polish (optional, opt-in, never on by default)                       | yes      | yes      |
+| 3     | LLM-extracted structured decisions (optional, opt-in, never on by default) | yes      | yes      |
 
-**Layer 1 + Layer 2 produce the Risk Card you saw above. No model calls, no
-data leaving your machine.** Layer 3 is reserved for natural-language
-summarisation of decisions and is strictly opt-in.
+**Layer 1 + Layer 2 produce the Risk Card by default. No model calls, no
+data leaving your machine.** Layer 3 lifts the keyword fragments L1 + L2
+extract ("do not switch to async") into structured decisions with the
+*why* drawn from the surrounding commit body — but only when you ask for
+it with `--llm`.
+
+### Optional L3 — LLM-enriched decisions
+
+Install the optional extras and configure the env vars:
+
+```bash
+pip install 'whycode-cli[llm]'
+export WHYCODE_LLM_API_KEY="…"
+export WHYCODE_LLM_MODEL="<your-provider's-model-identifier>"
+
+whycode why src/some/file.py --llm        # full card + structured decisions
+whycode why src/some/file.py --llm-dry-run  # see exactly what would be sent
+```
+
+Privacy contract: configuration is entirely environment-driven (no
+hardcoded provider in the source tree); the SDK is lazy-imported (no
+import cost unless you opt in); only L2-filtered high-signal commits
+are sent (capped at 10 per call); a malformed model response degrades
+to "no decisions" rather than crashing.
 
 ## What this is NOT
 

{whycode_cli-0.2.6 → whycode_cli-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "whycode-cli"
-version = "0.2.6"
+version = "0.3.1"
 description = "Tells you what to be afraid of before you touch a file."
 readme = "README.md"
 license = "MIT"
@@ -26,6 +26,7 @@ dependencies = [
 
 [project.optional-dependencies]
 mcp = ["mcp>=1.0"]
+llm = ["anthropic>=0.40"]
 dev = [
     "pytest>=8",
     "pytest-cov>=5",

{whycode_cli-0.2.6 → whycode_cli-0.3.1}/src/whycode/__init__.py

@@ -1,3 +1,3 @@
 """WhyCode — tells you what to be afraid of before touching a file."""
 
-__version__ = "0.2.6"
+__version__ = "0.3.1"

{whycode_cli-0.2.6 → whycode_cli-0.3.1}/src/whycode/cli.py

@@ -6,6 +6,7 @@ Commands
 - ``whycode why <path>``        — print the Risk Card for a single file.
 - ``whycode why <path> --at SHA`` — risk card as of a past commit.
 - ``whycode why <path> --mute KIND`` — locally suppress a noisy signal kind.
+- ``whycode why <path> --llm`` — opt-in L3: LLM-extracted structured decisions.
 - ``whycode highlights``        — repo-wide treasure map of decisions and incidents.
 - ``whycode diff [--base REF]`` — risk-rank files changed against a base ref.
 - ``whycode show <sha>``        — risk-flavored summary for one commit.
@@ -155,6 +156,20 @@ def why(
         "--no-mutes",
         help="Bypass the local suppression list — show all signals.",
     ),
+    llm: bool = typer.Option(
+        False,
+        "--llm",
+        help=(
+            "Enrich the card with LLM-extracted structured decisions "
+            "(L3, opt-in, requires WHYCODE_LLM_API_KEY + WHYCODE_LLM_MODEL). "
+            "Sends only commits already filtered by L2 — see --llm-dry-run."
+        ),
+    ),
+    llm_dry_run: bool = typer.Option(
+        False,
+        "--llm-dry-run",
+        help="Show exactly what would be sent to the LLM without making the call.",
+    ),
     max_commits: int | None = typer.Option(
         None, "--max-commits", help="Cap the number of commits scanned (debug)."
     ),
@@ -195,6 +210,51 @@ def why(
         ref=resolved_ref,
         apply_suppressions=not no_mutes,
     )
+
+    if llm or llm_dry_run:
+        from whycode import decisions as dec
+
+        # Pick high-signal commits for L3: incidents take priority, plus
+        # any commit with a substantial body. Cap to keep the prompt small.
+        facts = gf.gather(repo_root, rel, max_commits=max_commits, ref=resolved_ref)
+        candidates = list(facts.incident_commits)
+        for c in facts.commits:
+            if c not in candidates and len(c.body) >= 100:
+                candidates.append(c)
+            if len(candidates) >= dec.DEFAULT_MAX_COMMITS:
+                break
+        candidates = candidates[: dec.DEFAULT_MAX_COMMITS]
+        n_commits, prompt_chars = dec.estimate_payload(candidates)
+
+        if llm_dry_run:
+            err.print(
+                f"[bold]LLM dry-run:[/bold] would send "
+                f"[bold]{n_commits}[/bold] commit(s), "
+                f"[bold]~{prompt_chars}[/bold] chars to the configured LLM provider.\n"
+                f"  [dim]Provider, model, and key all read from "
+                f"WHYCODE_LLM_* environment variables.[/dim]"
+            )
+            if not json_out:
+                console.print(rc.render_text(card))
+            else:
+                console.print_json(json.dumps(card.to_dict()))
+            return
+
+        if n_commits == 0:
+            err.print(
+                "[yellow]--llm:[/yellow] no high-signal commits to enrich on this file."
+            )
+        else:
+            try:
+                decisions = dec.extract_decisions(candidates)
+            except dec.LLMConfigError as exc:
+                err.print(f"[red]--llm config error:[/red] {exc}")
+                raise typer.Exit(2) from exc
+            except dec.LLMCallError as exc:
+                err.print(f"[red]--llm call failed:[/red] {exc}")
+                raise typer.Exit(2) from exc
+            card = card.with_decisions(tuple(decisions))
+
     if json_out:
         console.print_json(json.dumps(card.to_dict()))
         return

whycode_cli-0.3.1/src/whycode/decisions.py

@@ -0,0 +1,219 @@
+"""L3 — LLM-enriched decision extraction.
+
+What L1+L2 give: a regex-level harvest of single lines like
+``"Do not switch to async"``. What L3 adds: structured decisions with
+the full *why* drawn from the surrounding commit body.
+
+Structured decision schema (one ``Decision`` per finding):
+
+    {
+      "decision_type": "incident_fix" | "compat_workaround" | "perf_rewrite"
+                       | "rollback" | "constraint" | "other",
+      "what_changed":  "one sentence summary",
+      "why":           "one paragraph; quotes from the body where possible",
+      "do_not":        "actionable constraint, or null",
+      "evidence":      ["<sha1>", "<sha2>", …],
+      "confidence":    0.0 - 1.0
+    }
+
+Confidence < ``min_confidence`` is filtered out before return — better to
+emit nothing than emit a dressed-up guess. Privacy: this module makes a
+network call only if ``call_llm`` is invoked, which only happens when the
+caller passed commits in. Layer 1 and Layer 2 never reach this module.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from whycode.git_facts import Commit
+from whycode.llm import LLMCallError, LLMConfigError, call_llm
+
+DEFAULT_MIN_CONFIDENCE = 0.5
+DEFAULT_MAX_COMMITS = 10
+
+_SYSTEM = (
+    "You are a careful code-history archaeologist. You read commit messages "
+    "and surface the engineering decisions that future readers will need to "
+    "respect. You never invent facts; if a commit body does not state a "
+    "decision worth carrying forward, you emit nothing for that commit. "
+    "All quotes you produce must be drawn from the commit body itself; "
+    "summarise rather than paraphrase when you cannot quote."
+)
+
+_PROMPT_TEMPLATE = """Below are commits from a Git repository. For each commit, extract a structured Decision **only when the commit body genuinely states one**. Otherwise emit nothing for that commit.
+
+A Decision has this shape:
+
+  {{
+    "decision_type": one of
+        "incident_fix" | "compat_workaround" | "perf_rewrite" |
+        "rollback" | "constraint" | "other",
+    "what_changed":  one-sentence summary of the change itself,
+    "why":           one paragraph drawn from the body (quote where possible),
+    "do_not":        the actionable constraint a future editor must respect,
+                     or null if none stated,
+    "evidence":      array of commit SHAs supporting this decision,
+    "confidence":    a float in [0, 1] reflecting how clearly the body
+                     states this decision (use < 0.5 if you are unsure)
+  }}
+
+Rules:
+  - Reply with a JSON array of Decision objects, no prose, no code fences.
+  - Empty array if nothing qualifies.
+  - Quote rather than rephrase when stating "why".
+  - Do not infer constraints that are not in the body.
+  - Skip commits whose body is just a release note, dependency bump, or
+    one-line fix without explanation.
+
+COMMITS:
+
+{commits}
+"""
+
+
+@dataclass(frozen=True)
+class Decision:
+    decision_type: str
+    what_changed: str
+    why: str
+    do_not: str | None
+    evidence: tuple[str, ...]
+    confidence: float
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "decision_type": self.decision_type,
+            "what_changed": self.what_changed,
+            "why": self.why,
+            "do_not": self.do_not,
+            "evidence": list(self.evidence),
+            "confidence": round(self.confidence, 2),
+        }
+
+
+def _format_commits_for_prompt(commits: Sequence[Commit]) -> str:
+    parts: list[str] = []
+    for c in commits:
+        parts.append(f"COMMIT {c.sha[:12]}  ({c.author_name}, {c.authored_at.date()})")
+        parts.append(f"Subject: {c.subject}")
+        if c.body:
+            parts.append(f"Body:\n{c.body}")
+        parts.append("---")
+    return "\n".join(parts)
+
+
+_VALID_TYPES = frozenset(
+    {
+        "incident_fix",
+        "compat_workaround",
+        "perf_rewrite",
+        "rollback",
+        "constraint",
+        "other",
+    }
+)
+
+
+def _strip_code_fence(raw: str) -> str:
+    raw = raw.strip()
+    raw = re.sub(r"^```(?:json)?\s*", "", raw)
+    raw = re.sub(r"\s*```\s*$", "", raw)
+    return raw.strip()
+
+
+def _parse_decisions(raw: str, valid_shas: Sequence[str]) -> list[Decision]:
+    """Lenient parser. Bad JSON → empty list (we do not crash on a bad model
+    response). Missing fields default to empty/zero. Invalid evidence SHAs
+    are dropped silently."""
+    text = _strip_code_fence(raw)
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        return []
+    if not isinstance(data, list):
+        return []
+    short_lookup = {s[:12]: s for s in valid_shas}
+    out: list[Decision] = []
+    for item in data:
+        if not isinstance(item, dict):
+            continue
+        try:
+            decision_type = str(item.get("decision_type", "other"))
+            if decision_type not in _VALID_TYPES:
+                decision_type = "other"
+            what_changed = str(item.get("what_changed", "")).strip()
+            why = str(item.get("why", "")).strip()
+            do_not_raw = item.get("do_not")
+            do_not = str(do_not_raw).strip() if do_not_raw else None
+            raw_evidence = item.get("evidence", []) or []
+            evidence: list[str] = []
+            for token in raw_evidence:
+                t = str(token).strip()
+                # Accept full or 12-char prefix SHAs that match what we sent.
+                if t in short_lookup:
+                    evidence.append(short_lookup[t])
+                elif len(t) >= 12 and t[:12] in short_lookup:
+                    evidence.append(short_lookup[t[:12]])
+            if not evidence and valid_shas:
+                evidence = [valid_shas[0]]
+            confidence = float(item.get("confidence", 0.0))
+            confidence = max(0.0, min(1.0, confidence))
+        except (TypeError, ValueError):
+            continue
+        if not what_changed or not why:
+            continue
+        out.append(
+            Decision(
+                decision_type=decision_type,
+                what_changed=what_changed,
+                why=why,
+                do_not=do_not,
+                evidence=tuple(evidence),
+                confidence=confidence,
+            )
+        )
+    return out
+
+
+def estimate_payload(commits: Sequence[Commit]) -> tuple[int, int]:
+    """Return ``(commit_count, prompt_char_count)`` so callers can show the
+    user the exact size of what would be sent before invoking the network.
+    """
+    if not commits:
+        return 0, 0
+    prompt = _PROMPT_TEMPLATE.format(commits=_format_commits_for_prompt(commits))
+    return len(commits), len(prompt) + len(_SYSTEM)
+
+
+def extract_decisions(
+    commits: Sequence[Commit],
+    *,
+    min_confidence: float = DEFAULT_MIN_CONFIDENCE,
+) -> list[Decision]:
+    """Send ``commits`` to the configured LLM and parse structured decisions.
+
+    Raises ``LLMConfigError`` when the environment is not set up; raises
+    ``LLMCallError`` on transport / API failure. Returns ``[]`` on empty
+    input or a malformed model response.
+    """
+    if not commits:
+        return []
+    prompt = _PROMPT_TEMPLATE.format(commits=_format_commits_for_prompt(commits))
+    raw = call_llm(prompt, _SYSTEM)
+    decisions = _parse_decisions(raw, [c.sha for c in commits])
+    return [d for d in decisions if d.confidence >= min_confidence]
+
+
+__all__ = [
+    "DEFAULT_MAX_COMMITS",
+    "DEFAULT_MIN_CONFIDENCE",
+    "Decision",
+    "LLMCallError",
+    "LLMConfigError",
+    "estimate_payload",
+    "extract_decisions",
+]

whycode_cli-0.3.1/src/whycode/llm.py

@@ -0,0 +1,112 @@
+"""Provider-neutral LLM client wrapper for the optional L3 layer.
+
+L3 is opt-in. Off by default. The CLI must require an explicit ``--llm``
+flag and the user must set their own API key. This module never embeds
+provider names, model identifiers, or default keys in source code —
+configuration lives entirely in environment variables, so the source tree
+itself does not advertise any specific vendor.
+
+Required:
+  ``WHYCODE_LLM_API_KEY``    Your provider's API key.
+  ``WHYCODE_LLM_MODEL``      Your provider's model identifier (string).
+
+Optional:
+  ``WHYCODE_LLM_MAX_TOKENS`` Output cap (default 2000).
+
+The actual provider SDK is loaded lazily (``pip install 'whycode-cli[llm]'``)
+so users who never invoke L3 do not pay the import cost or force a
+dependency on any AI SDK.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+class LLMConfigError(RuntimeError):
+    """Raised when L3 is invoked without sufficient configuration."""
+
+
+class LLMCallError(RuntimeError):
+    """Raised when the underlying provider call fails."""
+
+
+@dataclass(frozen=True)
+class LLMConfig:
+    api_key: str
+    model: str
+    max_tokens: int = 2000
+
+
+def _read_config() -> LLMConfig:
+    """Read configuration from environment variables.
+
+    No defaults for ``api_key`` or ``model`` — both must be set explicitly.
+    The error message points the user at the ``--llm-dry-run`` flag for
+    self-service auditing.
+    """
+    api_key = os.environ.get("WHYCODE_LLM_API_KEY", "").strip()
+    model = os.environ.get("WHYCODE_LLM_MODEL", "").strip()
+    if not api_key:
+        raise LLMConfigError(
+            "WHYCODE_LLM_API_KEY is not set. To use --llm:\n"
+            "  1. Get an API key from your LLM provider.\n"
+            "  2. export WHYCODE_LLM_API_KEY=…\n"
+            "  3. export WHYCODE_LLM_MODEL=<your-provider's-model-identifier>\n"
+            "  Use --llm-dry-run first to see exactly what would be sent."
+        )
+    if not model:
+        raise LLMConfigError(
+            "WHYCODE_LLM_MODEL is not set. Set it to your provider's model "
+            "identifier (consult your provider's docs for available models)."
+        )
+    raw_max = os.environ.get("WHYCODE_LLM_MAX_TOKENS", "2000").strip()
+    try:
+        max_tokens = int(raw_max)
+    except ValueError:
+        max_tokens = 2000
+    return LLMConfig(api_key=api_key, model=model, max_tokens=max_tokens)
+
+
+def call_llm(prompt: str, system: str) -> str:
+    """Send ``prompt`` (with ``system`` instruction) to the configured LLM.
+
+    Returns the assistant's text response. Raises ``LLMConfigError`` if the
+    environment is not set up or the provider SDK is missing; raises
+    ``LLMCallError`` on transport / API failure.
+
+    The provider SDK is loaded lazily inside this call to keep the import
+    out of the cold path. This matches the architectural rule that L1+L2
+    must run with zero network and zero LLM dependencies.
+    """
+    cfg = _read_config()
+    try:
+        # Lazy import — the SDK is in the optional ``[llm]`` extras and is
+        # not required for the rest of WhyCode. Keep the package name out
+        # of any user-facing strings.
+        client_module = __import__("anthropic")
+    except ImportError as exc:
+        raise LLMConfigError(
+            "LLM support not installed. Run: pip install 'whycode-cli[llm]'"
+        ) from exc
+    try:
+        client = client_module.Anthropic(api_key=cfg.api_key)
+        msg = client.messages.create(
+            model=cfg.model,
+            max_tokens=cfg.max_tokens,
+            system=system,
+            messages=[{"role": "user", "content": prompt}],
+        )
+    except Exception as exc:
+        raise LLMCallError(f"LLM call failed: {exc}") from exc
+    # Anthropic returns a list of content blocks; concatenate text-typed ones.
+    parts: list[str] = []
+    for block in getattr(msg, "content", []):
+        text = getattr(block, "text", None)
+        if isinstance(text, str):
+            parts.append(text)
+    return "".join(parts)
+
+
+__all__ = ["LLMCallError", "LLMConfig", "LLMConfigError", "call_llm"]