pi-simocracy 0.1.0 → 0.2.0

package/src/training/profile.ts

@@ -0,0 +1,229 @@
+/**
+ * `/sim train profile` — distill baseline + transcript into a
+ * `TrainingProfile`. Mirrors `/api/training/extract-profile` from
+ * simocracy-v2.
+ */
+
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+
+import type { LoadedSim } from "../persona.ts";
+import { openRouterComplete, TRAINING_CHAT_MODEL } from "../openrouter.ts";
+import {
+  loadTrainingLabState,
+  saveTrainingLabState,
+} from "./storage.ts";
+import {
+  clampConstitution,
+  clampTranscript,
+  renderBaselineForPrompt,
+  wrapAsData,
+} from "./prompt-helpers.ts";
+import { TRAINING_EXTRACT_PROFILE_SYSTEM_PROMPT } from "./prompts.ts";
+import type { IssuePriority, TrainingProfile } from "./types.ts";
+
+export async function runProfile(
+  ctx: ExtensionCommandContext,
+  loadedSim: LoadedSim,
+): Promise<TrainingProfile | null> {
+  let state = loadTrainingLabState(loadedSim.rkey);
+  const proposals = state.questionSet?.proposals ?? [];
+  if (state.baselineVotes.length === 0 && state.interviewTurns.length === 0) {
+    ctx.ui.notify(
+      "Need at least some baseline votes or interview turns before distilling. Run `/sim train baseline` first.",
+      "warning",
+    );
+    return null;
+  }
+
+  ctx.ui.notify("Distilling profile…", "info");
+  let profile: TrainingProfile | null;
+  try {
+    profile = await deriveProfile(loadedSim, state, proposals);
+  } catch (err) {
+    ctx.ui.notify(`OpenRouter error: ${(err as Error).message}`, "error");
+    return null;
+  }
+
+  if (!profile) {
+    ctx.ui.notify("Could not parse profile from model response.", "error");
+    return null;
+  }
+
+  state = { ...state, profile, alignment: null };
+  saveTrainingLabState(loadedSim.rkey, state);
+  printProfile(profile);
+  ctx.ui.notify(
+    "Profile saved. Run `/sim train alignment` next, or `/sim train apply` to merge it into the constitution.",
+    "info",
+  );
+  return profile;
+}
+
+export async function deriveProfile(
+  loadedSim: LoadedSim,
+  state: ReturnType<typeof loadTrainingLabState>,
+  proposals: { id: string; title: string; summary: string; topic: string }[],
+): Promise<TrainingProfile | null> {
+  const constitution = clampConstitution(loadedSim.description);
+  const baseline = renderBaselineForPrompt(state.baselineVotes, proposals);
+  const transcript = clampTranscript(state.interviewTurns);
+
+  const userPrompt = [
+    `simName: ${loadedSim.name}`,
+    wrapAsData("existingConstitution", constitution),
+    wrapAsData("baselineQuestionnaire", baseline),
+    wrapAsData("transcript", JSON.stringify(transcript, null, 2)),
+  ].join("\n\n");
+
+  const content = await openRouterComplete(
+    [
+      { role: "system", content: TRAINING_EXTRACT_PROFILE_SYSTEM_PROMPT },
+      { role: "user", content: userPrompt },
+    ],
+    { model: TRAINING_CHAT_MODEL, maxTokens: 1800, temperature: 0.3 },
+  );
+
+  return parseProfile(content);
+}
+
+// -----------------------------------------------------------------
+// Parsing — mirrors `normalizeProfile` in
+// `simocracy-v2/app/api/training/extract-profile/route.ts`.
+// -----------------------------------------------------------------
+
+function parseProfile(content: string): TrainingProfile | null {
+  const parsed = parseJsonObject(content);
+  if (!parsed) return null;
+
+  const coreValues = normalizeStringArray(parsed.coreValues, 7);
+  const issuePriorities = normalizeIssuePriorities(parsed.issuePriorities);
+  const redLines = normalizeStringArray(parsed.redLines, 6);
+  const acceptableTradeoffs = normalizeStringArray(parsed.acceptableTradeoffs, 6);
+  const uncertaintyAreas = normalizeStringArray(parsed.uncertaintyAreas, 6);
+  const representationRules = normalizeStringArray(parsed.representationRules, 5);
+
+  if (
+    typeof parsed.summary !== "string" ||
+    coreValues.length < 3 ||
+    issuePriorities.length < 4
+  ) {
+    return null;
+  }
+
+  return {
+    summary: parsed.summary.trim(),
+    coreValues,
+    issuePriorities,
+    redLines,
+    acceptableTradeoffs,
+    uncertaintyAreas,
+    representationRules,
+  };
+}
+
+function parseJsonObject(content: string): Record<string, unknown> | null {
+  const trimmed = content.trim();
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    const start = trimmed.indexOf("{");
+    const end = trimmed.lastIndexOf("}");
+    if (start === -1 || end === -1 || end <= start) return null;
+    try {
+      const parsed: unknown = JSON.parse(trimmed.slice(start, end + 1));
+      return isRecord(parsed) ? parsed : null;
+    } catch {
+      return null;
+    }
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeStringArray(value: unknown, max: number): string[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .filter((item): item is string => typeof item === "string")
+    .map((item) => item.trim())
+    .filter(Boolean)
+    .slice(0, max);
+}
+
+function normalizeIssuePriorities(value: unknown): IssuePriority[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((item) => {
+      if (!isRecord(item)) return null;
+      if (typeof item.issue !== "string" || typeof item.stance !== "string") return null;
+      const importance = toUnit(item.importance);
+      const negotiability = toUnit(item.negotiability);
+      const confidence = toUnit(item.confidence);
+      if (importance === null || negotiability === null || confidence === null) return null;
+      return {
+        issue: item.issue.trim(),
+        stance: item.stance.trim(),
+        importance,
+        negotiability,
+        confidence,
+      };
+    })
+    .filter((item): item is IssuePriority => item !== null)
+    .slice(0, 10);
+}
+
+function toUnit(value: unknown): number | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  return Math.min(1, Math.max(0, value));
+}
+
+// -----------------------------------------------------------------
+// Rendering
+// -----------------------------------------------------------------
+
+const BAR_WIDTH = 10;
+
+export function bar(value: number): string {
+  const filled = Math.max(0, Math.min(BAR_WIDTH, Math.round(value * BAR_WIDTH)));
+  return `[${"█".repeat(filled)}${"░".repeat(BAR_WIDTH - filled)}]`;
+}
+
+export function printProfile(profile: TrainingProfile): void {
+  const lines: string[] = [];
+  lines.push("");
+  lines.push(`Summary: ${profile.summary}`);
+  lines.push("");
+  lines.push(`Core Values:`);
+  for (const v of profile.coreValues) lines.push(`  - ${v}`);
+  lines.push("");
+  lines.push(`Issue Priorities:`);
+  for (const p of profile.issuePriorities) {
+    lines.push(
+      `  ${bar(p.importance)} importance | ${bar(p.negotiability)} negotiability | ${bar(p.confidence)} confidence`,
+    );
+    lines.push(`  ${p.issue} — ${p.stance}`);
+    lines.push("");
+  }
+  if (profile.redLines.length) {
+    lines.push(`Red Lines:`);
+    for (const r of profile.redLines) lines.push(`  - ${r}`);
+    lines.push("");
+  }
+  if (profile.acceptableTradeoffs.length) {
+    lines.push(`Acceptable Tradeoffs:`);
+    for (const t of profile.acceptableTradeoffs) lines.push(`  - ${t}`);
+    lines.push("");
+  }
+  if (profile.uncertaintyAreas.length) {
+    lines.push(`Uncertainty Areas:`);
+    for (const u of profile.uncertaintyAreas) lines.push(`  - ${u}`);
+    lines.push("");
+  }
+  if (profile.representationRules.length) {
+    lines.push(`Representation Rules:`);
+    for (const r of profile.representationRules) lines.push(`  - ${r}`);
+  }
+  console.log(lines.join("\n"));
+}

