@interleavelove/keating 0.1.0

package/dist/test/hyperteacher-extension.test.js

@@ -0,0 +1,122 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { ensureProjectScaffold } from "../src/core/project.js";
+import hyperteacher from "../src/pi/hyperteacher-extension.js";
+function createMockPi() {
+    const commands = new Map();
+    const events = new Map();
+    return {
+        commands,
+        events,
+        registerCommand(name, cmd) {
+            commands.set(name, cmd);
+        },
+        on(event, handler) {
+            events.set(event, handler);
+        }
+    };
+}
+function createMockCtx(cwd) {
+    const notifications = [];
+    let editorText = "";
+    return {
+        cwd,
+        notifications,
+        get editorText() {
+            return editorText;
+        },
+        ui: {
+            notify(message, level) {
+                notifications.push({ message, level });
+            },
+            setEditorText(text) {
+                editorText = text;
+            },
+            async select(_title, options) {
+                return options[0] ?? "";
+            }
+        }
+    };
+}
+async function setup() {
+    const cwd = await mkdtemp(join(tmpdir(), "keating-ext-"));
+    await ensureProjectScaffold(cwd);
+    const pi = createMockPi();
+    hyperteacher(pi);
+    const ctx = createMockCtx(cwd);
+    return { cwd, pi, ctx };
+}
+test("/plan with string arg produces notification", async () => {
+    const { pi, ctx } = await setup();
+    await pi.commands.get("plan").handler("derivative", ctx);
+    assert.ok(ctx.notifications.some((n) => n.message.includes("derivative")));
+    assert.ok(ctx.editorText.length > 0);
+});
+test("/plan with array arg joins words", async () => {
+    const { pi, ctx } = await setup();
+    await pi.commands.get("plan").handler(["bayes", "rule"], ctx);
+    assert.ok(ctx.notifications.some((n) => n.message.includes("bayes")));
+});
+test("/plan with empty string shows usage", async () => {
+    const { pi, ctx } = await setup();
+    await pi.commands.get("plan").handler("", ctx);
+    assert.ok(ctx.notifications[0].message.includes("Usage"));
+});
+test("/plan with empty array shows usage", async () => {
+    const { pi, ctx } = await setup();
+    await pi.commands.get("plan").handler([], ctx);
+    assert.ok(ctx.notifications[0].message.includes("Usage"));
+});
+test("/map with string arg produces map", async () => {
+    const { pi, ctx } = await setup();
+    await pi.commands.get("map").handler("derivative", ctx);
+    assert.ok(ctx.notifications.some((n) => n.message.includes("Generated")));
+});
+test("/animate with string arg produces animation", async () => {
+    const { pi, ctx } = await setup();
+    await pi.commands.get("animate").handler("entropy", ctx);
+    assert.ok(ctx.notifications.some((n) => n.message.includes("Generated")));
+});
+test("/verify with string arg produces checklist", async () => {
+    const { pi, ctx } = await setup();
+    await pi.commands.get("verify").handler("derivative", ctx);
+    assert.ok(ctx.notifications.some((n) => n.message.includes("checklist")));
+});
+test("/verify with empty arg shows usage", async () => {
+    const { pi, ctx } = await setup();
+    await pi.commands.get("verify").handler("", ctx);
+    assert.ok(ctx.notifications[0].message.includes("Usage"));
+});
+test("/feedback records signal", async () => {
+    const { pi, ctx } = await setup();
+    await pi.commands.get("feedback").handler("up derivative", ctx);
+    assert.ok(ctx.notifications.some((n) => n.message.includes("thumbs-up")));
+});
+test("/feedback with invalid signal shows usage", async () => {
+    const { pi, ctx } = await setup();
+    await pi.commands.get("feedback").handler("", ctx);
+    assert.ok(ctx.notifications[0].message.includes("Usage"));
+});
+test("/bench with empty args runs suite", async () => {
+    const { pi, ctx } = await setup();
+    await pi.commands.get("bench").handler("", ctx);
+    assert.ok(ctx.notifications.some((n) => n.message.includes("Benchmark score")));
+});
+test("/policy shows current policy", async () => {
+    const { pi, ctx } = await setup();
+    await pi.commands.get("policy").handler("", ctx);
+    assert.ok(ctx.editorText.includes("Policy:"));
+});
+test("/trace with empty args works", async () => {
+    const { pi, ctx } = await setup();
+    await pi.commands.get("trace").handler("", ctx);
+    assert.ok(ctx.notifications.length > 0);
+});
+test("session_start event fires notification", async () => {
+    const { pi, ctx } = await setup();
+    await pi.events.get("session_start")({}, ctx);
+    assert.ok(ctx.notifications.some((n) => n.message.includes("Keating loaded")));
+});

