mlx-tracker 0.1.0__tar.gz

mlx_tracker-0.1.0/.github/ISSUE_TEMPLATE/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+## What does this PR do?
+<!-- Brief description -->
+
+## Type of change
+- [ ] Bug fix
+- [ ] New feature  
+- [ ] Documentation update
+- [ ] Refactor
+
+## Checklist
+- [ ] I ran `pytest` and all tests pass
+- [ ] I ran `ruff check .` and fixed any issues
+- [ ] I updated `CHANGELOG.md`

mlx_tracker-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,21 @@
+---
+name: Bug Report
+about: Something isn't working
+labels: bug
+---
+
+## What happened?
+<!-- Describe the bug clearly -->
+
+## Steps to reproduce
+```bash
+# Paste the exact commands you ran
+```
+
+## Expected behavior
+<!-- What should have happened? -->
+
+## Environment
+- OS: 
+- Python version: 
+- mlx version: (`mlx version`)

mlx_tracker-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature Request
+about: Suggest something new
+labels: enhancement
+---
+
+## What problem does this solve?
+<!-- Describe the problem you're facing -->
+
+## Proposed solution
+<!-- How would you like it to work? -->
+
+## Example usage
+```bash
+# Show what the command would look like
+mlx your-new-command --option value
+```

mlx_tracker-0.1.0/.gitignore

@@ -0,0 +1,65 @@
+# ─────────────────────────────────────
+# Python
+# ─────────────────────────────────────
+
+# Virtual environment — never commit this
+venv
+venv/
+env/
+
+# Python compiled files — auto-generated by Python
+__pycache__/
+*.py[cod]       
+*.pyo
+
+# Build artifacts — generated when you run `pip install` or `python -m build`
+dist/
+build/
+*.egg-info/
+.eggs/
+
+# ─────────────────────────────────────
+# MLX — local experiment data
+# ─────────────────────────────────────
+
+# This is each user's private local data
+# Everyone has their own .mlx/ folder on their own machine
+.mlx/
+
+# ─────────────────────────────────────
+# Testing & Coverage
+# ─────────────────────────────────────
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# ─────────────────────────────────────
+# IDE / Editor files
+# ─────────────────────────────────────
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# ─────────────────────────────────────
+# OS generated files
+# ─────────────────────────────────────
+
+# Mac
+.DS_Store
+.AppleDouble
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# ─────────────────────────────────────
+# Secrets — NEVER commit these
+# ─────────────────────────────────────
+.env
+.env.local
+*.pem
+*.key
+secrets.toml

