@classytic/labs 0.1.0

package/dist/ml/classifier/preset.mjs

@@ -0,0 +1,315 @@
+'use client';
+
+import { clamp } from "../../core/util.mjs";
+import { StatusPill } from "../../kit/controls.mjs";
+import { LabFrame, LiveRegion } from "../../kit/frame.mjs";
+import { useCheckpoint } from "../../kit/pedagogy.mjs";
+import { useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { Circle, Dot, Label, MovableDot, Polygon, Segment, Stage } from "@classytic/stage";
+
+//#region src/ml/classifier/preset.tsx
+/**
+* ClassifierThresholdLab — the precision/recall trade-off you can drag. Positive
+* and negative examples sit along a score axis (they OVERLAP, like any real
+* classifier). Drag the threshold: everything to its right is predicted positive.
+* The 2×2 confusion matrix and precision / recall / accuracy / F1 update live —
+* slide right and precision climbs while recall falls; there's no setting that
+* maxes both. Misclassified points get a red ring.
+*
+* A data-analytics instrument from pure primitives: Dot + a horizontal MovableDot
+* threshold + a live HTML confusion matrix.
+*/
+const POS = "var(--stage-good)";
+const NEG = "var(--stage-muted)";
+const DEFAULT_POS = [
+	4,
+	5,
+	5.5,
+	6,
+	6.5,
+	7,
+	7.5,
+	8,
+	8.5,
+	9
+];
+const DEFAULT_NEG = [
+	1,
+	1.5,
+	2,
+	2.5,
+	3,
+	3.5,
+	4,
+	4.5,
+	5,
+	6
+];
+function ClassifierThresholdLab({ positives = DEFAULT_POS, negatives = DEFAULT_NEG, threshold = 5, span = 10, title = "The precision–recall trade-off", prompt = "Drag the threshold: everything to its right is called positive. Watch the confusion matrix — pushing precision up costs you recall.", objectives, height = 300 }) {
+	const view = {
+		xMin: 0,
+		xMax: span,
+		yMin: -4,
+		yMax: 4
+	};
+	const [t, setT] = useState(threshold);
+	const [moved, setMoved] = useState(false);
+	useCheckpoint({
+		solved: moved,
+		activity: "classifier-threshold"
+	});
+	const TP = positives.filter((s) => s >= t).length;
+	const FN = positives.length - TP;
+	const FP = negatives.filter((s) => s >= t).length;
+	const TN = negatives.length - FP;
+	const total = positives.length + negatives.length;
+	const precision = TP + FP === 0 ? 0 : TP / (TP + FP);
+	const recall = TP + FN === 0 ? 0 : TP / (TP + FN);
+	const accuracy = (TP + TN) / total;
+	const f1 = precision + recall === 0 ? 0 : 2 * precision * recall / (precision + recall);
+	const dragT = (p) => {
+		setT(clamp(p.x, view.xMin, view.xMax));
+		if (!moved) setMoved(true);
+	};
+	const yOf = (i) => i % 3 - 1;
+	const dot = (s, i, posClass) => {
+		const wrong = s >= t !== posClass;
+		const cy = (posClass ? 2 : -2) + yOf(i) * .5;
+		return /* @__PURE__ */ jsxs("g", { children: [wrong && /* @__PURE__ */ jsx(Circle, {
+			center: {
+				x: s,
+				y: cy
+			},
+			r: .42,
+			color: "var(--stage-danger)",
+			fill: "none",
+			weight: 2
+		}), /* @__PURE__ */ jsx(Dot, {
+			x: s,
+			y: cy,
+			r: 5.5,
+			color: posClass ? POS : NEG
+		})] }, `${posClass ? "p" : "n"}${i}`);
+	};
+	const Cell = ({ label, n, tone }) => /* @__PURE__ */ jsxs("div", {
+		style: {
+			padding: "8px 10px",
+			borderRadius: 8,
+			background: `color-mix(in oklab, ${tone} 14%, var(--stage-bg))`,
+			border: `1px solid color-mix(in oklab, ${tone} 40%, var(--stage-grid))`,
+			textAlign: "center",
+			minWidth: 78
+		},
+		children: [/* @__PURE__ */ jsx("div", {
+			style: {
+				fontSize: 10.5,
+				fontWeight: 700,
+				color: "var(--stage-muted)"
+			},
+			children: label
+		}), /* @__PURE__ */ jsx("div", {
+			style: {
+				fontSize: 20,
+				fontWeight: 800,
+				color: tone
+			},
+			children: n
+		})]
+	});
+	const Metric = ({ label, v }) => /* @__PURE__ */ jsxs("div", {
+		style: {
+			flex: 1,
+			minWidth: 90
+		},
+		children: [/* @__PURE__ */ jsxs("div", {
+			style: {
+				fontSize: 11,
+				fontWeight: 700,
+				color: "var(--stage-muted)"
+			},
+			children: [
+				label,
+				" ",
+				(v * 100).toFixed(0),
+				"%"
+			]
+		}), /* @__PURE__ */ jsx("div", {
+			style: {
+				height: 8,
+				borderRadius: 999,
+				background: "color-mix(in oklab, var(--stage-fg) 10%, transparent)",
+				overflow: "hidden"
+			},
+			children: /* @__PURE__ */ jsx("div", { style: {
+				width: `${v * 100}%`,
+				height: "100%",
+				background: "var(--stage-accent)",
+				transition: "width .1s"
+			} })
+		})]
+	});
+	const figure = /* @__PURE__ */ jsxs(Stage, {
+		view,
+		height,
+		preserveAspect: false,
+		ariaLabel: `Score axis with a threshold at ${t.toFixed(1)}; precision ${(precision * 100).toFixed(0)}%, recall ${(recall * 100).toFixed(0)}%`,
+		children: [
+			/* @__PURE__ */ jsx(Polygon, {
+				points: [
+					{
+						x: t,
+						y: view.yMin
+					},
+					{
+						x: span,
+						y: view.yMin
+					},
+					{
+						x: span,
+						y: view.yMax
+					},
+					{
+						x: t,
+						y: view.yMax
+					}
+				],
+				color: "transparent",
+				fill: "var(--stage-accent)",
+				fillOpacity: .08,
+				weight: 0
+			}),
+			/* @__PURE__ */ jsx(Segment, {
+				from: {
+					x: 0,
+					y: 0
+				},
+				to: {
+					x: span,
+					y: 0
+				},
+				color: "var(--stage-grid)",
+				weight: 1
+			}),
+			/* @__PURE__ */ jsx(Label, {
+				x: 1.2,
+				y: 3.5,
+				text: "positives ●",
+				size: 11,
+				color: POS
+			}),
+			/* @__PURE__ */ jsx(Label, {
+				x: 1.2,
+				y: -3.5,
+				text: "negatives ●",
+				size: 11,
+				color: NEG
+			}),
+			/* @__PURE__ */ jsx(Label, {
+				x: span - 1.3,
+				y: 3.5,
+				text: "→ called +",
+				size: 11,
+				color: "var(--stage-accent)"
+			}),
+			positives.map((s, i) => dot(s, i, true)),
+			negatives.map((s, i) => dot(s, i, false)),
+			/* @__PURE__ */ jsx(Segment, {
+				from: {
+					x: t,
+					y: view.yMin
+				},
+				to: {
+					x: t,
+					y: view.yMax
+				},
+				color: "var(--stage-accent)",
+				weight: 2.5,
+				dashed: true
+			}),
+			/* @__PURE__ */ jsx(MovableDot, {
+				value: {
+					x: t,
+					y: 0
+				},
+				onMove: dragT,
+				constrain: "horizontal",
+				range: {
+					min: view.xMin,
+					max: view.xMax
+				},
+				r: 9,
+				color: "var(--stage-accent)",
+				ariaLabel: "decision threshold"
+			})
+		]
+	});
+	return /* @__PURE__ */ jsx(LabFrame, {
+		title,
+		prompt,
+		objectives,
+		aside: /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsxs("div", {
+			style: {
+				display: "grid",
+				gridTemplateColumns: "1fr 1fr",
+				gap: 4
+			},
+			children: [
+				/* @__PURE__ */ jsx(Cell, {
+					label: "true +",
+					n: TP,
+					tone: POS
+				}),
+				/* @__PURE__ */ jsx(Cell, {
+					label: "false −",
+					n: FN,
+					tone: "var(--stage-warn)"
+				}),
+				/* @__PURE__ */ jsx(Cell, {
+					label: "false +",
+					n: FP,
+					tone: "var(--stage-danger)"
+				}),
+				/* @__PURE__ */ jsx(Cell, {
+					label: "true −",
+					n: TN,
+					tone: NEG
+				})
+			]
+		}), /* @__PURE__ */ jsxs("div", {
+			style: {
+				display: "flex",
+				flexWrap: "wrap",
+				gap: 12,
+				alignContent: "flex-start"
+			},
+			children: [
+				/* @__PURE__ */ jsx(Metric, {
+					label: "precision",
+					v: precision
+				}),
+				/* @__PURE__ */ jsx(Metric, {
+					label: "recall",
+					v: recall
+				}),
+				/* @__PURE__ */ jsx(Metric, {
+					label: "accuracy",
+					v: accuracy
+				}),
+				/* @__PURE__ */ jsx(Metric, {
+					label: "F1",
+					v: f1
+				}),
+				/* @__PURE__ */ jsxs(StatusPill, {
+					ok: true,
+					children: ["threshold ", t.toFixed(1)]
+				})
+			]
+		})] }),
+		footer: /* @__PURE__ */ jsx(LiveRegion, { children: `Threshold ${t.toFixed(1)}. Precision ${(precision * 100).toFixed(0)} percent, recall ${(recall * 100).toFixed(0)} percent.` }),
+		children: figure
+	});
+}
+
+//#endregion
+export { ClassifierThresholdLab };