package/dist/test/lesson-plan.test.js

@@ -0,0 +1,35 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildLessonPlan, lessonPlanToMarkdown } from "../src/core/lesson-plan.js";
+import { DEFAULT_POLICY, clampPolicy } from "../src/core/policy.js";
+import { Prng } from "../src/core/random.js";
+test("lesson plans preserve phase order and non-empty bullets across randomized policies", () => {
+    const prng = new Prng(42);
+    const topics = ["derivative", "entropy", "bayes", "falsifiability", "stoicism", "complex systems"];
+    for (let index = 0; index < 100; index += 1) {
+        const policy = clampPolicy({
+            ...DEFAULT_POLICY,
+            name: `policy-${index}`,
+            analogyDensity: prng.next(),
+            socraticRatio: prng.next(),
+            formalism: prng.next(),
+            retrievalPractice: prng.next(),
+            exerciseCount: prng.int(1, 5),
+            diagramBias: prng.next(),
+            reflectionBias: prng.next(),
+            interdisciplinaryBias: prng.next(),
+            challengeRate: prng.next()
+        });
+        const plan = buildLessonPlan(prng.pick(topics), policy);
+        assert.equal(plan.phases[0]?.title, "Orientation");
+        assert.equal(plan.phases.at(-1)?.title, "Transfer and Reflection");
+        assert.ok(plan.phases.some((phase) => phase.title === "Guided Practice"));
+        for (const phase of plan.phases) {
+            assert.ok(phase.bullets.length > 0);
+            for (const bullet of phase.bullets) {
+                assert.ok(bullet.length > 5);
+            }
+        }
+        assert.ok(lessonPlanToMarkdown(plan).includes(`# Lesson Plan: ${plan.topic.title}`));
+    }
+});

package/dist/test/pipeline.test.js

