masterytrace

インストール

MasteryTrace は、同じ 2 つのモデル（BKT、2PL IRT）と同じ CLI 仕様を実装する、独立した同等のパッケージを 2 種類提供しています。

npm（TypeScript CLI + ライブラリ）：

npm install -g masterytrace-cli

Node.js 18 以降が必要です。

pip（Python CLI + ライブラリ）：このリポジトリの TypeScript ソースを完全に移植した独立した Python 版が python/ にあります。同じ 2 つのモデルと同じ CLI 仕様を備え、75 件のテストからなる独自の pytest テストスイートを持ち、実際の wheel のインストールからエンドツーエンドでビルドおよび検証されています。

pip install masterytrace-cli

これにより、masterytrace コンソールスクリプトとして同じ 4 つのサブコマンド（init、record、score、report）がインストールされるほか、インポート可能な masterytrace ライブラリもインストールされます。これはこのリポジトリの TypeScript ソースを独立して移植したもので、Node バイナリをラップしたものではありません。Python 固有の使い方については、python/README.md を参照してください。

メモ

npm と pip の配布パッケージは同等のデータを返しますが、JSON キーの大文字・小文字の形式が異なります（TypeScript CLI は camelCase、Python CLI は snake_case）。両方の出力を同じパイプラインで解析する場合は、この点を考慮してください。

目次

• 機能
• クイックスタート
• CLI コマンドリファレンス
• ライブラリ API リファレンス
• BKT と IRT の仕組み
• ベンチマーク
• 比較
• FAQ
• コントリビューション
• ライセンス

機能

• ブラックボックスのスコアではなく、名前が付いた 2 つの心理測定モデルを利用できます。 ベイズ知識追跡は学習者ごと、スキルごとに事後習得確率を出力します。2 パラメータロジスティック IRT は、学習者ごとに連続的な能力推定値（theta）を、スキルごとに項目難易度と識別力を出力します。--model bkt|irt|both でどちらか一方、または両方を実行できます。
• 数値が一致する独立した 2 種類の配布パッケージ。 npm パッケージ（masterytrace-cli、TypeScript）と PyPI パッケージ（masterytrace-cli、Python）は、Node バイナリをラップした Python 版ではなく、行単位で対応する実際の移植版です。この監査では、同じ 58 件のイベントサンプルを両方に入力し、習得スコアが一致することを確認しました。
• エージェントが解析しやすい設計が標準です。 すべてのコマンドでグローバルな --json フラグを利用できます。report では --format markdown も指定できます。また、単一の汎用的な失敗コードではなく、3 種類の終了コード（0 成功、1 使用方法のエラー、2 不正なイベントデータ）を定めています。
• テスト 162 件、ステートメント／行／関数カバレッジ 100％。 TypeScript テスト 87 件と Python テスト 75 件を含みます。合成データを使った IRT の復元チェックでは、既知の正解パラメーターを用いた 4,000 件の回答を当てはめ、真の theta、項目難易度、項目識別力との差が 0.2 以内に収まることを確認しています。
• サーバー不要、データベース不要。 状態は CLI を実行する場所にある .masterytrace/ ディレクトリ内の 2 つの JSON ファイルに保存されます。イベント 100,000 件のスコアリングは、シングルコアで 1 秒未満です。

クイックスタート

masterytrace init
masterytrace record events.json
masterytrace score
masterytrace report

init は、現在のディレクトリにサンプルの events.json（学習者 3 人、スキル 3 件、それぞれに複数の回答）と、デフォルトの masterytrace.config.json を生成します。この処理の実際の出力は次のとおりです。

$ masterytrace init
Created: events.json, masterytrace.config.json
Next: run 'masterytrace record events.json' to load it, then 'masterytrace score'.

$ masterytrace record events.json
Stored 58 event(s) to /path/to/.masterytrace/events.json
(record replaces any previously stored event log; see --help for details.)

$ masterytrace score
Scored 58 event(s) with model(s): both
Wrote /path/to/.masterytrace/scores.json

$ masterytrace report
learner        skill                  model  metric                         value    responses
-------------  ---------------------  -----  -----------------------------  -------  ---------
learner-ada    fractions              bkt    posterior_mastery_probability  0.9994   6
learner-ada    fractions              irt    ability_theta                  0.7349   6
learner-ada    linear-equations       bkt    posterior_mastery_probability  0.9746   7
learner-brook  fractions              bkt    posterior_mastery_probability  0.0612   6
learner-cyrus  reading-comprehension  bkt    posterior_mastery_probability  0.9947   7
...

