@qlm/learnlog-mcp 0.0.0-stage → 0.2.0

package/dist/py.js

@@ -0,0 +1,419 @@
+/**
+ * Python behaviors the preprint's episode scripts depend on, reproduced exactly so that the counts this
+ * package computes are the counts the published Python scripts compute on the same files:
+ * float(), int(float()), round(x, n), datetime.fromisoformat().timestamp(), str ordering, the json
+ * module (raw_decode, NaN, int versus float), re's whitespace and word classes, and the csv module's
+ * excel dialect with strict=False.
+ */
+// ── float() and int(float()) ─────────────────────────────────────────────
+const PY_SPACE = "\\t\\n\\x0b\\x0c\\r\\x1c-\\x1f \\x85\\xa0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000";
+const STRIP = new RegExp(`^[${PY_SPACE}]+|[${PY_SPACE}]+$`, "g");
+const DIGITS = "\\d(?:_?\\d)*";
+const DECIMAL = new RegExp(`^[+-]?(?:${DIGITS}(?:\\.(?:${DIGITS})?)?|\\.${DIGITS})(?:[eE][+-]?${DIGITS})?$`);
+const SPECIAL = /^([+-]?)(nan|inf|infinity)$/i;
+/** Python's float(text) for a str argument. */
+export function pyFloat(text) {
+    const s = text.replace(STRIP, "");
+    const special = SPECIAL.exec(s);
+    if (special) {
+        if (special[2].toLowerCase() === "nan")
+            return NaN;
+        return special[1] === "-" ? -Infinity : Infinity;
+    }
+    if (!DECIMAL.test(s))
+        throw new Error(`could not convert string to float: '${text}'`);
+    return Number(s.replaceAll("_", ""));
+}
+/** Python's int(float(text)). */
+export function pyIntOfFloat(text) {
+    const f = pyFloat(text);
+    if (Number.isNaN(f))
+        throw new Error("cannot convert float NaN to integer");
+    if (!Number.isFinite(f))
+        throw new Error("cannot convert float infinity to integer");
+    return Math.trunc(f) + 0; // + 0 turns -0 into 0, as an int has no sign of zero
+}
+// ── round(x, n) ──────────────────────────────────────────────────────────
+/** Python's round(x, n) for a float: half to even, on the exact binary value. */
+export function pyRound(x, n) {
+    if (!Number.isFinite(x))
+        return x;
+    const view = new DataView(new ArrayBuffer(8));
+    view.setFloat64(0, x);
+    const hi = view.getUint32(0);
+    const lo = view.getUint32(4);
+    const negative = hi >>> 31 === 1;
+    const exponentBits = (hi >>> 20) & 0x7ff;
+    let mantissa = (BigInt(hi & 0xfffff) << 32n) | BigInt(lo);
+    let exponent;
+    if (exponentBits === 0)
+        exponent = -1074;
+    else {
+        mantissa |= 1n << 52n;
+        exponent = exponentBits - 1075;
+    }
+    if (exponent >= 0)
+        return x; // already an integer
+    const scaled = mantissa * 10n ** BigInt(n);
+    const divisor = 1n << BigInt(-exponent);
+    let q = scaled / divisor;
+    const twice = (scaled % divisor) * 2n;
+    if (twice > divisor || (twice === divisor && q % 2n === 1n))
+        q += 1n;
+    const result = Number(`${q}e-${n}`);
+    return negative ? -result : result;
+}
+// ── datetime.fromisoformat(text).timestamp() ─────────────────────────────
+const ISO = /^(\d{4})-(\d{2})-(\d{2})(?:[\s\S](\d{2})(?::(\d{2})(?::(\d{2})(?:[.,](\d+))?)?)?(Z|[+-]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,6})?)?)?)?$/u;
+function utcMillis(year, month, day, hour, minute, second) {
+    const d = new Date(0);
+    d.setUTCFullYear(year, month - 1, day);
+    d.setUTCHours(hour, minute, second, 0);
+    return d.getTime();
+}
+/** Python 3.11+ datetime.fromisoformat(text).timestamp(). A time without an offset is local time, as in Python. */
+export function pyIsoTimestamp(text) {
+    const m = ISO.exec(text);
+    const invalid = () => new Error(`Invalid isoformat string: '${text}'`);
+    if (!m)
+        throw invalid();
+    const [year, month, day] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    const [hour, minute, second] = [Number(m[4] ?? 0), Number(m[5] ?? 0), Number(m[6] ?? 0)];
+    const micro = Number((m[7] ?? "").slice(0, 6).padEnd(6, "0"));
+    const check = new Date(0);
+    check.setUTCFullYear(year, month - 1, day);
+    if (month < 1 || month > 12 || check.getUTCMonth() !== month - 1 || hour > 23 || minute > 59 || second > 59)
+        throw invalid();
+    const zone = m[8];
+    if (zone === undefined) {
+        const local = new Date(2000, 0, 1);
+        local.setFullYear(year, month - 1, day);
+        local.setHours(hour, minute, second, 0);
+        return local.getTime() / 1000 + micro / 1e6;
+    }
+    let offsetMicros = 0;
+    if (zone !== "Z") {
+        const sign = zone.startsWith("-") ? -1 : 1;
+        const [oh, om, os] = zone.slice(1).split(":");
+        const [whole, fraction] = (os ?? "0").split(".");
+        offsetMicros = sign * ((Number(oh) * 3600 + Number(om) * 60 + Number(whole)) * 1e6 + Number((fraction ?? "").padEnd(6, "0")));
+        if (Math.abs(offsetMicros) >= 86400e6)
+            throw invalid(); // Python normalizes minutes and seconds over 59
+    }
+    const micros = utcMillis(year, month, day, hour, minute, second) * 1000 + micro - offsetMicros;
+    return micros / 1e6;
+}
+// ── str ordering ─────────────────────────────────────────────────────────
+/** Python's ordering of str values: by code point, which differs from JavaScript's UTF-16 order above U+FFFF. */
+export function compareCodePoints(a, b) {
+    const x = Array.from(a);
+    const y = Array.from(b);
+    for (let i = 0; i < Math.min(x.length, y.length); i++) {
+        const d = x[i].codePointAt(0) - y[i].codePointAt(0);
+        if (d !== 0)
+            return d < 0 ? -1 : 1;
+    }
+    return x.length === y.length ? 0 : x.length < y.length ? -1 : 1;
+}
+// ── re.search for the two eventsData patterns ────────────────────────────
+const PATTERNS = {
+    /** cross_source.py: re.search(r"eventsData\s*=\s*", h) */
+    eventsData: new RegExp(`eventsData[${PY_SPACE}]*=[${PY_SPACE}]*`, "u"),
+    /** aggregate.py: re.search(r"\bconst\s+eventsData\s*=\s*", text) */
+    constEventsData: new RegExp(`(?<![\\p{L}\\p{N}_])const[${PY_SPACE}]+eventsData[${PY_SPACE}]*=[${PY_SPACE}]*`, "u"),
+};
+/** The end index of the first match of one of the scripts' patterns (Python's match.end()), or -1. */
+export function findPy(text, pattern) {
+    const m = PATTERNS[pattern].exec(text);
+    return m ? m.index + m[0].length : -1;
+}
+// ── json ─────────────────────────────────────────────────────────────────
+const kinds = new WeakMap();
+/** Whether a number member was written as an int or a float in the JSON text. */
+export function numberKind(container, key) {
+    return kinds.get(container)?.get(key);
+}
+/** type(obj.get(key)).__name__ as Python would print it for a value decoded by the json module. */
+export function pyTypeName(container, key) {
+    const v = Object.hasOwn(container, key) ? container[key] : null;
+    if (v === null || v === undefined)
+        return "NoneType";
+    if (typeof v === "number")
+        return numberKind(container, key) ?? (Number.isInteger(v) ? "int" : "float");
+    if (typeof v === "string")
+        return "str";
+    if (typeof v === "boolean")
+        return "bool";
+    return Array.isArray(v) ? "list" : "dict";
+}
+const NUMBER = /-?(?:0|[1-9]\d*)(\.\d+)?([eE][-+]?\d+)?/y;
+const ESC = { '"': '"', "\\": "\\", "/": "/", b: "\b", f: "\f", n: "\n", r: "\r", t: "\t" };
+/**
+ * Python's json.JSONDecoder().raw_decode(text, start): the first JSON value starting exactly at
+ * `start` (no whitespace is skipped there), and the index just after it.
+ */
+export function parsePyJson(text, start = 0) {
+    let i = start;
+    const fail = (what) => {
+        throw new Error(`JSON: ${what} at ${i}`);
+    };
+    const ws = () => {
+        for (let c = text.charCodeAt(i); c === 32 || c === 9 || c === 10 || c === 13; c = text.charCodeAt(++i))
+            ;
+    };
+    const str = () => {
+        i++;
+        let out = "";
+        let run = i;
+        for (;;) {
+            if (i >= text.length)
+                fail("unterminated string");
+            const c = text.charCodeAt(i);
+            if (c === 34) {
+                out += text.slice(run, i);
+                i++;
+                return out;
+            }
+            if (c < 32)
+                fail("invalid control character");
+            if (c === 92) {
+                out += text.slice(run, i);
+                const e = text[i + 1] ?? "";
+                if (e === "u") {
+                    const hex = text.slice(i + 2, i + 6);
+                    if (!/^[0-9a-fA-F]{4}$/.test(hex))
+                        fail("invalid \\uXXXX escape");
+                    out += String.fromCharCode(parseInt(hex, 16));
+                    i += 6;
+                }
+                else {
+                    if (!Object.hasOwn(ESC, e))
+                        fail("invalid \\escape");
+                    out += ESC[e];
+                    i += 2;
+                }
+                run = i;
+                continue;
+            }
+            i++;
+        }
+    };
+    const value = () => {
+        const c = text[i];
+        if (c === "{") {
+            i++;
+            const obj = {};
+            const k = new Map();
+            kinds.set(obj, k);
+            ws();
+            if (text[i] === "}") {
+                i++;
+                return obj;
+            }
+            for (;;) {
+                if (text[i] !== '"')
+                    fail("expecting property name enclosed in double quotes");
+                const key = str();
+                ws();
+                if (text[i] !== ":")
+                    fail("expecting ':' delimiter");
+                i++;
+                ws();
+                const at = i;
+                const v = value();
+                Object.defineProperty(obj, key, { value: v, enumerable: true, writable: true, configurable: true });
+                if (typeof v === "number") {
+                    NUMBER.lastIndex = at;
+                    const m = NUMBER.exec(text);
+                    k.set(key, m && m.index === at && m[1] === undefined && m[2] === undefined ? "int" : "float");
+                }
+                else
+                    k.delete(key);
+                ws();
+                if (text[i] === "}") {
+                    i++;
+                    return obj;
+                }
+                if (text[i] !== ",")
+                    fail("expecting ',' delimiter");
+                i++;
+                ws();
+            }
+        }
+        if (c === "[") {
+            i++;
+            const arr = [];
+            ws();
+            if (text[i] === "]") {
+                i++;
+                return arr;
+            }
+            for (;;) {
+                arr.push(value());
+                ws();
+                if (text[i] === "]") {
+                    i++;
+                    return arr;
+                }
+                if (text[i] !== ",")
+                    fail("expecting ',' delimiter");
+                i++;
+                ws();
+            }
+        }
+        if (c === '"')
+            return str();
+        for (const [word, v] of [["null", null], ["true", true], ["false", false], ["NaN", NaN], ["Infinity", Infinity], ["-Infinity", -Infinity]]) {
+            if (text.startsWith(word, i)) {
+                i += word.length;
+                return v;
+            }
+        }
+        NUMBER.lastIndex = i;
+        const m = NUMBER.exec(text);
+        if (!m)
+            return fail("expecting value");
+        i += m[0].length;
+        const n = Number(m[0]);
+        return m[1] === undefined && m[2] === undefined ? n + 0 : n;
+    };
+    const v = value();
+    return { value: v, end: i };
+}
+/** Python's json.loads(text): whitespace around one value, and nothing else. */
+export function loadsPyJson(text) {
+    let i = 0;
+    while (" \t\n\r".includes(text[i] ?? "x"))
+        i++;
+    const { value, end } = parsePyJson(text, i);
+    let j = end;
+    while (" \t\n\r".includes(text[j] ?? "x"))
+        j++;
+    if (j !== text.length)
+        throw new Error(`JSON: extra data at ${j}`);
+    return value;
+}
+// ── csv ──────────────────────────────────────────────────────────────────
+const FIELD_LIMIT = 131072;
+/**
+ * Python's csv.reader with the excel dialect and strict=False, fed text in chunks. Blank lines are
+ * dropped, as csv.DictReader drops them. A field over Python's default limit of 131072 characters
+ * raises the error Python raises.
+ */
+export class PyCsv {
+    state = 0 /* S.StartRecord */;
+    field = "";
+    row = [];
+    push(chunk) {
+        const rows = [];
+        let i = 0;
+        const n = chunk.length;
+        const add = (s) => {
+            if (this.field.length + s.length > FIELD_LIMIT)
+                throw new Error(`field larger than field limit (${FIELD_LIMIT})`);
+            this.field += s;
+        };
+        const save = () => {
+            this.row.push(this.field);
+            this.field = "";
+        };
+        const endRow = () => {
+            save();
+            rows.push(this.row);
+            this.row = [];
+        };
+        while (i < n) {
+            const c = chunk.charCodeAt(i);
+            switch (this.state) {
+                case 0 /* S.StartRecord */:
+                case 5 /* S.EatCrnl */:
+                    if (c === 13 || c === 10) {
+                        this.state = 5 /* S.EatCrnl */;
+                        i++;
+                        break;
+                    }
+                    this.state = 1 /* S.StartField */;
+                    break;
+                case 1 /* S.StartField */:
+                    if (c === 34)
+                        this.state = 3 /* S.InQuoted */;
+                    else if (c === 44)
+                        save();
+                    else if (c === 13 || c === 10) {
+                        endRow();
+                        this.state = 5 /* S.EatCrnl */;
+                    }
+                    else
+                        this.state = 2 /* S.InField */;
+                    if (this.state !== 2 /* S.InField */)
+                        i++;
+                    break;
+                case 2 /* S.InField */: {
+                    let j = i;
+                    while (j < n) {
+                        const d = chunk.charCodeAt(j);
+                        if (d === 44 || d === 13 || d === 10)
+                            break;
+                        j++;
+                    }
+                    add(chunk.slice(i, j));
+                    i = j;
+                    if (i < n) {
+                        if (chunk.charCodeAt(i) === 44) {
+                            save();
+                            this.state = 1 /* S.StartField */;
+                        }
+                        else {
+                            endRow();
+                            this.state = 5 /* S.EatCrnl */;
+                        }
+                        i++;
+                    }
+                    break;
+                }
+                case 3 /* S.InQuoted */: {
+                    const j = chunk.indexOf('"', i);
+                    const stop = j < 0 ? n : j;
+                    add(chunk.slice(i, stop));
+                    i = stop;
+                    if (j >= 0) {
+                        this.state = 4 /* S.QuoteInQuoted */;
+                        i++;
+                    }
+                    break;
+                }
+                case 4 /* S.QuoteInQuoted */:
+                    if (c === 34) {
+                        add('"');
+                        this.state = 3 /* S.InQuoted */;
+                        i++;
+                    }
+                    else if (c === 44) {
+                        save();
+                        this.state = 1 /* S.StartField */;
+                        i++;
+                    }
+                    else if (c === 13 || c === 10) {
+                        endRow();
+                        this.state = 5 /* S.EatCrnl */;
+                        i++;
+                    }
+                    else
+                        this.state = 2 /* S.InField */;
+                    break;
+            }
+        }
+        return rows;
+    }
+    /** The last record, when the text does not end with a newline. */
+    end() {
+        if (this.state === 0 /* S.StartRecord */ || this.state === 5 /* S.EatCrnl */)
+            return [];
+        this.row.push(this.field);
+        const last = this.row;
+        this.row = [];
+        this.field = "";
+        this.state = 0 /* S.StartRecord */;
+        return [last];
+    }
+}

