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

gradia/__init__.py

@@ -1 +1,38 @@
-__version__ = "1.0.0"
+"""
+Gradia - Local-first ML Training Visualization
+
+v2.0.0: Learning Timeline Edition
+"""
+
+__version__ = "2.0.0"
+
+# Core exports
+from .core.scenario import Scenario, ScenarioInferrer
+from .core.config import ConfigManager
+from .core.inspector import Inspector
+from .core.migration import SchemaMigrator, ensure_v2_config
+
+# Events module (v2.0)
+from .events import LearningEvent, SampleTracker, TimelineLogger
+
+# Trainer
+from .trainer.engine import Trainer
+from .trainer.callbacks import EventLogger
+
+__all__ = [
+    "__version__",
+    # Core
+    "Scenario",
+    "ScenarioInferrer", 
+    "ConfigManager",
+    "Inspector",
+    "SchemaMigrator",
+    "ensure_v2_config",
+    # Events (v2.0)
+    "LearningEvent",
+    "SampleTracker",
+    "TimelineLogger",
+    # Trainer
+    "Trainer",
+    "EventLogger",
+]

gradia/cli/main.py

@@ -30,7 +30,7 @@ def run(
     """
     Starts the gradia training and visualization session.
     """
-    console.rule("[bold blue]gradia v1.0.0[/bold blue]")
+    console.rule("[bold blue]gradia v2.0.0[/bold blue]")
     
     # 1. Inspect
     path = Path(path).resolve()

gradia/core/config.py

@@ -2,55 +2,113 @@ import yaml
 from pathlib import Path
 from typing import Any, Dict
 
+from .migration import SchemaMigrator, SchemaVersion
+
+
 class ConfigManager:
-    """Manages gradia configuration."""
+    """Manages gradia configuration with v2.0 migration support."""
     
+    # v2.0 Default Configuration
     DEFAULT_CONFIG = {
+        'schema_version': SchemaVersion.V2_0.value,
         'model': {
-            'type': 'auto', # auto, linear, random_forest
+            'type': 'auto',  # auto, linear, random_forest, sgd, mlp, cnn
             'params': {}
         },
         'training': {
             'test_split': 0.2,
             'random_seed': 42,
-            'shuffle': True
+            'shuffle': True,
+            'epochs': 10
         },
         'scenario': {
-            'target': None, # Auto-detect
-            'task': None # Auto-detect
-        }
+            'target': None,  # Auto-detect
+            'task': None  # Auto-detect
+        },
+        # v2.0: Learning Timeline configuration
+        'timeline': {
+            'enabled': True,
+            'max_samples': 100,
+            'user_samples': None  # List of sample indices to always track
+        },
+        'project_name': 'experiment',
+        'save_model': False
     }
 
     def __init__(self, run_dir: str = ".gradia_logs"):
         self.run_dir = Path(run_dir)
         self.config_path = self.run_dir / "config.yaml"
+        self._migrator = SchemaMigrator()
 
     def load_or_create(self, user_overrides: Dict[str, Any] = None) -> Dict[str, Any]:
-        config = self.DEFAULT_CONFIG.copy()
+        config = self._deep_copy(self.DEFAULT_CONFIG)
         
-        # 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.
+        # Load existing config if present (for run continuation)
+        if self.config_path.exists():
+            with open(self.config_path, 'r') as f:
+                existing = yaml.safe_load(f) or {}
+                
+                # Migrate to v2 if needed
+                result = self._migrator.migrate(existing)
+                if result.changes:
+                    print(f"Config migrated: {', '.join(result.changes)}")
+                
+                self._update_recursive(config, existing)
         
+        # Load root gradia.yaml overrides
         root_config = Path("gradia.yaml")
         if root_config.exists():
             with open(root_config, 'r') as f:
-                user_config = yaml.safe_load(f)
+                user_config = yaml.safe_load(f) or {}
                 self._update_recursive(config, user_config)
 
+        # Apply explicit overrides
         if user_overrides:
             self._update_recursive(config, user_overrides)
+        
+        # Ensure v2 fields exist
+        config = self._ensure_v2_fields(config)
             
         return config
 
     def save(self, config: Dict[str, Any]):
-        self.run_dir.mkdir(exist_ok=True)
+        """Save config with schema version marker."""
+        self.run_dir.mkdir(parents=True, exist_ok=True)
+        
+        # Ensure schema version is set
+        config['schema_version'] = SchemaVersion.V2_0.value
+        
         with open(self.config_path, 'w') as f:
-            yaml.dump(config, f)
+            yaml.dump(config, f, default_flow_style=False)
 
     def _update_recursive(self, base: Dict, update: Dict):
+        """Recursively merge update into base."""
         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
+    
+    def _deep_copy(self, d: Dict) -> Dict:
+        """Create a deep copy of nested dict."""
+        import copy
+        return copy.deepcopy(d)
+    
+    def _ensure_v2_fields(self, config: Dict) -> Dict:
+        """Ensure all v2.0 required fields exist."""
+        # Timeline config
+        if 'timeline' not in config:
+            config['timeline'] = {
+                'enabled': True,
+                'max_samples': 100,
+                'user_samples': None
+            }
+        
+        # Training epochs
+        if 'epochs' not in config.get('training', {}):
+            config.setdefault('training', {})['epochs'] = 10
+        
+        # Schema version
+        config['schema_version'] = SchemaVersion.V2_0.value
+        
+        return config

