qlm-measure 0.1.0__tar.gz

qlm_measure-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: qlm-measure
+Version: 0.1.0
+Summary: Open measurement SDK for education AI — evidence events, record verification, and dataset clients
+Author: Quantum Learning Machines
+License: Apache-2.0
+Project-URL: Homepage, https://play.quantumlearningmachines.com/developer
+Project-URL: Repository, https://github.com/quantumkumar/qlm-measure
+Keywords: education,measurement,evidence,learning-analytics,misconceptions
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# @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).

qlm_measure-0.1.0/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).

qlm_measure-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qlm-measure"
+version = "0.1.0"
+description = "Open measurement SDK for education AI — evidence events, record verification, and dataset clients"
+readme = "README.md"
+license = {text = "Apache-2.0"}
+requires-python = ">=3.9"
+authors = [{name = "Quantum Learning Machines"}]
+keywords = ["education", "measurement", "evidence", "learning-analytics", "misconceptions"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Education",
+    "Topic :: Scientific/Engineering",
+]
+
+[project.urls]
+Homepage = "https://play.quantumlearningmachines.com/developer"
+Repository = "https://github.com/quantumkumar/qlm-measure"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["qlm_measure*"]

qlm_measure-0.1.0/qlm_measure/__init__.py

@@ -0,0 +1,27 @@
+"""
+qlm-measure — Open measurement SDK for education AI.
+
+Python mirror of @qlm/measure (npm). Provides:
+- Evidence event schema (ObservationEvent, MeasurementEvent)
+- Evidence record format + verifier
+- Dataset clients (OntologyClient)
+- Engine client (EngineClient, commercial boundary)
+
+Apache-2.0 · v0.1.0
+"""
+
+__version__ = "0.1.0"
+
+from .schema import (
+    ObservationEvent,
+    MeasurementEvent,
+    EvidenceEntry,
+    EvidenceRecord,
+    ScaffoldType,
+    EpistemicMode,
+    DepthLevel,
+    TriageResult,
+    COMPACTION_RETENTION,
+)
+from .verifier import verify_record, replay_to_version, posterior_at_version
+from .clients import OntologyClient, EngineClient

qlm_measure-0.1.0/qlm_measure/clients.py

