MasteryTrace

Instalación

MasteryTrace se distribuye como dos paquetes independientes, ambos de primera clase, que implementan los mismos dos modelos (BKT, IRT 2PL) y el mismo contrato de CLI.

npm (CLI + biblioteca TypeScript):

npm install -g masterytrace-cli

Requiere Node.js 18 o posterior.

pip (CLI + biblioteca Python): un puerto Python completo e independiente del código fuente TypeScript de este repositorio vive en python/ -- los mismos dos modelos, el mismo contrato de CLI, su propia suite de pruebas pytest con 75 pruebas, construido y verificado de extremo a extremo desde una instalación real de wheel.

pip install masterytrace-cli

Esto instala los mismos cuatro subcomandos (init, record, score, report) como un script de consola masterytrace, además de una biblioteca importable masterytrace, un puerto genuino e independiente del código fuente TypeScript de este repositorio, no un envoltorio alrededor del binario de Node. Consulta python/README.md para el uso específico de Python.

[!NOTE] Las distribuciones npm y pip devuelven datos equivalentes pero con diferente capitalización de claves JSON (camelCase desde la CLI TypeScript, snake_case desde la CLI Python). Ten esto en cuenta si analizas la salida de ambos en el mismo pipeline.

Tabla de contenidos

• Características
• Inicio rápido
• Referencia de comandos CLI
• Referencia de la API de biblioteca
• Cómo funcionan BKT e IRT
• Benchmark
• Comparación
• Preguntas frecuentes
• Contribuciones
• Licencia

Características

• Dos modelos psicométricos nombrados, no una puntuación de caja negra. El Rastreo Bayesiano del Conocimiento genera una probabilidad de dominio posterior por alumno y por habilidad; el IRT logístico de 2 parámetros genera una estimación continua de habilidad (theta) por alumno y dificultad/discriminación de ítem por habilidad. Ejecuta uno o ambos con --model bkt|irt|both.
• Dos distribuciones independientes y numéricamente equivalentes. El paquete npm (masterytrace-cli, TypeScript) y el paquete PyPI (masterytrace-cli, Python) son un puerto real línea por línea el uno del otro, no un envoltorio Python alrededor del binario de Node; esta auditoría ejecutó la misma muestra de 58 eventos a través de ambos y obtuvo puntuaciones de dominio idénticas.
• Analizable por agentes de forma predeterminada. Cada comando acepta una bandera global --json, report también acepta --format markdown, y hay un contrato real de códigos de salida de tres valores (0 éxito, 1 error de uso, 2 datos de evento incorrectos) en lugar de un único código de fallo genérico.
• 162 pruebas, 100% de cobertura de sentencias/líneas/funciones. 87 pruebas TypeScript más 75 pruebas Python, incluida una verificación de recuperación IRT con datos sintéticos que ajusta 4,000 respuestas con parámetros de verdad conocidos y aterriza dentro de 0.2 del theta verdadero, dificultad de ítem y discriminación de ítem.
• Sin servidor, sin base de datos. El estado son dos archivos JSON en un directorio .masterytrace/ junto a donde ejecutas la CLI. Puntuar 100,000 eventos toma menos de un segundo en un solo núcleo.

Inicio rápido

masterytrace init
masterytrace record events.json
masterytrace score
masterytrace report

init genera un events.json de muestra (3 alumnos, 3 habilidades, varias respuestas cada uno) y un masterytrace.config.json predeterminado en el directorio actual. Salida real de ese flujo:

$ 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
...

[!WARNING] masterytrace record siempre reemplaza por completo el registro de eventos previamente almacenado; no hay modo de anexar. Si necesitas agregar nuevas respuestas sin perder las existentes, combínalas en un solo archivo y vuelve a ejecutar record con el registro completo y combinado.

report también acepta --format markdown o --format json, y cada comando acepta una bandera global --json para salida legible por máquina en stdout, con un contrato real de códigos de salida (0 éxito, 1 error general/de uso, 2 datos de evento incorrectos) para que un script o agente que invoque esta CLI pueda ramificar según el resultado sin analizar texto.

