Kaaslane — MATx (Tom Kabel)

TL;DR

matx-hack õpetab modelleerimist — kuidas tekstülesandest saada võrrand. MATx (github.com/tomkabel/MATx) õpetab seda võrrandit lahendama tehniliselt. Kaks naabrit ühes ahelas, mis sobivad loomulikult kokku.

tekst ──▶ mudel (matx-hack) ──▶ võrrand ──▶ lahendus (MATx)

Täielik ülemineku-kaart mikrooskuste vahel — lehel Sild MATx-i.

Kes MATx-i taga seisab

Tom Kabel — autor ja arendaja. Eesti projekt põhikoolile (7.–9. klass). Stack: TypeScript + React (frontend) + Express (API) + Postgres + Drizzle ORM. Hostitud enda taristul aadressil matxdev.duckdns.org.

Koostöö staatus. Kirjutamise hetkel on repositoorium avalik, aga ilma LICENSE-failita. Ekraanitõmmiste ja kirjelduste kasutamine selles õpikus on autoriga Slackis kooskõlastatud. Iga tehniline integratsioon (vt allpool Phase 3) nõuab eraldi PR-i selgesõnalise nõusolekuga.

Mis MATx-is sees on

Tegelikud slug’id andmebaasis on saadud GET /api/topics kaudu — matxdev.duckdns.org/api/topics (avalik endpoint, autentimiseta).

1. abivalemid — Korrutamise abivalemid

Õpi ja harjuta kolme abivalemit: summa ruut, vahe ruut ja ruutude vahe.

Competency (id, nimi)	Valem
1 — Summa ruut	$(a + b)^2 = a^2 + 2ab + b^2$
2 — Vahe ruut	$(a - b)^2 = a^2 - 2ab + b^2$
3 — Ruutude vahe	$a^2 - b^2 = (a + b)(a - b)$

Ava topic →

2. protsendid — Protsentarvutus

Lahenda protsentülesandeid ristkorrutise meetodil.

Competency (id, nimi)	Mida teeb
4 — Osa leidmine	Leia osa, kui tervik ja protsent on teada
5 — Terviku leidmine	Leia tervik, kui osa ja protsent on teada
6 — Protsendi leidmine	Leia protsent, kui tervik ja osa on teada

Ava topic →

3. vorrandid — Ühe tundmatuga võrrandid

Lahenda võrrandeid samm-sammult, kirjutades välja iga teisenduse.

Competency (id, nimi)	Vorm / kirjeldus
7 — Lihtsad võrrandid	$ax + b = c$
8 — Sulgudega võrrandid	Võrrandid, kus tuleb esmalt sulud avada
9 — Murdudega võrrandid	Võrrandid, kus tuleb esmalt murrud kaotada

Ava topic →

Lisaks: docs/06-math-topics.md Tom-i juures (teoreetiline kirjeldus); tabelite formaalne skeem — shared/schema.ts.

Miks koos tugevam

	matx-hack (meie)	MATx (Tom)
Domeen	Modelleerimine	Arvutamine
Mikrooskused	9 (defining T1–T3 × kolm tüüpi suhteid)	9 (3 topicut × 3 competency)
Mida õpilane vastab	Suuruste avaldised läbi $x$	Numbriline/sümbolne vastus
Mida jälgib	BKT 9 defining-oskuse järgi	Per-question results + error categories
Stack	Astro + React + Next.js (web/)	React + Express + Postgres
Sihtgrupp	Eesti kool, 7. klass	Eesti kool, 7.–9. klass
Sisukeel	ET / RU / EN	ET

Kognitiivselt — meie õpilane lõpetab faasi “saa aru ülesandest ja kirjuta võrrand”, misjärel läheb loomulikult faasi “lahenda võrrand numbrini”. Ilma MATx-ita jääb teine faas meie raamatus sõnaliseks; ilma meieta eeldab MATx, et võrrand on juba kuidagi saadud.

Kus proovida

Live dev-instants: matxdev.duckdns.org. Avalikke lehti pole — kasutajakontoga (õpetaja/õpilane) sisselogimine on vajalik. Tom kasutab demo-kontot päringu peale.

Kõige olulisemad vaated (pärast sisselogimist)

