keating 0.3.6

package/README.md

@@ -0,0 +1,334 @@
+# Keating
+
+> "O me! O life! of the questions of these recurring,
+> Of the endless trains of the faithless, of cities fill’d with the foolish,
+> Of myself for ever reproaching myself, (for who more foolish than I, and who more faithless?)
+> Of eyes that vainly crave the light, of the objects mean, of the struggle ever renew’d,
+> Of the poor results of all, of the plodding and sordid crowds I see around me,
+> Of the empty and useless years of the rest, with the rest me intertwined,
+> The question, O me! so sad, recurring—What good amid these, O me, O life?
+>
+> Answer.
+> That you are here—that life exists and identity,
+> That the powerful play goes on, and you may contribute a verse."
+> -- Walt Whitman, *Leaves of Grass*
+
+Keating exists because as AI grows more capable, the risk is not just that it replaces our tasks, but that it replaces our *voice*. We must not let technology become a surrogate for thought. 
+
+**The goal of Keating is cognitive empowerment.** It is a Pi-powered hyperteacher scaffold designed to ensure that humans remain the authors of their own understanding. It uses the most advanced models not to provide answers, but to force the rigorous reconstruction of ideas within the learner's own identity.
+
+We use technology to ensure the "powerful play" goes on, and that every learner is equipped to contribute their own verse.
+
+It is designed around five influences:
+
+- `feynman` for the shell ergonomics, slash workflows, and artifact-oriented research UX.
+- `pi-mono` for the runtime model: prompts, skills, and extensions instead of a forked monolith.
+- `chrysalis-forge` for self-evolution, archival evaluation, and safety-gated improvement.
+- `HyperAgent` for role separation between planning, execution, and verification.
+- `Meta-Harness` for harness-level improvement rather than prompt-only tweaking.
+
+## What Exists
+
+- A Pi launcher that prefers a fresh standalone `pi` install by default and only uses the bundled Feynman runtime when you explicitly allow it.
+- A Pi extension with operational commands: `/plan`, `/map`, `/animate`, `/verify`, `/bench`, `/evolve`, `/prompt-evolve`, `/feedback`, `/policy`, `/outputs`, `/trace`.
+- Teaching workflows as prompt templates: `/learn`, `/diagnose`, `/quiz`, `/bridge`.
+- An optional speech module that exposes a `keating_voice` tool for short voice-tagged learner-facing utterances while the normal model keeps doing reasoning, questioning, verification, and tool-backed correction.
+- A prompt-evolution loop that scores prompt templates with natural-language feedback and picks revisions with a PROSPER-style multi-objective selector.
+- 12 domains: math, science, philosophy, code, law, politics, psychology, medicine, arts, history, and general.
+- Deterministic artifacts under `.keating/`:
+  - lesson plans with domain-specific guidance (code gets live-code phases, law gets case citations, etc.)
+  - richer Mermaid meaning maps rendered through `oxdraw`
+  - self-contained `manim-web` animation bundles: function-graphs, distribution-bars, belief-updates, code-traces, timelines, case-diagrams, mind-maps, and concept-cards
+  - fact-checking verification checklists that must be completed before teaching
+  - benchmark reports
+  - evolution reports
+  - prompt-evolution reports and evolved prompt snapshots
+  - the current policy and policy archive
+  - persistent learner state and feedback signals
+- Persisted traces that explain why benchmark runs and evolution candidates succeeded or failed.
+- A test suite with property checks, fuzz-style inputs, and an end-to-end acceptance pipeline.
+
+## Quick Start
+
+### From the Web
+
+Visit **[keating.help](https://keating.help)** to use Keating directly in your browser with:
+- Your own API keys (stored locally)
+- Local model inference via WebGPU (Gemma 4 E4B)
+- Optional Gemini 3.1 Flash Live speech from the speaker button in the chat header
+- Full hyperteacher experience without installation
+
+### From the Command Line
+
+Install via curl:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Diogenesoftoronto/keating/main/scripts/install/install.sh | bash
+```
+
+Or with npm/pnpm/bun:
+
+```bash
+npm install -g keating
+pnpm add -g keating
+bun add -g keating
+```
+
+Then launch the shell:
+
+```bash
+keating shell
+```
+
+For a guided local setup:
+
+```bash
+keating setup
+keating doctor
+keating shell
+```
+
+The setup screen uses an Ink-powered terminal UI with arrow-key choices for provider, model, thinking effort, and runtime preference. Choose the recommended default path for `google` + `gemini-3.1-pro-preview`, or select custom provider/model values when your Pi runtime supports them.
+
+Non-interactive environments can write the default config with `keating setup --yes`.
+
+Keating checks credentials before launching the shell. It tries the configured provider first, then falls back to configured OpenAI or Anthropic credentials when the default Google key is missing. Supported environment variables are:
+
+```bash
+export GEMINI_API_KEY=...
+export OPENAI_API_KEY=...
+export ANTHROPIC_API_KEY=...
+```
+
+From a local checkout, build first and run the repo binary directly:
+
+```bash
+bun run build
+node ./bin/keating.js shell
+```
+
+The executable form works too:
+
+```bash
+./bin/keating.js shell
+```
+
+### Development
+
+<video src="docs/assets/doctor.mp4" autoplay loop muted width="100%"></video>
+
+```bash
+mise run build
+mise run doctor
+mise run docs:diagrams
+mise run bench
+mise run evolve
+mise run prompt-evolve -- learn
+mise run map -- derivative
+mise run animate -- derivative
+mise run trace
+mise run shell
+```
+
+Keating reads runtime/model defaults from `keating.config.json`.
+
+```json
+{
+  "pi": {
+    "runtimePreference": "standalone-only",
+    "defaultProvider": "google",
+    "defaultModel": "gemini-3.1-pro-preview",
+    "defaultThinking": "medium"
+  },
+  "speech": {
+    "enabled": false,
+    "defaultVoice": "conversational",
+    "fastModel": "gemini-3.1-flash-tts-preview",
+    "steeringModel": "default"
+  },
+  "debug": {
+    "persistTraces": true,
+    "traceTopLearners": 3,
+    "consoleSummary": false
+  }
+}
+```
+
+`runtimePreference` supports:
+
+- `standalone-only`
+- `prefer-standalone`
+- `embedded-only`
+
+`keating --list-models` is passed through to the underlying Pi shell runtime. The legacy typo `keating --list-model` is accepted as an alias for the same runtime flag.
+
+The speech module is disabled by default. When `speech.enabled` is `true`, Keating registers a Pi tool named `keating_voice`. The tool returns transcript-safe voice tags such as:
+
+```text
+[voice voice=conversational tags=question,verify pace=normal affect=curious] What would you expect to happen next?
+```
+
+In the Pi shell, this first layer is provider-neutral: `fastModel` names the intended fast conversational voice path, and `steeringModel` names the supervising model path, but the tool emits structured voice-tagged utterances rather than audio. That keeps the speech loop optional while preserving the normal tool-using teacher as the source of questions, verification, and corrections.
+
+In the web app, the speech toggle registers the same `keating_voice` tool and routes it through Gemini 3.1 Flash Live (`gemini-3.1-flash-live-preview`) with audio output. Speech stays off by default, uses the Google API key from Settings, and should be used for short conversational delivery while the primary model continues to plan, verify, and steer the lesson.
+
+Inside the Pi shell:
+
+```text
+/plan derivative
+/map derivative
+/animate derivative
+/verify derivative
+/learn derivative
+/quiz derivative
+/bench derivative
+/evolve derivative
+/prompt-evolve learn
+/feedback up derivative
+/speech
+/trace derivative
+/outputs
+```
+
+## Prompt Evolution
+
+`prompt-evolve` does not silently rewrite the checked-in prompt template. It reads a source prompt such as `pi/prompts/learn.md`, scores it on teaching objectives like learner voice, diagnosis, verification, retrieval, transfer, and structure, then writes:
+
+- `.keating/outputs/prompt-evolution/learn.md`
+- `.keating/outputs/prompt-evolution/learn.evolved.md`
+
+Example:
+
+Before:
+
+```md
+Teach the learner the following topic: $@
+
+Workflow:
+1. Start with a short diagnostic question.
+2. Explain the concept.
+3. End with a summary.
+```
+
+After `mise run prompt-evolve -- learn`:
+
+```md
+Teach the learner the following topic: $@
+
+Workflow:
+1. Start with a short diagnostic question.
+1a. Separate missing prerequisite, partial intuition, and formal gap before choosing the next move.
+2. Explain the concept.
+5a. Make the learner reconstruct the core idea from memory rather than merely agreeing with your explanation.
+6a. Ask the learner to carry the idea into a new setting so they prove they can transfer it.
+0c. Keep Keating's standard in view: "Boys, you must strive to find your own voice..."
+```
+
+The point is not cosmetic prompt churn or benchmark gaming. The loop tries to produce prompts that improve human learning outcomes: sharper diagnosis, stronger reconstruction from memory, better transfer, and clearer learner articulation.
+
+## Benchmarking Cognitive Friction
+
+To ensure that Keating serves as a bridge to independent understanding rather than a shortcut to agreement, we maintain a **Synthetic Learner Suite**. 
+
+Recent results using small models (1–2B parameters) show that the system successfully identifies and redirects "Surface Agreement." Key findings include:
+- **Redirection Effectiveness:** Identifying meta-responses ("That's a great question!") and insisting on personal application before advancing.
+- **Intuition-First Efficacy:** Measurable self-correction in technical domains (e.g., correcting conflations between function values and derivatives).
+- **Voice Persistence:** Penalizing rote echoing of the teacher and rewarding novel analogies or domain transfers.
+
+Detailed results are available in our latest study: `docs/study.typ`.
+
+## Project Layout
+
+- `src/core/`: lesson planning, benchmarks, policy mutation, artifact helpers.
+- `src/core/animation.ts`: `manim-web` bundle generation for visual teaching artifacts.
+- `src/runtime/`: Pi/Feynman runtime detection and shell launcher.
+- `src/pi/`: the compiled Pi extension entrypoint.
+- `pi/prompts/`: teaching prompt templates.
+- `pi/skills/`: teaching skills for the runtime.
+- `docs/`: architecture, testing strategy, and diagrams.
+
+Key docs:
+
+- `docs/ARCHITECTURE.md`
+- `docs/OXDRAW-TUTORIAL.md`
+- `docs/VISUAL-ARCHITECTURE.md`
+
+## Design Notes
+
+The system deliberately separates:
+
+- live teaching behavior, which stays in Pi prompts and skills,
+- deterministic pedagogy artifacts, which are generated by local code and kept inspectable,
+- self-improvement, which runs against a synthetic learner suite before policy changes are accepted.
+
+That split keeps the interactive shell flexible while making the improvement loop testable without an LLM in the loop.
+
+## Testing
+
+<video src="docs/assets/tests.mp4" autoplay loop muted width="100%"></video>
+
+```bash
+mise run test
+```
+
+The test suite covers:
+- property checks for lesson plans and maps
+- fuzzed teaching policies and topics
+- visual grammar invariants for animations
+- end-to-end artifact generation and trace persistence
+
+## Visual Teaching Layer
+
+Keating now treats diagrams and animations as first-class teaching artifacts instead of optional garnish.
+
+- `mise run map -- <topic>` writes a meaning map with teaching loop, concept structure, misconceptions, practice, and transfer hooks, then renders it with `oxdraw` when available.
+- `mise run animate -- <topic>` writes a browser-runnable `manim-web` bundle under `.keating/outputs/animations/<topic>/`.
+- Each animation bundle includes:
+  - `player.html`
+  - `scene.mjs`
+  - `storyboard.md`
+  - `manifest.json`
+- The animation manifest explains why a particular scene grammar was selected, so the visual layer is inspectable alongside benchmark and evolution traces.
+
+## Debugging Self-Evolution
+
+Keating persists detailed trace artifacts under `.keating/outputs/traces/`.
+
+- Benchmark traces show:
+  - per-topic metric means
+  - the strongest and weakest synthetic learners
+  - natural-language reasons for strong or weak outcomes
+- Evolution traces show:
+  - every explored candidate
+  - score and weakest-topic deltas
+  - novelty scores
+  - gate outcomes
+  - acceptance or rejection reasons
+  - parameter deltas from the parent policy
+- Prompt-evolution artifacts show:
+  - baseline feedback on the source prompt
+  - candidate objective vectors
+  - the PROSPER-style preference score
+  - the recommended evolved prompt snapshot
+
+Useful commands:
+
+```bash
+mise run doctor
+mise run bench -- derivative
+mise run evolve -- derivative
+mise run prompt-evolve -- learn
+mise run trace -- derivative
+```
+
+## Documentation
+
+- Architecture overview: `docs/ARCHITECTURE.md`
+- Visual system architecture: `docs/VISUAL-ARCHITECTURE.md`
+- `oxdraw` authoring and rendering tutorial: `docs/OXDRAW-TUTORIAL.md`
+
+Regenerate the checked-in docs SVGs with:
+
+```bash
+mise run docs:diagrams
+```

package/SYSTEM.md

@@ -0,0 +1,33 @@
+You are Keating, a hyperteacher dedicated to the preservation of the human voice through cognitive empowerment.
+
+Core Mandate: 
+AI must not be a surrogate for thought. Your purpose is to ensure the learner does not merely offload their thinking to the machine, but instead uses this bridge to find their own identity and "contribute a verse" to the powerful play of human knowledge.
+
+Core rules:
+
+1. Teach for mastery, not for surface agreement. If the learner merely agrees, you have failed.
+2. Push the learner to articulate ideas in their own words. "Identity exists; the powerful play goes on."
+3. Use a loop of diagnose -> intuition -> formal core -> misconception repair -> example -> retrieval -> reflection.
+4. Keep the learner active with short questions, predictions, or reconstructions. 
+5. Technology is a scaffold, not a destination. Use artifacts (.keating/outputs/) to anchor the human voice.
+6. If `.keating/outputs/plans/<topic>.md` or `.keating/outputs/maps/<topic>.mmd` exists, read and use it. If no plan exists and teaching would benefit from structure, run `/plan <topic>` yourself.
+7. If the user wants a stronger lesson structure, run `/plan <topic>` or `/map <topic>` yourself rather than asking them to do it.
+8. If the user wants the teacher to improve, run `/bench [topic]` or `/evolve [topic]` yourself rather than asking them to do it.
+9. You are an autonomous agent with direct access to tools. NEVER ask the user to run commands for you. If you need a plan, call the plan tool. If you need verification, call the verify tool. If you need a map, call the map tool. Execute all prerequisites yourself without asking.
+10. When a topic is mathematical, do not hide the formalism forever; sequence into it.
+11. When a topic is philosophical, surface competing interpretations and where the concept breaks.
+12. When a topic is scientific, tie the idea to prediction, measurement, or model behavior.
+13. When a topic is about code, include runnable examples and step-by-step traces. Do not teach programming concepts without executable illustration.
+14. When a topic is legal, cite relevant cases or statutes. Distinguish jurisdiction-specific rules from general principles.
+15. When a topic is medical, reference the level of evidence. Distinguish clinical guidelines from individual studies.
+16. When a topic is historical, anchor claims in primary sources and timelines. Surface historiographic disagreements.
+17. When a topic is psychological, flag replication status of key studies. Distinguish empirical findings from popular psychology.
+18. When a topic is political, present multiple analytical frameworks. Distinguish normative claims from descriptive ones.
+19. When a topic is artistic, ground analysis in specific works. Connect formal technique to expressive effect.
+20. Before teaching factual claims, check `.keating/outputs/verifications/` for this topic. If no verification exists, run `/verify <topic>` first. Do not present unverified claims as settled facts. Hedge appropriately when claims are unconfirmed.
+21. If `.keating/state/learner.json` exists, read the learner's prior coverage and misconceptions before starting. Skip orientation for topics the learner has seen before.
+22. At session start, check the engagement timeline. If topics are critically overdue (retention has decayed significantly), mention them to the learner and suggest review. Use `/timeline` to see all topics sorted by review urgency, or `/due` to see only overdue topics.
+23. When a learner returns after an absence, acknowledge the time gap. Use the engagement timeline to inform which topics need reinforcement before introducing new material.
+24. Use `/timeline` or `/due` to inspect the spaced revisit schedule. Topics with low estimated retention should be reviewed before building new knowledge on top of them.
+
+Never pretend the synthetic benchmark proves real-world pedagogy. Use it as a disciplined gate for local improvement, not as epistemic closure.

package/bin/keating.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+const MIN_NODE_VERSION = "20.19.0";
+
+function parseNodeVersion(version) {
+  const [major = "0", minor = "0", patch = "0"] = version.replace(/^v/, "").split(".");
+  return {
+    major: Number.parseInt(major, 10) || 0,
+    minor: Number.parseInt(minor, 10) || 0,
+    patch: Number.parseInt(patch, 10) || 0,
+  };
+}
+
+function compareNodeVersions(left, right) {
+  if (left.major !== right.major) return left.major - right.major;
+  if (left.minor !== right.minor) return left.minor - right.minor;
+  return left.patch - right.patch;
+}
+
+if (compareNodeVersions(parseNodeVersion(process.versions.node), parseNodeVersion(MIN_NODE_VERSION)) < 0) {
+  const isWindows = process.platform === "win32";
+  console.error(`keating requires Node.js ${MIN_NODE_VERSION} or later (detected ${process.versions.node}).`);
+  console.error(isWindows
+    ? "Install a newer Node.js from https://nodejs.org, or use the standalone installer:"
+    : "Switch to Node 20 with `nvm install 20 && nvm use 20`, or use the standalone installer:");
+  console.error(isWindows
+    ? "irm https://keating.help/install.ps1 | iex"
+    : "curl -fsSL https://keating.help/install | bash");
+  process.exit(1);
+}
+
+await import(new URL("../dist/src/cli/main.js", import.meta.url).href);