mtrick 0.1.0__py3-none-any.whl

mtrick/__init__.py

@@ -0,0 +1,6 @@
+from .tracker import MTracker
+
+# For ease of import or standard naming
+Tracker = MTracker
+
+__all__ = ["MTracker", "Tracker"]

mtrick/dashboard.py

@@ -0,0 +1,139 @@
+import socket
+import http.server
+import socketserver
+import json
+import os
+import urllib.parse
+import argparse
+from typing import Any
+
+
+def local_network_ip() -> None:
+    # Create a dummy socket to find the interface used for external routing
+    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        # We use a public IP address (Google's DNS) and port.
+        # No actual connection or packet is sent over the network.
+        s.connect(("8.8.8.8", 80))
+        local_ip = s.getsockname()[0]
+    except Exception:
+        # Fallback to loopback if no active network connection exists
+        local_ip = "127.0.0.1"
+    finally:
+        s.close()
+        print(f"Local Network IP Address: {local_ip}")
+
+        
+class DashboardServer(socketserver.TCPServer):
+    allow_reuse_address = True
+
+    def __init__(
+        self, server_address, handler_class, tracker_dir="metrics"
+    ):
+        self.tracker_dir = tracker_dir
+
+        super().__init__(server_address, handler_class)
+
+
+class DashboardHandler(http.server.SimpleHTTPRequestHandler):
+    def do_GET(self):
+        parsed_path = urllib.parse.urlparse(self.path)
+        assert isinstance(self.server, DashboardServer)
+        tracker_dir = self.server.tracker_dir
+
+        # API Endpoint to get all runs
+        if parsed_path.path == "/api/runs":
+            self.send_response(200)
+            self.send_header("Content-type", "application/json; charset=utf-8")
+            # Add CORS headers just in case
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.end_headers()
+
+            runs = []
+            if os.path.exists(tracker_dir):
+                for dir_name in sorted(os.listdir(tracker_dir), reverse=True):
+                    dir_path = os.path.join(tracker_dir, dir_name)
+                    if os.path.isdir(dir_path):
+                        meta_path = os.path.join(dir_path, "meta.json")
+                        meta: dict[str, Any] = {}
+                        if os.path.exists(meta_path):
+                            with open(meta_path, "r") as f:
+                                meta = json.load(f)
+                        else:
+                            meta = {"experiment_name": dir_name, "timestamp": "Unknown"}
+                        meta["folder"] = dir_name
+                        try:
+                            meta["files"] = os.listdir(dir_path)
+                        except Exception:
+                            meta["files"] = []
+                        runs.append(meta)
+
+            # print(runs)
+            self.wfile.write(json.dumps(runs).encode("utf-8"))
+            return
+
+
+        # Serve the dashboard index for root path
+        elif parsed_path.path == "/":
+            self.send_response(200)
+            self.send_header("Content-type", "text/html; charset=utf-8")
+            self.send_header("Cache-Control", "no-store, no-cache, must-revalidate")
+            self.end_headers()
+
+            static_dir = os.path.join(os.path.dirname(__file__), "static")
+            index_path = os.path.join(static_dir, "index.html")
+
+            with open(index_path, "rb") as f:
+                self.wfile.write(f.read())
+            return
+
+        # Serve run data files (CSV / JSON) from tracker directory
+        else:
+            # only serve files that resolve inside TRACKER_DIR
+            requested = urllib.parse.unquote(parsed_path.path).lstrip("/")
+            tracker_root = os.path.realpath(tracker_dir)
+            local_path = os.path.realpath(os.path.join(tracker_dir, requested))
+            if not local_path.startswith(tracker_root + os.sep) or not os.path.isfile(
+                local_path
+            ):
+                self.send_error(404, "Not Found")
+                return
+            self.send_response(200)
+            if local_path.endswith(".json") or local_path.endswith(".jsonl"):
+                content_type = "application/json; charset=utf-8"
+            else:
+                content_type = "text/plain; charset=utf-8"
+            self.send_header("Content-type", content_type)
+            self.end_headers()
+            with open(local_path, "rb") as f:
+                self.wfile.write(f.read())
+
+
+def main():
+    local_network_ip()
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--port", type=int, default=8000, help="Port to run on")
+    parser.add_argument(
+        "--tracker-dir",
+        type=str,
+        default="metrics",
+        help="Local directory to scan for runs",
+    )
+    args = parser.parse_args()
+
+    port = args.port
+    tracker_dir = args.tracker_dir
+
+    with DashboardServer(
+        ("", port), DashboardHandler, tracker_dir=tracker_dir
+    ) as httpd:
+        print(f"🚀 Dashboard is live! Ctrl / Cmd Click >>> http://localhost:{port} <<<")
+        try:
+            httpd.serve_forever()
+        except KeyboardInterrupt:
+            print("\nShutting down dashboard...")
+
+
+if __name__ == "__main__":
+    main()

mtrick/static/index.html

