qlm-measure 0.1.0

package/LICENSE

@@ -0,0 +1,54 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity.
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+      "Source" form shall mean the preferred form for making modifications.
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form.
+      "Work" shall mean the work of authorship made available under the License.
+      "Derivative Works" shall mean any work that is based on the Work.
+      "Contribution" shall mean any work of authorship submitted to the
+      Licensor for inclusion in the Work.
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4-9. [Standard Apache 2.0 terms apply]
+
+   Copyright 2026 Quantum Learning Machines
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,13 @@
+qlm-measure
+Copyright 2026 Quantum Learning Machines
+
+This product includes software developed at
+Quantum Learning Machines (https://quantumlearningmachines.com).
+
+This SDK provides the public interface layer for the QLM measurement
+infrastructure. The estimation engine (Bayesian posteriors, IRT ability
+estimation, calibration, and cognitive dimension tracking) is a separate
+hosted service operated by Quantum Learning Machines.
+
+The SDK itself (event schema, emitter, verifier, and dataset clients)
+is licensed under the Apache License, Version 2.0.

package/README.md

@@ -0,0 +1,152 @@
+# @qlm/measure
+
+Open measurement SDK for education AI — evidence events, record verification, and dataset clients.
+
+**v0.1.0 · Apache-2.0 · [Documentation](https://play.quantumlearningmachines.com/developer) · [Manifesto](https://play.quantumlearningmachines.com/resources/open-measurement-layer)**
+
+## Limitations (read first)
+
+- This SDK is the **public interface layer**, not the measurement engine. The estimation service (Bayesian posteriors, IRT ability estimation, calibration) is QLM's hosted engine.
+- The verifier checks **bookkeeping integrity**, not estimation correctness. It can tell you if a record was tampered with. It cannot tell you if the posteriors are accurate. That distinction is the design.
+- Evidence event schemas are **v0.1** and may change in minor versions. Pin your dependency.
+- The ontology client requires the QLM API to be reachable. No offline mode.
+- Classifier runners require model weights downloaded separately from Hugging Face.
+
+## What it is
+
+1. **Typed evidence-event vocabulary** (`ObservationEvent`) — a schema any tool can emit to describe a student interaction, with scaffold level, depth, epistemic mode.
+2. **Buffered telemetry emitter** (`MeasurementEmitter`) — sends events to the measurement service with sendBeacon fallback.
+3. **Evidence record format + replay verifier** (`verifyRecord`, `replayToVersion`) — audits a record's hash-chain and posterior-chain integrity without containing any estimation mathematics.
+4. **Dataset clients** (`OntologyClient`) — typed wrappers over the public misconception ontology, learning graph, and standards alignment APIs.
+5. **Engine client** (`EngineClient`) — commercial boundary for the hosted measurement service.
+
+## What it is NOT
+
+- Not the estimation engine (that runs server-side at QLM)
+- Not a standalone learning analytics system
+- Not a replacement for the measurement service
+- Not a classifier or scorer (those are separate open-weights releases)
+
+## Install
+
+```bash
+npm install @qlm/measure
+```
+
+## Quickstart
+
+### 1. Query the misconception ontology (no auth)
+
+```typescript
+import { OntologyClient } from "@qlm/measure/clients";
+
+const client = new OntologyClient();
+const misconceptions = await client.getMisconceptions("math");
+console.log(`${misconceptions.length} math misconceptions`);
+```
+
+### 2. Emit measurement events
+
+```typescript
+import { MeasurementEmitter } from "@qlm/measure/emitter";
+
+const emitter = new MeasurementEmitter({
+  baseUrl: "https://play.quantumlearningmachines.com",
+  product: "my-tool",
+});
+
+emitter.emit({
+  eventType: "answer_submitted",
+  eventCategory: "learning",
+  domain: "math",
+  topic: "fractions",
+  payload: { questionId: "q1", correct: true },
+});
+```
+
+### 3. Verify an evidence record (tamper detection)
+
+```typescript
+import { verifyRecord } from "@qlm/measure/verifier";
+
+const result = verifyRecord(record);
+if (!result.valid) {
+  for (const v of result.violations) {
+    console.log(`[${v.category}] v${v.version}: ${v.message}`);
+  }
+}
+```
+
+## Schema Reference
+
+### ObservationEvent (evidence input)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| studentId | string | yes | Pseudonymous ID (no PII) |
+| sessionId | string | yes | Session identifier |
+| source | string | yes | Source system |
+| timestamp | string | yes | ISO 8601 |
+| correct | boolean | yes | Was the response correct? |
+| responseTimeMs | number | yes | Response time in ms |
+| domain | string | yes | Subject domain |
+| scaffoldType | ScaffoldType | no | What preceded this response |
+| misconceptionId | string | no | Detected misconception ID |
+| classifierConfidence | number | no | Classifier confidence (0-1) |
+| skillId | string | no | Skill being assessed |
+| score | number | no | Response score (0-1) |
+| difficulty | number | no | Item difficulty (0-1) |
+| epistemicMode | EpistemicMode | no | How student arrived at answer |
+| ext | Record | no | Extension namespace |
+
+### Enums
+
+**ScaffoldType:** `none`, `socratic`, `probing`, `metacognitive`, `scaffolding`, `explain`, `hint`, `demonstrate`
+
+**EpistemicMode:** `experience`, `inference`, `analogy`, `testimony`
+
+**DepthLevel:** `surface`, `conceptual`, `transfer`, `integration`
+
+**TriageResult:** `correct`, `slip`, `misconception`, `disengagement`, `ambiguous`
+
+## Verifier
+
+The verifier checks:
+- Schema validity (required fields, correct types)
+- Strictly monotonic version numbers
+- Timestamp monotonicity (configurable tolerance)
+- Hash-chain integrity (prevHash linkage, entryHash recompute)
+- Posterior chain consistency (each prior = previous updated)
+- Compaction-boundary integrity
+- Enum validity
+
+What it deliberately **cannot** check:
+- Whether posteriors are correctly computed (that requires the engine)
+- Whether evidential weights are appropriate (those are calibrated server-side)
+- Whether triage classifications are accurate (those use rules not in this package)
+
+This is the design: **verify instead of trust**.
+
+## Privacy
+
+- `studentId` MUST be a pseudonymous identifier. Never include names, emails, or other PII.
+- Events are buffered locally and sent via sendBeacon/fetch. No cookies are set.
+- The SDK does not store any data persistently.
+
+## Versioning
+
+- Semver from 0.1.0.
+- Schema changes in minor versions (0.2, 0.3).
+- Breaking changes in major versions (1.0).
+- Pin your dependency version.
+
+## Links
+
+- [Developer portal](https://play.quantumlearningmachines.com/developer)
+- [Open Measurement Manifesto](https://play.quantumlearningmachines.com/resources/open-measurement-layer)
+- [Misconception ontology](https://play.quantumlearningmachines.com/developer)
+- [Model cards on Hugging Face](https://huggingface.co/QuantumLearningMachines)
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE).

package/dist/clients/engine-client.d.ts

@@ -0,0 +1,51 @@
+/**
+ * EngineClient — Commercial boundary for the QLM measurement engine.
+ *
+ * The estimation service is QLM's hosted engine. This client wraps the
+ * API for submitting observations and retrieving student model state.
+ *
+ * Authentication is required. Contact QLM for API access.
+ */
+import type { ObservationEvent } from "../schema/observation-event";
+export interface EngineClientConfig {
+    /** Base URL of the QLM measurement service. */
+    baseUrl: string;
+    /** API key for authentication. */
+    apiKey: string;
+}
+export interface ModelStateSummary {
+    studentId: string;
+    totalSessions: number;
+    totalEvidenceEvents: number;
+    lastSessionAt: string | null;
+    /** Top misconceptions with posterior > 0.3 */
+    activeMisconceptions: Array<{
+        id: string;
+        posterior: number;
+        persistence: string;
+        detections: number;
+    }>;
+    /** Triage summary */
+    triage: {
+        correct: number;
+        slips: number;
+        misconceptions: number;
+        disengagements: number;
+    };
+}
+export declare class EngineClient {
+    private readonly config;
+    constructor(config: EngineClientConfig);
+    /**
+     * Submit a student observation to the measurement engine.
+     *
+     * The engine runs the full measurement pipeline and returns
+     * a summary of the updated state.
+     */
+    updateStudentModel(observation: ObservationEvent): Promise<ModelStateSummary>;
+    /**
+     * Retrieve the current model state for a student.
+     */
+    getState(studentId: string): Promise<ModelStateSummary>;
+}
+//# sourceMappingURL=engine-client.d.ts.map

package/dist/clients/engine-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-client.d.ts","sourceRoot":"","sources":["../../src/clients/engine-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAGpE,MAAM,WAAW,kBAAkB;IACjC,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,8CAA8C;IAC9C,oBAAoB,EAAE,KAAK,CAAC;QAC1B,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;IACH,qBAAqB;IACrB,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,cAAc,EAAE,MAAM,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;CACH;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;gBAEhC,MAAM,EAAE,kBAAkB;IAItC;;;;;OAKG;IACG,kBAAkB,CAAC,WAAW,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA0BnF;;OAEG;IACG,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAiB9D"}

package/dist/clients/engine-client.js

@@ -0,0 +1,59 @@
+/**
+ * EngineClient — Commercial boundary for the QLM measurement engine.
+ *
+ * The estimation service is QLM's hosted engine. This client wraps the
+ * API for submitting observations and retrieving student model state.
+ *
+ * Authentication is required. Contact QLM for API access.
+ */
+import { toPublicEpistemicMode } from "../schema/enums";
+export class EngineClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Submit a student observation to the measurement engine.
+     *
+     * The engine runs the full measurement pipeline and returns
+     * a summary of the updated state.
+     */
+    async updateStudentModel(observation) {
+        // Map public epistemic mode to internal at the boundary
+        const mapped = {
+            ...observation,
+            epistemicMode: observation.epistemicMode
+                ? toPublicEpistemicMode(observation.epistemicMode)
+                : undefined,
+        };
+        const response = await fetch(`${this.config.baseUrl}/api/student-model/update`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Authorization": `Bearer ${this.config.apiKey}`,
+            },
+            body: JSON.stringify(mapped),
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => "");
+            throw new Error(`EngineClient.updateStudentModel: ${response.status} ${response.statusText} — ${body}`);
+        }
+        return response.json();
+    }
+    /**
+     * Retrieve the current model state for a student.
+     */
+    async getState(studentId) {
+        const response = await fetch(`${this.config.baseUrl}/api/student-model/state?studentId=${encodeURIComponent(studentId)}`, {
+            headers: {
+                "Authorization": `Bearer ${this.config.apiKey}`,
+            },
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => "");
+            throw new Error(`EngineClient.getState: ${response.status} ${response.statusText} — ${body}`);
+        }
+        return response.json();
+    }
+}
+//# sourceMappingURL=engine-client.js.map

package/dist/clients/engine-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-client.js","sourceRoot":"","sources":["../../src/clients/engine-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AA8BxD,MAAM,OAAO,YAAY;IACN,MAAM,CAAqB;IAE5C,YAAY,MAA0B;QACpC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,kBAAkB,CAAC,WAA6B;QACpD,wDAAwD;QACxD,MAAM,MAAM,GAAG;YACb,GAAG,WAAW;YACd,aAAa,EAAE,WAAW,CAAC,aAAa;gBACtC,CAAC,CAAC,qBAAqB,CAAC,WAAW,CAAC,aAAa,CAAC;gBAClD,CAAC,CAAC,SAAS;SACd,CAAC;QAEF,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,2BAA2B,EAAE;YAC9E,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,eAAe,EAAE,UAAU,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE;aAChD;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;SAC7B,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YACnD,MAAM,IAAI,KAAK,CAAC,oCAAoC,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,MAAM,IAAI,EAAE,CAAC,CAAC;QAC1G,CAAC;QAED,OAAO,QAAQ,CAAC,IAAI,EAAgC,CAAC;IACvD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,QAAQ,CAAC,SAAiB;QAC9B,MAAM,QAAQ,GAAG,MAAM,KAAK,CAC1B,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,sCAAsC,kBAAkB,CAAC,SAAS,CAAC,EAAE,EAC3F;YACE,OAAO,EAAE;gBACP,eAAe,EAAE,UAAU,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE;aAChD;SACF,CACF,CAAC;QAEF,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YACnD,MAAM,IAAI,KAAK,CAAC,0BAA0B,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,MAAM,IAAI,EAAE,CAAC,CAAC;QAChG,CAAC;QAED,OAAO,QAAQ,CAAC,IAAI,EAAgC,CAAC;IACvD,CAAC;CACF"}

package/dist/clients/index.d.ts

@@ -0,0 +1,5 @@
+export { OntologyClient } from "./ontology-client";
+export type { OntologyClientConfig, DatasetName, MisconceptionEntry, LearningGraphNode, StandardAlignment } from "./ontology-client";
+export { EngineClient } from "./engine-client";
+export type { EngineClientConfig, ModelStateSummary } from "./engine-client";
+//# sourceMappingURL=index.d.ts.map

package/dist/clients/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/clients/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,oBAAoB,EAAE,WAAW,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACrI,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/clients/index.js

@@ -0,0 +1,3 @@
+export { OntologyClient } from "./ontology-client";
+export { EngineClient } from "./engine-client";
+//# sourceMappingURL=index.js.map

package/dist/clients/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/clients/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/clients/ontology-client.d.ts

@@ -0,0 +1,57 @@
+/**
+ * OntologyClient — Typed wrapper over the QLM dataset export API.
+ *
+ * Zero-auth. Queries the public misconception ontology, learning graph,
+ * and standards alignment datasets.
+ */
+export type DatasetName = "misconceptions" | "learning-graph" | "standards" | "assistments-alignment";
+export interface OntologyClientConfig {
+    /** Base URL of the QLM API. Default: https://play.quantumlearningmachines.com */
+    baseUrl?: string;
+}
+export interface MisconceptionEntry {
+    id: string;
+    domain: string;
+    topic: string;
+    label: string;
+    description: string;
+    triggerPatterns: string[];
+    correctivePrompts: string[];
+    gradeRange?: string;
+    severity?: string;
+}
+export interface LearningGraphNode {
+    id: string;
+    label: string;
+    domain: string;
+    prerequisites: string[];
+    relatedMisconceptions: string[];
+}
+export interface StandardAlignment {
+    standardCode: string;
+    framework: string;
+    description: string;
+    mappedConstructIds: string[];
+}
+export declare class OntologyClient {
+    private readonly baseUrl;
+    constructor(config?: OntologyClientConfig);
+    /**
+     * Fetch a dataset from the public export API.
+     *
+     * @param dataset The dataset name to fetch.
+     * @param options Optional query parameters (domain, format).
+     * @returns Parsed JSON response.
+     */
+    fetchDataset<T = unknown>(dataset: DatasetName, options?: {
+        domain?: string;
+        format?: string;
+    }): Promise<T>;
+    /** Fetch the misconception ontology. */
+    getMisconceptions(domain?: string): Promise<MisconceptionEntry[]>;
+    /** Fetch the learning graph. */
+    getLearningGraph(domain?: string): Promise<LearningGraphNode[]>;
+    /** Fetch standards alignment data. */
+    getStandards(domain?: string): Promise<StandardAlignment[]>;
+}
+//# sourceMappingURL=ontology-client.d.ts.map

package/dist/clients/ontology-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ontology-client.d.ts","sourceRoot":"","sources":["../../src/clients/ontology-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,WAAW,GACnB,gBAAgB,GAChB,gBAAgB,GAChB,WAAW,GACX,uBAAuB,CAAC;AAE5B,MAAM,WAAW,oBAAoB;IACnC,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,qBAAqB,EAAE,MAAM,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,CAAC,EAAE,oBAAoB;IAIzC;;;;;;OAMG;IACG,YAAY,CAAC,CAAC,GAAG,OAAO,EAC5B,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7C,OAAO,CAAC,CAAC,CAAC;IAiBb,wCAAwC;IAClC,iBAAiB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAIvE,gCAAgC;IAC1B,gBAAgB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAIrE,sCAAsC;IAChC,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;CAGlE"}

package/dist/clients/ontology-client.js

@@ -0,0 +1,47 @@
+/**
+ * OntologyClient — Typed wrapper over the QLM dataset export API.
+ *
+ * Zero-auth. Queries the public misconception ontology, learning graph,
+ * and standards alignment datasets.
+ */
+export class OntologyClient {
+    baseUrl;
+    constructor(config) {
+        this.baseUrl = config?.baseUrl ?? "https://play.quantumlearningmachines.com";
+    }
+    /**
+     * Fetch a dataset from the public export API.
+     *
+     * @param dataset The dataset name to fetch.
+     * @param options Optional query parameters (domain, format).
+     * @returns Parsed JSON response.
+     */
+    async fetchDataset(dataset, options) {
+        const params = new URLSearchParams({ dataset });
+        if (options?.domain)
+            params.set("domain", options.domain);
+        if (options?.format)
+            params.set("format", options.format);
+        const url = `${this.baseUrl}/api/labpath/dataset-export?${params.toString()}`;
+        const response = await fetch(url, {
+            headers: { Accept: "application/json" },
+        });
+        if (!response.ok) {
+            throw new Error(`OntologyClient: ${response.status} ${response.statusText} for ${dataset}`);
+        }
+        return response.json();
+    }
+    /** Fetch the misconception ontology. */
+    async getMisconceptions(domain) {
+        return this.fetchDataset("misconceptions", { domain });
+    }
+    /** Fetch the learning graph. */
+    async getLearningGraph(domain) {
+        return this.fetchDataset("learning-graph", { domain });
+    }
+    /** Fetch standards alignment data. */
+    async getStandards(domain) {
+        return this.fetchDataset("standards", { domain });
+    }
+}
+//# sourceMappingURL=ontology-client.js.map

package/dist/clients/ontology-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ontology-client.js","sourceRoot":"","sources":["../../src/clients/ontology-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwCH,MAAM,OAAO,cAAc;IACR,OAAO,CAAS;IAEjC,YAAY,MAA6B;QACvC,IAAI,CAAC,OAAO,GAAG,MAAM,EAAE,OAAO,IAAI,0CAA0C,CAAC;IAC/E,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,YAAY,CAChB,OAAoB,EACpB,OAA8C;QAE9C,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;QAChD,IAAI,OAAO,EAAE,MAAM;YAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAC1D,IAAI,OAAO,EAAE,MAAM;YAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAE1D,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,+BAA+B,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;QAC9E,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE;SACxC,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,mBAAmB,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,QAAQ,OAAO,EAAE,CAAC,CAAC;QAC9F,CAAC;QAED,OAAO,QAAQ,CAAC,IAAI,EAAgB,CAAC;IACvC,CAAC;IAED,wCAAwC;IACxC,KAAK,CAAC,iBAAiB,CAAC,MAAe;QACrC,OAAO,IAAI,CAAC,YAAY,CAAuB,gBAAgB,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/E,CAAC;IAED,gCAAgC;IAChC,KAAK,CAAC,gBAAgB,CAAC,MAAe;QACpC,OAAO,IAAI,CAAC,YAAY,CAAsB,gBAAgB,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,sCAAsC;IACtC,KAAK,CAAC,YAAY,CAAC,MAAe;QAChC,OAAO,IAAI,CAAC,YAAY,CAAsB,WAAW,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IACzE,CAAC;CACF"}

package/dist/emitter/index.d.ts

@@ -0,0 +1,3 @@
+export { MeasurementEmitter } from "./measurement-emitter";
+export type { EmitterConfig } from "./measurement-emitter";
+//# sourceMappingURL=index.d.ts.map

package/dist/emitter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/emitter/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/emitter/index.js

@@ -0,0 +1,2 @@
+export { MeasurementEmitter } from "./measurement-emitter";
+//# sourceMappingURL=index.js.map

package/dist/emitter/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/emitter/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/emitter/measurement-emitter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Measurement Emitter — Buffered telemetry for the open measurement layer.
+ *
+ * Buffers events and flushes via sendBeacon (browser) or fetch (Node).
+ * Survives page unload. Configurable endpoint and buffer size.
+ */
+import type { MeasurementEvent } from "../schema/measurement-event";
+export interface EmitterConfig {
+    /** Base URL of the measurement service. */
+    baseUrl: string;
+    /** API key for authentication (optional for public endpoints). */
+    apiKey?: string;
+    /** Product identifier. */
+    product?: string;
+    /** Maximum events to buffer before auto-flush. Default: 20. */
+    bufferSize?: number;
+    /** Flush interval in milliseconds. Default: 5000. */
+    flushIntervalMs?: number;
+}
+export declare class MeasurementEmitter {
+    private buffer;
+    private timer;
+    private readonly config;
+    private readonly ingestUrl;
+    constructor(config: EmitterConfig);
+    /** Emit a measurement event. Buffered until flush. */
+    emit(event: MeasurementEvent): void;
+    /** Flush all buffered events to the measurement service. */
+    flush(): void;
+    /** Stop the auto-flush timer. */
+    destroy(): void;
+}
+//# sourceMappingURL=measurement-emitter.d.ts.map

package/dist/emitter/measurement-emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measurement-emitter.d.ts","sourceRoot":"","sources":["../../src/emitter/measurement-emitter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAEpE,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAWD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,MAAM,EAAE,aAAa;IAmBjC,sDAAsD;IACtD,IAAI,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAgBnC,4DAA4D;IAC5D,KAAK,IAAI,IAAI;IA2Cb,iCAAiC;IACjC,OAAO,IAAI,IAAI;CAOhB"}

package/dist/emitter/measurement-emitter.js

@@ -0,0 +1,98 @@
+/**
+ * Measurement Emitter — Buffered telemetry for the open measurement layer.
+ *
+ * Buffers events and flushes via sendBeacon (browser) or fetch (Node).
+ * Survives page unload. Configurable endpoint and buffer size.
+ */
+function generateEventId(product) {
+    return `${product}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+export class MeasurementEmitter {
+    buffer = [];
+    timer = null;
+    config;
+    ingestUrl;
+    constructor(config) {
+        this.config = {
+            baseUrl: config.baseUrl,
+            apiKey: config.apiKey ?? "",
+            product: config.product ?? "external",
+            bufferSize: config.bufferSize ?? 20,
+            flushIntervalMs: config.flushIntervalMs ?? 5000,
+        };
+        this.ingestUrl = `${this.config.baseUrl}/api/measurement/ingest`;
+        // Auto-flush on page visibility change (browser only)
+        if (typeof window !== "undefined") {
+            window.addEventListener("visibilitychange", () => {
+                if (document.visibilityState === "hidden")
+                    this.flush();
+            });
+            window.addEventListener("pagehide", () => this.flush());
+        }
+    }
+    /** Emit a measurement event. Buffered until flush. */
+    emit(event) {
+        this.buffer.push({
+            ...event,
+            event_id: generateEventId(this.config.product),
+            created_at: new Date().toISOString(),
+        });
+        if (this.buffer.length >= this.config.bufferSize) {
+            this.flush();
+        }
+        if (!this.timer) {
+            this.timer = setInterval(() => this.flush(), this.config.flushIntervalMs);
+        }
+    }
+    /** Flush all buffered events to the measurement service. */
+    flush() {
+        if (this.buffer.length === 0)
+            return;
+        const batch = this.buffer.splice(0);
+        const body = JSON.stringify({
+            product: this.config.product,
+            events: batch.map((e) => ({
+                event_id: e.event_id,
+                event_type: e.eventType,
+                event_category: e.eventCategory,
+                session_id: e.sessionId ?? null,
+                classroom_id: e.classroomId ?? null,
+                domain: e.domain ?? null,
+                topic: e.topic ?? null,
+                mode: e.mode ?? null,
+                difficulty: e.difficulty ?? null,
+                payload: e.payload ?? {},
+                quality_signal: e.qualitySignal ?? null,
+                confidence: e.confidence ?? null,
+                duration_ms: e.durationMs ?? null,
+                parent_event_id: e.parentEventId ?? null,
+                created_at: e.created_at,
+            })),
+        });
+        const headers = { "Content-Type": "application/json" };
+        if (this.config.apiKey) {
+            headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+        }
+        // sendBeacon in browser (survives page unload)
+        if (typeof navigator !== "undefined" && navigator.sendBeacon) {
+            navigator.sendBeacon(this.ingestUrl, new Blob([body], { type: "application/json" }));
+        }
+        else {
+            fetch(this.ingestUrl, {
+                method: "POST",
+                headers,
+                body,
+                keepalive: true,
+            }).catch(() => { });
+        }
+    }
+    /** Stop the auto-flush timer. */
+    destroy() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.flush();
+    }
+}
+//# sourceMappingURL=measurement-emitter.js.map

package/dist/emitter/measurement-emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"measurement-emitter.js","sourceRoot":"","sources":["../../src/emitter/measurement-emitter.ts"],"names":[],"mappings":"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"}