package/dist/ml/index.d.mts

@@ -0,0 +1,6 @@
+import { RegressionLab, RegressionProps } from "./regression/preset.mjs";
+import { KMeansLab, KMeansProps } from "./kmeans/preset.mjs";
+import { ClassifierProps, ClassifierThresholdLab } from "./classifier/preset.mjs";
+import { BoundaryDataset, BoundaryProps, DecisionBoundaryLab } from "./boundary/preset.mjs";
+import { KNNBoundaryLab, KnnDataset, KnnProps } from "./knn/preset.mjs";
+export { type BoundaryDataset, type BoundaryProps, type ClassifierProps, ClassifierThresholdLab, DecisionBoundaryLab, KMeansLab, type KMeansProps, KNNBoundaryLab, type KnnDataset, type KnnProps, RegressionLab, type RegressionProps };

package/dist/ml/index.mjs

@@ -0,0 +1,7 @@
+import { RegressionLab } from "./regression/preset.mjs";
+import { KMeansLab } from "./kmeans/preset.mjs";
+import { ClassifierThresholdLab } from "./classifier/preset.mjs";
+import { DecisionBoundaryLab } from "./boundary/preset.mjs";
+import { KNNBoundaryLab } from "./knn/preset.mjs";
+
+export { ClassifierThresholdLab, DecisionBoundaryLab, KMeansLab, KNNBoundaryLab, RegressionLab };

