masterytrace-cli 0.1.0__py3-none-any.whl

masterytrace/__init__.py

@@ -0,0 +1,68 @@
+"""
+MasteryTrace: Mastery Measurement API and CLI. Fits Bayesian Knowledge
+Tracing (BKT) and 2-parameter logistic Item Response Theory (IRT) models
+to learner response logs and reports per-learner, per-skill mastery
+estimates.
+
+Re-exports mirror src/index.ts's re-export surface (core/*, models/*,
+adapters/*) so `from masterytrace import ...` covers the same public API
+as the npm package's `from 'masterytrace-cli'`.
+"""
+from .adapters.generic_adapter import GenericAdapter, generic_adapter, parse_csv
+from .core.config import DEFAULT_CONFIG, MasteryTraceConfig, load_config
+from .core.engine import EngineConfig, EngineResult, ModelSelector, run_scoring
+from .core.event_schema import EventValidationError, ResponseEvent, parse_response_events
+from .core.scoring_model import FittedModel, MasteryLearnerEntry, MasteryReport, MasterySkillEntry, ScoringModel
+from .models.bkt import (
+    BKT_DEFAULT_PARAMS,
+    BktConfig,
+    BktFittedModel,
+    BktModel,
+    BktParams,
+    fit_skill_params_by_grid_search,
+    run_forward_recursion,
+)
+from .models.irt import (
+    IrtConfig,
+    IrtFittedModel,
+    IrtItemParams,
+    IrtLearnerResult,
+    IrtModel,
+    probability_correct,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "GenericAdapter",
+    "generic_adapter",
+    "parse_csv",
+    "DEFAULT_CONFIG",
+    "MasteryTraceConfig",
+    "load_config",
+    "EngineConfig",
+    "EngineResult",
+    "ModelSelector",
+    "run_scoring",
+    "EventValidationError",
+    "ResponseEvent",
+    "parse_response_events",
+    "FittedModel",
+    "MasteryLearnerEntry",
+    "MasteryReport",
+    "MasterySkillEntry",
+    "ScoringModel",
+    "BKT_DEFAULT_PARAMS",
+    "BktConfig",
+    "BktFittedModel",
+    "BktModel",
+    "BktParams",
+    "fit_skill_params_by_grid_search",
+    "run_forward_recursion",
+    "IrtConfig",
+    "IrtFittedModel",
+    "IrtItemParams",
+    "IrtLearnerResult",
+    "IrtModel",
+    "probability_correct",
+]

masterytrace/adapters/generic_adapter.py

