MasteryTrace

Instalação

O MasteryTrace é distribuído como dois pacotes independentes e igualmente de primeira classe que implementam os mesmos dois modelos (BKT, IRT 2PL) e o mesmo contrato de CLI.

npm (CLI TypeScript + biblioteca):

npm install -g masterytrace-cli

Requer Node.js 18 ou posterior.

pip (CLI Python + biblioteca): uma porta Python completa e independente do código-fonte TypeScript deste repositório está em python/ -- os mesmos dois modelos, o mesmo contrato de CLI, sua própria suíte de testes pytest com 75 testes, construída e verificada de ponta a ponta a partir de uma instalação real de wheel.

pip install masterytrace-cli

Isso instala os mesmos quatro subcomandos (init, record, score, report) como um script de console masterytrace, além de uma biblioteca importável masterytrace, uma porta genuína e independente do código-fonte TypeScript deste repositório, não um wrapper em torno do binário Node. Consulte python/README.md para uso específico em Python.

[!NOTE] As distribuições npm e pip retornam dados equivalentes, mas com diferentes padrões de capitalização de chaves JSON (camelCase da CLI TypeScript, snake_case da CLI Python). Leve isso em consideração se você analisar a saída de ambos no mesmo pipeline.

Sumário

• Recursos
• Início rápido
• Referência de comandos da CLI
• Referência da API da biblioteca
• Como funcionam BKT e IRT
• Benchmark
• Comparação
• FAQ
• Contribuindo
• Licença

Recursos

• Dois modelos psicométricos nomeados, não uma pontuação de caixa-preta. O Bayesian Knowledge Tracing gera uma probabilidade de maestria posterior por aluno e por habilidade; o IRT logístico de 2 parâmetros gera uma estimativa contínua de habilidade (theta) por aluno e dificuldade/discriminação do item por habilidade. Execute um ou ambos com --model bkt|irt|both.
• Duas distribuições independentes e numericamente equivalentes. O pacote npm (masterytrace-cli, TypeScript) e o pacote PyPI (masterytrace-cli, Python) são uma porta real, linha por linha, um do outro, não um wrapper Python em torno do binário Node; esta auditoria executou a mesma amostra de 58 eventos em ambos e obteve pontuações de maestria idênticas.
• Analisável por agentes por padrão. Todo comando aceita uma flag global --json, report também aceita --format markdown, e há um contrato real de código de saída com três valores (0 sucesso, 1 erro de uso, 2 dados de evento inválidos) em vez de um único código de falha genérico.
• 162 testes, 100% de cobertura de declarações/linhas/funções. 87 testes TypeScript mais 75 testes Python, incluindo uma verificação de recuperação IRT com dados sintéticos que ajusta 4.000 respostas com parâmetros de verdade conhecidos e fica dentro de 0,2 do theta verdadeiro, dificuldade do item e discriminação do item.
• Sem servidor, sem banco de dados. O estado são dois arquivos JSON em um diretório .masterytrace/ ao lado de onde você executa a CLI. Pontuar 100.000 eventos leva menos de um segundo em um único núcleo.

Início rápido

masterytrace init
masterytrace record events.json
masterytrace score
masterytrace report

init cria um events.json de exemplo (3 alunos, 3 habilidades, várias respostas cada) e um masterytrace.config.json padrão no diretório atual. Saída real desse fluxo:

$ 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 sempre substitui todo o log de eventos armazenado anteriormente; não há modo de anexação. Se você precisar adicionar novas respostas sem perder as existentes, mescle-as em um único arquivo e execute novamente record com o log completo e combinado.

report também aceita --format markdown ou --format json, e todo comando aceita uma flag global --json para saída legível por máquina no stdout, com um contrato real de código de saída (0 sucesso, 1 erro geral/uso, 2 dados de evento inválidos) para que um script ou agente que invoque esta CLI possa ramificar com base no resultado sem analisar texto.

Seu próprio log de eventos é um array JSON de objetos { learnerId, skillId, correct, timestamp }, ou um CSV com cabeçalho learner_id,skill_id,correct,timestamp. timestamp deve ser ISO 8601; correct é um booleano (JSON) ou true/false/1/0 (CSV), e qualquer outro valor em uma célula correct de CSV é rejeitado como erro de validação, em vez de ser tratado silenciosamente como falso. Arquivos de log de eventos acima de 100 MB são rejeitados antecipadamente com um erro claro; logs de eventos são registros estruturados pequenos e não têm razão legítima para se aproximar desse tamanho.

Referência de comandos da CLI

