torchlit-lib 0.2.0__tar.gz

torchlit_lib-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chan Lee
+
+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.

torchlit_lib-0.2.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: torchlit-lib
+Version: 0.2.0
+Summary: A lightweight real-time ML training monitor.
+Author: ChanLumerico
+Project-URL: Homepage, https://github.com/ChanLumerico/torchlit
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: psutil
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.20.0
+Requires-Dist: websockets>=10.4
+Requires-Dist: pydantic>=2.0.0
+Dynamic: license-file
+
+# torchlit 🔥
+
+<p align="center">
+  <b>A lightweight, beautiful, and interactive real-time PyTorch training dashboard.</b>
+</p>
+
+<p align="center">
+  <img src="assets/dashboard.png" alt="torchlit Dashboard" width="80%" />
+</p>
+
+---
+
+`torchlit` is a zero-setup desktop GUI that hooks directly into your PyTorch training loops to monitor metrics, system stats, and model architecture in real time. Stop relying on cluttered TQDM bars or heavy logging frameworks.
+
+## ✨ Features
+
+- **Zero Configuration** — `with torchlit.Monitor():` and your dashboard spins up instantly
+- **Real-Time Streaming** — FastAPI + WebSockets push metrics to the browser immediately
+- **Model Architecture Explorer** — Interactive, color-coded layer tree with parameter counts
+- **Multi-Session Comparison** — Overlay and compare multiple experiments side-by-side
+- **Rust CLI Progress Display** — Beautiful terminal TUI (powered by `ratatui`) while training runs
+- **System Resource Sparklines** — Live CPU, RAM, and VRAM usage tracking
+- **CSV Export** — Download all aggregated metrics at any time
+- **Auto-Shutdown** — Background server cleans up automatically when the browser is closed
+
+## 🚀 Quick Start
+
+```bash
+pip install torchlit
+```
+
+```python
+import torch
+import torchlit
+
+model = torch.nn.Sequential(
+    torch.nn.Linear(10, 50),
+    torch.nn.ReLU(),
+    torch.nn.Linear(50, 2)
+)
+
+with torchlit.Monitor(exp_name="my_experiment", model=model, total_steps=100) as logger:
+    for step in range(1, 101):
+        loss = max(0, 1.0 - step * 0.01)
+        logger.log({"loss": loss, "accuracy": step / 100.0}, step=step)
+```
+
+*Your browser opens automatically at `http://localhost:8000`.*  
+*A live Rust-powered TUI also appears directly in your terminal.*
+
+## 📖 Full Example
+
+See [`examples/example.py`](examples/example.py) for a complete CIFAR-10 + ResNet-50 training loop demonstrating all features.
+
+```bash
+python examples/example.py
+```
+
+## ⚙️ Monitor Options
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `exp_name` | `str` | `"default_experiment"` | Name for this training run |
+| `model` | `nn.Module` | `None` | PyTorch model (for architecture extraction) |
+| `total_steps` | `int` | `None` | Total steps (enables ETA in CLI display) |
+| `server_url` | `str` | `http://localhost:8000` | Dashboard server URL |
+| `flush_interval` | `float` | `1.0` | Seconds between network flushes |
+
+## 🏗️ Architecture
+
+```
+torchlit.Monitor  ──►  FastAPI Backend  ──►  React Dashboard (browser)
+      │                                             │
+      └──►  Rust CLI (torchlit-progress)            └──►  WebSocket streaming
+```
+
+## 📦 Platform Support
+
+`pip install torchlit` includes pre-compiled CLI binaries for all major platforms:
+
+| Platform | Binary |
+|---|---|
+| macOS ARM (M1/M2/M3) | ✅ Included |
+| macOS Intel | ✅ Included |
+| Linux x86_64 | ✅ Included |
+| Windows x64 | ✅ Included |
+
+## 🔗 Links
+
+- [GitHub](https://github.com/ChanLumerico/torchlit)
+- [PyPI](https://pypi.org/project/torchlit/)

torchlit_lib-0.2.0/README.md

@@ -0,0 +1,91 @@
+# torchlit 🔥
+
+<p align="center">
+  <b>A lightweight, beautiful, and interactive real-time PyTorch training dashboard.</b>
+</p>
+
+<p align="center">
+  <img src="assets/dashboard.png" alt="torchlit Dashboard" width="80%" />
+</p>
+
+---
+
+`torchlit` is a zero-setup desktop GUI that hooks directly into your PyTorch training loops to monitor metrics, system stats, and model architecture in real time. Stop relying on cluttered TQDM bars or heavy logging frameworks.
+
+## ✨ Features
+
+- **Zero Configuration** — `with torchlit.Monitor():` and your dashboard spins up instantly
+- **Real-Time Streaming** — FastAPI + WebSockets push metrics to the browser immediately
+- **Model Architecture Explorer** — Interactive, color-coded layer tree with parameter counts
+- **Multi-Session Comparison** — Overlay and compare multiple experiments side-by-side
+- **Rust CLI Progress Display** — Beautiful terminal TUI (powered by `ratatui`) while training runs
+- **System Resource Sparklines** — Live CPU, RAM, and VRAM usage tracking
+- **CSV Export** — Download all aggregated metrics at any time
+- **Auto-Shutdown** — Background server cleans up automatically when the browser is closed
+
+## 🚀 Quick Start
+
+```bash
+pip install torchlit
+```
+
+```python
+import torch
+import torchlit
+
+model = torch.nn.Sequential(
+    torch.nn.Linear(10, 50),
+    torch.nn.ReLU(),
+    torch.nn.Linear(50, 2)
+)
+
+with torchlit.Monitor(exp_name="my_experiment", model=model, total_steps=100) as logger:
+    for step in range(1, 101):
+        loss = max(0, 1.0 - step * 0.01)
+        logger.log({"loss": loss, "accuracy": step / 100.0}, step=step)
+```
+
+*Your browser opens automatically at `http://localhost:8000`.*  
+*A live Rust-powered TUI also appears directly in your terminal.*
+
+## 📖 Full Example
+
+See [`examples/example.py`](examples/example.py) for a complete CIFAR-10 + ResNet-50 training loop demonstrating all features.
+
+```bash
+python examples/example.py
+```
+
+## ⚙️ Monitor Options
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `exp_name` | `str` | `"default_experiment"` | Name for this training run |
+| `model` | `nn.Module` | `None` | PyTorch model (for architecture extraction) |
+| `total_steps` | `int` | `None` | Total steps (enables ETA in CLI display) |
+| `server_url` | `str` | `http://localhost:8000` | Dashboard server URL |
+| `flush_interval` | `float` | `1.0` | Seconds between network flushes |
+
+## 🏗️ Architecture
+
+```
+torchlit.Monitor  ──►  FastAPI Backend  ──►  React Dashboard (browser)
+      │                                             │
+      └──►  Rust CLI (torchlit-progress)            └──►  WebSocket streaming
+```
+
+## 📦 Platform Support
+
+`pip install torchlit` includes pre-compiled CLI binaries for all major platforms:
+
+| Platform | Binary |
+|---|---|
+| macOS ARM (M1/M2/M3) | ✅ Included |
+| macOS Intel | ✅ Included |
+| Linux x86_64 | ✅ Included |
+| Windows x64 | ✅ Included |
+
+## 🔗 Links
+
+- [GitHub](https://github.com/ChanLumerico/torchlit)
+- [PyPI](https://pypi.org/project/torchlit/)

torchlit_lib-0.2.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "torchlit-lib"
+version = "0.2.0"
+description = "A lightweight real-time ML training monitor."
+readme = "README.md"
+authors = [
+    { name="ChanLumerico" }
+]
+requires-python = ">=3.8"
+dependencies = [
+    "requests",
+    "psutil",
+    "fastapi>=0.100.0",
+    "uvicorn>=0.20.0",
+    "websockets>=10.4",
+    "pydantic>=2.0.0",
+]
+
+[tool.setuptools]
+packages = ["torchlit", "torchlit.backend", "torchlit.frontend", "torchlit.bin"]
+
+[tool.setuptools.package-data]
+"torchlit.frontend" = ["dist/**/*"]
+"torchlit.bin" = ["torchlit-progress-*"]
+
+[project.urls]
+Homepage = "https://github.com/ChanLumerico/torchlit"

torchlit_lib-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

torchlit_lib-0.2.0/torchlit/__init__.py

@@ -0,0 +1,3 @@
+from .monitor import Monitor
+
+__all__ = ["Monitor"]

torchlit_lib-0.2.0/torchlit/backend/__init__.py

@@ -0,0 +1 @@
+# Empty init to make it a package

torchlit_lib-0.2.0/torchlit/backend/main.py

@@ -0,0 +1,203 @@
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+from typing import Dict, List, Any
+import asyncio
+import os
+import signal
+from collections import defaultdict, deque
+
+app = FastAPI(title="torchlit broker")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["http://localhost:5173"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# In-memory storage for metrics. structure:
+# {
+#    "experiment_name": deque([metric_dict, metric_dict, ...], maxlen=1000)
+# }
+experiment_metrics: Dict[str, deque] = defaultdict(lambda: deque(maxlen=1000))
+
+# {
+#    "experiment_name": [websocket1, websocket2, ...]
+# }
+active_connections: Dict[str, List[WebSocket]] = defaultdict(list)
+
+# Auto-shutdown state
+training_finished = False
+
+
+async def delayed_shutdown(delay: int = 2):
+    """Wait for delay, then shut down if conditions are still met."""
+    await asyncio.sleep(delay)
+    total_connections = sum(len(conns) for conns in active_connections.values())
+    if training_finished and total_connections == 0:
+        print(
+            "\n⚡ torchlit dashboard auto-shutting down because there are no active connections."
+        )
+        # Force terminate from a separate thread to bypass uvicorn's signal interception
+        import threading
+
+        threading.Thread(target=lambda: os._exit(0), daemon=True).start()
+
+
+class MetricLog(BaseModel):
+    exp_name: str
+    step: int
+    metrics: Dict[str, Any]
+    sys_stats: Dict[str, Any]
+    model_info: Dict[str, Any] = None
+
+
+class StatusLog(BaseModel):
+    status: str
+
+
+@app.post("/api/status")
+async def update_status(status_log: StatusLog):
+    """Receive status updates. Auto-shutdown if training finished and no one is watching."""
+    global training_finished
+    if status_log.status == "finished":
+        training_finished = True
+        total_connections = sum(len(conns) for conns in active_connections.values())
+        if total_connections == 0:
+            # Give user 10 seconds to open browser if they haven't yet
+            asyncio.create_task(delayed_shutdown(delay=10))
+    return {"status": "ok"}
+
+
+@app.post("/api/log")
+async def log_metrics(log_data: MetricLog):
+    """
+    Receive metrics from the torchlit python client and broadcast to connected frontends.
+    """
+    exp_name = log_data.exp_name
+    data_point = log_data.dict()
+
+    # Store in memory cache
+    experiment_metrics[exp_name].append(data_point)
+
+    # Broadcast to connected clients for this experiment
+    if exp_name in active_connections:
+        dead_connections = []
+        for connection in active_connections[exp_name]:
+            try:
+                await connection.send_json(data_point)
+            except Exception:
+                dead_connections.append(connection)
+
+        # Cleanup dead connections
+        for dead in dead_connections:
+            active_connections[exp_name].remove(dead)
+
+    return {"status": "ok"}
+
+
+@app.websocket("/ws/stream/{exp_name}")
+async def websocket_endpoint(websocket: WebSocket, exp_name: str):
+    """
+    WebSocket endpoint for frontend to receive live real-time metrics for a specific experiment.
+    On connection, rehydrate with the last N cached metrics.
+    """
+    await websocket.accept()
+    active_connections[exp_name].append(websocket)
+
+    try:
+        # Rehydrate existing data
+        if exp_name in experiment_metrics and len(experiment_metrics[exp_name]) > 0:
+            # Send all historical metrics
+            for data_point in list(experiment_metrics[exp_name]):
+                await websocket.send_json(data_point)
+
+        # Keep connection alive
+        while True:
+            # Wait for any messages from client (e.g. ping)
+            await websocket.receive_text()
+
+    except WebSocketDisconnect:
+        active_connections[exp_name].remove(websocket)
+        if not active_connections[exp_name]:
+            del active_connections[exp_name]
+
+        # Trigger auto-shutdown check if training is done
+        total_connections = sum(len(conns) for conns in active_connections.values())
+        if training_finished and total_connections == 0:
+            asyncio.create_task(delayed_shutdown(delay=2))
+
+
+@app.get("/api/experiments")
+async def list_experiments():
+    """List all active experiments"""
+    return {"experiments": list(experiment_metrics.keys())}
+
+
+@app.post("/api/experiments/clear")
+async def clear_all_experiments():
+    """Clear all experiment data and drop connections."""
+    try:
+        # Close all websocket connections
+        for exp_name in list(active_connections.keys()):
+            for ws in list(active_connections[exp_name]):
+                try:
+                    await ws.close()
+                except Exception:
+                    pass
+
+        # Clear in-memory datastores
+        experiment_metrics.clear()
+        active_connections.clear()
+
+        return {"status": "success"}
+    except Exception as e:
+        import traceback
+
+        traceback.print_exc()
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.delete("/api/experiments/{exp_name}")
+async def delete_experiment(exp_name: str):
+    """Delete all data for a specific experiment and close its connections"""
+    if exp_name in experiment_metrics:
+        del experiment_metrics[exp_name]
+
+    # Send close signal to connected clients
+    if exp_name in active_connections:
+        for ws in list(active_connections[exp_name]):
+            try:
+                await ws.close()
+            except Exception:
+                pass
+        del active_connections[exp_name]
+
+    return {"status": "ok", "deleted": exp_name}
+
+
+# --- Serve Frontend SPA ---
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+FRONTEND_DIST = os.path.join(BASE_DIR, "..", "frontend", "dist")
+FRONTEND_ASSETS = os.path.join(FRONTEND_DIST, "assets")
+
+if os.path.exists(FRONTEND_ASSETS):
+    app.mount("/assets", StaticFiles(directory=FRONTEND_ASSETS), name="assets")
+
+
+@app.get("/{full_path:path}")
+async def serve_frontend(full_path: str):
+    """Fallback route to serve the React SPA index.html for all non-API paths."""
+    # Check if we have the built frontend
+    index_path = os.path.join(FRONTEND_DIST, "index.html")
+    if os.path.exists(index_path):
+        # We explicitly serve index.html and let React handle the client-side routing
+        return FileResponse(index_path)
+
+    return {
+        "error": "Frontend build not found. Run 'npm run build' inside torchlit/frontend"
+    }

torchlit_lib-0.2.0/torchlit/monitor.py

@@ -0,0 +1,377 @@
+import contextlib
+import json
+import os
+import platform
+import subprocess
+import threading
+import time
+import requests
+import queue
+import psutil
+import socket
+import sys
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+
+def _get_bin_path() -> Path:
+    """Return the path to the platform-specific torchlit-progress binary."""
+    system = platform.system()  # Darwin, Linux, Windows
+    machine = platform.machine()  # arm64, x86_64, AMD64
+
+    if system == "Darwin":
+        suffix = f"darwin-{machine}"  # darwin-arm64 | darwin-x86_64
+    elif system == "Linux":
+        suffix = f"linux-{machine}"  # linux-x86_64 | linux-aarch64
+    elif system == "Windows":
+        suffix = f"windows-x86_64.exe"  # windows-x86_64.exe
+    else:
+        suffix = None
+
+    if suffix is None:
+        return Path()  # Empty path — will not exist, falls back gracefully
+
+    return Path(__file__).parent / "bin" / f"torchlit-progress-{suffix}"
+
+
+_BIN_PATH = _get_bin_path()
+
+
+class Monitor(contextlib.ContextDecorator):
+    """
+    Context manager and decorator for monitoring PyTorch training loops.
+    Sends real-time telemetry to the local torchlit visualization server.
+    Launches a Rust-based CLI display (torchlit-progress) for terminal progress.
+    Falls back to plain text if the binary is not available.
+    """
+
+    def __init__(
+        self,
+        exp_name: str = "default_experiment",
+        server_url: str | None = None,
+        flush_interval: float = 1.0,
+        model_info: Dict[str, Any] = None,
+        model: Optional[Any] = None,
+        optimizer: Optional[Any] = None,
+        start_server: bool = True,
+        total_steps: Optional[int] = None,
+    ):
+        self.exp_name = exp_name
+        self.server_url = (
+            server_url.rstrip("/") if server_url else "http://localhost:8000"
+        )
+        self.flush_interval = flush_interval
+        self.model_info = model_info or {}
+        self.model = model
+        self.optimizer = optimizer
+        self.start_server = start_server
+        self.total_steps = total_steps
+
+        self.queue = queue.Queue()
+        self.is_running = False
+        self.worker_thread: Optional[threading.Thread] = None
+
+        # Hardware Detection (Cache once)
+        self.device_type = "cpu"
+        self.device_name = "CPU"
+        self._torch = None
+
+        try:
+            import torch
+
+            self._torch = torch
+            if torch.cuda.is_available():
+                self.device_type = "cuda"
+                self.device_name = torch.cuda.get_device_name(0)
+            elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+                self.device_type = "mps"
+                self.device_name = "Apple Silicon (MPS)"
+        except Exception:
+            pass
+
+        # Auto-extract model info if provided
+        if self.model is not None:
+            self._extract_model_info()
+
+        # Rust CLI display state
+        self._cli_proc: Optional[subprocess.Popen] = None
+        self._start_time: Optional[float] = None
+
+    def _format_num(self, num: int) -> str:
+        if num >= 1e9:
+            return f"{num / 1e9:.1f} B"
+        elif num >= 1e6:
+            return f"{num / 1e6:.1f} M"
+        elif num >= 1e3:
+            return f"{num / 1e3:.1f} K"
+        return str(num)
+
+    def _extract_model_info(self):
+        try:
+            self.model_info["name"] = self.model_info.get(
+                "name", self.model.__class__.__name__
+            )
+
+            # Count parameters
+            total_params = sum(p.numel() for p in self.model.parameters())
+            trainable_params = sum(
+                p.numel() for p in self.model.parameters() if p.requires_grad
+            )
+
+            self.model_info["total_params"] = self.model_info.get(
+                "total_params", self._format_num(total_params)
+            )
+            self.model_info["trainable_params"] = self.model_info.get(
+                "trainable_params", self._format_num(trainable_params)
+            )
+
+            # Try to infer device from first parameter
+            first_param = next(self.model.parameters(), None)
+            if first_param is not None and hasattr(first_param, "device"):
+                dev_type = first_param.device.type
+                if dev_type == "cuda":
+                    self.device_type = "cuda"
+                    if self._torch and self._torch.cuda.is_available():
+                        self.device_name = self._torch.cuda.get_device_name(
+                            first_param.device.index or 0
+                        )
+                elif dev_type == "mps":
+                    self.device_type = "mps"
+                    self.device_name = "Apple Silicon (MPS)"
+                elif dev_type == "cpu":
+                    self.device_type = "cpu"
+                    self.device_name = "CPU"
+
+            # Extract architecture tree
+            def _get_module_tree(module, name="Root"):
+                children = list(module.named_children())
+                node_params = sum(p.numel() for p in module.parameters(recurse=False))
+                total_node_params = sum(p.numel() for p in module.parameters())
+
+                node = {
+                    "name": name,
+                    "class_name": module.__class__.__name__,
+                    "params": node_params,
+                    "total_params": total_node_params,
+                    "children": [],
+                }
+
+                for child_name, child_module in children:
+                    node["children"].append(_get_module_tree(child_module, child_name))
+
+                return node
+
+            self.model_info["architecture"] = _get_module_tree(self.model)
+
+        except Exception:
+            pass
+
+    def _start_server_if_needed(self):
+        """Checks if port 8000 is open. If not, spawns the FastAPI server as a detached daemon."""
+        try:
+            from urllib.parse import urlparse
+
+            port = urlparse(self.server_url).port or 8000
+            host = urlparse(self.server_url).hostname or "localhost"
+
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.settimeout(0.1)
+                if s.connect_ex((host, port)) != 0:
+                    print(
+                        f"⚡ torchlit catching up! Spawning dashboard background server at {self.server_url}..."
+                    )
+                    subprocess.Popen(
+                        [
+                            sys.executable,
+                            "-m",
+                            "uvicorn",
+                            "torchlit.backend.main:app",
+                            "--port",
+                            str(port),
+                            "--log-level",
+                            "error",
+                            "--no-access-log",
+                        ],
+                        stdout=subprocess.DEVNULL,
+                        stderr=subprocess.DEVNULL,
+                        start_new_session=True,
+                    )
+                    time.sleep(1.5)
+        except Exception as e:
+            print(f"⚠️ torchlit could not start background server: {e}")
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Rust CLI Display
+    # ─────────────────────────────────────────────────────────────────────────
+
+    def _write_cli(self, msg: dict) -> None:
+        """Write a JSON message line to the Rust CLI process stdin."""
+        if self._cli_proc is not None and self._cli_proc.poll() is None:
+            try:
+                line = json.dumps(msg) + "\n"
+                self._cli_proc.stdin.write(line.encode())
+                self._cli_proc.stdin.flush()
+            except (BrokenPipeError, OSError):
+                self._cli_proc = None
+
+    def _start_cli(self) -> None:
+        """Spawn the Rust CLI binary as a subprocess."""
+        if not _BIN_PATH.exists():
+            return  # Binary not compiled yet — skip silently
+
+        try:
+            self._cli_proc = subprocess.Popen(
+                [str(_BIN_PATH)],
+                stdin=subprocess.PIPE,
+                stdout=None,  # inherit terminal
+                stderr=subprocess.DEVNULL,
+            )
+            # Give Rust process a moment to initialize before writing
+            time.sleep(0.15)
+            # Send init message
+            self._write_cli(
+                {
+                    "type": "init",
+                    "exp_name": self.exp_name,
+                    "model_name": self.model_info.get("name"),
+                    "total_params": self.model_info.get("total_params"),
+                    "trainable_params": self.model_info.get("trainable_params"),
+                    "device": self.device_name,
+                    "total_steps": self.total_steps,
+                }
+            )
+        except Exception:
+            self._cli_proc = None
+
+    def _stop_cli(self, final_step: int = 0) -> None:
+        """Send done message and wait for the Rust CLI to exit cleanly."""
+        if self._cli_proc is None:
+            return
+        try:
+            self._write_cli({"type": "done", "step": final_step})
+            self._cli_proc.stdin.close()
+            self._cli_proc.wait(timeout=5)
+        except Exception:
+            try:
+                self._cli_proc.terminate()
+            except Exception:
+                pass
+        self._cli_proc = None
+
+    # ─────────────────────────────────────────────────────────────────────────
+
+    def __enter__(self):
+        if self.start_server:
+            self._start_server_if_needed()
+
+        self._start_time = time.time()
+        self.is_running = True
+        self.worker_thread = threading.Thread(target=self._worker_loop, daemon=True)
+        self.worker_thread.start()
+
+        self._start_cli()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.is_running = False
+        if self.worker_thread is not None:
+            self.worker_thread.join(timeout=2.0)
+
+        # Flush remaining queued items
+        self._flush_queue()
+
+        self._stop_cli(final_step=self._last_step)
+
+        if self.start_server:
+            try:
+                requests.post(
+                    f"{self.server_url}/api/status",
+                    json={"status": "finished"},
+                    timeout=1.0,
+                )
+                print(
+                    f"⚡ torchlit training complete! Dashboard stays active at {self.server_url}"
+                )
+                print(
+                    "   (It will automatically shut down when you close the browser window)"
+                )
+            except requests.RequestException:
+                pass
+
+        return False
+
+    _last_step: int = 0
+
+    def log(self, metrics: Dict[str, Any], step: int):
+        """Queue metrics for the server and push to the Rust CLI display."""
+        self._last_step = step
+        elapsed = time.time() - self._start_time if self._start_time else 0.0
+
+        self.queue.put({"step": step, "metrics": metrics})
+
+        # Push to Rust TUI
+        self._write_cli(
+            {
+                "type": "step",
+                "step": step,
+                "metrics": metrics,
+                "elapsed": elapsed,
+            }
+        )
+
+    def _get_system_stats(self) -> Dict[str, Any]:
+        """Collect system usage metrics"""
+        stats = {
+            "cpu_percent": psutil.cpu_percent(interval=None),
+            "ram_percent": psutil.virtual_memory().percent,
+            "device_type": self.device_type,
+            "device_name": self.device_name,
+            "vram_percent": None,
+        }
+
+        if self._torch is not None:
+            try:
+                if self.device_type == "cuda":
+                    mem_alloc = self._torch.cuda.memory_allocated(0)
+                    mem_total = self._torch.cuda.get_device_properties(0).total_memory
+                    if mem_total > 0:
+                        stats["vram_percent"] = (mem_alloc / mem_total) * 100
+                elif self.device_type == "mps":
+                    alloc = self._torch.mps.current_allocated_memory()
+                    total = psutil.virtual_memory().total
+                    stats["vram_percent"] = (alloc / total) * 100
+            except Exception:
+                pass
+
+        return stats
+
+    def _worker_loop(self):
+        """Background thread loop to send data"""
+        while self.is_running:
+            self._flush_queue()
+            time.sleep(self.flush_interval)
+
+    def _flush_queue(self):
+        """Send all items currently in the queue"""
+        while not self.queue.empty():
+            try:
+                item = self.queue.get_nowait()
+                self._send_data(int(item["step"]), dict(item["metrics"]))
+                self.queue.task_done()
+            except queue.Empty:
+                break
+
+    def _send_data(self, step: int, metrics: Dict[str, Any]):
+        """Perform the actual HTTP POST request"""
+        payload = {
+            "exp_name": self.exp_name,
+            "step": step,
+            "metrics": metrics,
+            "sys_stats": self._get_system_stats(),
+            "model_info": self.model_info if step == 1 else {},
+        }
+
+        try:
+            requests.post(f"{self.server_url}/api/log", json=payload, timeout=1.0)
+        except requests.RequestException:
+            pass

torchlit_lib-0.2.0/torchlit_lib.egg-info/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: torchlit-lib
+Version: 0.2.0
+Summary: A lightweight real-time ML training monitor.
+Author: ChanLumerico
+Project-URL: Homepage, https://github.com/ChanLumerico/torchlit
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: psutil
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.20.0
+Requires-Dist: websockets>=10.4
+Requires-Dist: pydantic>=2.0.0
+Dynamic: license-file
+
+# torchlit 🔥
+
+<p align="center">
+  <b>A lightweight, beautiful, and interactive real-time PyTorch training dashboard.</b>
+</p>
+
+<p align="center">
+  <img src="assets/dashboard.png" alt="torchlit Dashboard" width="80%" />
+</p>
+
+---
+
+`torchlit` is a zero-setup desktop GUI that hooks directly into your PyTorch training loops to monitor metrics, system stats, and model architecture in real time. Stop relying on cluttered TQDM bars or heavy logging frameworks.
+
+## ✨ Features
+
+- **Zero Configuration** — `with torchlit.Monitor():` and your dashboard spins up instantly
+- **Real-Time Streaming** — FastAPI + WebSockets push metrics to the browser immediately
+- **Model Architecture Explorer** — Interactive, color-coded layer tree with parameter counts
+- **Multi-Session Comparison** — Overlay and compare multiple experiments side-by-side
+- **Rust CLI Progress Display** — Beautiful terminal TUI (powered by `ratatui`) while training runs
+- **System Resource Sparklines** — Live CPU, RAM, and VRAM usage tracking
+- **CSV Export** — Download all aggregated metrics at any time
+- **Auto-Shutdown** — Background server cleans up automatically when the browser is closed
+
+## 🚀 Quick Start
+
+```bash
+pip install torchlit
+```
+
+```python
+import torch
+import torchlit
+
+model = torch.nn.Sequential(
+    torch.nn.Linear(10, 50),
+    torch.nn.ReLU(),
+    torch.nn.Linear(50, 2)
+)
+
+with torchlit.Monitor(exp_name="my_experiment", model=model, total_steps=100) as logger:
+    for step in range(1, 101):
+        loss = max(0, 1.0 - step * 0.01)
+        logger.log({"loss": loss, "accuracy": step / 100.0}, step=step)
+```
+
+*Your browser opens automatically at `http://localhost:8000`.*  
+*A live Rust-powered TUI also appears directly in your terminal.*
+
+## 📖 Full Example
+
+See [`examples/example.py`](examples/example.py) for a complete CIFAR-10 + ResNet-50 training loop demonstrating all features.
+
+```bash
+python examples/example.py
+```
+
+## ⚙️ Monitor Options
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `exp_name` | `str` | `"default_experiment"` | Name for this training run |
+| `model` | `nn.Module` | `None` | PyTorch model (for architecture extraction) |
+| `total_steps` | `int` | `None` | Total steps (enables ETA in CLI display) |
+| `server_url` | `str` | `http://localhost:8000` | Dashboard server URL |
+| `flush_interval` | `float` | `1.0` | Seconds between network flushes |
+
+## 🏗️ Architecture
+
+```
+torchlit.Monitor  ──►  FastAPI Backend  ──►  React Dashboard (browser)
+      │                                             │
+      └──►  Rust CLI (torchlit-progress)            └──►  WebSocket streaming
+```
+
+## 📦 Platform Support
+
+`pip install torchlit` includes pre-compiled CLI binaries for all major platforms:
+
+| Platform | Binary |
+|---|---|
+| macOS ARM (M1/M2/M3) | ✅ Included |
+| macOS Intel | ✅ Included |
+| Linux x86_64 | ✅ Included |
+| Windows x64 | ✅ Included |
+
+## 🔗 Links
+
+- [GitHub](https://github.com/ChanLumerico/torchlit)
+- [PyPI](https://pypi.org/project/torchlit/)

torchlit_lib-0.2.0/torchlit_lib.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+torchlit/__init__.py
+torchlit/monitor.py
+torchlit/backend/__init__.py
+torchlit/backend/main.py
+torchlit/bin/__init__.py
+torchlit/bin/torchlit-progress-darwin-arm64
+torchlit/bin/torchlit-progress-darwin-x86_64
+torchlit/bin/torchlit-progress-linux-x86_64
+torchlit/bin/torchlit-progress-windows-x86_64.exe
+torchlit/frontend/__init__.py
+torchlit_lib.egg-info/PKG-INFO
+torchlit_lib.egg-info/SOURCES.txt
+torchlit_lib.egg-info/dependency_links.txt
+torchlit_lib.egg-info/requires.txt
+torchlit_lib.egg-info/top_level.txt

torchlit_lib-0.2.0/torchlit_lib.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

torchlit_lib-0.2.0/torchlit_lib.egg-info/requires.txt

@@ -0,0 +1,6 @@
+requests
+psutil
+fastapi>=0.100.0
+uvicorn>=0.20.0
+websockets>=10.4
+pydantic>=2.0.0

torchlit_lib-0.2.0/torchlit_lib.egg-info/top_level.txt

@@ -0,0 +1 @@
+torchlit