@@ -0,0 +1,134 @@
+"""
+A source of response events: reads a JSON array of response events, or a
+CSV file with columns `learner_id,skill_id,correct,timestamp`, chosen by
+file extension. Ported from src/adapters/generic-adapter.ts, including its
+size guard and its symlink refusal.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, List, Union
+
+from ..core.event_schema import ResponseEvent, parse_response_events
+
+# Event logs are small structured records (a handful of fields per
+# response event); there is no legitimate reason for one to approach this
+# size. This guard exists for the case where masterytrace is invoked
+# programmatically (e.g. by another agent/tool) on a file it did not
+# choose itself: without it, an oversized file is read fully into memory
+# and handed to json.loads before any validation runs, which can exhaust
+# memory or hang the process well before the "not valid event data" error
+# a bad file should produce.
+MAX_EVENT_LOG_BYTES = 100 * 1024 * 1024  # 100 MB
+
+_CSV_COLUMNS = ("learner_id", "skill_id", "correct", "timestamp")
+
+
+def _assert_readable_regular_file(path: Union[str, Path]) -> None:
+    """
+    os.lstat (not os.stat) never follows a symlink, so a symlink at
+    `path` is caught here even if its target is a regular file elsewhere
+    on disk.
+    """
+    stats = os.lstat(path)
+    import stat as stat_module
+
+    if stat_module.S_ISLNK(stats.st_mode):
+        raise ValueError(f"Refusing to read '{path}': symlinks are not supported for event log paths.")
+    if not stat_module.S_ISREG(stats.st_mode):
+        raise ValueError(f"Refusing to read '{path}': not a regular file.")
+    if stats.st_size > MAX_EVENT_LOG_BYTES:
+        size_mb = stats.st_size / (1024 * 1024)
+        limit_mb = MAX_EVENT_LOG_BYTES / (1024 * 1024)
+        raise ValueError(
+            f"Refusing to read '{path}': file is {size_mb:.1f} MB, which exceeds the {limit_mb:.0f} MB event log size limit."
+        )
+
+
+def _parse_csv_boolean(raw: str) -> Union[bool, str]:
+    """
+    Parses a CSV `correct` cell into a boolean. Only recognizes
+    `true`/`false` and `1`/`0` (case-insensitive, trimmed); anything else
+    is returned as the original raw string rather than silently guessed.
+    That matters: coercing every unrecognized value to False would make a
+    typo, an empty cell from a shifted column, or a "yes"/"no" export
+    format silently record as an incorrect response instead of surfacing
+    as bad data. Returning the raw string instead lets it fail
+    ResponseEvent validation's `correct` boolean check with a clear,
+    row-numbered validation error, exactly like malformed JSON input does.
+    """
+    normalized = raw.strip().lower()
+    if normalized in ("true", "1"):
+        return True
+    if normalized in ("false", "0"):
+        return False
+    return raw
+
+
+def parse_csv(content: str) -> List[Any]:
+    """
+    Parses the fixed-column CSV format (`learner_id,skill_id,correct,
+    timestamp`) into the raw row shape event-schema expects, so it goes
+    through the same validation as JSON input. Deliberately hand-rolled
+    rather than pulling in a CSV library: the format has no quoting/
+    escaping requirements (skill and learner ids are plain identifiers),
+    so a dependency would buy nothing.
+    """
+    lines = [line for line in content.splitlines() if line.strip()]
+    if not lines:
+        return []
+
+    header = [h.strip() for h in lines[0].split(",")]
+    column_index = {name: i for i, name in enumerate(header)}
+    for required in _CSV_COLUMNS:
+        if required not in column_index:
+            raise ValueError(
+                f"CSV event log is missing required column '{required}'. Expected header: {','.join(_CSV_COLUMNS)}"
+            )
+
+    rows: List[Any] = []
+    for line in lines[1:]:
+        cells = line.split(",")
+
+        def cell(name: str) -> str:
+            index = column_index.get(name)
+            if index is None or index >= len(cells):
+                return ""
+            return cells[index].strip()
+
+        rows.append(
+            {
+                "learnerId": cell("learner_id"),
+                "skillId": cell("skill_id"),
+                "correct": _parse_csv_boolean(cell("correct")),
+                "timestamp": cell("timestamp"),
+            }
+        )
+    return rows
+
+
+class GenericAdapter:
+    """
+    The only event-log adapter shipped in v0.1: reads a JSON array of
+    response events, or a CSV file with columns
+    `learner_id,skill_id,correct,timestamp`, chosen by file extension.
+    """
+
+    name = "generic"
+
+    def load(self, path: Union[str, Path]) -> List[ResponseEvent]:
+        _assert_readable_regular_file(path)
+        content = Path(path).read_text(encoding="utf-8")
+        extension = Path(path).suffix.lower()
+
+        if extension == ".csv":
+            raw: Any = parse_csv(content)
+        else:
+            raw = json.loads(content)
+
+        return parse_response_events(raw)
+
+
+generic_adapter = GenericAdapter()

masterytrace/cli/commands/init.py

@@ -0,0 +1,57 @@
+"""
+Scaffolds a bundled sample `events.json` (3 learners x 3 skills, several
+responses each) and a default `masterytrace.config.json` in `cwd`.
+Ported from src/cli/commands/init.ts.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from ...core.config import DEFAULT_CONFIG
+from ...data.sample_events import SAMPLE_EVENTS
+from ..format import ok
+from ..json_encode import to_jsonable
+from ..types import CommandResult
+
+EVENTS_SAMPLE_FILENAME = "events.json"
+CONFIG_FILENAME = "masterytrace.config.json"
+
+
+@dataclass
+class InitOptions:
+    json: bool
+    force: bool
+
+
+def run_init(cwd: str, options: InitOptions) -> CommandResult:
+    """
+    Existing files are left untouched unless `--force` is passed.
+    """
+    events_path = Path(cwd) / EVENTS_SAMPLE_FILENAME
+    config_path = Path(cwd) / CONFIG_FILENAME
+
+    created = []
+    skipped = []
+
+    if not options.force and events_path.exists():
+        skipped.append(EVENTS_SAMPLE_FILENAME)
+    else:
+        events_path.write_text(json.dumps(to_jsonable(SAMPLE_EVENTS), indent=2) + "\n", encoding="utf-8")
+        created.append(EVENTS_SAMPLE_FILENAME)
+
+    if not options.force and config_path.exists():
+        skipped.append(CONFIG_FILENAME)
+    else:
+        config_path.write_text(json.dumps(DEFAULT_CONFIG, indent=2) + "\n", encoding="utf-8")
+        created.append(CONFIG_FILENAME)
+
+    lines = []
+    if created:
+        lines.append(f"Created: {', '.join(created)}")
+    if skipped:
+        lines.append(f"Skipped (already exists, use --force to overwrite): {', '.join(skipped)}")
+    lines.append("Next: run 'masterytrace record events.json' to load it, then 'masterytrace score'.")
+
+    return ok(options.json, {"created": created, "skipped": skipped}, "\n".join(lines) + "\n")