@@ -0,0 +1,57 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { access, mkdtemp, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { configPath } from "../src/core/config.js";
+import { animateTopicArtifact, benchPolicyArtifact, currentPolicySummary, ensureProjectScaffold, evolvePolicyArtifact, evolvePromptArtifact, listArtifacts, mapTopicArtifact, planTopicArtifact } from "../src/core/project.js";
+test("acceptance pipeline creates plans, maps, animations, benchmark reports, and evolved policy state", async () => {
+    const workdir = await mkdtemp(join(tmpdir(), "keating-pipeline-"));
+    await ensureProjectScaffold(workdir);
+    await mkdir(join(workdir, "pi", "prompts"), { recursive: true });
+    await writeFile(join(workdir, "pi", "prompts", "learn.md"), `---
+description: Teach a concept adaptively with a mastery-first lesson loop.
+---
+Teach the learner the following topic: $@
+
+Workflow:
+1. Start with a diagnostic question or assumption check.
+2. Give at least one worked example.
+3. Ask for retrieval or reconstruction, not just agreement.
+`);
+    const plan = await planTopicArtifact(workdir, "derivative");
+    const map = await mapTopicArtifact(workdir, "derivative");
+    const animation = await animateTopicArtifact(workdir, "derivative");
+    const bench = await benchPolicyArtifact(workdir, "derivative");
+    const evolution = await evolvePolicyArtifact(workdir, "derivative");
+    const promptEvolution = await evolvePromptArtifact(workdir, "learn");
+    await access(plan.planPath);
+    await access(map.mmdPath);
+    await access(animation.playerPath);
+    await access(animation.scenePath);
+    await access(animation.storyboardPath);
+    await access(animation.manifestPath);
+    await access(bench.reportPath);
+    await access(bench.tracePath);
+    await access(evolution.reportPath);
+    await access(evolution.tracePath);
+    await access(evolution.policyPath);
+    await access(promptEvolution.reportPath);
+    await access(promptEvolution.evolvedPromptPath);
+    await access(configPath(workdir));
+    const summary = await currentPolicySummary(workdir);
+    const report = await readFile(bench.reportPath, "utf8");
+    const trace = await readFile(evolution.tracePath, "utf8");
+    const storyboard = await readFile(animation.storyboardPath, "utf8");
+    const manifest = await readFile(animation.manifestPath, "utf8");
+    const promptReport = await readFile(promptEvolution.reportPath, "utf8");
+    const artifacts = await listArtifacts(workdir);
+    assert.ok(summary.includes("Policy:"));
+    assert.ok(report.includes("# Benchmark Report"));
+    assert.ok(trace.includes("\"decision\""));
+    assert.ok(storyboard.includes("# Animation Storyboard: Derivative"));
+    assert.ok(manifest.includes("\"sceneKind\": \"function-graph\""));
+    assert.ok(promptReport.includes("# Prompt Evolution Report: learn"));
+    assert.ok(artifacts.some((artifact) => artifact.path.endsWith("animations/derivative/player.html")));
+    assert.ok(artifacts.some((artifact) => artifact.path.endsWith("prompt-evolution/learn.evolved.md")));
+});

package/dist/test/prompt-evolution.test.js

@@ -0,0 +1,89 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { prosperStyleWinner, evolvePrompt } from "../src/core/prompt-evolution.js";
+import { ensureProjectScaffold } from "../src/core/project.js";
+async function mockEvaluator(_cwd, promptPath, prompt) {
+    const isGood = prompt.includes("own voice");
+    return {
+        promptPath,
+        promptName: "learn",
+        score: isGood ? 90 : 50,
+        objectives: {
+            voice_divergence: isGood ? 1 : 0.2,
+            diagnosis: 0.5,
+            verification: 0.5,
+            retrieval: 0.5,
+            transfer: 0.5,
+            structure: 0.5
+        },
+        feedback: isGood ? [] : ["Add voice"]
+    };
+}
+async function mockGenerator(_cwd, basePrompt, _evaluation, _iteration) {
+    return basePrompt + "\nHelp the learner find their own voice.";
+}
+test("PROSPER-style winner prefers candidates that win across multiple objectives", () => {
+    const candidates = [
+        {
+            iteration: 1,
+            label: "narrow",
+            prompt: "narrow",
+            parentLabel: "learn",
+            accepted: false,
+            preferenceScore: 0,
+            evaluation: {
+                promptPath: "learn.md",
+                promptName: "learn",
+                score: 78,
+                objectives: {
+                    voice_divergence: 1,
+                    diagnosis: 0.2,
+                    verification: 0.2,
+                    retrieval: 0.2,
+                    transfer: 0.2,
+                    structure: 1
+                },
+                feedback: []
+            }
+        },
+        {
+            iteration: 2,
+            label: "balanced",
+            prompt: "balanced",
+            parentLabel: "learn",
+            accepted: false,
+            preferenceScore: 0,
+            evaluation: {
+                promptPath: "learn.md",
+                promptName: "learn",
+                score: 84,
+                objectives: {
+                    voice_divergence: 0.8,
+                    diagnosis: 0.8,
+                    verification: 0.8,
+                    retrieval: 0.8,
+                    transfer: 0.8,
+                    structure: 0.8
+                },
+                feedback: []
+            }
+        }
+    ];
+    const winner = prosperStyleWinner(candidates);
+    assert.equal(winner.label, "balanced");
+    assert.ok(winner.preferenceScore > candidates[0].preferenceScore);
+});
+test("prompt evolution works with mocked LLM calls", async () => {
+    const workdir = await mkdtemp(join(tmpdir(), "keating-prompt-evolution-mock-"));
+    await ensureProjectScaffold(workdir);
+    await mkdir(join(workdir, "pi", "prompts"), { recursive: true });
+    await writeFile(join(workdir, "pi", "prompts", "learn.md"), "Teach the topic.");
+    const run = await evolvePrompt(workdir, "learn", 2, mockEvaluator, mockGenerator);
+    assert.ok(run.baseline.score < run.best.evaluation.score);
+    assert.ok(run.best.prompt.includes("own voice"));
+    assert.equal(run.exploredCandidates.length, 2);
+    assert.ok(run.best.accepted);
+});

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@interleavelove/keating",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A Pi-powered hyperteacher package with self-improving teaching policies, lesson maps, and animated visual teaching artifacts.",
+  "keywords": [
+    "pi-package",
+    "hyperteacher",
+    "education",
+    "feynman-style",
+    "teaching-agent",
+    "ai-education",
+    "cognitive-empowerment"
+  ],
+  "author": "Diogenes of Toronto",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Diogenesoftoronto/keating.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Diogenesoftoronto/keating/issues"
+  },
+  "homepage": "https://keating.help",
+  "bin": {
+    "keating": "./bin/keating.js"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "pi/",
+    "scripts/install/"
+  ],
+  "pi": {
+    "extensions": [
+      "./dist/src/pi"
+    ],
+    "skills": [
+      "./pi/skills"
+    ],
+    "prompts": [
+      "./pi/prompts"
+    ]
+  },
+  "scripts": {
+    "build": "bun x tsc -p tsconfig.json",
+    "test": "bun test ./test/*.test.ts",
+    "prepack": "bun x tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@google/generative-ai": "^0.24.1",
+    "dotenv": "^17.4.0",
+    "manim-web": "^0.3.16"
+  }
+}