package/src/training/prompt-helpers.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared helpers for training LLM prompts.
+ *
+ * Mirror of `simocracy-v2/lib/training/prompt-helpers.ts` (subset that
+ * the CLI actually uses). Keep clamps + wrappers in sync with the web
+ * app so the same input produces the same prompt locally.
+ */
+
+import type { BaselineProposal, BaselineVote, InterviewTurn } from "./types.ts";
+
+export const CONSTITUTION_MAX_CHARS = 6000;
+export const TRANSCRIPT_MAX_TURNS = 16;
+
+export function clampConstitution(text: string | undefined): string {
+  if (!text) return "(No current constitution provided)";
+  const trimmed = text.trim();
+  if (trimmed.length <= CONSTITUTION_MAX_CHARS) return trimmed;
+  return `${trimmed.slice(0, CONSTITUTION_MAX_CHARS)}\n\n[…truncated for prompt size; original is ${trimmed.length} chars]`;
+}
+
+export function clampTranscript(turns: InterviewTurn[]): InterviewTurn[] {
+  if (turns.length <= TRANSCRIPT_MAX_TURNS) return turns;
+  return turns.slice(-TRANSCRIPT_MAX_TURNS);
+}
+
+export function wrapAsData(label: string, content: string): string {
+  return `<${label}>\n${content}\n</${label}>`;
+}
+
+export function renderBaselineForPrompt(
+  baselineVotes: BaselineVote[],
+  baselineProposals: BaselineProposal[],
+): string {
+  const enriched = baselineVotes
+    .map((vote) => {
+      const proposal = baselineProposals.find((item) => item.id === vote.proposalId);
+      const reasoning = (vote.reasoning ?? "").trim();
+      const isUntouched =
+        vote.vote === "abstain" && Math.abs(vote.importance - 0.5) < 0.01 && !reasoning;
+      if (isUntouched) return null;
+      return { vote, proposal, reasoning };
+    })
+    .filter(
+      (entry): entry is { vote: BaselineVote; proposal: BaselineProposal | undefined; reasoning: string } =>
+        entry !== null,
+    );
+
+  if (enriched.length === 0) {
+    return "(The user has not voted on any baseline proposals yet.)";
+  }
+
+  const ranked = enriched
+    .map((entry) => {
+      const cast = entry.vote.vote === "abstain" ? 0 : 1;
+      return { ...entry, score: cast * 10 + entry.vote.importance };
+    })
+    .sort((a, b) => b.score - a.score);
+
+  return ranked
+    .map(({ vote, proposal, reasoning }, index) => {
+      const title = proposal?.title ?? vote.proposalId;
+      const topic = proposal?.topic ? ` (${proposal.topic})` : "";
+      const verdict = vote.vote.toUpperCase();
+      const importance = vote.importance.toFixed(2);
+      const summary = proposal?.summary ? ` — proposal: "${proposal.summary}"` : "";
+      const comment = reasoning ? `\n   Comment from user: "${reasoning}"` : "";
+      return `${index + 1}. ${verdict} (importance ${importance}) on "${title}"${topic}${summary}${comment}`;
+    })
+    .join("\n\n");
+}

