gradia 1.0.0__tar.gz → 2.0.0__tar.gz

gradia-2.0.0/PKG-INFO

@@ -0,0 +1,394 @@
+Metadata-Version: 2.4
+Name: gradia
+Version: 2.0.0
+Summary: Local-first ML training visualization with Learning Timeline - watch how your model learns sample by sample.
+Author-email: STiFLeR <hillaniljppatel@gmail.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
+Project-URL: Documentation, https://github.com/STiFLeR7/gradia#readme
+Project-URL: Changelog, https://github.com/STiFLeR7/gradia/blob/master/RELEASE_NOTES.md
+Keywords: machine-learning,dashboard,visualization,tracking,mlops,timeline,training-monitor
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scikit-learn>=1.0
+Requires-Dist: pandas>=1.3
+Requires-Dist: numpy>=1.20
+Requires-Dist: fastapi>=0.68
+Requires-Dist: uvicorn>=0.15
+Requires-Dist: typer>=0.4
+Requires-Dist: jinja2>=3.0
+Requires-Dist: rich>=10.0
+Requires-Dist: psutil>=5.8
+Requires-Dist: tqdm>=4.60
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: build>=0.10; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Requires-Dist: httpx>=0.24.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# G R A D I A
+
+**Next-Generation Local-First ML Training Visualization**
+
+[![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)
+
+*From observing training to understanding learning.*
+
+<p align="center">
+  <img src="assets/dashboard.png" alt="Gradia Dashboard" width="100%" />
+</p>
+
+</div>
+
+---
+
+## 🚀 What's New in v2.0.0
+
+**Gradia v2.0.0** introduces the **Learning Timeline** — a real-time, sample-centric view of how your models learn over time. This release transforms Gradia from a metrics dashboard into a **learning behavior explorer**.
+
+### ✨ Flagship Feature: Learning Timeline
+
+The Learning Timeline answers questions that aggregate metrics cannot:
+
+- 🎯 **When did this sample become correctly classified?**
+- 🔄 **Which samples keep flipping predictions?**
+- 📈 **Is the model memorizing or stabilizing?**
+- ⚠️ **Which data points drive learning instability?**
+
+<p align="center">
+  <img src="assets/experiment.png" alt="Learning Timeline" width="100%" />
+</p>
+
+---
+
+## 📖 Overview
+
+**Gradia** is a high-performance, local-first monitoring solution for machine learning workflows. Unlike cloud-native platforms, Gradia focuses on **zero-latency**, **privacy-first** tracking that runs directly alongside your training loop.
+
+Built on **FastAPI** and a **Reactive UI**, Gradia provides granular visibility into your model's training dynamics, system resources, and now — individual sample learning behavior.
+
+---
+
+## ⚡ Key Features
+
+| Feature | Description |
+| :--- | :--- |
+| **🔬 Learning Timeline** | Track how individual samples evolve during training with real-time visualization |
+| **📊 Real-Time Telemetry** | Nanosecond-precision tracking of Loss, Accuracy, and custom metrics |
+| **🧠 Intelligent Auto-Discovery** | Automatic task type inference (Classification vs Regression) and model suggestions |
+| **💻 System Profiling** | CPU and RAM monitoring during training epochs |
+| **📁 Artifact Management** | Automated checkpointing and structured logging (`events.jsonl`) |
+| **📋 Comprehensive Reporting** | One-click PDF/JSON reports with full training history |
+| **🔄 Backward Compatible** | Full support for v1.x runs with automatic migration |
+
+---
+
+## 🔬 Learning Timeline Deep Dive
+
+### How It Works
+
+The Learning Timeline tracks a bounded subset of samples (default: 100) throughout training, capturing:
+
+- **Prediction** — What the model predicts for each sample
+- **Confidence** — Model's certainty in its prediction
+- **Correctness** — Whether the prediction matches the true label
+- **Flip Events** — When predictions change between epochs
+
+### Sample Classification
+
+Gradia automatically classifies tracked samples into categories:
+
+| Category | Description | Visual |
+| :--- | :--- | :--- |
+| **Stable Correct** | Consistently correct predictions | 🟢 Green |
+| **Late Learner** | Became correct after epoch N | 🟡 Yellow |
+| **Unstable** | Predictions flip frequently | 🟠 Orange |
+| **Persistent Error** | Never correctly classified | 🔴 Red |
+
+### UI Blocks
+
+The Timeline interface is organized into focused blocks:
+
+1. **Block A: Timeline Overview** — High-level view of learning stability across all tracked samples
+2. **Block B: Sample Inspector** — Deep-dive into individual sample trajectories with confidence curves
+3. **Block C: Instability Panel** — Top flipping samples, late learners, and persistent errors
+4. **Block D: Training Context** — Current epoch, status, and tracking metadata
+
+---
+
+## 🛠️ Architecture
+
+Gradia employs a **Producer-Consumer** architecture:
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│  Trainer Thread │───▶│   Event Queue   │───▶│   FastAPI UI    │
+│   (Producer)    │    │ (Thread-Safe)   │    │   (Consumer)    │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+        │                                              │
+        ▼                                              ▼
+┌─────────────────┐                          ┌─────────────────┐
+│ Sample Tracker  │                          │ Timeline Logger │
+│   (v2.0 New)    │                          │   (v2.0 New)    │
+└─────────────────┘                          └─────────────────┘
+```
+
+### New v2.0 Components
+
+- **`gradia.events`** — Event model with `LearningEvent`, `SampleState`, `EpochSummary`
+- **`SampleTracker`** — Boundary-aware sample selection and tracking
+- **`TimelineLogger`** — Structured timeline event persistence
+- **`SchemaMigrator`** — Automatic v1.x to v2.0 config migration
+
+---
+
+## 📦 Installation
+
+```bash
+pip install gradia --upgrade
+```
+
+### From Source
+
+```bash
+git clone https://github.com/STiFLeR7/gradia.git
+cd gradia
+pip install -e ".[dev]"
+```
+
+---
+
+## 💻 Quick Start
+
+### Basic Usage
+
+```bash
+# Auto-detect datasets and start the dashboard
+gradia run .
+```
+
+### Advanced CLI
+
+```bash
+# Specify target column and port
+gradia run . --target "label" --port 8080
+```
+
+### Python API
+
+```python
+from gradia.trainer.engine import Trainer
+from gradia.core.scenario import ScenarioInferrer
+from gradia.core.config import ConfigManager
+
+# Infer scenario from dataset
+inferrer = ScenarioInferrer()
+scenario = inferrer.infer("data.csv", target_override="label")
+
+# Configure training with timeline enabled
+config_mgr = ConfigManager("./runs")
+config = config_mgr.load_or_create()
+config['model']['type'] = 'random_forest'
+config['training']['epochs'] = 20
+config['timeline']['enabled'] = True
+config['timeline']['max_samples'] = 100
+
+# Run training
+trainer = Trainer(scenario, config, "./runs")
+trainer.run()
+
+# Get timeline insights
+insights = trainer.get_timeline_insights()
+print(f"Stable samples: {insights['stable_correct']}")
+print(f"Flipping samples: {insights['top_flippers']}")
+```
+
+---
+
+## 📊 Dashboard
+
+Access the dashboard at `http://localhost:8000` after running `gradia run .`
+
+### Pages
+
+| Page | URL | Description |
+| :--- | :--- | :--- |
+| **Configure** | `/configure` | Select model, hyperparameters, and start training |
+| **Metrics** | `/` | Real-time training metrics and system resources |
+| **Timeline** | `/timeline` | Learning Timeline visualization (v2.0) |
+
+### Configuration Options
+
+```yaml
+# Example gradia_config.yaml (auto-generated)
+schema_version: "2.0"
+project_name: "my-experiment"
+save_model: true
+
+model:
+  type: "random_forest"
+  params:
+    n_estimators: 100
+    max_depth: null
+
+training:
+  epochs: 20
+  test_split: 0.2
+  random_seed: 42
+
+timeline:
+  enabled: true
+  max_samples: 100
+  sampling_strategy: "boundary"
+```
+
+---
+
+## 🔄 Migration from v1.x
+
+Gradia v2.0 is **fully backward compatible**. When you run `gradia run .` on a v1.x project:
+
+1. Existing configs are automatically migrated to v2.0 schema
+2. Old runs remain accessible
+3. Timeline features are enabled by default
+
+```bash
+# Migration happens automatically
+gradia run .
+# Output: Config migrated: Added timeline config, Set schema_version to 2.0
+```
+
+---
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ --cov=gradia --cov-report=html
+```
+
+---
+
+## 📁 Project Structure
+
+```
+gradia/
+├── cli/              # Typer CLI application
+├── core/             # Configuration, inspection, migration
+├── events/           # v2.0 Event model and tracking
+│   ├── models.py     # LearningEvent, SampleState, EpochSummary
+│   ├── tracker.py    # SampleTracker with boundary sampling
+│   └── logger.py     # TimelineLogger for event persistence
+├── models/           # sklearn wrappers and model factory
+├── trainer/          # Training engine with timeline integration
+└── viz/              # FastAPI server and UI templates
+    ├── templates/    # Jinja2 HTML templates
+    └── static/       # CSS and JavaScript
+```
+
+---
+
+## 🗺️ Roadmap
+
+### v2.1 (Planned)
+- [ ] WebSocket real-time updates
+- [ ] Dataset Intelligence Panel
+- [ ] Experiment Comparison (overlay 2-3 runs)
+- [ ] Export timeline to video/GIF
+
+### v2.2 (Future)
+- [ ] PyTorch integration
+- [ ] TensorFlow/Keras support
+- [ ] Remote monitoring mode
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+```bash
+# Development setup
+git clone https://github.com/STiFLeR7/gradia.git
+cd gradia
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Lint
+flake8 gradia/
+```
+
+---
+
+## 📄 License
+
+Distributed under the MIT License. See [LICENSE](LICENSE) for more information.
+
+---
+
+## 🔗 Links
+
+- **PyPI**: [pypi.org/project/gradia](https://pypi.org/project/gradia/)
+- **GitHub**: [github.com/STiFLeR7/gradia](https://github.com/STiFLeR7/gradia)
+- **Hugging Face**: [huggingface.co/STiFLeR7](https://huggingface.co/STiFLeR7)
+- **Issues**: [github.com/STiFLeR7/gradia/issues](https://github.com/STiFLeR7/gradia/issues)
+
+---
+
+<div align="center">
+  <sub>Built with ❤️ by <strong>STiFLeR</strong> for the ML Community.</sub>
+  <br><br>
+  <a href="https://instagram.com/stifler.xd">Instagram</a> •
+  <a href="https://huggingface.co/STiFLeR7">Hugging Face</a> •
+  <a href="https://pypi.org/user/stifler.xd/">PyPI</a>
+</div>