ralph-log-events

Ralph Log Events

Log events with bunx @pentoai/ml-ralph@<version> log <type> '<json>' (use the exact version RALPH.md shows) from the project directory (JSON on stdin with - if it contains quotes). The command validates the event against the schema for its type, appends one line to .ml-ralph/log.jsonl and adds ts and type. Invalid events are rejected with the failing field and what was expected. Never write the file any other way; never edit, only append.

The examples below show stored lines; pass everything except ts as the JSON argument.

Event Types

Phase Transitions

{"ts":"...","type":"phase","phase":"UNDERSTAND","summary":"Exploring data and researching prior work"}
{"ts":"...","type":"phase","phase":"STRATEGIZE","summary":"Evaluating 4 potential approaches"}
{"ts":"...","type":"phase","phase":"EXECUTE","summary":"Running minimal test of H-003"}
{"ts":"...","type":"phase","phase":"REFLECT","summary":"Analyzing unexpected results"}

Thinking & Mental Models

{"ts":"...","type":"thinking","subject":"Why is precision low?","thoughts":"Looking at false positives, I notice...","conclusion":"Model confuses X with Y because..."}
{"ts":"...","type":"mental_model","domain":"feature importance","belief":"Temporal features dominate","confidence":"high","evidence":["EDA analysis","H-002 ablation"]}

Research

{"ts":"...","type":"research","source":"Kaggle 1st place solution","url":"https://...","key_insights":["Feature X crucial","Avoided Y because..."],"relevance":"directly applicable"}
{"ts":"...","type":"research","source":"arXiv paper","url":"https://...","key_insights":["This loss handles imbalance better"],"relevance":"inspirational"}

Path Analysis & Hypotheses

{"ts":"...","type":"path_analysis","paths":[{"id":"A","description":"Gradient boosting","expected":"AUC ~0.78","learning_value":"high"},{"id":"B","description":"Neural net","expected":"AUC ~0.80","learning_value":"medium"}],"chosen":"A","rationale":"Best learning-to-effort ratio"}
{"ts":"...","type":"hypothesis","id":"H-001","claim":"Time features improve AUC","expected_delta":0.05,"rubrics":["Split unchanged","No post-prediction-time features"],"kill_criterion":"AUC gain below 0.01 on every seed","rationale":"EDA showed temporal patterns"}