gradia/core/migration.py

@@ -0,0 +1,324 @@
+"""
+Migration Layer for Gradia v2.0.0
+
+Handles backward compatibility with v1.x .gradia_logs runs.
+Supports schema versioning and silent migration.
+"""
+
+from typing import Dict, Any, Optional, List
+from pathlib import Path
+import json
+import yaml
+from dataclasses import dataclass
+from enum import Enum
+
+
+class SchemaVersion(str, Enum):
+    """Gradia config/log schema versions."""
+    V1_0 = "1.0"
+    V1_1 = "1.1"
+    V1_2 = "1.2"
+    V1_3 = "1.3"
+    V2_0 = "2.0"
+    
+    @classmethod
+    def current(cls) -> "SchemaVersion":
+        return cls.V2_0
+
+
+@dataclass
+class MigrationResult:
+    """Result of a migration operation."""
+    success: bool
+    from_version: str
+    to_version: str
+    changes: List[str]
+    warnings: List[str]
+
+
+class SchemaMigrator:
+    """
+    Handles schema migration between Gradia versions.
+    
+    Strategy:
+    - Silent upgrades (no user intervention required)
+    - Deprecate, don't remove fields
+    - Add new fields with sensible defaults
+    """
+    
+    def __init__(self):
+        self.migrations = {
+            ("1.0", "1.1"): self._migrate_1_0_to_1_1,
+            ("1.1", "1.2"): self._migrate_1_1_to_1_2,
+            ("1.2", "1.3"): self._migrate_1_2_to_1_3,
+            ("1.3", "2.0"): self._migrate_1_3_to_2_0,
+        }
+    
+    def detect_version(self, config: Dict[str, Any]) -> str:
+        """Detect schema version from config structure."""
+        # v2.0 has explicit version field
+        if "schema_version" in config:
+            return config["schema_version"]
+        
+        # v2.0 has timeline config
+        if "timeline" in config:
+            return "2.0"
+        
+        # v1.3 has project_name and save_model
+        if "project_name" in config or "save_model" in config:
+            return "1.3"
+        
+        # v1.2 has training.epochs
+        if config.get("training", {}).get("epochs"):
+            return "1.2"
+        
+        # v1.1 has model.params
+        if config.get("model", {}).get("params"):
+            return "1.1"
+        
+        # Default to 1.0
+        return "1.0"
+    
+    def migrate(self, config: Dict[str, Any], target_version: str = None) -> MigrationResult:
+        """
+        Migrate config to target version (default: current).
+        
+        Args:
+            config: Configuration dictionary
+            target_version: Target version string (default: current)
+            
+        Returns:
+            MigrationResult with details
+        """
+        if target_version is None:
+            target_version = SchemaVersion.current().value
+        
+        from_version = self.detect_version(config)
+        changes = []
+        warnings = []
+        
+        if from_version == target_version:
+            return MigrationResult(
+                success=True,
+                from_version=from_version,
+                to_version=target_version,
+                changes=["No migration needed"],
+                warnings=[]
+            )
+        
+        # Build migration path
+        current = from_version
+        version_order = ["1.0", "1.1", "1.2", "1.3", "2.0"]
+        
+        try:
+            start_idx = version_order.index(current)
+            end_idx = version_order.index(target_version)
+        except ValueError as e:
+            return MigrationResult(
+                success=False,
+                from_version=from_version,
+                to_version=target_version,
+                changes=[],
+                warnings=[f"Unknown version: {e}"]
+            )
+        
+        if start_idx > end_idx:
+            # Downgrade not supported
+            return MigrationResult(
+                success=False,
+                from_version=from_version,
+                to_version=target_version,
+                changes=[],
+                warnings=["Downgrade not supported. Please use a compatible Gradia version."]
+            )
+        
+        # Apply migrations sequentially
+        for i in range(start_idx, end_idx):
+            v_from = version_order[i]
+            v_to = version_order[i + 1]
+            key = (v_from, v_to)
+            
+            if key in self.migrations:
+                migration_fn = self.migrations[key]
+                step_changes, step_warnings = migration_fn(config)
+                changes.extend(step_changes)
+                warnings.extend(step_warnings)
+        
+        # Set version marker
+        config["schema_version"] = target_version
+        
+        return MigrationResult(
+            success=True,
+            from_version=from_version,
+            to_version=target_version,
+            changes=changes,
+            warnings=warnings
+        )
+    
+    def _migrate_1_0_to_1_1(self, config: Dict) -> tuple:
+        """Add model.params if missing."""
+        changes = []
+        warnings = []
+        
+        if "model" not in config:
+            config["model"] = {"type": "auto", "params": {}}
+            changes.append("Added model config with defaults")
+        elif "params" not in config["model"]:
+            config["model"]["params"] = {}
+            changes.append("Added model.params")
+        
+        return changes, warnings
+    
+    def _migrate_1_1_to_1_2(self, config: Dict) -> tuple:
+        """Add training.epochs default."""
+        changes = []
+        warnings = []
+        
+        if "training" not in config:
+            config["training"] = {
+                "test_split": 0.2,
+                "random_seed": 42,
+                "shuffle": True,
+                "epochs": 10
+            }
+            changes.append("Added training config with defaults")
+        elif "epochs" not in config["training"]:
+            config["training"]["epochs"] = 10
+            changes.append("Added training.epochs=10 default")
+        
+        return changes, warnings
+    
+    def _migrate_1_2_to_1_3(self, config: Dict) -> tuple:
+        """Add project_name and save_model."""
+        changes = []
+        warnings = []
+        
+        if "project_name" not in config:
+            config["project_name"] = "experiment"
+            changes.append("Added project_name default")
+        
+        if "save_model" not in config:
+            config["save_model"] = False
+            changes.append("Added save_model=False default")
+        
+        return changes, warnings
+    
+    def _migrate_1_3_to_2_0(self, config: Dict) -> tuple:
+        """Add v2.0 timeline configuration."""
+        changes = []
+        warnings = []
+        
+        if "timeline" not in config:
+            config["timeline"] = {
+                "enabled": True,
+                "max_samples": 100,
+                "user_samples": None
+            }
+            changes.append("Added timeline config for Learning Timeline feature")
+        
+        # Ensure schema version is set
+        config["schema_version"] = "2.0"
+        changes.append("Set schema_version to 2.0")
+        
+        return changes, warnings
+
+
+class RunMigrator:
+    """
+    Handles migration of existing .gradia_logs run directories.
+    """
+    
+    def __init__(self, run_dir: Path):
+        self.run_dir = Path(run_dir)
+        self.schema_migrator = SchemaMigrator()
+    
+    def needs_migration(self) -> bool:
+        """Check if run directory needs migration."""
+        config = self._load_config()
+        if config is None:
+            return False
+        
+        version = self.schema_migrator.detect_version(config)
+        return version != SchemaVersion.current().value
+    
+    def migrate(self) -> MigrationResult:
+        """Migrate the run directory to current schema."""
+        config = self._load_config()
+        
+        if config is None:
+            return MigrationResult(
+                success=False,
+                from_version="unknown",
+                to_version=SchemaVersion.current().value,
+                changes=[],
+                warnings=["No config.yaml found in run directory"]
+            )
+        
+        result = self.schema_migrator.migrate(config)
+        
+        if result.success:
+            self._save_config(config)
+            
+            # Create migration marker file
+            marker_path = self.run_dir / ".migrated"
+            marker_path.write_text(f"Migrated from {result.from_version} to {result.to_version}")
+        
+        return result
+    
+    def _load_config(self) -> Optional[Dict]:
+        """Load config.yaml from run directory."""
+        config_path = self.run_dir / "config.yaml"
+        
+        if not config_path.exists():
+            return None
+        
+        with open(config_path, 'r') as f:
+            return yaml.safe_load(f)
+    
+    def _save_config(self, config: Dict):
+        """Save config.yaml to run directory."""
+        config_path = self.run_dir / "config.yaml"
+        
+        with open(config_path, 'w') as f:
+            yaml.dump(config, f)
+
+
+def migrate_all_runs(base_dir: Path = None) -> List[MigrationResult]:
+    """
+    Migrate all run directories in .gradia_logs.
+    
+    Args:
+        base_dir: Base directory containing .gradia_logs (default: cwd)
+        
+    Returns:
+        List of migration results
+    """
+    if base_dir is None:
+        base_dir = Path.cwd()
+    
+    logs_dir = base_dir / ".gradia_logs"
+    results = []
+    
+    if not logs_dir.exists():
+        return results
+    
+    for run_dir in logs_dir.iterdir():
+        if run_dir.is_dir() and run_dir.name.startswith("run_"):
+            migrator = RunMigrator(run_dir)
+            if migrator.needs_migration():
+                result = migrator.migrate()
+                results.append(result)
+                print(f"Migrated {run_dir.name}: {result.from_version} → {result.to_version}")
+    
+    return results
+
+
+def ensure_v2_config(config: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Ensure config has all v2.0 fields with sensible defaults.
+    
+    Use this when loading configs to guarantee v2 compatibility.
+    """
+    migrator = SchemaMigrator()
+    migrator.migrate(config)
+    return config

gradia/events/__init__.py

@@ -0,0 +1,17 @@
+"""
+Gradia Events Module (v2.0.0)
+
+Core abstraction for sample-level learning events that power the Learning Timeline.
+Decouples training logic from visualization and storage.
+"""
+
+from .models import LearningEvent, EventType
+from .tracker import SampleTracker
+from .logger import TimelineLogger
+
+__all__ = [
+    "LearningEvent",
+    "EventType", 
+    "SampleTracker",
+    "TimelineLogger",
+]