• /dashboard — Sinu õpitee Õpilase kodu. Kolm teemakaarti (Korrutamise abivalemid / Protsentarvutus / Ühe tundmatuga võrrandid), igal oma oskus% ja edenemine. Soovitatud-tag märgib käesolevat ZPD-eesmärki. Pärast PR-1-e hakkab seda tagi tagant juhtima student_skill_state posterior — praegu on see lihtne % õigeid.
• /teacher/analytics — Pädevuste soojuskaart Õpetaja hot map: iga rida õpilane, iga veerg mikrooskus, värvid <50% / 50-74% / 75-89% / 90%+. Praegu tuleneb % otse results-tabelist. Pärast PR-1-e on iga lahter Bayesi posterior pKnown, mis on stabiilsem (ei kõigu üksikute attempt’ide peale) ja auditeeritav (igal hetkel saab (prior, isCorrect, params) log’ist taasesitada). Tabid Soojuskaart / Õpilased / Hoiatused katavad erinevaid analüütika-rakurse.
• /topic/3/practice-flow — praktika-tutorial Step-by-step ülesannete lahendus murdude eemaldamisest võrrandist. See annab tunde, kuidas ülesanne ekraanil välja näeb enne kui õpilane vastust sisestab. PR-1-i createResult on just see endpoint, kus vastus salvestatakse ja BKT-update toimub.

Otselingid topic-lehtedele

• matxdev.duckdns.org/topics/abivalemid — Korrutamise abivalemid
• matxdev.duckdns.org/topics/protsendid — Protsentarvutus
• matxdev.duckdns.org/topics/vorrandid — Ühe tundmatuga võrrandid

Avalik API ilma autentimiseta

• /api/topics — topicute nimekiri (id, slug, title, description)
• /api/topics/:slug — topic + competencies massiiv

Integratsiooni roadmap

Phase 1 — raamatu lehed (selles releases tehtud)

• Skill-bridge mapping — kaart 9→9 põhjendustega kolmes keeles
• data/matx-bridge.json — single source of truth mappingu jaoks
• See kaaslase-leht

Phase 2 — cross-links ja deep-links (tehtud)

• Inline-kaardid “Companion: MATx” võtmelehetel: pealeht, Multi-skill, Simulaator, Q&A
• Otselingid kolmele topicule slug’i kaudu + avalik API
• iframe-embed otsustasime mitte teha: connect.sid läheb SameSite=Lax-iga, seega sisselogitud flow iframe-is ei tööta — ilma selleta on embed kasutu. Parem avada uues vahekaardis.

Phase 3 — BKT-mudel MATx-i submit-handleris (PR-ide plaan)

Live: matxteacher.duckdns.org

PR-1, PR-2, PR-3 ja PR-4 on kõik mergitud ja deploy’tud demo-instantsile matxteacher.duckdns.org (TLS self-signed — brauser hoiatab, mine Advanced → Proceed-i kaudu).

Mis seal kohe näha:

• 4 teemat sh Defineerimine (3 competency-t = progressioonimaatriks, 28 ülesannet)
• 11 õpilast (1 demo + 10 mock’i, profilid: 3 advanced / 4 intermediate / 2 struggling / 1 fresh)
• /teacher/analytics heatmap — iga lahter näitab BKT pKnown%-i (BKT-rosetiga) ja tooltip avab nii Bayesi posterior’i kui klassikalise % õigeid koos algkogusega
• /dashboard Soovitatud-tag — info-ikoon avab tooltip’i Miks soovitatud? mis näitab pKnown / pSolve / ZPD-kaugus selgelt (Vygotsky P(solve) ≈ 0.7)

PR-id, kõik MERGED:

• #3 PR-1 — BKT bookkeeping (createResult + student_skill_state)
• #5 PR-2 — ZPD-targeted recommendation (closed-form scoring)
• #7 PR-3 — Defineerimine teema 16 algse ülesandega
• #8 PR-3 ext — +12 ülesannet, L1.mix/L2.mix gap’id täidetud
• #9 PR-4 — UI: heatmap pKnown, tooltip “Miks soovitatud?”, 10 mock-õpilast
• #10 PR-5 — audit_trace JSONB veerg + sparkline tooltipis + heatmap-veergude sortimine + mock-õpilastele realistlikud ajalood (canonical BKT 0.2 → 0.576 → 0.874 → …)
• #11 PR-6 — õpilase detailvaade /teacher/student/:userId (320×60 sparkline iga pädevuse kohta), BKT-juhitud teavitused (stuck / mastery / plataa / regression), mikrooskuse-tasemel BKT bookkeeping (student_microskill_state tabel, data.microskills[]-iga märgitud ülesanded uuendavad nüüd ka mikrooskuse-posterior’i)
• #15+#16 PR-7 — mikrooskuse UI: õpilase detailvaates “Mikrooskused” sektsioon kõikide puudutatud mikrooskudega (240×36 sparkline igal); analüütika lisatab 4. tab Mikrooskused õpilane × 9 mikrooskust soojuskaardiga; mock-õpilased seeditud ka mikrooskuse-tasemel (9 mocki × 9 mikrooskust = 81 rida)

