wisent 0.1.1__py3-none-any.whl → 0.5.2__py3-none-any.whl

wisent/core/tracking/memory.py

@@ -0,0 +1,359 @@
+"""
+Memory usage tracking for wisent-guard operations.
+
+This module provides comprehensive memory monitoring capabilities including
+GPU and CPU memory tracking, peak usage detection, and memory profiling.
+"""
+
+import gc
+import psutil
+import time
+import threading
+from typing import Dict, List, Optional, Any, Callable
+from dataclasses import dataclass, field
+from contextlib import contextmanager
+import torch
+
+from wisent.core.utils.device import resolve_default_device
+
+try:
+    import nvidia_ml_py3 as nvml
+    NVML_AVAILABLE = True
+except ImportError:
+    NVML_AVAILABLE = False
+
+
+@dataclass
+class MemorySnapshot:
+    """Snapshot of memory usage at a specific point in time."""
+    timestamp: float
+    cpu_memory_mb: float
+    cpu_memory_percent: float
+    gpu_memory_mb: Optional[float] = None
+    gpu_memory_percent: Optional[float] = None
+    allocated_tensors: Optional[int] = None
+    cached_memory_mb: Optional[float] = None
+    operation: Optional[str] = None
+
+
+@dataclass
+class MemoryStats:
+    """Aggregated memory statistics over a period."""
+    peak_cpu_mb: float
+    peak_gpu_mb: Optional[float]
+    avg_cpu_mb: float
+    avg_gpu_mb: Optional[float]
+    min_cpu_mb: float
+    min_gpu_mb: Optional[float]
+    duration_seconds: float
+    snapshots: List[MemorySnapshot] = field(default_factory=list)
+    operations: List[str] = field(default_factory=list)
+
+
+class MemoryTracker:
+    """
+    Comprehensive memory usage tracker for wisent-guard operations.
+    
+    Tracks both CPU and GPU memory usage with optional continuous monitoring.
+    """
+    
+    def __init__(
+        self,
+        track_gpu: bool = True,
+        sampling_interval: float = 0.1,
+        auto_cleanup: bool = True
+    ):
+        """
+        Initialize memory tracker.
+        
+        Args:
+            track_gpu: Whether to track GPU memory (requires CUDA)
+            sampling_interval: How often to sample memory (seconds)
+            auto_cleanup: Whether to automatically run garbage collection
+        """
+        self.device_kind = resolve_default_device()
+        self.track_gpu = track_gpu and self.device_kind in {"cuda", "mps"}
+        self.sampling_interval = sampling_interval
+        self.auto_cleanup = auto_cleanup
+        
+        self.snapshots: List[MemorySnapshot] = []
+        self.is_monitoring = False
+        self.monitor_thread: Optional[threading.Thread] = None
+        self.start_time: Optional[float] = None
+        
+        # Initialize GPU monitoring if available
+        if self.track_gpu and self.device_kind == "cuda" and NVML_AVAILABLE:
+            try:
+                nvml.nvmlInit()
+                self.gpu_handle = nvml.nvmlDeviceGetHandleByIndex(0)
+                self.gpu_available = True
+            except Exception:
+                self.gpu_available = False
+                self.gpu_handle = None
+        else:
+            self.gpu_handle = None
+            self.gpu_available = False
+    
+    def take_snapshot(self, operation: Optional[str] = None) -> MemorySnapshot:
+        """Take a single memory snapshot."""
+        timestamp = time.time()
+        
+        # CPU memory
+        process = psutil.Process()
+        memory_info = process.memory_info()
+        cpu_memory_mb = memory_info.rss / 1024 / 1024
+        cpu_memory_percent = process.memory_percent()
+        
+        # GPU memory
+        gpu_memory_mb = None
+        gpu_memory_percent = None
+        allocated_tensors = None
+        cached_memory_mb = None
+        
+        if self.track_gpu:
+            if self.device_kind == "cuda" and torch.cuda.is_available():
+                gpu_memory_mb = torch.cuda.memory_allocated() / 1024 / 1024
+                cached_memory_mb = torch.cuda.memory_reserved() / 1024 / 1024
+                allocated_tensors = len(
+                    [
+                        obj
+                        for obj in gc.get_objects()
+                        if torch.is_tensor(obj) and getattr(obj, "is_cuda", False)
+                    ]
+                )
+
+                if self.gpu_available and self.gpu_handle is not None:
+                    try:
+                        gpu_info = nvml.nvmlDeviceGetMemoryInfo(self.gpu_handle)
+                        total_gpu_mb = gpu_info.total / 1024 / 1024
+                        gpu_memory_percent = (gpu_memory_mb / total_gpu_mb) * 100
+                    except Exception:
+                        pass
+            elif self.device_kind == "mps" and hasattr(torch, "mps"):
+                try:
+                    allocated_bytes = torch.mps.current_allocated_memory()
+                except AttributeError:
+                    allocated_bytes = 0
+
+                try:
+                    cached_bytes = torch.mps.driver_allocated_memory()
+                except AttributeError:
+                    cached_bytes = allocated_bytes
+
+                gpu_memory_mb = allocated_bytes / 1024 / 1024
+                cached_memory_mb = cached_bytes / 1024 / 1024
+                allocated_tensors = len(
+                    [
+                        obj
+                        for obj in gc.get_objects()
+                        if torch.is_tensor(obj) and getattr(getattr(obj, "device", None), "type", None) == "mps"
+                    ]
+                )
+        
+        snapshot = MemorySnapshot(
+            timestamp=timestamp,
+            cpu_memory_mb=cpu_memory_mb,
+            cpu_memory_percent=cpu_memory_percent,
+            gpu_memory_mb=gpu_memory_mb,
+            gpu_memory_percent=gpu_memory_percent,
+            allocated_tensors=allocated_tensors,
+            cached_memory_mb=cached_memory_mb,
+            operation=operation
+        )
+        
+        self.snapshots.append(snapshot)
+        return snapshot
+    
+    def start_monitoring(self) -> None:
+        """Start continuous memory monitoring in a background thread."""
+        if self.is_monitoring:
+            return
+        
+        self.is_monitoring = True
+        self.start_time = time.time()
+        self.snapshots.clear()
+        
+        def monitor_loop():
+            while self.is_monitoring:
+                self.take_snapshot("continuous_monitoring")
+                time.sleep(self.sampling_interval)
+        
+        self.monitor_thread = threading.Thread(target=monitor_loop, daemon=True)
+        self.monitor_thread.start()
+    
+    def stop_monitoring(self) -> MemoryStats:
+        """Stop continuous monitoring and return aggregated statistics."""
+        if not self.is_monitoring:
+            raise ValueError("Monitoring is not active")
+        
+        self.is_monitoring = False
+        if self.monitor_thread:
+            self.monitor_thread.join()
+        
+        return self.get_stats()
+    
+    def get_stats(self) -> MemoryStats:
+        """Get aggregated memory statistics from collected snapshots."""
+        if not self.snapshots:
+            raise ValueError("No snapshots available")
+        
+        cpu_values = [s.cpu_memory_mb for s in self.snapshots]
+        gpu_values = [s.gpu_memory_mb for s in self.snapshots if s.gpu_memory_mb is not None]
+        
+        duration = self.snapshots[-1].timestamp - self.snapshots[0].timestamp
+        operations = list(set(s.operation for s in self.snapshots if s.operation))
+        
+        return MemoryStats(
+            peak_cpu_mb=max(cpu_values),
+            peak_gpu_mb=max(gpu_values) if gpu_values else None,
+            avg_cpu_mb=sum(cpu_values) / len(cpu_values),
+            avg_gpu_mb=sum(gpu_values) / len(gpu_values) if gpu_values else None,
+            min_cpu_mb=min(cpu_values),
+            min_gpu_mb=min(gpu_values) if gpu_values else None,
+            duration_seconds=duration,
+            snapshots=self.snapshots.copy(),
+            operations=operations
+        )
+    
+    def clear_cache(self) -> None:
+        """Clear GPU cache and run garbage collection."""
+        if self.auto_cleanup:
+            gc.collect()
+            if self.device_kind == "cuda" and torch.cuda.is_available():
+                torch.cuda.empty_cache()
+            elif self.device_kind == "mps" and hasattr(torch, "mps"):
+                try:
+                    torch.mps.empty_cache()
+                except AttributeError:
+                    pass
+    
+    def reset(self) -> None:
+        """Reset the tracker, clearing all snapshots."""
+        if self.is_monitoring:
+            self.stop_monitoring()
+        self.snapshots.clear()
+        self.start_time = None
+    
+    @contextmanager
+    def track_operation(self, operation_name: str):
+        """Context manager to track memory usage during a specific operation."""
+        self.take_snapshot(f"{operation_name}_start")
+        start_time = time.time()
+        
+        try:
+            yield self
+        finally:
+            end_time = time.time()
+            self.take_snapshot(f"{operation_name}_end")
+            
+            if self.auto_cleanup:
+                self.clear_cache()
+    
+    def get_current_usage(self) -> Dict[str, Any]:
+        """Get current memory usage without storing a snapshot."""
+        snapshot = self.take_snapshot("current_check")
+        self.snapshots.pop()  # Remove the snapshot we just added
+        
+        usage = {
+            "cpu_memory_mb": snapshot.cpu_memory_mb,
+            "cpu_memory_percent": snapshot.cpu_memory_percent,
+        }
+        
+        if snapshot.gpu_memory_mb is not None:
+            usage.update({
+                "gpu_memory_mb": snapshot.gpu_memory_mb,
+                "gpu_memory_percent": snapshot.gpu_memory_percent,
+                "allocated_tensors": snapshot.allocated_tensors,
+                "cached_memory_mb": snapshot.cached_memory_mb,
+            })
+        
+        return usage
+    
+    def format_stats(self, stats: MemoryStats, detailed: bool = False) -> str:
+        """Format memory statistics as a readable string."""
+        lines = [
+            "Memory Usage Statistics:",
+            f"  Duration: {stats.duration_seconds:.2f} seconds",
+            f"  CPU Memory:",
+            f"    Peak: {stats.peak_cpu_mb:.1f} MB",
+            f"    Average: {stats.avg_cpu_mb:.1f} MB", 
+            f"    Minimum: {stats.min_cpu_mb:.1f} MB",
+        ]
+        
+        if stats.peak_gpu_mb is not None:
+            lines.extend([
+                f"  GPU Memory:",
+                f"    Peak: {stats.peak_gpu_mb:.1f} MB",
+                f"    Average: {stats.avg_gpu_mb:.1f} MB",
+                f"    Minimum: {stats.min_gpu_mb:.1f} MB",
+            ])
+        
+        if stats.operations:
+            lines.append(f"  Operations: {', '.join(stats.operations)}")
+        
+        if detailed and stats.snapshots:
+            lines.append(f"  Snapshots: {len(stats.snapshots)} collected")
+            
+            # Show peak usage snapshot
+            peak_snapshot = max(stats.snapshots, key=lambda s: s.cpu_memory_mb)
+            lines.extend([
+                f"  Peak Usage Snapshot:",
+                f"    Time: {peak_snapshot.timestamp:.2f}",
+                f"    CPU: {peak_snapshot.cpu_memory_mb:.1f} MB ({peak_snapshot.cpu_memory_percent:.1f}%)",
+            ])
+            
+            if peak_snapshot.gpu_memory_mb is not None:
+                lines.append(f"    GPU: {peak_snapshot.gpu_memory_mb:.1f} MB")
+                if peak_snapshot.allocated_tensors is not None:
+                    lines.append(f"    Tensors: {peak_snapshot.allocated_tensors}")
+        
+        return "\n".join(lines)
+
+
+# Global memory tracker instance
+_global_tracker: Optional[MemoryTracker] = None
+
+
+def get_global_tracker() -> MemoryTracker:
+    """Get or create the global memory tracker instance."""
+    global _global_tracker
+    if _global_tracker is None:
+        _global_tracker = MemoryTracker()
+    return _global_tracker
+
+
+def track_memory(operation_name: str):
+    """Decorator to track memory usage of a function."""
+    def decorator(func: Callable) -> Callable:
+        def wrapper(*args, **kwargs):
+            tracker = get_global_tracker()
+            with tracker.track_operation(operation_name):
+                return func(*args, **kwargs)
+        return wrapper
+    return decorator
+
+
+def get_memory_info() -> Dict[str, Any]:
+    """Get current memory information without tracking."""
+    tracker = MemoryTracker(auto_cleanup=False)
+    return tracker.get_current_usage()
+
+
+def format_memory_usage(usage: Dict[str, Any]) -> str:
+    """Format memory usage dictionary as a readable string."""
+    lines = [
+        f"CPU Memory: {usage['cpu_memory_mb']:.1f} MB ({usage['cpu_memory_percent']:.1f}%)"
+    ]
+    
+    if 'gpu_memory_mb' in usage and usage['gpu_memory_mb'] is not None:
+        lines.append(f"GPU Memory: {usage['gpu_memory_mb']:.1f} MB")
+        if 'gpu_memory_percent' in usage and usage['gpu_memory_percent'] is not None:
+            lines[-1] += f" ({usage['gpu_memory_percent']:.1f}%)"
+        
+        if 'cached_memory_mb' in usage:
+            lines.append(f"GPU Cached: {usage['cached_memory_mb']:.1f} MB")
+        
+        if 'allocated_tensors' in usage:
+            lines.append(f"GPU Tensors: {usage['allocated_tensors']}")
+    
+    return " | ".join(lines)