package/dist/respond.js

@@ -0,0 +1,47 @@
+/**
+ * How every tool answers. An answer is JSON text, passes through the sealed-content filter, and must
+ * carry does_not_show: what the answer cannot tell you. A refusal is an error result with one plain reason.
+ */
+import { Refusal } from "./files.js";
+import { withholdSealed } from "./sealed.js";
+/**
+ * The most characters of JSON text one answer may carry. Assistants take in only so much at once:
+ * Claude Code warns above about 10,000 tokens and rejects above 25,000. 30,000 characters stays under the warning.
+ */
+export const ANSWER_BUDGET = 30_000;
+const n = (x) => x.toLocaleString("en-US");
+export function answer(body) {
+    const limits = body.does_not_show;
+    if (!Array.isArray(limits) || limits.length === 0)
+        throw new Error("every answer must say what it does not show (does_not_show)");
+    const text = sealedText(body);
+    if (text.length > ANSWER_BUDGET)
+        return refuse(`This answer would be ${n(text.length)} characters, more than the ${n(ANSWER_BUDGET)} an assistant can take in at once. Ask for less: a smaller limit, one direction, or fewer kinds.`);
+    return { content: [{ type: "text", text }] };
+}
+/** How many characters of JSON text this body's answer would be (after the sealed-content filter). */
+export function answerSize(body) {
+    return sealedText(body).length;
+}
+/** The answer's JSON text after the sealed-content filter, with what was withheld named. */
+function sealedText(body) {
+    const { value, withheld } = withholdSealed(body);
+    const out = value;
+    if (withheld.length)
+        out.sealed_content_withheld = withheld;
+    return JSON.stringify(out, null, 2);
+}
+export function refuse(message) {
+    return { content: [{ type: "text", text: JSON.stringify({ error: message }, null, 2) }], isError: true };
+}
+/** Runs a tool body and turns what it throws into a refusal. */
+export async function guard(body) {
+    try {
+        return answer(await body());
+    }
+    catch (e) {
+        if (e instanceof Refusal)
+            return refuse(e.message);
+        return refuse(`Unexpected error: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}

package/dist/sealed.js

@@ -0,0 +1,31 @@
+/**
+ * Sealed content (answer keys, sealed case variants) never appears in a tool's output. Every answer
+ * passes through withholdSealed, which replaces the value of any member with one of these names, at
+ * any depth, and reports where it did so.
+ */
+const SEALED = new Set([
+    "answerkey", "answerkeys", "correctanswer", "correctanswers", "expectedanswer", "expectedanswers", "solutionkey", "solutionkeys",
+    "sealed", "sealedvariant", "sealedvariants", "sealedcase", "sealedcases", "sealedcontent", "sealeditem", "sealeditems", "sealedanswer", "sealedanswers",
+]);
+export const WITHHELD = "[withheld: sealed content]";
+const isSealed = (key) => SEALED.has(key.toLowerCase().replace(/[^a-z0-9]/g, ""));
+const member = (path, key) => (/^[A-Za-z_$][\w$]*$/.test(key) ? `${path}.${key}` : `${path}[${JSON.stringify(key)}]`);
+export function withholdSealed(value) {
+    const withheld = [];
+    const walk = (v, path) => {
+        if (Array.isArray(v))
+            return v.map((x, i) => walk(x, `${path}[${i}]`));
+        if (v === null || typeof v !== "object")
+            return v;
+        const out = {};
+        for (const [k, x] of Object.entries(v)) {
+            // defineProperty keeps a member named "__proto__" (source text can use any name) as data.
+            const sealed = isSealed(k);
+            if (sealed)
+                withheld.push(member(path, k));
+            Object.defineProperty(out, k, { value: sealed ? WITHHELD : walk(x, member(path, k)), enumerable: true, writable: true, configurable: true });
+        }
+        return out;
+    };
+    return { value: walk(value, "$"), withheld };
+}

package/dist/server.js

@@ -0,0 +1,115 @@
+/**
+ * The Learnlog MCP server: six read-only tools over stdio. Five run on this machine and read local
+ * files only. verify_credential sends one request to app.qlmdev.com. Nothing is uploaded or written.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { NAME, VERSION } from "./package.js";
+import { guard } from "./respond.js";
+import { LEARNLOG_DRAFT } from "./stages.js";
+import { learnlogFormats } from "./tools/formats.js";
+import { assistanceInventory } from "./tools/inventory.js";
+import { learnlogTransform } from "./tools/transform.js";
+import { learnlogValidate } from "./tools/validate.js";
+import { verifyCredential } from "./tools/verify-credential.js";
+import { verifyEvidence } from "./tools/verify-evidence.js";
+import { EDGE_KINDS, qlmLearningGraph } from "./tools/learning-graph.js";
+import { qlmMisconceptions } from "./tools/misconceptions.js";
+import { DatasetClient } from "./tools/qlm-datasets.js";
+import { FORMAT_IDS } from "./transformer.js";
+export const TOOL_NAMES = ["learnlog_formats", "learnlog_transform", "learnlog_validate", "assistance_inventory", "verify_evidence", "verify_credential", "qlm_misconceptions", "qlm_learning_graph"];
+const INSTRUCTIONS = `Learnlog MCP answers questions about what learning records actually show about help, using Learnlog (${LEARNLOG_DRAFT}). Keep the six assistance stages apart: requested, offered, generated, transmitted, displayed, accepted. One never implies the next. A stage that wasn't captured is "not recorded", never "none" or zero. Every answer has a does_not_show list: pass those limits on to the person. All tools are read-only. Five read local files only. verify_credential sends one request to app.qlmdev.com; qlm_misconceptions and qlm_learning_graph read QLM's public LabPath datasets from play.quantumlearningmachines.com.`;
+const LOCAL = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const path = (what) => z.string().describe(`Full path to ${what} on this computer (absolute, or starting with ~/).`);
+export function createServer(options = {}) {
+    const server = new McpServer({ name: NAME, version: VERSION }, { instructions: INSTRUCTIONS });
+    const datasets = new DatasetClient(options.fetch);
+    const NETWORK = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
+    server.registerTool("learnlog_formats", {
+        title: "Learnlog formats",
+        description: "Which exports can I convert to Learnlog? Lists the transformer's source formats, what each one records at each of the six assistance stages, its bundled public sample, and the three released datasets the Learnlog preprint uses. No input.",
+        inputSchema: {},
+        annotations: LOCAL,
+    }, async () => guard(() => learnlogFormats()));
+    server.registerTool("learnlog_transform", {
+        title: "Transform to Learnlog",
+        description: "Turn an export into Learnlog records, keeping source and capture details. Give a format (see learnlog_formats) and either a local file path or use_sample: true for the format's bundled public sample. Returns a summary, the records' hash-chain heads, the unknowns they keep and a preview; set include_document for the whole Learnlog document, which comes back only when it fits in one answer (small exports). Nothing is written to disk.",
+        inputSchema: {
+            format: z.enum(FORMAT_IDS).describe("The source format."),
+            path: path("the export file").optional(),
+            use_sample: z.boolean().optional().describe("Use the format's bundled public sample instead of a file."),
+            tenant: z.string().min(1).max(200).optional().describe("A scope name for the learner pseudonyms. Default: local."),
+            include_document: z.boolean().optional().describe("Return the whole Learnlog document if it fits in one answer; otherwise its size is reported instead."),
+        },
+        annotations: LOCAL,
+    }, async (args) => guard(() => learnlogTransform(args)));
+    server.registerTool("learnlog_validate", {
+        title: "Validate Learnlog",
+        description: "Is this a valid Learnlog file? Replays each record's hash chain and checks the transformer's profile bindings, then lists errors, warnings and the unknowns each record keeps (for example source time, capture coverage or model version not recorded).",
+        inputSchema: { path: path("the Learnlog JSON file") },
+        annotations: LOCAL,
+    }, async (args) => guard(() => learnlogValidate(args)));
+    server.registerTool("assistance_inventory", {
+        title: "Assistance inventory",
+        description: "What does this dataset actually record about help? Reports, for each source, which of the six assistance stages are recorded (requested, offered, generated, transmitted, displayed, accepted), the counts, and what can't be concluded. Three ways to use it: (1) an export: format with path or use_sample: true; (2) a Learnlog file: learnlog_path; (3) the Learnlog preprint's released datasets, from your own copies: zenodo_zip, idetrace_json (with allow_idetrace_research: true), assistments_csv, which recomputes the preprint's inventory and episode counts and compares them with the published numbers when the files are the pinned releases. With no input it returns the preprint's published figures, labeled as not recomputed.",
+        inputSchema: {
+            format: z.enum(FORMAT_IDS).optional().describe("The export's format, with path or use_sample."),
+            path: path("the export file").optional(),
+            use_sample: z.boolean().optional().describe("Use the format's bundled public sample."),
+            tenant: z.string().min(1).max(200).optional(),
+            learnlog_path: path("a Learnlog JSON file").optional(),
+            zenodo_zip: path("the Zenodo 17551130 archive (ai_hints_interaction.zip)").optional(),
+            idetrace_json: path("IDETrace dataset/raw_telemetry/deployment_8.json").optional(),
+            allow_idetrace_research: z.boolean().optional().describe("Required to read the IDETrace file: it holds learner telemetry with unclear redistribution terms. Only counts are returned."),
+            assistments_csv: path("the ASSISTments 2012-13 School Data with Affect CSV").optional(),
+        },
+        annotations: LOCAL,
+    }, async (args) => guard(() => assistanceInventory(args)));
+    server.registerTool("verify_evidence", {
+        title: "Verify evidence",
+        description: "Can I trust this result? Replays a local evidence record or product hash chain with qlm-measure's own verifier and returns pass, or each named check that failed and where. kind: record (default), chain (with family or scheme), or list_schemes.",
+        inputSchema: {
+            path: path("the evidence record or chain JSON").optional(),
+            kind: z.enum(["record", "chain", "list_schemes"]).optional(),
+            family: z.string().min(1).optional().describe("Chain family, for example tpc/clinical."),
+            scheme: z.string().min(1).optional().describe("Exact chain scheme, for example tpc/clinical-v2."),
+            allow_mixed: z.boolean().optional().describe("Allow a chain that mixes scheme versions."),
+        },
+        annotations: LOCAL,
+    }, async (args) => guard(() => verifyEvidence(args)));
+    server.registerTool("verify_credential", {
+        title: "Verify a QLM credential",
+        description: "Is this QLM credential real and current? Give its ID (urn:uuid:...) or a link that contains it. Sends one request to https://app.qlmdev.com/v1/verify and returns whether it verified, each check with its result, the issuer, the achievement, the date and the AI-help summary by stage. The report has no personal data.",
+        inputSchema: { credential: z.string().min(1).max(2048).describe("The credential ID, or a link containing it.") },
+        annotations: NETWORK,
+    }, async (args) => guard(() => verifyCredential(args, options.fetch)));
+    server.registerTool("qlm_misconceptions", {
+        title: "QLM misconceptions",
+        description: "Which student misconception might be behind this? Searches QLM's public, research-based misconception dataset (LabPath Dataset v1.0, CC BY 4.0) by search words, domain, grade band or id. Returns each misconception's student belief, the scientific reality, a counterexample, a teacher intervention, its research source, severity, grade bands and LabPath modes, with the citation. Reads https://play.quantumlearningmachines.com once per session.",
+        inputSchema: {
+            search: z.string().max(200).optional().describe("Words that must all appear, for example: force motion."),
+            domain: z.string().max(50).optional().describe("For example physics, chemistry, biology, math, cs, health."),
+            grade_band: z.string().max(30).optional().describe("For example K-2, 3-5, 6-8, 9-12, postsecondary."),
+            id: z.string().max(50).optional().describe("A misconception id, for example from qlm_learning_graph."),
+            limit: z.number().int().min(1).max(50).optional().describe("How many to return. Default 10."),
+        },
+        annotations: NETWORK,
+    }, async (args) => guard(() => qlmMisconceptions(args, datasets)));
+    server.registerTool("qlm_learning_graph", {
+        title: "QLM learning graph",
+        description: "What comes before or after this LabPath activity? Give a LabPath mode id (from qlm_misconceptions) or a standard code. Returns the linked activities in LabPath's designed learning graph, with the teacher-facing reason for each link, its first 8 concepts, the misconception ids it carries, the full standards for the asked-about activity, and the standard codes of each linked one. Reads https://play.quantumlearningmachines.com once per session.",
+        inputSchema: {
+            mode_id: z.string().min(1).max(100).optional().describe("A LabPath mode id, for example from a misconception's modes."),
+            standard: z.string().min(1).max(50).optional().describe("A standard code, for example HS-PS2-1."),
+            direction: z.enum(["before", "after", "both"]).optional().describe("Default both."),
+            kinds: z.array(z.enum(EDGE_KINDS)).min(1).optional().describe("Edge kinds to include. Default all."),
+            limit: z.number().int().min(1).max(50).optional().describe("Most edges per direction. Default 10. Lowered, and said so, if the answer would not fit."),
+        },
+        annotations: NETWORK,
+    }, async (args) => guard(() => qlmLearningGraph(args, datasets)));
+    return server;
+}
+export async function start() {
+    await createServer().connect(new StdioServerTransport());
+}

package/dist/stages.js

@@ -0,0 +1,35 @@
+/**
+ * The six assistance observations of draft-srivastava-learnlog-03, Section 2.2. Each is its own
+ * observation: one never implies the next, and a stage that wasn't captured is "not recorded".
+ */
+export const LEARNLOG_DRAFT = "draft-srivastava-learnlog-03 (IETF Internet-Draft, work in progress)";
+export const STAGES = [
+    { stage: "requested", meaning: "A learner or other identified actor asked for assistance. A request doesn't show that help was produced." },
+    { stage: "offered", meaning: "The instrument recorded a system or another identified actor starting assistance, for example steps given after a wrong answer. An offer doesn't show that help was displayed." },
+    { stage: "generated", meaning: "A system produced assistance content. Generation doesn't show that it was sent or displayed." },
+    { stage: "transmitted", meaning: "The instrument recorded assistance being sent to a stated destination. Sending doesn't show display or use." },
+    { stage: "displayed", meaning: "The instrument recorded assistance being shown in a stated interface. Display doesn't show attention, understanding or learning." },
+    { stage: "accepted", meaning: "The instrument recorded the action the product defines as accepting assistance. That doesn't by itself show use, agreement or learning." },
+];
+export const STAGE_IDS = STAGES.map((s) => s.stage);
+export const NOT_RECORDED = "not recorded";
+/** The transformer's lifecycle event types, and the stage each one asserts. offered and accepted have none. */
+export const TRANSFORMER_EVENT_STAGE = {
+    help_requested: "requested",
+    help_generated: "generated",
+    help_transmitted: "transmitted",
+    help_displayed: "displayed",
+};
+/** The past participle for "no help was ___" in a stage's note. */
+export const STAGE_VERB = {
+    requested: "asked for",
+    offered: "offered",
+    generated: "generated",
+    transmitted: "sent",
+    displayed: "shown",
+    accepted: "accepted",
+};
+/** An object with one value per stage, in the draft's order. */
+export function byStage(value) {
+    return Object.fromEntries(STAGE_IDS.map((s) => [s, value(s)]));
+}