diffract-core 0.3.0__tar.gz → 0.3.1__tar.gz

{diffract_core-0.3.0 → diffract_core-0.3.1}/.gitignore

@@ -2,6 +2,9 @@
 model_checkpoints
 .diffract
 
+# Benchmark reports (machine-specific; regenerated by scripts/bench_pipeline.py)
+bench_pipeline_results*.json
+
 # Byte-compiled / optimized
 __pycache__/
 *.py[cod]

{diffract_core-0.3.0 → diffract_core-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diffract-core
-Version: 0.3.0
+Version: 0.3.1
 Summary: Spectral analysis of neural network weights and their evolution over training
 Project-URL: Homepage, https://github.com/Risk-AI-Research/diffract
 Project-URL: Documentation, https://risk-ai-research.github.io/diffract/
@@ -41,6 +41,8 @@ Requires-Dist: polars>=0.20.0; extra == 'all'
 Requires-Dist: pyyaml>=6.0.1; extra == 'all'
 Requires-Dist: taichi>=1.7.3; extra == 'all'
 Requires-Dist: torch>=2.7.0; extra == 'all'
+Provides-Extra: bench
+Requires-Dist: psutil>=5.9.0; extra == 'bench'
 Provides-Extra: common
 Requires-Dist: hydra-core>=1.3.0; extra == 'common'
 Requires-Dist: kaleido>=0.2.1; extra == 'common'
@@ -62,6 +64,7 @@ Requires-Dist: pandas>=2.1.0; extra == 'dev'
 Requires-Dist: plotly>=6.0.0; extra == 'dev'
 Requires-Dist: polars>=0.20.0; extra == 'dev'
 Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
+Requires-Dist: psutil>=5.9.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
 Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
 Requires-Dist: pytest-timeout>=2.4.0; extra == 'dev'
@@ -238,7 +241,9 @@ internal structure:
 
   - **PARAMETER** - Operate on individual weight matrices.
   - **IN_MODEL** - Aggregate within a single model.
-  - **CROSS_MODEL** - Compare or aggregate across models.
+  - **CROSS_MODEL** - Compare or aggregate across models. Pairwise comparisons
+    (the alignment/overlap family) compare exactly two models—scope to a pair with
+    `filter(model_ids=[a, b])`.
 
 - **Built-in Visualization**: Publication-ready Plotly plots with theming support.
 
@@ -318,14 +323,21 @@ with attn:
 Export results in various formats (`pandas`, `polars`, `dict`, `json`, or `list`):
 
 ```python
-scalars_df = session.results.export_metrics("stable_rank", export_format="pandas")
-aggregates_df = session.results.export_aggregates("stable_rank", export_format="pandas")
-
-# Other formats work the same way
-results = session.results.export_metrics("stable_rank", export_format="polars")
-results = session.results.export_metrics("stable_rank", export_format="dict")
-results = session.results.export_metrics("stable_rank", export_format="json")
-results = session.results.export_metrics("stable_rank", export_format="list")
+with session:
+    session.compute.apply("stable_rank", "log_norm")
+
+    # PARAMETER-level fields come from export_metrics
+    scalars_df = session.results.export_metrics("stable_rank", export_format="pandas")
+    # IN_MODEL / CROSS_MODEL fields come from export_aggregates
+    aggregates_df = session.results.export_aggregates(
+        "log_norm", export_format="pandas"
+    )
+
+    # Other formats work the same way
+    results = session.results.export_metrics("stable_rank", export_format="polars")
+    results = session.results.export_metrics("stable_rank", export_format="dict")
+    results = session.results.export_metrics("stable_rank", export_format="json")
+    results = session.results.export_metrics("stable_rank", export_format="list")
 ```
 
 ### Visualization
@@ -362,6 +374,19 @@ session.compute.list_available_metrics(verbose=True)
 session.compute.configure_kernel("hard_rank", rtol=1e-6)
 ```
 
+Configuration takes effect when a kernel executes. Fields already stored are reused
+as-is — `apply` skips them by field presence, without comparing stored values to the
+current configuration. To recompute under a new configuration, erase the stored fields
+first:
+
+```python
+session.results.erase("hard_rank")
+session.compute.apply("hard_rank")  # computes with rtol=1e-6
+```
+
+See [kernel configuration](https://risk-ai-research.github.io/diffract/guide/recipes/kernels_and_compute.html)
+for the erase-then-apply pattern with multi-output kernels and dependent fields.
+
 ### Session Management
 
 Parameters and results stay available whenever the session is reopened. `Session()`

{diffract_core-0.3.0 → diffract_core-0.3.1}/README.md

@@ -114,7 +114,9 @@ internal structure:
 
   - **PARAMETER** - Operate on individual weight matrices.
   - **IN_MODEL** - Aggregate within a single model.
-  - **CROSS_MODEL** - Compare or aggregate across models.
+  - **CROSS_MODEL** - Compare or aggregate across models. Pairwise comparisons
+    (the alignment/overlap family) compare exactly two models—scope to a pair with
+    `filter(model_ids=[a, b])`.
 
 - **Built-in Visualization**: Publication-ready Plotly plots with theming support.
 
@@ -194,14 +196,21 @@ with attn:
 Export results in various formats (`pandas`, `polars`, `dict`, `json`, or `list`):
 
 ```python
-scalars_df = session.results.export_metrics("stable_rank", export_format="pandas")
-aggregates_df = session.results.export_aggregates("stable_rank", export_format="pandas")
-
-# Other formats work the same way
-results = session.results.export_metrics("stable_rank", export_format="polars")
-results = session.results.export_metrics("stable_rank", export_format="dict")
-results = session.results.export_metrics("stable_rank", export_format="json")
-results = session.results.export_metrics("stable_rank", export_format="list")
+with session:
+    session.compute.apply("stable_rank", "log_norm")
+
+    # PARAMETER-level fields come from export_metrics
+    scalars_df = session.results.export_metrics("stable_rank", export_format="pandas")
+    # IN_MODEL / CROSS_MODEL fields come from export_aggregates
+    aggregates_df = session.results.export_aggregates(
+        "log_norm", export_format="pandas"
+    )
+
+    # Other formats work the same way
+    results = session.results.export_metrics("stable_rank", export_format="polars")
+    results = session.results.export_metrics("stable_rank", export_format="dict")
+    results = session.results.export_metrics("stable_rank", export_format="json")
+    results = session.results.export_metrics("stable_rank", export_format="list")
 ```
 
 ### Visualization
@@ -238,6 +247,19 @@ session.compute.list_available_metrics(verbose=True)
 session.compute.configure_kernel("hard_rank", rtol=1e-6)
 ```
 
+Configuration takes effect when a kernel executes. Fields already stored are reused
+as-is — `apply` skips them by field presence, without comparing stored values to the
+current configuration. To recompute under a new configuration, erase the stored fields
+first:
+
+```python
+session.results.erase("hard_rank")
+session.compute.apply("hard_rank")  # computes with rtol=1e-6
+```
+
+See [kernel configuration](https://risk-ai-research.github.io/diffract/guide/recipes/kernels_and_compute.html)
+for the erase-then-apply pattern with multi-output kernels and dependent fields.
+
 ### Session Management
 
 Parameters and results stay available whenever the session is reopened. `Session()`

{diffract_core-0.3.0 → diffract_core-0.3.1}/pyproject.toml

@@ -85,6 +85,7 @@ notebooks = [
     "einops >=0.7.0",
 ]
 taichi = ["taichi >=1.7.3"]
+bench = ["psutil >=5.9.0"]
 all = [
     "torch >=2.7.0",
     "plotly >=6.0.0",
@@ -115,6 +116,7 @@ dev = [
     "pandas >=2.1.0",
     "polars >=0.20.0",
     "pre-commit >=3.6.0",
+    "psutil >=5.9.0",
     "pytest >=7.4.0",
     "pytest-cov >=4.0.0",
     "pytest-mock >=3.12.0",
@@ -297,11 +299,3 @@ check-hidden = true
 name = "pypi"
 url = "https://pypi.org/simple"
 explicit = false
-
-[tool.commitizen]
-name = "cz_conventional_commits"
-tag_format = "v$version"
-version_scheme = "pep440"
-version_provider = "uv"
-update_changelog_on_bump = true
-major_version_zero = true

{diffract_core-0.3.0 → diffract_core-0.3.1}/src/diffract/__init__.py

@@ -22,9 +22,10 @@ from __future__ import annotations
 import importlib
 from typing import TYPE_CHECKING, Any
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 
 from .containers import list_profiles
+from .core.data.metadata import upgrade_metadata_index
 from .core.data.nn.params.schema import ParameterType
 from .session import ParameterOverrides, Session
 
@@ -37,6 +38,7 @@ __all__ = [
     "Session",
     "__version__",
     "list_profiles",
+    "upgrade_metadata_index",
     "viz",
 ]
 

{diffract_core-0.3.0 → diffract_core-0.3.1}/src/diffract/containers.py

@@ -181,8 +181,10 @@ class MainContainer(containers.DeclarativeContainer):
     # Configuration
     config = providers.Configuration()
 
-    # Logging configuration
-    logging_config = providers.Resource(
+    # Callable, not Resource: logging is configured once at build and must stay
+    # out of the init_resources()/shutdown_resources() lifecycle, which would
+    # otherwise re-run dictConfig on every context entry and reset user handlers.
+    logging_config = providers.Callable(
         "logging.config.dictConfig",
         config=config.logging,
     )

{diffract_core-0.3.0 → diffract_core-0.3.1}/src/diffract/core/__init__.py

@@ -1,23 +1,17 @@
 """Core module for diffract."""
 
 from diffract.core.constants import (
-    CONTEXT_SEPARATOR,
     HDF5_INDEX_DATASET,
     HDF5_INDEX_GROUP,
     HDF5_INDEX_TOMBSTONE,
-    MODELS_CONTEXT_PREFIX,
-    PARAMS_CONTEXT_PREFIX,
     REGEX_PREFIX,
     WEIGHTS_FIELD,
 )
 
 __all__ = [
-    "CONTEXT_SEPARATOR",
     "HDF5_INDEX_DATASET",
     "HDF5_INDEX_GROUP",
     "HDF5_INDEX_TOMBSTONE",
-    "MODELS_CONTEXT_PREFIX",
-    "PARAMS_CONTEXT_PREFIX",
     "REGEX_PREFIX",
     "WEIGHTS_FIELD",
 ]

{diffract_core-0.3.0 → diffract_core-0.3.1}/src/diffract/core/compute/execution/aggregation.py

@@ -5,10 +5,6 @@ from __future__ import annotations
 from collections.abc import Callable, Iterable
 from dataclasses import dataclass
 
-from diffract.core.constants import (
-    format_contextual_field_name,
-    format_field_suffix,
-)
 from diffract.core.data.nn.params.interface import IParameterView
 
 type GroupsIterator = Iterable[tuple[str, IParameterView]]
@@ -17,7 +13,7 @@ type ContextBuilder = Callable[[str, IParameterView], AggregationContext]
 
 @dataclass(frozen=True)
 class AggregationContext:
-    """Context for aggregated computations with contextual field naming.
+    """Structured context of an aggregated computation.
 
     Attributes:
         models: Model identifiers participating in aggregation.
@@ -27,16 +23,6 @@ class AggregationContext:
     models: tuple[str, ...] | None = None
     parameters: tuple[str, ...] | None = None
 
-    def to_field_suffix(self) -> str:
-        """Build a deterministic suffix from context identifiers."""
-        return format_field_suffix(models=self.models, params=self.parameters)
-
-    def create_field_name(self, field_name: str) -> str:
-        """Compose contextual field name using the context suffix."""
-        return format_contextual_field_name(
-            field_name, models=self.models, params=self.parameters
-        )
-
 
 def aggregate_parameters(
     collection: IParameterView,

{diffract_core-0.3.0 → diffract_core-0.3.1}/src/diffract/core/compute/execution/aggregation_runner.py

@@ -52,28 +52,35 @@ class AggregationKernelRunner:
         self._parallel = parallel
         self._aggregate_repository = aggregate_repository
 
-    def run(self, kernel_name: str, parameters: IParameterView) -> None:
+    def run(self, kernel_name: str, parameters: IParameterView) -> set[str]:
         """Execute kernel with aggregation across models or parameters.
 
         Args:
             kernel_name: Name of the registered kernel.
             parameters: Parameter collection to process.
+
+        Returns:
+            The set of field names actually written to the aggregate
+            repository (empty when every group was already computed, dropped by
+            a restriction, or there is no repository configured).
         """
         pending_groups = self._collect_pending_groups(kernel_name, parameters)
         if not pending_groups:
             logger.debug(
                 "Skip execution of kernel '%s': no pending groups", kernel_name
             )
-            return
+            return set()
 
         logger.info(
             "Executing kernel '%s' (%d groups)", kernel_name, len(pending_groups)
         )
 
+        written: set[str] = set()
         batches = self._batch_groups_by_budget(pending_groups, parameters)
         for batch in batches:
             self._prefetch_batch(batch, parameters)
-            self._execute_batch(kernel_name, batch)
+            written |= self._execute_batch(kernel_name, batch)
+        return written
 
     def _collect_pending_groups(
         self, kernel_name: str, parameters: IParameterView
@@ -250,8 +257,12 @@ class AggregationKernelRunner:
                 aggregate_uids.append(uid)
         return aggregate_uids
 
-    def _execute_batch(self, kernel_name: str, batch: list[PendingGroup]) -> None:
-        """Execute aggregation-level kernel on a batch with streaming writes."""
+    def _execute_batch(self, kernel_name: str, batch: list[PendingGroup]) -> set[str]:
+        """Execute aggregation-level kernel on a batch with streaming writes.
+
+        Returns:
+            The set of field names written for this batch.
+        """
         required_args = self._registry.get_fields_kernel_require(kernel_name)
         tasks: dict[tuple[str, AggregationContext], tuple[Any, ...]] = {}
 
@@ -265,12 +276,13 @@ class AggregationKernelRunner:
             self._registry.get_kernel_restrictions(kernel_name),
         )
         if not tasks:
-            return
+            return set()
 
         if self._aggregate_repository is None:
             msg = "AggregateRepository required for aggregation kernels"
             raise RuntimeError(msg)
 
+        written: set[str] = set()
         with self._aggregate_repository:
             for (group_id, context), result in self._stream_results(kernel_name, tasks):
                 logger.debug(
@@ -278,7 +290,8 @@ class AggregationKernelRunner:
                     kernel_name,
                     group_id,
                 )
-                self._store_result(kernel_name, context, result)
+                written |= self._store_result(kernel_name, context, result)
+        return written
 
     def _build_task_args(
         self, required_args: tuple[str, ...], group: PendingGroup
@@ -311,35 +324,36 @@ class AggregationKernelRunner:
         self, field_name: str, context: AggregationContext
     ) -> Any:
         """Read an aggregate value from AggregateRepository."""
-        if self._aggregate_repository is None:
-            contextual_name = context.create_field_name(field_name)
-            msg = f"AggregateRepository not configured, cannot read '{contextual_name}'"
-            raise KeyError(msg)
-
         uid = AggregateMetadata.create_uid_from_context(
             field_name=field_name,
             context_models=context.models or (),
             context_params=context.parameters or (),
         )
 
+        if self._aggregate_repository is None:
+            msg = f"AggregateRepository not configured, cannot read '{uid}'"
+            raise KeyError(msg)
+
         try:
             aggregate = self._aggregate_repository.get_proxy(uid)
         except KeyError:
-            contextual_name = context.create_field_name(field_name)
-            msg = f"Missing contextual dependency '{contextual_name}'"
+            msg = f"Missing contextual dependency '{uid}'"
             raise KeyError(msg) from None
 
         if not aggregate.has_field("value"):
-            contextual_name = context.create_field_name(field_name)
-            msg = f"Aggregate '{contextual_name}' exists but has no value"
+            msg = f"Aggregate '{uid}' exists but has no value"
             raise KeyError(msg)
 
         return aggregate.get_field("value")
 
     def _store_result(
         self, kernel_name: str, context: AggregationContext, result: Any
-    ) -> None:
-        """Store kernel result in aggregate repository."""
+    ) -> set[str]:
+        """Store kernel result in aggregate repository.
+
+        Returns:
+            The set of field names written for this result.
+        """
         normalized = self._registry.normalize_kernel_result(kernel_name, result)
         for field_name, value in normalized.items():
             aggregate = self._aggregate_repository.get_or_create(
@@ -348,6 +362,7 @@ class AggregationKernelRunner:
                 context_params=context.parameters or (),
             )
             aggregate.set_field("value", value)
+        return set(normalized.keys())
 
     def _stream_results(
         self, kernel_name: str, tasks: dict[Any, tuple[Any, ...]]

{diffract_core-0.3.0 → diffract_core-0.3.1}/src/diffract/core/compute/execution/executor.py

@@ -89,7 +89,9 @@ class KernelExecutor:
         """Reset executed kernels set, allowing re-execution."""
         self._executed.clear()
 
-    def execute(self, field_or_kernel_name: str, parameters: IParameterView) -> None:
+    def execute(
+        self, field_or_kernel_name: str, parameters: IParameterView
+    ) -> set[str]:
         """Execute a kernel or produce a field with dependency resolution.
 
         Main entry point for kernel execution. Resolves all dependencies
@@ -98,28 +100,35 @@ class KernelExecutor:
         Args:
             field_or_kernel_name: Kernel name or field name to execute/produce.
             parameters: Parameter collection to process.
+
+        Returns:
+            The set of field names actually written across the resolved
+            dependency chain (empty when everything was already computed).
         """
         if field_or_kernel_name in self._executed:
-            return
+            return set()
 
         dependencies = self._registry.resolve_dependencies(field_or_kernel_name)
 
+        written: set[str] = set()
         for dep in dependencies:
             if dep != field_or_kernel_name and dep not in self._executed:
-                self.execute(dep, parameters)
+                written |= self.execute(dep, parameters)
 
         if self._registry.has_kernel(field_or_kernel_name):
-            self._dispatch_kernel(field_or_kernel_name, parameters)
+            written |= self._dispatch_kernel(field_or_kernel_name, parameters)
             self._executed.add(field_or_kernel_name)
+        return written
 
-    def _dispatch_kernel(self, kernel_name: str, parameters: IParameterView) -> None:
+    def _dispatch_kernel(
+        self, kernel_name: str, parameters: IParameterView
+    ) -> set[str]:
         """Dispatch kernel execution to the appropriate runner."""
         apply_level = self._registry.get_kernel_apply_level(kernel_name)
 
         if apply_level == KernelApplyLevel.PARAMETER:
-            self._parameter_runner.run(kernel_name, parameters)
-        elif apply_level in (KernelApplyLevel.IN_MODEL, KernelApplyLevel.CROSS_MODEL):
-            self._aggregation_runner.run(kernel_name, parameters)
-        else:
-            msg = f"Unknown kernel apply level: {apply_level}"
-            raise RuntimeError(msg)
+            return self._parameter_runner.run(kernel_name, parameters)
+        if apply_level in (KernelApplyLevel.IN_MODEL, KernelApplyLevel.CROSS_MODEL):
+            return self._aggregation_runner.run(kernel_name, parameters)
+        msg = f"Unknown kernel apply level: {apply_level}"
+        raise RuntimeError(msg)

{diffract_core-0.3.0 → diffract_core-0.3.1}/src/diffract/core/compute/execution/parameter_runner.py

@@ -43,12 +43,16 @@ class ParameterKernelRunner:
         self._process_pool = process_pool
         self._parallel = parallel
 
-    def run(self, kernel_name: str, parameters: IParameterView) -> None:
+    def run(self, kernel_name: str, parameters: IParameterView) -> set[str]:
         """Execute kernel on individual parameters.
 
         Args:
             kernel_name: Name of the registered kernel.
             parameters: Parameter collection to process.
+
+        Returns:
+            The set of field names actually written to storage (empty when
+            every parameter already had the target fields or nothing matched).
         """
         target_fields = self._registry.get_fields_kernel_produce(kernel_name)
         pending = parameters.filter_by_fields(
@@ -60,7 +64,7 @@ class ParameterKernelRunner:
             logger.debug(
                 "Skip execution of kernel '%s': no pending parameters", kernel_name
             )
-            return
+            return set()
 
         logger.info("Executing kernel '%s'", kernel_name)
 
@@ -74,17 +78,22 @@ class ParameterKernelRunner:
             )
         )
         if not chunks:
-            return
+            return set()
 
+        written: set[str] = set()
         for chunk in chunks:
             chunk.prefetch_fields(fields=required_fields, parallel=self._parallel)
-            self._execute_batch(kernel_name, chunk)
+            written |= self._execute_batch(kernel_name, chunk)
+        return written
 
-    def _execute_batch(self, kernel_name: str, batch: IParameterView) -> None:
+    def _execute_batch(self, kernel_name: str, batch: IParameterView) -> set[str]:
         """Execute parameter-level kernel on a batch with streaming writes.
 
         Results are written immediately as they become available, reducing
         memory pressure for heavy computations (e.g., SVD matrices).
+
+        Returns:
+            The set of field names written for this batch.
         """
         required_args = self._registry.get_fields_kernel_require(kernel_name)
         tasks: dict[tuple[str, str], tuple[Any, ...]] = {}
@@ -99,16 +108,19 @@ class ParameterKernelRunner:
             self._registry.get_kernel_restrictions(kernel_name),
         )
         if not tasks:
-            return
+            return set()
 
         param_lookup = {(p.meta.model_id, p.meta.uid): p for p in batch}
 
+        written: set[str] = set()
         with batch:
             for key, result in self._stream_results(kernel_name, tasks):
                 normalized = self._registry.normalize_kernel_result(kernel_name, result)
                 param = param_lookup[key]
                 for field_name, value in normalized.items():
                     param.set_field(field_name, value)
+                    written.add(field_name)
+        return written
 
     def _stream_results(
         self,

diffract_core-0.3.1/src/diffract/core/compute/execution/restrictions.py

@@ -0,0 +1,81 @@
+"""Kernel restriction checking utilities."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Hashable
+from typing import Any
+
+from .aggregation import AggregationContext
+from .enums import KernelRestrictions
+
+logger = logging.getLogger(__name__)
+
+_BINARY_MODEL_COUNT = 2
+
+# An aggregation task id is a (group_id, AggregationContext) pair; the
+# arity is unrelated to the binary-kernel model count.
+_AGGREGATION_TASK_ARITY = 2
+
+
+def apply_restrictions_filter(
+    kernel_name: str,
+    tasks: dict[Hashable, tuple[Any, ...]],
+    restrictions: KernelRestrictions | None,
+) -> None:
+    """Drop tasks that violate kernel restrictions (mutates tasks dict).
+
+    The ``BINARY`` restriction marks a cross-model kernel that operates on a
+    model pair. A group spanning any other number of models is dropped with a
+    ``WARNING`` -- never silently -- so a mis-scoped binary kernel cannot no-op
+    unnoticed (the caller pre-validates scope and raises before reaching here;
+    this is the defense-in-depth backstop).
+
+    Args:
+        kernel_name: Name of the kernel for logging.
+        tasks: Dictionary of task_id -> args to filter in place. Aggregation
+            task ids are ``(group_id, AggregationContext)``; the model count is
+            read from the context.
+        restrictions: Optional kernel restrictions to check.
+    """
+    if not restrictions or not (restrictions & KernelRestrictions.BINARY):
+        return
+
+    to_remove: list[Hashable] = []
+    for task_id in tasks:
+        context = _task_context(task_id)
+        if context is None:
+            # BINARY is a cross-model restriction; there is nothing to enforce
+            # off the aggregation path.
+            continue
+
+        model_count = len(context.models or ())
+        if model_count != _BINARY_MODEL_COUNT:
+            logger.warning(
+                "Skipping kernel '%s' for group '%s': a binary cross-model kernel "
+                "requires exactly two models, but the group spans %d: %s",
+                kernel_name,
+                _task_label(task_id),
+                model_count,
+                list(context.models or ()),
+            )
+            to_remove.append(task_id)
+
+    for task_id in to_remove:
+        del tasks[task_id]
+
+
+def _task_context(task_id: Hashable) -> AggregationContext | None:
+    """Extract the aggregation context from a task id, if present."""
+    if isinstance(task_id, tuple) and len(task_id) == _AGGREGATION_TASK_ARITY:
+        candidate = task_id[1]
+        if isinstance(candidate, AggregationContext):
+            return candidate
+    return None
+
+
+def _task_label(task_id: Hashable) -> Any:
+    """Human-readable group label for logging."""
+    if isinstance(task_id, tuple) and task_id:
+        return task_id[0]
+    return task_id