package/dist/ml/kmeans/index.d.mts

@@ -0,0 +1 @@
+import { KMeansLab, KMeansProps } from "./preset.mjs";

package/dist/ml/kmeans/preset.d.mts

@@ -0,0 +1,33 @@
+import { ReactNode } from "react";
+
+//#region src/ml/kmeans/preset.d.ts
+interface KMeansProps {
+  points?: {
+    x: number;
+    y: number;
+  }[];
+  k?: number;
+  seeds?: {
+    x: number;
+    y: number;
+  }[];
+  span?: number;
+  showLines?: boolean;
+  title?: string;
+  prompt?: string;
+  objectives?: string[];
+  height?: number;
+}
+declare function KMeansLab({
+  points,
+  k,
+  seeds,
+  span,
+  showLines,
+  title,
+  prompt,
+  objectives,
+  height
+}: KMeansProps): ReactNode;
+//#endregion
+export { KMeansLab, KMeansProps };

package/dist/ml/kmeans/preset.mjs

@@ -0,0 +1,236 @@
+'use client';
+
+import { CheckButton, StatusPill } from "../../kit/controls.mjs";
+import { ControlBar, LabFrame, LiveRegion } from "../../kit/frame.mjs";
+import { useCheckpoint } from "../../kit/pedagogy.mjs";
+import { useMemo, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Circle, Dot, Grid, MovableDot, Segment, Stage, useFrameLoop, useInView } from "@classytic/stage";
+
+//#region src/ml/kmeans/preset.tsx
+/**
+* KMeansLab — unsupervised clustering you can watch converge. Points sit in a few
+* blobs; you drag the k centroids to seed them, then Step (Lloyd's algorithm):
+* every point recolours to its nearest centroid, and each centroid jumps to the
+* mean of its cluster. Run animates it — centroids migrate into the blobs, the
+* within-cluster error (inertia) drops, and it stops when nothing moves. Seed the
+* centroids badly on purpose and you land in a worse local minimum — the key
+* k-means intuition that initialisation matters.
+*
+* Pure stage primitives: Dot (coloured by assignment) + MovableDot (centroids) +
+* useFrameLoop (throttled stepping). Isometric square view (SSR-safe).
+*/
+const COLORS = [
+	"var(--stage-accent)",
+	"var(--stage-good)",
+	"var(--stage-danger)",
+	"var(--stage-warn)",
+	"var(--stage-accent-2)"
+];
+const OFFS = [
+	[-.8, .5],
+	[.6, .9],
+	[-.4, -.7],
+	[.9, -.3],
+	[.1, .6],
+	[-.9, -.2],
+	[.5, -.85]
+];
+const DEFAULT_POINTS = [
+	[2.6, 7.2],
+	[7.4, 7.6],
+	[5, 2.7]
+].flatMap(([cx, cy]) => OFFS.map(([dx, dy]) => ({
+	x: cx + dx,
+	y: cy + dy
+})));
+const DEFAULT_SEEDS = [
+	{
+		x: 3.5,
+		y: 5.5
+	},
+	{
+		x: 6.5,
+		y: 6
+	},
+	{
+		x: 5,
+		y: 4
+	}
+];
+const d2 = (a, b) => (a.x - b.x) ** 2 + (a.y - b.y) ** 2;
+function KMeansLab({ points = DEFAULT_POINTS, k = 3, seeds, span = 10, showLines = true, title = "k-means — watch the clusters form", prompt = "Drag the centroids to seed them, then Step: points recolour to the nearest centroid, centroids jump to their cluster mean. Seed them badly and you get stuck in a worse answer.", objectives, height = 380 }) {
+	const view = {
+		xMin: 0,
+		xMax: span,
+		yMin: 0,
+		yMax: span
+	};
+	const [cents, setCents] = useState((seeds ?? DEFAULT_SEEDS).slice(0, k));
+	const [running, setRunning] = useState(false);
+	const [iter, setIter] = useState(0);
+	const [converged, setConverged] = useState(false);
+	const { ref: viewRef, inView } = useInView();
+	useCheckpoint({
+		solved: converged,
+		activity: "kmeans"
+	});
+	const assign = (cs) => points.map((p) => {
+		let best = 0, bd = Infinity;
+		cs.forEach((c, j) => {
+			const dd = d2(c, p);
+			if (dd < bd) {
+				bd = dd;
+				best = j;
+			}
+		});
+		return best;
+	});
+	const labels = useMemo(() => assign(cents), [cents, points]);
+	const inertia = useMemo(() => points.reduce((s, p, i) => s + d2(cents[labels[i]], p), 0), [
+		cents,
+		labels,
+		points
+	]);
+	const stepOnce = (cs) => {
+		const lab = assign(cs);
+		return cs.map((c, j) => {
+			const mine = points.filter((_, i) => lab[i] === j);
+			if (!mine.length) return c;
+			return {
+				x: mine.reduce((s, p) => s + p.x, 0) / mine.length,
+				y: mine.reduce((s, p) => s + p.y, 0) / mine.length
+			};
+		});
+	};
+	const moved = (a, b) => a.reduce((m, c, i) => Math.max(m, Math.hypot(c.x - b[i].x, c.y - b[i].y)), 0);
+	const step = () => {
+		setCents((cs) => {
+			const nx = stepOnce(cs);
+			if (moved(cs, nx) < .02) {
+				setRunning(false);
+				setConverged(true);
+			}
+			return nx;
+		});
+		setIter((i) => i + 1);
+	};
+	const acc = useRef(0);
+	useFrameLoop((f) => {
+		acc.current += f.dtMs;
+		if (acc.current >= 320) {
+			acc.current = 0;
+			step();
+		}
+	}, { running: running && inView });
+	const reset = () => {
+		setCents((seeds ?? DEFAULT_SEEDS).slice(0, k));
+		setIter(0);
+		setRunning(false);
+		setConverged(false);
+	};
+	const dragCent = (j, p) => {
+		setRunning(false);
+		setConverged(false);
+		setCents((cs) => cs.map((c, i) => i === j ? p : c));
+	};
+	const figure = /* @__PURE__ */ jsx("div", {
+		ref: viewRef,
+		className: "lab-playwrap",
+		children: /* @__PURE__ */ jsxs(Stage, {
+			view,
+			height,
+			ariaLabel: `k-means with ${k} clusters; inertia ${inertia.toFixed(1)}`,
+			children: [
+				/* @__PURE__ */ jsx(Grid, {}),
+				showLines && points.map((p, i) => {
+					const c = cents[labels[i]];
+					return /* @__PURE__ */ jsx(Segment, {
+						from: {
+							x: p.x,
+							y: p.y
+						},
+						to: {
+							x: c.x,
+							y: c.y
+						},
+						color: COLORS[labels[i] % COLORS.length],
+						weight: 1,
+						opacity: .25
+					}, `l${i}`);
+				}),
+				points.map((p, i) => /* @__PURE__ */ jsx(Dot, {
+					x: p.x,
+					y: p.y,
+					r: 5,
+					color: COLORS[labels[i] % COLORS.length]
+				}, i)),
+				cents.map((c, j) => /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsx(Circle, {
+					center: {
+						x: c.x,
+						y: c.y
+					},
+					r: .45,
+					color: COLORS[j % COLORS.length],
+					fill: "none",
+					weight: 2
+				}), /* @__PURE__ */ jsx(MovableDot, {
+					value: c,
+					onMove: (p) => dragCent(j, p),
+					r: 9,
+					color: COLORS[j % COLORS.length],
+					ariaLabel: `centroid ${j + 1}`
+				})] }, `c${j}`))
+			]
+		})
+	});
+	return /* @__PURE__ */ jsx(LabFrame, {
+		title,
+		prompt,
+		objectives,
+		controls: /* @__PURE__ */ jsxs(ControlBar, { children: [
+			/* @__PURE__ */ jsx(CheckButton, {
+				onClick: () => setRunning((r) => !r),
+				children: running ? "⏸ Pause" : "▶ Run"
+			}),
+			/* @__PURE__ */ jsx("button", {
+				type: "button",
+				className: "lab-chip",
+				onClick: step,
+				children: "Step"
+			}),
+			/* @__PURE__ */ jsx("button", {
+				type: "button",
+				className: "lab-chip",
+				onClick: reset,
+				children: "Reset"
+			}),
+			/* @__PURE__ */ jsxs("span", {
+				style: {
+					fontWeight: 700,
+					fontVariantNumeric: "tabular-nums"
+				},
+				children: ["inertia ", /* @__PURE__ */ jsx("b", {
+					style: { fontSize: 17 },
+					children: inertia.toFixed(1)
+				})]
+			}),
+			/* @__PURE__ */ jsx(StatusPill, {
+				ok: !running && iter > 0,
+				children: !running && iter > 0 ? "converged" : `step ${iter}`
+			}),
+			/* @__PURE__ */ jsx("span", {
+				style: {
+					marginLeft: "auto",
+					color: "var(--stage-muted)"
+				},
+				children: "drag a centroid to re-seed"
+			})
+		] }),
+		footer: /* @__PURE__ */ jsx(LiveRegion, { children: `Step ${iter}. Inertia ${inertia.toFixed(1)}.` }),
+		children: figure
+	});
+}
+
+//#endregion
+export { KMeansLab };

package/dist/ml/knn/index.d.mts

@@ -0,0 +1 @@
+import { KNNBoundaryLab, KnnDataset, KnnProps } from "./preset.mjs";

package/dist/ml/knn/preset.d.mts

@@ -0,0 +1,28 @@
+import { ReactNode } from "react";
+
+//#region src/ml/knn/preset.d.ts
+type KnnDataset = 'blobs' | 'xor' | 'circles';
+interface KnnProps {
+  dataset?: KnnDataset;
+  k?: number;
+  seed?: number;
+  title?: string;
+  prompt?: string;
+  objectives?: string[];
+  hints?: string[];
+  controlId?: string;
+  height?: number;
+}
+declare function KNNBoundaryLab({
+  dataset,
+  k,
+  seed,
+  title,
+  prompt,
+  objectives,
+  hints: hintList,
+  controlId,
+  height
+}: KnnProps): ReactNode;
+//#endregion
+export { KNNBoundaryLab, KnnDataset, KnnProps };