package/src/training/prompts.ts

@@ -0,0 +1,131 @@
+/**
+ * Shared LLM system prompts for Training Lab + Interview flows.
+ *
+ * **Mirror of `simocracy-v2/lib/training/prompts.ts`.** Keep contents
+ * byte-identical — drift means the CLI's output diverges from the
+ * web app's for the same input.
+ */
+
+/**
+ * System prompt for the adaptive-interview chat turn (mirrors
+ * `/api/training/next-question` on simocracy-v2). Parameterised
+ * because each turn includes the sim's current speaking-style block.
+ */
+export function buildNextQuestionSystemPrompt(simName: string, existingStyle?: string): string {
+  const styleBlock = existingStyle?.trim()
+    ? `\n\n## Your Speaking Style\n${existingStyle.trim()}\n\nKeep this voice in every reply.`
+    : "";
+
+  return `You are ${simName} — a political AI representative the user is currently training. The user has answered a baseline questionnaire (yes/no votes on a set of proposals, with an importance slider and an optional comment per vote) and is now chatting with you so you can fill in the gaps.${styleBlock}
+
+The baseline questionnaire is your primary source of signal. Before each reply you should mentally scan it for:
+
+  - YES votes with high importance and a comment — those reveal what the user actively wants.
+  - NO votes with high importance — those reveal red lines.
+  - ABSTAIN votes — those reveal genuine uncertainty; the user wants you to help them think it through.
+  - Comments that contradict another vote, or that hint at a tradeoff the user would accept.
+  - Importance scores below ~0.3 — those tell you what NOT to spend a question on.
+
+Also scan the constitution above (if any) for what's already settled, and the running transcript so you don't repeat yourself.
+
+This is a chat, not a survey. Each of your replies has two parts:
+
+  1. REACT, briefly, to what the user just said in their previous message. One or two sentences. Reflect back what you heard, push back on a tension you noticed in their votes or earlier answers, or acknowledge a constraint — like a real conversation, not a form. Reference specific things they actually said or voted on when you can ("You voted yes on X with importance 0.8 — …"). Do NOT flatter, do NOT summarize the whole conversation, do NOT explain your methodology. If this is your very first turn (no user messages yet), skip the reaction and just open with a question that follows from their baseline.
+
+  2. ASK exactly one concrete next question, grounded in the baseline. Strongly prefer questions that reference something the user actually voted on or commented on. Probe, in roughly this order of usefulness: red lines they hinted at, tradeoffs they'd accept, relative priority between two issues they both care about, and contradictions in what they've said so far. The question should follow naturally from your reaction — if you noticed a tension, your question should test it.
+
+Speak in first person. Keep your voice consistent with the constitution above. Avoid clichés like "that's a really thoughtful answer". Keep the whole reply under ~120 words; users read every word.
+
+Output plain prose only. No JSON, no markdown headings, no bullet points — just the reaction (if any) followed by the question, written as you would say it out loud.`;
+}
+
+export const TRAINING_EXTRACT_PROFILE_SYSTEM_PROMPT = `You are distilling a training conversation into a structured preference architecture for an AI political representative. Be faithful to the user's own words and votes. Do not invent positions they did not express. Mark anything you are inferring, rather than they stated, by lowering the confidence on that priority. Use short, plain labels.
+
+Return strict JSON matching this TrainingProfile shape exactly:
+{
+  "summary": "1-2 sentence overview",
+  "coreValues": ["3-7 short values"],
+  "issuePriorities": [
+    {
+      "issue": "short label",
+      "stance": "1 sentence",
+      "importance": 0.0,
+      "negotiability": 0.0,
+      "confidence": 0.0
+    }
+  ],
+  "redLines": ["0-6 items"],
+  "acceptableTradeoffs": ["0-6 items"],
+  "uncertaintyAreas": ["0-6 items"],
+  "representationRules": ["0-5 items"]
+}
+No prose outside JSON. Output strict JSON, nothing else.`;
+
+export const TRAINING_ALIGNMENT_TEST_SYSTEM_PROMPT = `You are voting as a trained Simocracy political representative. Use the sim's current constitution and the structured training profile to decide how the sim should vote.
+
+Vote only yes, no, or abstain. Explain your vote in fewer than 280 characters. Output strict JSON, nothing else.`;
+
+export const TRAINING_MERGE_CONSTITUTION_SYSTEM_PROMPT = `You are merging a sim's training profile into its constitution. Your job is to produce a SINGLE COHERENT constitution that reads as a hand-written document — not a Frankenstein of old text plus appended sections.
+
+You receive:
+  - The sim's existing constitution (markdown, may be empty).
+  - The sim's existing short description (one-liner used in previews).
+  - The sim's speaking style, if any (use it to keep voice consistent).
+  - A distilled training profile: summary, core values, issue priorities (each with stance, importance, negotiability, confidence), red lines, acceptable tradeoffs, uncertainty areas, representation rules.
+
+Your output should:
+  1. PRESERVE the existing constitution's voice, structure, and positions still consistent with the profile. Never throw away well-written prose for no reason.
+  2. UPDATE existing positions that are now refined or contradicted by the profile.
+  3. ADD new positions from the profile that aren't covered yet — woven into the existing structure where natural, not appended at the bottom.
+  4. REMOVE or REWRITE stale positions the profile clearly contradicts.
+  5. Read as ONE consistent document. NO section labelled "Training Lab Profile", "Distilled positions", "Update from training", or any other meta-commentary that names the lab. The result should look like a hand-written constitution, not a generated artefact.
+
+If the existing constitution is empty, write one from scratch using the profile as the source of truth — pick a structure that fits the sim's voice (typically: brief intro, core values, key positions, red lines, decision rules / how I vote).
+
+Keep markdown formatting (## headings, **bold**, lists). Stay under ~2,500 words. Don't include placeholder text. Don't add disclaimers like "this constitution may evolve".
+
+OUTPUT FORMAT — exactly two sections separated by a single line containing only "---":
+  - The first section is the new short description (one or two sentences, max 280 characters, no markdown). Suitable for previews and list views.
+  - The second section is the full markdown constitution.
+
+Example output:
+
+A free-software public-goods funder, sceptical of metric-driven funding, optimising for governance experiments and underrepresented communities.
+---
+## What I value
+
+I fund projects that demonstrate strong community governance and serve underrepresented populations…
+
+## How I evaluate proposals
+
+…`;
+
+export const DERIVE_FROM_INTERVIEW_SYSTEM_PROMPT = `You are a constitutional architect and communication style designer for governance simulation agents ("sims") in Simocracy.
+
+You are given an interview transcript containing:
+- Open-ended voice answers about the person's values, evaluation philosophy, and funding priorities
+- Yes/no positions on value statements
+
+From this interview, you must derive TWO things:
+
+=== CONSTITUTION ===
+SHORT: <one-sentence summary of this sim's core political identity, max 200 chars>
+---
+<full constitution in markdown, under 3000 chars, covering:>
+## Core Beliefs
+## Values & Principles
+## Governance Positions
+## Behavioral Guidelines
+
+Use **bold**, *italic*, bullet lists, > blockquotes. Stay faithful to the interviewee's actual positions and voice.
+
+=== STYLE ===
+<speaking style guide in markdown, under 3000 chars, covering:>
+## Tone & Register
+## Vocabulary & Diction
+## Mannerisms & Quirks
+## Communication Patterns
+
+Derive the style from HOW the person expressed themselves in the interview — their word choices, sentence structure, level of formality, use of examples, etc.
+
+Output EXACTLY in this format with the delimiters shown. No other preamble.`;