警告

masterytrace record は、保存済みのイベントログ全体を常に置き換えます。追記モードはありません。既存の回答を失わずに新しい回答を追加する必要がある場合は、1 つのファイルにまとめてから、全体を含むログを指定して record を再実行してください。

report では --format markdown または --format json も指定できます。また、すべてのコマンドは、stdout に機械可読な出力を返すグローバルな --json フラグを受け付けます。終了コードも明確に定義されているため（成功は 0、一般エラー／使用法エラーは 1、イベントデータの不正は 2）、この CLI を呼び出すスクリプトやエージェントはテキストを解析せずに結果に応じて処理を分岐できます。

独自のイベントログには、{ learnerId, skillId, correct, timestamp } オブジェクトの JSON 配列、またはヘッダーが learner_id,skill_id,correct,timestamp の CSV を使用します。timestamp は ISO 8601 形式である必要があります。correct はブール値（JSON）、または true／false／1／0（CSV）を指定します。CSV の correct セルにこれ以外の値がある場合、暗黙的に false として扱われず、検証エラーとして拒否されます。100 MB を超えるイベントログファイルは明確なエラーとともに事前に拒否されます。イベントログは小さな構造化レコードであり、そのようなサイズに達する正当な理由はありません。

CLI コマンドリファレンス

コマンド	引数	オプション	機能
masterytrace init		--force	現在のディレクトリにサンプルの events.json と masterytrace.config.json を生成します。--force が指定されない限り、すでに存在するファイルはスキップします。
masterytrace record <path>	<path>：JSON または CSV のイベントログ		イベントログを検証し、.masterytrace/events.json に保存します。以前に保存されたログは常に置き換えます。
masterytrace score		--model <bkt|irt|both>（デフォルトは both）	保存済みのイベントログをモデルに適合させてスコアを算出し、結果を .masterytrace/scores.json に書き込みます。
masterytrace report		--format <table|json|markdown>（デフォルトは table）	.masterytrace/scores.json を読み込み、学習者ごと、スキルごとの習熟度テーブルを出力します。

グローバルオプション：--json は、report の --format を上書きし、すべてのコマンドで stdout に機械可読な JSON を強制的に出力します。

終了コード：成功は 0、一般エラーまたは使用法エラー（不正なフラグ、ファイルが見つからない）は 1、検証エラー（イベントログ自体の形式が不正）は 2 です。

MCP サーバー

MasteryTrace には Model Context Protocol（MCP）サーバーが含まれているため、エージェント（Claude Desktop、Claude Code、その他の MCP クライアント）は、シェルコマンドを自分で実行する代わりに CLI を直接呼び出せます。

mcp エクストラを指定して Python パッケージをインストールします。

pip install "masterytrace-cli[mcp]"

次に、masterytrace-mcp コンソールスクリプトを MCP クライアントに指定します。Claude Desktop の設定例（claude_desktop_config.json）：

{
  "mcpServers": {
    "masterytrace": {
      "command": "masterytrace-mcp"
    }
  }
}

サーバーは単一のツール run(args: list[str]) -> dict を公開します。このツールは、指定された引数リストを使ってインストール済みの masterytrace CLI をシェル経由で実行し、解析済みの出力を返します。CLI がサポートするサブコマンドやフラグは、どれもこのツールから利用できます。呼び出し例：run(["score", "--model", "bkt", "--json"]) は、保存済みのイベントログに BKT モデルを適合させ、解析済みの JSON 習熟度レポートを返します。

ライブラリ API リファレンス

