Release v0.2.4

- Add universal DataLoader format support for analyze_layer_importance
- Support dict, tuple/list, and single tensor batch formats
- Add _prepare_batch_inputs utility function
- Document L2 norm neuron selection method
- Add TensorDataset examples to notebook and docs
- 16 new tests (11 unit + 5 integration)

Closes #12, #17, #18

Author: peremartra

CHANGELOG.md

@@ -1,13 +1,65 @@
 ## [Unreleased]
 
+---
+
+## [0.2.4] - 2026-01-10
+
+### 🎉 New Features
+
+#### Universal DataLoader Format Support for `analyze_layer_importance`
+- **Multi-Format Batch Handling**: `analyze_layer_importance` now automatically detects and handles multiple DataLoader batch formats without requiring HuggingFace dataset utilities
+- **Supported Formats**:
+  - **Dictionary**: HuggingFace-style `{'input_ids': tensor, 'attention_mask': tensor}`
+  - **Tuple/List**: PyTorch `TensorDataset` format `(input_ids, attention_mask, ...)`
+  - **Single Tensor**: Direct tensor input treated as `input_ids`
+- **Positional Mapping**: Tuple/list elements automatically map to standard transformer arguments: `[0]=input_ids`, `[1]=attention_mask`, `[2]=token_type_ids`, etc.
+- **Internal Utility**: New `_prepare_batch_inputs()` function normalizes all formats transparently
+- **Debug Logging**: Optional DEBUG-level logging shows format detection and positional mapping
+- **Zero Breaking Changes**: Existing code with dict-based DataLoaders works exactly as before
+
+**Closes Issues**: #12, #17, #18
+
 ### 📝 Documentation Updates
 
 #### Terminology Update: MAW → PPM
 - **New Nomenclature**: The neuron selection method previously known as "MAW (Maximum Absolute Weight)" is now officially documented as **PPM (Peak-to-Peak Magnitude)**, which more accurately describes the calculation method (max + |min|).
 - **Backward Compatibility**: The parameter value `"MAW"` is maintained for full backward compatibility and maps to the PPM method.
 - **Research Foundation**: PPM is formally described in: *Martra, P. (2025). Fragile Knowledge, Robust Instruction-Following: The Width Pruning Dichotomy in Llama-3.2. ArXiv. https://arxiv.org/abs/2512.22671*
 - **Updated Documentation**: All documentation files now reference PPM as the primary name with MAW noted as the legacy parameter value.
-- **No Breaking Changes**: No code changes required; all existing code using `neuron_selection_method="MAW"` continues to work exactly as before.
+
+#### Clarification: L2 Norm Neuron Selection Method
+- **Existing Feature**: The L2 norm method (`neuron_selection_method="L2"`) has been available since early versions
+- **How It Works**: Calculates neuron importance using L2 (Euclidean) norms of weight values: `||gate_weight||₂ + ||up_weight||₂`
+- **Static Only**: Supports **weight-only (static) pruning** exclusively - not compatible with data-driven mode (dataloader)
+- **Documentation Enhancement**: Added explicit warnings in usage guides about L2 limitations vs PPM/MAW data-driven capabilities
+
+### 🧪 Testing
+
+#### Comprehensive Test Coverage for Batch Format Support
+- **Unit Tests**: 11 new tests for `_prepare_batch_inputs()` covering all format variations
+- **Integration Tests**: 5 new tests for `analyze_layer_importance()` with different DataLoader types
+- **Test Coverage**: Dict batches, 2-element tuples, 3+ element tuples, lists, single tensors, None handling, device placement
+- **All Tests Pass**: 16 new tests + 95 existing tests = 111 total passing tests
+
+### 🔧 Technical Details
+
+#### Implementation
+- **File**: `optipfair/pruning/utils.py`
+- **New Function**: `_prepare_batch_inputs(batch, device)` - internal utility with underscore prefix
+- **Modified Function**: `analyze_layer_importance()` in `optipfair/pruning/depth.py` now uses normalized batch handling
+- **Device Handling**: All tensors automatically moved to model device regardless of input format
+- **Error Handling**: Clear ValueError with format hints for unsupported batch types
+
+#### Enhanced Examples
+- **layer_importance_analysis.ipynb**: Added section demonstrating TensorDataset (tuple format) usage
+- **docs/usage.md**: New examples showing analyze_layer_importance with various DataLoader formats
+
+### 🔒 Compatibility
+
+- **Fully Backward Compatible**: All existing code continues to work without modification
+- **No API Changes**: Function signatures unchanged, new functionality is transparent
+- **Python**: Requires Python >=3.8 (unchanged)
+- **Dependencies**: No new dependencies added
 
 ---
 

