@principles/pd-cli 1.96.0 → 1.98.0

package/src/commands/quality-scorecard.ts

@@ -0,0 +1,272 @@
+/**
+ * pd quality scorecard — CLI command (PRI-361)
+ *
+ * JSON contract: --json mode outputs EXACTLY one JSON object to stdout.
+ * All progress/diagnostic output goes to stderr.
+ * Errors produce structured JSON: { ok: false, error, nextAction }.
+ */
+
+import { mkdirSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
+import type {
+  EpisodeEvaluation,
+  QualityScorecardReport,
+  StrongModelAdjudication,
+} from '@principles/core/quality-scorecard';
+import {
+  validateCliOptions,
+  needsAdjudication,
+  generateMarkdownReport,
+  generateHtmlReport,
+  generateJsonReport,
+} from '@principles/core/quality-scorecard';
+import { extractEpisodes, extractLogStats } from '../services/quality-scorecard/data-extractor.js';
+import { evaluateWithLocalModel, checkLmStudioAvailable } from '../services/quality-scorecard/local-evaluator.js';
+import { adjudicate, skippedAdjudication, determineFinalLabel } from '../services/quality-scorecard/strong-model-gate.js';
+
+// ── Logging: stderr only, silent in JSON mode ──────────────────────
+
+let jsonMode = false;
+
+function log(msg: string): void {
+  if (!jsonMode) {
+    process.stderr.write(msg + '\n');
+  }
+}
+
+// ── Structured JSON output helpers ─────────────────────────────────
+
+function writeJsonOutput(data: unknown): void {
+  process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+}
+
+function writeJsonError(error: string, nextAction: string): void {
+  writeJsonOutput({ ok: false, error, nextAction });
+}
+
+// ── Summary computation ────────────────────────────────────────────
+
+function computeSummary(evaluations: EpisodeEvaluation[]) {
+  const totalEpisodes = evaluations.length;
+  // localPassCount/localFailCount: based strictly on local model's own conclusion
+  // (localEval.mvpMet + totalScore), NOT finalLabel which may incorporate strong-model adjudication.
+  const localPassCount = evaluations.filter(e => e.localEvaluation.mvpMet && e.localEvaluation.totalScore >= 12).length;
+  const localFailCount = evaluations.filter(e => e.localEvaluation.totalScore <= 6).length;
+  const strongModelReviewedCount = evaluations.filter(e =>
+    e.strongModelAdjudication && e.strongModelAdjudication.adjudicationStatus !== 'skipped'
+  ).length;
+  const finalPassCount = evaluations.filter(e => e.finalLabel === 'pass').length;
+  const finalFailCount = evaluations.filter(e => e.finalLabel === 'fail').length;
+  const needsReviewCount = evaluations.filter(e => e.finalLabel === 'needs-review').length;
+  const localOnlyCount = evaluations.filter(e => e.finalLabel === 'local-pass' || e.finalLabel === 'local-fail').length;
+  const averageLocalScore = totalEpisodes > 0
+    ? evaluations.reduce((s, e) => s + e.localEvaluation.totalScore, 0) / totalEpisodes
+    : 0;
+  const mvpThresholdMetCount = evaluations.filter(e => e.localEvaluation.mvpMet).length;
+
+  return {
+    totalEpisodes, localPassCount, localFailCount, strongModelReviewedCount,
+    finalPassCount, finalFailCount, needsReviewCount, localOnlyCount,
+    averageLocalScore, mvpThresholdMetCount,
+  };
+}
+
+// ── Main handler ───────────────────────────────────────────────────
+
+export async function handleQualityScorecard(opts: Record<string, unknown>): Promise<void> {
+  const isJson = Boolean(opts.json);
+  jsonMode = isJson;
+
+  // Resolve workspace paths
+  const { resolveWorkspaceDir } = await import('../resolve-workspace.js');
+  const { join } = await import('path');
+  const { existsSync } = await import('fs');
+  const workspace = resolveWorkspaceDir(opts.workspace as string | undefined);
+  const dbPath = join(workspace, '.state', 'trajectory.db');
+  const logsDir = join(workspace, '.state', 'logs');
+
+  // 1. Validate CLI options
+  const { options, errors } = validateCliOptions({
+    dbPath,
+    logsDir,
+    localModelBaseUrl: opts.localUrl ?? 'http://localhost:12341/v1',
+    localModelId: opts.localModel ?? 'qwen3.6-27b-mtp',
+    strongModelId: opts.strongModel ?? null,
+    limit: opts.limit ?? '0',
+    format: isJson ? 'json' : (opts.format ?? 'markdown'),
+    output: opts.output,
+    minPainScore: opts.minScore ?? '50',
+    skipStrongModel: opts.skipStrongModel ?? false,
+  });
+
+  if (errors.length > 0) {
+    const msg = errors.map(e => `${e.field}: ${e.message}`).join('; ');
+    if (isJson) {
+      writeJsonError(msg, 'Fix the invalid options and retry');
+    } else {
+      process.stderr.write(`❌ Invalid options:\n${errors.map(e => `  - ${e.field}: ${e.message}`).join('\n')}\n`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  // 2. Check files exist
+  if (!existsSync(options.dbPath)) {
+    const msg = `trajectory.db not found at: ${options.dbPath}`;
+    if (isJson) {
+      writeJsonError(msg, 'Ensure the workspace has PD data (run PD first to generate trajectory.db)');
+    } else {
+      process.stderr.write(`❌ ${msg}\n`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  // 3. Ensure output directory exists
+  const outputDir = dirname(options.output);
+  if (outputDir && !existsSync(outputDir)) {
+    try {
+      mkdirSync(outputDir, { recursive: true });
+      log(`Created output directory: ${outputDir}`);
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (isJson) {
+        writeJsonError(`Cannot create output directory: ${msg}`, 'Ensure the output path is writable');
+      } else {
+        process.stderr.write(`❌ Cannot create output directory: ${msg}\n`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  // 4. Check LM Studio
+  log('🔍 PD Quality Scorecard — Starting...');
+  log(`   DB: ${options.dbPath}`);
+  log(`   Local Model: ${options.localModelId} @ ${options.localModelBaseUrl}`);
+  log(`   Strong Model: ${options.strongModelId ?? 'skipped'}`);
+
+  const lmStatus = await checkLmStudioAvailable(options.localModelBaseUrl);
+  if (!lmStatus.available) {
+    if (isJson) {
+      writeJsonError(`LM Studio not available: ${lmStatus.error}`, 'Start LM Studio or check --local-url');
+    } else {
+      process.stderr.write(`❌ LM Studio not available at ${options.localModelBaseUrl}: ${lmStatus.error}\n`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!lmStatus.models.includes(options.localModelId)) {
+    if (isJson) {
+      writeJsonError(`Model "${options.localModelId}" not found. Available: ${lmStatus.models.join(', ')}`, 'Use --local-model with an available model');
+    } else {
+      process.stderr.write(`❌ Model "${options.localModelId}" not found. Available: ${lmStatus.models.join(', ')}\n`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  // 5. Extract data
+  log('\n📊 Extracting dogfood data...');
+  const { episodes, stats: extractStats } = await extractEpisodes(options.dbPath, {
+    minScore: options.minPainScore,
+    limit: options.limit,
+  });
+  log(`   Found ${episodes.length} unique episodes (total pain events: ${extractStats.total})`);
+
+  const logStats = extractLogStats(options.logsDir);
+  log(`   Event logs: ${logStats.totalEvents} events (${logStats.painSignalCount} pain signals)`);
+
+  // 6. Evaluate each episode
+  log('\n🤖 Running local model evaluation...');
+  const evaluations: EpisodeEvaluation[] = [];
+
+  for (let i = 0; i < episodes.length; i++) {
+    const ep = episodes[i];
+    if (!ep) continue;
+    log(`   [${i + 1}/${episodes.length}] ${ep.episodeId} (score=${ep.score})...`);
+
+    const localEval = await evaluateWithLocalModel(ep, {
+      baseUrl: options.localModelBaseUrl,
+      model: options.localModelId,
+    }, (msg: string) => log(`     ${msg}`));
+    log(`     Local: ${localEval.totalScore}/14 MVP=${localEval.mvpMet} flags=[${localEval.flags.join(',')}]`);
+
+    // 7. Strong model adjudication
+    let adjudication: StrongModelAdjudication;
+    if (options.skipStrongModel || !options.strongModelId) {
+      adjudication = skippedAdjudication(
+        options.skipStrongModel
+          ? 'Strong model skipped by --skip-strong-model flag'
+          : 'No strong model configured'
+      );
+    } else {
+      const decision = needsAdjudication(ep, localEval);
+      if (decision.shouldAdjudicate) {
+        log(`     Adjudicating (${decision.priority}: ${decision.reason})...`);
+        adjudication = await adjudicate(ep, localEval, { modelId: options.strongModelId, log: (msg: string) => log(`     ${msg}`) });
+        log(`     Adjudication: ${adjudication.adjudicationStatus}`);
+      } else {
+        adjudication = skippedAdjudication(decision.reason);
+        log(`     Adjudication skipped: ${decision.reason}`);
+      }
+    }
+
+    const finalLabel = determineFinalLabel(localEval, adjudication);
+    evaluations.push({ episode: ep, localEvaluation: localEval, strongModelAdjudication: adjudication, finalLabel });
+  }
+
+  // 8. Build and write report
+  log('\n📝 Generating report...');
+  const summary = computeSummary(evaluations);
+  const report: QualityScorecardReport = {
+    generatedAt: new Date().toISOString(),
+    dataSource: {
+      painEventCount: extractStats.total,
+      evolutionTaskCount: 0,
+      principleEventCount: 0,
+      gateBlockCount: 0,
+      dateRange: extractStats.dateRange,
+    },
+    localEvaluatorConfig: {
+      model: options.localModelId,
+      baseUrl: options.localModelBaseUrl.replace(/\/v\d+$/, '/...'),
+      apiKeyStatus: 'not-required',
+    },
+    strongModelConfig: {
+      model: options.strongModelId,
+      status: options.skipStrongModel || !options.strongModelId ? 'skipped' : 'configured',
+    },
+    evaluations,
+    summary,
+    knownLimitations: [
+      'Local model scores are advisory only — not final quality conclusions.',
+      'Without strong-model adjudication, samples are marked local-pass/local-fail/needs-review.',
+      'Deduplication is based on reason text similarity — may miss distinct episodes.',
+      'Local model output is non-deterministic despite temperature=0.1.',
+    ],
+  };
+
+  let content: string;
+  switch (options.format) {
+    case 'html': content = generateHtmlReport(report); break;
+    case 'json': content = generateJsonReport(report); break;
+    case 'markdown':
+    default: content = generateMarkdownReport(report); break;
+  }
+
+  writeFileSync(options.output, content, 'utf-8');
+
+  log(`\n✅ Report written to: ${options.output}`);
+  log(`   Format: ${options.format}`);
+  log(`   Episodes: ${summary.totalEpisodes}`);
+  log(`   Local Pass: ${summary.localPassCount} | Local Fail: ${summary.localFailCount}`);
+  log(`   Strong Model Reviewed: ${summary.strongModelReviewedCount}`);
+  log(`   Final Pass: ${summary.finalPassCount} | Final Fail: ${summary.finalFailCount} | Needs Review: ${summary.needsReviewCount}`);
+
+  // JSON mode: output exactly one JSON object to stdout
+  if (isJson) {
+    writeJsonOutput({ ok: true, report });
+  }
+}

package/src/commands/runtime-internalization-queue.ts

@@ -12,13 +12,14 @@ import { createInternalizationQueueReadModel } from '@principles/core/runtime-v2
 import type { InternalizationQueueSnapshot } from '@principles/core/runtime-v2';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
 import { loadEffectiveFeatureFlags } from '../services/feature-flag-loader.js';
+import { loadPdConfig, computeFlagsFromLoadResult } from '../services/pd-config-loader.js';
 
 interface QueueOptions {
   workspace?: string;
   json?: boolean;
 }
 
-function formatTextOutput(snap: InternalizationQueueSnapshot): string {
+function formatTextOutput(snap: InternalizationQueueSnapshot, workspaceDir: string, autoConsumerEnabled: boolean): string {
   const lines: string[] = [];
   lines.push(`Internalization Queue Snapshot`);
   lines.push(`  pending: ${snap.pendingCount}  retry_wait: ${snap.retryWaitCount}`);
@@ -78,6 +79,16 @@ function formatTextOutput(snap: InternalizationQueueSnapshot): string {
     }
   }
 
+  if (snap.readyTasks.length > 0) {
+    if (autoConsumerEnabled) {
+      lines.push(`  consumerStatus: auto_consumer_enabled`);
+    } else {
+      const nextAction = `pd runtime internalization run-once --workspace "${workspaceDir}" --runner dreamer --runtime config --json`;
+      lines.push(`  consumerStatus: manual_action_required`);
+      lines.push(`  nextAction: ${nextAction}`);
+    }
+  }
+
   return lines.join('\n');
 }
 
@@ -95,10 +106,33 @@ export async function handleRuntimeInternalizationQueue(opts: QueueOptions): Pro
   try {
     const snapshot = await readModel.getSnapshot();
 
+    const pdConfigResult = loadPdConfig(workspaceDir);
+    if (!pdConfigResult.ok) {
+      const configWarning = JSON.stringify({
+        level: 'warning',
+        source: 'pd_config',
+        errors: pdConfigResult.errors.map(e => ({ reason: e.reason, nextAction: e.nextAction })),
+      });
+      process.stderr.write(`${configWarning}\n`);
+    }
+    const pdFlags = computeFlagsFromLoadResult(pdConfigResult);
+    const autoConsumerEnabled = pdFlags.flags.internalization_auto_consumer?.enabled ?? false;
+
     if (opts.json) {
-      console.log(JSON.stringify(snapshot, null, 2));
+      const output: Record<string, unknown> = { ...snapshot };
+
+      if (snapshot.readyTasks.length > 0) {
+        if (autoConsumerEnabled) {
+          output.consumerStatus = 'auto_consumer_enabled';
+        } else {
+          output.nextAction = `pd runtime internalization run-once --workspace "${workspaceDir}" --runner dreamer --runtime config --json`;
+          output.consumerStatus = 'manual_action_required';
+        }
+      }
+
+      console.log(JSON.stringify(output, null, 2));
     } else {
-      console.log(formatTextOutput(snapshot));
+      console.log(formatTextOutput(snapshot, workspaceDir, autoConsumerEnabled));
     }
   } finally {
     await close();

package/src/index.ts

@@ -927,4 +927,28 @@ consoleCmd.action(async (opts) => {
   });
 });
 
+// ─── Quality Scorecard (PRI-361) ──────────────────────────────────
+
+const qualityCmd = program
+  .command('quality')
+  .description('Quality scoring and evaluation');
+
+qualityCmd
+  .command('scorecard')
+  .description('Generate quality scorecard report for PD pain→diagnosis→principle chain')
+  .option('-w, --workspace <path>', 'Workspace directory')
+  .option('--local-model <id>', 'LM Studio model ID', 'qwen3.6-27b-mtp')
+  .option('--local-url <url>', 'LM Studio base URL', 'http://localhost:12341/v1')
+  .option('--strong-model <id>', 'Strong model for adjudication (provider/model)')
+  .option('--skip-strong-model', 'Skip strong model adjudication', false)
+  .option('--min-score <n>', 'Minimum pain score to evaluate', '50')
+  .option('--limit <n>', 'Max episodes to evaluate (0=all)', '0')
+  .option('--format <fmt>', 'Output format: json, markdown, html', 'markdown')
+  .option('--output <path>', 'Output file path')
+  .option('--json', 'Output as JSON', false)
+  .action(async (opts) => {
+    const { handleQualityScorecard } = await import('./commands/quality-scorecard.js');
+    await handleQualityScorecard(opts);
+  });
+
 program.parse();

package/src/services/quality-scorecard/data-extractor.ts

@@ -0,0 +1,150 @@
+/**
+ * PRI-361 — Data Extractor (I/O layer in pd-cli)
+ *
+ * Reads trajectory.db and event logs. Uses runtime validation
+ * from @principles/core — no `as RawPainEvent[]` casts.
+ */
+
+import type { PainEpisode } from '@principles/core/quality-scorecard';
+import {
+  validatePainRow,
+  validateEvolutionRow,
+  validatePrincipleEventRow,
+  validateGateRow,
+  sanitize,
+  truncate,
+} from '@principles/core/quality-scorecard';
+import { readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+export interface ExtractionResult {
+  episodes: PainEpisode[];
+  stats: { total: number; dateRange: { from: string; to: string } };
+}
+
+export async function extractEpisodes(
+  dbPath: string,
+  options: { minScore?: number; limit?: number } = {}
+): Promise<ExtractionResult> {
+  const Database = (await import('better-sqlite3')).default;
+  const db = new Database(dbPath, { readonly: true });
+
+  const minScore = options.minScore ?? 0;
+  const limit = options.limit ?? 0;
+
+  try {
+    // Fetch pain events with parameterized query
+    let painQuery = 'SELECT id, session_id, source, score, reason, severity, created_at FROM pain_events WHERE 1=1';
+    const params: (string | number)[] = [];
+    if (minScore > 0) {
+      painQuery += ' AND score >= ?';
+      params.push(minScore);
+    }
+    painQuery += ' ORDER BY created_at DESC';
+    if (limit > 0) {
+      painQuery += ' LIMIT ?';
+      params.push(limit);
+    }
+
+    const rawPainRows = db.prepare(painQuery).all(...params);
+    // Validate each row — no unsafe cast
+    const painEvents = rawPainRows.map(validatePainRow).filter((r): r is NonNullable<typeof r> => r !== null);
+
+    // Fetch evolution tasks
+    const rawEvoRows = db.prepare('SELECT task_id, score, status, resolution, created_at FROM evolution_tasks').all();
+    const evoTasks = rawEvoRows.map(validateEvolutionRow).filter((r): r is NonNullable<typeof r> => r !== null);
+
+    // Fetch principle events
+    const rawPeRows = db.prepare('SELECT principle_id, event_type, created_at FROM principle_events').all();
+    const prEvents = rawPeRows.map(validatePrincipleEventRow).filter((r): r is NonNullable<typeof r> => r !== null);
+
+    // Gate blocks count per session — validate each row
+    const rawGateRows = db.prepare('SELECT session_id, COUNT(*) as cnt FROM gate_blocks GROUP BY session_id').all();
+    const gateRows = rawGateRows.map(validateGateRow).filter((r): r is NonNullable<typeof r> => r !== null);
+    const gateBlockMap = new Map(gateRows.map(g => [g.session_id, g.cnt]));
+
+    // Deduplicate by sanitized reason
+    const seen = new Set<string>();
+    const episodes: PainEpisode[] = [];
+
+    for (const pe of painEvents) {
+      const dedupKey = sanitize(pe.reason).substring(0, 80);
+      if (seen.has(dedupKey)) continue;
+      seen.add(dedupKey);
+
+      const peTime = new Date(pe.created_at).getTime();
+      const linkedTask = evoTasks.find(t => {
+        const tTime = new Date(t.created_at).getTime();
+        return Math.abs(tTime - peTime) < 3600000 && Math.abs(t.score - pe.score) <= 10;
+      });
+
+      const linkedPrinciples = prEvents
+        .filter(e => {
+          if (!e.principle_id) return false;
+          const eTime = new Date(e.created_at).getTime();
+          return Math.abs(eTime - peTime) < 7200000;
+        })
+        .map(e => e.principle_id)
+        .filter((v): v is string => v !== null)
+        .filter((v, i, a) => a.indexOf(v) === i);
+
+      episodes.push({
+        episodeId: `EP-${pe.id}`,
+        summary: truncate(sanitize(pe.reason)),
+        source: pe.source,
+        score: pe.score,
+        severity: pe.severity,
+        createdAt: pe.created_at,
+        evolutionTaskResolution: linkedTask?.resolution ?? null,
+        linkedPrinciples,
+        gateBlockCount: gateBlockMap.get(pe.session_id) ?? 0,
+      });
+    }
+
+    const dates = painEvents.map(e => e.created_at).sort();
+    return {
+      episodes,
+      stats: {
+        total: painEvents.length,
+        dateRange: {
+          from: dates[0] ?? new Date().toISOString(),
+          to: dates[dates.length - 1] ?? new Date().toISOString(),
+        },
+      },
+    };
+  } finally {
+    db.close();
+  }
+}
+
+export interface LogStats {
+  totalEvents: number;
+  painSignalCount: number;
+  degradedReasons: string[];
+}
+
+export function extractLogStats(logsDir: string): LogStats {
+  const stats: LogStats = { totalEvents: 0, painSignalCount: 0, degradedReasons: [] };
+
+  try {
+    const files = readdirSync(logsDir).filter(f => f.endsWith('.jsonl'));
+    for (const file of files) {
+      const lines = readFileSync(join(logsDir, file), 'utf-8').split('\n').filter(Boolean);
+      for (const line of lines) {
+        try {
+          const ev = JSON.parse(line) as Record<string, unknown>;
+          stats.totalEvents++;
+          if (ev.type === 'pain_signal') stats.painSignalCount++;
+        } catch (parseErr: unknown) {
+          const msg = parseErr instanceof Error ? parseErr.message : String(parseErr);
+          stats.degradedReasons.push(`jsonl-parse-fail:${file}:${msg}`);
+        }
+      }
+    }
+  } catch (dirErr: unknown) {
+    const msg = dirErr instanceof Error ? dirErr.message : String(dirErr);
+    stats.degradedReasons.push(`logs-dir-unreadable:${msg}`);
+  }
+
+  return stats;
+}

package/src/services/quality-scorecard/local-evaluator.ts

@@ -0,0 +1,142 @@
+/**
+ * PRI-361 — Local Evaluator (I/O layer in pd-cli)
+ *
+ * Calls LM Studio for advisory scoring. Uses core validation
+ * to parse LLM responses — no unsafe casts.
+ */
+
+import type {
+  PainEpisode,
+  LocalEvaluation,
+  RubricDimension,
+  RubricScore,
+} from '@principles/core/quality-scorecard';
+import {
+  RUBRIC_LABELS,
+  RUBRIC_PROMPTS,
+  RUBRIC_DIMENSIONS as DIMS,
+  meetsMvpThreshold,
+  sumScores,
+  validateLlmScoreResponse,
+  extractJsonFromLlmResponse,
+} from '@principles/core/quality-scorecard';
+
+function buildEvaluationPrompt(episode: PainEpisode): string {
+  const dimensions = DIMS.map(d => `${d} (${RUBRIC_LABELS[d]}): ${RUBRIC_PROMPTS[d]}`).join('\n');
+
+  return `You are a quality evaluator for an AI agent's pain-signal -> diagnosis -> principle pipeline.
+
+## Task
+Evaluate this pain episode on a 7-dimension rubric. Each dimension scores 0 (fail), 1 (partial), or 2 (pass).
+
+## Pain Episode
+- ID: ${episode.episodeId}
+- Source: ${episode.source}
+- Pain Score: ${episode.score}
+- Severity: ${episode.severity}
+- Summary: ${episode.summary}
+- Created: ${episode.createdAt}
+- Evolution Task Resolution: ${episode.evolutionTaskResolution ?? 'none'}
+- Linked Principles: ${episode.linkedPrinciples.length > 0 ? episode.linkedPrinciples.join(', ') : 'none'}
+- Gate Blocks: ${episode.gateBlockCount}
+
+## Rubric Dimensions
+${dimensions}
+
+## Additional Checks
+- Is the language consistent (not mixing Chinese and English incoherently)?
+- Is the diagnosis/principle overly abstract (no concrete actionable guidance)?
+- Does it fabricate non-existent evidence, axioms, or references?
+
+## Output Format (STRICT JSON)
+Respond with ONLY a JSON object:
+{
+  "scores": { "G1": 0-2, "G2": 0-2, "G3": 0-2, "G4": 0-2, "G5": 0-2, "G6": 0-2, "G7": 0-2 },
+  "rationales": { "G1": "...", "G2": "...", "G3": "...", "G4": "...", "G5": "...", "G6": "...", "G7": "..." },
+  "flags": ["list of issues found"]
+}
+
+Do NOT output anything other than this JSON object.`;
+}
+
+export interface LocalEvaluatorConfig {
+  baseUrl: string;
+  model: string;
+}
+
+export async function evaluateWithLocalModel(
+  episode: PainEpisode,
+  config: LocalEvaluatorConfig,
+  log: (msg: string) => void
+): Promise<LocalEvaluation> {
+  const prompt = buildEvaluationPrompt(episode);
+  const url = `${config.baseUrl.replace(/\/+$/, '')}/chat/completions`;
+
+  try {
+    const resp = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        model: config.model,
+        messages: [
+          { role: 'system', content: 'You are a precise JSON-output quality evaluator. Output only valid JSON.' },
+          { role: 'user', content: prompt },
+        ],
+        temperature: 0.1,
+        max_tokens: 2000,
+      }),
+      signal: AbortSignal.timeout(120_000),
+    });
+
+    if (!resp.ok) {
+      throw new Error(`LM Studio request failed: ${resp.status}`);
+    }
+
+    const data = (await resp.json()) as { choices: { message: { content: string } }[] };
+    const content = data.choices?.[0]?.message?.content ?? '';
+
+    const parsed = extractJsonFromLlmResponse(content);
+    if (parsed === null) {
+      throw new Error(`LM Studio returned non-JSON response`);
+    }
+
+    const { scores, rationales, flags } = validateLlmScoreResponse(parsed);
+    const totalScore = sumScores(scores);
+
+    return {
+      model: config.model,
+      dimensionScores: scores,
+      dimensionRationales: rationales,
+      totalScore,
+      maxScore: 14,
+      mvpMet: meetsMvpThreshold(scores),
+      flags: flags,
+    };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log(`Evaluation error for ${episode.episodeId}: ${msg}`);
+    const zeroScores = Object.fromEntries(DIMS.map(d => [d, 0])) as Record<RubricDimension, RubricScore>;
+    return {
+      model: config.model,
+      dimensionScores: zeroScores,
+      dimensionRationales: Object.fromEntries(DIMS.map(d => [d, `Evaluation failed: ${msg}`])) as Record<RubricDimension, string>,
+      totalScore: 0,
+      maxScore: 14,
+      mvpMet: false,
+      flags: ['evaluation_error'],
+    };
+  }
+}
+
+export async function checkLmStudioAvailable(baseUrl: string): Promise<{ available: boolean; models: string[]; error?: string }> {
+  try {
+    const url = `${baseUrl.replace(/\/+$/, '')}/models`;
+    const resp = await fetch(url, { signal: AbortSignal.timeout(5000) });
+    if (!resp.ok) return { available: false, models: [], error: `HTTP ${resp.status}` };
+    const data = (await resp.json()) as { data: { id: string }[] };
+    const models = (data.data || []).map((m) => m.id);
+    return { available: true, models };
+  } catch (err: unknown) {
+    return { available: false, models: [], error: err instanceof Error ? err.message : String(err) };
+  }
+}