package/pi/prompts/bridge.md

@@ -0,0 +1,14 @@
+---
+description: Bridge a concept across domains including science, math, philosophy, code, law, history, psychology, medicine, arts, and politics so the learner sees what transfers and what does not.
+args: <topic>
+section: Teaching Workflows
+topLevelCli: true
+---
+Bridge the following concept across domains: $@
+
+Structure:
+
+1. Define the core invariant idea.
+2. Show how that idea appears in at least two domains.
+3. Point out where the analogy stops working.
+4. End with a transfer question for the learner.

package/pi/prompts/diagnose.md

@@ -0,0 +1,15 @@
+---
+description: Diagnose what a learner already understands, where they are confused, and what to teach next.
+args: <topic>
+section: Teaching Workflows
+topLevelCli: true
+---
+Diagnose the learner's current state on: $@
+
+Requirements:
+
+0. If `.keating/state/learner.json` exists, read the learner's identified misconceptions and mastery estimates before asking diagnostic questions. Use prior state to focus your questions.
+1. Ask at most three high-information questions before explaining.
+2. Infer likely misconceptions from the answers.
+3. Separate "missing prerequisite", "partial intuition", and "formal gap".
+4. End with a proposed next teaching step, not a full lecture.

package/pi/prompts/improve.md

@@ -0,0 +1,39 @@
+---
+description: Run the self-improvement loop — diagnose benchmark weaknesses and propose code changes.
+args: [history]
+section: Meta-Evolution
+topLevelCli: true
+---
+Run the Keating self-improvement pipeline.
+
+If the argument is "history", show the improvement attempt archive:
+- Run `/improve history` and display the result.
+
+Otherwise, generate a new improvement proposal:
+
+1. Run `/improve` to diagnose benchmark weaknesses and generate a proposal.
+2. Read the proposal file under `.keating/outputs/improvements/`.
+3. The proposal contains:
+   - A ranked list of diagnosed weaknesses (from benchmark traces).
+   - Specific target files that may be modified.
+   - Structured instructions for what to change and why.
+   - Safety rules: which files are mutable vs immutable.
+
+4. Execute the proposed changes:
+   - Only modify files listed in the proposal's `targets`.
+   - Never modify: `self-improve.ts`, `types.ts`, `config.ts`, `paths.ts`, `random.ts`.
+   - Before each edit, explain what you are changing and why.
+   - Keep changes minimal and focused on the diagnosed weakness.
+
+5. After making changes, run the benchmark to evaluate:
+   - `keating bench` to get the new score.
+   - Compare against the before-score in the proposal.
+   - If the score improved or held steady, the change is accepted.
+   - If the score dropped, revert your changes.
+
+6. Report the outcome: what changed, before/after scores, and whether the change was kept or rolled back.
+
+Safety contract:
+- The self-improvement loop modifies teaching logic (lesson plans, benchmark weights, animations, topic definitions, maps, policy defaults).
+- It never modifies the improvement engine itself, type definitions, configuration, or the random seed system.
+- Every attempt is archived with snapshots so changes can always be rolled back.

