Install

MasteryTrace ships as two independent, equally first-class packages that implement the same two models (BKT, 2PL IRT) and the same CLI contract.

npm (TypeScript CLI + library):

npm install -g masterytrace-cli

Requires Node.js 18 or later.

pip (Python CLI + library): a full, independent Python port of this repo's TypeScript source lives in python/ -- same two models, same CLI contract, its own 75-test pytest suite, built and verified end to end from a real wheel install.

pip install masterytrace-cli

This installs the same four subcommands (init, record, score, report) as a masterytrace console script, plus an importable masterytrace library, a genuine, independent port of this repo's TypeScript source, not a wrapper around the Node binary. See python/README.md for Python-specific usage.

[!NOTE] The npm and pip distributions return equivalent data but with different JSON key casing (camelCase from the TypeScript CLI, snake_case from the Python CLI). Account for this if you parse output from both in the same pipeline.

Table of Contents

• Features
• Quickstart
• CLI command reference
• Library API reference
• How BKT and IRT work
• Benchmark
• Comparison
• FAQ
• Contributing
• License

Features

• Two named psychometric models, not a black-box score. Bayesian Knowledge Tracing outputs a posterior mastery probability per learner per skill; 2-parameter logistic IRT outputs a continuous ability estimate (theta) per learner and item difficulty/discrimination per skill. Run either or both with --model bkt|irt|both.
• Two independent, numerically matching distributions. The npm package (masterytrace-cli, TypeScript) and the PyPI package (masterytrace-cli, Python) are a real line-for-line port of each other, not a Python wrapper around the Node binary; this audit ran the same 58-event sample through both and got identical mastery scores.
• Agent-parseable by default. Every command accepts a global --json flag, report also takes --format markdown, and there's a real three-value exit code contract (0 success, 1 usage error, 2 bad event data) instead of a single generic failure code.
• 162 tests, 100% statement/line/function coverage. 87 TypeScript tests plus 75 Python tests, including a synthetic-data IRT recovery check that fits 4,000 responses with known ground-truth parameters and lands within 0.2 of the true theta, item difficulty, and item discrimination.
• No server, no database. State is two JSON files in a .masterytrace/ directory next to where you run the CLI. Scoring 100,000 events takes under a second on a single core.

Quickstart

masterytrace init
masterytrace record events.json
masterytrace score
masterytrace report

init scaffolds a sample events.json (3 learners, 3 skills, several responses each) and a default masterytrace.config.json in the current directory. Real output from that flow:

$ masterytrace init
Created: events

... [View full README on GitHub](https://github.com/rudrendupaul/masterytrace#readme)