keating 0.3.6

package/dist/src/core/animation.js

@@ -0,0 +1,304 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { buildLessonPlan } from "./lesson-plan.js";
+import { animationsDir } from "./paths.js";
+import { resolveTopic } from "./topics.js";
+import { slugify } from "./util.js";
+function pickSceneKind(topicName) {
+    const topic = resolveTopic(topicName);
+    // Canonical slug overrides for backward compatibility
+    if (topic.slug === "derivative")
+        return "function-graph";
+    if (topic.slug === "entropy")
+        return "distribution-bars";
+    if (topic.slug === "bayes-rule")
+        return "belief-update";
+    // Route by domain
+    switch (topic.domain) {
+        case "math": return "function-graph";
+        case "science": return "distribution-bars";
+        case "code": return "code-trace";
+        case "history": return "timeline";
+        case "law":
+        case "politics": return "case-diagram";
+        case "psychology":
+        case "arts": return "mind-map";
+        case "medicine": return "distribution-bars";
+        default: return "concept-card";
+    }
+}
+function importSpecifierFrom(dirPath, targetPath) {
+    const specifier = relative(dirPath, targetPath).replaceAll("\\", "/");
+    return specifier.startsWith(".") ? specifier : `./${specifier}`;
+}
+function installedManimWebDistDir() {
+    const moduleUrl = import.meta.url;
+    const modulePath = decodeURIComponent(moduleUrl.replace(/^file:\/\//, ""));
+    const packageRoot = modulePath.includes("/src/")
+        ? modulePath.split("/src/")[0]
+        : modulePath.includes("/dist/src/")
+            ? modulePath.split("/dist/src/")[0]
+            : join(dirname(modulePath), "../../../");
+    return join(packageRoot, "node_modules/manim-web/dist");
+}
+async function copyDir(sourceDir, targetDir) {
+    await mkdir(targetDir, { recursive: true });
+    const entries = await readdir(sourceDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const sourcePath = join(sourceDir, entry.name);
+        const targetPath = join(targetDir, entry.name);
+        if (entry.isDirectory()) {
+            await copyDir(sourcePath, targetPath);
+        }
+        else if (entry.isFile()) {
+            await writeFile(targetPath, await readFile(sourcePath));
+        }
+    }
+}
+function sceneRationale(topicName, policy, sceneKind) {
+    const topic = resolveTopic(topicName);
+    return [
+        `${topic.title} is marked visualizable=${String(topic.visualizable)} and belongs to ${topic.domain}.`,
+        `The current policy prefers diagrams at ${policy.diagramBias.toFixed(2)} and formalism at ${policy.formalism.toFixed(2)}.`,
+        sceneKind === "function-graph"
+            ? "A function graph highlights local change, secant-to-tangent motion, and equation refinement."
+            : sceneKind === "distribution-bars"
+                ? "A bar chart makes multiplicity, relative weight, and statistical relationships legible before symbol manipulation."
+                : sceneKind === "belief-update"
+                    ? "A belief-update chart makes prior, evidence, and posterior shifts visible instead of purely verbal."
+                    : sceneKind === "code-trace"
+                        ? "A code-trace scene shows execution flow, variable state, and call-stack evolution step by step."
+                        : sceneKind === "timeline"
+                            ? "A timeline scene places events in chronological order so causal relationships and periodization become visible."
+                            : sceneKind === "case-diagram"
+                                ? "A case-diagram scene structures arguments as premises leading to conclusions, making reasoning transparent."
+                                : sceneKind === "mind-map"
+                                    ? "A mind-map scene radiates concepts from a central idea, revealing connections and clustering."
+                                    : "A concept-card scene is safer when the concept is philosophical or the visual grammar is still exploratory.",
+        `Interdisciplinary hooks carried into the scene: ${topic.interdisciplinaryHooks.join(", ")}.`
+    ];
+}
+export function buildAnimationManifest(topicName, policy) {
+    const topic = resolveTopic(topicName);
+    const plan = buildLessonPlan(topicName, policy);
+    const sceneKind = pickSceneKind(topicName);
+    return {
+        topic: topic.title,
+        slug: slugify(topicName),
+        domain: topic.domain,
+        sceneKind,
+        rationale: sceneRationale(topicName, policy, sceneKind),
+        focusMoments: plan.phases.slice(0, 4).map((phase) => `${phase.title}: ${phase.purpose}`)
+    };
+}
+import { piComplete } from "./pi-agent.js";
+export async function animationSceneSource(cwd, topicName, policy, importSpecifier) {
+    const topic = resolveTopic(topicName);
+    const manifest = buildAnimationManifest(topicName, policy);
+    const thesis = topic.formalCore[0] ?? topic.summary;
+    const misconception = topic.misconceptions[0] ?? `Avoid flattening ${topic.title} into a slogan.`;
+    const bridge = topic.interdisciplinaryHooks[0] ?? "application";
+    const palette = {
+        background: "#08111f",
+        ink: "#f8f5ec",
+        accent: "#ff7a59",
+        support: "#7bb0ff",
+        soft: "#9dd7c8",
+        warning: "#ff8e72"
+    };
+    const commonHelpers = `
+const palette = ${JSON.stringify(palette, null, 2)};
+
+function textLine(text, y, fontSize = 28, color = palette.ink, fontFamily = "Iowan Old Style, Georgia, serif") {
+  const node = new Text({
+    text,
+    fontSize,
+    color,
+    fontFamily,
+    lineHeight: 1.15
+  });
+  node.moveTo([0, y, 0]);
+  return node;
+}
+`;
+    const prompt = `You are an expert ManimJS animation developer. Output the body of the 'construct(scene)' function for an animation explaining the academic topic: "${topic.title}".
+  
+Domain: ${topic.domain}
+Focus: ${manifest.sceneKind}
+Topic Details:
+- Thesis: ${thesis}
+- Misconception to avoid: ${misconception}
+- Application: ${bridge}
+- Diagram Nodes available: ${JSON.stringify(topic.diagramNodes)}
+
+Environment Context:
+We are using manim-web. You have imported Scene, Text, MathTex, Axes, BarChart, Create, Write, FadeIn, FadeOut, Transform. 
+You can use the helper \`textLine(text, y, fontSize, color)\` which returns a Text node centered at (0, y).
+Colors available: palette.accent, palette.support, palette.soft, palette.warning, palette.ink.
+
+Respond ONLY with the JavaScript code that belongs inside \`export async function construct(scene) { ... }\`. Do NOT wrap it in markdown block quotes. Do not provide a pre-amble or explanation. Generate sequential scene animations using \`await scene.play(...)\` and \`await scene.wait(...)\` in a way that matches the requested topic's depth. Ensure it looks impressive and dynamic.`;
+    let sceneLogic = "";
+    try {
+        sceneLogic = await piComplete(cwd, prompt, { thinking: "medium" });
+        // Remove markdown code blocks if the LLM leaked them
+        sceneLogic = sceneLogic.replace(/^```[a-z]*\n?/gm, "").replace(/```$/g, "").trim();
+    }
+    catch (error) {
+        console.error("Failed to dynamically generate scene logic, falling back to basic stub:", error);
+        sceneLogic = `
+  const thesisNode = textLine(${JSON.stringify(thesis)}, 1.25, 26);
+  const warningNode = textLine(${JSON.stringify(`Misconception: ${misconception}`)}, -0.15, 24, palette.warning);
+  await scene.play(new FadeIn(thesisNode), new FadeIn(warningNode));
+`;
+    }
+    return `import { 
+  Scene, Text, MathTex, Axes, BarChart, 
+  Create, Write, FadeIn, FadeOut, Transform 
+} from ${JSON.stringify(importSpecifier)};
+
+${commonHelpers}
+
+export async function construct(scene) {
+  const title = textLine(${JSON.stringify(`${topic.title}: ${manifest.sceneKind}`)}, 3.2, 34, palette.accent);
+  await scene.play(new Write(title));
+
+  ${sceneLogic}
+
+  await scene.wait(2.0);
+}
+`;
+}
+export function animationStoryboardMarkdown(topicName, policy) {
+    const manifest = buildAnimationManifest(topicName, policy);
+    const plan = buildLessonPlan(topicName, policy);
+    const lines = [
+        `# Animation Storyboard: ${manifest.topic}`,
+        "",
+        `- Scene kind: ${manifest.sceneKind}`,
+        `- Domain: ${manifest.domain}`,
+        `- Policy: ${policy.name}`,
+        "",
+        "## Why This Visual",
+        ...manifest.rationale.map((item) => `- ${item}`),
+        "",
+        "## Focus Moments",
+        ...manifest.focusMoments.map((item) => `- ${item}`),
+        "",
+        "## Teaching Beats",
+        ...plan.phases.map((phase) => `- ${phase.title}: ${phase.purpose}`),
+        ""
+    ];
+    return `${lines.join("\n").trim()}\n`;
+}
+export async function writeLessonAnimation(cwd, topicName, policy) {
+    const slug = slugify(topicName);
+    const topicDir = join(animationsDir(cwd), slug);
+    await mkdir(topicDir, { recursive: true });
+    const vendorDir = join(topicDir, "_vendor", "manim-web");
+    await copyDir(installedManimWebDistDir(), vendorDir);
+    const importSpecifier = importSpecifierFrom(topicDir, join(vendorDir, "index.js"));
+    const playerPath = join(topicDir, "player.html");
+    const scenePath = join(topicDir, "scene.mjs");
+    const storyboardPath = join(topicDir, "storyboard.md");
+    const manifestPath = join(topicDir, "manifest.json");
+    const readmePath = join(topicDir, "README.md");
+    const manifest = buildAnimationManifest(topicName, policy);
+    const sceneSource = await animationSceneSource(cwd, topicName, policy, importSpecifier);
+    const playerHtml = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Keating Animation: ${manifest.topic}</title>
+    <style>
+      :root {
+        color-scheme: dark;
+        --paper: #f8f5ec;
+        --ink: #07111d;
+        --frame: #10223a;
+        --muted: #90a3b8;
+      }
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: grid;
+        place-items: center;
+        background:
+          radial-gradient(circle at top, rgba(121, 168, 255, 0.25), transparent 28rem),
+          linear-gradient(180deg, #08111f 0%, #050a12 100%);
+        color: var(--paper);
+        font-family: "Iowan Old Style", Georgia, serif;
+      }
+      main {
+        width: min(92vw, 1280px);
+        display: grid;
+        gap: 1rem;
+      }
+      header {
+        display: flex;
+        justify-content: space-between;
+        gap: 1rem;
+        align-items: end;
+      }
+      .meta {
+        color: var(--muted);
+        font-size: 0.95rem;
+      }
+      #scene {
+        height: min(72vh, 760px);
+        border: 1px solid rgba(255, 255, 255, 0.14);
+        border-radius: 20px;
+        overflow: hidden;
+        box-shadow: 0 24px 90px rgba(0, 0, 0, 0.35);
+        background: #08111f;
+      }
+      a { color: #b5d2ff; }
+    </style>
+  </head>
+  <body>
+    <main>
+      <header>
+        <div>
+          <div class="meta">Keating visual artifact</div>
+          <h1>${manifest.topic}</h1>
+        </div>
+        <div class="meta">
+          <div><a href="./storyboard.md">storyboard.md</a></div>
+          <div><a href="./manifest.json">manifest.json</a></div>
+        </div>
+      </header>
+      <div id="scene"></div>
+    </main>
+    <script type="module">
+      import { Scene } from ${JSON.stringify(importSpecifier)};
+      import { construct } from "./scene.mjs";
+
+      const container = document.getElementById("scene");
+      const scene = new Scene(container, {
+        width: 1280,
+        height: 720,
+        backgroundColor: "#08111f"
+      });
+
+      await construct(scene);
+    </script>
+  </body>
+</html>
+`;
+    const readme = `# ${manifest.topic} Animation Bundle
+
+- Serve the repository root with a static file server, for example: \`python3 -m http.server 4173\`
+- Open: \`http://localhost:4173/${relative(cwd, playerPath).replaceAll("\\", "/")}\`
+- Inspect the bundle in \`scene.mjs\`, \`storyboard.md\`, and \`manifest.json\`
+
+This bundle is deterministic source output. Keating does not yet export a video in Node; it generates a browser-runnable \`manim-web\` scene so the visual teaching layer can evolve under versioned prompts and tests.
+`;
+    await Promise.all([
+        writeFile(scenePath, sceneSource, "utf8"),
+        writeFile(playerPath, playerHtml, "utf8"),
+        writeFile(storyboardPath, animationStoryboardMarkdown(topicName, policy), "utf8"),
+        writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8"),
+        writeFile(readmePath, readme, "utf8")
+    ]);
+    return { topicDir, playerPath, scenePath, storyboardPath, manifestPath };
+}

package/dist/src/core/ax-optimizer.js

@@ -0,0 +1,81 @@
+import { writeFile, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { runBenchmarkSuite } from "./benchmark.js";
+import { PolicyTrial, trialToPolicy, trialToWeights, optimize } from "./ax-trial.js";
+import { mean } from "./util.js";
+import { stateDir } from "./paths.js";
+import { mapElitesEvolve, mapElitesToEvolutionRun } from "./map-elites.js";
+function gepaResultPath(cwd) {
+    return join(stateDir(cwd), "gepa-optimized.json");
+}
+/**
+ * Optimizes the TeacherPolicy using GEPA multi-objective tuning.
+ */
+export async function optimizePolicy(cwd, basePolicy, options = {}) {
+    const { nTrials = 24, objectives = ["score", "transfer", "engagement"], focusTopic, seed = 20260401 } = options;
+    console.log(`Starting GEPA Policy Optimization (${nTrials} trials, objectives: ${objectives.join(", ")})`);
+    const objective = async (trial) => {
+        const policy = trialToPolicy(trial, `gepa-candidate-${trial.params.iteration ?? 0}`);
+        const weights = trialToWeights(trial);
+        const benchmark = await runBenchmarkSuite(cwd, policy, focusTopic, seed, 3, weights);
+        const result = {};
+        for (const obj of objectives) {
+            if (obj === "score")
+                result[obj] = benchmark.overallScore / 100;
+            else if (obj === "transfer")
+                result[obj] = mean(benchmark.topicBenchmarks.map(b => b.meanTransfer));
+            else if (obj === "engagement")
+                result[obj] = mean(benchmark.topicBenchmarks.map(b => b.meanEngagement));
+            else if (obj === "retention")
+                result[obj] = mean(benchmark.topicBenchmarks.map(b => b.meanRetention));
+            else if (obj === "confusion")
+                result[obj] = 1 - mean(benchmark.topicBenchmarks.map(b => b.meanConfusion));
+        }
+        return result;
+    };
+    try {
+        const study = await optimize(objective, {
+            nTrials,
+            direction: "maximize",
+            seed
+        });
+        const bestPolicy = trialToPolicy(new PolicyTrial(study.bestParams), `gepa-best-${Date.now().toString(36)}`);
+        const archiveContent = await readFile(join(stateDir(cwd), "policy-archive.json"), "utf8").catch(() => "[]");
+        const archive = JSON.parse(archiveContent);
+        const baseline = await runBenchmarkSuite(cwd, basePolicy, focusTopic, seed);
+        const best = await runBenchmarkSuite(cwd, bestPolicy, focusTopic, seed);
+        const run = {
+            baseline,
+            best,
+            acceptedCandidates: [], // Not using candidate-by-candidate acceptance here
+            exploredCandidates: study.paretoFront.map((p, i) => ({
+                policy: trialToPolicy(new PolicyTrial(p.params), `gepa-pareto-${i}`),
+                benchmark: baseline, // Placeholder
+                parentName: basePolicy.name,
+                iteration: i,
+                novelty: 1.0,
+                accepted: true,
+                parameterDelta: [],
+                decision: { improves: true, safe: true, novelEnough: true, scoreDelta: 0, weakestTopicDelta: 0, reasons: [] }
+            })),
+            archive: {
+                currentPolicy: bestPolicy,
+                bestScore: best.overallScore,
+                candidates: study.paretoFront.map(p => ({
+                    policy: trialToPolicy(new PolicyTrial(p.params), "gepa"),
+                    score: mean(Object.values(p.scores)) * 100,
+                    novelty: 1.0,
+                    accepted: true,
+                    iteration: 0
+                }))
+            }
+        };
+        await writeFile(gepaResultPath(cwd), JSON.stringify(study, null, 2), "utf8");
+        return run;
+    }
+    catch (error) {
+        console.warn("GEPA Optimization failed, falling back to MAP-Elites.", error);
+        const meRun = await mapElitesEvolve(cwd, basePolicy, { iterations: nTrials, focusTopic, seed });
+        return mapElitesToEvolutionRun(meRun);
+    }
+}

package/dist/src/core/ax-prompt-learner.js

@@ -0,0 +1,59 @@
+import { writeFile, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ai, ax, AxACE } from "@ax-llm/ax";
+import { evaluatePromptContent } from "./prompt-evolution.js";
+import { stateDir } from "./paths.js";
+import { loadKeatingConfig } from "./config.js";
+// Helper to convert typical string models to Ax model enums or strings
+function mapToAxModel(keatingModel) {
+    if (keatingModel.includes("gpt-4o-mini"))
+        return "gpt-4o-mini";
+    if (keatingModel.includes("gpt-4o"))
+        return "gpt-4o";
+    if (keatingModel.includes("claude-3-5-sonnet"))
+        return "claude-3-5-sonnet-20240620";
+    // fallback
+    return keatingModel;
+}
+export async function learnPrompt(cwd, promptName = "learn", options = {}) {
+    const { maxEpochs = 3 } = options;
+    const promptPath = join(cwd, "pi", "prompts", `${promptName}.md`);
+    const basePrompt = await readFile(promptPath, "utf8");
+    const config = await loadKeatingConfig(cwd);
+    const studentAI = ai({
+        name: config.pi.defaultProvider === "openai" ? "openai" : "google-gemini",
+        apiKey: process.env.OPENAI_API_KEY || process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY || "",
+        config: { model: mapToAxModel(config.pi.defaultModel || "google/gemini-3.1-pro-preview") }
+    });
+    const teacherAI = ai({
+        name: config.pi.defaultProvider === "openai" ? "openai" : "google-gemini",
+        apiKey: process.env.OPENAI_API_KEY || process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY || "",
+        config: { model: mapToAxModel("google/gemini-3.1-pro-preview") }
+    });
+    const analyzer = ax('topic:string -> teachingResponse:string');
+    analyzer.setDescription("You are Keating, a hyperteacher.");
+    // Dummy baseline examples for ACE
+    const examples = [
+        { topic: "Functions", teachingResponse: "Functions are machines that take inputs and produce outputs." }
+    ];
+    const metric = async ({ prediction, example }) => {
+        // Call the original heuristic / LLM evaluator
+        const evalResult = await evaluatePromptContent(cwd, promptPath, prediction.teachingResponse);
+        return evalResult.score / 100.0;
+    };
+    try {
+        const optimizer = new AxACE({ studentAI, teacherAI, verbose: true }, { maxEpochs });
+        console.log(`Running ACE Prompt Learning for ${promptName}...`);
+        const result = await optimizer.compile(analyzer, examples, metric);
+        if (result.artifact?.playbook) {
+            const playbookPath = join(stateDir(cwd), "ace-playbook.json");
+            await writeFile(playbookPath, JSON.stringify(result.artifact.playbook, null, 2), "utf8");
+            return { playbook: result.artifact.playbook };
+        }
+        return { playbook: {} };
+    }
+    catch (error) {
+        console.warn("Ax ACE prompt optimization failed or API key missing, falling back to heuristics.", error);
+        return { playbook: {} };
+    }
+}

package/dist/src/core/ax-trial.js

@@ -0,0 +1,181 @@
+/**
+ * ax-trial.ts — Hyperparameter trial abstraction for Keating
+ *
+ * Maps TeacherPolicy fields into an Optuna-style suggest API that
+ * GEPA's multi-objective optimizer can explore. Provides the
+ * `KeatingTrial` / `optimize()` surface that mirrors the
+ * `hyperparameter` package API from the design spec.
+ */
+import { mean } from "./util.js";
+import { clampPolicy, clampWeights, DEFAULT_POLICY, DEFAULT_WEIGHTS } from "./policy.js";
+/** The full search space for Keating's TeacherPolicy hyperparameters. */
+export const POLICY_PARAM_SPACE = [
+    { name: "analogyDensity", type: "float", low: 0.0, high: 1.0 },
+    { name: "socraticRatio", type: "float", low: 0.0, high: 1.0 },
+    { name: "formalism", type: "float", low: 0.0, high: 1.0 },
+    { name: "retrievalPractice", type: "float", low: 0.0, high: 1.0 },
+    { name: "exerciseCount", type: "int", low: 1, high: 5 },
+    { name: "diagramBias", type: "float", low: 0.0, high: 1.0 },
+    { name: "reflectionBias", type: "float", low: 0.0, high: 1.0 },
+    { name: "interdisciplinaryBias", type: "float", low: 0.0, high: 1.0 },
+    { name: "challengeRate", type: "float", low: 0.0, high: 1.0 }
+];
+/** The search space for SimulationWeights (learned scoring weights). */
+export const WEIGHT_PARAM_SPACE = [
+    { name: "masteryGain", type: "float", low: 0.05, high: 1.0 },
+    { name: "retention", type: "float", low: 0.05, high: 1.0 },
+    { name: "engagement", type: "float", low: 0.05, high: 1.0 },
+    { name: "transfer", type: "float", low: 0.05, high: 1.0 },
+    { name: "confusion", type: "float", low: 0.05, high: 1.0 }
+];
+// ---------------------------------------------------------------------------
+// Trial implementation — used internally by the optimizer
+// ---------------------------------------------------------------------------
+export class PolicyTrial {
+    values;
+    _params = {};
+    constructor(values) {
+        this.values = values;
+    }
+    get params() {
+        return { ...this._params };
+    }
+    suggestFloat(name, low, high) {
+        const value = this.values[name] ?? (low + high) / 2;
+        const clamped = Math.max(low, Math.min(high, value));
+        this._params[name] = clamped;
+        return clamped;
+    }
+    suggestInt(name, low, high) {
+        const value = this.values[name] ?? Math.round((low + high) / 2);
+        const clamped = Math.max(low, Math.min(high, Math.round(value)));
+        this._params[name] = clamped;
+        return clamped;
+    }
+}
+// ---------------------------------------------------------------------------
+// Conversion helpers
+// ---------------------------------------------------------------------------
+/**
+ * Build a TeacherPolicy from a trial's suggested parameters.
+ * Missing fields fall back to DEFAULT_POLICY.
+ */
+export function trialToPolicy(trial, label) {
+    const params = trial.params;
+    return clampPolicy({
+        name: label,
+        analogyDensity: params.analogyDensity ?? DEFAULT_POLICY.analogyDensity,
+        socraticRatio: params.socraticRatio ?? DEFAULT_POLICY.socraticRatio,
+        formalism: params.formalism ?? DEFAULT_POLICY.formalism,
+        retrievalPractice: params.retrievalPractice ?? DEFAULT_POLICY.retrievalPractice,
+        exerciseCount: params.exerciseCount ?? DEFAULT_POLICY.exerciseCount,
+        diagramBias: params.diagramBias ?? DEFAULT_POLICY.diagramBias,
+        reflectionBias: params.reflectionBias ?? DEFAULT_POLICY.reflectionBias,
+        interdisciplinaryBias: params.interdisciplinaryBias ?? DEFAULT_POLICY.interdisciplinaryBias,
+        challengeRate: params.challengeRate ?? DEFAULT_POLICY.challengeRate
+    });
+}
+/**
+ * Build SimulationWeights from a trial's suggested parameters.
+ * Missing fields fall back to DEFAULT_WEIGHTS.
+ */
+export function trialToWeights(trial) {
+    const params = trial.params;
+    return clampWeights({
+        masteryGain: params.masteryGain ?? DEFAULT_WEIGHTS.masteryGain,
+        retention: params.retention ?? DEFAULT_WEIGHTS.retention,
+        engagement: params.engagement ?? DEFAULT_WEIGHTS.engagement,
+        transfer: params.transfer ?? DEFAULT_WEIGHTS.transfer,
+        confusion: params.confusion ?? DEFAULT_WEIGHTS.confusion
+    });
+}
+/**
+ * Convert an existing TeacherPolicy into a parameter dict suitable for PolicyTrial.
+ */
+export function policyToParams(policy) {
+    return {
+        analogyDensity: policy.analogyDensity,
+        socraticRatio: policy.socraticRatio,
+        formalism: policy.formalism,
+        retrievalPractice: policy.retrievalPractice,
+        exerciseCount: policy.exerciseCount,
+        diagramBias: policy.diagramBias,
+        reflectionBias: policy.reflectionBias,
+        interdisciplinaryBias: policy.interdisciplinaryBias,
+        challengeRate: policy.challengeRate
+    };
+}
+export function weightsToParams(weights) {
+    return {
+        masteryGain: weights.masteryGain,
+        retention: weights.retention,
+        engagement: weights.engagement,
+        transfer: weights.transfer,
+        confusion: weights.confusion
+    };
+}
+/**
+ * A basic multi-objective optimizer that returns the Pareto frontier.
+ */
+export async function optimize(objective, options) {
+    const { nTrials, seed = Date.now() } = options;
+    const prng = new (await import("./random.js")).Prng(seed);
+    const trials = [];
+    for (let i = 0; i < nTrials; i++) {
+        const values = {};
+        for (const range of POLICY_PARAM_SPACE) {
+            values[range.name] = range.type === "float"
+                ? range.low + prng.next() * (range.high - range.low)
+                : Math.round(range.low + prng.next() * (range.high - range.low));
+        }
+        for (const range of WEIGHT_PARAM_SPACE) {
+            values[range.name] = range.type === "float"
+                ? range.low + prng.next() * (range.high - range.low)
+                : Math.round(range.low + prng.next() * (range.high - range.low));
+        }
+        const trial = new PolicyTrial(values);
+        const scores = await objective(trial);
+        trials.push({ params: trial.params, scores });
+    }
+    // Compute Pareto frontier
+    const paretoFront = trials.filter((t1) => {
+        // A trial is Pareto-optimal if no other trial dominates it
+        return !trials.some((t2) => {
+            if (t1 === t2)
+                return false;
+            const objectives = Object.keys(t1.scores);
+            // t2 dominates t1 if:
+            // 1. t2 is better than or equal to t1 in all objectives
+            // 2. t2 is strictly better than t1 in at least one objective
+            let betterOrEqual = true;
+            let strictlyBetter = false;
+            for (const obj of objectives) {
+                const v1 = t1.scores[obj];
+                const v2 = t2.scores[obj];
+                if (options.direction === "maximize") {
+                    if (v2 < v1)
+                        betterOrEqual = false;
+                    if (v2 > v1)
+                        strictlyBetter = true;
+                }
+                else {
+                    if (v2 > v1)
+                        betterOrEqual = false;
+                    if (v2 < v1)
+                        strictlyBetter = true;
+                }
+            }
+            return betterOrEqual && strictlyBetter;
+        });
+    });
+    // Pick "best" by simple mean of scores
+    const best = paretoFront.sort((a, b) => {
+        const meanA = mean(Object.values(a.scores));
+        const meanB = mean(Object.values(b.scores));
+        return meanB - meanA;
+    })[0] || trials[0];
+    return {
+        bestParams: best.params,
+        paretoFront
+    };
+}