LoCAL2 Phase 18 — Explainable AI (XAI)

MemoryService.search_episodic() already returns a composite score per result (cosine similarity + entity overlap + critic weight). The MemoryWindow Search mode discards it — only content and metadata are displayed.

What changes

• ui/memory_window.py — add "Score" column to _EPISODIC_COLS (between "Age" and "Query"). Format as "0.87" (2 decimal places).
• _populate_episodic() — read row_data.get("score") and include it in the per-row values list. It is already present in every dict returned by search_episodic.
• Browse mode also benefits: for browse results, score is absent (list_episodic doesn't score), so show "—".

Data flow (unchanged)

The absolute grading rubric — what distinguishes a 1 from a 3 from a 5 — is buried in config/critic.yaml. Users see a numeric badge with no grading criteria. This undermines trust in the score, because the Prometheus feedback (Phase 18f) references criteria the user hasn't seen.

The rubric is the evaluation contract: Prometheus feedback is always written against it. Disclosing the rubric completes the XAI chain — users can read the score, read the feedback, and then read the rubric to understand exactly what criteria were applied.

What changes

• ui/critic_window.py — add a third stack page (alongside the existing activity log and settings pages) that shows the rubric text. CriticWindow inherits BaseObservabilityWindow's two-page stack; extend to three pages.
• Add a "?" button in the CriticWindow header (next to the ⚙ gear). Toggles to rubric page.
• Rubric page: loads config/critic.yaml, reads the rubric key, displays as a styled QTextEdit (read-only, monospace).
• BaseObservabilityWindow may need a small refactor to support a third page, or CriticWindow can manage the extra page itself since it's critic-specific.

Design note

The rubric in critic.yaml is a multi-line string already formatted for human reading (Prometheus-style). Just render it as-is — no parsing needed.

Thinking tokens show Gemma's reasoning. The answer shows the result. But the tool calls that happened between — Gemma decided to call search_memory, then web_search — are only visible in the side panels. The main response card should show the step chain.

Visual target

[10:42:12] RESPONSE  ✓

◈ thinking  ▼
[collapsed thinking block]

→ search_memory  "previous discussion about flux"
→ web_search  "flux capacitor timeline 2024"
→ web_fetch  "https://example.com/flux"

[answer text here]

● 4/5  👍 👎

What changes

• ui/main_window.py — StreamingResponseWidget:
  • Add a QVBoxLayout container (between thinking block and answer) called self._trace_layout.
  • Method add_tool_step(tool_name: str, preview: str) appends a dim label row: "→ tool_name <preview>". Preview is the first arg truncated to 60 chars.
  • The trace section is hidden until the first step is added.
• ui/main_window.py — MainWindow:
  • Subscribe to all tool.activity.* subjects (already done via _TOOL_ACTIVITY_SUBJECTS).
  • In the activity handler, on event "request": look up the pending response widget by correlation_id and call add_tool_step(tool_name, query_preview).
  • The correlation_id on tool activity events matches the original query_id (confirmed: GeneratorAgent threads it through all tool calls).

Data flow

This is the core XAI gap. When Gemma uses search_memory or search_library, the retrieved snippets are passed as text in the tool result — but which specific engrams or document chunks were fetched is lost before the answer is rendered. The user cannot tell whether Gemma cited two engrams from last week or three chunks from a PDF they uploaded.

What changes

1. SearchMemoryTool — emit source IDs in activity

In tools/search_memory_tool.py, _search() iterates candidates (which already carries id, score, content, metadata). Before returning the text string, collect source metadata and pass it to _publish_activity:

sources = [
    {
        "id": c["id"],
        "score": round(c["score"], 3),
        "snippet": c["content"][:80],
        "query": c["metadata"].get("query", ""),
    }
    for c in candidates
]
self._publish_activity("result", {"result": result, "sources": sources}, correlation_id)

2. SearchLibraryTool — emit source refs in activity

In tools/search_library_tool.py, _search() iterates hits (already has source_file, chunk_index, page, content). Collect and emit:

sources = [
    {
        "source_file": h["source_file"],
        "chunk_index": h.get("chunk_index"),
        "page": h.get("page"),
        "snippet": h["content"].strip()[:80],
    }
    for h in hits
]
self._publish_activity("result", {"result": result, "sources": sources}, correlation_id)

3. MainWindow — accumulate sources per turn

Add self._pending_sources: dict[str, list[dict]] = {}. In the tool activity handler, on event "result" for search tools, merge incoming sources into self._pending_sources[correlation_id].

4. MainWindow._on_response — inject sources into widget

After the response widget is finalized, if query_id is in self._pending_sources, call widget.set_sources(sources) and remove from the pending dict to avoid leaking.

5. StreamingResponseWidget — sources strip

Add a collapsible "Sources" section at the bottom of the response card, below the answer and above the score/thumbs row.

▼ 3 sources
  ┌ memory: "What is the capital of…"  (score 0.87, 2d ago)
  ├ memory: "Discussed flux capacitor…"  (score 0.71, 1h ago)
  └ library: research-paper.pdf p.4, chunk 12

The sources strip is collapsed by default; a "▼ N sources" toggle expands it. Each source row is a label — memory rows show query preview + age, library rows show filename + page.

Data flow

Even with the sources strip (18d), a user glancing at the conversation log can't immediately tell whether a response drew on retrieved evidence or pure training knowledge. A groundedness indicator makes this scannable at a glance.

What changes

Indicator design

A small badge in the response card header row, next to the timestamp:

[10:42:12] RESPONSE  ✓   ⊙ grounded       ← retrieved sources used
[10:44:05] RESPONSE  ✓   ○ knowledge       ← answered from training only

Three groundedness levels, tracked by which tools fired:

• ⊙ grounded (teal) — search_memory, search_library, or search_papers fired
• ◉ web (blue) — web_search or web_fetch fired
• ○ knowledge (dim gray) — no retrieval tools fired this turn

If both web and memory tools fire, show the highest-confidence indicator (web > grounded).

Implementation

• StreamingResponseWidget: add a small QLabel self._ground_label in the header row. Initially hidden. Method set_groundedness(level: str) sets text and color.
• MainWindow: add self._pending_ground: dict[str, set[str]] = {}. In the tool activity handler on event "request", add the tool name to the set for that correlation_id.
• In _on_response, look up the tool set, derive groundedness level, call widget.set_groundedness(level).

Every response already receives a paragraph of natural language feedback from Prometheus explaining why it earned its score. This is the primary XAI artifact the system produces. It is currently set as a tooltip on the score label — hover-only, invisible by default, truncated to a single line.

The fix mirrors the thinking token pattern already in StreamingResponseWidget: a collapsible toggle that expands to show the full feedback text below the score badge.

Visual target

[10:42:12] RESPONSE  ✓   ⊙ grounded

◈ thinking  ▼
[collapsed]

→ search_memory  "previous discussion…"

[answer text]

▼ sources

● 4/5  ◈ Prometheus  ▼         ← new toggle, replaces bare label
  The response correctly identifies the core mechanism and provides
  a clear explanation. Minor gaps: it doesn't address edge cases
  mentioned in the rubric's Score 5 criteria.

👍 👎

What changes

• ui/main_window.py — StreamingResponseWidget:
  • Replace self._score_label (plain QLabel) with a QPushButton styled as a toggle — same pattern as self._toggle_btn for thinking.
  • Add self._feedback_box: a QTextEdit (read-only, max height ~120px, initially hidden) below the score button.
  • set_score(score, feedback): set button text to f"● {score}/5 ◈ Prometheus ▼"; store feedback text; connect button click to toggle self._feedback_box visibility.
  • Remove the setToolTip(feedback) call — tooltip is superseded by the expandable block.
• No bus, protocol, or agent changes — CritiqueResult.feedback is already delivered to MainWindow._on_critique() and passed to widget.set_score().

Data flow (unchanged — feedback already arrives)

These ideas are valid extensions of the Prometheus XAI capability but are deferred to avoid scope creep:

• Custom rubric presets — selectable rubrics per session (toxicity, hallucination rate, domain compliance, factual accuracy). Prometheus is capable of evaluating all of these given the right rubric. Implementation: a rubric dropdown in CriticWindow settings; config/critic.yaml gains a rubric_presets map.
• On-demand pairwise comparison — Gemma-callable critic_comparison tool (the infrastructure exists as CriticAgentTool, removed in Phase 5 when RespondentB was cut). With single-respondent architecture, pairwise comparison would evaluate two user-supplied alternatives rather than two system respondents. Prometheus provides a reasoned ranking with explanation — the XAI output, not just a winner flag.
• Feedback annotation in MemoryWindow — show Prometheus feedback alongside critic score in the episodic memory table detail pane, so users can see not just that an engram scored 4/5 but why.