以下はすべて、masterytrace-cli のパッケージエントリポイント（src/index.ts。src/core/* と src/models/* を再エクスポート）からエクスポートされています。

import {
  // Event schema and validation
  ResponseEventSchema, parseResponseEvents, EventValidationError,
  type ResponseEvent,

  // Shared model types
  type ScoringModel, type FittedModel, type MasteryReport,
  type MasteryLearnerEntry, type MasterySkillEntry,

  // Engine: runs one or both models
  runScoring, type ModelSelector, type EngineConfig, type EngineResult,

  // BKT
  BktModel, BKT_DEFAULT_PARAMS, runForwardRecursion, fitSkillParamsByGridSearch,
  type BktParams, type BktConfig, type BktFittedModel,

  // IRT
  IrtModel, probabilityCorrect,
  type IrtItemParams, type IrtLearnerResult, type IrtConfig, type IrtFittedModel,

  // Generic JSON/CSV event log adapter
  genericAdapter, parseCsv, type EventAdapter,
} from 'masterytrace-cli';

ライブラリの最小限の使用例：

import { runScoring, parseResponseEvents } from 'masterytrace-cli';

const events = parseResponseEvents([
  { learnerId: 'l1', skillId: 'fractions', correct: true, timestamp: '2026-01-01T00:00:00Z' },
  { learnerId: 'l1', skillId: 'fractions', correct: false, timestamp: '2026-01-02T00:00:00Z' },
]);

const { reports } = runScoring(events, 'both');
// reports[0].model === 'bkt', reports[1].model === 'irt'
// each learner's report.learners[i].skills[j].value is the mastery estimate

BktModel と IrtModel はどちらも同じ ScoringModel インターフェイス（fit(events) の後に score(fittedModel) を呼び出す）を実装しているため、エンジンや独自のコードでは、これらを相互に置き換えて扱えます。

BKT と IRT の仕組み

MasteryTrace は、独立した 2 つの心理測定モデルを実装しています。これらは異なる問いに答え、種類の異なる値を出力するため、masterytrace score --model both はどちらか一方を選ぶのではなく、両方を並行して実行します。

ベイズ知識追跡（BKT）

BKT は、学習者 1 人の 1 つのスキルの習得度を、隠れた二値状態（習得している／まだ習得していない）としてモデル化し、4 つのパラメーターを使って、回答するたびに「習得している」確率を更新します。

• pInit：証拠が得られる前に、学習者がすでにそのスキルを習得している確率。
• pTransit：ある試行から次の試行までの間に、そのスキルを習得する確率。
• pSlip：スキルを習得しているにもかかわらず、不正解になる確率。
• pGuess：スキルを習得していないにもかかわらず、正解する確率。

回答ごとに、前向き再帰ではまず観測された結果に基づいて信念を更新し（ベイズの定理）、次に、次の試行までに習得する可能性を考慮して進めます。

after correct:   P(know | obs) = P(know) * (1 - pSlip) / [P(know) * (1 - pSlip) + (1 - P(know)) * pGuess]
after incorrect: P(know | obs) = P(know) * pSlip       / [P(know) * pSlip       + (1 - P(know)) * (1 - pGuess)]
P(know)_next = P(know | obs) + (1 - P(know | obs)) * pTransit

MasteryTrace は、この再帰を学習者ごと、スキルごとに時系列順で実行し、最終的な事後確率を、その学習者がそのスキルを習得している確率として報告します。masterytrace.config.json に "bkt": { "fit": true } を設定すると、教科書に記載された既定値（pInit=0.4, pTransit=0.3, pSlip=0.1, pGuess=0.2）を使う代わりに、各スキルの 4 つのパラメーターを独自のデータから、予測正答率と観測正答率の二乗誤差を最小化する粗いグリッドサーチ（7 x 7 x 5 x 5 個の候補の組み合わせ）で適合させます。

項目反応理論（2PL IRT）

IRT は、学習者ごとに 1 つの連続的な能力（theta）と、「項目」として扱う各スキルごとに 2 つのパラメーターをモデル化します。2 つのパラメーターは、識別力（a。能力の高低によって学習者をどれだけ明確に区別するか）と難易度（b）です。2 パラメーターロジスティックモデルにおける正答確率は次のとおりです。

P(correct) = sigmoid(a * (theta - b))

MasteryTrace は、対数尤度に対する勾配上昇法（同時 MLE）によって、これらすべてをまとめて適合させます。また、小さな L2 ペナルティを適用し、theta／b を 0 に、a を 1 に近づけます。このペナルティによって、正則化されていない場合には尤度が無限大で最大化される、全問正解または全問不正解の記録を持つ学習者やスキルについても、適合結果が有限に保たれます。2PL モデルは theta の平行移動と尺度変更に対して識別できないため（theta と b を同じ定数だけ平行移動する、または theta／b を尺度変更して、それに応じて a を割ると、すべての予測確率が変わりません）、適合では標準的な手法として、各反復後に theta の平均を 0、標準偏差を 1 に再調整し、解を 1 つに定めます。

実データによる復元チェック

test/irt.test.ts は、既知の正解データにおける theta／a／b の値から作成した合成データセット（5 人の学習者と 4 つのスキルにわたる 4,000 件の回答）に対してモデルを適合させ、同じゲージ正規化を適用したときに、復元されたパラメーターが真の値に近いことを確認します。この README のために実際に実行したところ、適合時間 26 ms で、最大絶対誤差は theta で 0.123、項目難易度で 0.196、項目識別力で 0.114 となり、テストの許容誤差 0.3 を十分に下回りました。

ベンチマーク

合成イベントログを使ってローカルで実行しました（Node 24、単一コア、Node の起動を含む実際のサブプロセスとして masterytrace score を実行）：

データセット	イベント数	--model bkt	--model irt	--model both
小規模	10,000（学習者 50 人 x スキル 20 個 x 回答 10 件）	0.06s	0.10s	0.11s
大規模	100,000（学習者 100 人 x スキル 50 個 x 回答 20 件）	0.17s	0.54s	0.60s

スキルごとのグリッドサーチ適合を有効にした BKT（"bkt": { "fit": true }。スキルごとに 1,225 通りの組み合わせをグリッドサーチ）では、100,000 件のイベントを含むデータセットの処理に 1.39s かかりました。すべての数値は、Node プロセスの起動を含めた masterytrace score サブプロセス全体の実時間です。そのため、適合関数単体のマイクロベンチマークではなく、コマンドを実際に実行したときの所要時間を反映しています。

比較

MasteryTrace 独自の強みは、Python ランタイムを必要とせず、CLI と TypeScript ライブラリの両方として使えることです。ここでは、機能が最も近い既存ライブラリと比較します。それぞれの情報は、GitHub リポジトリとパッケージレジストリのページで確認しています。

プロジェクト	言語	ライセンス	種別	インストール	GitHub スター数
MasteryTrace	TypeScript/Node + Python	MIT	CLI + ライブラリ	pip install masterytrace-cli / npm install -g masterytrace-cli	新規
pyBKT	Python（C++ コア）	MIT	ライブラリのみ	pip install pyBKT	272
girth	Python	MIT	ライブラリのみ	pip install girth	124
py-irt	Python（PyTorch/Pyro）	MIT	CLI + ライブラリ	pip install py-irt	170
DeepTutor	Python + TypeScript	Apache-2.0	総合的な個別指導アプリケーション	pip install -U deeptutor	32,000+

UC Berkeley の CAHLR 研究室が開発した pyBKT は、最も実績のある BKT 実装であり、MasteryTrace の単一の教科書的モデルとグリッドサーチによるモデルよりも多くの BKT バリエーション（忘却、項目順序の影響）をサポートしています。girth と py-irt はどちらも IRT ライブラリです。py-irt は 2 つのうち大規模なほうで、PyTorch と Pyro を基盤として、より大規模な IRT モデル（1PL/2PL/4PL）の GPU による高速フィッティングに対応し、独自の CLI も備えています。一方、girth はより軽量な純粋 Python の選択肢で、正則化勾配上昇法による MasteryTrace の 2PL 実装に近い考え方です。この 3 つはいずれも Node.js パッケージではなく、masterytrace score/report と同じ形式の汎用 CLI も提供していません。

DeepTutor は、測定ライブラリとして競合するものではありません。エージェントのオーケストレーション、個別指導用ワークスペース、メモリを備えた、大規模で活発に開発されているオープンソースの AI 個別指導プラットフォームです。独自の README によると、BKT や IRT 自体は実装していません。連携先として有望であり、DeepTutor は回答イベントを記録して MasteryTrace に渡すことで、ほかの方法では実現できない実際の習熟度推定を行えます。

MasteryTrace とは何か、なぜ存在するのか

MasteryTrace は、学習者の回答イベントのログにベイズ知識追跡と項目反応理論のモデルを当てはめ、学習者ごと、スキルごとの較正済み習熟度推定値を報告する、オープンソースの TypeScript CLI およびライブラリです。多くのオープンソース AI 個別指導エージェントは、会話を続けたりレッスンを調整したりするために作られており、学習者が実際に何を習得したかを測定するためのものではありません。一方、その測定を厳密に行う 2 つの心理測定モデルは、ほぼすべて Python ライブラリとして提供されており、Node または TypeScript のスタックに相当するものも、Python 以外のツールからシェル経由で呼び出せる CLI もありません。MasteryTrace はこの特定のギャップを埋めます。JSON または CSV のイベントログを指定すれば、スクリプト、個別指導製品、エージェントが解析できる形式で、習熟度の確率（BKT）と能力推定値（IRT）を取得できます。

よくある質問

pyBKT や py-irt ではだめなのですか？ 忘却や項目順序の影響など、より多くの BKT バリエーションが必要な場合や、GPU を活用した大規模な IRT のフィッティングが必要な場合は、これらが適しています。MasteryTrace の上記の比較表でも、その点を明記しています。MasteryTrace の Python パッケージ（pip install masterytrace-cli）は、このリポジトリで実装しているシンプルな教科書的 BKT とグリッドサーチ、正則化付き 2PL-IRT モデルをカバーしており、Python だけのパイプラインで利用できます。TypeScript パッケージ（npm install -g masterytrace-cli）では、Python の実行環境をまったく使わずに Node のコードベースで習熟度スコアを算出したい場合にも対応しています。

データベースは必要ですか？ いいえ。状態は、CLI を実行する場所の隣にある .masterytrace/ ディレクトリ内の 2 つの JSON ファイル（events.json と scores.json）に保存されます。実行にサーバーや外部依存関係は必要ありません。

自分のチュータリングアプリのデータを接続できますか？ はい。{ learnerId, skillId, correct, timestamp } の行を含む JSON 配列または CSV を生成できれば利用できます。アプリごとのアダプターはまだありませんが、同梱の genericAdapter が両方の形式に対応しています。データの形式が異なる場合は、runScoring を呼び出す前にこの形式に変換するか、すでにこの形式になっている行に対して parseResponseEvents を呼び出してください。

BKT／IRT の計算は信頼できますか？ どちらのモデルも、手計算した例（BKT）と、正解となるパラメーターが既知の合成データセット（IRT）を使ったユニットテストに加え、CLI の全テストスイートで検証されています。実際にパラメーターをどの程度復元できるかは、上記の「BKT と IRT の仕組み」をご覧ください。

回答が 1 件しかない場合や、回答がまったくない場合はどうなりますか？ どちらのモデルもエラーを起こさずに処理できます。回答が 1 件の場合、BKT は単一の事後確率を返します。イベントログが空の場合は、どちらのモデルも例外をスローせず、空のレポートを返します。

MasteryTrace を一言で説明すると？ 学習者の回答イベントを記録した JSON または CSV から、単純な正答率ではなく、名前の付いた 2 つの心理測定モデル（BKT、2PL IRT）を使って、学習者ごと・スキルごとの習熟度スコアを算出する CLI およびライブラリです。TypeScript／Node パッケージと独立した Python 移植版の両方として提供されており、会話をしたり、レッスンを実施したりするものではありません。

どのプラットフォームと言語ランタイムに対応していますか？ TypeScript の CLI／ライブラリには Node.js 18 以降が必要です（package.json の engines.node を参照）。OS 固有のコードパスはありません。Python 移植版には Python 3.9～3.13 が必要で（python/pyproject.toml の分類を参照）、こちらも OS 非依存として宣言されています。どちらの配布版も、データベースやその他のランタイム依存関係を必要としません。

MasteryTrace と pyBKT の具体的な違いは何ですか？ pyBKT（CAHLR／UC Berkeley、前回確認時の GitHub スター数は 272）は、より成熟した BKT 実装です。コンパイル済みの C++ フィッティングコアを備え、忘却や項目順序の影響など、MasteryTrace が対応していない BKT バリエーションもサポートしています。MasteryTrace の BKT は、任意でグリッドサーチによるフィッティングを行える、教科書的な 4 パラメーターの単一モデルであり、意図的にシンプルにしています。選択時に重要な違いは、pyBKT が Python 専用であるのに対し、MasteryTrace は Node／TypeScript パッケージとしても提供され、BKT 専用のライブラリではなく、1 つの CLI（masterytrace score --model bkt|irt|both）から両方のモデルを利用できることです。

npm パッケージはありますか？ はい。npm install -g masterytrace-cli は npm レジストリで公開されています。CI を通過している同じ TypeScript ソースからビルドされており、Python 移植版と同じ 4 つのサブコマンド（init、record、score、report）を提供します。

MasteryTrace を商用製品で使えますか？ はい。TypeScript と Python のコードはいずれも MIT ライセンスです（LICENSE と python/pyproject.toml の対応する分類を参照）。表示を条件に、商用利用、変更、再配布が認められており、保証はありません。

コントリビューション

TypeScript のコードベース（リポジトリのルート）でも Python のコードベース（python/）でも、Issue とプルリクエストを歓迎します。詳しいガイドは CONTRIBUTING.md をご覧ください。TypeScript のクイックスタート：

npm install
npm run lint
npm run typecheck
npm run test:coverage

このプロジェクトでは、ステートメント／行／関数のカバレッジ 100％と、eslint／tsc／npm audit のクリーンな状態を維持しています。これらのいずれかを損なう変更は、そのままではマージされない可能性が高いです。Python のクイックスタートは python/README.md をご覧ください。

ライセンス

MIT。詳しくは LICENSE をご覧ください。