masterytrace/cli/commands/record.py

@@ -0,0 +1,51 @@
+"""
+Validates and loads an event log (JSON or CSV, chosen by file extension)
+and stores it to `.masterytrace/events.json`. Storing always *replaces*
+any previously stored log in v0.1 (there is no append/merge mode yet).
+Ported from src/cli/commands/record.ts.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from ...adapters.generic_adapter import generic_adapter
+from ...core.event_schema import EventValidationError
+from ..format import fail, ok
+from ..json_encode import to_jsonable
+from ..types import CommandResult
+
+STATE_DIR = ".masterytrace"
+EVENTS_STATE_FILENAME = "events.json"
+
+
+@dataclass
+class RecordOptions:
+    json: bool
+
+
+def run_record(cwd: str, event_log_path: str, options: RecordOptions) -> CommandResult:
+    try:
+        events = generic_adapter.load(event_log_path)
+    except EventValidationError as error:
+        return fail(
+            2,
+            options.json,
+            {"error": str(error), "issues": error.issues},
+            f"Validation error:\n{error}\n",
+        )
+    except Exception as error:  # noqa: BLE001 -- mirrors the TS catch-all for I/O/parse errors
+        return fail(1, options.json, {"error": str(error)}, f"Error: {error}\n")
+
+    state_dir = Path(cwd) / STATE_DIR
+    state_dir.mkdir(parents=True, exist_ok=True)
+    state_path = state_dir / EVENTS_STATE_FILENAME
+    state_path.write_text(json.dumps(to_jsonable(events), indent=2) + "\n", encoding="utf-8")
+
+    return ok(
+        options.json,
+        {"eventCount": len(events), "storedAt": str(state_path)},
+        f"Stored {len(events)} event(s) to {state_path}\n"
+        "(record replaces any previously stored event log; see --help for details.)\n",
+    )

masterytrace/cli/commands/report.py

@@ -0,0 +1,102 @@
+"""
+Reads `.masterytrace/scores.json` (written by `masterytrace score`) and
+prints a per-learner, per-skill mastery table in the requested format.
+Ported from src/cli/commands/report.ts.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List
+
+from ..format import fail
+from ..types import CommandResult
+from .record import STATE_DIR
+from .score import SCORES_STATE_FILENAME
+
+ReportFormat = str  # "table" | "json" | "markdown"
+
+
+@dataclass
+class ReportOptions:
+    json: bool
+    format: ReportFormat
+
+
+def _build_rows(result: Dict[str, Any]) -> List[Dict[str, Any]]:
+    rows: List[Dict[str, Any]] = []
+    for report in result.get("reports", []):
+        for learner in report.get("learners", []):
+            for skill in learner.get("skills", []):
+                rows.append(
+                    {
+                        "learner_id": learner["learner_id"],
+                        "skill_id": skill["skill_id"],
+                        "model": report["model"],
+                        "metric": skill["metric"],
+                        "value": skill["value"],
+                        "response_count": skill["response_count"],
+                    }
+                )
+    rows.sort(key=lambda r: (r["learner_id"], r["skill_id"], r["model"]))
+    return rows
+
+
+_TABLE_HEADER = ["learner", "skill", "model", "metric", "value", "responses"]
+
+
+def _render_table(rows: List[Dict[str, Any]]) -> str:
+    if not rows:
+        return "No scores found.\n"
+    data = [
+        [r["learner_id"], r["skill_id"], r["model"], r["metric"], f"{r['value']:.4f}", str(r["response_count"])]
+        for r in rows
+    ]
+    widths = [max(len(_TABLE_HEADER[i]), *(len(row[i]) for row in data)) for i in range(len(_TABLE_HEADER))]
+
+    def render_row(cells: List[str]) -> str:
+        return "  ".join(cell.ljust(widths[i]) for i, cell in enumerate(cells))
+
+    lines = [render_row(_TABLE_HEADER), render_row(["-" * w for w in widths])]
+    lines.extend(render_row(row) for row in data)
+    return "\n".join(lines) + "\n"
+
+
+def _render_markdown(rows: List[Dict[str, Any]]) -> str:
+    if not rows:
+        return "No scores found.\n"
+    lines = [
+        f"| {' | '.join(_TABLE_HEADER)} |",
+        f"| {' | '.join('---' for _ in _TABLE_HEADER)} |",
+    ]
+    for r in rows:
+        lines.append(
+            f"| {r['learner_id']} | {r['skill_id']} | {r['model']} | {r['metric']} | {r['value']:.4f} | {r['response_count']} |"
+        )
+    return "\n".join(lines) + "\n"
+
+
+def run_report(cwd: str, options: ReportOptions) -> CommandResult:
+    scores_path = Path(cwd) / STATE_DIR / SCORES_STATE_FILENAME
+    if not scores_path.exists():
+        message = f"No scores found at {scores_path}. Run 'masterytrace score' first."
+        return fail(1, options.json, {"error": message}, f"{message}\n")
+
+    try:
+        result = json.loads(scores_path.read_text(encoding="utf-8"))
+    except Exception as error:  # noqa: BLE001 -- mirrors the TS catch-all for parse errors
+        return fail(1, options.json, {"error": str(error)}, f"Error reading scores: {error}\n")
+
+    if options.json:
+        return CommandResult(exit_code=0, stdout=f"{json.dumps(result)}\n")
+
+    rows = _build_rows(result)
+    if options.format == "markdown":
+        text = _render_markdown(rows)
+    elif options.format == "json":
+        text = json.dumps(result, indent=2) + "\n"
+    else:
+        text = _render_table(rows)
+
+    return CommandResult(exit_code=0, stdout=text)