docs/usage.md

@@ -653,4 +653,88 @@ pruned_model = prune_model(
     pruning_type="DEPTH",
     layer_indices=layers_to_remove
 )
-```
+```
+
+### DataLoader Format Support (v0.2.4+)
+
+Starting from OptiPFair v0.2.4, `analyze_layer_importance` automatically handles multiple DataLoader batch formats, making it compatible with both HuggingFace datasets and native PyTorch structures.
+
+#### Supported Batch Formats
+
+**1. Dictionary Format (HuggingFace)**
+
+```python
+from datasets import load_dataset
+from torch.utils.data import DataLoader
+
+# HuggingFace datasets return dict batches
+dataset = load_dataset('wikitext', 'wikitext-2-raw-v1', split='train[:100]')
+tokenized = dataset.map(tokenize_function, batched=True)
+tokenized.set_format(type='torch', columns=['input_ids', 'attention_mask'])
+dataloader = DataLoader(tokenized, batch_size=8)
+
+# Batch format: {'input_ids': tensor, 'attention_mask': tensor}
+importance_scores = analyze_layer_importance(model, dataloader)
+```
+
+**2. Tuple Format (TensorDataset)**
+
+```python
+from torch.utils.data import DataLoader, TensorDataset
+
+# Tokenize texts manually
+inputs = tokenizer(
+    texts,
+    truncation=True,
+    padding='max_length',
+    max_length=512,
+    return_tensors='pt'
+)
+
+# TensorDataset returns tuples
+dataset = TensorDataset(inputs['input_ids'], inputs['attention_mask'])
+dataloader = DataLoader(dataset, batch_size=8)
+
+# Batch format: (input_ids, attention_mask)
+# Automatically mapped: [0]=input_ids, [1]=attention_mask
+importance_scores = analyze_layer_importance(model, dataloader)
+```
+
+**3. List Format (Custom Datasets)**
+
+```python
+class CustomDataset(Dataset):
+    def __getitem__(self, idx):
+        return [self.input_ids[idx], self.attention_mask[idx]]
+
+# Batch format: [input_ids, attention_mask]
+# Same positional mapping as tuples
+importance_scores = analyze_layer_importance(model, dataloader)
+```
+
+**4. Single Tensor Format**
+
+```python
+# Dataset with only input_ids (no attention_mask)
+dataset = TensorDataset(input_ids_tensor)
+dataloader = DataLoader(dataset, batch_size=8)
+
+# Batch format: single tensor
+# Automatically treated as input_ids
+importance_scores = analyze_layer_importance(model, dataloader)
+```
+
+#### Positional Mapping for Tuple/List Formats
+
+When using tuple or list batches, elements are automatically mapped to standard transformer arguments:
+
+- `[0]` → `input_ids` (required)
+- `[1]` → `attention_mask` (optional)
+- `[2]` → `token_type_ids` (optional)
+- `[3]` → `position_ids` (optional)
+- `[4]` → `head_mask` (optional)
+- `[5]` → `inputs_embeds` (optional)
+
+**Note**: All formats are fully backward compatible. Existing code continues to work without modifications.
+
+---