@interleavelove/keating 0.1.0

package/dist/src/core/animation.js

@@ -0,0 +1,372 @@
+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}`)
+    };
+}
+export function animationSceneSource(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;
+}
+`;
+    let sceneLogic = "";
+    switch (manifest.sceneKind) {
+        case "function-graph":
+            sceneLogic = `
+  const axes = new Axes({
+    xRange: [-2, 3, 1],
+    yRange: [-1, 6, 1],
+    xLength: 10,
+    yLength: 5.5,
+    color: palette.support
+  });
+  axes.moveTo([0, -0.2, 0]);
+
+  const plot = axes.plot((x) => x * x, {
+    xRange: [-1.8, 2.2],
+    color: palette.accent,
+    strokeWidth: 5
+  });
+
+  const formula = new MathTex({
+    latex: ${JSON.stringify(topic.formalCore[0] || "f(x)")},
+    fontSize: 42,
+    color: palette.ink
+  });
+  formula.moveTo([0, -3.05, 0]);
+
+  await scene.play(new Create(axes), new Create(plot));
+  await scene.play(new Write(formula));
+`;
+            break;
+        case "distribution-bars":
+        case "belief-update":
+            sceneLogic = `
+  const chart = new BarChart({
+    values: [0.2, 0.5, 0.8],
+    xLabels: ["initial", "mid", "target"],
+    barColors: [palette.support, palette.soft, palette.accent],
+    yRange: [0, 1, 0.2],
+    width: 8.5,
+    height: 4.6,
+    axisColor: palette.ink
+  });
+  chart.moveTo([0, -0.25, 0]);
+
+  const label = textLine(${JSON.stringify(topic.summary)}, -3.0, 24, palette.soft);
+
+  await scene.play(new Create(chart));
+  await scene.play(new FadeIn(label));
+`;
+            break;
+        case "code-trace":
+            sceneLogic = `
+  const code = textLine(${JSON.stringify(topic.examples[0] || "// example code")}, 0, 24, palette.soft, "'Fira Code', monospace");
+  const state = textLine("State: evolving...", -2.0, 24, palette.accent);
+  await scene.play(new Write(code));
+  await scene.play(new FadeIn(state));
+`;
+            break;
+        case "timeline":
+            sceneLogic = `
+  const events = ${JSON.stringify(topic.diagramNodes.slice(0, 4))};
+  for (let i = 0; i < events.length; i++) {
+    const node = textLine(events[i], 1.5 - i * 1.0, 28, i % 2 === 0 ? palette.accent : palette.support);
+    await scene.play(new FadeIn(node));
+    await scene.wait(0.2);
+  }
+`;
+            break;
+        case "case-diagram":
+            sceneLogic = `
+  const premise = textLine(${JSON.stringify(topic.formalCore[0] || "Premise")}, 1.0, 26, palette.soft);
+  const conclusion = textLine(${JSON.stringify(topic.summary)}, -1.0, 30, palette.accent);
+  await scene.play(new Write(premise));
+  await scene.wait(0.5);
+  await scene.play(new Transform(premise, conclusion));
+`;
+            break;
+        case "mind-map":
+            sceneLogic = `
+  const center = textLine(${JSON.stringify(topic.title)}, 0, 42, palette.accent);
+  await scene.play(new Write(center));
+  const nodes = ${JSON.stringify(topic.diagramNodes.slice(0, 4))};
+  const positions = [[-4, 2], [4, 2], [-4, -2], [4, -2]];
+  for (let i = 0; i < nodes.length; i++) {
+    const node = textLine(nodes[i], 0, 24, palette.support);
+    node.moveTo([...positions[i], 0]);
+    await scene.play(new FadeIn(node));
+  }
+`;
+            break;
+        default: // concept-card
+            sceneLogic = `
+  const thesis = textLine(${JSON.stringify(thesis)}, 1.25, 26);
+  const warning = textLine(${JSON.stringify(`Misconception: ${misconception}`)}, -0.15, 24, palette.warning);
+  const hook = textLine(${JSON.stringify(`Bridge: ${bridge}`)}, -1.65, 24, palette.soft);
+
+  await scene.play(new FadeIn(thesis), new FadeIn(warning), new FadeIn(hook));
+`;
+    }
+    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 = animationSceneSource(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/benchmark.js

@@ -0,0 +1,238 @@
+import { Prng } from "./random.js";
+import { benchmarkTopics } from "./topics.js";
+import { clamp, mean } from "./util.js";
+function buildLearnerPopulation(seed, count) {
+    const prng = new Prng(seed);
+    const learners = [];
+    for (let index = 0; index < count; index += 1) {
+        learners.push({
+            id: `learner-${seed}-${index}`,
+            priorKnowledge: prng.next(),
+            abstractionComfort: prng.next(),
+            analogyNeed: prng.next(),
+            dialoguePreference: prng.next(),
+            diagramAffinity: prng.next(),
+            persistence: prng.next(),
+            transferDesire: prng.next(),
+            anxiety: prng.next()
+        });
+    }
+    return learners;
+}
+export function simulateTeaching(policy, topic, learner) {
+    const intuitionFit = 1 - Math.abs(policy.analogyDensity - learner.analogyNeed);
+    const rigorTarget = clamp((topic.formalism + learner.abstractionComfort) / 2);
+    const rigorFit = 1 - Math.abs(policy.formalism - rigorTarget);
+    const dialogueFit = 1 - Math.abs(policy.socraticRatio - learner.dialoguePreference);
+    const diagramTarget = topic.visualizable ? learner.diagramAffinity : 0.2;
+    const diagramFit = 1 - Math.abs(policy.diagramBias - diagramTarget);
+    const practiceNeed = clamp(1 - learner.priorKnowledge + learner.anxiety * 0.2);
+    const practiceFit = 1 - Math.abs(policy.exerciseCount / 5 - practiceNeed);
+    const reflectionFit = 1 - Math.abs(policy.reflectionBias - learner.transferDesire);
+    const overload = clamp(policy.formalism * 0.35 +
+        (policy.exerciseCount / 5) * 0.15 +
+        policy.challengeRate * 0.3 -
+        learner.persistence * 0.2 +
+        learner.anxiety * 0.25 -
+        learner.priorKnowledge * 0.15);
+    const masteryGain = clamp(0.14 +
+        intuitionFit * 0.18 +
+        rigorFit * 0.2 +
+        dialogueFit * 0.12 +
+        diagramFit * 0.09 +
+        practiceFit * 0.12 +
+        (1 - overload) * 0.18);
+    const retention = clamp(masteryGain * (0.55 + policy.retrievalPractice * 0.45));
+    const engagement = clamp(0.12 +
+        intuitionFit * 0.16 +
+        dialogueFit * 0.16 +
+        diagramFit * 0.1 +
+        reflectionFit * 0.14 +
+        (1 - overload) * 0.18);
+    const transfer = clamp(retention * (0.55 + policy.interdisciplinaryBias * 0.25 + learner.transferDesire * 0.2));
+    const confusion = clamp(0.04 +
+        overload * 0.55 +
+        Math.abs(policy.formalism - learner.abstractionComfort) * 0.18 +
+        Math.abs(policy.challengeRate - learner.persistence) * 0.12);
+    const score = clamp(masteryGain * 0.34 +
+        retention * 0.2 +
+        engagement * 0.16 +
+        transfer * 0.18 -
+        confusion * 0.18, 0, 1);
+    const explanation = [];
+    if (intuitionFit >= 0.8)
+        explanation.push("analogy pacing matched the learner well");
+    if (rigorFit >= 0.8)
+        explanation.push("formal depth fit the learner's abstraction comfort");
+    if (practiceFit >= 0.75)
+        explanation.push("exercise load matched the learner's need for repetition");
+    if (reflectionFit >= 0.75)
+        explanation.push("reflection and transfer demands aligned with the learner");
+    if (overload >= 0.55)
+        explanation.push("challenge and formal load pushed the learner toward overload");
+    if (diagramFit <= 0.45)
+        explanation.push("diagram emphasis mismatched the learner's visual preference");
+    if (explanation.length === 0)
+        explanation.push("the lesson was balanced but not strongly optimized for this learner");
+    return {
+        learner,
+        topic,
+        masteryGain,
+        retention,
+        engagement,
+        transfer,
+        confusion,
+        score,
+        breakdown: {
+            intuitionFit,
+            rigorFit,
+            dialogueFit,
+            diagramFit,
+            practiceFit,
+            reflectionFit,
+            overload
+        },
+        explanation
+    };
+}
+function classifyDominantSignal(simulations, kind) {
+    const metrics = {
+        intuitionFit: mean(simulations.map((entry) => entry.breakdown.intuitionFit)),
+        rigorFit: mean(simulations.map((entry) => entry.breakdown.rigorFit)),
+        dialogueFit: mean(simulations.map((entry) => entry.breakdown.dialogueFit)),
+        diagramFit: mean(simulations.map((entry) => entry.breakdown.diagramFit)),
+        practiceFit: mean(simulations.map((entry) => entry.breakdown.practiceFit)),
+        reflectionFit: mean(simulations.map((entry) => entry.breakdown.reflectionFit)),
+        overload: mean(simulations.map((entry) => entry.breakdown.overload))
+    };
+    const ordered = Object.entries(metrics).sort((left, right) => kind === "strength" ? right[1] - left[1] : left[1] - right[1]);
+    const [name] = ordered[0] ?? ["unknown"];
+    return name;
+}
+function summarizeTopic(topic, simulations, traceLimit) {
+    const ranked = [...simulations].sort((left, right) => right.score - left.score);
+    return {
+        topic,
+        learnerCount: simulations.length,
+        meanScore: mean(simulations.map((entry) => entry.score)) * 100,
+        meanMasteryGain: mean(simulations.map((entry) => entry.masteryGain)),
+        meanRetention: mean(simulations.map((entry) => entry.retention)),
+        meanEngagement: mean(simulations.map((entry) => entry.engagement)),
+        meanTransfer: mean(simulations.map((entry) => entry.transfer)),
+        meanConfusion: mean(simulations.map((entry) => entry.confusion)),
+        topLearners: ranked.slice(0, traceLimit),
+        strugglingLearners: ranked.slice(-traceLimit).reverse(),
+        dominantStrength: classifyDominantSignal(simulations, "strength"),
+        dominantWeakness: classifyDominantSignal(simulations, "weakness")
+    };
+}
+export function runBenchmarkSuite(policy, focusTopic, seed = 20260401, traceLimit = 3) {
+    const topics = benchmarkTopics(focusTopic);
+    const topicTraces = [];
+    const topicBenchmarks = topics.map((topic, index) => {
+        const learners = buildLearnerPopulation(seed + index * 97, 18);
+        const simulations = learners.map((learner) => simulateTeaching(policy, topic, learner));
+        const summary = summarizeTopic(topic, simulations, traceLimit);
+        topicTraces.push({
+            topic: topic.title,
+            topLearners: summary.topLearners.map((entry) => ({
+                learnerId: entry.learner.id,
+                score: entry.score,
+                explanation: entry.explanation
+            })),
+            strugglingLearners: summary.strugglingLearners.map((entry) => ({
+                learnerId: entry.learner.id,
+                score: entry.score,
+                explanation: entry.explanation
+            })),
+            metricMeans: {
+                masteryGain: summary.meanMasteryGain,
+                retention: summary.meanRetention,
+                engagement: summary.meanEngagement,
+                transfer: summary.meanTransfer,
+                confusion: summary.meanConfusion
+            },
+            dominantStrength: summary.dominantStrength,
+            dominantWeakness: summary.dominantWeakness
+        });
+        return summary;
+    });
+    const weakest = [...topicBenchmarks].sort((left, right) => left.meanScore - right.meanScore)[0];
+    return {
+        policy,
+        suiteName: focusTopic ? `focused:${focusTopic}` : "core-suite",
+        topicBenchmarks,
+        overallScore: mean(topicBenchmarks.map((entry) => entry.meanScore)),
+        weakestTopic: weakest?.topic.title ?? "n/a",
+        trace: {
+            seed,
+            learnerCountPerTopic: 18,
+            topicTraces
+        }
+    };
+}
+export function benchmarkToMarkdown(result) {
+    const lines = [
+        `# Benchmark Report: ${result.policy.name}`,
+        "",
+        `- Suite: ${result.suiteName}`,
+        `- Overall score: ${result.overallScore.toFixed(2)}`,
+        `- Weakest topic: ${result.weakestTopic}`,
+        "",
+        "| Topic | Score | Mastery | Retention | Engagement | Transfer | Confusion |",
+        "| --- | ---: | ---: | ---: | ---: | ---: | ---: |"
+    ];
+    for (const benchmark of result.topicBenchmarks) {
+        lines.push(`| ${benchmark.topic.title} | ${benchmark.meanScore.toFixed(2)} | ${benchmark.meanMasteryGain.toFixed(2)} | ${benchmark.meanRetention.toFixed(2)} | ${benchmark.meanEngagement.toFixed(2)} | ${benchmark.meanTransfer.toFixed(2)} | ${benchmark.meanConfusion.toFixed(2)} |`);
+    }
+    lines.push("");
+    lines.push("## Interpretation");
+    lines.push("");
+    lines.push(`- The policy currently underperforms most on ${result.weakestTopic}, which is a useful anchor for mutation and curriculum repair.`);
+    lines.push("- Invariants tracked here favor durable learning signals: mastery, retention, engagement, transfer, and bounded confusion.");
+    lines.push("- Debug traces below explain which learners the policy helped most, where it struggled, and which signal dominated.");
+    lines.push("");
+    lines.push("## Debug Trace");
+    lines.push("");
+    for (const benchmark of result.topicBenchmarks) {
+        lines.push(`### ${benchmark.topic.title}`);
+        lines.push(`- Dominant strength: ${benchmark.dominantStrength}`);
+        lines.push(`- Dominant weakness: ${benchmark.dominantWeakness}`);
+        lines.push("- Top learners:");
+        for (const learner of benchmark.topLearners) {
+            lines.push(`  - ${learner.learner.id}: ${(learner.score * 100).toFixed(1)} because ${learner.explanation.join("; ")}`);
+        }
+        lines.push("- Struggling learners:");
+        for (const learner of benchmark.strugglingLearners) {
+            lines.push(`  - ${learner.learner.id}: ${(learner.score * 100).toFixed(1)} because ${learner.explanation.join("; ")}`);
+        }
+        lines.push("");
+    }
+    lines.push("");
+    return `${lines.join("\n")}\n`;
+}
+const BASE_WEIGHTS = {
+    masteryGain: 0.34,
+    retention: 0.20,
+    engagement: 0.16,
+    transfer: 0.18,
+    confusion: 0.18
+};
+export function applyFeedbackBias(feedback) {
+    if (feedback.sampleSize < 5)
+        return { ...BASE_WEIGHTS };
+    const weights = { ...BASE_WEIGHTS };
+    // High confusion from real users → increase confusion penalty weight
+    weights.confusion = clamp(weights.confusion + feedback.confusionRate * 0.08);
+    // High satisfaction → slightly increase engagement weight
+    weights.engagement = clamp(weights.engagement + feedback.satisfactionRate * 0.04);
+    // Renormalize positive weights to sum to ~0.88 (1 - confusion weight)
+    const positiveSum = weights.masteryGain + weights.retention + weights.engagement + weights.transfer;
+    const targetPositive = 1 - weights.confusion;
+    const scale = targetPositive / positiveSum;
+    weights.masteryGain *= scale;
+    weights.retention *= scale;
+    weights.engagement *= scale;
+    weights.transfer *= scale;
+    return weights;
+}

package/dist/src/core/config.js

@@ -0,0 +1,81 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+export const DEFAULT_KEATING_CONFIG = {
+    pi: {
+        runtimePreference: "standalone-only",
+        defaultProvider: "google",
+        defaultModel: "google/gemini-2.5-pro",
+        defaultThinking: "medium"
+    },
+    debug: {
+        persistTraces: true,
+        traceTopLearners: 3,
+        consoleSummary: true
+    }
+};
+export function configPath(cwd) {
+    return resolve(cwd, "keating.config.json");
+}
+function sanitizeRuntimePreference(value) {
+    if (value === "standalone-only" || value === "prefer-standalone" || value === "embedded-only") {
+        return value;
+    }
+    return DEFAULT_KEATING_CONFIG.pi.runtimePreference;
+}
+function sanitizeOptionalString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+export async function loadKeatingConfig(cwd) {
+    const path = configPath(cwd);
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        return {
+            pi: {
+                runtimePreference: sanitizeRuntimePreference(parsed.pi?.runtimePreference),
+                defaultProvider: sanitizeOptionalString(parsed.pi?.defaultProvider) ?? DEFAULT_KEATING_CONFIG.pi.defaultProvider,
+                defaultModel: sanitizeOptionalString(parsed.pi?.defaultModel) ?? DEFAULT_KEATING_CONFIG.pi.defaultModel,
+                defaultThinking: sanitizeOptionalString(parsed.pi?.defaultThinking) ?? DEFAULT_KEATING_CONFIG.pi.defaultThinking
+            },
+            debug: {
+                persistTraces: typeof parsed.debug?.persistTraces === "boolean"
+                    ? parsed.debug.persistTraces
+                    : DEFAULT_KEATING_CONFIG.debug.persistTraces,
+                traceTopLearners: typeof parsed.debug?.traceTopLearners === "number" && parsed.debug.traceTopLearners > 0
+                    ? Math.round(parsed.debug.traceTopLearners)
+                    : DEFAULT_KEATING_CONFIG.debug.traceTopLearners,
+                consoleSummary: typeof parsed.debug?.consoleSummary === "boolean"
+                    ? parsed.debug.consoleSummary
+                    : DEFAULT_KEATING_CONFIG.debug.consoleSummary
+            }
+        };
+    }
+    catch {
+        return DEFAULT_KEATING_CONFIG;
+    }
+}
+export async function ensureConfig(cwd) {
+    const path = configPath(cwd);
+    if (!existsSync(path)) {
+        await writeFile(path, `${JSON.stringify(DEFAULT_KEATING_CONFIG, null, 2)}\n`, "utf8");
+    }
+}
+export function mergePiDefaults(config, args) {
+    const merged = [...args];
+    const hasProvider = merged.includes("--provider");
+    const hasModel = merged.includes("--model");
+    const hasThinking = merged.includes("--thinking");
+    if (!hasProvider && config.pi.defaultProvider) {
+        merged.unshift(config.pi.defaultProvider);
+        merged.unshift("--provider");
+    }
+    if (!hasModel && config.pi.defaultModel) {
+        merged.unshift(config.pi.defaultModel);
+        merged.unshift("--model");
+    }
+    if (!hasThinking && config.pi.defaultThinking) {
+        merged.unshift(config.pi.defaultThinking);
+        merged.unshift("--thinking");
+    }
+    return merged;
+}