gradia 1.0.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

gradia/viz/server.py

@@ -1,3 +1,4 @@
+from contextlib import asynccontextmanager
 from fastapi import FastAPI, Request
 from fastapi.staticfiles import StaticFiles
 from fastapi.templating import Jinja2Templates
@@ -6,15 +7,13 @@ import uvicorn
 import json
 import threading
 from pathlib import Path
-from typing import Dict, Any
+from typing import Dict, Any, Optional
 
 from ..trainer.engine import Trainer
 
 import psutil
 import time
 
-app = FastAPI()
-
 # Global State (Injected by CLI)
 SCENARIO = None
 CONFIG_MGR = None
@@ -24,20 +23,13 @@ TRAINER = None
 TRAINING_THREAD = None
 SYSTEM_THREAD = None
 
-# Mounts
+# Base directory for templates and static files
 BASE_DIR = Path(__file__).resolve().parent
 
-app.mount("/static", StaticFiles(directory=BASE_DIR / "static"), name="static")
-# Mount assets if they exist outside static, or ensure user put them in static. Assuming viz/assets
-assets_path = BASE_DIR / "assets"
-if assets_path.exists():
-    app.mount("/assets", StaticFiles(directory=assets_path), name="assets")
-
 templates = Jinja2Templates(directory=BASE_DIR / "templates")
 
 from ..trainer.callbacks import log_lock
 
-# ... imports ...
 import os
 
 # System Monitor
@@ -61,27 +53,47 @@ def system_monitor_loop():
                     f.flush()
                     os.fsync(f.fileno())
 
