Add modular prompt composition and dialog subsystem for AI reviewer

prompts/: per-prompt template.md + spec.yaml with Jinja loops over
toggleable list items, shared fragments, PromptLibrary.render(overrides, note).
dialog/: Dialog/Option/Answer schema, YAML loader, presenter interface with
menu renderer and overrides resolver, optimization_strategy spec.

Author: OutlyingWest

jumper_extension/adapters/ai_reviewer/dialog/__init__.py

@@ -0,0 +1,20 @@
+from jumper_extension.adapters.ai_reviewer.dialog.loader import load_all, load_dialog
+from jumper_extension.adapters.ai_reviewer.dialog.models import Answer, Dialog, Option
+from jumper_extension.adapters.ai_reviewer.dialog.runner import (
+    DefaultPresenter,
+    DialogPresenter,
+    render_menu,
+    resolve_overrides,
+)
+
+__all__ = [
+    "Answer",
+    "DefaultPresenter",
+    "Dialog",
+    "DialogPresenter",
+    "Option",
+    "load_all",
+    "load_dialog",
+    "render_menu",
+    "resolve_overrides",
+]

jumper_extension/adapters/ai_reviewer/dialog/loader.py

@@ -0,0 +1,39 @@
+from pathlib import Path
+
+import yaml
+
+from jumper_extension.adapters.ai_reviewer.dialog.models import Dialog, Option
+
+_SPECS_DIR = Path(__file__).parent / "specs"
+
+
+def load_dialog(dialog_id: str, specs_dir: Path = _SPECS_DIR) -> Dialog:
+    return _build_dialog(yaml.safe_load((specs_dir / f"{dialog_id}.yaml").read_text()))
+
+
+def load_all(specs_dir: Path = _SPECS_DIR) -> dict[str, Dialog]:
+    return {
+        path.stem: _build_dialog(yaml.safe_load(path.read_text()))
+        for path in sorted(specs_dir.glob("*.yaml"))
+    }
+
+
+def _build_dialog(data: dict) -> Dialog:
+    options = tuple(
+        Option(
+            id=entry["id"],
+            label=entry["label"],
+            effect=entry.get("effect") or {},
+            description=entry.get("description", ""),
+            default=bool(entry.get("default", False)),
+            require_note=bool(entry.get("require_note", False)),
+        )
+        for entry in data["options"]
+    )
+    return Dialog(
+        id=data["id"],
+        header=data["header"],
+        options=options,
+        kind=data.get("kind", "single"),
+        allow_note=bool(data.get("allow_note", False)),
+    )

jumper_extension/adapters/ai_reviewer/dialog/models.py

@@ -0,0 +1,49 @@
+import dataclasses
+
+
+@dataclasses.dataclass(frozen=True)
+class Option:
+    """One selectable choice in a dialog.
+
+    ``effect`` is an opaque payload interpreted by a domain handler (for the
+    optimization dialogs it holds ``{"overrides": {id: enabled}}``), which keeps
+    the dialog schema decoupled from whatever the choice controls.
+    """
+    id: str
+    label: str
+    effect: dict = dataclasses.field(default_factory=dict)
+    description: str = ""
+    default: bool = False
+    require_note: bool = False
+
+
+@dataclasses.dataclass(frozen=True)
+class Dialog:
+    """A single question with its options.
+
+    Identical whether loaded from ``specs/*.yaml`` (deterministic) or built by
+    the agent at runtime (dynamic) - the presenter and handlers treat both the
+    same way.
+    """
+    id: str
+    header: str
+    options: tuple[Option, ...]
+    kind: str = "single"          # single | multi | text
+    allow_note: bool = False
+
+    def default_option(self) -> Option:
+        for option in self.options:
+            if option.default:
+                return option
+        return self.options[0]
+
+
+@dataclasses.dataclass(frozen=True)
+class Answer:
+    dialog_id: str
+    selected: tuple[str, ...]
+    note: str | None = None
+
+    @property
+    def option_id(self) -> str:
+        return self.selected[0]

