Next-Generation Local-First ML Training Visualization
From observing training to understanding learning.
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.
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?
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.
| 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 |
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
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 |
The Timeline interface is organized into focused blocks:
- Block A: Timeline Overview — High-level view of learning stability across all tracked samples
- Block B: Sample Inspector — Deep-dive into individual sample trajectories with confidence curves
- Block C: Instability Panel — Top flipping samples, late learners, and persistent errors
- Block D: Training Context — Current epoch, status, and tracking metadata
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) │
└─────────────────┘ └─────────────────┘
gradia.events— Event model withLearningEvent,SampleState,EpochSummarySampleTracker— Boundary-aware sample selection and trackingTimelineLogger— Structured timeline event persistenceSchemaMigrator— Automatic v1.x to v2.0 config migration
pip install gradia --upgradegit clone https://github.com/STiFLeR7/gradia.git
cd gradia
pip install -e ".[dev]"# Auto-detect datasets and start the dashboard
gradia run .# Specify target column and port
gradia run . --target "label" --port 8080from 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']}")Access the dashboard at http://localhost:8000 after running gradia run .
| 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) |
# 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"Gradia v2.0 is fully backward compatible. When you run gradia run . on a v1.x project:
- Existing configs are automatically migrated to v2.0 schema
- Old runs remain accessible
- Timeline features are enabled by default
# Migration happens automatically
gradia run .
# Output: Config migrated: Added timeline config, Set schema_version to 2.0# Run all tests
pytest tests/ -v
# Run with coverage
pytest tests/ --cov=gradia --cov-report=htmlgradia/
├── 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
- WebSocket real-time updates
- Dataset Intelligence Panel
- Experiment Comparison (overlay 2-3 runs)
- Export timeline to video/GIF
- PyTorch integration
- TensorFlow/Keras support
- Remote monitoring mode
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
# Development setup
git clone https://github.com/STiFLeR7/gradia.git
cd gradia
pip install -e ".[dev]"
# Run tests
pytest tests/ -v
# Lint
flake8 gradia/Distributed under the MIT License. See LICENSE for more information.
- PyPI: pypi.org/project/gradia
- GitHub: github.com/STiFLeR7/gradia
- Hugging Face: huggingface.co/STiFLeR7
- Issues: github.com/STiFLeR7/gradia/issues