wisent/core/trainers/core/__init__.py

@@ -0,0 +1,11 @@
+#1 class WisentSteeringTrainer:
+#2 trainer should load activation collector (sse provded file).
+#3 shoudl load contrastive pair set (see provided file)
+#4 should decide what type of sterring trainig method choose: caa, bipo, etc.
+#4 should be able to but from which layer we collect activation and then use for each activanis and layer steering method to obtain steering vector.
+#5 some method uses many actviations from layers aome only one. we need to be able to specify that. like user can say use layer 10, 20, 30 or use all layers from 10 to 30.
+#6 after training user need to obtain contrastive piars set with collected activatioons (see provded file) and steered vectors which need to be LayerActivations class.
+#7 we should save all the trained sterred vectors, with contrastive pairs with activations, and meta data like date, model name, layers used, method used, hyperparams used etc.
+
+# Imporatat info: we also need to sepcyfy activation collection stategy (see LayerActivations). All provded files has good descriptions/docstrings. Plse wrtire code with that in mind. create two files: atoms.py
+# where we defied all base structure for the trainers, all abtarct calss etc. and steering_trainer.py where we implement WisentSteeringTrainer class.

wisent/core/trainers/core/atoms.py

@@ -0,0 +1,45 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Dict
+
+from wisent.core.activations.core.atoms import LayerActivations
+from wisent.core.contrastive_pairs.core.set import ContrastivePairSet
+
+__all__ = [
+    "TrainingResult",
+]
+
+@dataclass(slots=True)
+class TrainingResult:
+    """
+    Container returned by a trainer after running the full pipeline.
+
+    attributes:
+        steered_vectors:
+            Per-layer steering vectors in a LayerActivations mapping. Each value
+            is typically a 1D tensor of shape [H].
+        pair_set_with_activations:
+            The original ContrastivePairSet, but with per-pair, per-layer activations
+            collected and stored in the Positive/NegativeResponse objects.
+        metadata:
+            A JSON-serializable dictionary with run metadata
+            (date, model_name, layers, method, hyperparams, aggregation, etc.).
+    """
+    steered_vectors: LayerActivations
+    pair_set_with_activations: ContrastivePairSet
+    metadata: Dict[str, Any]
+
+class BaseSteeringTrainer(ABC):
+    """
+    Abstract interface for a trainer that orchestrates:
+        1) Collecting activations for a set of contrastive pairs
+        2) Training a steering vector(s) using a chosen method
+        3) Returning a TrainingResult and (optionally) saving artifacts
+    """
+
+    @abstractmethod
+    def run(self, *args: Any, **kwargs: Any) -> TrainingResult:
+        """
+        Execute the full pipeline and return a TrainingResult.
+        """
+        ...