mlx_tracker-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to mlx will be documented here.
+
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versioning follows [Semantic Versioning](https://semver.org/).
+
+---
+
+## [Unreleased]
+
+### Added
+- Initial project structure
+- `pyproject.toml` with modern Python packaging
+- CLI entry point via Typer
+- MIT License
+
+---
+
+## Version Guide
+
+- `0.x.x` — Early development, APIs may change
+- `1.0.0` — Stable release, ready for production use

mlx_tracker-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mlx_tracker-0.1.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: mlx-tracker
+Version: 0.1.0
+Summary: Local ML experiment tracker for engineers who live in the terminal
+Project-URL: Homepage, https://github.com/adityasingh345/mlx
+Project-URL: Repository, https://github.com/adityasingh345/mlx
+Author-email: Your Real Name <your@email.com>
+License: MIT License
+        
+        Copyright (c) 2024 Your Name
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cli,experiment-tracking,machine-learning,mlops
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: rich>=13
+Requires-Dist: sqlmodel>=0.0.16
+Requires-Dist: toml>=0.10
+Requires-Dist: typer[all]>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 🧪 mlx — ML Experiment Manager
+
+> Track experiments, runs, params & metrics. 100% local. No server needed.
+```bash

mlx_tracker-0.1.0/README.md

@@ -0,0 +1,4 @@
+# 🧪 mlx — ML Experiment Manager
+
+> Track experiments, runs, params & metrics. 100% local. No server needed.
+```bash

mlx_tracker-0.1.0/docs/commands/init.md

@@ -0,0 +1,40 @@
+# mlx init
+
+Initialize a new mlx project in the current directory.
+
+## Usage
+```bash
+mlx init [OPTIONS]
+```
+
+## Options
+
+| Option | Short | Default | Description |
+|--------|-------|---------|-------------|
+| `--name` | `-n` | folder name | Project name |
+| `--desc` | `-d` | `""` | Project description |
+| `--force` | `-f` | `False` | Re-initialize existing project |
+
+## Examples
+```bash
+# Basic init
+mlx init
+
+# With custom name
+mlx init --name "fraud-detection"
+
+# With name and description
+mlx init --name "fraud-detection" --desc "Fraud model v2"
+
+# Re-initialize (keeps existing data)
+mlx init --force
+```
+
+## What it creates
+```
+.mlx/
+├── mlx.db        ← SQLite database
+├── config.toml   ← project config
+├── runs/         ← log files per run
+└── artifacts/    ← saved models (future)
+```

mlx_tracker-0.1.0/docs/commands/log.md

@@ -0,0 +1,37 @@
+# mlx log
+
+Log metrics, params and notes to the active run.
+
+## mlx log metric
+```bash
+mlx log metric accuracy 0.94
+mlx log metric accuracy 0.94 --step 100
+mlx log metric val_loss 0.21 --step 50
+```
+
+| Argument | Description |
+|----------|-------------|
+| `key` | Metric name — accuracy, loss, auc |
+| `value` | Numeric value — 0.94 |
+| `--step` | Training step or epoch |
+
+---
+
+## mlx log param
+```bash
+mlx log param learning_rate 0.05
+mlx log param depth 6
+mlx log param optimizer adam
+```
+
+Logging the same param twice **updates** it — no duplicates.
+
+---
+
+## mlx log note
+```bash
+mlx log note "val loss stopped improving at step 150"
+mlx log note "model saved to artifacts/model.cbm"
+```
+
+Notes are saved to the run's log file and shown in `mlx logs`.

mlx_tracker-0.1.0/docs/commands/run.md

@@ -0,0 +1,57 @@
+# mlx run
+
+Manage experiment runs.
+
+## Subcommands
+
+### mlx run start
+
+Start a new run and begin tracking.
+```bash
+mlx run start --name "catboost-v1"
+mlx run start --name "catboost-v1" --experiment "fraud"
+mlx run start --name "catboost-v1" --tags "catboost,baseline"
+```
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--name` | `-n` | **Required.** Run name |
+| `--experiment` | `-e` | Experiment group (default: "default") |
+| `--tags` | `-t` | Comma-separated tags |
+
+---
+
+### mlx run stop
+
+Stop the active run.
+```bash
+mlx run stop
+mlx run stop --status failed
+```
+
+| Option | Description |
+|--------|-------------|
+| `--status` | `done` or `failed` (default: done) |
+| `--run-id` | Stop specific run instead of active |
+
+---
+
+### mlx run list
+
+List all runs.
+```bash
+mlx run list
+mlx run list --experiment fraud
+mlx run list --status done
+mlx run list --limit 10
+```
+
+---
+
+### mlx run delete
+
+Delete a run and all its data permanently.
+```bash
+mlx run delete --run-id "catboost-v1_..."
+mlx run delete --run-id "catboost-v1_..." --yes
+```

mlx_tracker-0.1.0/docs/index.md

@@ -0,0 +1,54 @@
+# mlx — ML Experiment Manager
+
+> Track experiments, runs, params and metrics.
+> 100% local. No server. No account. No cloud.
+
+## Why mlx?
+
+Every ML engineer has this problem:
+
+- Trained 20 models last week
+- Can't remember which settings gave the best result
+- No way to compare runs side by side
+- Results scattered across notebooks and print statements
+
+mlx fixes this with one simple workflow:
+```bash
+mlx run start --name "catboost-v1"
+python train.py
+mlx run stop
+mlx compare catboost-v1 catboost-v2
+```
+
+## How it works
+
+mlx stores everything in a local SQLite database at `.mlx/mlx.db`.
+No internet connection needed. Your data never leaves your machine.
+```
+your-project/
+└── .mlx/
+    ├── mlx.db        ← all runs, params, metrics
+    ├── config.toml   ← project settings
+    └── runs/
+        └── catboost-v1_20240301/
+            └── stdout.log
+```
+
+## Install
+```bash
+pip install mlx-tracker
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `mlx init` | Initialize project |
+| `mlx run start` | Start a run |
+| `mlx run stop` | Stop active run |
+| `mlx log metric` | Log a metric |
+| `mlx log param` | Log a param |
+| `mlx ls` | List all runs |
+| `mlx status` | Show active run |
+| `mlx compare` | Compare runs |
+| `mlx export` | Export to CSV/JSON |

mlx_tracker-0.1.0/docs/quickstart.md

@@ -0,0 +1,55 @@
+# Quickstart
+
+Get tracking in under 5 minutes.
+
+## 1. Install
+```bash
+pip install mlx-tracker
+```
+
+## 2. Initialize your project
+```bash
+cd your-ml-project
+mlx init
+```
+
+## 3. Start a run
+```bash
+mlx run start --name "my-first-run" --experiment "fraud-detection"
+```
+
+## 4. Log params and metrics
+```bash
+mlx log param learning_rate 0.05
+mlx log param depth 6
+
+mlx log metric accuracy 0.94 --step 100
+mlx log metric loss 0.21 --step 100
+```
+
+## 5. Stop the run
+```bash
+mlx run stop
+```
+
+## 6. See your results
+```bash
+mlx ls
+mlx status --run-id "my-first-run_..."
+```
+
+## 7. Train another model and compare
+```bash
+mlx run start --name "my-second-run"
+mlx log param learning_rate 0.01
+mlx log metric accuracy 0.97 --step 100
+mlx run stop
+
+mlx compare my-first-run_... my-second-run_...
+```
+
+## Next steps
+
+- [Commands reference](commands/init.md)
+- [CatBoost example](../examples/catboost_example.py)
+- [sklearn example](../examples/sklearn_example.py)

mlx_tracker-0.1.0/examples/catboost_example.py

@@ -0,0 +1,79 @@
+"""
+examples/catboost_example.py
+
+Full CatBoost training tracked with mlx.
+
+Setup:
+    pip install catboost scikit-learn
+
+Usage:
+    cd your-project
+    mlx init
+    mlx run start --name "catboost-v1" --tags "catboost,baseline"
+    python examples/catboost_example.py
+    mlx run stop
+    mlx ls
+"""
+
+import subprocess
+from sklearn.datasets import make_classification
+from sklearn.model_selection import train_test_split
+from sklearn.metrics import accuracy_score, roc_auc_score
+from catboost import CatBoostClassifier
+
+
+def mlx(cmd: str):
+    """Call mlx CLI from Python."""
+    result = subprocess.run(
+        f"mlx {cmd}", shell=True,
+        capture_output=True, text=True
+    )
+    if result.stdout.strip():
+        print(f"  {result.stdout.strip()}")
+
+
+# ── Data ────────────────────────────────────
+X, y = make_classification(n_samples=10000, n_features=20,
+                            n_informative=10, random_state=42)
+X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)
+X_train, X_val, y_train, y_val   = train_test_split(X_train, y_train, test_size=0.2)
+
+# ── Params ───────────────────────────────────
+params = {
+    "learning_rate": 0.05,
+    "depth":         6,
+    "iterations":    200,
+    "loss_function": "Logloss",
+    "eval_metric":   "AUC",
+    "random_seed":   42,
+    "verbose":       False,
+}
+
+for key, value in params.items():
+    mlx(f"log param {key} {value}")
+
+# ── Train ────────────────────────────────────
+model = CatBoostClassifier(**params)
+model.fit(X_train, y_train, eval_set=(X_val, y_val), use_best_model=True)
+
+# ── Log metrics per iteration ────────────────
+evals = model.get_evals_result()
+for i, (tl, vl) in enumerate(zip(
+    evals["learn"]["Logloss"],
+    evals["validation"]["Logloss"]
+)):
+    step = i + 1
+    if step % 20 == 0:
+        mlx(f"log metric train_logloss {tl:.4f} --step {step}")
+        mlx(f"log metric val_logloss   {vl:.4f} --step {step}")
+
+# ── Final metrics ─────────────────────────────
+y_pred      = model.predict(X_test)
+y_pred_prob = model.predict_proba(X_test)[:, 1]
+
+mlx(f"log metric test_accuracy {accuracy_score(y_test, y_pred):.4f}")
+mlx(f"log metric test_auc      {roc_auc_score(y_test, y_pred_prob):.4f}")
+mlx(f"log param  best_iteration {model.get_best_iteration()}")
+mlx("log note 'Training complete'")
+
+print("\nDone! Run: mlx run stop && mlx ls")