Comando	Argumentos	Opções	Função
masterytrace init		--force	Cria um events.json e masterytrace.config.json de exemplo no diretório atual. Ignora arquivos que já existem, a menos que --force seja passado.
masterytrace record <path>	<path>: log de eventos JSON ou CSV		Valida um log de eventos e o armazena em .masterytrace/events.json. Sempre substitui qualquer log armazenado anteriormente.
masterytrace score		--model <bkt|irt|both> (padrão both)	Ajusta e pontua o log de eventos armazenado, gravando o resultado em .masterytrace/scores.json.
masterytrace report		--format <table|json|markdown> (padrão table)	Lê .masterytrace/scores.json e imprime uma tabela de maestria por aluno e por habilidade.

Opção global: --json força JSON legível por máquina no stdout para qualquer comando, substituindo --format em report.

Códigos de saída: 0 sucesso, 1 erro geral ou de uso (flag inválida, arquivo ausente), 2 erro de validação (o próprio log de eventos está malformado).

Servidor MCP

O MasteryTrace inclui um servidor Model Context Protocol (MCP), para que um agente (Claude Desktop, Claude Code ou qualquer outro cliente MCP) possa invocar a CLI diretamente em vez de executá-la por conta própria.

Instale o pacote Python com o extra mcp:

pip install "masterytrace-cli[mcp]"

Em seguida, aponte um cliente MCP para o script de console masterytrace-mcp. Exemplo de configuração do Claude Desktop (claude_desktop_config.json):

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

O servidor expõe uma única ferramenta, run(args: list[str]) -> dict, que executa a CLI masterytrace instalada com a lista de argumentos fornecida e retorna sua saída analisada -- qualquer subcomando ou flag suportado pela CLI é acessível por meio dela. Exemplo de chamada: run(["score", "--model", "bkt", "--json"]) ajusta um modelo BKT contra o log de eventos armazenado e retorna o relatório de maestria JSON analisado.

Referência da API da biblioteca

