tnfr 4.5.2__py3-none-any.whl → 6.0.0__py3-none-any.whl

tnfr/metrics/common.py

@@ -6,12 +6,10 @@ from types import MappingProxyType
 from typing import Any, Iterable, Mapping, Sequence
 
 from ..alias import collect_attr, get_attr, multi_recompute_abs_max
-from ..collections_utils import normalize_weights
 from ..constants import DEFAULTS, get_aliases
-from ..cache import edge_version_cache
 from ..helpers.numeric import clamp01, kahan_sum_nd
-from ..import_utils import get_numpy
 from ..types import GraphLike
+from ..utils import edge_version_cache, get_numpy, normalize_weights
 
 ALIAS_DNFR = get_aliases("DNFR")
 ALIAS_D2EPI = get_aliases("D2EPI")

tnfr/metrics/common.pyi

@@ -0,0 +1,15 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+GraphLike: Any
+_get_vf_dnfr_max: Any
+compute_coherence: Any
+compute_dnfr_accel_max: Any
+ensure_neighbors_map: Any
+merge_and_normalize_weights: Any
+merge_graph_weights: Any
+min_max_range: Any
+normalize_dnfr: Any

tnfr/metrics/core.py

@@ -2,12 +2,31 @@
 
 from __future__ import annotations
 
-from typing import Any
+from collections.abc import Mapping
+from typing import Any, NamedTuple, cast
+
+from ..types import (
+    GlyphSelector,
+    NodeId,
+    SelectorPreselectionChoices,
+    SelectorPreselectionMetrics,
+    SelectorPreselectionPayload,
+    TNFRGraph,
+    TraceCallback,
+    TraceFieldFn,
+    TraceFieldMap,
+    TraceFieldRegistry,
+)
 
 from ..callback_utils import CallbackEvent, callback_manager
 from ..constants import get_param
 from ..glyph_history import append_metric, ensure_history