Idee. Tõsta meie BKT-matemaatika pure-TypeScript paketti bkt-core (zero runtime deps), Tom lisab selle ühe sõltuvusega ja ühe kutsega storage.createResult-i. Mingit võrgukutset, mingit ML-taristut. Mergitav kahes iseseisvas PR-is.

Mida portime bkt-core-i

Allikas matx-hack-is	Mis	Maht
web/lib/microskills.ts	Tüübid BktParams, MicroSkill, Task, StudentState + konstant DEFAULT_BKT	~25 rida, ilma deps-ita
web/lib/bkt.ts	bktUpdate, pSolve, ensureMastery, applyAttempt, scoreTaskForStudent, recommend	~150 rida, impordib ainult tüüpe

Paketi package.json sisaldab ainult name, main, types, tsc. Mitte ühtegi production-sõltuvust — see on puhas matemaatika.

PR 1 — bookkeeping (miinimum, ~70 rida, UI-d ei muuda)

Iga vastusekatse uuendab vastava competency BKT suletud valemiga. MATx-i nähtav käitumine ei muutu — andmebaasis ilmub uus väli.

1. Drizzle migration — uus tabel:

CREATE TABLE student_skill_state (
  user_id text NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  competency_id integer NOT NULL REFERENCES competencies(id) ON DELETE CASCADE,
  p_known double precision NOT NULL DEFAULT 0.2,
  attempts integer NOT NULL DEFAULT 0,
  last_updated timestamp DEFAULT now(),
  PRIMARY KEY (user_id, competency_id)
);

Zero-downtime (uus tabel, midagi ei blokeerita). Rakendatakse olemasoleva npm run db:push-iga.

2. shared/schema.ts — lisa tabeli definitsioon (~15 rida):