Tudo abaixo é exportado do ponto de entrada do pacote masterytrace-cli (src/index.ts, reexportando src/core/* e 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';

Um exemplo mínimo de uso da 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 e IrtModel implementam ambos a mesma interface ScoringModel (fit(events) e depois score(fittedModel)), para que o mecanismo, e seu próprio código, possam tratá-los de forma intercambiável.

Como funcionam BKT e IRT

O MasteryTrace implementa dois modelos psicométricos independentes. Eles respondem a perguntas diferentes e produzem tipos diferentes de números, então masterytrace score --model both os executa lado a lado em vez de escolher um.

Bayesian Knowledge Tracing (BKT)

O BKT modela a maestria de um aluno em uma habilidade como um estado binário oculto (sabe / ainda não sabe) e atualiza uma probabilidade de "sabe" após cada resposta, usando quatro parâmetros:

• pInit: probabilidade de o aluno já saber a habilidade antes de qualquer evidência.
• pTransit: probabilidade de aprender a habilidade entre uma tentativa e a próxima.
• pSlip: probabilidade de uma resposta incorreta apesar de saber a habilidade.
• pGuess: probabilidade de uma resposta correta apesar de não saber a habilidade.

Para cada resposta, a recursão direta primeiro atualiza a crença dado o resultado observado (regra de Bayes) e depois a avança para possível aprendizado antes da próxima tentativa:

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

O MasteryTrace executa essa recursão por aluno e por habilidade, em ordem cronológica, e relata a posteriori final como a probabilidade de maestria desse aluno para essa habilidade. Se você definir "bkt": { "fit": true } em masterytrace.config.json, os quatro parâmetros de cada habilidade são ajustados a partir de seus próprios dados por uma busca em grade grosseira (7 x 7 x 5 x 5 combinações candidatas) que minimiza o erro quadrático entre a correção prevista e a observada, em vez de usar os padrões de livro-texto (pInit=0.4, pTransit=0.3, pSlip=0.1, pGuess=0.2).

Item Response Theory (IRT 2PL)

O IRT modela uma habilidade contínua do aluno (theta) por aluno e dois parâmetros por habilidade tratada como um "item": discriminação (a, quão nitidamente o item separa alunos de alta e baixa habilidade) e dificuldade (b). A probabilidade de uma resposta correta sob o modelo logístico de 2 parâmetros é:

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

O MasteryTrace ajusta todos esses parâmetros conjuntamente por ascensão de gradiente na log-verossimilhança (MLE conjunta), com uma pequena penalidade L2 puxando theta/b em direção a 0 e a em direção a 1. Essa penalidade é o que mantém o ajuste finito para um aluno ou habilidade com um registro todo correto ou todo incorreto, onde a verossimilhança não regularizada seria maximizada no infinito. Como o modelo 2PL só é identificado até um deslocamento e escala de theta (deslocar theta e b pela mesma constante, ou escalar theta/b enquanto divide a de acordo, deixa cada probabilidade prevista inalterada), o ajuste recentraliza theta para média 0 e desvio padrão 1 após cada iteração, a maneira padrão de fixar uma solução única.

Uma verificação real de recuperação

test/irt.test.ts ajusta o modelo contra um conjunto de dados sintético construído a partir de valores de verdade conhecidos de theta/a/b (4.000 respostas em 5 alunos e 4 habilidades) e verifica se os parâmetros recuperados ficam próximos dos verdadeiros após passarem pela mesma normalização de calibração. Realmente executado para este README: erro absoluto máximo foi 0,123 em theta, 0,196 na dificuldade do item e 0,114 na discriminação do item, bem dentro da tolerância de 0,3 do teste, em 26 ms de tempo de ajuste.

Benchmark

Executado localmente contra logs de eventos sintéticos (Node 24, núcleo único, masterytrace score invocado como um subprocesso real, incluindo a inicialização do Node):

Conjunto de dados	Eventos	--model bkt	--model irt	--model both
Pequeno	10.000 (50 alunos x 20 habilidades x 10 respostas)	0,06s	0,10s	0,11s
Grande	100.000 (100 alunos x 50 habilidades x 20 respostas)	0,17s	0,54s	0,60s

BKT com ajuste por busca em grade por habilidade ("bkt": { "fit": true }, uma busca em grade de 1.225 combinações por habilidade) no conjunto de dados de 100.000 eventos levou 1,39s. Todos os números são tempo de parede para o subprocesso completo masterytrace score, incluindo a inicialização do processo Node, então refletem o que executar o comando realmente parece, em vez de um microbenchmark isolado da função de ajuste.

Comparação

O nicho do MasteryTrace é ser uma CLI e uma biblioteca TypeScript ao mesmo tempo, sem exigir runtime Python. Aqui está como ele se compara às bibliotecas estabelecidas mais próximas do que ele faz, cada uma verificada em seu próprio repositório GitHub e página de registro de pacotes:

Projeto	Linguagem	Licença	Tipo	Instalação	Estrelas no GitHub
MasteryTrace	TypeScript/Node + Python	MIT	CLI + biblioteca	pip install masterytrace-cli / npm install -g masterytrace-cli	Novo
pyBKT	Python (núcleo C++)	MIT	Somente biblioteca	pip install pyBKT	272
girth	Python	MIT	Somente biblioteca	pip install girth	124
py-irt	Python (PyTorch/Pyro)	MIT	CLI + biblioteca	pip install py-irt	170
DeepTutor	Python + TypeScript	Apache-2.0	Aplicativo completo de tutoria	pip install -U deeptutor	32.000+
pyBKT (do laboratório CAHLR da UC Berkeley) é a implementação de BKT mais estabelecida e suporta mais variantes de BKT (esquecimento, efeitos de ordem de itens) do que o modelo único de livro-texto com busca em grade do MasteryTrace. girth e py-irt são ambas bibliotecas de TRI; py-irt é a mais pesada das duas, construída sobre PyTorch e Pyro para ajuste acelerado por GPU de modelos de TRI maiores (1PL/2PL/4PL) e inclui sua própria CLI, enquanto girth é uma opção mais leve em Python puro, mais próxima em espírito da implementação de 2PL com ascensão de gradiente regularizada do MasteryTrace. Nenhuma das três é um pacote Node.js nem inclui uma CLI de propósito geral no mesmo formato que masterytrace score/report.

DeepTutor não é uma biblioteca de medição concorrente. É uma plataforma grande e ativamente desenvolvida de tutoria de IA de código aberto (orquestração de agentes, espaços de trabalho de tutoria, memória) que, segundo seu próprio README, não implementa BKT nem TRI. É um alvo de integração plausível: o DeepTutor poderia registrar eventos de resposta e entregá-los ao MasteryTrace para a estimativa de domínio que ele não realiza por conta própria.

O Que É o MasteryTrace e Por Que Ele Existe

O MasteryTrace é uma CLI e biblioteca TypeScript de código aberto que ajusta modelos de Bayesian Knowledge Tracing e Item Response Theory a um registro de eventos de resposta do aprendiz e, em seguida, reporta estimativas calibradas de domínio por aprendiz e por habilidade. Ele existe porque a maioria dos agentes de tutoria de IA de código aberto é construída para manter uma conversa e adaptar uma lição, não para medir o que um aprendiz realmente dominou, enquanto os dois modelos psicométricos que fazem esse trabalho com rigor vivem quase inteiramente em bibliotecas Python, sem equivalente para uma pilha Node ou TypeScript e sem uma CLI que uma ferramenta não-Python possa invocar. O MasteryTrace preenche essa lacuna específica: aponte-o para um registro de eventos JSON ou CSV e receba de volta uma probabilidade de domínio (BKT) e uma estimativa de habilidade (TRI), em um formato que qualquer script, produto de tutoria ou agente possa analisar.

FAQ

Por que não usar apenas pyBKT ou py-irt? Se você quiser mais variantes de BKT (esquecimento, efeitos de ordem de itens) ou ajuste de TRI em escala de GPU, essas são boas escolhas, e a tabela de comparação do MasteryTrace acima diz isso diretamente. O pacote Python do MasteryTrace (pip install masterytrace-cli) cobre os mesmos modelos simples de livro-texto-BKT-com-busca-em-grade e 2PL-IRT regularizado que este repositório implementa, para um pipeline somente Python; o pacote TypeScript (npm install -g masterytrace-cli) cobre adicionalmente o caso em que você quer pontuação de domínio em uma base de código Node sem nenhum runtime Python.

Isso precisa de um banco de dados? Não. O estado são dois arquivos JSON em um diretório .masterytrace/ ao lado de onde você executa a CLI (events.json e scores.json). Não há servidor nem dependência externa para executar.

Posso conectar os dados do meu próprio aplicativo de tutoria? Sim, desde que você consiga produzir um array JSON ou CSV de linhas { learnerId, skillId, correct, timestamp }. Ainda não há adaptador por aplicativo; o genericAdapter incluído cobre ambos os formatos. Se seus dados tiverem um formato diferente, transforme-os para esse formato (ou chame parseResponseEvents em linhas já formatadas) antes de chamar runScoring.

A matemática de BKT/TRI é confiável? Ambos os modelos são testados por unidade contra exemplos trabalhados calculados à mão (BKT) e um conjunto de dados sintético com parâmetros de verdade conhecidos (TRI), além da suíte completa de testes da CLI. Veja Como BKT e TRI funcionam acima para os números reais de recuperação.

O que acontece com uma única resposta, ou nenhuma resposta? Ambos os modelos lidam com isso sem erro: BKT com uma resposta retorna um único posterior; um registro de eventos vazio retorna um relatório vazio para qualquer um dos modelos, em vez de lançar uma exceção.

O que é o MasteryTrace, em uma frase? É uma CLI e biblioteca, distribuída tanto como pacote TypeScript/Node quanto como porta Python independente, que transforma um registro JSON ou CSV de eventos de resposta do aprendiz em pontuações de domínio por aprendiz e por habilidade usando dois modelos psicométricos nomeados (BKT, 2PL IRT) em vez de percentual bruto de acertos; ele não mantém uma conversa nem executa uma lição por conta própria.

Quais plataformas e runtimes de linguagem ele suporta? A CLI/biblioteca TypeScript requer Node.js 18 ou posterior (veja engines.node em package.json) e não tem caminho de código específico de SO. A porta Python requer Python 3.9 a 3.13 (veja os classificadores em python/pyproject.toml) e também é declarada independente de SO. Nenhuma das distribuições precisa de banco de dados ou qualquer outra dependência de runtime.

Como o MasteryTrace se compara especificamente ao pyBKT? pyBKT (CAHLR/UC Berkeley, 272 estrelas no GitHub na última verificação) é a implementação de BKT mais madura: tem um núcleo de ajuste compilado em C++ e suporta variantes de BKT que o MasteryTrace não suporta, como esquecimento e efeitos de ordem de itens. O BKT do MasteryTrace é o modelo único de livro-texto de quatro parâmetros mais um ajuste opcional por busca em grade, deliberadamente mais simples. A diferença que importa para escolher entre eles: pyBKT é somente Python, o MasteryTrace também é distribuído como pacote Node/TypeScript e expõe ambos os modelos por trás de uma única CLI (masterytrace score --model bkt|irt|both) em vez de uma biblioteca somente BKT.

Existe um pacote npm? Sim, npm install -g masterytrace-cli está publicado no registro npm. Ele inclui os mesmos quatro subcomandos (init, record, score, report) que a porta Python, construídos a partir do mesmo código-fonte TypeScript que passa na CI.

Posso usar o MasteryTrace em um produto comercial? Sim. Tanto o código TypeScript quanto o Python são licenciados sob MIT (veja LICENSE e o classificador correspondente em python/pyproject.toml), o que permite uso comercial, modificação e redistribuição com atribuição e não oferece garantia.

Contribuindo

Issues e pull requests são bem-vindos, tanto para a base de código TypeScript (raiz do repositório) quanto para a base de código Python (python/). Veja CONTRIBUTING.md para o guia completo. Início rápido em TypeScript:

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

O projeto mantém 100% de cobertura de declarações/linhas/funções e um eslint/tsc/npm audit limpo; uma mudança que reduza qualquer um desses provavelmente não será mesclada como está. Início rápido em Python em python/README.md.

Licença

MIT, veja LICENSE.