jumper_extension/adapters/ai_reviewer/dialog/runner.py

@@ -0,0 +1,58 @@
+from jumper_extension.adapters.ai_reviewer.dialog.models import Answer, Dialog
+
+
+class DialogPresenter:
+    """Renders a dialog in the chat and returns the user's answer.
+
+    Concrete presenters (notebook widget, terminal, ...) implement ``present``.
+    Everything else depends only on this interface, so the presentation
+    technology can change without touching dialog specs, the schema, or the
+    effect handlers.
+    """
+
+    def present(self, dialog: Dialog) -> Answer:
+        raise NotImplementedError
+
+
+class DefaultPresenter(DialogPresenter):
+    """Non-interactive fallback: selects each dialog's default option.
+
+    Used when ``interactive: false``, in tests, and until a real widget
+    presenter is wired in.
+    """
+
+    def present(self, dialog: Dialog) -> Answer:
+        option = dialog.default_option()
+        return Answer(dialog_id=dialog.id, selected=(option.id,))
+
+
+def render_menu(
+    dialog: Dialog,
+    cursor: int,
+    selected: set[str],
+    note: str | None = None,
+) -> str:
+    """Text of the arrow-select menu; ``❯`` marks the cursor row.
+
+    Reused by any concrete presenter regardless of the widget technology.
+    """
+    lines = [f"{dialog.header}:"]
+    for index, option in enumerate(dialog.options):
+        pointer = "❯" if index == cursor else " "
+        if dialog.kind == "multi":
+            mark = "[x]" if option.id in selected else "[ ]"
+        else:
+            mark = "●" if option.id in selected else "○"
+        lines.append(f"{pointer} {mark} {option.label}")
+    if note:
+        lines.append(f"      note: {note}")
+    return "\n".join(lines)
+
+
+def resolve_overrides(dialog: Dialog, answer: Answer) -> dict:
+    """Merge the ``overrides`` payloads of the selected options into one map."""
+    by_id = {option.id: option for option in dialog.options}
+    overrides = {}
+    for option_id in answer.selected:
+        overrides.update(by_id[option_id].effect.get("overrides", {}))
+    return overrides

jumper_extension/adapters/ai_reviewer/dialog/specs/optimization_strategy.yaml

@@ -0,0 +1,27 @@
+id: optimization_strategy
+header: Optimization strategy
+kind: single
+allow_note: true                      # key `n` attaches a free-text note to any option
+
+options:
+  - id: faster
+    label: Just make it faster
+    default: true
+    description: Agent figures out the bottlenecks and suggests several options.
+    effect:
+      overrides: {}
+
+  - id: parallelization
+    label: Focus on parallelization
+    description: Agent focuses on GPU under-use and threading/multiprocessing libraries.
+    effect:
+      overrides:
+        gpu_offload: true
+        parallel_analysis_hint: true
+
+  - id: custom
+    label: Explain what you need
+    description: Free-form instruction to the agent.
+    require_note: true
+    effect:
+      overrides: {}

jumper_extension/adapters/ai_reviewer/prompts/__init__.py