@@ -0,0 +1,832 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>MTRICK</title>
+    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/chartjs-chart-matrix@latest/dist/chartjs-chart-matrix.min.js"></script>
+    <style>
+        body {
+            margin: 0;
+            padding: 0;
+            font-family: monospace;
+            background-color: #111;
+            color: #eee;
+            height: 100vh;
+            display: flex;
+        }
+
+        .sidebar {
+            width: 300px;
+            background: #222;
+            border-right: 1px solid #444;
+            display: flex;
+            flex-direction: column;
+            padding: 20px;
+            overflow-y: auto;
+        }
+
+        .run-item {
+            border: 1px solid #444;
+            padding: 10px;
+            margin-bottom: 10px;
+            transition: background 0.2s;
+        }
+
+        .run-item:hover {
+            background: #333;
+        }
+
+        .run-item.active {
+            background: #444;
+            border-color: #888;
+        }
+
+        .main-content {
+            flex: 1;
+            padding: 20px;
+            overflow-y: auto;
+            display: flex;
+            flex-direction: column;
+        }
+
+        .chart-box {
+            background: #222;
+            border: 1px solid #444;
+            padding: 20px;
+            display: flex;
+            flex-direction: column;
+            min-width: 0;
+        }
+
+        #dynamic-charts-container {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(450px, 1fr));
+            gap: 20px;
+        }
+
+        .header-row {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            margin-bottom: 20px;
+        }
+
+        #run-title-display {
+            margin: 0;
+        }
+
+        .chart-controls {
+            display: flex;
+            gap: 20px;
+            margin-bottom: 15px;
+            padding-bottom: 15px;
+            border-bottom: 1px solid #444;
+            align-items: center;
+            flex-wrap: wrap;
+            font-size: 0.9em;
+        }
+
+        .chart-wrapper {
+            width: 100%;
+            display: flex;
+            justify-content: center;
+        }
+
+        .chart-container {
+            position: relative;
+            width: 100%;
+            height: 400px;
+        }
+
+        .chart-container.square-mode {
+            width: 100% !important;
+            height: auto !important;
+            aspect-ratio: 1 / 1;
+            max-width: 500px;
+            max-height: 500px;
+        }
+
+        pre code {
+            display: block;
+            background: #000;
+            padding: 15px;
+            overflow-x: auto;
+            color: #a5d6ff;
+            font-family: 'Courier New', Courier, monospace;
+        }
+
+        button,
+        select,
+        input,
+        #run-warnings-container {
+            border-radius: 0 !important;
+        }
+    </style>
+</head>
+
+<body>
+    <div class="sidebar" id="sidebar">
+        <h3 style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 10px;">
+            Experiment Runs
+        </h3>
+        <button id="clear-all-btn"
+            style="margin-bottom: 15px; padding: 6px; background: #333; color: #eee; border: 1px solid #555; cursor: pointer;">Clear
+            All</button>
+        <div id="runs-list"></div>
+    </div>
+
+    <div class="main-content">
+        <div class="header-row">
+            <h2 id="run-title-display">Select runs to compare</h2>
+            <div style="display: flex; gap: 15px; align-items: center;">
+                <div class="layout-control-container">
+                    <label for="non-line-select">Non-Line Charts:</label>
+                    <select id="non-line-select"
+                        style="padding: 5px; background: #333; color: #eee; border: 1px solid #555;">
+                        <option value="latest">Show Latest</option>
+                        <option value="all">Show All</option>
+                        <option value="none">Show None</option>
+                    </select>
+                </div>
+                <div class="layout-control-container">
+                    <label for="layout-select">Layout:</label>
+                    <select id="layout-select"
+                        style="padding: 5px; background: #333; color: #eee; border: 1px solid #555;">
+                        <option value="auto">Auto (Smart)</option>
+                        <option value="1">1 Column</option>
+                        <option value="2">2 Columns</option>
+                        <option value="3">3 Columns</option>
+                    </select>
+                </div>
+            </div>
+        </div>
+        <div id="run-warnings-container"
+            style="display: none; background: rgba(245, 158, 11, 0.1); border: 1px solid #f59e0b; color: #f59e0b; padding: 15px; margin-bottom: 20px;">
+        </div>
+        <div id="dynamic-charts-container"></div>
+
+    </div>
+
+    <script>
+        const RUN_COLORS = [
+            '#3b82f6', '#22c55e', '#ef4444', '#a855f7', '#f59e0b',
+            '#ec4899', '#06b6d4', '#10b981', '#f97316', '#6366f1'
+        ];
+        const DASH_PATTERNS = [[], [5, 5], [2, 2], [8, 4], [12, 6]];
+        let allRuns = [];
+        let selectedRuns = [];
+        let chartInstances = {};
+        let chartConfigs = {};
+
+        function isOverlayable(type) {
+            return ['line', 'line_multi', 'scatter'].includes(type);
+        }
+
+        function parseCSV(text) {
+            const lines = text.trim().split('\n');
+            if (lines.length === 0 || lines[0] === '') return null;
+            const headers = lines[0].split(',').map(h => h.trim());
+            const rows = [];
+            for (let i = 1; i < lines.length; i++) {
+                const cols = lines[i].split(',');
+                if (cols.length > 1) rows.push(cols);
+            }
+            return { headers, rows };
+        }
+
+        function computeEqualAspectRange(datasets, options) {
+            const allVals = [];
+            datasets.forEach(ds => ds.data.forEach(d => { allVals.push(d.x); allVals.push(d.y); }));
+            const valid = allVals.filter(v => !isNaN(v));
+            if (valid.length === 0) return;
+            const globalMin = Math.min(...valid);
+            const globalMax = Math.max(...valid);
+            const padding = (globalMax - globalMin) * 0.1 || 1;
+            options.scales.x.min = globalMin - padding;
+            options.scales.x.max = globalMax + padding;
+            options.scales.y.min = globalMin - padding;
+            options.scales.y.max = globalMax + padding;
+        }
+
+        function esc(s) {
+            if (s == null) return '';
+            return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+        }
+
+        function calculateEMA(data, weight) {
+            if (weight <= 0) return data;
+            if (data.length === 0) return [];
+            let smoothed = [];
+            let current = null;
+            for (let i = 0; i < data.length; i++) {
+                if (data[i] === null || isNaN(data[i])) {
+                    smoothed.push(data[i]);
+                } else {
+                    if (current === null) current = data[i];
+                    else current = current * weight + data[i] * (1 - weight);
+                    smoothed.push(current);
+                }
+            }
+            return smoothed;
+        }
+
+        async function fetchRuns() {
+            try {
+                const response = await fetch('/api/runs');
+                const runs = await response.json();
+                allRuns = runs;
+                const list = document.getElementById('runs-list');
+                list.innerHTML = '';
+                runs.forEach((run, index) => {
+                    const div = document.createElement('div');
+                    div.className = 'run-item';
+                    const scriptText = run.source_script ? `<br><small style="color: #a855f7;">Script: ${esc(run.source_script)}</small>` : '';
+                    div.innerHTML = `
+                        <label style="display: flex; align-items: flex-start; gap: 10px; cursor: pointer; width: 100%; margin: 0;">
+                            <input type="checkbox" class="run-checkbox" value="${index}" style="margin-top: 4px;">
+                            <div style="flex: 1;">
+                                <b>${esc(run.experiment_name) || 'Experiment'} #${esc(run.experiment_number) || '?'}</b><br><small>${esc(run.timestamp)}</small><br><small>Commit: ${esc(run.git_commit)}</small>${scriptText}
+                            </div>
+                        </label>
+                    `;
+                    const checkbox = div.querySelector('input');
+                    checkbox.addEventListener('change', () => {
+                        if (checkbox.checked) {
+                            div.classList.add('active');
+                            if (!selectedRuns.includes(run)) selectedRuns.push(run);
+                        } else {
+                            div.classList.remove('active');
+                            selectedRuns = selectedRuns.filter(r => r !== run);
+                        }
+                        selectedRuns.sort((a, b) => allRuns.indexOf(a) - allRuns.indexOf(b));
+                        loadMultipleRunsData();
+                    });
+                    list.appendChild(div);
+                });
+                if (runs.length > 0) {
+                    const firstCb = list.querySelector('input');
+                    firstCb.checked = true;
+                    firstCb.dispatchEvent(new Event('change'));
+                }
+            } catch (err) {
+                console.error("Failed to fetch runs:", err);
+            }
+        }
+
+        document.getElementById('clear-all-btn').addEventListener('click', () => {
+            document.querySelectorAll('.run-checkbox').forEach(cb => {
+                if (cb.checked) {
+                    cb.checked = false;
+                    cb.dispatchEvent(new Event('change'));
+                }
+            });
+        });
+
+        document.getElementById('non-line-select').addEventListener('change', () => {
+            loadMultipleRunsData();
+        });
+
+        function createChartDOM(id, title, type, layout) {
+            layout = layout || {};
+            let controlsHtml = '';
+
+            if (type === 'line' || type === 'line_multi') {
+                controlsHtml += `<label style="cursor: pointer;"><input type="checkbox" id="log_${id}" onchange="updateChart('${id}')"> Log Y Scale</label>`;
+                controlsHtml += `<label style="display: flex; align-items: center; gap: 5px;">Smoothing: <input type="range" id="smooth_${id}" min="0" max="0.99" step="0.01" value="0.0" oninput="updateChart('${id}')"></label>`;
+            }
+            if (layout.equal_aspect) {
+                controlsHtml += `<label style="cursor: pointer;"><input type="checkbox" id="equal_${id}" onchange="updateChart('${id}')" checked> Equal X/Y Scale</label>`;
+            }
+
+            return `
+                <div class="chart-box" id="box_${id}">
+                    <div class="chart-controls">
+                        <b style="color: #3b82f6;">${title}</b>
+                        ${controlsHtml}
+                    </div>
+                    <div class="chart-wrapper">
+                        <div class="chart-container ${layout.equal_aspect ? 'square-mode' : ''}" id="container_${id}">
+                            <canvas id="canvas_${id}"></canvas>
+                        </div>
+                    </div>
+                </div>
+            `;
+        }
+
+        let currentLoadId = 0;
+
+        async function loadMultipleRunsData() {
+            const loadId = ++currentLoadId;
+            const container = document.getElementById('dynamic-charts-container');
+            const warningsContainer = document.getElementById('run-warnings-container');
+
+            if (selectedRuns.length === 0) {
+                document.getElementById('run-title-display').textContent = 'No runs selected';
+                container.innerHTML = '';
+                if (warningsContainer) warningsContainer.style.display = 'none';
+                return;
+            }
+
+            let titleText = `Comparing ${selectedRuns.length} run(s)`;
+            if (selectedRuns.length === 1) {
+                titleText = `${selectedRuns[0].experiment_name || 'Experiment'} (Experiment #${selectedRuns[0].experiment_number || '?'})`;
+                if (selectedRuns[0].source_script) titleText += ` — Script: ${selectedRuns[0].source_script}`;
+            }
+            document.getElementById('run-title-display').textContent = titleText;
+
+            container.innerHTML = '';
+            if (warningsContainer) {
+                warningsContainer.style.display = 'none';
+                warningsContainer.innerHTML = '';
+            }
+            Object.values(chartInstances).forEach(c => c.destroy());
+            chartInstances = {};
+            chartConfigs = {};
+
+            try {
+                const nonLineMode = document.getElementById('non-line-select').value;
+
+                const runPromises = selectedRuns.map(async (run) => {
+                    const runIdx = allRuns.indexOf(run);
+                    const runCharts = {};
+                    const filesToFetch = new Set();
+
+                    // Fetch metrics.jsonl if present in run files
+                    if (!run.files || run.files.includes('metrics.jsonl')) {
+                        filesToFetch.add('metrics.jsonl');
+                    }
+
+                    // Scan run files for any confusion matrix files
+                    if (run.files) {
+                        run.files.forEach(filename => {
+                            if (filename.endsWith('confusion.jsonl')) {
+                                filesToFetch.add(filename);
+                            }
+                        });
+                    }
+
+                    // Retain support for any explicitly registered charts in meta.json
+                    if (run.charts && run.charts.length > 0) {
+                        run.charts.forEach(chart => {
+                            if (chart.filename) {
+                                filesToFetch.add(chart.filename);
+                            }
+                        });
+                    }
+
+                    for (const filename of filesToFetch) {
+                        const response = await fetch(`/${run.folder}/${filename}`);
+                        if (!response.ok) continue;
+                        const text = await response.text();
+                        const rows = text.trim().split('\n');
+                        if (rows.length === 0 || rows[0] === "") continue;
+
+                        if (filename.endsWith('confusion.jsonl')) {
+                            const id = `confusion_${filename.replace(/[^a-zA-Z0-9]/g, '_')}`;
+                            runCharts[id] = {
+                                type: 'heatmap',
+                                title: filename === 'confusion.jsonl' ? 'Confusion Matrix' : `Confusion Matrix (${filename})`,
+                                layout: {},
+                                series: [],
+                                raw_csv: text
+                            };
+                            continue;
+                        }
+
+                        if (filename.endsWith('.jsonl')) {
+                            // Parse JSONL file
+                            const jsonObjects = rows.map(line => {
+                                try { return JSON.parse(line); } catch(e) { return null; }
+                            }).filter(obj => obj !== null);
+
+                            if (jsonObjects.length === 0) continue;
+
+                            // Collect all unique keys (excluding epoch and step)
+                            const allKeys = new Set();
+                            jsonObjects.forEach(obj => {
+                                Object.keys(obj).forEach(k => {
+                                    if (k !== 'epoch' && k !== 'step') allKeys.add(k);
+                                });
+                            });
+
+                            const epochs = [];
+                            const metricData = {};
+                            allKeys.forEach(k => {
+                                metricData[k] = { values: [] };
+                            });
+
+                            jsonObjects.forEach((obj, i) => {
+                                const epochVal = obj.epoch !== undefined ? obj.epoch : (obj.step !== undefined ? obj.step : i);
+                                epochs.push(epochVal);
+                                allKeys.forEach(k => {
+                                    metricData[k].values.push(obj[k] !== undefined ? obj[k] : null);
+                                });
+                            });
+
+                            // Track columns claimed by manually defined custom charts
+                            const claimedColumns = new Set();
+                            const fileCharts = (run.charts || []).filter(c => c.filename === filename);
+                            fileCharts.forEach(chart => {
+                                if (chart.series) chart.series.forEach(s => claimedColumns.add(s.y));
+                            });
+
+                            // Prefix Auto-Grouping: group keys by their first namespace parts (divided by '/' or '.')
+                            const groups = {};
+                            const singleMetrics = [];
+
+                            Object.keys(metricData).forEach(metricName => {
+                                if (claimedColumns.has(metricName)) return;
+
+                                const parts = metricName.split(/[\/\.]/);
+                                if (parts.length > 1) {
+                                    const prefix = parts[0];
+                                    const suffix = parts.slice(1).join('/');
+                                    if (!groups[prefix]) groups[prefix] = [];
+                                    groups[prefix].push({ y: metricName, name: suffix });
+                                } else {
+                                    singleMetrics.push(metricName);
+                                }
+                            });
+
+                            // 1. Create multi-series line charts for auto-grouped keys
+                            Object.keys(groups).forEach(prefix => {
+                                const id = `auto_group_${filename.replace(/[^a-zA-Z0-9]/g, '_')}_${prefix.replace(/[^a-zA-Z0-9]/g, '_')}`;
+                                const dsData = {};
+                                const series = groups[prefix];
+                                series.forEach(s => {
+                                    dsData[s.y] = metricData[s.y].values;
+                                });
+
+                                runCharts[id] = {
+                                    type: 'line_multi',
+                                    title: `${prefix} (${filename})`,
+                                    layout: {},
+                                    series: series,
+                                    epochs,
+                                    datasetsData: dsData
+                                };
+                            });
+
+                            // 2. Create single line charts for ungrouped keys
+                            singleMetrics.forEach(metricName => {
+                                const id = `metric_${filename.replace(/[^a-zA-Z0-9]/g, '_')}_${metricName.replace(/[^a-zA-Z0-9]/g, '_')}`;
+                                runCharts[id] = {
+                                    type: 'line',
+                                    title: `${metricName} (${filename})`,
+                                    epochs,
+                                    values: metricData[metricName].values,
+                                    layout: {}
+                                };
+                            });
+
+                            // 3. Keep custom manually defined charts (e.g. from meta.json)
+                            fileCharts.forEach(chart => {
+                                if (chart.series && chart.series.length > 0) {
+                                    const id = `custom_${chart.title.replace(/[^a-zA-Z0-9]/g, '_')}`;
+                                    const dsData = {};
+                                    chart.series.forEach(s => {
+                                        if (metricData[s.y]) dsData[s.y] = metricData[s.y].values;
+                                    });
+                                    runCharts[id] = { type: 'line_multi', title: chart.title, layout: chart.layout || {}, series: chart.series, epochs, datasetsData: dsData };
+                                }
+                            });
+                        }
+                    }
+
+                    return { run, runIdx, runCharts };
+                });
+
+                const results = await Promise.all(runPromises);
+                if (loadId !== currentLoadId) return;
+
+                results.forEach(res => {
+                    const { run, runIdx, runCharts } = res;
+                    const runName = run.experiment_name || `Experiment #${run.experiment_number || runIdx}`;
+
+                    Object.keys(runCharts).forEach(id => {
+                        const chartData = runCharts[id];
+                        let targetId = id;
+
+                        if (!isOverlayable(chartData.type)) {
+                            if (nonLineMode === 'none') return;
+                            if (nonLineMode === 'all') {
+                                targetId = `${id}_run${runIdx}`;
+                            }
+                        }
+
+                        if (!chartConfigs[targetId]) {
+                            chartConfigs[targetId] = {
+                                type: chartData.type,
+                                title: (nonLineMode === 'all' && !isOverlayable(chartData.type) && selectedRuns.length > 1) ? `${chartData.title} (${runName})` : chartData.title,
+                                layout: chartData.layout,
+                                series: chartData.series,
+                                dataByRun: []
+                            };
+                            container.insertAdjacentHTML('beforeend', createChartDOM(targetId, chartConfigs[targetId].title, chartData.type, chartData.layout));
+                        }
+
+                        if (nonLineMode === 'latest' && !isOverlayable(chartData.type)) {
+                            if (chartConfigs[targetId].dataByRun.length === 0 || runIdx < chartConfigs[targetId].dataByRun[0].runIdx) {
+                                chartConfigs[targetId].dataByRun = [{ runName, runIdx, ...chartData }];
+                            }
+                        } else {
+                            chartConfigs[targetId].dataByRun.push({ runName, runIdx, ...chartData });
+                        }
+                    });
+                });
+
+                if (loadId !== currentLoadId) return;
+
+                Object.keys(chartConfigs).forEach(id => updateChart(id));
+
+            } catch (err) {
+                console.error("Error loading multiple runs data:", err);
+            }
+        }
+
+
+        fetchRuns();
+
+        function updateChart(id) {
+            const config = chartConfigs[id];
+            if (!config) return;
+
+            const ctx = document.getElementById(`canvas_${id}`).getContext('2d');
+            if (chartInstances[id]) chartInstances[id].destroy();
+
+            const logEl = document.getElementById(`log_${id}`);
+            const isLog = logEl ? logEl.checked : false;
+
+            const smoothEl = document.getElementById(`smooth_${id}`);
+            const smoothWeight = smoothEl ? parseFloat(smoothEl.value) : 0;
+
+            const equalEl = document.getElementById(`equal_${id}`);
+            const isEqual = equalEl ? equalEl.checked : (config.layout && config.layout.equal_aspect || false);
+
+            if (isEqual) {
+                document.getElementById(`container_${id}`).classList.add('square-mode');
+            } else {
+                document.getElementById(`container_${id}`).classList.remove('square-mode');
+            }
+
+            if (config.type === 'line' || config.type === 'line_multi' || config.type === 'scatter') {
+                const datasets = [];
+
+                config.dataByRun.forEach(runData => {
+                    const runName = runData.runName;
+                    const c = RUN_COLORS[runData.runIdx % RUN_COLORS.length];
+                    const c_raw = c + '40';
+
+                    if (config.type === 'line' || config.type === 'line_multi') {
+                        // Normalize 'line' into a single-series 'line_multi' shape
+                        const seriesList = config.type === 'line'
+                            ? [{ name: config.dataByRun.length > 1 ? runName : 'Value', y: '__value__' }]
+                            : config.series;
+                        const getData = (col) => col === '__value__' ? runData.values : (runData.datasetsData && runData.datasetsData[col]);
+
+                        let seriesIdx = 0;
+                        seriesList.forEach(s => {
+                            const seriesName = s.name || s.y;
+                            const vals = getData(s.y);
+                            if (!vals) return;
+
+                            const rawPoints = runData.epochs.map((e, i) => ({ x: e, y: vals[i] }));
+                            const smoothed = calculateEMA(vals, smoothWeight);
+                            const smoothedPoints = runData.epochs.map((e, i) => ({ x: e, y: smoothed[i] }));
+                            const dash = DASH_PATTERNS[seriesIdx % DASH_PATTERNS.length];
+
+                            let label = config.dataByRun.length > 1 && config.type === 'line_multi' ? `${seriesName} (${runName})` : seriesName;
+                            let rawLabel = config.dataByRun.length > 1 ? `${seriesName} (${config.type === 'line_multi' ? runName + ' ' : ''}Raw)` : `${seriesName === 'Value' ? '' : seriesName + ' '}Raw`;
+                            // For single-series line with single run, use cleaner labels
+                            if (config.type === 'line' && config.dataByRun.length === 1) { label = 'Smoothed'; rawLabel = 'Raw'; }
+
+                            if (smoothWeight > 0) datasets.push({ label: rawLabel, data: rawPoints, borderColor: c_raw, backgroundColor: c_raw, borderWidth: 1, pointRadius: 0, showLine: true, borderDash: dash });
+                            datasets.push({ label: label, data: smoothedPoints, borderColor: c, backgroundColor: c, borderWidth: 2, pointRadius: smoothWeight > 0 ? 0 : 1.5, showLine: true, borderDash: dash });
+                            seriesIdx++;
+                        });
+                    }
+                    else if (config.type === 'scatter') {
+                        const csv = parseCSV(runData.raw_csv);
+                        if (!csv) return;
+
+                        config.series.forEach((s, sIdx) => {
+                            const xIdx = csv.headers.indexOf(s.x);
+                            const yIdx = csv.headers.indexOf(s.y);
+                            if (xIdx === -1 || yIdx === -1) return;
+
+                            const data = [];
+                            csv.rows.forEach(cols => {
+                                if (cols.length > Math.max(xIdx, yIdx)) {
+                                    const xVal = parseFloat(cols[xIdx]);
+                                    const yVal = parseFloat(cols[yIdx]);
+                                    if (!isNaN(xVal) && !isNaN(yVal)) data.push({ x: xVal, y: yVal });
+                                }
+                            });
+
+                            const labelPrefix = config.dataByRun.length > 1 ? `${s.name || 'Series'} (${runName})` : (s.name || `Series ${sIdx + 1}`);
+                            const showLines = config.layout && config.layout.show_lines;
+                            const dash = showLines ? DASH_PATTERNS[sIdx % DASH_PATTERNS.length] : [];
+                            const seriesColor = config.dataByRun.length > 1 ? c : RUN_COLORS[sIdx % RUN_COLORS.length];
+
+                            datasets.push({
+                                label: labelPrefix, data, borderColor: seriesColor, backgroundColor: seriesColor,
+                                showLine: !!showLines, borderWidth: showLines ? 1.5 : undefined,
+                                pointRadius: 2.5, borderDash: dash
+                            });
+                        });
+                    }
+                });
+
+                let options = {
+                    responsive: true, maintainAspectRatio: !isEqual, aspectRatio: isEqual ? 1 : undefined, animation: false, color: '#eee',
+                    scales: {
+                        x: { type: 'linear', ticks: { color: '#aaa' }, grid: { color: '#333' } },
+                        y: { type: isLog ? 'logarithmic' : 'linear', ticks: { color: '#aaa' }, grid: { color: '#333' } }
+                    },
+                    plugins: {
+                        legend: {
+                            labels: {
+                                usePointStyle: true,
+                                color: '#eee',
+                                padding: 15,
+                                font: { size: 12 },
+                                generateLabels(chart) {
+                                    return chart.data.datasets.map((ds, i) => {
+                                        const meta = chart.getDatasetMeta(i);
+                                        return {
+                                            text: ds.label,
+                                            fontColor: '#eee',
+                                            fillStyle: ds.borderColor,
+                                            strokeStyle: ds.borderColor,
+                                            lineWidth: ds.showLine ? (ds.borderWidth || 2) : 0,
+                                            lineDash: ds.borderDash || [],
+                                            pointStyle: ds.showLine ? 'line' : 'circle',
+                                            hidden: meta.hidden,
+                                            datasetIndex: i
+                                        };
+                                    });
+                                }
+                            }
+                        }
+                    }
+                };
+                if (!isEqual) {
+                    options.maintainAspectRatio = false;
+                    delete options.aspectRatio;
+                }
+
+                if (config.type === 'scatter' && isEqual) {
+                    computeEqualAspectRange(datasets, options);
+                }
+
+                chartInstances[id] = new Chart(ctx, {
+                    type: 'line',
+                    data: { datasets: datasets },
+                    options: options
+                });
+            }
+            else if (config.type === 'heatmap') {
+                const runData = config.dataByRun[0];
+                if (!runData) return;
+
+                const rows = runData.raw_csv.trim().split('\n');
+                const jsonObjects = rows.map(line => {
+                    try { return JSON.parse(line); } catch(e) { return null; }
+                }).filter(obj => obj !== null);
+
+                if (jsonObjects.length === 0) return;
+
+                const matrixData = [];
+                let maxCount = 0;
+
+                // Dynamically collect class labels sorted by their index
+                const classLabelMap = {};
+                jsonObjects.forEach(obj => {
+                    if (obj.true_class !== undefined && obj.true_label !== undefined) {
+                        classLabelMap[obj.true_class] = obj.true_label;
+                    }
+                    if (obj.pred_class !== undefined && obj.pred_label !== undefined) {
+                        classLabelMap[obj.pred_class] = obj.pred_label;
+                    }
+                });
+
+                // Extract unique indices, sort them, and map to label strings
+                const sortedIndices = Object.keys(classLabelMap).map(Number).sort((a, b) => a - b);
+                const classLabels = sortedIndices.map(idx => classLabelMap[idx]);
+
+                jsonObjects.forEach(obj => {
+                    const x_idx = obj.pred_class;
+                    const y_idx = obj.true_class;
+                    const count = obj.count;
+
+                    if (x_idx === undefined || y_idx === undefined || count === undefined) return;
+
+                    if (count > maxCount) maxCount = count;
+
+                    matrixData.push({
+                        x: classLabelMap[x_idx] || `Class ${x_idx}`,
+                        y: classLabelMap[y_idx] || `Class ${y_idx}`,
+                        v: count
+                    });
+                });
+
+                const numClasses = classLabels.length || 1;
+
+                chartInstances[id] = new Chart(ctx, {
+                    type: 'matrix',
+                    data: {
+                        datasets: [{
+                            label: config.title,
+                            data: matrixData,
+                            backgroundColor(context) {
+                                const value = context.dataset.data[context.dataIndex].v;
+                                const alpha = maxCount > 0 ? (0.15 + 0.85 * value / maxCount) : 0;
+                                return `rgba(59, 130, 246, ${alpha})`;
+                            },
+                            borderColor: '#333',
+                            borderWidth: 2,
+                            width: ({ chart }) => {
+                                const area = chart.chartArea;
+                                if (!area) return 0;
+                                return (area.width / numClasses) - 4;
+                            },
+                            height: ({ chart }) => {
+                                const area = chart.chartArea;
+                                if (!area) return 0;
+                                return (area.height / numClasses) - 4;
+                            }
+                        }]
+                    },
+                    options: {
+                        responsive: true, maintainAspectRatio: false, color: '#eee',
+                        scales: {
+                            x: {
+                                type: 'category',
+                                title: { display: true, text: 'Predicted Class', color: '#eee' },
+                                ticks: { color: '#aaa' },
+                                grid: { display: false },
+                                offset: true
+                            },
+                            y: {
+                                type: 'category',
+                                title: { display: true, text: 'True Class', color: '#eee' },
+                                ticks: { color: '#aaa' },
+                                grid: { display: false },
+                                offset: true,
+                                reverse: true
+                            }
+                        },
+                        plugins: {
+                            tooltip: {
+                                callbacks: {
+                                    title() { return ''; },
+                                    label(context) {
+                                        const v = context.dataset.data[context.dataIndex];
+                                        return ['True: ' + v.y, 'Pred: ' + v.x, 'Count: ' + v.v];
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    plugins: [{
+                        id: 'matrixText',
+                        afterDatasetsDraw(chart) {
+                            const ctx = chart.ctx;
+                            chart.data.datasets.forEach((dataset, i) => {
+                                const meta = chart.getDatasetMeta(i);
+                                meta.data.forEach((element, index) => {
+                                    const value = dataset.data[index].v;
+                                    const cellW = element.width || 0;
+                                    const cellH = element.height || 0;
+                                    ctx.fillStyle = '#fff';
+                                    ctx.font = 'bold 14px monospace';
+                                    ctx.textAlign = 'center';
+                                    ctx.textBaseline = 'middle';
+                                    ctx.fillText(value, element.x + cellW / 2, element.y + cellH / 2);
+                                });
+                            });
+                        }
+                    }]
+                });
+            }
+        }
+        document.getElementById('layout-select').addEventListener('change', function (e) {
+            const val = e.target.value;
+            const container = document.getElementById('dynamic-charts-container');
+            if (val === 'auto') {
+                container.style.gridTemplateColumns = 'repeat(auto-fit, minmax(450px, 1fr))';
+            } else {
+                container.style.gridTemplateColumns = `repeat(${val}, 1fr)`;
+            }
+
+            setTimeout(() => {
+                Object.values(chartInstances).forEach(chart => chart.resize());
+            }, 100);
+        });
+    </script>
+</body>
+
+</html>

mtrick/tracker.py

@@ -0,0 +1,142 @@
+import os
+import re
+import json
+import subprocess
+from datetime import datetime
+
+class MTracker:
+    def __init__(
+        self,
+        experiment_name: str,
+        save_path: str = "metrics",
+    ):
+        self.experiment_name = experiment_name
+        self.save_path = save_path
+
+        # Autogenerated metadata
+        self.timestamp: str = datetime.now().strftime("%Y%m%d_%H%M%S")
+        self.git_commit: str = self.get_git_commit()
+
+        # Determine experiment number from the highest existing exp* directory
+        os.makedirs(self.save_path, exist_ok=True)
+        self.experiment_number = self.get_experiment_number()
+
+        dir_name = f"exp{self.experiment_number:03d}_{self.experiment_name}_{self.timestamp}"
+        self.experiment_dir = os.path.join(self.save_path, dir_name)
+        try:
+            os.mkdir(self.experiment_dir)
+        except FileExistsError:
+            raise RuntimeError(
+                f"Failed to create a unique run directory {self.save_path}"
+            )
+
+        # Metadata dump
+        self.meta = {
+            "experiment_name": self.experiment_name,
+            "experiment_number": self.experiment_number,
+            "timestamp": self.timestamp,
+            "git_commit": self.git_commit,
+        }
+        with open(os.path.join(self.experiment_dir, "meta.json"), "w") as f:
+            json.dump(self.meta, f, indent=4)
+
+        print(f"Tracking experiment at: {self.experiment_dir}")
+
+    def get_git_commit(self) -> str:
+        """Returns the current short git commit hash, appending '-dirty' if uncommitted changes exist."""
+        try:
+            commit_hash = (
+                subprocess.check_output(["git", "rev-parse", "--short", "HEAD"])
+                .decode("ascii")
+                .strip()
+            )
+            status = (
+                subprocess.check_output(["git", "status", "--porcelain"])
+                .decode("ascii")
+                .strip()
+            )
+            if status:
+                return f"{commit_hash}-dirty"
+            return commit_hash
+        except Exception:
+            return "unknown"
+
+    def get_experiment_number(self) -> int:
+        max_exp_num = 0
+        for path in os.listdir(self.save_path):
+            match = re.match(r"^exp(\d+)_", path)
+            if match:
+                max_exp_num = max(max_exp_num, int(match.group(1)))
+
+        return max_exp_num + 1
+
+
+    def log(
+        self,
+        metrics: dict[str, float],
+        epoch: int,
+    ):
+        """
+        Simplified logging API.
+        """
+        print(f"{epoch:4d}| {metrics}")
+
+        log_entry: dict[str, float] = {"epoch": epoch, **metrics}
+        metrics_path = os.path.join(self.experiment_dir, "metrics.jsonl")
+        with open(metrics_path, "a") as f:
+            f.write(json.dumps(log_entry) + "\n")
+
+        
+
+    def log_trajectory(
+        self,
+        true_data: list[list[float]],
+        pred_data: list[list[float]],
+    ):
+        """
+        Saves a 2D trajectory of ground truth vs predicted data to a JSON file.
+        true_data: numpy array of shape (seq_len, 2+)
+        pred_data: numpy array of shape (seq_len, 2+)
+        """
+        data: dict[str, list[list[float]]] = {
+            "true": [[float(p[0]), float(p[1])] for p in true_data],
+            "pred": [[float(p[0]), float(p[1])] for p in pred_data]
+        }
+
+        filename = "trajectory.json"
+        json_path = os.path.join(self.experiment_dir, filename)
+
+        with open(json_path, "w") as f:
+            json.dump(data, f)
+
+
+    def log_confusion_matrix(
+        self,
+        matrix_data,
+        classes=None,
+        title="Confusion Matrix",
+        filename="confusion.jsonl",
+    ):
+        """
+        Saves a confusion matrix to JSONL.
+        matrix_data: 2D numpy array or nested list [true_class][pred_class]
+        classes: List of string labels for the classes.
+        """
+        jsonl_path = os.path.join(self.experiment_dir, filename)
+        num_classes = len(matrix_data)
+        if classes is None:
+            classes = [f"Class {i}" for i in range(num_classes)]
+
+        with open(jsonl_path, "w") as f:
+            for i in range(num_classes):
+                for j in range(num_classes):
+                    row = {
+                        "true_class": i,
+                        "pred_class": j,
+                        "count": int(matrix_data[i][j]),
+                        "true_label": str(classes[i]),
+                        "pred_label": str(classes[j])
+                    }
+                    f.write(json.dumps(row) + "\n")
+
+        print(f"Saved confusion matrix: {jsonl_path}")

mtrick-0.1.0.dist-info/METADATA

@@ -0,0 +1,46 @@
+Metadata-Version: 2.3
+Name: mtrick
+Version: 0.1.0
+Summary: A local-first, simple ML experiment tracker
+Author: Avik Arefin
+Author-email: Avik Arefin <avik.me.arefin@gmail.com>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/AvikArefin/mtrick
+Description-Content-Type: text/markdown
+
+# mtrick: Metrics Tracker
+A local-first simple ML experiment tracker with zero configurations required.
+
+![Dashboard Interface](interface.png)
+
+## Installation
+
+```
+uv add mtrick
+```
+or 
+```
+pip install mtrick
+```
+
+
+If you want the latest version
+
+```
+uv add git+https://github.com/AvikArefin/mtrick.git
+```
+or 
+
+```bash
+pip install git+https://github.com/AvikArefin/mtrick.git
+```
+
+## Usage
+Launch the dashboard via:
+```bash
+mtrick
+```

mtrick-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+mtrick/__init__.py,sha256=DtuNXopfvhHgo8EojHJC0WS4DzVEBwzZWUhvtDCxCMQ,125
+mtrick/dashboard.py,sha256=UfmIZN3Qe2kZ3-yzkrW6KtZ0zPFGrjW_S7kscmvrdtk,4954
+mtrick/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mtrick/static/index.html,sha256=W06j_k6VM_e2we2ssMFYTHyxoKcAn8GlAtlK8rYojrc,37906
+mtrick/tracker.py,sha256=59DPMgFvRPA2tbb77cArO8zXnCet6_66T_j7JJtkTVA,4627
+mtrick/utils.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mtrick-0.1.0.dist-info/WHEEL,sha256=o6xtdofIa8Zz80kUveEHMWeAWtEyZSzYS1bbyKDCgzA,80
+mtrick-0.1.0.dist-info/entry_points.txt,sha256=0YOBI8RCdeddujXWZKeikFdAoMOhO9ikiIj4swbvw4I,50
+mtrick-0.1.0.dist-info/METADATA,sha256=IZBNfgfKPukXMvdFWMrU46Nru9CDCJyfM7GOr_qtFKI,899
+mtrick-0.1.0.dist-info/RECORD,,

mtrick-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.10.4
+Root-Is-Purelib: true
+Tag: py3-none-any

mtrick-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+mtrick = mtrick.dashboard:main
+