export const studentSkillState = pgTable("student_skill_state", {
  userId: text("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
  competencyId: integer("competency_id").notNull().references(() => competencies.id, { onDelete: "cascade" }),
  pKnown: doublePrecision("p_known").notNull().default(0.2),
  attempts: integer("attempts").notNull().default(0),
  lastUpdated: timestamp("last_updated").defaultNow(),
}, (t) => ({ pk: primaryKey({ columns: [t.userId, t.competencyId] }) }));

3. server/storage.ts.createResult (praegune, read 150–152) — lisa upsert pärast insert (~20 rida):

import { bktUpdate, DEFAULT_BKT } from "@matx-hack/bkt-core";
import { studentSkillState } from "@shared/schema";

async createResult(result: CreateResultRequest) {
  const [savedResult] = await db.insert(results).values(result).returning();

  // — BKT update —
  const q = await this.getQuestion(result.questionId);
  if (q?.competencyId) {
    const [cur] = await db.select().from(studentSkillState).where(and(
      eq(studentSkillState.userId, result.userId),
      eq(studentSkillState.competencyId, q.competencyId),
    )).limit(1);
    const prior = cur?.pKnown ?? DEFAULT_BKT.pInit;
    const posterior = bktUpdate(prior, result.isCorrect, DEFAULT_BKT);
    await db.insert(studentSkillState).values({
      userId: result.userId, competencyId: q.competencyId,
      pKnown: posterior, attempts: 1, lastUpdated: new Date(),
    }).onConflictDoUpdate({
      target: [studentSkillState.userId, studentSkillState.competencyId],
      set: { pKnown: posterior, attempts: sql`${studentSkillState.attempts} + 1`, lastUpdated: new Date() },
    });
  }

  return savedResult;
}

server/routes.ts (submit-handler readadel 292–345) jääb puutumata — uuendus on inkapsuleeritud storage-kihti.

PR 2 — nutikam soovitus (~80 rida, vabatahtlik)

Asenda heuristika getNextRecommendedQuestion-is (praegune, read 878–940) BKT-põhise valikuga ZPD-sihtmärgi $P(solve) \approx 0.7$ kaudu.

Praegune loogika — kolm bucketit notStarted / needsWork (mastery < 60%) / progressing (60–90%) valikuga mastery asc järgi — säilib mapping-kihina tagasi Tom-i eestikeelseteks selgitusteks (Harjuta..., Kinnista..., Korda...), et UI/UX ei muutuks. Kapoti all — meie recommend(state, tasks):

import { recommend } from "@matx-hack/bkt-core";

async getNextRecommendedQuestion(userId, topicId) {
  const skillStates = await db.select().from(studentSkillState)
    .innerJoin(competencies, eq(studentSkillState.competencyId, competencies.id))
    .where(eq(competencies.topicId, topicId));
  const state = {
    student_id: userId,
    mastery: Object.fromEntries(skillStates.map(s => [String(s.competency_id), s.p_known])),
    history: [],
  };
  const qs = await db.select().from(questions).where(eq(questions.topicId, topicId));
  const tasks = qs.map(q => ({
    id: String(q.id),
    topic: String(topicId),
    microskills: q.competencyId ? [String(q.competencyId)] : [],
    difficulty: 0.5, prompt_et: q.text, answer: "",
  }));
  const top = recommend(state, tasks, 1)[0];
  // … map score+pSolve back to existing reason buckets for UX continuity
}

Mis on tehtud, mis on järel

Tükk	Staatus
bkt-core paketiks ekstraheerimine	✅ Tehtud
tomkabel/MATx-i submodule lisamine	✅ Tom tegi ise
PR-1 BKT bookkeeping	✅ Mergitud + deploy’tud
PR-2 ZPD-targeted soovitus	✅ Mergitud + deploy’tud
PR-3 Defineerimine + 28 ülesannet	✅ Mergitud + deploy’tud
PR-4 UI: heatmap pKnown, “Miks soovitatud?”, 10 mock-õpilast	✅ Mergitud + deploy’tud
PR-5 audit_trace + sparkline + sortimine	✅ Mergitud + deploy’tud
PR-6 õpilase detailvaade + BKT-teavitused + mikrooskuse bookkeeping	✅ Mergitud + deploy’tud
PR-7 mikrooskuse UI (detailvaade sektsioon + uus heatmap-tab + mock-seed)	✅ Mergitud + deploy’tud
Õpetaja tagasiside-iteratsioon	⏳ Käes

Audit-trail EU AI Act jaoks

bktUpdate on suletud analüütiline valem. See tähendab: igal hetkel saab audiitor võtta logist (prior, observation, params) ja iseseisvalt taasesitada posterior. Mingit “black-box” põhjendust pole vaja.

Vabatahtlik: lisa audit_trace JSONB veerg student_skill_state-i — sinna kogunes uuenduste ajalugu (timestamp, prior, isCorrect, posterior) tuplitena. See katab Annex III nõuded traceability + explainability ilma eraldi compliance-taristuta.

EU AI Act compliance

Education / vocational training — high-risk Annex III kategooria Regulation (EU) 2024/1689 järgi. Nõuded traceability’le, dokumentatsioonile, human oversight’ile ja explainability’le jõustuvad etapiviisiliselt augustist 2026 kuni augustini 2027.

Meie konveier on juba praegu täielikult deterministlik — production- teel pole ühtegi LLM-kutset:

• BKT-uuendus — suletud analüütiline avaldis Bayesi järgi.
• Selgitused — mallimootor (web/lib/explain.ts) fikseeritud fraaside komplektiga.
• Selektor — argmax mudeli kindluse järgi + topology reeglid (skill-graph).

Pärast Phase 3-e pärib MATx sama profiili automaatselt: üks rida bktUpdate(...) submit-handleris — ja audit-trail järgmise küsimuse otsuse kohta tekib ilma eraldi compliance-taristuta.

Lisaks saab katuse peale lisada eatf.eu — model attestation, response signing, audit ühe API-kutsega — artefaktide tsentraliseeritud salvestamiseks.

Seotud lehed

• Progressioonimaatriks — meie 9-mikrooskuse defining-skills mudel.
• Sild MATx-i — vastavustabel microskill ↔ MATx-competency ja Mermaid-graafik üleminekutest.
• Selektori simulaator — kuidas BKT valib järgmise defining-mikrooskuse; pärast Phase 3-e viitab ka MATx-competencies’idele.
• Sõnastik — terminid (microskill, competency, BKT jne).