Product Factsheet · v0.2.0
SIAIS — Self-Improving Adaptive Instructional System
A pedagogical orchestrator that sits between learners and the apps that teach them — deciding which strategy to deploy when and what to learn from each interaction. Built on five disciplined components and four escalating policy levels, moving from a fixed sequence to a contextual bandit by swapping a single class.
Every figure above is counted from the repository — see the notes beside each section.
Theory
SIAIS is not a bag of features — it is a set of positions about how adaptive instruction should be built, each of which decides a piece of the architecture. Below, the school of thought on the left, the design decision it forces on the right.
ruleBKT.js) estimates latent mastery from a stream of correct/incorrect observations and drives rule-based selection off it.contextualBandit.js) balances exploration against exploitation per learner-context, using a zero-dependency linear-algebra core (matrix.js).V before promotion.409 { handover: true } instead of guessing.The design invariant that makes the theory hold
Every write to the parametric components (C2) must go through the API Gateway (C3), which logs to the LRS (C1) and consults the Governor (C5). The Pedagogy Engine (C4) reads C1 and C2 but cannot bypass C3 to mutate state. There is no other path — this single invariant is the foundation of safety, auditability, and reproducibility.
Technology
A Node.js ≥ 20 / ESM codebase that runs entirely in memory by default and lights up GCS, a remote LRS, and LLM vendors only when their env vars are present. The stack is deliberately small: five core files, four swappable policies, one gateway, one LLM chokepoint, GCS-only persistence.
The five conditions core
Verified in src/core/ — five layers, one file each.
| # | Name | File | Role |
|---|---|---|---|
| C1 | Persistent Memory | core/lrs.js | Append-only xAPI log; mirrors to GCS (JSONL) and a remote LRS when configured. In-memory by default. |
| C2 | Parametric Components | core/components.js | Named, runtime-mutable parameters (e.g. dialogue.modality, dialogue.hint_depth). |
| C3 | API Gateway | core/gateway.js | The only path between C1 and C2. Logs, validates against C5, then applies. All writes funnel here. |
| C4 | Pedagogy Engine | core/pedagogy.js | Strategy library + active policy + pluggable objective (target mastery gain). |
| C5 | Governance | core/governor.js | Reviews every self-modification — log_only at L0–L2, bounded at L3+. |
Four policy levels — one class swap src/factory.js
Escalate from "simple" to "master" by swapping the policy class in src/factory.js. Nothing else changes — same library, same gateway, same LRS. The Governor automatically becomes bounded at L3.
| Level | Class | File | What it does |
|---|---|---|---|
| L0 | FixedSequencePolicy | policies/fixed.js | Returns the first strategy. Baseline. |
| L1 | DifficultyOnlyRulePolicy | policies/ruleDifficulty.js | Difficulty rule against a single mastery proxy. |
| L2 | BKTRulePolicy | policies/ruleBKT.js | Bayesian Knowledge Tracing → rule-based selection. |
| L3 | ContextualBanditPolicy | policies/contextualBandit.js | LinUCB contextual bandit; zero-dep linear algebra via matrix.js. |
No L4 in code today — the vocabulary spec leaves the slot open for human-in-the-loop or multi-agent ensembles.
The eleven-layer self-improvability architecture
The canonical specification of what makes SIAIS self-improvable. Source of truth:
src/architecture/elevenLayers.js — regenerate the doc with npm run gen:arch, served
live at GET /api/architecture/layers and rendered at /architecture.html.
Counted from that file: 3 macro-groups, 8 implemented · 2 partial · 1 design-only.
Foundation 3 layers
Teleology, Substrate, Identity — what the system is and is for. Two carry human-only self-improvement modes that bound the rest.
Cognition 5 layers
Temporality, Epistemics, Evaluation, Optimization, Reflexivity — how it knows, judges, proposes, and monitors its own loop. All five implemented.
Constraint 3 layers
Governance, Resources, Communication — how improvement is bounded, resourced, and made inspectable. Resources is design-only today.
xAPI — the lingua franca v1.0.0 spec
A closed set — counted from docs/architecture/xapi_vocabulary.md. Adding a verb or activity type requires a version bump.
15 verbs closed set
observed, experienced, interacted, attempted, answered, inferred, recommended, selected, applied, rejected, audited, scored, completed, handed-off, flagged.
13 activity types closed set
session, ke-content, sata-item, spl-turn, strategy-bundle, parameter-write, governance-decision, mastery-estimate, affect-snapshot, misconception, intervention, worked-example, learner-fingerprint.
Chokepoints, persistence & the HTTP surface
One LLM gateway
A single runLlmChat({ vendor, model, messages }) routes across many vendors — OpenAI-compatible (OpenAI, Groq, Together, Perplexity, OpenRouter, DeepSeek, xAI, Ollama, LM Studio, custom) share one adapter; Azure OpenAI, Anthropic, and Google Gemini have explicit adapters; AWS Bedrock is a placeholder. The self-improvement layer separates three roles: operator · author · judge.
GCS-only persistence
No browser localStorage anywhere — an explicit design decision. Learner state at learners/<id>.json; xAPI mirrored as dated JSONL; three self-improvement buckets (skills · ledger · state), the ledger write-once. Provisioned by infra/terraform/ with four scoped service accounts.
One unified server
src/server.js is what npm start boots (helmet · cors · morgan, PORT=4000). It builds the five-condition core and mounts the AutoTutor routes. server/index.js is now just a two-line stub that imports it. Static assets from public/; no SPA catch-all.
Applications
SIAIS is the conductor for a federation of teaching apps and a laboratory for the pedagogy that drives them. Three external surfaces present, assess, and converse; a synthetic-cohort engine lets a teacher improve the tutoring before a single real learner arrives.
Three federated surfaces 45 methods total
SIAIS orchestrates three external apps; the C4 engine selects a strategy bundle and the Session Manager walks
its steps. Each surface's method catalog is verified in docs/its-agents/specifications/ — exactly
15 each.
KE 15 methods
Knowledge Explorer — content presentation. Concept maps, timelines, hierarchical, problem-based, spaced repetition, and more.
SATA 15 formats
Select-All-That-Apply — assessment. Classic, weighted, confidence-weighted, evidence-based, metacognitive, and more.
VHS-SPL 15 methods
Virtual-Human Self-Paced Learning — dialogue tutoring. Socratic, productive failure, peer tutoring, cognitive apprenticeship, and more.
Simulate & Improve — the flagship engine
Open to any teacher or admin: compose a synthetic student, have an LLM role-play that learner
through a topic, analyze where the cohort fell short, and let an LLM author propose a pedagogy improvement
targeted at that exact kind of learner — all governed and schema-validated. Routes in
src/routes/admin/simulate.js; engine in src/services/simulate/.
A student is composed by choosing a level for each of nine independent dimensions — cognitive ability, literacy, attention, prior knowledge, motivation, affect, peer influence, help-seeking, misconception tendency — every level layering calibrated values onto a shared 15-trait vector. In principle each profile can receive its own pedagogy adapted to any tutoring topic.
Compose
Pick a level per dimension; the composer merges trait values, labels the student, and persists a first-class learner profile. dimensions.js · profiles.js
Roleplay
A RoleplayStudent runs the learner through the topic via the real EMT dialogue engine — LLM-driven when configured, else a deterministic trait heuristic. Every turn emits xAPI.
Analyze
Aggregate per-expectation coverage, misconception rates, and weak moves into a ranked list of improvement targets. analyze.js · interpret.js
Improve
An LLM author proposes one improved move (hint or prompt), schema-validated, never giving the answer away, gated by governance (layer 9). reviewPedagogy.js
Where it fits
Self-improving tutors
Every observation lands in the LRS; every parameter change is reviewed by the Governor — a tutor that gets better under audit, without a redeploy.
Pedagogy research
Swap policies L0→L3 with a single class swap; a seeded PRNG gives byte-identical cohort trajectories, so strategy comparisons are reproducible.
App federations
A Knowledge Explorer, an assessment app, and a dialogue tutor share one session model and one xAPI vocabulary. Briefings via /KEAPI, /SATAAPI, /SPLAPI.
A parallel 100-agent ITS architecture lives in src/services/its/ (CommonJS): 5 of 100 agents implemented — learner-model, mastery-estimation, pedagogical-model, adaptive-sequencing, affective-state-monitoring. Not yet mounted in the server; the 99 agent specs in docs/its-agents/specifications/ are authoritative.
Impacts
What changes for each audience — framed as mechanisms the design produces, not measured study results. These follow directly from how the code is built; none is a claim about efficacy, adoption, or outcomes we have not measured.
For learners
Strategy is chosen per learner-context rather than fixed, and mastery is tracked latently — so difficulty and modality can move with the learner instead of the calendar.
When a request falls outside the system's designed domain, it hands off rather than bluffing an answer.
For educators
The Simulate & Improve loop lets a teacher stress-test pedagogy against ~2M synthetic learner profiles before a real cohort, and read a ranked list of where instruction fell short.
Proposed improvements are versioned skills through a governance gate — nothing promotes without review.
For researchers
A single class swap moves L0→L3, and a seeded PRNG makes cohort runs byte-identical — so a policy comparison is a controlled, reproducible experiment, not an anecdote.
Every decision logs its propensity, enabling honest off-policy (IPS) evaluation of candidate strategies.
For integrators & institutions
A closed xAPI vocabulary is the contract, so three independent apps interoperate without sharing code. Persistence is GCS-only with scoped service accounts and no browser storage.
Three layers are deliberately human-only: a self-improving system that cannot loosen its own gate is auditable by construction.
What's wired vs. designed honest status
Wired & working today
- Five-condition core (C1–C5)
- Policies L0/L1/L2/L3 — single-class-swap pluggability
- One unified HTTP server with the listed endpoints
- GCS persistence + remote LRS mirror (when env vars set)
- LLM provider routing across many vendors
- xAPI vocabulary spec v1.0.0 (the contract)
- CLI cohort tools (
demo,compare) - Simulate & Improve engine (compose → roleplay → analyze → author)
- Dimensional learner model — 59 composable classifications
Designed but not yet wired
- Surface orchestration (launch tickets,
/sessions/:id/next, redirect flow) - Strategy bundle registry as multi-step sequences
- Per-surface JWT auth + JWKS endpoint
- C3 ingress validation against the canonical xAPI envelope
- Read-side projection auto-mounting
- Governor human-in-the-loop (
audited) mode - ITS agent subsystem mounting; L4+ policies
- Resources layer (the economy of improvement)