mlx_tracker-0.1.0/examples/pytorch_example.py

@@ -0,0 +1,92 @@
+"""
+examples/pytorch_example.py
+
+PyTorch training loop tracked with mlx.
+Logs metrics at every epoch.
+
+Usage:
+    pip install torch
+    mlx run start --name "pytorch-v1" --tags "pytorch,mlp"
+    python examples/pytorch_example.py
+    mlx run stop
+"""
+
+import subprocess
+import torch
+import torch.nn as nn
+from torch.utils.data import DataLoader, TensorDataset
+from sklearn.datasets import make_classification
+from sklearn.model_selection import train_test_split
+from sklearn.preprocessing import StandardScaler
+import numpy as np
+
+
+def mlx(cmd):
+    subprocess.run(f"mlx {cmd}", shell=True, capture_output=True)
+
+
+# ── Data ─────────────────────────────────────
+X, y = make_classification(n_samples=5000, n_features=20,
+                            n_informative=10, random_state=42)
+X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)
+
+scaler  = StandardScaler()
+X_train = scaler.fit_transform(X_train)
+X_test  = scaler.transform(X_test)
+
+# Convert to tensors
+X_tr = torch.FloatTensor(X_train)
+y_tr = torch.FloatTensor(y_train)
+X_te = torch.FloatTensor(X_test)
+y_te = torch.FloatTensor(y_test)
+
+loader = DataLoader(TensorDataset(X_tr, y_tr), batch_size=64, shuffle=True)
+
+# ── Model ─────────────────────────────────────
+model = nn.Sequential(
+    nn.Linear(20, 64), nn.ReLU(),
+    nn.Linear(64, 32), nn.ReLU(),
+    nn.Linear(32, 1),  nn.Sigmoid(),
+)
+
+lr         = 0.001
+epochs     = 20
+optimizer  = torch.optim.Adam(model.parameters(), lr=lr)
+criterion  = nn.BCELoss()
+
+# ── Log params ────────────────────────────────
+mlx(f"log param learning_rate {lr}")
+mlx(f"log param epochs        {epochs}")
+mlx(f"log param batch_size    64")
+mlx(f"log param optimizer     adam")
+mlx(f"log param architecture  MLP-64-32-1")
+
+# ── Training loop ─────────────────────────────
+for epoch in range(1, epochs + 1):
+
+    model.train()
+    total_loss = 0
+    for xb, yb in loader:
+        optimizer.zero_grad()
+        loss = criterion(model(xb).squeeze(), yb)
+        loss.backward()
+        optimizer.step()
+        total_loss += loss.item()
+
+    avg_loss = total_loss / len(loader)
+
+    # Evaluate
+    model.eval()
+    with torch.no_grad():
+        preds = model(X_te).squeeze()
+        test_loss = criterion(preds, y_te).item()
+        accuracy  = ((preds > 0.5).float() == y_te).float().mean().item()
+
+    # Log every epoch
+    mlx(f"log metric train_loss {avg_loss:.4f}  --step {epoch}")
+    mlx(f"log metric test_loss  {test_loss:.4f} --step {epoch}")
+    mlx(f"log metric accuracy   {accuracy:.4f}  --step {epoch}")
+
+    print(f"Epoch {epoch:2d} | train={avg_loss:.4f} | test={test_loss:.4f} | acc={accuracy:.4f}")
+
+print("\nDone! Run: mlx run stop && mlx ls")