@qlm/learnlog-mcp 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+## 0.2.0 (not yet published)
+
+Misconceptions and LabPath worlds by default:
+
+- `qlm_misconceptions` gives each misconception's LabPath worlds with their names and public pages. `qlm_learning_graph` names every world in its answer the same way. A world gets a link only if it is in `data/labpath-worlds.json`, which `scripts/refresh-worlds.mjs` builds from the live world pages (100 of 100 checked on Oct 24, 2026).
+- `assistance_inventory` on an ASSISTments file adds `assistments_requests_by_skill`: help requests on main problems, by the file's own skill labels (counts only, 15 most requested).
+- An answer about some of the preprint's files lists only the cautions that apply to them.
+- Four Claude skills ship in `skills/`, each ending on misconceptions and LabPath worlds.
+
+Published as `@qlm/learnlog-mcp`, under QLM's npm account (it was `@quantumkumar/learnlog-mcp` before release).
+
+A fourth format, `sandpiper`: the utterances CSV that Sandpiper, the National Tutoring Observatory's open-source annotation app, exports for a per-utterance run. `learnlog_formats` lists it stage by stage, and `learnlog_transform` and `assistance_inventory` accept it.
+
+- One record per session, entries in `sequence_id` order. Each utterance is a dialogue turn; role and text are kept as the export has them, and start/end times stay unparsed strings.
+- Annotation codes are kept as an annotator's inferred assertions. The inventory reports turns by role and counts codes by annotator and field, never as help. Every stage is not recorded.
+- The bundled sample is SYNTHETIC, built from Sandpiper's documented example rows (MIT). There is no public NTO dataset in this package.
+- Re-vendored the transformer from qlm-measure commit 68404b53d0584c9817346b83ee499a38b692adcd. Documents made by the previous engine still validate (tested with saved outputs), because existing formats keep their profile version, `qlm:assistance-context:0.1.0`; Sandpiper records bind `0.2.0`.
+- Answers keep a member named `__proto__` as data instead of dropping it, since exported role and annotator names can be any text.
+
+Two new read-only tools, which read QLM's public LabPath datasets (CC BY 4.0) from `https://play.quantumlearningmachines.com/api/labpath/dataset-export` with GET only, a timeout, no redirects and one request per dataset per session:
+
+- `qlm_misconceptions`: searches the misconception dataset by words, domain, grade band or id. Evaluation-tier trigger patterns and diagnostic questions are never returned.
+- `qlm_learning_graph`: what comes before or after a LabPath activity, from a mode id or a standard code, with teacher-facing reasons, linked misconception ids and aligned standards.
+
+Every answer now fits what an assistant can take in at once (30,000 characters of JSON, under Claude Code's 10,000-token warning). Before this, two answers were far too large and Claude Code rejected them:
+
+- `learnlog_transform` with `include_document` returns the whole document only when the answer fits. Otherwise it reports the document's size in `document_omitted`. A 91 KB tutoring export made a 1 MB document.
+- `qlm_learning_graph` shows 10 links per direction by default (was 25), each edge's first 8 concepts (with `concepts_total`), full standards only for the asked-about activity and standard codes for linked ones (`linked_mode_standards`). If a limit still wouldn't fit, it is lowered and `limit_lowered` says so. The most it accepts is 50 (was 200).
+- Any answer that still wouldn't fit is refused with its size and what to ask for instead.
+
+## 0.1.0 (not yet published)
+
+First release. Six read-only tools over stdio:
+
+- `learnlog_formats`: the transformer's source formats and what each records at each of the six assistance stages.
+- `learnlog_transform`: a local export, or a bundled public sample, into Learnlog records.
+- `learnlog_validate`: replays a Learnlog file's hash chains and lists the unknowns each record keeps.
+- `assistance_inventory`: what a dataset records about help, stage by stage, with counts and limits. Recomputes the Learnlog preprint's inventory and episode counts from your own copies of its three released datasets.
+- `verify_evidence`: qlm-measure's verifier on a local evidence record or product hash chain.
+- `verify_credential`: one request to app.qlmdev.com to verify a QLM credential.
+
+Wraps, unchanged, the QLM transformer engine and the qlm-measure 0.9.0 verifier from qlm-measure commit 24419687cddf238030a918834fbb9ef079f2fc57. The preprint's counting rules are ported from its Python scripts and tested against them on the same files.

package/LICENSE

@@ -0,0 +1,201 @@
+
+                                 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. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such 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,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   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
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. Please also get specific
+      permission from your organization's legal counsel before applying
+      the license to work owned by your organization.
+
+   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,43 @@
+Learnlog MCP (@qlm/learnlog-mcp)
+Copyright 2026 Quantum Learning Machines
+
+This product includes software developed at Quantum Learning Machines
+(https://quantumlearningmachines.com). It is licensed under the Apache
+License, Version 2.0 (see LICENSE).
+
+It includes, unchanged, files from the qlm-measure repository
+(https://github.com/quantumlearningmachines/qlm-measure). vendor/PROVENANCE.json
+names each file, its source path, the commit and its SHA-256.
+
+- vendor/qlm-measure/: the qlm-measure 0.9.0 verifier build. Apache-2.0.
+- vendor/transformer/: the QLM transformer engine. MIT; its license is in
+  vendor/transformer/LICENSE.txt and is kept with those files.
+- data/samples/tutormoments-real-transcripts.jsonl and the TutorMoments
+  sample embedded in vendor/transformer/profiles.mjs: excerpts of
+  TutorMoments-Preview, Albert Zhang and colleagues, Ai2 and collaborators
+  (2026), https://huggingface.co/datasets/allenai/tutormoments-preview,
+  revision 3bb0c104d65e29facffca7ba864ef10fa22d0e78. CC BY 4.0.
+- data/samples/oatutor-real-participants.csv and the OATutor sample embedded
+  in vendor/transformer/profiles.mjs: an excerpt of Pardos and Bhandari
+  (2023), https://doi.org/10.6084/m9.figshare.23935269.v1. CC BY 4.0.
+- data/samples/explicit-assistance-SYNTHETIC.jsonl and data/examples/: QLM's
+  synthetic fixtures and test vectors. No learner data.
+- data/samples/sandpiper-SYNTHETIC.csv and the Sandpiper sample embedded in
+  vendor/transformer/profiles.mjs: a SYNTHETIC fixture arranging example rows
+  from the documentation of Sandpiper,
+  https://github.com/National-Tutoring-Observatory/sandpiper, commit
+  28e0d25c069ce07c759d802184d4ab914e9cfe8b. MIT, Copyright (c) 2025 National
+  Tutoring Observatory; the license text is in data/THIRD_PARTY_DATA.md. No
+  NTO data and no learner data.
+- data/preprint/ and vendor/transformer/cross-source-analysis-data.mjs:
+  aggregate counts published with the Learnlog preprint. No learner rows.
+
+qlm_misconceptions and qlm_learning_graph read, at run time and without
+bundling them, the LabPath misconception, learning-graph and standards
+datasets: QLM LabPath Dataset v1.0, Quantum Learning Machines, 2026, CC BY 4.0,
+https://play.quantumlearningmachines.com/api/labpath/dataset-export, archived
+as https://doi.org/10.5281/zenodo.21800324.
+
+The selection, attribution and limits of each excerpt are in
+data/THIRD_PARTY_DATA.md and data/provenance/. No source author endorses this
+software.

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# Learnlog MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Ask your AI assistant what learning records actually show about help, and get an answer you can check.
+
+Learnlog MCP is a server for the Model Context Protocol (MCP), the standard way assistants like Claude call outside tools. It reads learning records in [Learnlog](https://datatracker.ietf.org/doc/draft-srivastava-learnlog/), a draft format for recording assistance, and answers questions about them. It also searches QLM's public misconception dataset and LabPath's learning graph. Every answer says what it can't show.
+
+Learnlog keeps six kinds of help apart, from the Internet-Draft draft-srivastava-learnlog-03, Section 2.2:
+
+| Stage | What it records |
+| --- | --- |
+| requested | someone asked for help |
+| offered | a system or person started help on its own, like steps after a wrong answer |
+| generated | a system produced help content |
+| transmitted | help was sent somewhere |
+| displayed | help was shown on a screen |
+| accepted | the learner took the action the product calls accepting help |
+
+Each stage is its own observation. A request doesn't mean help was shown, and a display doesn't mean it was read. A stage that wasn't captured is "not recorded", never "none".
+
+## Install
+
+You need Node.js 22.12 or later.
+
+```
+npx -y @qlm/learnlog-mcp
+```
+
+### Claude Desktop
+
+Add this to `claude_desktop_config.json` (Settings, Developer, Edit Config), then restart Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "learnlog": {
+      "command": "npx",
+      "args": ["-y", "@qlm/learnlog-mcp"]
+    }
+  }
+}
+```
+
+Any MCP client that can start a command over stdio works the same way.
+
+## Tools
+
+All eight are read-only. Paths are full paths on your computer (or start with `~/`).
+
+**`learnlog_formats`** lists the exports the transformer converts and what each one records at each stage.
+> "Which exports can Learnlog MCP convert, and what does each one record about help?"
+
+There are four formats: `tutormoments` (TutorMoments transcripts), `oatutor` (OATutor participant summaries), `explicit-assistance-events` (an explicit help-lifecycle contract) and `sandpiper` (the utterances CSV that Sandpiper, the National Tutoring Observatory's annotation app, exports for a per-utterance run). For Sandpiper, each utterance is a dialogue turn, and each annotation code is kept as an annotator's inferred assertion. No code counts as help, so every stage is not recorded. The lifecycle and Sandpiper samples are SYNTHETIC; the Sandpiper one is built from Sandpiper's documented examples, not NTO data.
+
+**`learnlog_transform`** turns an export into Learnlog records, keeping source and capture details. Use your own file, or `use_sample: true` for a bundled public sample.
+> "Turn the TutorMoments sample into Learnlog and tell me what it keeps and what it leaves unknown."
+
+**`learnlog_validate`** replays a Learnlog file's hash chains, checks its profile bindings, and lists the unknowns each record keeps.
+> "Is ~/exports/session.learnlog.json a valid Learnlog file? What doesn't it record?"
+
+**`assistance_inventory`** says which stages a dataset records, with counts by source and what can't be concluded.
+> "What does this tutoring dataset actually record about help?"
+
+It can also recompute the inventory and episode counts in the Learnlog preprint, *Preserving assistance meaning in cross-source learning analytics*, from your own copies of its three released datasets. When your files are the exact releases the preprint used, it checks every number against the published ones. With no input, it returns the published figures and says they weren't recomputed.
+
+| Argument | Dataset | Where to get it |
+| --- | --- | --- |
+| `zenodo_zip` | JetBrains Academy next-step hint study, Zenodo 17551130 v1 | [zenodo.org/records/17551130](https://zenodo.org/records/17551130) |
+| `idetrace_json` | TutorTrace / IDETrace deployment 8 (needs `allow_idetrace_research: true`) | [the pinned repository commit](https://github.com/divadbaroon/TutorTrace_dataset_and_benchmark/tree/bc7990370da18a611a122255ebc3e475bd8a3fc6) |
+| `assistments_csv` | ASSISTments 2012-13 School Data with Affect | [ASSISTments datasets](https://sites.google.com/site/assistmentsdata/datasets/2012-13-school-data-with-affect) |
+
+These datasets aren't bundled. Their learner records stay with their owners, and only counts come back. The ASSISTments file is about 3 GB. Reading it took about 70 seconds in testing, so a client with a short tool timeout may give up first.
+
+**`verify_evidence`** replays a local evidence record or product hash chain with qlm-measure's own verifier and returns pass, or each named check that failed.
+> "Can I trust this evidence record? ~/Downloads/record.json"
+
+**`verify_credential`** checks a QLM credential with QLM's verify service. Give its ID (`urn:uuid:...`) or a link that contains one.
+> "Is this credential real and current? urn:uuid:<the ID on the badge>"
+
+It returns whether the credential verified, each check with its result, the issuer, the achievement, the date and the AI-help summary by stage. The service's report has no personal data, and the tool shows only the fields it knows.
+
+**`qlm_misconceptions`** searches QLM's public misconception dataset by words, domain, grade band or id. Each result gives the student's belief, the scientific reality, a counterexample, a teacher intervention, the research source, severity, grade bands and the LabPath worlds that work on it, each with its name and public page.
+> "Which misconception might explain students passing force problems only with hints, and what should the teacher try?"
+
+Evaluation-tier records never include their trigger patterns or diagnostic question; they're kept back for benchmark integrity. Held-out records aren't in the dataset at all.
+
+**`qlm_learning_graph`** says what comes before or after a LabPath activity, from a mode id or a standard code. It returns each link's kind (prerequisite, labpath-sequence, reinforcement, transfer, extension), the teacher-facing reason, its first 8 concepts, the misconception ids it carries, the full standards for the activity you asked about, and the standard codes of each linked activity. It shows 10 links per direction unless you ask for more, and names every world in the answer with its public page.
+> "What should students do before the forces activity, and which standards does it cover?"
+
+The graph is LabPath's designed sequence, not evidence that a student needs a step. The standards are LabPath's own mapping to NGSS-style codes.
+
+Both read [QLM's LabPath dataset export](https://play.quantumlearningmachines.com/api/labpath/dataset-export?dataset=misconceptions), CC BY 4.0, once per session. The archived v1.0 is [QLM LabPath Dataset v1.0 on Zenodo](https://doi.org/10.5281/zenodo.21800324).
+
+## Skills
+
+The package ships four Claude skills in `skills/`. Each walks an assistant through one workflow and ends the same way: the likely QLM misconceptions, one way to check for each, its teacher move, and the LabPath worlds that work on it, with their links.
+
+- **`learnlog-export-to-action`**: any supported export to Learnlog, what it records about help stage by stage, and what it can't show.
+- **`learnlog-assistments`**: your own copy of ASSISTments 2012-13 School Data with Affect, counted stage by stage and by the file's skill labels. Counts only.
+- **`learnlog-nto-sandpiper`**: a National Tutoring Observatory Sandpiper run export. Turns stay observed; every code stays inferred, with who coded it.
+- **`learnlog-learning-commons`**: with the Learning Commons Knowledge Graph MCP beside this one, a standard's official statement, learning components and earlier standards.
+
+In Claude Code, copy a skill's folder into `.claude/skills/`.
+
+## What it never does
+
+- It never writes, changes or uploads anything. It doesn't change records, scores or credentials.
+- Five tools read local files only and make no network calls.
+- `verify_credential` makes one request, to `https://app.qlmdev.com/v1/verify`, sending only the credential ID. It follows no redirects.
+- `qlm_misconceptions` and `qlm_learning_graph` make GET requests to `https://play.quantumlearningmachines.com/api/labpath/dataset-export` only, one per dataset per session, and send nothing about you or your files. They follow no redirects.
+- It never shows sealed content, such as answer keys or sealed case variants.
+- It never turns "not recorded" into "none" or zero.
+- It doesn't estimate learning or say whether help worked.
+
+## Where the code comes from
+
+The transformer engine and the qlm-measure 0.9.0 verifier are copied unchanged from [qlm-measure](https://github.com/quantumlearningmachines/qlm-measure). `vendor/PROVENANCE.json` lists every copied file with its source path, commit and SHA-256. The preprint's counting rules are ported from its published Python scripts, and the tests run both on the same files and require identical output.
+
+## License
+
+Apache-2.0. See `LICENSE` and `NOTICE`. The vendored transformer files keep their MIT license (`vendor/transformer/LICENSE.txt`). The TutorMoments and OATutor sample excerpts are CC BY 4.0; their attribution and limits are in `data/THIRD_PARTY_DATA.md`. The SYNTHETIC Sandpiper sample uses Sandpiper's documentation examples, MIT, Copyright (c) 2025 National Tutoring Observatory; the notice is in `data/THIRD_PARTY_DATA.md`. The LabPath misconception, learning-graph and standards data are CC BY 4.0 from Quantum Learning Machines; they're read from QLM's service, not bundled. Cite them as: QLM LabPath Dataset v1.0, Quantum Learning Machines, 2026, https://doi.org/10.5281/zenodo.21800324.
+
+Made by Kumar Srivastava at [Quantum Learning Machines](https://quantumlearningmachines.com).

package/data/SOURCE_CORRECTION.md

@@ -0,0 +1,9 @@
+# Sample authenticity correction — 17 October 2026
+
+The first public demo used six authored synthetic rows with generic headers under Khan Academy, IXL, DreamBox Math and ALEKS. Its MATHia example used documented Progress Report headers with invented values. These fixtures did not establish vendor export compatibility. Internal transformation tests did not validate vendor authenticity.
+
+This release removes all five branded examples and their downloadable synthetic fixtures. It uses two explicitly named public research sources: TutorMoments human tutoring transcripts and OATutor participant summaries. Their original inputs have different, preserved structures. Public samples are exact-byte excerpts with pinned source locations, full-file and excerpt hashes, selection rules and license attribution.
+
+TutorMoments source turns contain actual released student/tutor dialogue, including requests for help and tutor questions. They are machine-produced transcripts of real sessions, not native clickstream logs or independently verified recordings. No generated enrichment is promoted to an observed event. OATutor condition assignment is retained as assignment, not hint delivery. Import times are identified as import times; relative source offsets are not converted into invented dates.
+
+This is a source-adapter demonstration. It does not establish integration with the original five vendors, comparable outcome scales, learning effectiveness, independent learner performance or valid causal pooling.

package/data/THIRD_PARTY_DATA.md

@@ -0,0 +1,148 @@
+# Published research data and attribution
+
+The application's MIT code license does not relicense these data. Both supplied
+research excerpts are distributed under the publishers' **CC BY 4.0** grants.
+The Sandpiper fixture is synthetic and carries Sandpiper's MIT notice. The original
+publisher-deidentified data, citations, source restrictions and selection rules
+are documented in each `dist/provenance/*.json` file. No original recording,
+private export or personal identity mapping is included.
+
+## TutorMoments-Preview
+
+Albert Zhang and colleagues, *When Help is Unhelpful: Evaluating AI Tutors for
+Productive Struggle* (2026 preview release). Ai2 and collaborators.
+
+- Dataset: https://huggingface.co/datasets/allenai/tutormoments-preview
+- Pinned revision: `3bb0c104d65e29facffca7ba864ef10fa22d0e78`
+- Paper: https://tutormoments.allen.ai/static/paper/tutormoments-preview.pdf
+- License: https://creativecommons.org/licenses/by/4.0/
+- Supplied excerpt: complete `transcripts.jsonl` source lines 366 and 435,
+  unchanged, with 149 and 161 turns respectively.
+
+These are transcripts of real human tutoring sessions, machine-transcribed by
+SUT (Gemini 2.5 Pro). The provider is anonymized. Publisher-generated surrogate
+names/IDs are retained in the source excerpt. Absolute dates were removed by
+the publisher. Relative offsets, transcript inaccuracies and source text are
+not independently checked against a recording. The selected sessions contain
+mathematics practice, explicit requests for help and tutor prompts; this is a
+purposive demonstration subset, not a representative sample or quality rating.
+
+Only released `turns[]` are mapped to observed transcript turns. Model-generated
+`enrichments`, replay conversations and pedagogical labels are not promoted to
+observed events. The Learnlog adapter omits known source ID fields from its
+selected source-field payload and uses scoped pseudonyms; it is not a general
+anonymizer for free text.
+
+The companion scaffolding view uses exact original `ground_truth.jsonl` lines
+157 and 190 and 14 complete original lines from `annotations.jsonl`, at the same
+pinned revision and CC BY 4.0 license. The 60 included derived scaffolding rows'
+situation/action/result strings match the raw human annotation release
+verbatim. Their categorical need and action-direction labels are the source
+publisher's LLM-assisted classifications, not new QLM classifications or
+validated facts about assistance effectiveness. Sixty rows repeat labels for
+ten distinct, sometimes overlapping intervals; each interval is counted once.
+One raw human moment omitted by the publisher's derived release is not silently
+added to the derived-label denominator. Source commentary can discuss context
+beyond its marked interval, so the interval is not an exact assistance-event
+boundary. `dist/provenance/scaffolding-evidence.json` records the source hashes,
+line locators, labels, commentary and selection limits.
+
+## OATutor help-condition study participant data
+
+Zachary Pardos and Shreya Bhandari (2023), *ChatGPT-generated help produces
+learning gains equivalent to human tutors on mathematics skills*, Figshare
+dataset. The associated research article was published in PLOS ONE in 2024.
+
+- Paper: https://doi.org/10.1371/journal.pone.0304013
+- Archived dataset: https://doi.org/10.6084/m9.figshare.23935269.v1
+- Original file: https://ndownloader.figshare.com/files/41974569
+- License: https://creativecommons.org/licenses/by/4.0/
+- Supplied excerpt: original CSV header and first 12 participant records,
+  unchanged, with original column names and CRLF newlines.
+
+This is a participant-level results table, not an event log. `condition` records
+assigned ChatGPT, human-tutor or no-hint support; it does not establish actual
+hint opening or receipt. The raw “Human tutor” condition refers to
+human-authored hints, while “ChatGPT” refers to pre-generated solution hints;
+these are not recordings of live tutor conversations. The paper reports correctness feedback and optional
+bottom-out answers in the no-hint condition too; this label does not mean no
+assistance. No timestamp, inquiry, hint text or event sequence is
+supplied by that table. No learning effect is estimated by the demonstration.
+
+## Sandpiper documentation examples: SYNTHETIC fixture (MIT)
+
+`dist/samples/sandpiper-SYNTHETIC.csv` is a SYNTHETIC fixture, not research
+data. It arranges eight example utterances and one example annotation from the
+documentation of Sandpiper, the National Tutoring Observatory's open-source
+annotation app (<https://github.com/National-Tutoring-Observatory/sandpiper>,
+commit `28e0d25c069ce07c759d802184d4ab914e9cfe8b`), in the layout of
+Sandpiper's PER_UTTERANCE utterances CSV (`app/functions/outputRunDataToCSV`).
+QLM did the arranging. There is no public National Tutoring Observatory dataset
+here: no real learner, session or Sandpiper export is included. The adapter
+keeps each utterance as an observed dialogue turn and each annotation code as an
+inferred assertion by its annotator; no code is counted as help. The engine
+offers this adapter to callers such as the Learnlog MCP; the demo page does not
+list it.
+
+> MIT License
+>
+> Copyright (c) 2025 National Tutoring Observatory
+>
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.
+
+## Separate cross-source request analysis: aggregate facts only
+
+The cross-source panel adds **1,050** released Get Hint/Retry observations from
+the JetBrains Academy plugin supplement to **59** `CHAT_QUERY` observations in
+the selected TutorTrace / IDETrace deployment-8 file. These are source-native
+request-record occurrences, not verified distinct human requests, pedagogical
+quality labels or a complete assistance census. No raw learner rows, dialogue,
+prompts, source-code payloads, event timestamps or linkable learner IDs from
+these two additional releases are bundled with the website or its download.
+
+JetBrains Academy supplement: Anastasiia Birillo, Aleksei Rostovskii, Yaroslav
+Golubev and Hieke Keuning (2025), *Supplementary materials for the paper
+“Understanding Student Interaction with AI-Powered Next-Step Hints: Strategies
+and Challenges”*, v1, https://doi.org/10.5281/zenodo.17551130, CC BY 4.0. QLM
+authored the transformations; no source-author endorsement is implied.
+
+TutorTrace repository: `divadbaroon/TutorTrace_dataset_and_benchmark`, commit
+`bc7990370da18a611a122255ebc3e475bd8a3fc6`, selected
+`dataset/raw_telemetry/deployment_8.json`:
+https://github.com/divadbaroon/TutorTrace_dataset_and_benchmark/tree/bc7990370da18a611a122255ebc3e475bd8a3fc6.
+Its pinned `croissant.json` declares CC BY 4.0 with an anonymous creator. The
+pinned datasheet is empty, GitHub reports no repository license, and published
+population descriptions differ. No verified learner count, broad license-scope
+claim or permission to redistribute the raw payload is inferred. The prepared
+analysis distributes aggregate factual counts only. Source retrieval for
+research reproduction requires the companion pipeline's explicit opt-in.
+
+The generated `dist/examples/cross-source-analysis.json` retains source hashes,
+release scopes, mappings, exclusions and metadata caveats. Candidate mappings
+are agent-authored and agent-audited; independent human mapping review remains
+pending. Raw source inputs and cached third-party code are excluded from the
+prepared analysis archive.
+
+## Original five branded examples
+
+The original Khan Academy, MATHia, IXL, DreamBox Math and ALEKS synthetic
+examples have been removed. They did not establish authentic vendor export
+compatibility. See `SOURCE_CORRECTION.md`. No replacement dataset is relabeled
+as one of those vendors. ASSISTments, DataShop and other investigated sources
+are not bundled without established redistribution rights.