cognit 0.1.0__py3-none-any.whl

cognit/__init__.py

@@ -0,0 +1 @@
+"""Voluntary PR-author comprehension quiz tool."""

cognit/__main__.py

@@ -0,0 +1,2 @@
+# Placeholder for __main__.py
+# Will be populated in M3.1 when cognit.cli is implemented

cognit/cli/__init__.py

@@ -0,0 +1,36 @@
+import typer
+from cognit.cli.version import __version__
+from cognit.cli import take as _take
+
+app = typer.Typer(no_args_is_help=True, help="PR-author comprehension quiz tool")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"cognit {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def root(
+    version: bool = typer.Option(False, "--version", callback=_version_callback, is_eager=True),
+) -> None:
+    pass
+
+
+@app.command("take")
+def take_cmd(
+    pr: str | None = typer.Option(None, "--pr", help="PR URL (default: auto-detect)"),
+    show_results: bool = typer.Option(False, "--show-results"),
+    model: str = typer.Option("claude-sonnet-4-6", "--model"),
+    min_diff_lines: int = typer.Option(50, "--min-diff-lines"),
+    max_diff_lines: int = typer.Option(2000, "--max-diff-lines"),
+) -> None:
+    """Take a quiz on a PR. Generates one if none exists, opens browser, grades in-session, optional publish."""
+    _take.run(
+        pr,
+        show_results=show_results,
+        model=model,
+        min_diff_lines=min_diff_lines,
+        max_diff_lines=max_diff_lines,
+    )

cognit/cli/take.py

