import live www.sillylaird.ca webrootHEADmain

11 files changed, 1634 insertions, 0 deletions

diff --git a/.agents/skills/architecture-design/SKILL.md b/.agents/skills/architecture-design/SKILL.md
new file mode 100644
index 0000000..5bbbf87
--- /dev/null
+++ b/.agents/skills/architecture-design/SKILL.md
@@ -0,0 +1,274 @@
+---
+name: architecture-design
+description: Use only when creating new registrable ML components that require Factory or Registry patterns.
+version: 1.2.0
+---
+
+# Architecture Design - ML Project Template
+
+This skill defines the standard code architecture for machine learning projects based on the template structure. When modifying or extending code, follow these patterns to maintain consistency.
+
+## Overview
+
+The project follows a modular, extensible architecture with clear separation of concerns. Each module (data, model, trainer, analysis) is independently organized using factory and registry patterns for maximum flexibility.
+
+## When to Use
+
+Use this skill when:
+- Creating a new Dataset class that needs `@register_dataset`
+- Creating a new Model class that needs `@register_model`
+- Creating a new module directory with `__init__.py` factory wiring
+- Initializing a new ML project structure from scratch
+- Adding new component types such as Augmentation, CollateFunction, or Metrics
+
+## When Not to Use
+
+Do not use this skill when:
+- Modifying existing functions or methods
+- Fixing bugs in existing code
+- Adding helper functions or utilities
+- Refactoring without adding new registrable components
+- Making simple code changes to a single file
+- Modifying configuration files
+- Reading or understanding existing code
+
+Key indicator: if the task does not require a `@register_*` decorator or a Factory pattern, skip this skill.
+
+## Core Design Patterns
+
+### Factory Pattern
+
+Each module uses a factory to create instances dynamically:
+
+```python
+# Example from data_module/dataset/__init__.py
+DATASET_FACTORY: Dict = {}
+
+def DatasetFactory(data_name: str):
+    dataset = DATASET_FACTORY.get(data_name, None)
+    if dataset is None:
+        print(f"{data_name} dataset is not implementation, use simple dataset")
+        dataset = DATASET_FACTORY.get('simple')
+    return dataset
+```
+
+For detailed guidance, refer to `references/factory_pattern.md`.
+
+### Registry Pattern
+
+Components register themselves via decorators:
+
+```python
+# Example from data_module/dataset/simple_dataset.py
+@register_dataset("simple")
+class SimpleDataset(Dataset):
+    def __init__(self, data):
+        self.data = data
+```
+
+For detailed guidance, refer to `references/registry_pattern.md`.
+
+### Auto-Import Pattern
+
+Modules automatically discover and import submodules:
+
+```python
+# Example from data_module/dataset/__init__.py
+models_dir = os.path.dirname(__file__)
+import_modules(models_dir, "src.data_module.dataset")
+```
+
+For detailed guidance, refer to `references/auto_import.md`.
+
+## Directory Structure
+
+```
+project/
+├── run/
+│   ├── pipeline/            # Main workflow scripts
+│   │   ├── training/        # Training pipelines
+│   │   ├── prepare_data/    # Data preparation pipelines
+│   │   └── analysis/        # Analysis pipelines
+│   └── conf/                # Hydra configuration files
+│       ├── training/        # Training configs
+│       ├── dataset/         # Dataset configs
+│       ├── model/           # Model configs
+│       ├── prepare_data/    # Data prep configs
+│       └── analysis/        # Analysis configs
+│
+├── src/
+│   ├── data_module/         # Data processing module
+│   │   ├── dataset/         # Dataset implementations
+│   │   ├── augmentation/    # Data augmentation
+│   │   ├── collate_fn/      # Collate functions
+│   │   ├── compute_metrics/ # Metrics computation
+│   │   ├── prepare_data/    # Data preparation logic
+│   │   ├── data_func/       # Data utility functions
+│   │   └── utils.py         # Module-specific utilities
+│   │
+│   ├── model_module/        # Model implementations
+│   │   ├── brain_decoder/   # Brain decoder models
+│   │   └── model/           # Alternative model location
+│   │
+│   ├── trainer_module/      # Training logic
+│   ├── analysis_module/     # Analysis and evaluation
+│   ├── llm/                 # LLM-related code
+│   └── utils/               # Shared utilities
+│
+├── data/
+│   ├── raw/                 # Original, immutable data
+│   ├── processed/           # Cleaned, transformed data
+│   └── external/            # Third-party data
+│
+├── outputs/
+│   ├── logs/                # Training and evaluation logs
+│   ├── checkpoints/         # Model checkpoints
+│   ├── tables/              # Result tables
+│   └── figures/             # Plots and visualizations
+│
+├── pyproject.toml           # Project configuration
+├── uv.lock                  # Dependency lock file
+├── TODO.md                  # Task tracking
+├── README.md                # Project documentation
+└── .gitignore               # Git ignore rules
+```
+
+For detailed directory structure with file descriptions, refer to `references/structure.md`.
+
+## Module Organization
+
+### Creating a New Dataset
+
+When adding a new dataset:
+
+1. Create file in `src/data_module/dataset/`
+2. Use `@register_dataset("name")` decorator
+3. Inherit from `torch.utils.data.Dataset`
+4. Implement `__init__`, `__len__`, `__getitem__`
+
+```python
+from torch.utils.data import Dataset
+from typing import Dict
+import torch
+from src.data_module.dataset import register_dataset
+
+@register_dataset("custom")
+class CustomDataset(Dataset):
+    def __init__(self, data):
+        self.data = data
+
+    def __len__(self):
+        return len(self.data)
+
+    def __getitem__(self, i: int) -> Dict[str, torch.Tensor]:
+        return self.data[i]
+```
+
+### Creating a New Model
+
+**CRITICAL: Models use config-driven pattern**
+
+When adding a new model:
+
+1. Create file in `src/model_module/model/` or appropriate module subdirectory
+2. Use `@register_model('ModelName')` decorator
+3. `__init__` accepts **ONLY** `cfg` parameter - all hyperparameters come from config
+4. `forward()` returns dict: `{"loss": loss, "labels": labels, "logits": logits}`
+5. Handle training vs inference modes using `self.training`
+
+```python
+from src.model_module.brain_decoder import register_model
+
+@register_model('MyModel')
+class MyModel(nn.Module):
+    def __init__(self, cfg):
+        super().__init__()
+        self.cfg = cfg
+        self.task = cfg.dataset.task
+
+        # ALL parameters from cfg
+        self.hidden_dim = cfg.model.hidden_dim
+        self.output_dim = cfg.dataset.target_size[cfg.dataset.task]
+
+    def forward(self, x, labels=None, **kwargs):
+        if self.training:
+            # Training logic
+            pass
+        else:
+            # Inference logic
+            pass
+
+        return {"loss": loss, "labels": labels, "logits": logits}
+```
+
+### Adding Data Augmentation
+
+When adding augmentation:
+
+1. Create file in `src/data_module/augmentation/`
+2. Implement transformation function
+3. Register with factory if needed
+
+## Code Style Guidelines
+
+For comprehensive style guidelines, refer to `references/code_style.md`.
+
+**Key principles:**
+- Always use type hints for function signatures
+- Follow import order: standard library → third-party → local
+- Module `__init__.py` files contain factory/registry logic
+- Model classes must be config-driven
+
+## Configuration Management
+
+The project uses Hydra for configuration management:
+
+- Config files in `run/conf/` organize by module
+- Each stage (training, analysis) has its own config structure
+- Use YAML files for all configuration
+
+## When Working on This Project
+
+### Before Modifying Code
+
+1. Read the relevant module's factory/registry pattern
+2. Check existing implementations for consistency
+3. Follow the established directory structure
+4. Use registration decorators for new components
+
+### Adding New Features
+
+1. Determine which module the feature belongs to
+2. Check if similar functionality exists
+3. Follow factory/registry pattern if creating new component types
+4. Add configuration files if needed
+5. Update documentation
+
+### Code Review Checklist
+
+- [ ] Uses factory/registry pattern appropriately
+- [ ] Follows module directory structure
+- [ ] Has proper type annotations
+- [ ] Imports are correctly ordered
+- [ ] Registration decorator is used
+- [ ] Configuration files are added if needed
+
+## Additional Resources
+
+### Reference Files
+
+For detailed information, consult:
+- **`references/structure.md`** - Detailed directory structure with file descriptions
+- **`references/factory_pattern.md`** - Factory pattern in-depth explanation
+- **`references/registry_pattern.md`** - Registry pattern in-depth explanation
+- **`references/auto_import.md`** - Auto-import pattern in-depth explanation
+- **`references/code_style.md`** - Comprehensive code style guidelines
+
+### Example Files
+
+Working examples in `examples/`:
+- **`examples/custom_dataset.py`** - Custom dataset implementation
+- **`examples/custom_model.py`** - Custom model implementation
+- **`examples/augmentation_example.py`** - Data augmentation example
+- **`examples/config_example.yaml`** - Configuration file example
+- **`examples/pipeline_example.sh`** - Pipeline script example
diff --git a/.agents/skills/architecture-design/examples/augmentation_example.py b/.agents/skills/architecture-design/examples/augmentation_example.py
new file mode 100644
index 0000000..949b033
--- /dev/null
+++ b/.agents/skills/architecture-design/examples/augmentation_example.py
@@ -0,0 +1,117 @@
+"""
+Data Augmentation Example
+
+Demonstrates how to create a custom data augmentation function
+following the architecture design pattern.
+"""
+
+import torch
+from typing import Dict
+from src.data_module.augmentation import register_augmentation
+
+
+@register_augmentation("time_shift")
+def time_shift(signal: torch.Tensor, max_shift: int = 10) -> torch.Tensor:
+    """Randomly shift signal in time.
+
+    Args:
+        signal: Input signal tensor of shape (channels, time_steps)
+        max_shift: Maximum number of steps to shift
+
+    Returns:
+        Shifted signal tensor
+    """
+    shift = torch.randint(-max_shift, max_shift + 1, (1,)).item()
+    return torch.roll(signal, shifts=shift, dims=-1)
+
+
+@register_augmentation("amplitude_scale")
+def amplitude_scale(
+    signal: torch.Tensor,
+    min_scale: float = 0.8,
+    max_scale: float = 1.2
+) -> torch.Tensor:
+    """Randomly scale signal amplitude.
+
+    Args:
+        signal: Input signal tensor of shape (channels, time_steps)
+        min_scale: Minimum scaling factor
+        max_scale: Maximum scaling factor
+
+    Returns:
+        Scaled signal tensor
+    """
+    scale = torch.empty(1).uniform_(min_scale, max_scale).item()
+    return signal * scale
+
+
+@register_augmentation("gaussian_noise")
+def add_gaussian_noise(
+    signal: torch.Tensor,
+    mean: float = 0.0,
+    std: float = 0.1
+) -> torch.Tensor:
+    """Add Gaussian noise to signal.
+
+    Args:
+        signal: Input signal tensor of shape (channels, time_steps)
+        mean: Mean of Gaussian noise
+        std: Standard deviation of Gaussian noise
+
+    Returns:
+        Signal with added noise
+    """
+    noise = torch.randn_like(signal) * std + mean
+    return signal + noise
+
+
+# Example: Composed augmentation
+@register_augmentation("composed")
+def composed_augmentation(signal: torch.Tensor, cfg) -> torch.Tensor:
+    """Apply multiple augmentations in sequence.
+
+    Args:
+        signal: Input signal tensor
+        cfg: Configuration object with augmentation parameters
+
+    Returns:
+        Augmented signal tensor
+    """
+    # Apply each augmentation based on config
+    if cfg.augmentation.time_shift:
+        signal = time_shift(signal, cfg.augmentation.max_shift)
+
+    if cfg.augmentation.amplitude_scale:
+        signal = amplitude_scale(
+            signal,
+            cfg.augmentation.min_scale,
+            cfg.augmentation.max_scale
+        )
+
+    if cfg.augmentation.gaussian_noise:
+        signal = add_gaussian_noise(
+            signal,
+            cfg.augmentation.noise_mean,
+            cfg.augmentation.noise_std
+        )
+
+    return signal
+
+
+# Usage in dataset class
+class AugmentedDataset:
+    """Example dataset with augmentation support."""
+
+    def __init__(self, cfg):
+        self.cfg = cfg
+        self.augmentation_fn = AugmentationFactory(cfg.augmentation.name)
+
+    def __getitem__(self, idx: int) -> Dict[str, torch.Tensor]:
+        # Load signal
+        signal = self.load_signal(idx)
+
+        # Apply augmentation (training mode only)
+        if self.training and self.augmentation_fn:
+            signal = self.augmentation_fn(signal, self.cfg)
+
+        return {"signal": signal, "label": self.labels[idx]}
diff --git a/.agents/skills/architecture-design/examples/config_example.yaml b/.agents/skills/architecture-design/examples/config_example.yaml
new file mode 100644
index 0000000..8b61442
--- /dev/null
+++ b/.agents/skills/architecture-design/examples/config_example.yaml
@@ -0,0 +1,131 @@
+# Hydra Configuration Example
+# This demonstrates the config structure for training pipeline
+
+# Run with: python train.py --config-name=config_example
+
+defaults:
+  - training: default
+  - dataset: brain_decoder
+  - model: transformer
+  - override hydra/launcher: submitit_local
+
+# Project settings
+project_name: brain_decoder
+experiment_name: transformer_baseline
+
+# Random seed
+seed: 42
+
+# Device settings
+device: cuda
+num_workers: 4
+pin_memory: true
+
+# Training configuration
+training:
+  epochs: 100
+  batch_size: 32
+  learning_rate: 0.001
+  weight_decay: 0.0001
+  gradient_clip: 1.0
+  early_stopping:
+    patience: 10
+    min_delta: 0.001
+
+  # Optimizer settings
+  optimizer: adamw
+  optimizer_params:
+    betas: [0.9, 0.999]
+    eps: 1.0e-08
+
+  # Scheduler settings
+  scheduler: cosine
+  scheduler_params:
+    warmup_epochs: 10
+    min_lr: 1.0e-06
+
+  # Checkpoint settings
+  checkpoint:
+    save_every: 5
+    save_best: true
+    monitor: val_loss
+    mode: min
+
+# Dataset configuration
+dataset:
+  name: brain_decoder
+  task: movement_classification
+  target_size:
+    movement_classification: 5
+    reconstruction: [64, 64]
+
+  # Data paths
+  data_dir: ${dir.data_dir}/processed
+  train_split: train
+  val_split: val
+  test_split: test
+
+  # Data loading
+  num_channels: 64
+  sampling_rate: 1000
+  sequence_length: 1000
+
+  # Augmentation
+  augmentation:
+    name: composed
+    time_shift: true
+    amplitude_scale: true
+    gaussian_noise: true
+    max_shift: 10
+    min_scale: 0.8
+    max_scale: 1.2
+    noise_mean: 0.0
+    noise_std: 0.1
+
+# Model configuration
+model:
+  name: Transformer
+  hidden_dim: 256
+  num_heads: 8
+  num_layers: 6
+  dropout: 0.1
+  activation: gelu
+
+  # Architecture specific
+  encoder:
+    input_dim: 64
+    embedding_dim: 256
+    positional_encoding: true
+
+  decoder:
+    output_dim: ${dataset.target_size.${dataset.task}}
+    pooling: avg
+
+# Logging configuration
+logging:
+  logger: wandb
+  log_every: 10
+  log_grads: false
+
+  # TensorBoard
+  tensorboard: true
+  histogram: true
+
+  # W&B
+  wandb:
+    project: ${project_name}
+    entity: null
+    tags: ["baseline", "transformer"]
+
+# Output directories
+dir:
+  data_dir: ./data
+  output_dir: ./outputs
+  log_dir: ${dir.output_dir}/logs
+  checkpoint_dir: ${dir.output_dir}/checkpoints
+  figure_dir: ${dir.output_dir}/figures
+  table_dir: ${dir.output_dir}/tables
+
+# Debug settings
+debug: false
+fast_dev_run: false
diff --git a/.agents/skills/architecture-design/examples/custom_dataset.py b/.agents/skills/architecture-design/examples/custom_dataset.py
new file mode 100644
index 0000000..c9fe002
--- /dev/null
+++ b/.agents/skills/architecture-design/examples/custom_dataset.py
@@ -0,0 +1,50 @@
+"""
+Example: Creating a Custom Dataset
+
+This example shows how to add a new dataset following the project architecture.
+"""
+
+from torch.utils.data import Dataset
+from typing import Dict
+import torch
+from src.data_module.dataset import register_dataset
+
+
+@register_dataset("time_series")
+class TimeSeriesDataset(Dataset):
+    """
+    Time series dataset for sequence modeling.
+
+    Args:
+        sequences: List of time series sequences
+        seq_length: Fixed sequence length (pad or truncate if needed)
+    """
+
+    def __init__(self, sequences: list, seq_length: int = 100):
+        self.sequences = sequences
+        self.seq_length = seq_length
+
+    def __len__(self) -> int:
+        return len(self.sequences)
+
+    def __getitem__(self, i: int) -> Dict[str, torch.Tensor]:
+        sequence = self.sequences[i]
+
+        # Pad or truncate to fixed length
+        if len(sequence) < self.seq_length:
+            padding = torch.zeros(self.seq_length - len(sequence))
+            sequence = torch.cat([sequence, padding])
+        else:
+            sequence = sequence[:self.seq_length]
+
+        return {
+            "input": sequence,
+            "label": sequence,  # For autoencoder, etc.
+            "length": torch.tensor(min(len(self.sequences[i]), self.seq_length))
+        }
+
+
+# Usage in training:
+# from src.data_module.dataset import DatasetFactory
+# dataset = DatasetFactory("time_series")(sequences=training_data, seq_length=128)
+# dataloader = DataLoader(dataset, batch_size=32, shuffle=True)
diff --git a/.agents/skills/architecture-design/examples/custom_model.py b/.agents/skills/architecture-design/examples/custom_model.py
new file mode 100644
index 0000000..0e00752
--- /dev/null
+++ b/.agents/skills/architecture-design/examples/custom_model.py
@@ -0,0 +1,217 @@
+"""
+Example: Creating a Custom Model
+
+This example shows how to add a new model following the project architecture.
+IMPORTANT: Models use a config-driven pattern where __init__ only accepts cfg.
+
+Key Requirements:
+- Use @register_model('ModelName') decorator
+- __init__ accepts ONLY cfg parameter
+- All hyperparameters come from cfg (cfg.model.*, cfg.dataset.*, etc.)
+- forward() returns dict: {"loss": loss, "labels": labels, "logits": logits}
+"""
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from typing import Dict, Optional
+
+# Import the register_model decorator
+# Location may vary: src.model_module.brain_decoder or src.model_module.model
+from src.model_module.brain_decoder import register_model
+
+
+@register_model('SimpleMLP')
+class SimpleMLP(nn.Module):
+    """
+    Simple Multi-Layer Perceptron for classification tasks.
+
+    Config structure ( Hydra YAML ):
+        model:
+            input_dim: 100
+            hidden_dim: 256
+            output_dim: 10
+            num_layers: 3
+            dropout: 0.1
+        dataset:
+            task: classification  # Used to get target_size
+            target_size:
+                classification: 10
+    """
+
+    def __init__(self, cfg):
+        super().__init__()
+
+        # Store config
+        self.cfg = cfg
+
+        # Get task info from config
+        self.task = cfg.dataset.task
+
+        # Build model - ALL parameters from cfg
+        self.input_dim = cfg.model.input_dim
+        self.hidden_dim = cfg.model.get('hidden_dim', 256)
+        self.output_dim = cfg.dataset.target_size[cfg.dataset.task]
+        self.num_layers = cfg.model.get('num_layers', 3)
+        self.dropout = cfg.model.get('dropout', 0.1)
+
+        # Build layers
+        layers = []
+        in_dim = self.input_dim
+
+        for i in range(self.num_layers):
+            layers.extend([
+                nn.Linear(in_dim, self.hidden_dim),
+                nn.ReLU(),
+                nn.Dropout(self.dropout)
+            ])
+            in_dim = self.hidden_dim
+
+        # Output layer
+        layers.append(nn.Linear(self.hidden_dim, self.output_dim))
+        self.network = nn.Sequential(*layers)
+
+        # Loss function
+        self.loss_fn = nn.CrossEntropyLoss()
+
+    def forward(
+        self,
+        x: torch.Tensor,
+        labels: Optional[torch.Tensor] = None,
+        **kwargs
+    ) -> Dict[str, Optional[torch.Tensor]]:
+        """
+        Forward pass.
+
+        Args:
+            x: Input tensor of shape (batch_size, input_dim)
+            labels: Ground truth labels (optional, for training)
+
+        Returns:
+            Dictionary with:
+                - loss: Computed loss (None if labels not provided)
+                - labels: Ground truth labels
+                - logits: Model predictions
+        """
+        logits = self.network(x)
+
+        loss = None
+        if labels is not None:
+            # Convert labels to long type if needed
+            if labels.dtype != torch.long:
+                labels = labels.long()
+            loss = self.loss_fn(logits, labels)
+
+        return {
+            "loss": loss,
+            "labels": labels,
+            "logits": logits
+        }
+
+
+# ============================================
+# Example with Training/Inference Modes
+# ============================================
+
+@register_model('SimpleMLPWithModes')
+class SimpleMLPWithModes(nn.Module):
+    """
+    MLP with separate training and inference logic.
+    Shows how to handle different modes using self.training.
+    """
+
+    def __init__(self, cfg):
+        super().__init__()
+        self.cfg = cfg
+        self.task = cfg.dataset.task
+
+        self.input_dim = cfg.model.input_dim
+        self.hidden_dim = cfg.model.get('hidden_dim', 256)
+        self.output_dim = cfg.dataset.target_size[cfg.dataset.task]
+
+        self.fc_in = nn.Linear(self.input_dim, self.hidden_dim)
+        self.ln = nn.LayerNorm(self.hidden_dim)
+        self.fc_out = nn.Linear(self.hidden_dim, self.output_dim)
+        self.loss_fn = nn.CrossEntropyLoss()
+
+        # Test-time augmentation config
+        self.tta_times = cfg.model.get('tta_times', 1)
+
+    def forward(
+        self,
+        x: torch.Tensor,
+        labels: Optional[torch.Tensor] = None,
+        **kwargs
+    ) -> Dict[str, Optional[torch.Tensor]]:
+        """
+        Forward pass with training/inference modes.
+        """
+        if self.training:
+            # Training mode
+            x = x.float()
+            x = self.fc_in(x)
+            x = self.ln(x)
+            x = F.relu(x)
+            logits = self.fc_out(x)
+
+            loss = None
+            if labels is not None:
+                if labels.dtype != torch.long:
+                    labels = labels.long()
+                loss = self.loss_fn(logits, labels)
+
+            return {
+                "loss": loss,
+                "labels": labels,
+                "logits": logits
+            }
+        else:
+            # Inference mode with TTA
+            all_logits = []
+            with torch.no_grad():
+                x = x.float()
+                for _ in range(self.tta_times):
+                    x_aug = x.clone()
+                    # Apply TTA transformations here if needed
+
+                    x_aug = self.fc_in(x_aug)
+                    x_aug = self.ln(x_aug)
+                    x_aug = F.relu(x_aug)
+                    logits = self.fc_out(x_aug)
+                    all_logits.append(logits)
+
+            # Average predictions
+            avg_logits = torch.mean(torch.stack(all_logits), dim=0)
+
+            loss = None
+            if labels is not None:
+                if labels.dtype != torch.long:
+                    labels = labels.long()
+                loss = self.loss_fn(avg_logits, labels)
+
+            return {
+                "loss": loss,
+                "labels": labels,
+                "logits": avg_logits
+            }
+
+
+# ============================================
+# Config Example (Hydra YAML)
+# ============================================
+"""
+# run/conf/model/simple_mlp.yaml
+
+model:
+  name: SimpleMLP
+  input_dim: 100
+  hidden_dim: 256
+  output_dim: 10
+  num_layers: 3
+  dropout: 0.1
+  tta_times: 1
+
+# Then in training pipeline:
+# from src.model_module.brain_decoder import ModelFactory
+# model = ModelFactory(cfg.model.name)(cfg)
+"""
diff --git a/.agents/skills/architecture-design/examples/pipeline_example.sh b/.agents/skills/architecture-design/examples/pipeline_example.sh
new file mode 100755
index 0000000..abd7b46
--- /dev/null
+++ b/.agents/skills/architecture-design/examples/pipeline_example.sh
@@ -0,0 +1,189 @@
+#!/bin/bash
+###############################################################################
+# Training Pipeline Script
+#
+# This script demonstrates the standard training pipeline execution pattern.
+# It handles environment setup, configuration, and execution with proper
+# error handling and logging.
+#
+# Usage:
+#   ./run/pipeline/training/train.sh --config-name=config_example
+###############################################################################
+
+set -e  # Exit on error
+set -o pipefail  # Exit on pipe failure
+
+# Script configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+EXPERIMENT_NAME="baseline_experiment"
+TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+###############################################################################
+# Helper Functions
+###############################################################################
+
+log_info() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+cleanup() {
+    log_info "Cleaning up..."
+    # Add cleanup logic here (e.g., kill background processes)
+}
+
+trap cleanup EXIT
+
+###############################################################################
+# Environment Setup
+###############################################################################
+
+setup_environment() {
+    log_info "Setting up environment..."
+
+    # Activate virtual environment if it exists
+    if [ -f "${PROJECT_ROOT}/.venv/bin/activate" ]; then
+        source "${PROJECT_ROOT}/.venv/bin/activate"
+        log_info "Activated virtual environment"
+    fi
+
+    # Check required commands
+    command -v python >/dev/null 2>&1 || { log_error "Python not found"; exit 1; }
+
+    # Set Python path
+    export PYTHONPATH="${PROJECT_ROOT}/src:${PYTHONPATH}"
+    log_info "PYTHONPATH set to: ${PYTHONPATH}"
+}
+
+###############################################################################
+# Configuration
+###############################################################################
+
+parse_arguments() {
+    # Default values
+    CONFIG="default"
+    GPUS=0
+    SEED=42
+
+    # Parse arguments
+    while [[ $# -gt 0 ]]; do
+        case $1 in
+            --config-name|-c)
+                CONFIG="$2"
+                shift 2
+                ;;
+            --gpus|-g)
+                GPUS="$2"
+                shift 2
+                ;;
+            --seed|-s)
+                SEED="$2"
+                shift 2
+                ;;
+            *)
+                log_warn "Unknown argument: $1"
+                shift
+                ;;
+        esac
+    done
+
+    log_info "Configuration: ${CONFIG}"
+    log_info "GPUs: ${GPUS}"
+    log_info "Seed: ${SEED}"
+}
+
+###############################################################################
+# Main Training Function
+###############################################################################
+
+run_training() {
+    log_info "Starting training..."
+
+    # Output directory for this run
+    OUTPUT_DIR="${PROJECT_ROOT}/outputs/${EXPERIMENT_NAME}/${TIMESTAMP}"
+    mkdir -p "${OUTPUT_DIR}"
+
+    log_info "Output directory: ${OUTPUT_DIR}"
+
+    # Training command with Hydra
+    python "${PROJECT_ROOT}/train.py" \
+        --config-name="${CONFIG}" \
+        seed=${SEED} \
+        dir.output_dir="${OUTPUT_DIR}" \
+        training.device=cuda \
+        hydra.output_dir="${OUTPUT_DIR}/hydra" \
+        hydra.run.dir="${OUTPUT_DIR}/hydra" || {
+        log_error "Training failed!"
+        exit 1
+    }
+
+    log_info "Training completed successfully!"
+}
+
+###############################################################################
+# Post-Processing
+###############################################################################
+
+post_process() {
+    log_info "Post-processing results..."
+
+    # Copy logs to output directory
+    if [ -f "${OUTPUT_DIR}/hydra/*.log" ]; then
+        cp "${OUTPUT_DIR}/hydra/"*.log "${OUTPUT_DIR}/"
+    fi
+
+    # Generate summary
+    log_info "Run summary:"
+    log_info "  Config: ${CONFIG}"
+    log_info "  Seed: ${SEED}"
+    log_info "  Output: ${OUTPUT_DIR}"
+
+    # Print path to best checkpoint
+    BEST_CHECKPOINT=$(find "${OUTPUT_DIR}" -name "best*.pt" | head -n 1)
+    if [ -n "${BEST_CHECKPOINT}" ]; then
+        log_info "  Best checkpoint: ${BEST_CHECKPOINT}"
+    fi
+}
+
+###############################################################################
+# Main Execution
+###############################################################################
+
+main() {
+    log_info "=========================================="
+    log_info "Training Pipeline"
+    log_info "=========================================="
+
+    # Setup
+    setup_environment
+
+    # Parse arguments
+    parse_arguments "$@"
+
+    # Run training
+    run_training
+
+    # Post-process
+    post_process
+
+    log_info "=========================================="
+    log_info "Pipeline completed successfully!"
+    log_info "=========================================="
+}
+
+# Run main function
+main "$@"
diff --git a/.agents/skills/architecture-design/references/auto_import.md b/.agents/skills/architecture-design/references/auto_import.md
new file mode 100644
index 0000000..59c19ef
--- /dev/null
+++ b/.agents/skills/architecture-design/references/auto_import.md
@@ -0,0 +1,117 @@
+# Auto-Import Pattern
+
+## Overview
+
+The Auto-Import pattern automatically discovers and imports all submodules in a directory, ensuring all components are registered without manual imports.
+
+## Structure
+
+```python
+# In module __init__.py (e.g., data_module/dataset/__init__.py)
+import os
+from src.utils.helpers import import_modules
+
+models_dir = os.path.dirname(__file__)
+import_modules(models_dir, "src.data_module.dataset")
+```
+
+## Helper Function
+
+```python
+# In src/utils/helpers.py
+import os
+import importlib
+import pkgutil
+from typing import List
+
+def import_modules(models_dir: str, package_name: str) -> List[str]:
+    """
+    Import all Python modules in a directory.
+
+    Args:
+        models_dir: Directory path to scan
+        package_name: Full package name for imports
+
+    Returns:
+        List of imported module names
+    """
+    imported = []
+    for module_loader, name, ispkg in pkgutil.iter_modules([models_dir]):
+        if not name.startswith('_'):
+            full_name = f"{package_name}.{name}"
+            importlib.import_module(full_name)
+            imported.append(name)
+    return imported
+```
+
+## Benefits
+
+- **Zero maintenance**: Adding new file = auto-registration
+- **No遗漏**: Cannot forget to import new component
+- **Consistent**: All components follow same discovery path
+- **Scalable**: Works for any number of submodules
+
+## Implementation Details
+
+1. Scan directory for `.py` files
+2. Skip files starting with `_` (private)
+3. Import each module using full package path
+4. Import triggers decorator registration
+
+## Directory Structure Example
+
+```
+dataset/
+├── __init__.py          # Contains import_modules() call
+├── simple_dataset.py    # Auto-imported, registers "simple"
+├── custom_dataset.py    # Auto-imported, registers "custom"
+└── _private.py          # NOT imported (starts with _)
+```
+
+## Best Practices
+
+- **Skip private files**: Files starting with `_` are not imported
+- **Full package paths**: Use dot-notation for correct imports
+- **Idempotent**: Safe to call multiple times
+- **Error handling**: Import errors propagate for debugging
+
+## Common Patterns
+
+### Conditional Import
+
+```python
+def import_modules(models_dir: str, package_name: str, skip: List[str] = None):
+    skip = skip or []
+    for module_loader, name, ispkg in pkgutil.iter_modules([models_dir]):
+        if name not in skip and not name.startswith('_'):
+            importlib.import_module(f"{package_name}.{name}")
+```
+
+### Recursive Import
+
+```python
+def import_modules_recursive(models_dir: str, package_name: str):
+    """Import modules and subpackages recursively."""
+    for importer, name, ispkg in pkgutil.walk_packages([models_dir], prefix=f"{package_name}."):
+        if not name.split('.')[-1].startswith('_'):
+            importlib.import_module(name)
+```
+
+### Dry-Run Mode
+
+```python
+def import_modules(models_dir: str, package_name: str, dry_run: bool = False):
+    if dry_run:
+        return [name for _, name, _ in pkgutil.iter_modules([models_dir])
+                if not name.startswith('_')]
+    # ... actual import logic
+```
+
+## Integration with Registry
+
+The auto-import pattern is typically used WITH registry pattern:
+
+1. **Import time**: `import_modules()` imports all files
+2. **Decorator execution**: `@register_dataset()` runs
+3. **Factory population**: `DATASET_FACTORY` dict populated
+4. **Runtime**: `DatasetFactory()` looks up registered classes
diff --git a/.agents/skills/architecture-design/references/code_style.md b/.agents/skills/architecture-design/references/code_style.md
new file mode 100644
index 0000000..c07fd0a
--- /dev/null
+++ b/.agents/skills/architecture-design/references/code_style.md
@@ -0,0 +1,234 @@
+# Code Style Guidelines
+
+## Type Annotations
+
+Always use type hints for function signatures and class attributes:
+
+```python
+from typing import Dict, List, Optional, Tuple
+import torch
+
+def __getitem__(self, i: int) -> Dict[str, torch.Tensor]:
+    """Get item by index."""
+    return self.data[i]
+
+def compute_metrics(predictions: torch.Tensor, labels: torch.Tensor) -> Dict[str, float]:
+    """Compute evaluation metrics."""
+    pass
+
+class MyModel(nn.Module):
+    hidden_dim: int  # Class attribute type hints
+    output_dim: int
+
+    def __init__(self, cfg):
+        self.hidden_dim: int = cfg.model.hidden_dim
+        self.output_dim: int = cfg.model.output_dim
+```
+
+## Import Order
+
+Organize imports in three sections with blank lines between:
+
+```python
+# 1. Standard library imports
+import os
+from typing import Dict, List, Optional
+from pathlib import Path
+
+# 2. Third-party imports
+import torch
+import torch.nn as nn
+from torch.utils.data import Dataset
+import numpy as np
+
+# 3. Local imports
+from src.data_module.dataset import register_dataset
+from src.utils.helpers import import_modules
+from src.model_module.brain_decoder import register_model
+```
+
+## __init__.py Files
+
+### Module __init__.py (with factory)
+
+Contains factory/registry logic and auto-import:
+
+```python
+# src/data_module/dataset/__init__.py
+import os
+from typing import Dict, Callable, TypeVar
+from src.utils.helpers import import_modules
+
+T = TypeVar('T')
+
+DATASET_FACTORY: Dict[str, type] = {}
+
+def register_dataset(name: str) -> Callable[[T], T]:
+    """Decorator to register dataset classes."""
+    def decorator(cls: T) -> T:
+        DATASET_FACTORY[name] = cls
+        return cls
+    return decorator
+
+def DatasetFactory(data_name: str):
+    """Create dataset instance by name."""
+    dataset = DATASET_FACTORY.get(data_name, None)
+    if dataset is None:
+        dataset = DATASET_FACTORY.get('simple')
+    return dataset
+
+# Auto-import all submodules
+models_dir = os.path.dirname(__file__)
+import_modules(models_dir, "src.data_module.dataset")
+```
+
+### Subpackage __init__.py (can be empty)
+
+```python
+# src/data_module/augmentation/__init__.py
+# Empty file - just marks as package
+```
+
+Or with exports:
+
+```python
+# src/data_module/__init__.py
+from .dataset import DatasetFactory, register_dataset
+from .augmentation import AugmentationFactory
+```
+
+## Naming Conventions
+
+### Files
+
+- **Modules**: `simple_dataset.py`, `custom_model.py`
+- **Pipelines**: `training.sh`, `inference.sh`
+- **Configs**: `config.yaml`, `brain_decoder.yaml`
+- **Utilities**: `get_optimizer.py`, `helpers.py`, `compute_metrics.py`
+
+### Classes and Functions
+
+```python
+# Classes: PascalCase
+class SimpleDataset(Dataset):
+    pass
+
+class MyCustomModel(nn.Module):
+    pass
+
+# Functions and variables: snake_case
+def compute_accuracy(predictions, labels):
+    pass
+
+def get_optimizer(cfg):
+    pass
+
+learning_rate = 0.001
+batch_size = 32
+```
+
+### Constants
+
+```python
+# Constants: UPPER_SNAKE_CASE
+DEFAULT_HIDDEN_DIM = 256
+MAX_EPOCHS = 100
+LEARNING_RATE = 0.001
+```
+
+## Docstrings
+
+Use Google-style docstrings:
+
+```python
+def DatasetFactory(data_name: str) -> type:
+    """Create dataset class by name.
+
+    Args:
+        data_name: Name of the dataset to create.
+
+    Returns:
+        Dataset class if found, otherwise simple dataset.
+
+    Raises:
+        ValueError: If no dataset is found and no default exists.
+    """
+    pass
+```
+
+## Configuration-Driven Classes
+
+Model classes must be config-driven:
+
+```python
+@register_model('MyModel')
+class MyModel(nn.Module):
+    def __init__(self, cfg):
+        """Initialize model from config.
+
+        Args:
+            cfg: Hydra config object with model attributes.
+        """
+        super().__init__()
+        self.cfg = cfg
+
+        # ALL parameters from cfg
+        self.hidden_dim = cfg.model.hidden_dim
+        self.output_dim = cfg.dataset.target_size[cfg.dataset.task]
+        self.dropout = cfg.model.dropout
+
+    def forward(self, x, labels=None, **kwargs):
+        """Forward pass.
+
+        Args:
+            x: Input tensor.
+            labels: Ground truth labels (training mode).
+            **kwargs: Additional arguments.
+
+        Returns:
+            Dict with loss, labels, and logits.
+        """
+        # Implementation
+        return {"loss": loss, "labels": labels, "logits": logits}
+```
+
+## Error Handling
+
+```python
+def DatasetFactory(data_name: str) -> type:
+    """Create dataset class by name."""
+    dataset = DATASET_FACTORY.get(data_name)
+    if dataset is None:
+        available = ', '.join(DATASET_FACTORY.keys())
+        raise ValueError(
+            f"Dataset '{data_name}' not found. "
+            f"Available: {available}"
+        )
+    return dataset
+```
+
+## Logging
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+@register_dataset('custom')
+class CustomDataset(Dataset):
+    def __init__(self, cfg):
+        self.cfg = cfg
+        logger.info(f"Initializing {self.__class__.__name__}")
+        logger.debug(f"Config: {cfg.dataset}")
+```
+
+## Code Review Checklist
+
+- [ ] All functions have type hints
+- [ ] Imports are correctly ordered
+- [ ] Classes use PascalCase, functions use snake_case
+- [ ] Docstrings follow Google style
+- [ ] Model classes are config-driven
+- [ ] Registration decorators are used
+- [ ] Error messages are informative
+- [ ] Logging is added for key operations
diff --git a/.agents/skills/architecture-design/references/factory_pattern.md b/.agents/skills/architecture-design/references/factory_pattern.md
new file mode 100644
index 0000000..f700dd4
--- /dev/null
+++ b/.agents/skills/architecture-design/references/factory_pattern.md
@@ -0,0 +1,53 @@
+# Factory Pattern
+
+## Overview
+
+The Factory pattern allows dynamic creation of instances without specifying the exact class. Each module uses a factory to decouple creation from usage.
+
+## Structure
+
+```python
+# In module __init__.py (e.g., data_module/dataset/__init__.py)
+DATASET_FACTORY: Dict[str, type] = {}
+
+def DatasetFactory(data_name: str):
+    """Create dataset instance by name."""
+    dataset = DATASET_FACTORY.get(data_name, None)
+    if dataset is None:
+        # Fallback to default
+        dataset = DATASET_FACTORY.get('simple')
+    return dataset
+```
+
+## Usage
+
+```python
+# Consumer code doesn't need to know concrete class
+dataset = DatasetFactory(cfg.dataset.name)
+```
+
+## Benefits
+
+- **Loose coupling**: Consumer doesn't import concrete classes
+- **Extensibility**: Add new types without changing consumer code
+- **Fallback handling**: Graceful degradation for unknown types
+- **Centralized registry**: Single source of truth for available types
+
+## Implementation Details
+
+1. Define factory dict at module level
+2. Factory function handles lookup and fallback
+3. Return class (not instance) for deferred initialization
+4. None result triggers fallback to default implementation
+
+## Common Patterns
+
+```python
+# With config integration
+def DatasetFactory(cfg):
+    data_name = cfg.dataset.name
+    dataset_cls = DATASET_FACTORY.get(data_name)
+    if dataset_cls is None:
+        raise ValueError(f"Unknown dataset: {data_name}")
+    return dataset_cls(cfg)
+```
diff --git a/.agents/skills/architecture-design/references/registry_pattern.md b/.agents/skills/architecture-design/references/registry_pattern.md
new file mode 100644
index 0000000..0b9c34e
--- /dev/null
+++ b/.agents/skills/architecture-design/references/registry_pattern.md
@@ -0,0 +1,102 @@
+# Registry Pattern
+
+## Overview
+
+The Registry pattern allows components to register themselves via decorators, enabling automatic discovery and centralized management of available types.
+
+## Structure
+
+```python
+# In module __init__.py (e.g., data_module/dataset/__init__.py)
+from typing import Dict, Callable, TypeVar
+
+T = TypeVar('T')
+
+DATASET_FACTORY: Dict[str, type] = {}
+
+def register_dataset(name: str) -> Callable[[T], T]:
+    """Decorator to register dataset classes."""
+    def decorator(cls: T) -> T:
+        DATASET_FACTORY[name] = cls
+        return cls
+    return decorator
+```
+
+## Usage
+
+```python
+# In implementation file (e.g., simple_dataset.py)
+from data_module.dataset import register_dataset
+
+@register_dataset("simple")
+class SimpleDataset(Dataset):
+    def __init__(self, cfg):
+        # Implementation
+        pass
+```
+
+## Benefits
+
+- **Automatic registration**: Components register themselves on import
+- **Declarative**: Single decorator line replaces manual registration code
+- **Import-time discovery**: Auto-import pattern finds all implementations
+- **Type-safe**: Preserves original class type
+
+## Implementation Details
+
+1. Decorator returns the class unchanged (for immediate use)
+2. Side effect: adds class to factory dict
+3. Name parameter must be unique per module
+4. Registration happens at module import time
+
+## Advanced Patterns
+
+### Registration with Config
+
+```python
+def register_model(name: str):
+    def decorator(cls):
+        MODEL_FACTORY[name] = cls
+        # Add config validation
+        cls._config_schema = getattr(cls, '_config_schema', {})
+        return cls
+    return decorator
+```
+
+### Conditional Registration
+
+```python
+def register_dataset(name: str, experimental: bool = False):
+    def decorator(cls):
+        if not experimental or cfg.enable_experimental:
+            DATASET_FACTORY[name] = cls
+        return cls
+    return decorator
+```
+
+### Multi-Registry
+
+```python
+# Multiple registries in one module
+DATASET_FACTORY = {}
+AUGMENTATION_FACTORY = {}
+
+def register_dataset(name: str):
+    def decorator(cls):
+        DATASET_FACTORY[name] = cls
+        return cls
+    return decorator
+
+def register_augmentation(name: str):
+    def decorator(fn):
+        AUGMENTATION_FACTORY[name] = fn
+        return fn
+    return decorator
+```
+
+## Best Practices
+
+- **Unique names**: Use descriptive, unique registration names
+- **Documentation**: Document required parameters in class docstring
+- **Validation**: Validate config in `__init__`, not in decorator
+- **Consistency**: Use same naming convention across modules
diff --git a/.agents/skills/architecture-design/references/structure.md b/.agents/skills/architecture-design/references/structure.md
new file mode 100644
index 0000000..fcd6b09
--- /dev/null
+++ b/.agents/skills/architecture-design/references/structure.md
@@ -0,0 +1,150 @@
+# Detailed Directory Structure
+
+This document provides a comprehensive breakdown of the ML project template directory structure.
+
+## Root Level Files
+
+| File | Purpose |
+|------|---------|
+| `README.md` | Project documentation, installation guide, usage examples |
+| `TODO.md` | Task tracking with weekly focus and daily tasks |
+| `.gitignore` | Git ignore patterns for Python, Jupyter, IDEs, logs, cache |
+| `pyproject.toml` | Project configuration for build system and dependencies |
+| `uv.lock` | Locked dependency versions for reproducibility |
+
+## run/ - Execution Layer
+
+### pipeline/
+
+Main workflow scripts organized by stage:
+
+| Directory | Purpose |
+|-----------|---------|
+| `training/` | Training execution scripts (training.sh, inference.sh) |
+| `prepare_data/` | Data preparation and preprocessing pipelines |
+| `analysis/` | Evaluation and analysis workflows |
+
+### conf/
+
+Hydra configuration files organized by module:
+
+| Directory | Purpose |
+|-----------|---------|
+| `training/` | Training hyperparameters, model configs, optimizer settings |
+| `dataset/` | Dataset configurations, data paths, preprocessing options |
+| `model/` | Model architecture configurations |
+| `prepare_data/` | Data preparation parameters |
+| `analysis/` | Analysis and evaluation configurations |
+| `dir/` | Directory path configurations |
+| `analysis/` | Analysis-specific settings |
+
+## src/ - Source Code Layer
+
+### data_module/ - Data Processing Module
+
+```
+data_module/
+├── __init__.py              # Module exports
+├── utils.py                 # Data-specific utility functions
+├── dataset/                 # Dataset implementations
+│   ├── __init__.py          # Dataset factory and registry
+│   └── simple_dataset.py    # Simple dataset example
+├── augmentation/            # Data augmentation methods
+│   ├── __init__.py
+│   ├── mixup.py            # Mixup augmentation
+│   ├── random_shift.py     # Random shifting
+│   ├── channel_mask.py     # Channel masking
+│   ├── time_masking.py     # Time masking
+│   └── add_noise.py        # Noise injection
+├── collate_fn/             # Batch collation functions
+│   ├── __init__.py
+│   └── simple_collate_fn.py
+├── compute_metrics/        # Metrics computation
+│   ├── __init__.py
+│   └── simple_compute_metrics.py
+├── prepare_data/           # Data preparation logic
+│   ├── __init__.py
+│   ├── prepare_data.py
+│   └── generate_yaml.py
+└── data_func/              # Data utility functions
+    ├── __init__.py
+    └── simple_data_func.py
+```
+
+### model_module/ - Model Module
+
+```
+model_module/
+├── __init__.py             # Module exports
+└── model/                  # Model implementations
+    └── [model files]
+```
+
+### trainer_module/ - Training Module
+
+Contains training loop logic, validation, and checkpoint management.
+
+### analysis_module/ - Analysis Module
+
+Contains evaluation, visualization, and result analysis code.
+
+### llm/ - LLM Module
+
+LLM-related code and integrations.
+
+### utils/ - Shared Utilities
+
+```
+utils/
+├── __init__.py
+├── helpers.py              # Helper functions (import_modules, etc.)
+├── logging.py              # Logging configuration
+├── get_optimizer.py        # Optimizer factory
+├── get_scheduler.py        # Learning rate scheduler factory
+├── get_callback.py         # Training callbacks
+├── get_activation.py       # Activation functions
+└── get_checkpoint_aggregation.py  # Checkpoint handling
+```
+
+## data/ - Data Layer
+
+Following the Cookiecutter Data Science standard:
+
+| Directory | Purpose |
+|-----------|---------|
+| `raw/` | Original, immutable data dump |
+| `processed/` | Cleaned, transformed data ready for use |
+| `external/` | Data from third-party sources |
+
+## outputs/ - Output Layer
+
+| Directory | Purpose |
+|-----------|---------|
+| `logs/` | Training logs, tensorboard logs |
+| `checkpoints/` | Model checkpoints for resuming training |
+| `tables/` | Result tables, CSV outputs |
+| `figures/` | Plots, visualizations, figures |
+
+## Module Interaction Flow
+
+```
+run/pipeline/    ->  src/trainer_module/  ->  src/model_module/
+                     src/data_module/         src/utils/
+                     src/utils/
+
+run/conf/        ->  Hydra config loader  ->  All modules
+```
+
+## File Naming Conventions
+
+- **Modules**: `simple_dataset.py`, `custom_model.py`
+- **Pipelines**: `training.sh`, `inference.sh`
+- **Configs**: `config.yaml`, dataset-specific names
+- **Utilities**: Descriptive names (`get_optimizer.py`, `helpers.py`)
+
+## Python Package Structure
+
+Each module is a proper Python package:
+- Has `__init__.py` with factory/registry logic
+- Can be imported as `from src.module import Component`
+- Subpackages are automatically discovered via `import_modules()`