wisent/core/trainers/steering_trainer.py

@@ -0,0 +1,271 @@
+from __future__ import annotations
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Sequence
+
+import json
+import torch
+import datetime as _dt
+
+from wisent.core.activations.core.atoms import (
+    LayerActivations,
+    ActivationAggregationStrategy,
+    RawActivationMap,
+)
+from wisent.core.models.wisent_model import WisentModel
+
+from wisent.core.trainers.core.atoms import (
+    TrainingResult,
+    BaseSteeringTrainer
+)
+
+from wisent.core.contrastive_pairs.core.set import ContrastivePairSet
+from wisent.core.activations.activations_collector import ActivationCollector  
+from wisent.core.steering_methods.core.atoms import BaseSteeringMethod
+from wisent.core.contrastive_pairs.diagnostics import run_control_vector_diagnostics
+
+__all__ = [
+    "WisentSteeringTrainer",
+]
+
+
+logger = logging.getLogger(__name__)
+
+@dataclass(slots=True)
+class WisentSteeringTrainer(BaseSteeringTrainer):
+    """
+    Orchestrates activation collection + steering vector training for a given model and pair set.
+
+    Minimal usage:
+        trainer = WisentSteeringTrainer(model, pair_set, steering_method)
+        result = trainer.run(layers_spec=..., method_kwargs=..., aggregation=..., ...)
+        # result is a TrainingResult with steered vectors, enriched pair set, and metadata
+        trainer.save_result(output_dir)  # optional save
+    
+    arguments:
+        model: WisentModel to use for activation collection.
+        pair_set: ContrastivePairSet with pairs to use for collection and training.
+        steering_method: BaseSteeringMethod instance to use for training.
+        store_device: Device to store collected activations on (default "cpu").
+        dtype: Optional torch.dtype to cast collected activations to (default None, meaning no cast).
+    """
+
+    model: WisentModel
+    pair_set: ContrastivePairSet
+    steering_method: BaseSteeringMethod
+    store_device: str | torch.device = "cpu"
+    dtype: torch.dtype | None = None
+
+    def __post_init__(self) -> None:
+        self.collector = ActivationCollector(model=self.model, store_device=self.store_device, dtype=self.dtype)
+        self._last_result: TrainingResult | None = None
+
+    def run(
+        self,
+        layers_spec: Sequence[str] | str | int | Sequence[int] | None,
+        method_kwargs: dict[str, Any] | None = None,
+        aggregation: ActivationAggregationStrategy = ActivationAggregationStrategy.CONTINUATION_TOKEN,
+        return_full_sequence: bool = False,
+        normalize_layers: bool = False,
+        save_dir: str | Path | None = None,
+    ) -> TrainingResult:
+        """
+        Full pipeline:
+          1) Decide which layers to use (from spec or all layers if None).
+          2) Collect activations for each pair at these layers.
+          3) Train steering vectors using the selected method.
+          4) Return a TrainingResult with vectors, enriched pair set, and metadata.
+          5) Optionally save artifacts to disk.
+
+        arguments:
+            layers_spec:
+                - list like ["10","20","30"] or [10, 20, 30]
+                - range string "10-30" / "10..30"
+                - single int "12"
+                - None → use all available layers on the model
+            method:
+                Name of steering method ("caa", "bipo", ...).
+            method_kwargs:
+                Dict of hyperparameters for the method (e.g., {"normalize": True, "scale": 1.0}).
+            aggregation:
+                ActivationAggregationStrategy to use during collection when not returning
+                full sequences. Ignored if 'return_full_sequence=True'.
+            return_full_sequence:
+                If True, store full [T,H] sequences per layer (method then must know how
+                to collapse to vectors). Default False (collect [H] vectors directly).
+            normalize_layers:
+                If True, L2-normalize activations layer-wise during collection.
+            save_dir:
+                If provided, artifacts are written there. Directory is created if missing.
+
+        returns:
+            TrainingResult
+        """
+        method_kwargs = method_kwargs or {}
+
+        # 1) Resolve layer names
+        layers = self._resolve_layers(layers_spec)
+
+        # 2) Collect activations for each pair
+        for i, pair in enumerate(self.pair_set.pairs):
+            updated = self.collector.collect_for_pair(
+                pair,
+                layers=layers,
+                aggregation=aggregation,
+                return_full_sequence=return_full_sequence,
+                normalize_layers=normalize_layers,
+            )
+            self.pair_set.pairs[i] = updated  
+
+        # 3) Train using selected method
+        raw_vectors: RawActivationMap = self.steering_method.train(self.pair_set, **(method_kwargs or {}))
+
+        steered = LayerActivations(raw_vectors)
+
+        control_vector_report = run_control_vector_diagnostics(steered)
+        for issue in control_vector_report.issues:
+            log_method = logger.error if issue.severity == "critical" else logger.warning
+            log_method(
+                "[control_vector diagnostics] %s (details=%s)",
+                issue.message,
+                issue.details,
+            )
+
+        control_vector_summary = control_vector_report.summary.get("control_vectors", {})
+        control_vector_issues = [
+            {
+                "metric": issue.metric,
+                "severity": issue.severity,
+                "message": issue.message,
+                "details": issue.details,
+            }
+            for issue in control_vector_report.issues
+        ]
+
+        if control_vector_report.has_critical_issues:
+            raise ValueError("Control vector diagnostics found critical issues; see logs for specifics.")
+
+        # 4) Metadata
+        now = _dt.datetime.now().astimezone()
+        metadata: dict[str, Any] = {
+            "timestamp": now.isoformat(),
+            "model_name": getattr(self.model, "model_name", getattr(self.model, "name", None)),
+            "layers_used": layers or "all",
+            "method": self.steering_method.name,
+            "method_kwargs": method_kwargs,
+            "activation_aggregation_strategy": (None if return_full_sequence else aggregation),
+            "return_full_sequence": bool(return_full_sequence),
+            "normalize_layers": bool(normalize_layers),
+            "num_pairs": len(self.pair_set.pairs),
+            "hidden_size": getattr(self.model, "hidden_size", None),
+            "control_vector_diagnostics": control_vector_summary,
+        }
+
+        if control_vector_issues:
+            metadata["control_vector_issues"] = control_vector_issues
+
+        result = TrainingResult(steered_vectors=steered, pair_set_with_activations=self.pair_set, metadata=metadata)
+        self._last_result = result
+
+        # 5) Optional save
+        if save_dir is not None:
+            self.save_result(save_dir, result)
+
+        return result
+
+    def save_result(self, output_dir: str | Path, result: TrainingResult | None = None) -> Path:
+        """
+        Persist vectors, metadata, and the pair set (with activations) to disk.
+
+        Files written:
+            - metadata.json                (JSON)
+            - steering_vectors.pt          (torch.save of dict[layer]->tensor on CPU)
+            - pairs_with_activations.pt    (torch.save of the full ContrastivePairSet object)
+            - steering_vectors_summary.json (shapes/dtypes only, human-readable)
+
+        returns:
+            Path to the created directory.
+        """
+        result = result or self._last_result
+        if result is None:
+            raise RuntimeError("No result to save. Run the trainer first.")
+
+        out = Path(output_dir)
+        out.mkdir(parents=True, exist_ok=True)
+
+        # Vectors
+        raw_map: RawActivationMap = result.steered_vectors.to_dict()  # still tensors
+        cpu_map = {k: (v.detach().to("cpu") if isinstance(v, torch.Tensor) else v) for k, v in raw_map.items() if k != "_activation_aggregation_strategy"}
+        torch.save(cpu_map, out / "steering_vectors.pt")
+
+        # Summary (json-serializable)
+        vec_summary = {
+            k: None if v is None else {
+                "shape": tuple(v.shape),
+                "dtype": str(v.dtype),
+            }
+            for k, v in cpu_map.items()
+        }
+        (out / "steering_vectors_summary.json").write_text(json.dumps(vec_summary, indent=2))
+
+        # Metadata
+        (out / "metadata.json").write_text(json.dumps(result.metadata, indent=2))
+
+        # Full pair set with activations (Python pickle via torch.save)
+        torch.save(result.pair_set_with_activations, out / "pairs_with_activations.pt")
+
+        return out
+
+    def _resolve_layers(self, spec: Sequence[str] | str | int | Sequence[int] | None) -> list[str] | None:
+        """
+        Convert a user-facing spec into canonical layer names ("1","2",...).
+        If None, return None (meaning: use all layers in the collector/model).
+
+        arguments:
+            spec: See 'layers_spec' argument in run().
+        
+        returns:
+            Sorted list of layer names as strings, or None.
+
+        examples:
+            None -> None
+            "10-12" -> ["10","11","12"]
+            [5,10,15] -> ["5","10","15"]
+            "3,7,10..12" -> ["3","7","10","11","12"]
+            8 -> ["8"]
+        """
+        if spec is None:
+            return None
+
+        if isinstance(spec, (list, tuple)):
+            names: list[str] = []
+            for item in spec:
+                if isinstance(item, int):
+                    names.append(str(item))
+                else:
+                    names.extend(self._parse_layer_token(item))
+            return sorted(set(names), key=lambda s: (len(s), s))
+
+        if isinstance(spec, int):
+            return [str(spec)]
+
+        names: list[str] = []
+        for token in str(spec).replace(" ", "").split(","):
+            names.extend(self._parse_layer_token(token))
+        return sorted(set(names), key=lambda s: (len(s), s))
+
+    @staticmethod
+    def _parse_layer_token(token: str) -> list[str]:
+        """
+        Parse a token like "5", "10-20", "10..20" into a list of names.
+        """
+        if not token:
+            return []
+        if "-" in token or ".." in token:
+            a, b = token.replace("..", "-").split("-")
+            a_i, b_i = int(a), int(b)
+            lo, hi = (a_i, b_i) if a_i <= b_i else (b_i, a_i)
+            return [str(i) for i in range(lo, hi + 1)]
+        else:
+            return [str(int(token))]