gradia 1.0.0__tar.gz

gradia-1.0.0/LICENSE

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

gradia-1.0.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include README.md
+include LICENSE
+recursive-include gradia/viz/templates *
+recursive-include gradia/viz/static *
+recursive-include gradia/viz/assets *
+global-exclude .gradia
+global-exclude .gradia_logs
+global-exclude *.pyc
+global-exclude __pycache__
+global-exclude *.DS_Store

gradia-1.0.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: gradia
+Version: 1.0.0
+Summary: Local-first ML training visualization and tracking dashboard.
+Author-email: STiFLeR <stifler@example.com>
+License: MIT License
+        
+        Copyright (c) 2025 STiFLeR
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/STiFLeR7/gradia
+Project-URL: Bug Tracker, https://github.com/STiFLeR7/gradia/issues
+Keywords: machine-learning,dashboard,visualization,tracking,mlops
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scikit-learn
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: fastapi
+Requires-Dist: uvicorn
+Requires-Dist: typer
+Requires-Dist: jinja2
+Requires-Dist: watchdog
+Requires-Dist: rich
+Requires-Dist: psutil
+Requires-Dist: tqdm
+Dynamic: license-file
+
+<div align="center">
+
+# G R A D I A
+
+**Next-Generation Local-First MLOps Platform**
+
+[![PyPI Version](https://img.shields.io/pypi/v/gradia?style=for-the-badge&color=blue)](https://pypi.org/project/gradia/)
+[![Python Version](https://img.shields.io/badge/Python-3.9%2B-blue?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
+[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/STiFLeR7/gradia/ci-update.yaml?style=for-the-badge)](https://github.com/STiFLeR7/gradia/actions)
+
+<p align="center">
+  <img src="https://github.com/STiFLeR7/gradia/blob/master/docs/dashboard.png" alt="Gradia Dashboard" width="100%" />
+</p>
+
+</div>
+
+---
+
+## 🚀 Overview
+
+**Gradia** is a high-performance, asynchronous monitoring solution designed for local machine learning workflows. Unlike cloud-native behemoths, Gradia focuses on **zero-latency**, **privacy-first** tracking that runs directly alongside your training loop.
+
+Built on **FastAPI**, **WebSockets** (simulated via high-frequency polling), and **Reactive UI**, Gradia provides granular visibility into your model's training dynamics, system resource consumption, and feature importance without the overhead of external servers.
+
+## ⚡ Key Capabilities
+
+| Feature | Description |
+| :--- | :--- |
+| **Real-Time Telemetry** | Nanosecond-precision tracking of Loss, Accuracy, and custom metrics via async event dispatching. |
+| **Intelligent Auto-Discovery** | Heuristic analysis of tabular datasets to automatically infer task types (Regression vs Classification) and suggest optimal architectures (CNNs, RFCs). |
+| **System Profiling** | Integrated `psutil` hooks for monitoring CPU/GPU* and RAM saturation during training epochs. |
+| **Artifact Management** | Automated checkpointing (`best-ckpt`) and structured logging (`events.jsonl`) with thread-safe IO. |
+| **Comprehensive Reporting** | One-click generation of audit-ready PDF/JSON reports containing full training history and confusion matrices. |
+| **Interactive Evaluation** | Post-training validation suite featuring dynamic Heatmap visualization for Confusion Matrices. |
+
+## 🛠️ Architecture
+
+Gradia employs a **Producer-Consumer** architecture:
+
+1.  **Trainer Thread (Producer)**: Executes the Scikit-Learn training loop, emitting atomic events to a thread-locked `EventLogger`.
+2.  **System Thread**: Asynchronously samples hardware metrics.
+3.  **Visualization Server (Consumer)**: A lightweight FastAPI instance that aggregates logs and serves a reactive Single Page Application (SPA).
+
+This decoupling ensures that monitoring never bottlenecks your training throughput.
+
+## 📦 Installation
+
+```bash
+pip install gradia --upgrade
+```
+
+## 💻 Usage
+
+### Quick Start
+Initialize the environment and start the observer in one command. Gradia will auto-detect any CSV files in the directory.
+
+```bash
+gradia run .
+```
+
+### Advanced CLI
+Override default heuristics and bind to specific interfaces.
+
+```bash
+gradia run . \
+  --target "churn_label" \
+  --port 8080 \
+  --workers 4
+```
+
+## 📊 Dashboard
+
+Access the dashboard at `http://localhost:8000`.
+
+-   **Configure**: Select your model (Random Forest, MLP, etc.) and hyperparameters.
+-   **Observe**: Watch metrics stream in real-time.
+-   **Analyze**: Use the built-in Feature Importance charts to debug model bias.
+
+## 🤝 Contributing
+
+We welcome contributions! Please see `CONTRIBUTING.md` for details on submitting logical PRs.
+
+## 📄 License
+
+Distributed under the MIT License. See `LICENSE` for more information.
+
+---
+
+<div align="center">
+  <sub>Built with ❤️ by STiFLeR for the ML Community.</sub>
+</div>

gradia-1.0.0/README.md

@@ -0,0 +1,92 @@
+<div align="center">
+
+# G R A D I A
+
+**Next-Generation Local-First MLOps Platform**
+
+[![PyPI Version](https://img.shields.io/pypi/v/gradia?style=for-the-badge&color=blue)](https://pypi.org/project/gradia/)
+[![Python Version](https://img.shields.io/badge/Python-3.9%2B-blue?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
+[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/STiFLeR7/gradia/ci-update.yaml?style=for-the-badge)](https://github.com/STiFLeR7/gradia/actions)
+
+<p align="center">
+  <img src="https://github.com/STiFLeR7/gradia/blob/master/docs/dashboard.png" alt="Gradia Dashboard" width="100%" />
+</p>
+
+</div>
+
+---
+
+## 🚀 Overview
+
+**Gradia** is a high-performance, asynchronous monitoring solution designed for local machine learning workflows. Unlike cloud-native behemoths, Gradia focuses on **zero-latency**, **privacy-first** tracking that runs directly alongside your training loop.
+
+Built on **FastAPI**, **WebSockets** (simulated via high-frequency polling), and **Reactive UI**, Gradia provides granular visibility into your model's training dynamics, system resource consumption, and feature importance without the overhead of external servers.
+
+## ⚡ Key Capabilities
+
+| Feature | Description |
+| :--- | :--- |
+| **Real-Time Telemetry** | Nanosecond-precision tracking of Loss, Accuracy, and custom metrics via async event dispatching. |
+| **Intelligent Auto-Discovery** | Heuristic analysis of tabular datasets to automatically infer task types (Regression vs Classification) and suggest optimal architectures (CNNs, RFCs). |
+| **System Profiling** | Integrated `psutil` hooks for monitoring CPU/GPU* and RAM saturation during training epochs. |
+| **Artifact Management** | Automated checkpointing (`best-ckpt`) and structured logging (`events.jsonl`) with thread-safe IO. |
+| **Comprehensive Reporting** | One-click generation of audit-ready PDF/JSON reports containing full training history and confusion matrices. |
+| **Interactive Evaluation** | Post-training validation suite featuring dynamic Heatmap visualization for Confusion Matrices. |
+
+## 🛠️ Architecture
+
+Gradia employs a **Producer-Consumer** architecture:
+
+1.  **Trainer Thread (Producer)**: Executes the Scikit-Learn training loop, emitting atomic events to a thread-locked `EventLogger`.
+2.  **System Thread**: Asynchronously samples hardware metrics.
+3.  **Visualization Server (Consumer)**: A lightweight FastAPI instance that aggregates logs and serves a reactive Single Page Application (SPA).
+
+This decoupling ensures that monitoring never bottlenecks your training throughput.
+
+## 📦 Installation
+
+```bash
+pip install gradia --upgrade
+```
+
+## 💻 Usage
+
+### Quick Start
+Initialize the environment and start the observer in one command. Gradia will auto-detect any CSV files in the directory.
+
+```bash
+gradia run .
+```
+
+### Advanced CLI
+Override default heuristics and bind to specific interfaces.
+
+```bash
+gradia run . \
+  --target "churn_label" \
+  --port 8080 \
+  --workers 4
+```
+
+## 📊 Dashboard
+
+Access the dashboard at `http://localhost:8000`.
+
+-   **Configure**: Select your model (Random Forest, MLP, etc.) and hyperparameters.
+-   **Observe**: Watch metrics stream in real-time.
+-   **Analyze**: Use the built-in Feature Importance charts to debug model bias.
+
+## 🤝 Contributing
+
+We welcome contributions! Please see `CONTRIBUTING.md` for details on submitting logical PRs.
+
+## 📄 License
+
+Distributed under the MIT License. See `LICENSE` for more information.
+
+---
+
+<div align="center">
+  <sub>Built with ❤️ by STiFLeR for the ML Community.</sub>
+</div>

gradia-1.0.0/gradia/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

gradia-1.0.0/gradia/cli/main.py

@@ -0,0 +1,91 @@
+import typer
+import threading
+import time
+import os
+import webbrowser
+from pathlib import Path
+from rich.console import Console
+from ..core.inspector import Inspector
+from ..core.scenario import ScenarioInferrer
+from ..core.config import ConfigManager
+from ..trainer.engine import Trainer
+from ..viz import server
+
+app = typer.Typer()
+console = Console()
+
+@app.callback()
+def callback():
+    """
+    gradia: Local-first ML training visualization.
+    """
+
+@app.command()
+def run(
+    ctx: typer.Context, 
+    path: str = typer.Argument(".", help="Path to data directory"),
+    target: str = typer.Option(None, help="Manually specify target column"),
+    port: int = typer.Option(8000, help="Port for visualization server")
+):
+    """
+    Starts the gradia training and visualization session.
+    """
+    console.rule("[bold blue]gradia v1.0.0[/bold blue]")
+    
+    # 1. Inspect
+    path = Path(path).resolve()
+    inspector = Inspector(path)
+    datasets = inspector.find_datasets()
+    
+    if not datasets:
+        console.print(f"[red]No .csv or .parquet files found in {path}[/red]")
+        raise typer.Exit(code=1)
+    
+    # Select first dataset for MVP
+    dataset = datasets[0]
+    console.print(f"[green]Found dataset:[/green] {dataset.name}")
+    
+    # 2. Config & Scenario Reuse
+    run_dir = path / ".gradia_logs"
+    config_mgr = ConfigManager(run_dir)
+    config = config_mgr.load_or_create()
+    
+    # We infer scenario here to pass to server, but user confirms/configures in UI
+    with console.status("Inferring scenario..."):
+        inferrer = ScenarioInferrer()
+        scenario = inferrer.infer(str(dataset), target_override=target)
+    
+    console.print(f"Target: [bold]{scenario.target_column}[/bold] | Task: [bold]{scenario.task_type}[/bold]")
+    # Session Isolation: Create unique run directory
+    session_id = int(time.time())
+    run_dir = Path(".gradia_logs") / f"run_{session_id}"
+    run_dir.mkdir(parents=True, exist_ok=True)
+
+    config_mgr = ConfigManager(run_dir)
+    config = config_mgr.load_or_create()
+    
+    # Apply Smart Recommendation
+    config['model']['type'] = scenario.recommended_model
+    console.print(f"[cyan]Smart Suggestion:[/cyan] Using [bold]{scenario.recommended_model}[/bold] for this dataset.")
+    
+    console.print(f"[bold green]Configuration moved to Web UI[/bold green]")
+    console.print(f"Visualization running at http://localhost:{port}")
+    console.print(f"Logs: {run_dir.resolve()}")
+    
+    # 3. Launch Server
+    # We inject state into the server module before starting it
+    server.SCENARIO = scenario
+    server.CONFIG_MGR = config_mgr
+    server.RUN_DIR = run_dir
+    server.DEFAULT_CONFIG = config
+    
+    
+    # Launch browser
+    threading.Timer(1.5, lambda: webbrowser.open(f"http://localhost:{port}/configure")).start()
+    
+    # Start server (blocking main thread is fine now as we don't have a separate training thread YET)
+    # The training thread will be spawned by the server upon API request.
+    server.start_server(str(run_dir), port)
+
+if __name__ == "__main__":
+    app()

gradia-1.0.0/gradia/core/config.py

@@ -0,0 +1,56 @@
+import yaml
+from pathlib import Path
+from typing import Any, Dict
+
+class ConfigManager:
+    """Manages gradia configuration."""
+    
+    DEFAULT_CONFIG = {
+        'model': {
+            'type': 'auto', # auto, linear, random_forest
+            'params': {}
+        },
+        'training': {
+            'test_split': 0.2,
+            'random_seed': 42,
+            'shuffle': True
+        },
+        'scenario': {
+            'target': None, # Auto-detect
+            'task': None # Auto-detect
+        }
+    }
+
+    def __init__(self, run_dir: str = ".gradia_logs"):
+        self.run_dir = Path(run_dir)
+        self.config_path = self.run_dir / "config.yaml"
+
+    def load_or_create(self, user_overrides: Dict[str, Any] = None) -> Dict[str, Any]:
+        config = self.DEFAULT_CONFIG.copy()
+        
+        # Load existing if any (feature for restart, maybe not for MVP run-once)
+        # For immutable runs, we usually generate NEW config.
+        # But if gradia.yaml exists in ROOT, we load it.
+        
+        root_config = Path("gradia.yaml")
+        if root_config.exists():
+            with open(root_config, 'r') as f:
+                user_config = yaml.safe_load(f)
+                self._update_recursive(config, user_config)
+
+        if user_overrides:
+            self._update_recursive(config, user_overrides)
+            
+        return config
+
+    def save(self, config: Dict[str, Any]):
+        self.run_dir.mkdir(exist_ok=True)
+        with open(self.config_path, 'w') as f:
+            yaml.dump(config, f)
+
+    def _update_recursive(self, base: Dict, update: Dict):
+        for k, v in update.items():
+            if k in base and isinstance(base[k], dict) and isinstance(v, dict):
+                self._update_recursive(base[k], v)
+            else:
+                base[k] = v

gradia-1.0.0/gradia/core/inspector.py

@@ -0,0 +1,37 @@
+import os
+from pathlib import Path
+from typing import List, Optional
+
+class Inspector:
+    """Scans the working directory for potential dataset files."""
+    
+    SUPPORTED_EXTENSIONS = {'.csv', '.parquet'}
+
+    def __init__(self, root_dir: str = "."):
+        self.root_dir = Path(root_dir)
+
+    def find_datasets(self) -> List[Path]:
+        """Finds all supported dataset files in the root directory."""
+        datasets = []
+        for ext in self.SUPPORTED_EXTENSIONS:
+            datasets.extend(self.root_dir.glob(f"*{ext}"))
+        return sorted(datasets)
+
+    def detect_split_layout(self):
+        """
+        Detects if proper 'train'/'val'/'test' folders exist.
+        Returns a dictionary with paths or None.
+        """
+        layout = {}
+        for split in ['train', 'val', 'validation', 'test']:
+            split_dir = self.root_dir / split
+            if split_dir.exists() and split_dir.is_dir():
+                # Check for files inside
+                files = []
+                for ext in self.SUPPORTED_EXTENSIONS:
+                    files.extend(list(split_dir.glob(f"*{ext}")))
+                
+                if files:
+                    layout[split] = split_dir
+        
+        return layout if layout else None

gradia-1.0.0/gradia/core/scenario.py

@@ -0,0 +1,118 @@
+import pandas as pd
+import numpy as np
+from dataclasses import dataclass, field
+from typing import Optional, List, Any
+
+@dataclass
+class Scenario:
+    dataset_path: str
+    target_column: str
+    task_type: str  # 'classification' or 'regression'
+    is_multiclass: bool = False
+    class_count: int = 0
+    features: List[str] = field(default_factory=list)
+    recommended_model: str = "random_forest"
+
+class ScenarioInferrer:
+    """Infers the ML scenario (Task type, Target) from a dataset."""
+
+    POSSIBLE_TARGET_NAMES = ['target', 'label', 'y', 'class', 'outcome', 'price', 'score']
+    
+    def infer(self, file_path: str, target_override: Optional[str] = None) -> Scenario:
+        # Load a sample to infer types
+        df = self._load_sample(file_path)
+        
+        target = target_override
+        if not target:
+            target = self._guess_target(df)
+            
+        if not target:
+            raise ValueError(f"Could not infer target column for {file_path}. Please name one of {self.POSSIBLE_TARGET_NAMES} or provide config.")
+            
+        task_type, is_multiclass, count = self._infer_task_type(df[target])
+        features = [c for c in df.columns if c != target]
+        
+        recommended_model = self._infer_model_recommendation(features)
+        
+        return Scenario(
+            dataset_path=str(file_path),
+            target_column=target,
+            task_type=task_type,
+            is_multiclass=is_multiclass,
+            class_count=count,
+            features=features,
+            recommended_model=recommended_model
+        )
+
+    def _infer_model_recommendation(self, features: List[str]) -> str:
+        # Heuristic 1: Check for pixel data (Fashion MNIST, MNIST, etc.)
+        # If > 100 features and names contain 'pixel'
+        if len(features) > 100:
+            pixel_cols = [f for f in features if 'pixel' in f.lower()]
+            if len(pixel_cols) > len(features) * 0.5:
+                return "cnn"
+                
+        # Heuristic 2: Tabular default
+        return "random_forest"
+
+    def _load_sample(self, path: str, n_rows: int = 1000) -> pd.DataFrame:
+        if path.endswith('.csv'):
+            return pd.read_csv(path, nrows=n_rows)
+        elif path.endswith('.parquet'):
+            # Parquet doesn't support 'nrows' efficiently same as csv sometimes, 
+            # but pandas read_parquet usually loads full. For large files we might need pyarrow.
+            # For MVP assume fits in memory or use logic to limits.
+            return pd.read_parquet(path).head(n_rows)
+        else:
+            raise ValueError("Unsupported format")
+
+    def _guess_target(self, df: pd.DataFrame) -> Optional[str]:
+        # 1. Exact Name match
+        for name in self.POSSIBLE_TARGET_NAMES:
+            if name in df.columns:
+                return name
+            if name.upper() in df.columns:
+                return name.upper()
+        
+        # 2. Heuristic: Avoid ID/Date columns
+        candidates = []
+        for col in df.columns:
+            lower = col.lower()
+            if not any(x in lower for x in ['id', 'date', 'time', 'created_at', 'uuid', 'index']):
+                candidates.append(col)
+        
+        if candidates:
+            return candidates[-1]
+            
+        # 3. Last column fallback
+        return df.columns[-1]
+
+    def _infer_task_type(self, series: pd.Series):
+        """
+        Returns (task_type, is_multiclass, class_count)
+        """
+        # Heuristics:
+        # If string/object -> Classification
+        # If float -> Regression (unless low cardinality?)
+        # If int -> Check cardinality. Low (<20) -> Classification. High -> Regression.
+        
+        unique_count = series.nunique()
+        dtype = series.dtype
+        
+        if pd.api.types.is_string_dtype(dtype) or pd.api.types.is_object_dtype(dtype):
+            return 'classification', unique_count > 2, unique_count
+            
+        if pd.api.types.is_float_dtype(dtype):
+            # If floats are actually integers (e.g. 1.0, 0.0), check that
+            if series.apply(float.is_integer).all() and unique_count < 20:
+                 return 'classification', unique_count > 2, unique_count
+            return 'regression', False, 0
+            
+        if pd.api.types.is_integer_dtype(dtype):
+            if unique_count < 20:  # Arbitrary threshold for MVP
+                return 'classification', unique_count > 2, unique_count
+            else:
+                return 'regression', False, 0
+                
+        # Fallback
+        return 'regression', False, 0

gradia-1.0.0/gradia/models/base.py

@@ -0,0 +1,39 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional
+import numpy as np
+
+class GradiaModel(ABC):
+    """Abstract base class for all Gradia models."""
+
+    @abstractmethod
+    def fit(self, X, y, **kwargs):
+        """Train the model fully."""
+        pass
+
+    def partial_fit(self, X, y, **kwargs):
+        """Train on a batch or single epoch (optional)."""
+        raise NotImplementedError("This model does not support iterative training.")
+
+    @property
+    def supports_iterative(self) -> bool:
+        return False
+
+    @abstractmethod
+    def predict(self, X) -> np.ndarray:
+        """Make predictions."""
+        pass
+    
+    @abstractmethod
+    def predict_proba(self, X) -> Optional[np.ndarray]:
+        """Make probability predictions (if applicable)."""
+        pass
+
+    @abstractmethod
+    def get_feature_importance(self) -> Optional[Dict[str, float]]:
+        """Return feature importance map if available."""
+        pass
+        
+    @abstractmethod
+    def get_params(self) -> Dict[str, Any]:
+        """Return model hyperparameters."""
+        pass