masterytrace-cli 0.1.0__py3-none-any.whl

masterytrace/cli/json_encode.py

@@ -0,0 +1,52 @@
+"""
+Converts the library's dataclass return values (ResponseEvent,
+MasteryReport, EngineResult, BktParams, ...) into plain JSON-serializable
+dicts for `.masterytrace/*.json` state files and `--json` CLI output.
+
+Two different conventions are used deliberately, matching each value's
+role:
+
+- `ResponseEvent` (the event-log wire format read by `parse_response_events`
+  and produced by `masterytrace init`/`record`) always serializes to
+  **camelCase** (`learnerId`, `skillId`, ...): this is the shared,
+  cross-distribution event-log contract with the npm CLI, and
+  `parse_response_events` itself only recognizes these camelCase keys, so
+  an event log this CLI writes must stay readable by this CLI (and by the
+  npm CLI) without a key-casing mismatch.
+- Everything else (scores, reports, engine results) serializes to
+  **snake_case**, matching Python naming convention -- see
+  python/README.md's "deliberate naming divergence" note. These values
+  are never fed back through `parse_response_events`, so there is no
+  cross-format contract to preserve.
+"""
+from __future__ import annotations
+
+import dataclasses
+from typing import Any, List
+
+from ..core.event_schema import ResponseEvent
+
+
+def response_event_to_dict(event: ResponseEvent) -> dict:
+    return {
+        "learnerId": event.learner_id,
+        "skillId": event.skill_id,
+        "correct": event.correct,
+        "timestamp": event.timestamp,
+    }
+
+
+def response_events_to_jsonable(events: List[ResponseEvent]) -> List[dict]:
+    return [response_event_to_dict(e) for e in events]
+
+
+def to_jsonable(value: Any) -> Any:
+    if isinstance(value, ResponseEvent):
+        return response_event_to_dict(value)
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return {k: to_jsonable(v) for k, v in dataclasses.asdict(value).items()}
+    if isinstance(value, dict):
+        return {k: to_jsonable(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [to_jsonable(v) for v in value]
+    return value

masterytrace/cli/types.py

@@ -0,0 +1,21 @@
+"""
+Every CLI command handler returns this shape instead of writing to
+stdout/exiting directly, so integration tests can invoke handlers as plain
+functions and assert on their output/exit code without spawning a
+subprocess. Ported from src/cli/types.ts.
+
+Exit code contract (required so an agent invoking this CLI programmatically
+can rely on it): 0 = success, 1 = general/usage error, 2 = validation
+error (bad event data).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class CommandResult:
+    exit_code: int
+    stdout: str
+    stderr: Optional[str] = None

masterytrace/core/config.py

@@ -0,0 +1,62 @@
+"""
+Project-level configuration read from `masterytrace.config.json` in the
+current directory (scaffolded by `masterytrace init`). Ported from
+src/core/config.ts.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from ..models.bkt import BktConfig
+from ..models.irt import IrtConfig
+
+CONFIG_FILENAME = "masterytrace.config.json"
+
+
+@dataclass
+class MasteryTraceConfig:
+    bkt: Optional[Dict[str, Any]] = None
+    irt: Optional[Dict[str, Any]] = None
+
+
+DEFAULT_CONFIG: Dict[str, Any] = {"bkt": {"fit": False}, "irt": {}}
+
+
+def load_config(cwd: str) -> Dict[str, Any]:
+    """
+    Loads `masterytrace.config.json` from `cwd` if present, merging it
+    over DEFAULT_CONFIG; otherwise returns DEFAULT_CONFIG unchanged.
+    """
+    config_path = Path(cwd) / CONFIG_FILENAME
+    if not config_path.exists():
+        return dict(DEFAULT_CONFIG)
+    raw = json.loads(config_path.read_text(encoding="utf-8"))
+    merged = dict(DEFAULT_CONFIG)
+    merged.update(raw)
+    return merged
+
+
+def bkt_config_from_dict(raw: Optional[Dict[str, Any]]) -> BktConfig:
+    """Builds a BktConfig from the plain dict shape stored in masterytrace.config.json."""
+    raw = raw or {}
+    return BktConfig(
+        default_params=raw.get("defaultParams"),
+        skill_params=raw.get("skillParams"),
+        fit=bool(raw.get("fit", False)),
+    )
+
+
+def irt_config_from_dict(raw: Optional[Dict[str, Any]]) -> IrtConfig:
+    """Builds an IrtConfig from the plain dict shape stored in masterytrace.config.json."""
+    raw = raw or {}
+    kwargs: Dict[str, Any] = {}
+    if "iterations" in raw:
+        kwargs["iterations"] = raw["iterations"]
+    if "learningRate" in raw:
+        kwargs["learning_rate"] = raw["learningRate"]
+    if "regularization" in raw:
+        kwargs["regularization"] = raw["regularization"]
+    return IrtConfig(**kwargs)

masterytrace/core/engine.py

@@ -0,0 +1,54 @@
+"""
+Orchestrates the scoring pipeline: given a validated event log, runs
+whichever model(s) were requested and returns their reports together.
+Ported from src/core/engine.ts.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import List, Literal, Optional
+
+from ..models.bkt import BktConfig, BktModel
+from ..models.irt import IrtConfig, IrtModel
+from .event_schema import ResponseEvent
+from .scoring_model import MasteryReport
+
+ModelSelector = Literal["bkt", "irt", "both"]
+
+
+@dataclass
+class EngineConfig:
+    bkt: Optional[BktConfig] = None
+    irt: Optional[IrtConfig] = None
+
+
+@dataclass
+class EngineResult:
+    generated_at: str
+    reports: List[MasteryReport] = field(default_factory=list)
+
+
+def run_scoring(
+    events: List[ResponseEvent],
+    selector: ModelSelector = "both",
+    config: Optional[EngineConfig] = None,
+) -> EngineResult:
+    """
+    Runs whichever model(s) were requested and returns their reports
+    together. This is the single place that knows how to wire the engine
+    config into concrete model instances; callers (CLI or library
+    consumers) only pick a model selector and pass raw events.
+    """
+    config = config or EngineConfig()
+    reports: List[MasteryReport] = []
+
+    if selector in ("bkt", "both"):
+        model = BktModel(config.bkt)
+        reports.append(model.score(model.fit(events)))
+
+    if selector in ("irt", "both"):
+        model = IrtModel(config.irt)
+        reports.append(model.score(model.fit(events)))
+
+    return EngineResult(generated_at=datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"), reports=reports)

masterytrace/core/event_schema.py

@@ -0,0 +1,131 @@
+"""
+A single learner response event: one attempt by one learner at one skill,
+scored correct/incorrect, at a point in time.
+
+This is the only unit of data every scoring model and adapter in
+MasteryTrace operates on. Ported from src/core/event-schema.ts, which uses
+`zod` for validation; this port hand-rolls the equivalent field checks
+(learnerId/skillId non-empty strings, correct a bool, timestamp a parseable
+ISO 8601 string) to avoid a validation-library dependency the TypeScript
+side has but the Python side does not need for four fields.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, List
+
+
+@dataclass(frozen=True)
+class ResponseEvent:
+    learner_id: str
+    skill_id: str
+    correct: bool
+    timestamp: str
+
+
+class EventValidationError(Exception):
+    """
+    Raised when an event log fails validation. `issues` lists every
+    field/row failure found, so a caller (or the CLI) can report all
+    problems at once instead of stopping at the first one -- matching the
+    TypeScript EventValidationError contract exactly (same field name,
+    same "row N: field 'x' - message" issue format).
+    """
+
+    def __init__(self, message: str, issues: List[str]) -> None:
+        super().__init__(message)
+        self.issues = issues
+
+
+def _is_valid_iso8601(value: str) -> bool:
+    """
+    Mirrors `!Number.isNaN(Date.parse(value))` closely enough for the
+    timestamps this project actually produces and accepts (ISO 8601,
+    optionally with a trailing 'Z'). datetime.fromisoformat() is stricter
+    than JS's Date.parse() about some non-standard formats, but every
+    timestamp MasteryTrace itself generates (sample data, CLI-recorded
+    logs) is a real ISO 8601 string, so this does not reject valid
+    MasteryTrace data.
+    """
+    if not isinstance(value, str) or value == "":
+        return False
+    candidate = value[:-1] + "+00:00" if value.endswith("Z") else value
+    try:
+        datetime.fromisoformat(candidate)
+        return True
+    except ValueError:
+        return False
+
+
+def _validate_row(row: Any, index: int, issues: List[str]) -> ResponseEvent | None:
+    if not isinstance(row, dict):
+        issues.append(f"row {index}: field '(row)' - expected an object")
+        return None
+
+    ok = True
+
+    learner_id = row.get("learnerId")
+    if not isinstance(learner_id, str):
+        issues.append(f"row {index}: field 'learnerId' - learnerId must be a string")
+        ok = False
+    elif len(learner_id) < 1:
+        issues.append(f"row {index}: field 'learnerId' - learnerId must be a non-empty string")
+        ok = False
+
+    skill_id = row.get("skillId")
+    if not isinstance(skill_id, str):
+        issues.append(f"row {index}: field 'skillId' - skillId must be a string")
+        ok = False
+    elif len(skill_id) < 1:
+        issues.append(f"row {index}: field 'skillId' - skillId must be a non-empty string")
+        ok = False
+
+    correct = row.get("correct")
+    if not isinstance(correct, bool):
+        issues.append(f"row {index}: field 'correct' - correct must be a boolean")
+        ok = False
+
+    timestamp = row.get("timestamp")
+    if not isinstance(timestamp, str):
+        issues.append(f"row {index}: field 'timestamp' - timestamp must be an ISO 8601 date string")
+        ok = False
+    elif not _is_valid_iso8601(timestamp):
+        issues.append(f"row {index}: field 'timestamp' - timestamp must be a valid ISO 8601 date string")
+        ok = False
+
+    if not ok:
+        return None
+    return ResponseEvent(learner_id=learner_id, skill_id=skill_id, correct=correct, timestamp=timestamp)
+
+
+def parse_response_events(raw: Any) -> List[ResponseEvent]:
+    """
+    Parses an unknown value (typically json.load output or rows decoded
+    from CSV) into a validated list of ResponseEvent. Every row is
+    checked; on failure the error lists every failing row/field, not just
+    the first.
+    """
+    if not isinstance(raw, list):
+        raise EventValidationError(
+            "Event log must be a JSON array of response events (row 0: expected array, got "
+            f"{type(raw).__name__})",
+            ["row 0: expected an array of response events"],
+        )
+
+    events: List[ResponseEvent] = []
+    issues: List[str] = []
+
+    for index, row in enumerate(raw):
+        event = _validate_row(row, index, issues)
+        if event is not None:
+            events.append(event)
+
+    if issues:
+        plural = "" if len(issues) == 1 else "s"
+        raise EventValidationError(
+            f"Event log failed validation ({len(issues)} issue{plural}):\n" + "\n".join(issues),
+            issues,
+        )
+
+    return events

masterytrace/core/scoring_model.py

@@ -0,0 +1,68 @@
+"""
+The unified report/model shapes both BKT and IRT produce, letting the
+engine and CLI treat either psychometric model interchangeably. Ported
+from src/core/scoring-model.ts.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Protocol, TypeVar
+
+
+@dataclass
+class MasterySkillEntry:
+    """
+    A single per-skill mastery estimate for one learner, as produced by a
+    scoring model. `metric` names what `value` means so a report consumer
+    (or the CLI's table renderer) can label it correctly without knowing
+    which model produced it: 'posterior_mastery_probability' (BKT) or
+    'ability_theta' (IRT).
+    """
+
+    skill_id: str
+    metric: str
+    value: float
+    response_count: int
+    details: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class MasteryLearnerEntry:
+    learner_id: str
+    skills: List[MasterySkillEntry] = field(default_factory=list)
+
+
+@dataclass
+class MasteryReport:
+    """
+    The unified shape every ScoringModel.score() returns, regardless of
+    which psychometric model produced it.
+    """
+
+    model: str
+    generated_at: str
+    learners: List[MasteryLearnerEntry] = field(default_factory=list)
+    meta: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class FittedModel:
+    """Opaque fitted-model artifact produced by ScoringModel.fit()."""
+
+    model_name: str
+
+
+F = TypeVar("F", bound=FittedModel)
+
+
+class ScoringModel(Protocol[F]):
+    """
+    Common interface both BKT and IRT implement, so an engine or CLI can
+    fit and score either model (or both) through the same code path.
+    """
+
+    name: str
+
+    def fit(self, events: List[Any]) -> F: ...
+
+    def score(self, fitted_model: F) -> MasteryReport: ...

masterytrace/data/sample_events.py

@@ -0,0 +1,78 @@
+"""
+Bundled example event log for `masterytrace init`: 3 learners x 3 skills,
+6-7 responses each, with a deterministic (seeded) but plausible "improving
+over time" pattern per learner. Ported from src/data/sample-events.ts,
+including its linear congruential generator, so the bundled sample data
+follows the same generation algorithm as the npm package's (the two are
+not required to be byte-identical, only algorithmically equivalent, since
+each runtime's `Date`/timestamp formatting differs slightly).
+"""
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Callable, Dict, List
+
+from ..core.event_schema import ResponseEvent
+
+_UINT32_MASK = 0xFFFFFFFF
+
+
+def _make_lcg(seed: int) -> Callable[[], float]:
+    """
+    A small deterministic linear congruential generator, used only to keep
+    the bundled sample data reproducible (no random.random()) while still
+    looking like a real, slightly noisy response log rather than a
+    hand-typed pattern.
+    """
+    state = seed & _UINT32_MASK
+
+    def _next() -> float:
+        nonlocal state
+        state = (state * 1664525 + 1013904223) & _UINT32_MASK
+        return state / _UINT32_MASK
+
+    return _next
+
+
+_LEARNERS = ["learner-ada", "learner-brook", "learner-cyrus"]
+_SKILLS = ["fractions", "linear-equations", "reading-comprehension"]
+
+# Roughly how likely each learner is to answer correctly on their Nth
+# attempt at a skill (index 0 = first attempt), used only to shape the
+# bundled sample into a plausible "learning over time" curve.
+_LEARNING_CURVES: Dict[str, List[float]] = {
+    "learner-ada": [0.3, 0.4, 0.55, 0.7, 0.8, 0.85, 0.9],
+    "learner-brook": [0.2, 0.25, 0.3, 0.45, 0.55, 0.65, 0.75],
+    "learner-cyrus": [0.5, 0.65, 0.75, 0.85, 0.9, 0.92, 0.95],
+}
+_DEFAULT_CURVE = [0.4, 0.5, 0.6, 0.7, 0.8, 0.85, 0.9]
+
+
+def _build_sample_events() -> List[ResponseEvent]:
+    rand = _make_lcg(42)
+    events: List[ResponseEvent] = []
+    start_date = datetime(2026, 1, 5, 9, 0, 0, tzinfo=timezone.utc)
+    day_offset = 0
+
+    for skill_id in _SKILLS:
+        for learner_id in _LEARNERS:
+            curve = _LEARNING_CURVES.get(learner_id, _DEFAULT_CURVE)
+            attempts = 6 + int(rand() * 2)  # 6 or 7 attempts per learner+skill
+            for attempt in range(attempts):
+                p_correct = curve[min(attempt, len(curve) - 1)]
+                correct = rand() < p_correct
+                timestamp = start_date + timedelta(days=day_offset, hours=attempt)
+                events.append(
+                    ResponseEvent(
+                        learner_id=learner_id,
+                        skill_id=skill_id,
+                        correct=correct,
+                        timestamp=timestamp.isoformat().replace("+00:00", "Z"),
+                    )
+                )
+            day_offset += 1
+
+    return events
+
+
+SAMPLE_EVENTS: List[ResponseEvent] = _build_sample_events()