package/pi/prompts/learn.md

@@ -0,0 +1,21 @@
+---
+description: Teach a concept adaptively with a mastery-first lesson loop.
+args: <topic>
+section: Teaching Workflows
+topLevelCli: true
+---
+Teach the learner the following topic: $@
+
+Workflow:
+
+0. Before teaching, check `.keating/outputs/verifications/` for this topic. If no verification checklist exists, run `/verify <topic>` first. Do not present unverified factual claims as settled truth.
+0b. Check `.keating/state/learner.json` for prior coverage of this topic. If the learner has seen it before, skip orientation and go straight to retrieval practice or misconception repair.
+1. Start with a short diagnostic question or assumption check.
+2. Move through intuition before formal structure.
+3. Repair the likeliest misconception explicitly.
+4. Give at least one worked example.
+5. Ask for retrieval or reconstruction, not just agreement.
+6. End by bridging the topic to another domain or a practical consequence.
+
+If a matching Keating artifact already exists under `.keating/outputs/plans/` or `.keating/outputs/maps/`, read it and use it.
+If it does not exist and a structured lesson would help, tell the user to run `/plan <topic>` or `/map <topic>`.

package/pi/prompts/quiz.md

@@ -0,0 +1,14 @@
+---
+description: Quiz a learner on a topic with feedback that reveals misconceptions instead of just scoring answers.
+args: <topic>
+section: Teaching Workflows
+topLevelCli: true
+---
+Run a short mastery quiz on: $@
+
+Rules:
+
+1. Ask one question at a time.
+2. Mix recall, transfer, and misconception-revealing prompts.
+3. After each answer, say what the answer shows about understanding.
+4. If the learner misses something, teach the minimum needed correction before continuing.

package/pi/skills/adaptive-teaching/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: adaptive-teaching
+description: Use when the user wants to learn, be taught, be quizzed, or understand an idea across any domain — science, math, philosophy, code, law, politics, psychology, medicine, arts, or history — with active scaffolding.
+---
+
+# Adaptive Teaching
+
+Use this skill when the user asks to learn a concept rather than merely receive a summary.
+
+## Teaching Contract
+
+1. Diagnose first if the learner state is unknown. Check `.keating/state/learner.json` for prior coverage.
+2. Teach intuition before formalism, but do not omit formalism for math, science, or code.
+3. Surface one misconception early.
+4. Use retrieval and reconstruction prompts, not just exposition.
+5. End with transfer, reflection, or a next challenge.
+6. Verify factual claims before teaching. If `.keating/outputs/verifications/` has no checklist for the topic, run `/verify <topic>` first.
+
+## Keating Artifacts
+
+- If a lesson plan would help, tell the user to run `/plan <topic>`.
+- If a concept map would help, tell the user to run `/map <topic>`.
+- If an animation would help, tell the user to run `/animate <topic>`.
+- If they want to verify facts first, tell the user to run `/verify <topic>`.
+- If they want the teacher to improve, tell the user to run `/bench [topic]` and `/evolve [topic]`.
+- If they want to give feedback, tell the user to run `/feedback <up|down|confused> [topic]`.
+
+## Red Flags
+
+- Do not drown the learner in formal language before a concrete hook exists.
+- Do not act as though the synthetic benchmark proves pedagogical truth.
+- Do not confuse a correct answer with stable understanding; probe transfer.
+- Do not present unverified factual claims as settled truth. If verification artifacts exist, consult them. If claims are flagged as unconfirmed, hedge appropriately.