package/src/training/question-set.ts

@@ -0,0 +1,134 @@
+/**
+ * Question-set bootstrapping for the CLI Training Lab.
+ *
+ * Web parity: `simocracy-v2/lib/training/question-sets.ts`. The web
+ * Lab's BaselineTab auto-picks the facilitator-starred default
+ * template via the indexer; the CLI does the same by listing
+ * `org.simocracy.interviewTemplate` records and asking the user to
+ * pick one (single template = pick automatically; none = built-in
+ * fallback that mirrors `interview-modal.tsx`'s
+ * `buildFallbackTemplate`).
+ */
+
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+
+import { searchInterviewTemplates, type LoadedInterviewTemplate } from "../simocracy.ts";
+import type { BaselineProposal, BaselineQuestionSet, InterviewTemplateRecord } from "./types.ts";
+
+const FALLBACK_OPEN_QUESTIONS = [
+  "What's your personal definition of a \"high-impact project\"?",
+  "When you review a proposal, what are the top 3 things you look for?",
+  "What red flags make you skeptical about a proposal's credibility?",
+  "How do you balance measurable outcomes vs. long-term systemic change?",
+  "If you had limited resources, how would you decide which project to support?",
+  "Which values guide your evaluations the most (e.g., equity, scale, innovation, sustainability)?",
+  "Can you give an example of a project you'd enthusiastically fund, and why?",
+  "Can you give an example of a project you'd likely reject, and why?",
+];
+
+const FALLBACK_YESNO_STATEMENTS = [
+  "Projects with strong community governance should receive preference in funding.",
+  "Public goods that effectively demonstrate the benefit of public goods should receive more funding.",
+  "Environmental sustainability should be a key factor in funding decisions.",
+  "Innovation and experimental approaches should be prioritized over proven solutions.",
+  "Projects with measurable outcomes should be favored over those with difficult-to-quantify benefits.",
+  "Funders should be accountable for the funding they provide to the selected projects.",
+  "Humans are accountable for decisions made by an AI.",
+  "Public goods should prioritize immediate community needs over long-term systemic change.",
+  "Projects that already have a lot of support shouldn't receive additional donations for new small projects.",
+  "Cost effectiveness should be the primary criterion for funding allocation.",
+  "Funding decisions should consider geographic equity and underserved populations.",
+  "Projects that benefit the greatest number of people should be prioritized.",
+  "Funding should support projects with sustainable revenue models.",
+  "Open source software should be allocated the most funding compared to other categories.",
+];
+
+export function buildFallbackTemplate(): InterviewTemplateRecord {
+  return {
+    $type: "org.simocracy.interviewTemplate",
+    name: "Default Constitution",
+    description: "Built-in fallback when the indexer returns no curated templates.",
+    questions: [
+      ...FALLBACK_OPEN_QUESTIONS.map((prompt, i) => ({
+        id: `open-${i + 1}`,
+        type: "open" as const,
+        prompt,
+      })),
+      ...FALLBACK_YESNO_STATEMENTS.map((prompt, i) => ({
+        id: `yesno-${i + 1}`,
+        type: "yesNo" as const,
+        prompt,
+      })),
+    ],
+    createdAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Convert the yes/no questions of a template into a BaselineQuestionSet.
+ * Mirrors `questionSetFromTemplate` in
+ * `simocracy-v2/lib/training/question-sets.ts`.
+ */
+export function questionSetFromTemplate(
+  template: InterviewTemplateRecord,
+  templateUri: string,
+): BaselineQuestionSet {
+  const rkey = templateUri.split("/").pop() ?? "template";
+  const proposals: BaselineProposal[] = template.questions
+    .filter((q) => q.type === "yesNo")
+    .map((question, index) => ({
+      id: `template:${rkey}:${question.id || `q${index}`}`,
+      title: question.prompt,
+      summary: question.prompt,
+      topic: template.name,
+    }));
+  return {
+    source: "template",
+    templateUri,
+    templateName: template.name,
+    proposals,
+  };
+}
+
+/**
+ * Pick an interview template via `ctx.ui.select`. Returns null if the
+ * user cancels. Falls back to the built-in template when the indexer
+ * returns nothing.
+ */
+export async function pickInterviewTemplate(
+  ctx: ExtensionCommandContext,
+): Promise<LoadedInterviewTemplate | null> {
+  ctx.ui.notify("Loading interview templates…", "info");
+  let templates: LoadedInterviewTemplate[] = [];
+  try {
+    templates = await searchInterviewTemplates(100);
+  } catch (err) {
+    ctx.ui.notify(
+      `Indexer template fetch failed: ${(err as Error).message}. Using built-in fallback.`,
+      "warning",
+    );
+  }
+
+  if (templates.length === 0) {
+    ctx.ui.notify(
+      "No curated templates available — using built-in fallback questionnaire.",
+      "info",
+    );
+    return {
+      uri: "",
+      cid: "",
+      did: "",
+      rkey: "",
+      template: buildFallbackTemplate(),
+    };
+  }
+
+  const labels = templates.map((t) => {
+    const yesNoCount = t.template.questions.filter((q) => q.type === "yesNo").length;
+    return `${t.template.name}  —  ${yesNoCount} yes/no, ${t.template.questions.length} total`;
+  });
+  const picked = await ctx.ui.select("Choose an interview template", labels);
+  if (!picked) return null;
+  const idx = labels.indexOf(picked);
+  return templates[idx] ?? null;
+}

package/src/training/storage.ts

@@ -0,0 +1,81 @@
+/**
+ * File-backed Training Lab state for the pi-simocracy CLI.
+ *
+ * Web parity: simocracy-v2 stores `TrainingLabState` in localStorage
+ * keyed by `simocracy.trainingLab.v1.<simUri>`. The CLI has no
+ * localStorage, so we mirror the schema to a JSON file under the
+ * platform's XDG data dir, keyed by the sim's rkey (the loaded sim's
+ * AT-URI rkey is unique within the user's PDS).
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import type { TrainingLabState } from "./types.ts";
+
+const DATA_DIR = process.env.XDG_DATA_HOME
+  ? join(process.env.XDG_DATA_HOME, "pi-simocracy", "training")
+  : join(homedir(), ".local", "share", "pi-simocracy", "training");
+
+export function trainingFilePath(rkey: string): string {
+  return join(DATA_DIR, `${rkey}.json`);
+}
+
+export function trainingDir(): string {
+  return DATA_DIR;
+}
+
+function ensureDir(): void {
+  mkdirSync(DATA_DIR, { recursive: true });
+}
+
+export function createEmptyTrainingLabState(): TrainingLabState {
+  return {
+    baselineVotes: [],
+    interviewTurns: [],
+    feedbackTurns: [],
+    profile: null,
+    alignment: null,
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+export function loadTrainingLabState(rkey: string): TrainingLabState {
+  const path = trainingFilePath(rkey);
+  if (!existsSync(path)) return createEmptyTrainingLabState();
+  try {
+    const raw = readFileSync(path, "utf8");
+    const parsed = JSON.parse(raw) as Partial<TrainingLabState>;
+    return {
+      baselineVotes: parsed.baselineVotes ?? [],
+      interviewTurns: parsed.interviewTurns ?? [],
+      feedbackTurns: parsed.feedbackTurns ?? [],
+      profile: parsed.profile ?? null,
+      alignment: parsed.alignment ?? null,
+      questionSet: parsed.questionSet,
+      updatedAt: parsed.updatedAt ?? new Date().toISOString(),
+    };
+  } catch (err) {
+    console.error(`[pi-simocracy] Could not parse training state at ${path}:`, (err as Error).message);
+    return createEmptyTrainingLabState();
+  }
+}
+
+export function saveTrainingLabState(rkey: string, state: TrainingLabState): void {
+  ensureDir();
+  const path = trainingFilePath(rkey);
+  const next: TrainingLabState = { ...state, updatedAt: new Date().toISOString() };
+  writeFileSync(path, JSON.stringify(next, null, 2), "utf8");
+}
+
+export function clearTrainingLabState(rkey: string): boolean {
+  const path = trainingFilePath(rkey);
+  if (!existsSync(path)) return false;
+  rmSync(path, { force: true });
+  return true;
+}
+
+export function trainingStateExists(rkey: string): boolean {
+  return existsSync(trainingFilePath(rkey));
+}