pi-fluency 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ihar Trafimovich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# Pi Fluency
+
+Pi Fluency is a Pi extension that turns recurring English mistakes in human-authored prompts into private, keyboard-first coaching. It analyzes sanitized interactive prose after Pi settles, asks you to review each detected occurrence, and tracks accepted mistakes per 1,000 English words across projects and sessions.
+
+## Privacy
+
+Pi Fluency collects only `input` events with `source === "interactive"`. It excludes RPC/API input, extension-injected messages such as Ralph and subagent control prompts, slash commands, fenced and indented code, inline code, assistant messages, and tool output.
+
+Before analysis it:
+
+- strips terminal control sequences;
+- removes code;
+- redacts common API keys, tokens, secrets, passwords, private keys, JWTs, cloud credentials, and URL user-info credentials;
+- hashes the sanitized prose for replay protection.
+
+Language classification belongs to the selected analyzer model. English results create word-count observations; non-English results must contain no mistakes or demonstrated fixes and contribute nothing to analytics.
+
+After explicit consent, Pi Fluency sends the selected provider:
+
+- filtered, redacted prose;
+- up to 500 newest eligible pending or accepted rules, represented by internal key, explanation, and ERRANT type;
+- controlled ERRANT error types and context-scope choices for structured output.
+
+Full prompts are never written to history. Local history stores prompt hashes, timestamps, local dates, English word counts, occurrence decisions, and bounded sanitized finding excerpts/corrections/explanations. An excerpt may equal an entire short sanitized prompt. Demonstrated-fix evidence is processed in memory but omitted from persisted events. Data goes only to the model provider selected during setup.
+
+Global data lives under `~/.pi/agent/pi-fluency/`. The directory is restricted to mode `0700`; history and settings files use `0600`.
+
+## Install
+
+**Requires Pi 0.80.10 or newer.**
+
+```sh
+pi install npm:pi-fluency
+```
+
+Run `/reload` after installation.
+
+For local development:
+
+```sh
+git clone https://github.com/unutranyholas/pi-fluency.git
+cd pi-fluency
+npm install
+pi -e ./extensions/pi-fluency/index.ts
+```
+
+## First run
+
+Run `/fluency`. Select an available low-cost analyzer model, review the provider disclosure, and accept consent. Analysis remains disabled unless setup completes. Provider credentials come from Pi's model registry.
+
+## Review model
+
+Each Inbox card represents every currently pending occurrence of one concrete rule.
+
+- **Accept** confirms only the current pending batch. Accepted occurrences enter analytics. A later recurrence opens the rule in Inbox again.
+- **Dismiss** rejects only the current pending batch. It does not suppress future recurrence and does not enter the mistake-rate numerator.
+- **Ignore** persistently hides an exact rule or ERRANT category. Hidden pending occurrences remain stored and return when restored. Already accepted history remains accepted.
+- **Clear** removes coaching and analytics history while preserving settings, model choice, and consent.
+
+Rules use stable namespaced keys and full ERRANT types such as `M:DET`, `U:PUNCT`, and `R:VERB:FORM`. Internal keys and ERRANT codes are not shown in coaching or Stats UI.
+
+## Toolbar
+
+Normal toolbar example:
+
+```text
+󰇮 12  󰌵 6  ▆▄▃▂▁▂▂ 8.4/k
+```
+
+| Part | Meaning |
+| --- | --- |
+| `󰇮 12` | 12 visible pending occurrences; `󰇰` means zero |
+| `󰌵 6` | 6 recurring rule-explanation groups with accepted occurrences in the trailing seven days |
+| `▆▄▃▂▁▂▂` | Seven rolling seven-day accepted-mistake rates |
+| `8.4/k` | Latest accepted mistakes per 1,000 English words |
+
+Counts are real and unclamped. A missing denominator renders `—/k`; missing sparkline points render `·`. Startup shows a loading-shaped toolbar. Stable errors are bounded to:
+
+```text
+󰅙 ERR auth
+󰅙 ERR model
+󰅙 ERR analyze
+󰅙 ERR store
+󰅙 ERR migrate
+```
+
+Full sanitized error detail appears in notifications. `/fluency status` reports state, model, queue, drops, and storage warning count. Stock Pi receives the complete toolbar text. Powerbar receives the leading Nerd Font icon separately to avoid duplication. With Powerbar installed, add **Pi Fluency** through `/extension-settings`.
+
+## Commands and keyboard controls
+
+`Ctrl+Shift+L` opens Inbox when configured.
+
+| Command | Action |
+| --- | --- |
+| `/fluency` | Run setup when unconfigured; otherwise open Inbox |
+| `/fluency stats` | Open local Stats directly, including while paused or model-offline |
+| `/fluency pause` | Stop analysis and hide status |
+| `/fluency resume` | Resume a valid consented configuration |
+| `/fluency status` | Show state, model, queue, drops, and storage warnings |
+| `/fluency model` | Select another analyzer model and review provider disclosure |
+| `/fluency clear` | Confirm, then remove coaching and analytics history |
+
+Inside the overlay:
+
+- Left/Right changes cards.
+- Up/Down, `j`/`k`, and Page Up/Down scroll.
+- `a` accepts the current Inbox batch; `l` remains a compatibility alias.
+- `d` dismisses the current Inbox batch.
+- `i` ignores an exact rule or ERRANT category.
+- `u` restores every ignore affecting an item in Ignored.
+- Tab cycles Inbox, Accepted, Ignored, and Stats.
+- Esc closes.
+
+Actions auto-advance to the next card. Stats is read-only. Compact diffs use `└─` for replacements, strikethrough for deletions, and underline for insertions.
+
+## Analytics and Stats
+
+For a period `P`:
+
+```text
+accepted mistake rate(P) = accepted occurrences in P / English words in P × 1000
+```
+
+Every analyzer-classified English prompt contributes words, including prompts with zero findings. Pending, dismissed, hidden-unaccepted, and non-English occurrences do not enter the numerator.
+
+Stats covers 30 local calendar days and shows:
+
+- 30-day accepted rate, English words, accepted, dismissed, and visible pending totals;
+- a single aggregate count for one-off accepted mistakes in the period;
+- review coverage: `(accepted + dismissed) / (accepted + dismissed + visible pending)`;
+- active trailing-seven-day recurring rules;
+- rolling seven-day toolbar trend;
+- recurring-rule rates, sparklines, and `improving`, `worsening`, `stable`, or `new` trends.
+
+A rule becomes recurring after at least two accepted occurrences across retained history. One-offs remain part of accepted totals and rates, but do not clutter the toolbar count, Concrete rules list, or trend totals. Rule trends compare adjacent 30-day windows. Improving/worsening requires both at least 20% relative change and at least 0.5 mistakes per 1,000 words absolute change. Rules are grouped and displayed by human explanation, never by internal key or broad category.
+
+## Storage and migration
+
+`settings.json`, `history.jsonl`, and the private clear-generation marker are shared globally across Pi projects and sessions. Analyzer responses and current settings use schema v3. History uses strict schema v4 events with deterministic occurrence IDs. Compaction:
+
+- retains every pending occurrence regardless of age;
+- retains 365 local calendar days of reviewed observations and occurrences;
+- preserves hashes referenced by retained observations;
+- writes state-free schema-v4 snapshots under an atomic cross-process lock.
+
+History schema v4 is a clean break. Non-empty v1, v2, or v3 history is not interpreted, normalized, or rewritten. Pi Fluency reports `ERR migrate` and blocks history mutations until confirmed clear. There is no automatic migration or backup. Current schema-v3 settings, provider choice, and consent remain intact.
+
+### Safe history reset
+
+Direct `history.jsonl` edits are unsupported, especially while the extension is running. To recover from old, polluted, or unwanted history:
+
+1. Run `/reload` after installing the updated extension.
+2. Run `/fluency clear`.
+3. Confirm the prompt.
+4. Verify `/fluency stats` is empty and settings/model/consent remain configured.
+
+Pi Fluency adopts the English error taxonomy from the MIT-licensed [ERRANT toolkit](https://github.com/chrisjbryant/errant) and its [ACL 2017 paper](https://aclanthology.org/P17-1074/). It does not bundle ERRANT, Python, spaCy, language models, or learner corpora.
+
+## Development
+
+```sh
+npm install
+npm run check
+pi -e ./extensions/pi-fluency/index.ts
+```
+
+Automated tests always use temporary storage roots and never touch `~/.pi/agent/pi-fluency/`.
+
+## Known limitations
+
+The overlay is available only in interactive TUI mode. Pi has no native low-priority scheduler, so Pi Fluency queues bounded work and starts analysis only after the main agent settles and Pi reports idle. Redaction is defense in depth, not a substitute for avoiding secrets in prompts.

package/extensions/pi-fluency/analytics.ts

@@ -0,0 +1,253 @@
+import { errantCategory } from "./taxonomy.js";
+import type {
+  EnglishObservation,
+  MistakeOccurrence,
+  MistakePattern,
+} from "./types.js";
+import type { ErrantCategory } from "./taxonomy.js";
+
+const ENGLISH_WORD = /[\p{L}\p{N}]+(?:['’][\p{L}\p{N}]+)*/gu;
+const SPARK_GLYPHS = "▁▂▃▄▅▆▇█";
+const DATE_KEY = /^\d{4}-\d{2}-\d{2}$/;
+const TREND_DAYS = 30;
+
+/** Count word-like runs after the analyzer has classified sanitized prose as English. */
+export function countEnglishWords(prose: string): number {
+  return [...prose.matchAll(ENGLISH_WORD)].length;
+}
+
+export type RuleTrend = "improving" | "worsening" | "stable" | "new";
+
+export interface RuleAnalytics {
+  patternId: string;
+  explanation: string;
+  accepted: number;
+  ratePerThousand: number | undefined;
+  sparkline: string;
+  trend: RuleTrend;
+  changePercent?: number;
+}
+
+export interface FluencyAnalytics {
+  pendingOccurrences: number;
+  periodPendingOccurrences: number;
+  activeRules: number;
+  currentRatePerThousand?: number;
+  periodRatePerThousand?: number;
+  toolbarSparkline: string;
+  englishWords: number;
+  accepted: number;
+  dismissed: number;
+  oneOffAccepted: number;
+  reviewCoverage?: number;
+  rules: RuleAnalytics[];
+  trendCounts: Record<RuleTrend, number>;
+}
+
+export interface AnalyticsInput {
+  observations: Iterable<EnglishObservation>;
+  occurrences: Iterable<MistakeOccurrence>;
+  patterns: Iterable<MistakePattern>;
+  ignoredPatternKeys: ReadonlySet<string>;
+  ignoredCategories: ReadonlySet<ErrantCategory>;
+  now: number;
+}
+
+export function ratePerThousand(accepted: number, words: number): number | undefined {
+  return words > 0 ? accepted * 1_000 / words : undefined;
+}
+
+export function renderSparkline(values: Array<number | undefined>): string {
+  const finite = values.filter((value): value is number =>
+    typeof value === "number" && Number.isFinite(value));
+  if (finite.length === 0) return values.map(() => "·").join("");
+  const minimum = Math.min(...finite);
+  const maximum = Math.max(...finite);
+  return values.map((value) => {
+    if (value === undefined || !Number.isFinite(value)) return "·";
+    if (minimum === maximum) return maximum === 0 ? SPARK_GLYPHS[0]! : SPARK_GLYPHS[3]!;
+    const index = Math.round((value - minimum) / (maximum - minimum) * (SPARK_GLYPHS.length - 1));
+    return SPARK_GLYPHS[Math.max(0, Math.min(SPARK_GLYPHS.length - 1, index))]!;
+  }).join("");
+}
+
+export function classifyRuleTrend(
+  current: number | undefined,
+  previous: number | undefined,
+): RuleTrend {
+  if (current === undefined || !Number.isFinite(current) || current <= 0) {
+    if (previous === undefined || !Number.isFinite(previous) || previous <= 0) return "stable";
+  }
+  if (current !== undefined && Number.isFinite(current) && current > 0
+    && (previous === undefined || !Number.isFinite(previous) || previous <= 0)) return "new";
+  if (current === undefined || previous === undefined || !Number.isFinite(current) || !Number.isFinite(previous)) {
+    return "stable";
+  }
+  const absolute = Math.abs(current - previous);
+  const relative = previous > 0 ? absolute / previous : 0;
+  if (absolute < 0.5 || relative < 0.2) return "stable";
+  return current < previous ? "improving" : "worsening";
+}
+
+function localDateKey(now: number): string {
+  const date = new Date(now);
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+function shiftDate(localDate: string, days: number): string {
+  const [year, month, day] = localDate.split("-").map(Number);
+  return new Date(Date.UTC(year!, month! - 1, day! + days)).toISOString().slice(0, 10);
+}
+
+function within(localDate: string, start: string, end: string): boolean {
+  return DATE_KEY.test(localDate) && localDate >= start && localDate <= end;
+}
+
+interface WindowTotals {
+  words: number;
+  accepted: number;
+  dismissed: number;
+}
+
+interface RuleGroup {
+  patternId: string;
+  explanation: string;
+  patternIds: Set<string>;
+}
+
+export function computeFluencyAnalytics(input: AnalyticsInput): FluencyAnalytics {
+  const observations = [...input.observations];
+  const occurrences = [...input.occurrences];
+  const patterns = [...input.patterns];
+  const today = localDateKey(input.now);
+  const patternsById = new Map(patterns.map((pattern) => [pattern.id, pattern]));
+
+  const isIgnored = (occurrence: MistakeOccurrence): boolean => {
+    const pattern = patternsById.get(occurrence.patternId);
+    if (input.ignoredPatternKeys.has(pattern?.patternKey ?? occurrence.patternKey)) return true;
+    return pattern !== undefined && input.ignoredCategories.has(errantCategory(pattern.errorType));
+  };
+
+  const totals = (end: string, days: number): WindowTotals => {
+    const start = shiftDate(end, -(days - 1));
+    return {
+      words: observations
+        .filter((observation) => within(observation.localDate, start, end))
+        .reduce((sum, observation) => sum + Math.max(0, observation.wordCount), 0),
+      accepted: occurrences.filter((occurrence) =>
+        occurrence.decision === "accepted" && within(occurrence.localDate, start, end)).length,
+      dismissed: occurrences.filter((occurrence) =>
+        occurrence.decision === "dismissed" && within(occurrence.localDate, start, end)).length,
+    };
+  };
+
+  const trailingRates = Array.from({ length: 7 }, (_, index) => {
+    const end = shiftDate(today, index - 6);
+    const window = totals(end, 7);
+    return ratePerThousand(window.accepted, window.words);
+  });
+  const currentSeven = totals(today, 7);
+  const currentThirty = totals(today, TREND_DAYS);
+  const previousEnd = shiftDate(today, -TREND_DAYS);
+  const previousThirty = totals(previousEnd, TREND_DAYS);
+  const currentStart = shiftDate(today, -(TREND_DAYS - 1));
+
+  const visiblePending = occurrences.filter((occurrence) =>
+    occurrence.decision === "pending" && !isIgnored(occurrence));
+  const visiblePendingInPeriod = visiblePending.filter((occurrence) =>
+    within(occurrence.localDate, currentStart, today)).length;
+  const reviewed = currentThirty.accepted + currentThirty.dismissed;
+  const reviewable = reviewed + visiblePendingInPeriod;
+
+  const groupsByExplanation = new Map<string, RuleGroup>();
+  for (const pattern of patterns) {
+    const explanation = pattern.explanation;
+    const existing = groupsByExplanation.get(explanation);
+    if (existing) {
+      existing.patternIds.add(pattern.id);
+      if (pattern.id.localeCompare(existing.patternId) < 0) existing.patternId = pattern.id;
+    } else {
+      groupsByExplanation.set(explanation, {
+        patternId: pattern.id,
+        explanation,
+        patternIds: new Set([pattern.id]),
+      });
+    }
+  }
+
+  const acceptedForGroup = (group: RuleGroup, end: string, days: number): number => {
+    const start = shiftDate(end, -(days - 1));
+    return occurrences.filter((occurrence) =>
+      occurrence.decision === "accepted"
+      && group.patternIds.has(occurrence.patternId)
+      && within(occurrence.localDate, start, end)).length;
+  };
+
+  const lifetimeAcceptedForGroup = (group: RuleGroup): number => occurrences.filter((occurrence) =>
+    occurrence.decision === "accepted" && group.patternIds.has(occurrence.patternId)).length;
+  const recurringGroups = [...groupsByExplanation.values()].filter((group) =>
+    lifetimeAcceptedForGroup(group) >= 2);
+  const oneOffAccepted = [...groupsByExplanation.values()]
+    .filter((group) => lifetimeAcceptedForGroup(group) === 1)
+    .reduce((sum, group) => sum + acceptedForGroup(group, today, TREND_DAYS), 0);
+
+  const rules = recurringGroups.flatMap((group): RuleAnalytics[] => {
+    const accepted = acceptedForGroup(group, today, TREND_DAYS);
+    const previousAccepted = acceptedForGroup(group, previousEnd, TREND_DAYS);
+    if (accepted === 0 && previousAccepted === 0) return [];
+    const currentRate = ratePerThousand(accepted, currentThirty.words);
+    const previousRate = ratePerThousand(previousAccepted, previousThirty.words);
+    const trend = previousAccepted === 0 && accepted > 0
+      ? "new"
+      : classifyRuleTrend(currentRate, previousRate);
+    const sparklineValues = Array.from({ length: 7 }, (_, index) => {
+      const end = shiftDate(today, index - 6);
+      const window = totals(end, 7);
+      return ratePerThousand(acceptedForGroup(group, end, 7), window.words);
+    });
+    const changePercent = trend !== "new" && trend !== "stable"
+      && previousRate !== undefined && previousRate > 0 && currentRate !== undefined
+      ? (currentRate - previousRate) / previousRate * 100
+      : undefined;
+    return [{
+      patternId: group.patternId,
+      explanation: group.explanation,
+      accepted,
+      ratePerThousand: currentRate,
+      sparkline: renderSparkline(sparklineValues),
+      trend,
+      ...(changePercent === undefined ? {} : { changePercent }),
+    }];
+  }).sort((left, right) =>
+    right.accepted - left.accepted
+    || (right.ratePerThousand ?? -Infinity) - (left.ratePerThousand ?? -Infinity)
+    || left.explanation.localeCompare(right.explanation));
+
+  const trendCounts: Record<RuleTrend, number> = { improving: 0, worsening: 0, stable: 0, new: 0 };
+  for (const rule of rules) trendCounts[rule.trend] += 1;
+
+  const activeRules = recurringGroups.filter((group) =>
+    acceptedForGroup(group, today, 7) > 0).length;
+
+  const currentRatePerThousand = ratePerThousand(currentSeven.accepted, currentSeven.words);
+  const periodRatePerThousand = ratePerThousand(currentThirty.accepted, currentThirty.words);
+  const reviewCoverage = reviewable > 0 ? reviewed / reviewable : undefined;
+  return {
+    pendingOccurrences: visiblePending.length,
+    periodPendingOccurrences: visiblePendingInPeriod,
+    activeRules,
+    ...(currentRatePerThousand === undefined ? {} : { currentRatePerThousand }),
+    ...(periodRatePerThousand === undefined ? {} : { periodRatePerThousand }),
+    toolbarSparkline: renderSparkline(trailingRates),
+    englishWords: currentThirty.words,
+    accepted: currentThirty.accepted,
+    dismissed: currentThirty.dismissed,
+    oneOffAccepted,
+    ...(reviewCoverage === undefined ? {} : { reviewCoverage }),
+    rules,
+    trendCounts,
+  };
+}

package/extensions/pi-fluency/analyzer.ts

@@ -0,0 +1,171 @@
+import type { Api, Model, UserMessage } from "@earendil-works/pi-ai";
+import { complete } from "@earendil-works/pi-ai/compat";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import {
+  ANALYSIS_SCHEMA_VERSION,
+  type AnalysisResult,
+  type CollectedPrompt,
+  type MistakePattern,
+  type RawAnalysisResult,
+} from "./types.js";
+import {
+  ERRANT_ERROR_TYPES,
+  isErrantErrorType,
+} from "./taxonomy.js";
+import { materializeMistake } from "./context.js";
+import { sanitizeAnalyzerField } from "./sanitize.js";
+
+const CONTEXT_SCOPES = ["sentence", "previous-and-current", "current-and-next"] as const;
+const MAX_KNOWN_PATTERNS = 500;
+const MAX_MISTAKES = 20;
+const MAX_DEMONSTRATED_FIXES = 25;
+
+export class AnalyzerConfigurationError extends Error {
+  override readonly name = "AnalyzerConfigurationError";
+}
+
+export interface Analyzer {
+  analyze(
+    prompt: CollectedPrompt,
+    activePatterns: MistakePattern[],
+    signal: AbortSignal,
+  ): Promise<AnalysisResult>;
+}
+
+export function buildAnalysisPrompt(prompt: CollectedPrompt, activePatterns: MistakePattern[]): string {
+  const knownPatterns = activePatterns
+    .slice(0, MAX_KNOWN_PATTERNS)
+    .map(({ patternKey, explanation, errorType }) => ({ patternKey, explanation, errorType }));
+  return JSON.stringify({
+    prose: prompt.prose,
+    knownPatterns,
+    allowedErrorTypes: ERRANT_ERROR_TYPES,
+    allowedContextScopes: CONTEXT_SCOPES,
+  });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function validateAnalysisResult(value: unknown, minimumConfidence: number): RawAnalysisResult {
+  if (
+    !isRecord(value)
+    || value.schemaVersion !== ANALYSIS_SCHEMA_VERSION
+    || (value.language !== "en" && value.language !== "other")
+    || !Array.isArray(value.mistakes)
+    || !Array.isArray(value.demonstratedFixes)
+  ) throw new Error("Invalid analysis result");
+
+  if (value.language === "other" && (value.mistakes.length > 0 || value.demonstratedFixes.length > 0)) {
+    throw new Error("Invalid analysis result");
+  }
+
+  const scopes = new Set<string>(CONTEXT_SCOPES);
+  const validConfidence = (confidence: unknown): confidence is number =>
+    typeof confidence === "number" && Number.isFinite(confidence) && confidence >= 0 && confidence <= 1;
+
+  const mistakes: RawAnalysisResult["mistakes"] = [];
+  for (const candidate of value.mistakes.slice(0, MAX_MISTAKES)) {
+    if (!isRecord(candidate)) throw new Error("Invalid analysis result");
+    const original = sanitizeAnalyzerField(candidate.original);
+    const correction = sanitizeAnalyzerField(candidate.correction, true);
+    const explanation = sanitizeAnalyzerField(candidate.explanation);
+    const patternKey = sanitizeAnalyzerField(candidate.patternKey);
+    const contextScope = candidate.contextScope;
+    if (
+      original === undefined || correction === undefined || explanation === undefined || patternKey === undefined
+      || !/^[a-z]+(?:[.-][a-z0-9]+)+$/.test(patternKey)
+      || typeof contextScope !== "string" || !scopes.has(contextScope)
+      || !validConfidence(candidate.confidence)
+    ) throw new Error("Invalid analysis result");
+    if (candidate.confidence < minimumConfidence) continue;
+    const errorType = isErrantErrorType(candidate.errorType) ? candidate.errorType : "R:OTHER";
+    mistakes.push({ original, correction, explanation, patternKey, contextScope: contextScope as RawAnalysisResult["mistakes"][number]["contextScope"], errorType, confidence: candidate.confidence });
+  }
+
+  const demonstratedFixes: RawAnalysisResult["demonstratedFixes"] = [];
+  for (const candidate of value.demonstratedFixes.slice(0, MAX_DEMONSTRATED_FIXES)) {
+    if (!isRecord(candidate)) throw new Error("Invalid analysis result");
+    const patternKey = sanitizeAnalyzerField(candidate.patternKey);
+    const evidence = sanitizeAnalyzerField(candidate.evidence);
+    if (patternKey === undefined || evidence === undefined || !validConfidence(candidate.confidence)) {
+      throw new Error("Invalid analysis result");
+    }
+    if (candidate.confidence >= minimumConfidence) demonstratedFixes.push({ patternKey, evidence, confidence: candidate.confidence });
+  }
+  return { schemaVersion: ANALYSIS_SCHEMA_VERSION, language: value.language, mistakes, demonstratedFixes };
+}
+
+const SYSTEM_PROMPT = `You are Pi Fluency's English learning analyzer.
+Return only one JSON object with exactly this shape:
+{"schemaVersion":3,"language":"en","mistakes":[{"original":"exact erroneous quote","correction":"corrected quote","contextScope":"sentence","explanation":"brief rule","errorType":"R:DET","patternKey":"grammar.articles.example-rule","confidence":0.95}],"demonstratedFixes":[{"patternKey":"grammar.articles.example-rule","evidence":"exact correct quote","confidence":0.95}]}
+Classify the supplied prose as English or other. For language "other", return empty mistakes and demonstratedFixes. Do not correct or translate non-English prose.
+Use empty arrays when no mistakes or fixes exist. Do not rename fields or add fields.
+For each mistake, original must be the shortest unique exact quote containing the error; choose contextScope and errorType only from supplied controlled values.
+Report genuine grammar, spelling, word-choice, or idiomatic-usage errors only.
+Do not report style preferences, capitalization of product names, or informal-but-valid wording.
+A demonstrated fix must match one supplied knownPatterns pattern and quote comparable correct evidence.
+Never infer a demonstrated fix merely because an earlier mistake is absent.
+Reuse an existing knownPatterns patternKey for the same rule; mint a new namespaced lowercase key only when no known rule matches.
+Keep every explanation under 240 characters. Return JSON only.`;
+
+export class ModelAnalyzer implements Analyzer {
+  constructor(private readonly options: {
+    model: Model<Api>;
+    registry: ModelRegistry;
+    minimumConfidence: number;
+  }) {}
+
+  async analyze(
+    prompt: CollectedPrompt,
+    activePatterns: MistakePattern[],
+    signal: AbortSignal,
+  ): Promise<AnalysisResult> {
+    let auth: Awaited<ReturnType<ModelRegistry["getApiKeyAndHeaders"]>>;
+    try {
+      auth = await this.options.registry.getApiKeyAndHeaders(this.options.model);
+    } catch {
+      throw new AnalyzerConfigurationError("Unable to resolve model authentication");
+    }
+    if (!auth.ok || !auth.apiKey) {
+      throw new AnalyzerConfigurationError("Model authentication unavailable");
+    }
+
+    const message: UserMessage = {
+      role: "user",
+      content: buildAnalysisPrompt(prompt, activePatterns),
+      timestamp: Date.now(),
+    };
+    const response = await complete(
+      this.options.model,
+      { systemPrompt: SYSTEM_PROMPT, messages: [message] },
+      {
+        apiKey: auth.apiKey,
+        ...(auth.headers === undefined ? {} : { headers: auth.headers }),
+        ...(auth.env === undefined ? {} : { env: auth.env }),
+        signal,
+      },
+    );
+    const text = response.content
+      .filter((block): block is { type: "text"; text: string } => block.type === "text")
+      .map((block) => block.text)
+      .join("\n")
+      .trim();
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text) as unknown;
+    } catch {
+      throw new Error("Invalid analysis result");
+    }
+    const validated = validateAnalysisResult(parsed, this.options.minimumConfidence);
+    const knownPatternKeys = new Set(activePatterns.map((pattern) => pattern.patternKey));
+    return {
+      schemaVersion: ANALYSIS_SCHEMA_VERSION,
+      language: validated.language,
+      mistakes: validated.mistakes.map((mistake) => materializeMistake(prompt.prose, mistake)),
+      demonstratedFixes: validated.demonstratedFixes.filter((fix) =>
+        knownPatternKeys.has(fix.patternKey) && prompt.prose.includes(fix.evidence)),
+    };
+  }
+}