@@ -0,0 +1,78 @@
+from pathlib import Path
+
+import yaml
+from jinja2 import Environment, FileSystemLoader
+
+_PROMPTS_DIR = Path(__file__).parent
+_FRAGMENTS_DIR = _PROMPTS_DIR / "fragments"
+
+
+class PromptLibrary:
+    """Composes the AI-reviewer system prompts from per-prompt templates + specs.
+
+    Each prompt has its own folder (``analyze``/``suggest``/``refine``) with a
+    ``template.md`` (Jinja prose + loops over list items) and a ``spec.yaml``
+    (the toggleable items, each ``{id, enabled, text|fragment}``).
+
+    ``render`` takes an ``overrides`` map (``id -> enabled``) so any caller - a
+    deterministic dialog or one an agent builds at runtime - can flip items
+    on/off without this layer knowing where the choice came from.
+    """
+
+    def __init__(self, specs: dict[str, dict], env: Environment):
+        self._specs = specs
+        self._env = env
+
+    @classmethod
+    def load(cls, root: Path = _PROMPTS_DIR) -> "PromptLibrary":
+        env = Environment(
+            loader=FileSystemLoader(str(root)),
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+        specs = {
+            prompt_dir.name: _resolve_fragments(
+                yaml.safe_load((prompt_dir / "spec.yaml").read_text()) or {}
+            )
+            for prompt_dir in sorted(root.iterdir())
+            if (prompt_dir / "template.md").exists()
+        }
+        return cls(specs, env)
+
+    def prompt_ids(self) -> list[str]:
+        return list(self._specs)
+
+    def render(
+        self,
+        prompt_id: str,
+        overrides: dict | None = None,
+        note: str | None = None,
+    ) -> str:
+        overrides = overrides or {}
+        context = {}
+        for key, value in self._specs[prompt_id].items():
+            if isinstance(value, list):
+                context[key] = [
+                    {**item, "enabled": overrides.get(item["id"], item["enabled"])}
+                    for item in value
+                ]
+            else:
+                context[key] = {**value, "enabled": bool(note), "text": note or ""}
+        template = self._env.get_template(f"{prompt_id}/template.md")
+        return template.render(**context).strip() + "\n"
+
+
+def _resolve_fragments(spec: dict) -> dict:
+    resolved = {}
+    for key, value in spec.items():
+        if isinstance(value, list):
+            resolved[key] = [_resolve_item(item) for item in value]
+        else:
+            resolved[key] = _resolve_item(value)
+    return resolved
+
+
+def _resolve_item(item: dict) -> dict:
+    if "fragment" in item:
+        return {**item, "text": (_FRAGMENTS_DIR / item["fragment"]).read_text().strip()}
+    return item

jumper_extension/adapters/ai_reviewer/prompts/analyze/spec.yaml

@@ -0,0 +1,17 @@
+given:
+  - id: an_cell_source
+    enabled: true
+    text: Source code of a notebook cell
+  - id: perf_tags
+    enabled: true
+    text: Performance classification tags JUmPER assigned to it
+  - id: metrics_summary
+    enabled: true
+    text: Summary of the measured CPU/GPU/memory metrics, and a description of the available hardware
+
+hints:
+  - id: parallel_analysis_hint
+    enabled: false
+    text: >-
+      Pay special attention to whether the workload under-uses available parallel
+      hardware - an idle GPU or unused CPU cores.

jumper_extension/adapters/ai_reviewer/prompts/analyze/template.md

@@ -0,0 +1,16 @@
+You are a performance engineering assistant embedded in a Jupyter notebook profiler called JUmPER.
+
+You are given the:
+{% for item in given if item.enabled %}
+    - {{ item.text | indent(6) }}
+{% endfor %}
+
+Identify the most likely performance bottleneck of the cell in 2-4 sentences.
+Be concrete: name the resource that is the bottleneck, point at the part of the
+code responsible for it, and explain why the measured metrics support your
+conclusion. Do not propose code changes here - that happens in a later step.
+Respond with plain text only, no markdown headings.
+{% for item in hints if item.enabled %}
+
+{{ item.text }}
+{% endfor %}

jumper_extension/adapters/ai_reviewer/prompts/fragments/gpu_offload.md

@@ -0,0 +1,4 @@
+If the hardware includes one or more GPUs and the code contains a workload that can be efficiently parallelized:
+  - Include at least one option that refactors the CPU implementation to run on the GPU, whichever fits the existing code with the least disruption.
+  - Prefer using preinstalled libraries (check the list of "Available libraries").
+Skip this if no GPU is available or the workload is not a good parallelization candidate (e.g. it is I/O-bound or inherently sequential).

jumper_extension/adapters/ai_reviewer/prompts/fragments/pep8_multiline.md

@@ -0,0 +1 @@
+Write code as properly formatted multi-line Python with real newlines between statements (PEP 8 style), never as a semicolon-joined one-liner.