mlx-tracker 0.1.0__py3-none-any.whl

mlx/__init__.py

@@ -0,0 +1,8 @@
+"""
+mlx — Local ML Experiment Manager
+Track experiments, runs, params & metrics. 100% local. No server needed.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Aditya Kumar Singh"
+__license__ = "MIT"

mlx/cli.py

@@ -0,0 +1,46 @@
+"""
+mlx/cli.py — The main entry point for the mlx CLI tool.
+
+When the user types `mlx` in their terminal, Python runs this file
+and calls `app`. Everything starts here.
+"""
+
+
+import typer
+from rich.console import Console
+
+from mlx import __version__
+
+app = typer.Typer(
+    help="[bold cyan]MLX[/bold cyan] — Local ML Experiment Manager.\n\n"
+         "Track experiments, runs, params and metrics. 100% local. No server needed.",
+    no_args_is_help=True,       # Show help when user types just `mlx`
+    rich_markup_mode="rich",    # Allow [bold], [cyan] etc in help text
+    add_completion=True, 
+)
+
+console = Console()
+
+from mlx.commands.init import init 
+from mlx.commands import run as run_cmd 
+from mlx.commands import log as log_cmd 
+from mlx.commands import ls as ls_cmd 
+from mlx.commands import status as status_cmd  
+from mlx.commands import compare as compare_cmd
+from mlx.commands import export as export_cmd
+
+from mlx.commands.init import init
+app.command("init", help="Initialize a new mlx project")(init)
+app.add_typer(run_cmd.app,  name="run",  help="Manage experiment runs")
+app.add_typer(log_cmd.app, name="log", help="Log Metric, params and notes")
+app.add_typer(ls_cmd.app , name="ls", help="list all runs")
+app.add_typer(status_cmd.app, name="status", help="show the active run")
+app.add_typer(compare_cmd.app, name="compare", help="comapre runs side by side")
+app.add_typer(export_cmd.app, name="export", help="Export runs to csv or json")
+
+@app.command("version")
+def version():
+    console.print(f"mlx [bold cyan]v{__version__}[/bold cyan]")
+    
+if __name__ == "__main__":
+    app()

mlx/commands/__init__.py

@@ -0,0 +1 @@
+# CLI commands — one file per command group

mlx/commands/compare.py

@@ -0,0 +1,346 @@
+#it is the most important command, see exactly which model won and why ??
+# uasge: mlx compare run-id-1 run-id-2 , mlx compare run-id-1 run-id-2 --params-only 
+
+
+import typer 
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text 
+from rich import box
+
+from mlx.core.run import RunManager 
+from mlx.core.metrics import MetricManager
+from mlx.core.params import ParamManager
+from mlx.utils.display import error, warn
+
+app = typer.Typer(help="Compare two or more runs side by side")
+
+console = Console()
+
+def _print_header(runs: list):
+    console.print(
+        f"[bold white]Comparing {len(runs)} runs[/bold white]\n"
+    )
+
+    for i, run in enumerate(runs):
+        # Last item gets └── others get ├──
+        prefix = "└──" if i == len(runs) - 1 else "├──"
+
+        status_color = {
+            "done":    "green",
+            "running": "yellow",
+            "failed":  "red",
+        }.get(run.status, "white")
+
+        duration = ""
+        if run.duration_sec:
+            m, s = divmod(int(run.duration_sec), 60)
+            duration = f"{m}m {s}s" if m > 0 else f"{s}s"
+            duration = f"  [dim]{duration}[/dim]"
+
+        console.print(
+            f"  {prefix} [bold white]{run.name}[/bold white]"
+            f"  [{status_color}]{run.status}[/{status_color}]"
+            f"{duration}"
+            f"  [dim]{run.run_id}[/dim]"
+        )
+
+    console.print()
+    
+def _print_params_table(
+    runs: list,
+    params_by_run: dict,
+    show_all: bool = False,
+):
+
+    # Collect all unique param keys across all runs
+    all_keys = set()
+    for params in params_by_run.values():
+        all_keys.update(params.keys())
+    all_keys = sorted(all_keys)
+
+    if not all_keys:
+        console.print("[dim]  No params logged for these runs.[/dim]\n")
+        return
+
+    # Figure out which params actually changed
+    changed_keys = set()
+    for key in all_keys:
+        values = [
+            params_by_run[run.run_id].get(key, "—")
+            for run in runs
+        ]
+        # If not all values are the same → it changed
+        if len(set(values)) > 1:
+            changed_keys.add(key)
+
+    # Filter to only changed params unless show_all
+    display_keys = all_keys if show_all else [
+        k for k in all_keys if k in changed_keys
+    ]
+
+    if not display_keys:
+        console.print(
+            "[dim]  All params are identical across runs.[/dim]"
+        )
+        if not show_all:
+            console.print(
+                "[dim]  Use [cyan]--all-params[/cyan] "
+                "to see them anyway.[/dim]"
+            )
+        console.print()
+        return
+
+    # ── Build the table ────────────────────────
+    table = Table(
+        box=box.SIMPLE_HEAD,
+        border_style="dim",
+        header_style="bold cyan",
+        show_edge=True,
+        pad_edge=True,
+    )
+
+    # First column: param name
+    table.add_column(
+        "Param",
+        style="dim",
+        no_wrap=True,
+        min_width=18,
+    )
+
+    # One column per run
+    for run in runs:
+        table.add_column(
+            run.name,
+            justify="right",
+            style="white",
+            min_width=12,
+        )
+
+    # Last column: changed indicator
+    table.add_column("", justify="center", min_width=6)
+
+    # ── Add rows ───────────────────────────────
+    for key in display_keys:
+        values = [
+            params_by_run[run.run_id].get(key, "—")
+            for run in runs
+        ]
+
+        is_changed = key in changed_keys
+
+        # Style each cell
+        styled_values = []
+        for v in values:
+            if v == "—":
+                # Not logged for this run
+                styled_values.append(Text("—", style="dim"))
+            elif is_changed:
+                # Changed — highlight yellow
+                styled_values.append(Text(str(v), style="bold yellow"))
+            else:
+                styled_values.append(Text(str(v), style="white"))
+
+        # Changed indicator
+        indicator = Text("← diff", style="dim yellow") if is_changed else Text("")
+
+        table.add_row(
+            key,
+            *styled_values,
+            indicator,
+        )
+
+    console.print("[bold]Params[/bold]")
+    console.print(table)
+
+    # Note about hidden unchanged params
+    hidden = len(all_keys) - len(display_keys)
+    if hidden > 0 and not show_all:
+        console.print(
+            f"  [dim]{hidden} unchanged param(s) hidden — "
+            f"use [cyan]--all-params[/cyan] to show[/dim]"
+        )
+    console.print()
+
+def _print_metrics_table(runs: list, metrics_by_run: dict):
+
+    # Collect all unique metric keys
+    all_keys = set()
+    for metrics in metrics_by_run.values():
+        all_keys.update(metrics.keys())
+    all_keys = sorted(all_keys)
+
+    if not all_keys:
+        console.print("[dim]  No metrics logged for these runs.[/dim]\n")
+        return
+
+    # ── Decide which direction is "better" ────
+    # Lower is better for these metric name patterns
+    lower_is_better_patterns = [
+        "loss", "error", "mse", "mae", "rmse",
+        "mape", "logloss", "cross_entropy",
+    ]
+
+    def lower_is_better(key: str) -> bool:
+        key_lower = key.lower()
+        return any(p in key_lower for p in lower_is_better_patterns)
+
+    # ── Build the table ────────────────────────
+    table = Table(
+        box=box.SIMPLE_HEAD,
+        border_style="dim",
+        header_style="bold cyan",
+        show_edge=True,
+        pad_edge=True,
+    )
+
+    # First column: metric name
+    table.add_column(
+        "Metric",
+        style="dim",
+        no_wrap=True,
+        min_width=18,
+    )
+
+    # One column per run
+    for run in runs:
+        table.add_column(
+            run.name,
+            justify="right",
+            style="white",
+            min_width=12,
+        )
+
+    # Last column: difference
+    table.add_column(
+        "diff",
+        justify="right",
+        style="dim",
+        min_width=10,
+    )
+
+    # ── Add rows ───────────────────────────────
+    for key in all_keys:
+
+        # Get values for all runs — None if not logged
+        values = [
+            metrics_by_run[run.run_id].get(key)
+            for run in runs
+        ]
+
+        # Filter out None for calculations
+        real_values = [v for v in values if v is not None]
+
+        if not real_values:
+            continue
+
+        # Find best value
+        if lower_is_better(key):
+            best_val = min(real_values)
+            worst_val = max(real_values)
+        else:
+            best_val = max(real_values)
+            worst_val = min(real_values)
+
+        # Calculate difference
+        if len(real_values) >= 2:
+            diff = best_val - worst_val
+            # Format diff with sign
+            diff_str = f"{diff:+.4f}"
+            diff_color = "green" if diff > 0 else "red" if diff < 0 else "dim"
+            diff_display = Text(diff_str, style=diff_color)
+        else:
+            diff_display = Text("—", style="dim")
+
+        # Style each cell
+        styled_values = []
+        for v in values:
+            if v is None:
+                styled_values.append(Text("—", style="dim"))
+            elif v == best_val and len(real_values) > 1:
+                # Best value — green and bold
+                styled_values.append(
+                    Text(f"{v:.4f}", style="bold green")
+                )
+            else:
+                styled_values.append(Text(f"{v:.4f}", style="white"))
+
+        table.add_row(
+            key,
+            *styled_values,
+            diff_display,
+        )
+
+    console.print("[bold]Metrics[/bold]")
+    console.print(table)
+    console.print(
+        "  [dim][bold green]green[/bold green] = best value  "
+        "·  diff = best − worst[/dim]"
+    )
+    console.print()
+
+@app.callback(invoke_without_command=True)
+def compare(
+    run_ids: list[str] = typer.Argument(
+        ...,
+        help="Two or more run IDS to compare"
+    ),
+    params_only: bool = typer.Option(
+        False,
+        "--params-only", "-p",
+        help="Show only params, no metrics"
+    ),
+    metrics_only: bool = typer.Option(
+        False,
+        "--metrics-only", "-m",
+        help="Show only metrics, no params"
+    ),
+    all_params: bool = typer.Option(
+        False,
+        "--all-params",
+        help="Show all params including unchanged ones"
+    ),
+):
+    # first of all we will checks that we have at least 2 ids 
+    if len(run_ids) < 2:
+        error("Please provide at least 2 run IDs to compare.")
+        console.print()
+        console.print(
+            "  Usage: [cyan]mlx compare run-id-1 run-id-2[/cyan]"
+        )
+        console.print(
+            "  Get run IDs from: [cyan]mlx ls[/cyan]"
+        )
+        raise typer.Exit(1)
+
+    # fetch all runs
+    runs = []
+    for rid in run_ids:
+        run = RunManager.get(rid)
+        if not run:
+            error(f"Run not found: [bold]{rid}[/bold]")
+            console.print(
+                f"  Check your run IDs with: [cyan]mlx ls[/cyan]"
+            )
+            raise typer.Exit(1)
+        
+        runs.append(run)
+        
+    # fetch params and metrics for each run 
+    params_by_run = {r.run_id: ParamManager.as_dict(r.run_id) for r in runs}
+    metrics_by_run = {
+        r.run_id: {m.key: m.value for m in MetricManager.get_latest(r.run_id)}
+        for r in runs
+    }
+    
+    console.print()
+    _print_header(runs)
+    
+    if not metrics_only:
+        _print_params_table(runs, params_by_run, show_all=all_params)
+        
+    if not params_only:
+        _print_metrics_table(runs, metrics_by_run)
+
+    console.print()
+

mlx/commands/export.py

@@ -0,0 +1,264 @@
+"""
+
+Usage:
+    mlx export                          → CSV to stdout
+    mlx export --format json            → JSON to stdout
+    mlx export --out runs.csv           → save to file
+    mlx export --out runs.json --format json
+    mlx export --experiment fraud       → filter by experiment
+    mlx export --status done            → filter by status
+"""
+
+import json
+import csv
+import io
+import typer
+from pathlib import Path
+from rich.console import Console
+
+from mlx.core.run import RunManager
+from mlx.core.metrics import MetricManager
+from mlx.core.params import ParamManager
+from mlx.utils.display import success, error, info, warn
+
+app = typer.Typer(help="Export runs to CSV or JSON.")
+console = Console()
+
+
+@app.callback(invoke_without_command=True)
+def export(
+    format: str = typer.Option(
+        "csv",
+        "--format", "-f",
+        help="Export format: csv or json"
+    ),
+    out: str = typer.Option(
+        None,
+        "--out", "-o",
+        help="Output file path  e.g. runs.csv"
+    ),
+    experiment: str = typer.Option(
+        None,
+        "--experiment", "-e",
+        help="Filter by experiment name"
+    ),
+    status: str = typer.Option(
+        None,
+        "--status", "-s",
+        help="Filter by status: done, running, failed"
+    ),
+    limit: int = typer.Option(
+        None,
+        "--limit", "-l",
+        help="Max number of runs to export"
+    ),
+    latest_metrics: bool = typer.Option(
+        True,
+        "--latest-metrics/--all-metrics",
+        help="Export only latest metric per key (default) or all steps"
+    ),
+):
+
+    # ── Validate format 
+    if format not in ("csv", "json"):
+        error(f"Unknown format: '{format}'")
+        console.print("  Supported formats: [cyan]csv[/cyan], [cyan]json[/cyan]")
+        raise typer.Exit(1)
+
+    # ── Fetch runs 
+    runs = RunManager.get_all(
+        experiment=experiment,
+        status=status,
+        limit=limit or 999999,
+    )
+
+    if not runs:
+        warn("No runs found to export.")
+        if experiment or status:
+            console.print("  Try removing filters.")
+        raise typer.Exit()
+
+    # ── Build export data 
+    # Each item = one run with all its params and metrics
+    export_data = _build_export_data(runs, latest_metrics)
+
+    # ── Generate output 
+    if format == "csv":
+        output = _to_csv(export_data)
+    else:
+        output = _to_json(export_data)
+
+    # ── Write to file or stdout 
+    if out:
+        _save_to_file(output, out, format, len(runs))
+    else:
+        # Print to terminal
+        # Use print() not console.print() to avoid Rich markup
+        print(output)
+
+
+# DATA BUILDER
+
+def _build_export_data(runs: list, latest_only: bool) -> list[dict]:
+    data = []
+
+    for run in runs:
+
+        # Base run fields
+        row = {
+            "run_id":       run.run_id,
+            "name":         run.name,
+            "experiment":   run.experiment,
+            "status":       run.status,
+            "tags":         run.tags,
+            "created_at":   run.created_at[:19].replace("T", " "),
+            "finished_at":  run.finished_at[:19].replace("T", " ") if run.finished_at else "",
+            "duration_sec": run.duration_sec or "",
+        }
+
+        # Add params — prefix with "param_" to avoid name collisions
+        params = ParamManager.as_dict(run.run_id)
+        for key, value in sorted(params.items()):
+            row[f"param_{key}"] = value
+
+        # Add metrics — prefix with "metric_"
+        if latest_only:
+            # One value per metric key — the final/best one
+            metrics = {
+                m.key: m.value
+                for m in MetricManager.get_latest(run.run_id)
+            }
+            for key, value in sorted(metrics.items()):
+                row[f"metric_{key}"] = value
+        else:
+            # All steps — creates columns like metric_accuracy_step_100
+            all_metrics = MetricManager.get_for_run(run.run_id)
+            for m in all_metrics:
+                row[f"metric_{m.key}_step_{m.step}"] = m.value
+
+        data.append(row)
+
+    return data
+
+
+# CSV FORMATTER
+
+def _to_csv(data: list[dict]) -> str:
+
+    if not data:
+        return ""
+
+    # Collect ALL unique column names across all runs
+    # Preserve order: base fields first, then params, then metrics
+    all_columns = []
+    seen = set()
+
+    for row in data:
+        for key in row.keys():
+            if key not in seen:
+                all_columns.append(key)
+                seen.add(key)
+
+    # Write CSV to a string buffer
+    output = io.StringIO()
+    writer = csv.DictWriter(
+        output,
+        fieldnames=all_columns,
+        extrasaction="ignore",    # ignore extra keys
+        restval="",               # empty string for missing values
+        lineterminator="\n",
+    )
+
+    writer.writeheader()
+    writer.writerows(data)
+
+    return output.getvalue()
+
+
+
+# JSON FORMATTER
+
+
+def _to_json(data: list[dict]) -> str:
+
+    # Rebuild as nested structure for JSON
+    nested = []
+
+    for row in data:
+        # Separate base fields, params, metrics
+        base    = {}
+        params  = {}
+        metrics = {}
+
+        for key, value in row.items():
+            if key.startswith("param_"):
+                params[key[6:]] = value      # strip "param_" prefix
+            elif key.startswith("metric_"):
+                metrics[key[7:]] = value     # strip "metric_" prefix
+            else:
+                base[key] = value
+
+        nested.append({
+            **base,
+            "params":  params,
+            "metrics": metrics,
+        })
+
+    return json.dumps(nested, indent=2)
+
+
+
+# FILE SAVER
+
+
+def _save_to_file(
+    content: str,
+    path: str,
+    format: str,
+    run_count: int,
+):
+    """
+    Save exported content to a file.
+    Creates parent directories if needed.
+    """
+    out_path = Path(path)
+
+    # Auto-add extension if missing
+    if not out_path.suffix:
+        out_path = out_path.with_suffix(f".{format}")
+
+    # Create parent dirs if needed
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Write the file
+    out_path.write_text(content)
+
+    success(
+        f"Exported [bold]{run_count}[/bold] run(s) "
+        f"to [bold cyan]{out_path}[/bold cyan]"
+    )
+    console.print(
+        f"  [dim]Format  :[/dim]  {format.upper()}"
+    )
+    console.print(
+        f"  [dim]Size    :[/dim]  "
+        f"{out_path.stat().st_size / 1024:.1f} KB"
+    )
+    console.print()
+
+    # Show a helpful next step
+    if format == "csv":
+        console.print("[dim]Open in pandas:[/dim]")
+        console.print(
+            f"  [cyan]import pandas as pd[/cyan]\n"
+            f"  [cyan]df = pd.read_csv('{out_path}')[/cyan]\n"
+            f"  [cyan]print(df.head())[/cyan]"
+        )
+    else:
+        console.print("[dim]Load in Python:[/dim]")
+        console.print(
+            f"  [cyan]import json[/cyan]\n"
+            f"  [cyan]data = json.load(open('{out_path}'))[/cyan]\n"
+            f"  [cyan]print(data[0]['metrics'])[/cyan]"
+        )
+    console.print()