Tu propio registro de eventos es un arreglo JSON de objetos { learnerId, skillId, correct, timestamp }, o un CSV con encabezado learner_id,skill_id,correct,timestamp. timestamp debe ser ISO 8601; correct es un booleano (JSON) o true/false/1/0 (CSV), y cualquier otro valor en una celda correct de CSV se rechaza como error de validación en lugar de tratarse silenciosamente como falso. Los archivos de registro de eventos de más de 100 MB se rechazan de antemano con un error claro; los registros de eventos son registros estructurados pequeños y no tienen razón legítima para acercarse a ese tamaño.

Referencia de comandos CLI

Comando	Argumentos	Opciones	Función
masterytrace init		--force	Genera un events.json y masterytrace.config.json de muestra en el directorio actual. Omite archivos que ya existen a menos que se pase --force.
masterytrace record <path>	<path>: registro de eventos JSON o CSV		Valida un registro de eventos y lo almacena en .masterytrace/events.json. Siempre reemplaza cualquier registro previamente almacenado.
masterytrace score		--model <bkt|irt|both> (predeterminado both)	Ajusta y puntúa el registro de eventos almacenado, escribiendo el resultado en .masterytrace/scores.json.
masterytrace report		--format <table|json|markdown> (predeterminado table)	Lee .masterytrace/scores.json e imprime una tabla de dominio por alumno y por habilidad.

Opción global: --json fuerza JSON legible por máquina en stdout para cualquier comando, anulando --format en report.

Códigos de salida: 0 éxito, 1 error general o de uso (bandera incorrecta, archivo faltante), 2 error de validación (el registro de eventos en sí está malformado).

Servidor MCP

MasteryTrace incluye un servidor de Protocolo de Contexto de Modelo (MCP), para que un agente (Claude Desktop, Claude Code o cualquier otro cliente MCP) pueda invocar la CLI directamente en lugar de ejecutarla por sí mismo.

Instala el paquete Python con el extra mcp:

pip install "masterytrace-cli[mcp]"

Luego apunta un cliente MCP al script de consola masterytrace-mcp. Ejemplo de configuración de Claude Desktop (claude_desktop_config.json):

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

El servidor expone una sola herramienta, run(args: list[str]) -> dict, que ejecuta la CLI masterytrace instalada con la lista de argumentos dada y devuelve su salida analizada -- cualquier subcomando o bandera que la CLI soporte es alcanzable a través de ella. Ejemplo de llamada: run(["score", "--model", "bkt", "--json"]) ajusta un modelo BKT contra el registro de eventos almacenado y devuelve el informe JSON de dominio analizado.

Referencia de la API de biblioteca