@@ -0,0 +1,79 @@
+"""
+Dataset and engine clients — Python mirror.
+"""
+
+from __future__ import annotations
+import json
+from typing import Any, Optional
+from urllib.request import urlopen, Request
+from urllib.parse import urlencode
+
+
+class OntologyClient:
+    """Typed wrapper over the QLM dataset export API. Zero-auth."""
+
+    def __init__(self, base_url: str = "https://play.quantumlearningmachines.com"):
+        self.base_url = base_url
+
+    def fetch_dataset(
+        self,
+        dataset: str,
+        domain: Optional[str] = None,
+        fmt: Optional[str] = None,
+    ) -> Any:
+        params = {"dataset": dataset}
+        if domain:
+            params["domain"] = domain
+        if fmt:
+            params["format"] = fmt
+
+        url = f"{self.base_url}/api/labpath/dataset-export?{urlencode(params)}"
+        req = Request(url, headers={"Accept": "application/json"})
+        with urlopen(req) as resp:
+            return json.loads(resp.read().decode())
+
+    def get_misconceptions(self, domain: Optional[str] = None) -> list[dict]:
+        data = self.fetch_dataset("misconceptions", domain=domain)
+        return data.get("misconceptions", data) if isinstance(data, dict) else data
+
+    def get_learning_graph(self, domain: Optional[str] = None) -> list[dict]:
+        data = self.fetch_dataset("learning-graph", domain=domain)
+        return data.get("learningGraph", data) if isinstance(data, dict) else data
+
+    def get_standards(self, domain: Optional[str] = None) -> list[dict]:
+        data = self.fetch_dataset("standards", domain=domain)
+        return data.get("standardsAlignment", data) if isinstance(data, dict) else data
+
+
+class 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 state.
+    """
+
+    def __init__(self, base_url: str, api_key: str):
+        self.base_url = base_url
+        self.api_key = api_key
+
+    def _request(self, method: str, path: str, body: Optional[dict] = None) -> dict:
+        url = f"{self.base_url}{path}"
+        data = json.dumps(body).encode() if body else None
+        req = Request(
+            url,
+            data=data,
+            method=method,
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.api_key}",
+            },
+        )
+        with urlopen(req) as resp:
+            return json.loads(resp.read().decode())
+
+    def update_student_model(self, observation: dict) -> dict:
+        return self._request("POST", "/api/student-model/update", observation)
+
+    def get_state(self, student_id: str) -> dict:
+        return self._request("GET", f"/api/student-model/state?studentId={student_id}")

qlm_measure-0.1.0/qlm_measure/schema.py

@@ -0,0 +1,126 @@
+"""
+Public event schema — Python mirror of TypeScript types.
+
+All types are TypedDict for structural typing without runtime overhead.
+"""
+
+from __future__ import annotations
+from typing import TypedDict, Literal, Optional, Any
+
+# ── Enums (as Literal unions) ─────────────────────────────────────────────────
+
+ScaffoldType = Literal[
+    "none", "socratic", "probing", "metacognitive",
+    "scaffolding", "explain", "hint", "demonstrate",
+]
+
+EpistemicMode = Literal["experience", "inference", "analogy", "testimony"]
+
+DepthLevel = Literal["surface", "conceptual", "transfer", "integration"]
+
+TriageResult = Literal["correct", "slip", "misconception", "disengagement", "ambiguous"]
+
+EventCategory = Literal["learning", "teaching", "assessment", "interaction", "system"]
+
+COMPACTION_RETENTION = 500
+
+# ── Internal -> Public mapping ────────────────────────────────────────────────
+
+_EPISTEMIC_MAP = {
+    "direct": "experience",
+    "reason": "inference",
+    "compare": "analogy",
+    "told": "testimony",
+    "experience": "experience",
+    "inference": "inference",
+    "analogy": "analogy",
+    "testimony": "testimony",
+}
+
+
+def to_public_epistemic_mode(value: str) -> EpistemicMode:
+    return _EPISTEMIC_MAP.get(value, "testimony")  # type: ignore[return-value]
+
+
+# ── ObservationEvent ──────────────────────────────────────────────────────────
+
+class ObservationEvent(TypedDict, total=False):
+    studentId: str
+    sessionId: str
+    source: str
+    timestamp: str
+    correct: bool
+    responseTimeMs: int
+    domain: str
+    scaffoldType: Optional[ScaffoldType]
+    misconceptionId: Optional[str]
+    classifierConfidence: Optional[float]
+    classifierLabel: Optional[str]
+    skillId: Optional[str]
+    score: Optional[float]
+    difficulty: Optional[float]
+    consecutiveErrors: Optional[int]
+    sessionErrorRate: Optional[float]
+    explanationQuality: Optional[float]
+    isTransferProblem: Optional[bool]
+    connectionsMade: Optional[int]
+    epistemicMode: Optional[EpistemicMode]
+    selfCorrected: Optional[bool]
+    ext: Optional[dict[str, Any]]
+
+
+# ── MeasurementEvent ──────────────────────────────────────────────────────────
+
+class MeasurementEvent(TypedDict, total=False):
+    eventType: str
+    eventCategory: EventCategory
+    sessionId: Optional[str]
+    classroomId: Optional[str]
+    domain: Optional[str]
+    topic: Optional[str]
+    mode: Optional[str]
+    difficulty: Optional[float]
+    payload: Optional[dict[str, Any]]
+    qualitySignal: Optional[float]
+    confidence: Optional[float]
+    durationMs: Optional[int]
+    parentEventId: Optional[str]
+
+
+# ── Evidence Record ───────────────────────────────────────────────────────────
+
+class NonInterventionDecision(TypedDict):
+    intervened: bool
+    confidence: float
+
+
+class RedactedEvent(TypedDict):
+    redacted: bool
+    eventHash: str
+
+
+class EvidenceEntry(TypedDict, total=False):
+    version: int
+    timestamp: str
+    event: ObservationEvent | RedactedEvent
+    scaffoldType: ScaffoldType
+    depthLevel: DepthLevel
+    epistemicMode: Optional[EpistemicMode]
+    triageResult: TriageResult
+    evidentialWeight: float
+    priorPosterior: float
+    updatedPosterior: float
+    nonInterventionDecision: Optional[NonInterventionDecision]
+    entryHash: str
+    prevHash: str
+
+
+class CompactedBefore(TypedDict):
+    version: int
+    summaryHash: str
+
+
+class EvidenceRecord(TypedDict, total=False):
+    studentScopeId: str
+    entries: list[EvidenceEntry]
+    compactedBefore: Optional[CompactedBefore]

qlm_measure-0.1.0/qlm_measure/verifier.py

@@ -0,0 +1,166 @@
+"""
+Evidence Record Verifier — Python mirror.
+
+Checks bookkeeping integrity WITHOUT any estimation mathematics.
+"""
+
+from __future__ import annotations
+import hashlib
+import json
+from dataclasses import dataclass, field
+from typing import Optional
+
+from .schema import EvidenceRecord, EvidenceEntry
+
+VALID_SCAFFOLD_TYPES = {"none", "socratic", "probing", "metacognitive", "scaffolding", "explain", "hint", "demonstrate"}
+VALID_DEPTH_LEVELS = {"surface", "conceptual", "transfer", "integration"}
+VALID_EPISTEMIC_MODES = {"experience", "inference", "analogy", "testimony"}
+VALID_TRIAGE_RESULTS = {"correct", "slip", "misconception", "disengagement", "ambiguous"}
+
+
+@dataclass
+class Violation:
+    version: int
+    category: str  # schema | version | timestamp | hash | posterior | compaction | enum
+    message: str
+
+
+@dataclass
+class VerificationResult:
+    valid: bool
+    violations: list[Violation] = field(default_factory=list)
+    entries_checked: int = 0
+
+
+def _canonicalize(obj: object) -> str:
+    """Canonical JSON: sorted keys, no whitespace."""
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), default=str)
+
+
+def _sha256(s: str) -> str:
+    return hashlib.sha256(s.encode()).hexdigest()
+
+
+def _hash_entry(entry: EvidenceEntry) -> str:
+    hashable = {
+        "version": entry.get("version"),
+        "timestamp": entry.get("timestamp"),
+        "event": entry.get("event"),
+        "scaffoldType": entry.get("scaffoldType"),
+        "depthLevel": entry.get("depthLevel"),
+        "epistemicMode": entry.get("epistemicMode"),
+        "triageResult": entry.get("triageResult"),
+        "evidentialWeight": entry.get("evidentialWeight"),
+        "priorPosterior": entry.get("priorPosterior"),
+        "updatedPosterior": entry.get("updatedPosterior"),
+        "nonInterventionDecision": entry.get("nonInterventionDecision"),
+    }
+    return _sha256(_canonicalize(hashable))
+
+
+def verify_record(
+    record: EvidenceRecord,
+    timestamp_tolerance_ms: int = 1000,
+) -> VerificationResult:
+    """Verify bookkeeping integrity of an evidence record."""
+    violations: list[Violation] = []
+
+    scope_id = record.get("studentScopeId", "")
+    if not scope_id:
+        violations.append(Violation(0, "schema", "Missing or empty studentScopeId"))
+
+    entries = record.get("entries", [])
+    if not isinstance(entries, list):
+        violations.append(Violation(0, "schema", "entries must be a list"))
+        return VerificationResult(valid=False, violations=violations, entries_checked=0)
+
+    compacted = record.get("compactedBefore")
+    prev_version = compacted["version"] if compacted else 0
+    prev_hash = compacted.get("summaryHash", "") if compacted else ""
+    last_updated: Optional[float] = None
+
+    from datetime import datetime
+
+    prev_ts_str = ""
+    for entry in entries:
+        v = entry.get("version", -1)
+
+        # Schema
+        if not isinstance(v, int) or v < 1:
+            violations.append(Violation(v, "schema", "version must be a positive integer"))
+        if not entry.get("timestamp"):
+            violations.append(Violation(v, "schema", "timestamp is required"))
+        if not isinstance(entry.get("evidentialWeight"), (int, float)):
+            violations.append(Violation(v, "schema", "evidentialWeight must be a number"))
+        if not isinstance(entry.get("priorPosterior"), (int, float)):
+            violations.append(Violation(v, "schema", "priorPosterior must be a number"))
+        if not isinstance(entry.get("updatedPosterior"), (int, float)):
+            violations.append(Violation(v, "schema", "updatedPosterior must be a number"))
+
+        # Monotonic version
+        if v <= prev_version:
+            violations.append(Violation(v, "version", f"Version {v} <= previous {prev_version}"))
+
+        # Timestamp monotonicity
+        ts_str = entry.get("timestamp", "")
+        if prev_ts_str and ts_str:
+            try:
+                prev_ms = datetime.fromisoformat(prev_ts_str.replace("Z", "+00:00")).timestamp() * 1000
+                curr_ms = datetime.fromisoformat(ts_str.replace("Z", "+00:00")).timestamp() * 1000
+                if curr_ms < prev_ms - timestamp_tolerance_ms:
+                    violations.append(Violation(v, "timestamp", f"Timestamp goes backward"))
+            except (ValueError, TypeError):
+                pass
+
+        # Enum validation
+        st = entry.get("scaffoldType")
+        if st and st not in VALID_SCAFFOLD_TYPES:
+            violations.append(Violation(v, "enum", f"Invalid scaffoldType: {st}"))
+        dl = entry.get("depthLevel")
+        if dl and dl not in VALID_DEPTH_LEVELS:
+            violations.append(Violation(v, "enum", f"Invalid depthLevel: {dl}"))
+        em = entry.get("epistemicMode")
+        if em and em not in VALID_EPISTEMIC_MODES:
+            violations.append(Violation(v, "enum", f"Invalid epistemicMode: {em}"))
+        tr = entry.get("triageResult")
+        if tr and tr not in VALID_TRIAGE_RESULTS:
+            violations.append(Violation(v, "enum", f"Invalid triageResult: {tr}"))
+
+        # Hash chain
+        if entry.get("prevHash") != prev_hash:
+            violations.append(Violation(v, "hash", f"prevHash mismatch"))
+        computed = _hash_entry(entry)
+        if entry.get("entryHash") != computed:
+            violations.append(Violation(v, "hash", f"entryHash mismatch"))
+
+        # Posterior chain
+        if last_updated is not None:
+            prior = entry.get("priorPosterior")
+            if isinstance(prior, (int, float)) and abs(prior - last_updated) > 1e-9:
+                violations.append(Violation(v, "posterior", f"priorPosterior ({prior}) != previous updatedPosterior ({last_updated})"))
+
+        prev_version = v
+        prev_ts_str = ts_str
+        prev_hash = entry.get("entryHash", "")
+        up = entry.get("updatedPosterior")
+        if isinstance(up, (int, float)):
+            last_updated = up
+
+    return VerificationResult(
+        valid=len(violations) == 0,
+        violations=violations,
+        entries_checked=len(entries),
+    )
+
+
+def replay_to_version(record: EvidenceRecord, target_version: int) -> list[EvidenceEntry]:
+    """Return entries up to and including target_version."""
+    return [e for e in record.get("entries", []) if e.get("version", 0) <= target_version]
+
+
+def posterior_at_version(record: EvidenceRecord, target_version: int) -> Optional[float]:
+    """Get the posterior at a specific version."""
+    entries = replay_to_version(record, target_version)
+    if not entries:
+        return None
+    return entries[-1].get("updatedPosterior")

qlm_measure-0.1.0/qlm_measure.egg-info/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: qlm-measure
+Version: 0.1.0
+Summary: Open measurement SDK for education AI — evidence events, record verification, and dataset clients
+Author: Quantum Learning Machines
+License: Apache-2.0
+Project-URL: Homepage, https://play.quantumlearningmachines.com/developer
+Project-URL: Repository, https://github.com/quantumkumar/qlm-measure
+Keywords: education,measurement,evidence,learning-analytics,misconceptions
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# @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).

qlm_measure-0.1.0/qlm_measure.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+qlm_measure/__init__.py
+qlm_measure/clients.py
+qlm_measure/schema.py
+qlm_measure/verifier.py
+qlm_measure.egg-info/PKG-INFO
+qlm_measure.egg-info/SOURCES.txt
+qlm_measure.egg-info/dependency_links.txt
+qlm_measure.egg-info/top_level.txt

qlm_measure-0.1.0/qlm_measure.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

qlm_measure-0.1.0/qlm_measure.egg-info/top_level.txt

@@ -0,0 +1 @@
+qlm_measure

qlm_measure-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+