-from ..logging_utils import get_logger
+from ..utils import get_logger
+from ..telemetry.verbosity import (
+    TelemetryVerbosity,
+    TELEMETRY_VERBOSITY_DEFAULT,
+    TELEMETRY_VERBOSITY_LEVELS,
+)
 from .coherence import (
     _aggregate_si,
     _track_stability,
@@ -15,9 +34,10 @@ from .coherence import (
     _update_phase_sync,
     _update_sigma,
     register_coherence_callbacks,
+    GLYPH_LOAD_STABILIZERS_KEY,
 )
 from .diagnosis import register_diagnosis_callbacks
-from .glyph_timing import _compute_advanced_metrics
+from .glyph_timing import _compute_advanced_metrics, GlyphMetricsHistory
 from .reporting import (
     Tg_by_node,
     Tg_global,
@@ -29,6 +49,16 @@ from .reporting import (
 logger = get_logger(__name__)
 
 __all__ = [
+    "TNFRGraph",
+    "NodeId",
+    "GlyphSelector",
+    "SelectorPreselectionMetrics",
+    "SelectorPreselectionChoices",
+    "SelectorPreselectionPayload",
+    "TraceCallback",
+    "TraceFieldFn",
+    "TraceFieldMap",
+    "TraceFieldRegistry",
     "_metrics_step",
     "register_metrics_callbacks",
     "Tg_global",
@@ -39,32 +69,124 @@ __all__ = [
 ]
 
 
-def _metrics_step(G, ctx: dict[str, Any] | None = None):
+class MetricsVerbositySpec(NamedTuple):
+    """Runtime configuration for metrics verbosity tiers."""
+
+    name: str
+    enable_phase_sync: bool
+    enable_sigma: bool
+    enable_aggregate_si: bool
+    enable_advanced: bool
+    attach_coherence_hooks: bool
+    attach_diagnosis_hooks: bool
+
+
+METRICS_VERBOSITY_DEFAULT = TELEMETRY_VERBOSITY_DEFAULT
+
+_METRICS_VERBOSITY_PRESETS: dict[str, MetricsVerbositySpec] = {}
+
+
+def _register_metrics_preset(spec: MetricsVerbositySpec) -> None:
+    if spec.name not in TELEMETRY_VERBOSITY_LEVELS:
+        raise ValueError(
+            "Unknown metrics verbosity '%s'; use %s" % (
+                spec.name,
+                ", ".join(TELEMETRY_VERBOSITY_LEVELS),
+            )
+        )
+    _METRICS_VERBOSITY_PRESETS[spec.name] = spec
+
+
+_register_metrics_preset(
+    MetricsVerbositySpec(
+        name=TelemetryVerbosity.BASIC.value,
+        enable_phase_sync=False,
+        enable_sigma=False,
+        enable_aggregate_si=False,
+        enable_advanced=False,
+        attach_coherence_hooks=False,
+        attach_diagnosis_hooks=False,
+    )
+)
+
+_detailed_spec = MetricsVerbositySpec(
+    name=TelemetryVerbosity.DETAILED.value,
+    enable_phase_sync=True,
+    enable_sigma=True,
+    enable_aggregate_si=True,
+    enable_advanced=False,
+    attach_coherence_hooks=True,
+    attach_diagnosis_hooks=False,
+)
+_register_metrics_preset(_detailed_spec)
+_register_metrics_preset(
+    _detailed_spec._replace(
+        name=TelemetryVerbosity.DEBUG.value,
+        enable_advanced=True,
+        attach_diagnosis_hooks=True,
+    )
+)
+
+
+_METRICS_BASE_HISTORY_KEYS = ("C_steps", "stable_frac", "delta_Si", "B")
+_METRICS_PHASE_HISTORY_KEYS = ("phase_sync", "kuramoto_R")
+_METRICS_SIGMA_HISTORY_KEYS = (
+    GLYPH_LOAD_STABILIZERS_KEY,
+    "glyph_load_disr",
+    "sense_sigma_x",
+    "sense_sigma_y",
+    "sense_sigma_mag",
+    "sense_sigma_angle",
+)
+_METRICS_SI_HISTORY_KEYS = ("Si_mean", "Si_hi_frac", "Si_lo_frac")
+
+
+def _resolve_metrics_verbosity(cfg: Mapping[str, Any]) -> MetricsVerbositySpec:
+    """Return the preset matching ``cfg['verbosity']``."""
+
+    raw_value = cfg.get("verbosity", METRICS_VERBOSITY_DEFAULT)
+    key = str(raw_value).lower()
+    spec = _METRICS_VERBOSITY_PRESETS.get(key)
+    if spec is not None:
+        return spec
+    logger.warning(
+        "Unknown METRICS verbosity '%s'; falling back to '%s'",
+        raw_value,
+        METRICS_VERBOSITY_DEFAULT,
+    )
+    return _METRICS_VERBOSITY_PRESETS[METRICS_VERBOSITY_DEFAULT]
+
+
+def _metrics_step(G: TNFRGraph, ctx: dict[str, Any] | None = None) -> None:
     """Update operational TNFR metrics per step."""
 
     del ctx
 
-    cfg = get_param(G, "METRICS")
+    cfg = cast(Mapping[str, Any], get_param(G, "METRICS"))
     if not cfg.get("enabled", True):
         return
 
+    spec = _resolve_metrics_verbosity(cfg)
     hist = ensure_history(G)
+    if "glyph_load_estab" in hist:
+        raise ValueError(
+            "History payloads using 'glyph_load_estab' are no longer supported. "
+            "Rename the series to 'glyph_load_stabilizers' before loading the graph."
+        )
     metrics_sentinel_key = "_metrics_history_id"
     history_id = id(hist)
     if G.graph.get(metrics_sentinel_key) != history_id:
-        for k in (
-            "C_steps",
-            "stable_frac",
-            "phase_sync",
-            "glyph_load_estab",
-            "glyph_load_disr",
-            "Si_mean",
-            "Si_hi_frac",
-            "Si_lo_frac",
-            "delta_Si",
-            "B",
-        ):
-            hist.setdefault(k, [])
+        for key in _METRICS_BASE_HISTORY_KEYS:
+            hist.setdefault(key, [])
+        if spec.enable_phase_sync:
+            for key in _METRICS_PHASE_HISTORY_KEYS:
+                hist.setdefault(key, [])
+        if spec.enable_sigma:
+            for key in _METRICS_SIGMA_HISTORY_KEYS:
+                hist.setdefault(key, [])
+        if spec.enable_aggregate_si:
+            for key in _METRICS_SI_HISTORY_KEYS:
+                hist.setdefault(key, [])
         G.graph[metrics_sentinel_key] = history_id
 
     dt = float(get_param(G, "DT"))
@@ -73,29 +195,65 @@ def _metrics_step(G, ctx: dict[str, Any] | None = None):
     t = float(G.graph.get("_t", 0.0))
 
     _update_coherence(G, hist)
-    _track_stability(G, hist, dt, eps_dnfr, eps_depi)
+
+    raw_jobs = cfg.get("n_jobs")
+    metrics_jobs: int | None
     try:
-        _update_phase_sync(G, hist)
-        _update_sigma(G, hist)
-        if hist.get("C_steps") and hist.get("stable_frac"):
-            append_metric(
-                hist,
-                "iota",
-                hist["C_steps"][-1] * hist["stable_frac"][-1],
-            )
-    except (KeyError, AttributeError, TypeError) as exc:
-        logger.debug("observer update failed: %s", exc)
+        metrics_jobs = None if raw_jobs is None else int(raw_jobs)
+    except (TypeError, ValueError):
+        metrics_jobs = None
+    else:
+        if metrics_jobs <= 0:
+            metrics_jobs = None
+
+    _track_stability(
+        G,
+        hist,
+        dt,
+        eps_dnfr,
+        eps_depi,
+        n_jobs=metrics_jobs,
+    )
+    if spec.enable_phase_sync or spec.enable_sigma:
+        try:
+            if spec.enable_phase_sync:
+                _update_phase_sync(G, hist)
+            if spec.enable_sigma:
+                _update_sigma(G, hist)
+        except (KeyError, AttributeError, TypeError) as exc:
+            logger.debug("observer update failed: %s", exc)
+
+    if hist.get("C_steps") and hist.get("stable_frac"):
+        append_metric(
+            hist,
+            "iota",
+            hist["C_steps"][-1] * hist["stable_frac"][-1],
+        )
+
+    if spec.enable_aggregate_si:
+        _aggregate_si(G, hist, n_jobs=metrics_jobs)
 
-    _aggregate_si(G, hist)
-    _compute_advanced_metrics(G, hist, t, dt, cfg)
+    if spec.enable_advanced:
+        _compute_advanced_metrics(
+            G,
+            cast(GlyphMetricsHistory, hist),
+            t,
+            dt,
+            cfg,
+            n_jobs=metrics_jobs,
+        )
 
 
-def register_metrics_callbacks(G) -> None:
+def register_metrics_callbacks(G: TNFRGraph) -> None:
+    cfg = cast(Mapping[str, Any], get_param(G, "METRICS"))
+    spec = _resolve_metrics_verbosity(cfg)
     callback_manager.register_callback(
         G,
         event=CallbackEvent.AFTER_STEP.value,
         func=_metrics_step,
         name="metrics_step",
     )
-    register_coherence_callbacks(G)
-    register_diagnosis_callbacks(G)
+    if spec.attach_coherence_hooks:
+        register_coherence_callbacks(G)
+    if spec.attach_diagnosis_hooks:
+        register_diagnosis_callbacks(G)

tnfr/metrics/core.pyi

@@ -0,0 +1,13 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+Tg_by_node: Any
+Tg_global: Any
+_metrics_step: Any
+glyph_top: Any
+glyphogram_series: Any
+latency_series: Any
+register_metrics_callbacks: Any