masterytrace/cli/commands/score.py

@@ -0,0 +1,63 @@
+"""
+Fits and scores the stored event log (`.masterytrace/events.json`,
+written by `masterytrace record`) with the requested model(s), writing
+the unified report(s) to `.masterytrace/scores.json`. Ported from
+src/cli/commands/score.ts.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from ...core.config import bkt_config_from_dict, irt_config_from_dict, load_config
+from ...core.engine import EngineConfig, ModelSelector, run_scoring
+from ...core.event_schema import EventValidationError, parse_response_events
+from ..format import fail, ok
+from ..json_encode import to_jsonable
+from ..types import CommandResult
+from .record import EVENTS_STATE_FILENAME, STATE_DIR
+
+SCORES_STATE_FILENAME = "scores.json"
+
+
+@dataclass
+class ScoreOptions:
+    json: bool
+    model: ModelSelector
+
+
+def run_score(cwd: str, options: ScoreOptions) -> CommandResult:
+    events_path = Path(cwd) / STATE_DIR / EVENTS_STATE_FILENAME
+    if not events_path.exists():
+        message = f"No stored event log found at {events_path}. Run 'masterytrace record <path>' first."
+        return fail(1, options.json, {"error": message}, f"{message}\n")
+
+    try:
+        raw = json.loads(events_path.read_text(encoding="utf-8"))
+        events = parse_response_events(raw)
+    except EventValidationError as error:
+        return fail(
+            2,
+            options.json,
+            {"error": str(error), "issues": error.issues},
+            f"Validation error:\n{error}\n",
+        )
+    except Exception as error:  # noqa: BLE001 -- mirrors the TS catch-all for parse errors
+        return fail(1, options.json, {"error": str(error)}, f"Error: {error}\n")
+
+    raw_config = load_config(cwd)
+    config = EngineConfig(
+        bkt=bkt_config_from_dict(raw_config.get("bkt")),
+        irt=irt_config_from_dict(raw_config.get("irt")),
+    )
+    result = run_scoring(events, options.model, config)
+
+    scores_path = Path(cwd) / STATE_DIR / SCORES_STATE_FILENAME
+    scores_path.write_text(json.dumps(to_jsonable(result), indent=2) + "\n", encoding="utf-8")
+
+    return ok(
+        options.json,
+        {"model": options.model, "eventCount": len(events), "storedAt": str(scores_path)},
+        f"Scored {len(events)} event(s) with model(s): {options.model}\nWrote {scores_path}\n",
+    )

masterytrace/cli/format.py

@@ -0,0 +1,17 @@
+"""Builds successful/failing CommandResults, choosing JSON or human text output. Ported from src/cli/format.ts."""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .types import CommandResult
+
+
+def ok(as_json: bool, json_payload: Any, text: str) -> CommandResult:
+    return CommandResult(exit_code=0, stdout=f"{json.dumps(json_payload)}\n" if as_json else text)
+
+
+def fail(exit_code: int, as_json: bool, json_payload: Any, text: str) -> CommandResult:
+    if as_json:
+        return CommandResult(exit_code=exit_code, stdout=f"{json.dumps(json_payload)}\n")
+    return CommandResult(exit_code=exit_code, stdout="", stderr=text)

masterytrace/cli/index.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""
+Console entry point: `masterytrace <command> [options]`, installed via the
+`masterytrace` console-script defined in python/pyproject.toml. Ported
+from src/cli/index.ts (which uses `commander`); this port uses the stdlib
+`argparse` to avoid a CLI-framework dependency, matching the flags,
+defaults, subcommands, and exit-code contract of the npm CLI's `--help`
+output.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from typing import List
+
+from .. import __version__
+from .commands.init import InitOptions, run_init
+from .commands.record import RecordOptions, run_record
+from .commands.report import ReportOptions, run_report
+from .commands.score import ScoreOptions, run_score
+from .format import fail
+from .types import CommandResult
+
+_MODELS = ("bkt", "irt", "both")
+_FORMATS = ("table", "json", "markdown")
+
+
+def _emit(result: CommandResult) -> int:
+    if result.stdout:
+        sys.stdout.write(result.stdout)
+    if result.stderr:
+        sys.stderr.write(result.stderr)
+    return result.exit_code
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="masterytrace",
+        description=(
+            "Mastery Measurement API/CLI. Fits Bayesian Knowledge Tracing (BKT) and "
+            "2-parameter logistic Item Response Theory (IRT) models to learner "
+            "response logs and reports per-learner, per-skill mastery estimates."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"masterytrace-cli {__version__}")
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        default=False,
+        help="force machine-readable JSON output on stdout instead of human-formatted text",
+    )
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    init_parser = subparsers.add_parser(
+        "init",
+        help="Scaffold a sample events.json and a default masterytrace.config.json in the current directory",
+    )
+    init_parser.add_argument(
+        "--force",
+        action="store_true",
+        default=False,
+        help="overwrite events.json/masterytrace.config.json if they already exist",
+    )
+
+    record_parser = subparsers.add_parser(
+        "record",
+        help="Validate and load an event log (JSON or CSV) and store it to .masterytrace/events.json",
+    )
+    record_parser.add_argument(
+        "path",
+        help="path to a JSON (array of response events) or CSV (learner_id,skill_id,correct,timestamp) event log",
+    )
+
+    score_parser = subparsers.add_parser(
+        "score",
+        help="Fit and score the stored event log and write results to .masterytrace/scores.json",
+    )
+    score_parser.add_argument(
+        "--model", default="both", help="which model(s) to run: bkt, irt, or both"
+    )
+
+    report_parser = subparsers.add_parser(
+        "report",
+        help="Read .masterytrace/scores.json and print a per-learner, per-skill mastery table",
+    )
+    report_parser.add_argument(
+        "--format", default="table", help="output format: table, json, or markdown"
+    )
+
+    return parser
+
+
+def run_cli(argv: List[str]) -> int:
+    """
+    `argv` follows the sys.argv convention: argv[0] is the program name,
+    the real arguments start at argv[1]. Returns the process exit code
+    (0 success, 1 general/usage error, 2 validation error).
+
+    argparse's `--help`/`--version` actions call `parser.exit()` directly
+    (raising SystemExit) rather than returning normally -- that is caught
+    here and turned into a normal return, so `run_cli` always returns an
+    int and never raises, matching the TS CLI's `program.exitOverride()`
+    behavior (commander.helpDisplayed/commander.version both map to exit
+    code 0) and letting command handlers be tested as plain functions.
+
+    `--json` is a *global* flag that must work whether it appears before
+    or after the subcommand (`masterytrace --json record x` and
+    `masterytrace record x --json` both need to force JSON output, same
+    as the npm CLI's commander-based global option). Registering the same
+    `--json` action on both the main parser and every subparser does not
+    reliably compose in argparse (a subparser's own default can overwrite
+    a value already set by the main parser's parsing pass), so instead
+    `--json` is detected directly from the raw argument list and stripped
+    out before argparse ever sees it.
+    """
+    rest = list(argv[1:])
+    as_json = "--json" in rest
+    while "--json" in rest:
+        rest.remove("--json")
+
+    parser = build_parser()
+    try:
+        args = parser.parse_args(rest)
+    except SystemExit as exc:
+        code = exc.code
+        return code if isinstance(code, int) else 0
+
+    if args.command == "init":
+        return _emit(run_init(os.getcwd(), InitOptions(json=as_json, force=args.force)))
+
+    if args.command == "record":
+        return _emit(run_record(os.getcwd(), args.path, RecordOptions(json=as_json)))
+
+    if args.command == "score":
+        if args.model not in _MODELS:
+            return _emit(
+                fail(
+                    1,
+                    as_json,
+                    {"error": f"Invalid --model '{args.model}'. Expected one of: bkt, irt, both."},
+                    f"Invalid --model '{args.model}'. Expected one of: bkt, irt, both.\n",
+                )
+            )
+        return _emit(run_score(os.getcwd(), ScoreOptions(json=as_json, model=args.model)))
+
+    if args.command == "report":
+        if args.format not in _FORMATS:
+            return _emit(
+                fail(
+                    1,
+                    as_json,
+                    {"error": f"Invalid --format '{args.format}'. Expected one of: table, json, markdown."},
+                    f"Invalid --format '{args.format}'. Expected one of: table, json, markdown.\n",
+                )
+            )
+        return _emit(run_report(os.getcwd(), ReportOptions(json=as_json, format=args.format)))
+
+    parser.print_help()
+    return 0
+
+
+def main() -> None:
+    try:
+        code = run_cli(sys.argv)
+    except SystemExit:
+        raise
+    except Exception as error:  # noqa: BLE001 -- top-level crash guard, mirrors src/cli/index.ts's catch-all
+        sys.stderr.write(f"Error: {error}\n")
+        sys.exit(1)
+    else:
+        sys.exit(code)
+
+
+if __name__ == "__main__":
+    main()