Todo lo siguiente se exporta desde el punto de entrada del paquete masterytrace-cli (src/index.ts, reexportando src/core/* y 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';

Un ejemplo mínimo de uso de la biblioteca:

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 y IrtModel ambos implementan la misma interfaz ScoringModel (fit(events) luego score(fittedModel)), por lo que el motor, y tu propio código, pueden tratarlos de manera intercambiable.

Cómo funcionan BKT e IRT

MasteryTrace implementa dos modelos psicométricos independientes. Responden preguntas diferentes y producen tipos diferentes de números, por lo que masterytrace score --model both los ejecuta lado a lado en lugar de elegir uno.

Rastreo Bayesiano del Conocimiento (BKT)

BKT modela el dominio de una habilidad por parte de un alumno como un estado binario oculto (la sabe / aún no la sabe) y actualiza una probabilidad de "la sabe" después de cada respuesta, usando cuatro parámetros:

• pInit: probabilidad de que el alumno ya sepa la habilidad antes de cualquier evidencia.
• pTransit: probabilidad de aprender la habilidad entre un intento y el siguiente.
• pSlip: probabilidad de una respuesta incorrecta a pesar de saber la habilidad.
• pGuess: probabilidad de una respuesta correcta a pesar de no saber la habilidad.

Para cada respuesta, la recursión hacia adelante primero actualiza la creencia dado el resultado observado (regla de Bayes), luego la avanza para un posible aprendizaje antes del siguiente intento:

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 ejecuta esta recursión por alumno y por habilidad, en orden cronológico, e informa el posterior final como la probabilidad de dominio de ese alumno para esa habilidad. Si estableces "bkt": { "fit": true } en masterytrace.config.json, los cuatro parámetros de cada habilidad se ajustan a partir de tus propios datos mediante una búsqueda de cuadrícula gruesa (7 x 7 x 5 x 5 combinaciones candidatas) que minimiza el error cuadrático entre la corrección predicha y la observada, en lugar de usar los valores predeterminados de los libros de texto (pInit=0.4, pTransit=0.3, pSlip=0.1, pGuess=0.2).

Teoría de Respuesta al Ítem (IRT 2PL)

IRT modela una habilidad continua del alumno (theta) por alumno y dos parámetros por habilidad tratada como un "ítem": discriminación (a, qué tan nítidamente el ítem separa a los alumnos de alta y baja habilidad) y dificultad (b). La probabilidad de una respuesta correcta bajo el modelo logístico de 2 parámetros es:

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

MasteryTrace ajusta todos estos conjuntamente mediante ascenso de gradiente en la log-verosimilitud (MLE conjunto), con una pequeña penalización L2 que empuja theta/b hacia 0 y a hacia 1. Esa penalización es lo que mantiene el ajuste finito para un alumno o habilidad con un registro todo correcto o todo incorrecto, donde la verosimilitud no regularizada se maximizaría en el infinito. Debido a que el modelo 2PL solo está identificado hasta un desplazamiento y escala de theta (desplazar theta y b por la misma constante, o escalar theta/b mientras se divide a en consecuencia, deja cada probabilidad predicha sin cambios), el ajuste vuelve a centrar theta a media 0 y desviación estándar 1 después de cada iteración, la forma estándar de fijar una solución única.

Una verificación de recuperación real

test/irt.test.ts ajusta el modelo contra un conjunto de datos sintético construido a partir de valores de verdad conocidos theta/a/b (4,000 respuestas en 5 alumnos y 4 habilidades) y verifica que los parámetros recuperados aterricen cerca de los verdaderos una vez sometidos a la misma normalización de calibre. Realmente ejecutado para este README: el error absoluto máximo fue 0.123 en theta, 0.196 en dificultad de ítem y 0.114 en discriminación de ítem, muy dentro de la tolerancia de 0.3 de la prueba, en 26 ms de tiempo de ajuste.

Benchmark

Ejecutado localmente contra registros de eventos sintéticos (Node 24, un solo núcleo, masterytrace score invocado como un subproceso real incluido el arranque de Node):

Conjunto de datos	Eventos	--model bkt	--model irt	--model both
Pequeño	10,000 (50 alumnos x 20 habilidades x 10 respuestas)	0.06s	0.10s	0.11s
Grande	100,000 (100 alumnos x 50 habilidades x 20 respuestas)	0.17s	0.54s	0.60s

BKT con ajuste de búsqueda de cuadrícula por habilidad ("bkt": { "fit": true }, una búsqueda de cuadrícula de 1,225 combinaciones por habilidad) en el conjunto de datos de 100,000 eventos tomó 1.39s. Todas las cifras son tiempo de pared para el subproceso completo masterytrace score, incluido el arranque del proceso de Node, por lo que reflejan lo que realmente se siente al ejecutar el comando en lugar de un microbenchmark aislado de la función de ajuste.

Comparación

El nicho propio de MasteryTrace es ser una CLI y una biblioteca TypeScript a la vez, sin requerir un runtime de Python. Aquí se compara con las bibliotecas establecidas más cercanas a lo que hace, cada una verificada contra su propio repositorio de GitHub y página de registro de paquetes:

Proyecto	Lenguaje	Licencia	Tipo	Instalación	Estrellas de GitHub
MasteryTrace	TypeScript/Node + Python	MIT	CLI + biblioteca	pip install masterytrace-cli / npm install -g masterytrace-cli	Nuevo
pyBKT	Python (núcleo C++)	MIT	Solo biblioteca	pip install pyBKT	272
girth	Python	MIT	Solo biblioteca	pip install girth	124
py-irt	Python (PyTorch/Pyro)	MIT	CLI + biblioteca	pip install py-irt	170
DeepTutor	Python + TypeScript	Apache-2.0	Aplicación completa de tutoría	pip install -U deeptutor	32,000+
pyBKT (del laboratorio CAHLR de UC Berkeley) es la implementación de BKT más consolidada y admite más variantes de BKT (olvido, efectos de orden de ítems) que el modelo único de libro de texto más búsqueda en cuadrícula de MasteryTrace. girth y py-irt son ambas bibliotecas de IRT; py-irt es la más pesada de las dos, construida sobre PyTorch y Pyro para el ajuste acelerado por GPU de modelos IRT más grandes (1PL/2PL/4PL) e incluye su propia CLI, mientras que girth es una opción más ligera de Python puro más cercana en espíritu a la implementación de 2PL con ascenso de gradiente regularizado de MasteryTrace. Ninguna de las tres es un paquete de Node.js ni incluye una CLI de propósito general con la misma forma que masterytrace score/report.

DeepTutor no es una biblioteca de medición competidora. Es una plataforma de tutoría de IA de código abierto grande y en desarrollo activo (orquestación de agentes, espacios de trabajo de tutoría, memoria) que, según su propio README, no implementa BKT ni IRT por sí misma. Es un objetivo de integración plausible: DeepTutor podría registrar eventos de respuesta y pasarlos a MasteryTrace para la estimación de dominio que de otro modo no realiza.

Qué es MasteryTrace y por qué existe

MasteryTrace es una CLI y biblioteca de TypeScript de código abierto que ajusta modelos de Rastreo de Conocimiento Bayesiano y Teoría de Respuesta al Ítem a un registro de eventos de respuesta de aprendices, y luego informa estimaciones de dominio calibradas por aprendiz y por habilidad. Existe porque la mayoría de los agentes de tutoría de IA de código abierto están construidos para mantener una conversación y adaptar una lección, no para medir lo que un aprendiz ha dominado realmente, mientras que los dos modelos psicométricos que hacen ese trabajo rigurosamente viven casi por completo en bibliotecas de Python sin equivalente para una pila de Node o TypeScript y sin una CLI a la que una herramienta que no sea de Python pueda invocar. MasteryTrace llena ese vacío específico: apúntalo a un registro de eventos JSON o CSV, obtén una probabilidad de dominio (BKT) y una estimación de habilidad (IRT), en un formato que cualquier script, producto de tutoría o agente pueda analizar.

Preguntas frecuentes

¿Por qué no usar simplemente pyBKT o py-irt? Si quieres más variantes de BKT (olvido, efectos de orden de ítems) o ajuste de IRT a escala de GPU, esas son buenas opciones, y la tabla comparativa de MasteryTrace lo dice directamente. El paquete de Python de MasteryTrace (pip install masterytrace-cli) cubre los mismos modelos simples de BKT de libro de texto más búsqueda en cuadrícula y de IRT 2PL regularizado que implementa este repositorio, para un pipeline solo de Python; el paquete de TypeScript (npm install -g masterytrace-cli) además cubre el caso en el que quieres puntuación de dominio en una base de código de Node sin ningún runtime de Python.

¿Necesita una base de datos? No. El estado son dos archivos JSON en un directorio .masterytrace/ junto a donde ejecutas la CLI (events.json y scores.json). No hay servidor ni dependencia externa para ejecutarlo.

¿Puedo conectar los datos de mi propia aplicación de tutoría? Sí, siempre que puedas producir un arreglo JSON o CSV de filas { learnerId, skillId, correct, timestamp }. Aún no hay un adaptador por aplicación; el genericAdapter incluido cubre ambos formatos. Si tus datos tienen una forma diferente, transfórmalos a esa forma (o llama a parseResponseEvents en filas ya formateadas) antes de llamar a runScoring.

¿Es confiable la matemática de BKT/IRT? Ambos modelos están probados con pruebas unitarias contra ejemplos resueltos a mano (BKT) y un conjunto de datos sintético con parámetros de verdad conocidos (IRT), además de la suite completa de pruebas de la CLI. Consulta Cómo funcionan BKT e IRT arriba para los números reales de recuperación.

¿Qué sucede con una sola respuesta, o sin respuestas en absoluto? Ambos modelos lo manejan sin errores: BKT con una respuesta devuelve un único posterior; un registro de eventos vacío devuelve un informe vacío para cualquiera de los modelos en lugar de lanzar una excepción.

¿Qué es MasteryTrace, en una frase? Es una CLI y biblioteca, distribuida tanto como paquete de TypeScript/Node como un puerto independiente de Python, que convierte un registro JSON o CSV de eventos de respuesta de aprendices en puntuaciones de dominio por aprendiz y por habilidad usando dos modelos psicométricos nombrados (BKT, IRT 2PL) en lugar de un porcentaje bruto de aciertos; no mantiene una conversación ni ejecuta una lección por sí misma.

¿Qué plataformas y runtimes de lenguaje admite? La CLI/biblioteca de TypeScript requiere Node.js 18 o posterior (consulta engines.node en package.json) y no tiene rutas de código específicas del sistema operativo. El puerto de Python requiere Python 3.9 a 3.13 (consulta los clasificadores en python/pyproject.toml) y también se declara independiente del sistema operativo. Ninguna de las dos distribuciones necesita una base de datos ni ninguna otra dependencia de runtime.

¿Cómo se compara MasteryTrace con pyBKT específicamente? pyBKT (CAHLR/UC Berkeley, 272 estrellas de GitHub en la última verificación) es la implementación de BKT más madura: tiene un núcleo de ajuste compilado en C++ y admite variantes de BKT que MasteryTrace no tiene, como olvido y efectos de orden de ítems. El BKT de MasteryTrace es el modelo único de libro de texto de cuatro parámetros más un ajuste opcional de búsqueda en cuadrícula, deliberadamente más simple. La diferencia que importa para elegir entre ellos: pyBKT es solo de Python, MasteryTrace también se distribuye como paquete de Node/TypeScript y expone ambos modelos detrás de una sola CLI (masterytrace score --model bkt|irt|both) en lugar de una biblioteca solo de BKT.

¿Hay un paquete npm? Sí, npm install -g masterytrace-cli está disponible en el registro npm. Incluye los mismos cuatro subcomandos (init, record, score, report) que el puerto de Python, construidos desde la misma fuente de TypeScript que pasa CI.

¿Puedo usar MasteryTrace en un producto comercial? Sí. Tanto el código de TypeScript como el de Python tienen licencia MIT (consulta LICENCIA y el clasificador correspondiente en python/pyproject.toml), lo que permite uso comercial, modificación y redistribución con atribución y sin garantía.

Contribuciones

Se aceptan problemas y solicitudes de extracción, tanto para la base de código de TypeScript (raíz del repositorio) como para la de Python (python/). Consulta CONTRIBUTING.md para la guía completa. Inicio rápido de TypeScript:

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

El proyecto mantiene una cobertura del 100% de sentencias/líneas/funciones y un eslint/tsc/npm audit limpio; un cambio que reduzca cualquiera de esos es poco probable que se fusione tal como está. Inicio rápido de Python en python/README.md.

Licencia

MIT, consulta LICENCIA.