-# Start System Monitor on import/startup (or when server starts)
-@app.on_event("startup")
-async def startup_event():
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Lifespan context manager for startup/shutdown events."""
     global SYSTEM_THREAD
+    # Startup
     SYSTEM_THREAD = threading.Thread(target=system_monitor_loop, daemon=True)
     SYSTEM_THREAD.start()
+    yield
+    # Shutdown (if needed)
+    pass
+
+
+app = FastAPI(lifespan=lifespan)
+
+# Mount static files
+app.mount("/static", StaticFiles(directory=BASE_DIR / "static"), name="static")
+assets_path = BASE_DIR / "assets"
+if assets_path.exists():
+    app.mount("/assets", StaticFiles(directory=assets_path), name="assets")
 
 
 @app.get("/")
 async def read_root(request: Request):
     if TRAINER is None:
         return RedirectResponse("/configure")
-    return templates.TemplateResponse("index.html", {"request": request, "scenario": SCENARIO})
+    return templates.TemplateResponse(request, "index.html", {"scenario": SCENARIO})
+
+@app.get("/timeline")
+async def timeline_page(request: Request):
+    """Learning Timeline view (v2.0)."""
+    if TRAINER is None:
+        return RedirectResponse("/configure")
+    return templates.TemplateResponse(request, "timeline.html", {"scenario": SCENARIO})
 
 @app.get("/configure")
 async def configure_page(request: Request):
     if SCENARIO is None:
         return "System not initialized correctly from CLI."
         
-    return templates.TemplateResponse("configure.html", {
-        "request": request, 
+    return templates.TemplateResponse(request, "configure.html", {
         "scenario": SCENARIO,
         "features": SCENARIO.features,
         "default_config": DEFAULT_CONFIG
@@ -221,6 +233,130 @@ async def evaluate_model():
     except Exception as e:
         return JSONResponse({"error": str(e)}, status_code=500)
 
+
+# ============================================================================
+# v2.0.0 Learning Timeline API Endpoints
+# ============================================================================
+
+@app.get("/api/timeline/events")
+async def get_timeline_events(epoch: int = None, sample_id: int = None):
+    """
+    Get learning timeline events with optional filtering.
+    
+    Query params:
+        epoch: Filter by specific epoch
+        sample_id: Filter by specific sample
+    """
+    if TRAINER is None or not TRAINER.enable_timeline:
+        return JSONResponse({"error": "Timeline not available"}, status_code=400)
+    
+    try:
+        events = TRAINER.timeline_logger.get_events(epoch=epoch, sample_id=sample_id)
+        return JSONResponse(content=[e.to_dict() for e in events])
+    except Exception as e:
+        return JSONResponse({"error": str(e)}, status_code=500)
+
+
+@app.get("/api/timeline/summaries")
+async def get_timeline_summaries():
+    """Get all epoch summaries for timeline overview."""
+    if TRAINER is None or not TRAINER.enable_timeline:
+        return JSONResponse({"error": "Timeline not available"}, status_code=400)
+    
+    try:
+        summaries = TRAINER.timeline_logger.get_summaries()
+        return JSONResponse(content=[s.to_dict() for s in summaries])
+    except Exception as e:
+        return JSONResponse({"error": str(e)}, status_code=500)
+
+
+@app.get("/api/timeline/sample/{sample_id}")
+async def get_sample_timeline(sample_id: int):
+    """Get full timeline for a specific tracked sample."""
+    if TRAINER is None or not TRAINER.enable_timeline:
+        return JSONResponse({"error": "Timeline not available"}, status_code=400)
+    
+    try:
+        timeline = TRAINER.get_sample_timeline(sample_id)
+        if not timeline:
+            return JSONResponse({"error": "Sample not tracked"}, status_code=404)
+        
+        # Also include stability analysis
+        state = TRAINER.sample_tracker.get_sample_state(sample_id)
+        result = {
+            "sample_id": sample_id,
+            "true_label": str(state.true_label) if state else None,
+            "flip_count": state.flip_count if state else 0,
+            "stability_class": state.stability_class if state else "unknown",
+            "first_correct_epoch": state.first_correct_epoch if state else None,
+            "events": timeline
+        }
+        return JSONResponse(content=result)
+    except Exception as e:
+        return JSONResponse({"error": str(e)}, status_code=500)
+
+
+@app.get("/api/timeline/insights")
+async def get_timeline_insights():
+    """Get aggregated timeline insights: flipping samples, late learners, etc."""
+    if TRAINER is None or not TRAINER.enable_timeline:
+        return JSONResponse({"error": "Timeline not available"}, status_code=400)
+    
+    try:
+        tracker = TRAINER.sample_tracker
+        
+        insights = {
+            "tracked_samples": list(tracker.tracked_indices),
+            "total_tracked": len(tracker.tracked_indices),
+            "top_flipping": [
+                {
+                    "sample_id": s.sample_id,
+                    "flip_count": s.flip_count,
+                    "true_label": str(s.true_label),
+                    "current_prediction": str(s.current_prediction),
+                    "stability_class": s.stability_class
+                }
+                for s in tracker.get_top_flipping_samples(20)
+            ],
+            "late_learners": [
+                {
+                    "sample_id": s.sample_id,
+                    "true_label": str(s.true_label),
+                    "first_correct_epoch": s.first_correct_epoch
+                }
+                for s in tracker.get_late_learners()
+            ],
+            "never_correct": [
+                {
+                    "sample_id": s.sample_id,
+                    "true_label": str(s.true_label),
+                    "current_prediction": str(s.current_prediction)
+                }
+                for s in tracker.get_never_correct()
+            ],
+            "stability_distribution": _compute_stability_distribution(tracker)
+        }
+        return JSONResponse(content=insights)
+    except Exception as e:
+        return JSONResponse({"error": str(e)}, status_code=500)
+
+
+def _compute_stability_distribution(tracker) -> Dict[str, int]:
+    """Compute distribution of stability classes."""
+    distribution = {
+        "stable_correct": 0,
+        "stable_wrong": 0,
+        "unstable": 0,
+        "late_learner": 0,
+        "unknown": 0
+    }
+    for state in tracker.sample_states.values():
+        stability = state.stability_class
+        if stability in distribution:
+            distribution[stability] += 1
+    return distribution
+
+
 def start_server(run_dir: str, port: int = 8000):
     global RUN_DIR
     RUN_DIR = Path(run_dir).resolve()

gradia/viz/static/css/timeline.css

@@ -0,0 +1,419 @@
+/* timeline.css - Styles for Learning Timeline v2.0 */
+
+/* Timeline Overview */
+.timeline-container {
+    min-height: 200px;
+    padding: 20px 0;
+    overflow-x: auto;
+}
+
+.timeline-loading {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    height: 150px;
+    color: var(--text-secondary);
+    font-style: italic;
+}
+
+.timeline-grid {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    min-width: 100%;
+}
+
+.timeline-row {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    height: 24px;
+}
+
+.timeline-sample-id {
+    width: 60px;
+    font-size: 0.75rem;
+    color: var(--text-secondary);
+    text-align: right;
+    flex-shrink: 0;
+    cursor: pointer;
+    transition: color 0.2s;
+}
+
+.timeline-sample-id:hover {
+    color: var(--accent);
+}
+
+.timeline-epochs {
+    display: flex;
+    gap: 2px;
+    flex-grow: 1;
+}
+
+.epoch-cell {
+    width: 20px;
+    height: 20px;
+    border-radius: 3px;
+    cursor: pointer;
+    transition: transform 0.1s, box-shadow 0.1s;
+    position: relative;
+}
+
+.epoch-cell:hover {
+    transform: scale(1.3);
+    box-shadow: 0 0 8px rgba(255,255,255,0.3);
+    z-index: 10;
+}
+
+.epoch-cell.correct {
+    background: var(--success);
+}
+
+.epoch-cell.wrong {
+    background: var(--error);
+}
+
+.epoch-cell.flip {
+    border: 2px solid #ffd700;
+}
+
+/* Stability Colors */
+.stable-correct { background: #238636; }
+.stable-wrong { background: #da3633; }
+.unstable { background: #d29922; }
+.late-learner { background: #58a6ff; }
+.unknown { background: #484f58; }
+
+/* Legend */
+.timeline-legend {
+    display: flex;
+    gap: 20px;
+    padding: 15px 0 0;
+    border-top: 1px solid var(--border);
+    margin-top: 15px;
+}
+
+.legend-item {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    font-size: 0.8rem;
+    color: var(--text-secondary);
+}
+
+.legend-color {
+    width: 12px;
+    height: 12px;
+    border-radius: 2px;
+}
+
+/* Card Enhancements */
+.card-header {
+    margin-bottom: 15px;
+}
+
+.card-header h3 {
+    margin: 0;
+    font-size: 1.1rem;
+}
+
+.card-subtitle {
+    font-size: 0.8rem;
+    color: var(--text-secondary);
+    margin-top: 4px;
+    display: block;
+}
+
+/* Instability Panel */
+#instability-panel {
+    display: flex;
+    flex-direction: column;
+    gap: 20px;
+}
+
+.instability-section h4 {
+    font-size: 0.9rem;
+    color: var(--text-secondary);
+    margin: 0 0 10px 0;
+    padding-bottom: 5px;
+    border-bottom: 1px solid var(--border);
+}
+
+.sample-list {
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+    max-height: 150px;
+    overflow-y: auto;
+}
+
+.sample-item {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 8px 12px;
+    background: var(--bg-tertiary);
+    border-radius: 4px;
+    cursor: pointer;
+    transition: background 0.2s;
+}
+
+.sample-item:hover {
+    background: var(--bg-hover);
+}
+
+.sample-item .sample-id {
+    font-family: monospace;
+    font-weight: 600;
+}
+
+.sample-item .sample-meta {
+    font-size: 0.8rem;
+    color: var(--text-secondary);
+}
+
+.sample-item .flip-badge {
+    background: var(--warning);
+    color: #000;
+    padding: 2px 6px;
+    border-radius: 10px;
+    font-size: 0.7rem;
+    font-weight: 600;
+}
+
+.empty-state {
+    color: var(--text-secondary);
+    font-style: italic;
+    font-size: 0.85rem;
+    padding: 10px;
+}
+
+/* Context Strip Items */
+.context-item {
+    display: flex;
+    justify-content: space-between;
+    padding: 4px 0;
+}
+
+.context-label {
+    color: var(--text-secondary);
+    font-size: 0.8rem;
+}
+
+.context-value {
+    font-weight: 600;
+    font-size: 0.85rem;
+}
+
+/* Navigation Buttons */
+.btn-nav {
+    background: var(--bg-card);
+    border: 1px solid var(--border);
+    color: var(--text-primary);
+    padding: 10px 12px;
+    border-radius: 6px;
+    cursor: pointer;
+    text-align: left;
+    font-size: 0.85rem;
+    transition: all 0.2s;
+}
+
+.btn-nav:hover {
+    background: var(--bg-hover);
+    border-color: var(--accent);
+}
+
+.btn-nav.active {
+    background: rgba(88, 166, 255, 0.1);
+    border-color: var(--accent);
+    color: var(--accent);
+}
+
+/* Modal Styles */
+.modal {
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    background: rgba(0, 0, 0, 0.8);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    z-index: 1000;
+}
+
+.modal-content {
+    background: var(--bg-card);
+    border-radius: 12px;
+    width: 90%;
+    max-width: 900px;
+    max-height: 85vh;
+    overflow-y: auto;
+    border: 1px solid var(--border);
+}
+
+.modal-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 20px;
+    border-bottom: 1px solid var(--border);
+}
+
+.modal-header h3 {
+    margin: 0;
+}
+
+.modal-close {
+    background: none;
+    border: none;
+    color: var(--text-secondary);
+    font-size: 1.5rem;
+    cursor: pointer;
+    padding: 5px 10px;
+    transition: color 0.2s;
+}
+
+.modal-close:hover {
+    color: var(--error);
+}
+
+.modal-body {
+    padding: 20px;
+}
+
+/* Inspector Header */
+.inspector-header {
+    display: grid;
+    grid-template-columns: repeat(4, 1fr);
+    gap: 15px;
+    margin-bottom: 25px;
+}
+
+.inspector-stat {
+    background: var(--bg-tertiary);
+    padding: 15px;
+    border-radius: 8px;
+    text-align: center;
+}
+
+.stat-label {
+    display: block;
+    font-size: 0.75rem;
+    color: var(--text-secondary);
+    margin-bottom: 5px;
+}
+
+.stat-value {
+    display: block;
+    font-size: 1.2rem;
+    font-weight: 700;
+    color: var(--accent);
+}
+
+/* Inspector Charts */
+.inspector-charts {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 20px;
+    margin-bottom: 25px;
+}
+
+.inspector-charts .chart-container {
+    background: var(--bg-tertiary);
+    padding: 15px;
+    border-radius: 8px;
+}
+
+.inspector-charts h4 {
+    margin: 0 0 10px 0;
+    font-size: 0.9rem;
+    color: var(--text-secondary);
+}
+
+/* Event History */
+.inspector-events h4 {
+    margin: 0 0 10px 0;
+    font-size: 0.9rem;
+    color: var(--text-secondary);
+}
+
+.event-list {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    max-height: 200px;
+    overflow-y: auto;
+}
+
+.event-item {
+    display: grid;
+    grid-template-columns: 60px 80px 80px 80px 1fr;
+    gap: 10px;
+    padding: 10px;
+    background: var(--bg-tertiary);
+    border-radius: 4px;
+    font-size: 0.8rem;
+    align-items: center;
+}
+
+.event-item.correct {
+    border-left: 3px solid var(--success);
+}
+
+.event-item.wrong {
+    border-left: 3px solid var(--error);
+}
+
+.event-item .epoch-badge {
+    font-weight: 600;
+}
+
+.event-item .flip-marker {
+    color: #ffd700;
+    font-weight: bold;
+}
+
+/* Epoch Axis */
+.epoch-axis {
+    display: flex;
+    gap: 2px;
+    padding-left: 68px;
+    margin-bottom: 5px;
+}
+
+.epoch-label {
+    width: 20px;
+    text-align: center;
+    font-size: 0.65rem;
+    color: var(--text-secondary);
+}
+
+/* Tooltip */
+.epoch-tooltip {
+    position: absolute;
+    background: var(--bg-card);
+    border: 1px solid var(--border);
+    border-radius: 4px;
+    padding: 8px 12px;
+    font-size: 0.8rem;
+    z-index: 100;
+    pointer-events: none;
+    white-space: nowrap;
+}
+
+/* Responsive */
+@media (max-width: 768px) {
+    .inspector-header {
+        grid-template-columns: repeat(2, 1fr);
+    }
+    
+    .inspector-charts {
+        grid-template-columns: 1fr;
+    }
+    
+    .timeline-legend {
+        flex-wrap: wrap;
+    }
+}