@@ -0,0 +1,246 @@
+"""`cognit take` — the only command.
+
+Generates the quiz in memory (cached locally for resume), opens the browser quiz,
+grades in-session, opt-in publishes the results comment to the PR. The quiz itself
+is **never posted to the PR** — only the results comment, and only when the user
+clicks Publish.
+"""
+
+import hashlib
+import json
+import logging
+import os
+import socket
+import subprocess
+import tempfile
+import threading
+import webbrowser
+from collections.abc import Callable
+from pathlib import Path
+
+import typer
+import uvicorn
+from anthropic import APIError as AnthropicAPIError
+from pydantic import ValidationError
+
+from cognit.comment.parse import parse_results
+from cognit.engine.generate import generate_quiz
+from cognit.engine.llm import LLMClient
+from cognit.engine.llm_anthropic import AnthropicLLM
+from cognit.engine.llm_claude_agent import ClaudeAgentLLM
+from cognit.engine.models import Quiz
+from cognit.ghio.diff import fetch_diff_and_files, read_file_at_head
+from cognit.ghio.pr import fetch_pr_info, find_latest_marker_comment, post_comment
+from cognit.server.app import build_app
+
+logger = logging.getLogger("cognit.cli.take")
+
+_MARKER_RESULTS = "<!-- cognit:results v1 -->"
+
+
+def _make_llm(model: str) -> LLMClient:
+    """Pick the adapter based on the only auth signal that matters.
+
+    `ANTHROPIC_API_KEY` set → direct Anthropic SDK (fastest, no subprocess).
+    Otherwise → `claude_agent_sdk` (subprocesses the `claude` binary, which is
+    the only path that unlocks sonnet/opus for OAuth-only users; see
+    docs/superpowers/specs/2026-05-22-claude-agent-sdk-engine-design.md).
+    """
+    if os.environ.get("ANTHROPIC_API_KEY"):
+        return AnthropicLLM(model=model)
+    return ClaudeAgentLLM(model=model)
+
+
+def _detect_pr_from_branch() -> str | None:
+    """Use `gh pr view` to find the PR for the current branch."""
+    try:
+        result = subprocess.run(
+            ["gh", "pr", "view", "--json", "url"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return str(json.loads(result.stdout)["url"])
+    except subprocess.CalledProcessError:
+        return None
+
+
+def _free_port() -> int:
+    """Find an unused localhost TCP port."""
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        port: int = s.getsockname()[1]
+        return port
+
+
+def _cache_path_for(pr_url: str) -> Path:
+    """Local cache path for a generated quiz, keyed by PR URL digest.
+
+    Lives under `$TMPDIR/cognit/`. OS reboot clears it. No explicit lifecycle.
+    """
+    digest = hashlib.sha1(pr_url.encode("utf-8")).hexdigest()[:16]
+    cache_dir = Path(tempfile.gettempdir()) / "cognit"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir / f"{digest}.json"
+
+
+def _serve_blocking(
+    quiz: Quiz,
+    pr_url: str,
+    llm: LLMClient,
+    post_comment_fn: Callable[[str], str],
+) -> None:
+    """Build the FastAPI app, launch the browser, run uvicorn until killed."""
+    app = build_app(quiz=quiz, pr_url=pr_url, llm=llm, post_comment=post_comment_fn)
+    port = _free_port()
+    url = f"http://127.0.0.1:{port}"
+    typer.echo(f"opening {url} in your browser... (Ctrl-C to quit)")
+    threading.Thread(target=lambda: webbrowser.open(url), daemon=True).start()
+    uvicorn.run(app, host="127.0.0.1", port=port, log_level="warning")
+
+
+def _generate_in_memory(
+    pr_url: str,
+    llm: LLMClient,
+    model: str,
+    min_diff_lines: int,
+    max_diff_lines: int,
+) -> Quiz | None:
+    """Generate a quiz from the PR's diff. Returns the Quiz, or None if skipped.
+
+    Unlike the previous behaviour, does NOT post anything to the PR — the quiz
+    lives only in memory (and the local cache `_load_or_generate` writes).
+    """
+    info = fetch_pr_info(pr_url)
+    if "quiz: skip" in info.body.lower():
+        typer.echo("quiz: skip in PR body — skipping.")
+        return None
+    diff, files = fetch_diff_and_files(pr_url, fetch_file_contents=read_file_at_head)
+    diff_lines = diff.count("\n")
+    if diff_lines < min_diff_lines:
+        typer.echo(f"diff is {diff_lines} lines (< {min_diff_lines}) — skipping.")
+        return None
+    if diff_lines > max_diff_lines:
+        typer.echo(f"diff is {diff_lines} lines (> {max_diff_lines}) — skipping.")
+        return None
+    try:
+        return generate_quiz(
+            diff=diff,
+            pr_title=info.title,
+            pr_body=info.body,
+            files=files,
+            pr_number=info.number,
+            llm=llm,
+            model=model,
+        )
+    except AnthropicAPIError as e:
+        typer.echo(f"LLM call failed: {type(e).__name__}: {e}", err=True)
+        raise typer.Exit(code=1) from None
+    except ValidationError as e:
+        typer.echo(f"LLM returned malformed quiz: {e}", err=True)
+        raise typer.Exit(code=1) from None
+    except RuntimeError as e:
+        typer.echo(f"LLM call failed: {e}", err=True)
+        raise typer.Exit(code=1) from None
+
+
+def _load_or_generate(
+    pr_url: str,
+    llm: LLMClient,
+    model: str,
+    min_diff_lines: int,
+    max_diff_lines: int,
+) -> Quiz | None:
+    """Return a Quiz: from local cache if present, else generate fresh and cache it."""
+    cache_path = _cache_path_for(pr_url)
+    if cache_path.exists():
+        logger.debug("cache hit: loading quiz from %s", cache_path)
+        try:
+            return Quiz.model_validate_json(cache_path.read_text())
+        except ValidationError:
+            logger.debug("cache at %s is invalid — regenerating", cache_path)
+            cache_path.unlink(missing_ok=True)
+    logger.debug("cache miss: will generate fresh quiz (will write to %s)", cache_path)
+    typer.echo("generating quiz from diff...")
+    quiz = _generate_in_memory(pr_url, llm, model, min_diff_lines, max_diff_lines)
+    if quiz is None:
+        return None
+    cache_path.write_text(quiz.model_dump_json())
+    logger.debug("quiz cached at %s (%d bytes)", cache_path, cache_path.stat().st_size)
+    return quiz
+
+
+def _run_take_flow(
+    pr_url: str,
+    show_results_only: bool,
+    llm: LLMClient,
+    model: str = "claude-sonnet-4-6",
+    min_diff_lines: int = 50,
+    max_diff_lines: int = 2000,
+) -> None:
+    if show_results_only:
+        results_md = find_latest_marker_comment(pr_url, _MARKER_RESULTS)
+        if results_md is None:
+            typer.echo("no results comment found on this PR.")
+            raise typer.Exit(code=1)
+        typer.echo(parse_results(results_md).model_dump_json(indent=2))
+        return
+
+    quiz = _load_or_generate(
+        pr_url,
+        llm=llm,
+        model=model,
+        min_diff_lines=min_diff_lines,
+        max_diff_lines=max_diff_lines,
+    )
+    if quiz is None:
+        return
+    _serve_blocking(
+        quiz,
+        pr_url,
+        llm=llm,
+        post_comment_fn=lambda md: post_comment(pr_url, md),
+    )
+
+
+def _configure_logging() -> None:
+    """Wire up `COGNIT_LOG_LEVEL` so debug traces from the engine layers are visible.
+
+    Default is WARNING (quiet). Set `COGNIT_LOG_LEVEL=DEBUG` to see which mermaid
+    validator is being used, cache hits, and other internal decisions:
+
+        COGNIT_LOG_LEVEL=DEBUG cognit take
+
+    `force=True` so a parent harness (uvicorn, pytest) that already configured
+    root logging doesn't make our env var silently a no-op.
+    """
+    level_name = os.environ.get("COGNIT_LOG_LEVEL", "WARNING").upper()
+    level = getattr(logging, level_name, logging.WARNING)
+    logging.basicConfig(
+        level=level,
+        format="%(name)s %(levelname)s: %(message)s",
+        force=True,
+    )
+
+
+def run(
+    pr: str | None,
+    show_results: bool,
+    model: str = "claude-sonnet-4-6",
+    min_diff_lines: int = 50,
+    max_diff_lines: int = 2000,
+) -> None:
+    _configure_logging()
+    pr_url = pr or _detect_pr_from_branch()
+    if pr_url is None:
+        typer.echo("error: no PR detected from current branch; pass --pr <url>")
+        raise typer.Exit(code=1)
+    llm = _make_llm(model)
+    _run_take_flow(
+        pr_url,
+        show_results_only=show_results,
+        llm=llm,
+        model=model,
+        min_diff_lines=min_diff_lines,
+        max_diff_lines=max_diff_lines,
+    )

cognit/cli/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

cognit/comment/parse.py

@@ -0,0 +1,51 @@
+import re
+from cognit.engine.models import Quiz, Answers, Results, QuestionResult
+
+_JSON_BLOCK = re.compile(r"```json\s*\n(.*?)\n```", re.DOTALL)
+
+
+def _extract_json(md: str, marker: str) -> str:
+    if marker not in md:
+        raise ValueError(f"marker {marker!r} not found")
+    after = md.split(marker, 1)[1]
+    m = _JSON_BLOCK.search(after)
+    if not m:
+        raise ValueError(f"no json block after {marker!r}")
+    return m.group(1)
+
+
+def parse_quiz(md: str) -> Quiz:
+    return Quiz.model_validate_json(_extract_json(md, "<!-- cognit:quiz v1 -->"))
+
+
+def parse_answers(md: str) -> Answers:
+    return Answers.model_validate_json(_extract_json(md, "<!-- cognit:answers v1 -->"))
+
+
+def parse_results(md: str) -> Results:
+    """Parse a results comment. Prefers the embedded JSON state; falls back to scraping the human text."""
+    marker = "<!-- cognit:results v1 -->"
+    if marker not in md:
+        raise ValueError("not a results comment")
+    # Prefer JSON state if present (added in v1; older comments may lack it).
+    try:
+        return Results.model_validate_json(_extract_json(md, marker))
+    except ValueError:
+        pass  # No JSON block; fall back to scraping.
+    total = 0
+    m = re.search(r"\*\*Total:\s*(\d+)%\*\*", md)
+    if m:
+        total = int(m.group(1))
+    per: list[QuestionResult] = []
+    for line in md.splitlines():
+        m2 = re.match(r"- (✅|❌) `([^`]+)` — (\d+)%", line)
+        if m2:
+            per.append(
+                QuestionResult(
+                    question_id=m2.group(2),
+                    correct=m2.group(1) == "✅",
+                    score=int(m2.group(3)),
+                    feedback="",
+                )
+            )
+    return Results(pr_number=0, total_score=total, per_question=per)

cognit/comment/render.py

@@ -0,0 +1,123 @@
+from cognit.engine.models import (
+    Quiz,
+    Answers,
+    Results,
+    MCQQuestion,
+    MermaidQuestion,
+    TrueFalseQuestion,
+)
+
+_MARKER_QUIZ = "<!-- cognit:quiz v1 -->"
+_MARKER_ANSWERS = "<!-- cognit:answers v1 -->"
+_MARKER_RESULTS = "<!-- cognit:results v1 -->"
+
+
+def render_quiz(quiz: Quiz) -> str:
+    parts: list[str] = [
+        _MARKER_QUIZ,
+        "## Quiz on your PR",
+        "",
+        "Take it: `cognit take` or scroll down.",
+        "",
+    ]
+    for i, q in enumerate(quiz.questions, 1):
+        parts.append(f"### Question {i} — {q.type}")
+        parts.append(q.prompt)
+        parts.append("")
+        if isinstance(q, MCQQuestion):
+            for label in q.options:
+                parts.append(f"- {label}")
+        elif isinstance(q, MermaidQuestion):
+            for label, src in q.options.items():
+                parts.append(f"#### Option {label}")
+                parts.append("```mermaid")
+                parts.append(src)
+                parts.append("```")
+        elif isinstance(q, TrueFalseQuestion):
+            parts.append("- true / false")
+        # open: just the prompt; no extra rendering
+        parts.append("")
+    parts.append("---")
+    parts.append("<details><summary>Quiz state (used by the CLI)</summary>")
+    parts.append("")
+    parts.append("```json")
+    parts.append(quiz.model_dump_json(indent=2))
+    parts.append("```")
+    parts.append("</details>")
+    return "\n".join(parts)
+
+
+def render_answers(ans: Answers, deterministic_score: int) -> str:
+    return (
+        f"{_MARKER_ANSWERS}\n"
+        f"## My answers\n\n"
+        f"Deterministic-grade score (MCQ + mermaid + T/F): **{deterministic_score}%**\n\n"
+        f"```json\n{ans.model_dump_json(indent=2)}\n```\n"
+    )
+
+
+def render_results(res: Results) -> str:
+    lines: list[str] = [
+        _MARKER_RESULTS,
+        "## Quiz results",
+        "",
+        f"**Total: {res.total_score}%**",
+        "",
+    ]
+    for r in res.per_question:
+        icon = "✅" if r.correct else "❌"
+        lines.append(f"- {icon} `{r.question_id}` — {r.score}%")
+        if r.feedback:
+            lines.append(f"  > {r.feedback}")
+    lines.append("")
+    lines.append("---")
+    lines.append("<details><summary>Results state (used by the CLI)</summary>")
+    lines.append("")
+    lines.append("```json")
+    lines.append(res.model_dump_json(indent=2))
+    lines.append("```")
+    lines.append("</details>")
+    return "\n".join(lines)
+
+
+def render_results_inlined(quiz: Quiz, answers: Answers, results: Results) -> str:
+    """Render results with question prompts and author answers inlined.
+
+    The in-memory-only flow no longer posts a quiz comment to the PR, so the published
+    results comment must be self-contained. Each question is rendered with its prompt,
+    the author's answer, the score, and any feedback. The JSON state block at the
+    bottom is preserved so `parse_results` still round-trips.
+    """
+    answer_by_qid = {e.question_id: e.value for e in answers.entries}
+    result_by_qid = {r.question_id: r for r in results.per_question}
+
+    lines: list[str] = [
+        _MARKER_RESULTS,
+        "## Quiz results",
+        "",
+        f"**Total: {results.total_score}%**",
+        "",
+    ]
+    for i, q in enumerate(quiz.questions, 1):
+        r = result_by_qid.get(q.id)
+        if r is None:
+            continue
+        icon = "✅" if r.correct else "❌"
+        lines.append(f"### Question {i} — {icon} {r.score}%")
+        lines.append("")
+        lines.append(f"**Prompt:** {q.prompt}")
+        lines.append("")
+        user_answer = answer_by_qid.get(q.id, "")
+        lines.append(f"**Your answer:** `{user_answer}`")
+        if r.feedback:
+            lines.append("")
+            lines.append(f"> {r.feedback}")
+        lines.append("")
+    lines.append("---")
+    lines.append("<details><summary>Results state (used by the CLI)</summary>")
+    lines.append("")
+    lines.append("```json")
+    lines.append(results.model_dump_json(indent=2))
+    lines.append("```")
+    lines.append("</details>")
+    return "\n".join(lines)

cognit/engine/_mermaid_docker/Dockerfile

@@ -0,0 +1,20 @@
+# Tiny parse-only mermaid validator. No Chromium, no rendering — just mermaid.parse().
+#
+# The official `@mermaid-js/mermaid-cli` image (~500MB) bundles Puppeteer +
+# Chromium for image rendering. We only need parsing, so we install just the
+# `mermaid` library + a Node-side DOM shim (jsdom). Image size: ~200MB.
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Manual package.json so npm doesn't complain. ESM type so mermaid v11 works.
+# Pinned to specific minor versions for reproducible builds — bump deliberately
+# when picking up a new mermaid release rather than letting a silent upstream
+# change drift the validator.
+RUN echo '{"name":"cognit-mermaid-validator","version":"1.0.0","type":"module","private":true}' > package.json \
+ && npm install --no-audit --no-fund --no-progress mermaid@11.15.0 jsdom@24.0.0 \
+ && npm cache clean --force
+
+COPY validate.mjs /app/validate.mjs
+
+ENTRYPOINT ["node", "/app/validate.mjs"]

cognit/engine/_mermaid_docker/README.md

@@ -0,0 +1,28 @@
+# Dockerised mermaid validator
+
+Tiny parse-only mermaid validator. Used by `engine/mermaid.py` when `mmdc` is not
+installed locally but `docker` is.
+
+**Why this exists.** The official `@mermaid-js/mermaid-cli` Docker image bundles
+Puppeteer + Chromium (~500MB) because `mmdc` does image rendering. We only need
+*parsing* to validate LLM-generated diagrams, so this image installs just the
+`mermaid` JS library + `jsdom` (~200MB total).
+
+**Built lazily.** `cognit` runs `docker build` the first time it needs the
+validator and an image isn't already present. After that, validation runs in
+milliseconds per diagram via `docker run`.
+
+**Build manually:**
+
+```bash
+docker build -t cognit-mermaid-validator:local src/cognit/engine/_mermaid_docker/
+```
+
+**Use manually:**
+
+```bash
+echo 'flowchart LR
+A --> B' | docker run --rm -i cognit-mermaid-validator:local
+```
+
+Exit code 0 = valid, 1 = parse error (message on stderr).

cognit/engine/_mermaid_docker/validate.mjs

@@ -0,0 +1,32 @@
+// Parse-only mermaid validator. Reads a mermaid source from stdin, calls
+// mermaid.parse(), exits 0 on success and 1 on parse error. The error message
+// (if any) goes to stderr so the caller can surface it.
+//
+// We set up jsdom before importing mermaid because mermaid touches `document`
+// at module-load time even in pure-parse mode. The HTML doc is empty — we
+// never render, just parse.
+
+import { JSDOM } from "jsdom";
+
+const dom = new JSDOM("<!DOCTYPE html><html><body></body></html>", {
+  pretendToBeVisual: true,
+});
+globalThis.window = dom.window;
+globalThis.document = dom.window.document;
+globalThis.navigator = dom.window.navigator;
+globalThis.HTMLElement = dom.window.HTMLElement;
+globalThis.Node = dom.window.Node;
+
+const mermaid = (await import("mermaid")).default;
+
+const chunks = [];
+for await (const chunk of process.stdin) chunks.push(chunk);
+const src = Buffer.concat(chunks).toString("utf-8");
+
+try {
+  await mermaid.parse(src);
+  process.exit(0);
+} catch (e) {
+  process.stderr.write(String(e && e.message ? e.message : e) + "\n");
+  process.exit(1);
+}