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

tnfr/trace.py

@@ -7,25 +7,37 @@ structures as immutable snapshots.
 
 from __future__ import annotations
 
-from functools import partial
-from typing import Any, Callable, Optional, Protocol, NamedTuple, TypedDict, cast
+import warnings
 from collections.abc import Iterable, Mapping
+from types import MappingProxyType
+from typing import Any, Callable, NamedTuple, Protocol, cast
 
 from .constants import TRACE
-from .glyph_history import ensure_history, count_glyphs, append_metric
-from .import_utils import cached_import
-from .graph_utils import get_graph_mapping
-from .collections_utils import is_non_string_sequence
+from .glyph_history import append_metric, count_glyphs, ensure_history
+from .metrics.sense_index import _normalise_si_sensitivity_mapping
+from .telemetry.verbosity import (
+    TELEMETRY_VERBOSITY_DEFAULT,
+    TelemetryVerbosity,
+)
+from .types import (
+    SigmaVector,
+    TNFRGraph,
+    TraceCallback,
+    TraceFieldFn,
+    TraceFieldMap,
+    TraceFieldRegistry,
+    TraceMetadata,
+    TraceSnapshot,
+)
+from .utils import cached_import, get_graph_mapping, is_non_string_sequence
 
 
 class _KuramotoFn(Protocol):
-    def __call__(self, G: Any) -> tuple[float, float]: ...
+    def __call__(self, G: TNFRGraph) -> tuple[float, float]: ...
 
 
 class _SigmaVectorFn(Protocol):
-    def __call__(
-        self, G: Any, weight_mode: str | None = None
-    ) -> dict[str, float]: ...
+    def __call__(self, G: TNFRGraph, weight_mode: str | None = None) -> SigmaVector: ...
 
 
 class CallbackSpec(NamedTuple):
@@ -35,30 +47,77 @@ class CallbackSpec(NamedTuple):
     func: Callable[..., Any]
 
 
-class TraceMetadata(TypedDict, total=False):
-    """Metadata captured by trace field functions."""
+class TraceFieldSpec(NamedTuple):
+    """Declarative specification for a trace field producer."""
+
+    name: str
+    phase: str
+    producer: TraceFieldFn
+    tiers: tuple[TelemetryVerbosity, ...]
 
-    gamma: Mapping[str, Any]
-    grammar: Mapping[str, Any]
-    selector: str | None
-    dnfr_weights: Mapping[str, Any]
-    si_weights: Mapping[str, Any]
-    si_sensitivity: Mapping[str, Any]
-    callbacks: Mapping[str, list[str] | None]
-    thol_open_nodes: int
-    kuramoto: Mapping[str, float]
-    sigma: Mapping[str, float]
-    glyphs: Mapping[str, int]
 
+TRACE_VERBOSITY_DEFAULT = TELEMETRY_VERBOSITY_DEFAULT
+TRACE_VERBOSITY_PRESETS: dict[str, tuple[str, ...]] = {}
+_TRACE_CAPTURE_ALIASES: Mapping[str, str] = MappingProxyType(
+    {
+        "glyphs": "glyph_counts",
+    }
+)
 
-class TraceSnapshot(TraceMetadata, total=False):
-    """Trace snapshot stored in the history."""
 
-    t: float
-    phase: str
+def _canonical_capture_name(name: str) -> str:
+    """Return the canonical capture field name for ``name``."""
+
+    stripped = name.strip()
+    alias = _TRACE_CAPTURE_ALIASES.get(stripped)
+    if alias is not None:
+        return alias
+
+    lowered = stripped.lower()
+    alias = _TRACE_CAPTURE_ALIASES.get(lowered)
+    if alias is not None:
+        return alias
+
+    return stripped
+
+
+def _normalise_capture_spec(raw: Any) -> set[str]:
+    """Coerce custom capture payloads to a ``set`` of field names."""
 
+    if raw is None:
+        return set()
+    if isinstance(raw, Mapping):
+        return {_canonical_capture_name(str(name)) for name in raw.keys()}
+    if isinstance(raw, str):
+        return {_canonical_capture_name(raw)}
+    if isinstance(raw, Iterable):
+        return {_canonical_capture_name(str(name)) for name in raw}
+    return {_canonical_capture_name(str(raw))}
 
-def _kuramoto_fallback(G: Any) -> tuple[float, float]:
+
+def _resolve_trace_capture(cfg: Mapping[str, Any]) -> set[str]:
+    """Return the capture set declared by ``cfg`` respecting verbosity."""
+
+    if "capture" in cfg:
+        return _normalise_capture_spec(cfg.get("capture"))
+
+    raw_verbosity = cfg.get("verbosity", TRACE_VERBOSITY_DEFAULT)
+    verbosity = str(raw_verbosity).lower()
+    fields = TRACE_VERBOSITY_PRESETS.get(verbosity)
+    if fields is None:
+        warnings.warn(
+            (
+                "Unknown TRACE verbosity %r; falling back to %s"
+                % (raw_verbosity, TRACE_VERBOSITY_DEFAULT)
+            ),
+            UserWarning,
+            stacklevel=3,
+        )
+        fields = TRACE_VERBOSITY_PRESETS[TRACE_VERBOSITY_DEFAULT]
+    return set(fields)
+
+
+def _kuramoto_fallback(G: TNFRGraph) -> tuple[float, float]:
     return 0.0, 0.0
 
 
@@ -68,9 +127,7 @@ kuramoto_R_psi: _KuramotoFn = cast(
 )
 
 
-def _sigma_fallback(
-    G: Any, _weight_mode: str | None = None
-) -> dict[str, float]:
+def _sigma_fallback(G: TNFRGraph, _weight_mode: str | None = None) -> SigmaVector:
     """Return a null sigma vector regardless of ``_weight_mode``."""
 
     return {"x": 0.0, "y": 0.0, "mag": 0.0, "angle": 0.0, "n": 0}
@@ -79,6 +136,7 @@ def _sigma_fallback(
 # Public exports for this module
 __all__ = (
     "CallbackSpec",
+    "TraceFieldSpec",
     "TraceMetadata",
     "TraceSnapshot",
     "register_trace",
@@ -94,24 +152,28 @@ __all__ = (
 
 
 def _trace_setup(
-    G,
+    G: TNFRGraph,
 ) -> tuple[
-    Optional[dict[str, Any]], set[str], Optional[dict[str, Any]], Optional[str]
+    Mapping[str, Any] | None,
+    set[str],
+    dict[str, Any] | None,
+    str | None,
 ]:
-    """Common configuration for trace snapshots.
+    """Prepare common configuration for trace snapshots.
 
     Returns the active configuration, capture set, history and key under
     which metadata will be stored. If tracing is disabled returns
     ``(None, set(), None, None)``.
     """
 
-    cfg = G.graph.get("TRACE", TRACE)
+    cfg_raw = G.graph.get("TRACE", TRACE)
+    cfg = cfg_raw if isinstance(cfg_raw, Mapping) else TRACE
     if not cfg.get("enabled", True):
         return None, set(), None, None
 
-    capture: set[str] = set(cfg.get("capture", []))
+    capture = _resolve_trace_capture(cfg)
     hist = ensure_history(G)
-    key = cfg.get("history_key", "trace_meta")
+    key = cast(str | None, cfg.get("history_key", "trace_meta"))
     return cfg, capture, hist, key
 
 
@@ -122,21 +184,22 @@ def _callback_names(
     if isinstance(callbacks, Mapping):
         callbacks = callbacks.values()
     return [
-        cb.name
-        if cb.name is not None
-        else str(getattr(cb.func, "__name__", "fn"))
+        cb.name if cb.name is not None else str(getattr(cb.func, "__name__", "fn"))
         for cb in callbacks
     ]
 
 
-def mapping_field(G: Any, graph_key: str, out_key: str) -> TraceMetadata:
-    """Helper to copy mappings from ``G.graph`` into trace output."""
+EMPTY_MAPPING: Mapping[str, Any] = MappingProxyType({})
+
+
+def mapping_field(G: TNFRGraph, graph_key: str, out_key: str) -> TraceMetadata:
+    """Copy mappings from ``G.graph`` into trace output."""
     mapping = get_graph_mapping(
-        G, graph_key, f"G.graph[{graph_key!r}] no es un mapeo; se ignora"
+        G, graph_key, f"G.graph[{graph_key!r}] is not a mapping; ignoring"
     )
     if mapping is None:
         return {}
-    return cast(TraceMetadata, {out_key: mapping})
+    return {out_key: mapping}
 
 
 # -------------------------
@@ -145,10 +208,8 @@ def mapping_field(G: Any, graph_key: str, out_key: str) -> TraceMetadata:
 
 
 def _new_trace_meta(
-    G, phase: str
-) -> Optional[
-    tuple[TraceSnapshot, set[str], Optional[dict[str, Any]], Optional[str]]
-]:
+    G: TNFRGraph, phase: str
+) -> tuple[TraceSnapshot, set[str], dict[str, Any] | None, str | None] | None:
     """Initialise trace metadata for a ``phase``.
 
     Wraps :func:`_trace_setup` and creates the base structure with timestamp
@@ -168,9 +229,7 @@ def _new_trace_meta(
 # -------------------------
 
 
-def _trace_capture(
-    G, phase: str, fields: Mapping[str, Callable[[Any], TraceMetadata]]
-) -> None:
+def _trace_capture(G: TNFRGraph, phase: str, fields: TraceFieldMap) -> None:
     """Capture ``fields`` for ``phase`` and store the snapshot.
 
     A :class:`TraceSnapshot` is appended to the configured history when
@@ -187,7 +246,7 @@ def _trace_capture(
         return
     for name, getter in fields.items():
         if name in capture:
-            meta.update(cast(TraceSnapshot, getter(G)))
+            meta.update(getter(G))
     if hist is None or key is None:
         return
     append_metric(hist, key, meta)
@@ -198,54 +257,70 @@ def _trace_capture(
 # -------------------------
 
 
-TRACE_FIELDS: dict[str, dict[str, Callable[[Any], TraceMetadata]]] = {}
+TRACE_FIELDS: TraceFieldRegistry = {}
 
 
-def register_trace_field(
-    phase: str, name: str, func: Callable[[Any], TraceMetadata]
-) -> None:
+def register_trace_field(phase: str, name: str, func: TraceFieldFn) -> None:
     """Register ``func`` to populate trace field ``name`` during ``phase``."""
 
     TRACE_FIELDS.setdefault(phase, {})[name] = func
 
 
-gamma_field = partial(mapping_field, graph_key="GAMMA", out_key="gamma")
+def gamma_field(G: TNFRGraph) -> TraceMetadata:
+    """Expose γ-field metadata stored under ``G.graph['GAMMA']``."""
 
+    return mapping_field(G, "GAMMA", "gamma")
 
-grammar_field = partial(mapping_field, graph_key="GRAMMAR_CANON", out_key="grammar")
 
+def grammar_field(G: TNFRGraph) -> TraceMetadata:
+    """Expose canonical grammar metadata for trace emission."""
 
-dnfr_weights_field = partial(
-    mapping_field, graph_key="DNFR_WEIGHTS", out_key="dnfr_weights"
-)
+    return mapping_field(G, "GRAMMAR_CANON", "grammar")
 
 
-def selector_field(G: Any) -> TraceMetadata:
+def dnfr_weights_field(G: TNFRGraph) -> TraceMetadata:
+    return mapping_field(G, "DNFR_WEIGHTS", "dnfr_weights")
+
+
+def selector_field(G: TNFRGraph) -> TraceMetadata:
     sel = G.graph.get("glyph_selector")
-    return cast(TraceMetadata, {"selector": getattr(sel, "__name__", str(sel)) if sel else None})
+    selector_name = getattr(sel, "__name__", str(sel)) if sel else None
+    return {"selector": selector_name}
 
 
-_si_weights_field = partial(mapping_field, graph_key="_Si_weights", out_key="si_weights")
+def _si_weights_field(G: TNFRGraph) -> TraceMetadata:
+    weights = mapping_field(G, "_Si_weights", "si_weights")
+    if weights:
+        return weights
+    return {"si_weights": EMPTY_MAPPING}
 
 
-_si_sensitivity_field = partial(
-    mapping_field, graph_key="_Si_sensitivity", out_key="si_sensitivity"
-)
+def _si_sensitivity_field(G: TNFRGraph) -> TraceMetadata:
+    mapping = get_graph_mapping(
+        G,
+        "_Si_sensitivity",
+        "G.graph['_Si_sensitivity'] is not a mapping; ignoring",
+    )
+    if mapping is None:
+        return {"si_sensitivity": EMPTY_MAPPING}
+
+    normalised = _normalise_si_sensitivity_mapping(mapping, warn=True)
+
+    if normalised != mapping:
+        G.graph["_Si_sensitivity"] = normalised
 
+    return {"si_sensitivity": MappingProxyType(normalised)}
 
-def si_weights_field(G: Any) -> TraceMetadata:
+
+def si_weights_field(G: TNFRGraph) -> TraceMetadata:
     """Return sense-plane weights and sensitivity."""
 
-    return cast(
-        TraceMetadata,
-        {
-            **(_si_weights_field(G) or {"si_weights": {}}),
-            **(_si_sensitivity_field(G) or {"si_sensitivity": {}}),
-        },
-    )
+    weights = _si_weights_field(G)
+    sensitivity = _si_sensitivity_field(G)
+    return {**weights, **sensitivity}
 
 
-def callbacks_field(G: Any) -> TraceMetadata:
+def callbacks_field(G: TNFRGraph) -> TraceMetadata:
     cb = G.graph.get("callbacks")
     if not isinstance(cb, Mapping):
         return {}
@@ -255,24 +330,24 @@ def callbacks_field(G: Any) -> TraceMetadata:
             out[phase] = _callback_names(cb_map)
         else:
             out[phase] = None
-    return cast(TraceMetadata, {"callbacks": out})
+    return {"callbacks": out}
 
 
-def thol_state_field(G: Any) -> TraceMetadata:
+def thol_state_field(G: TNFRGraph) -> TraceMetadata:
     th_open = 0
     for _, nd in G.nodes(data=True):
         st = nd.get("_GRAM", {})
         if st.get("thol_open", False):
             th_open += 1
-    return cast(TraceMetadata, {"thol_open_nodes": th_open})
+    return {"thol_open_nodes": th_open}
 
 
-def kuramoto_field(G: Any) -> TraceMetadata:
+def kuramoto_field(G: TNFRGraph) -> TraceMetadata:
     R, psi = kuramoto_R_psi(G)
-    return cast(TraceMetadata, {"kuramoto": {"R": float(R), "psi": float(psi)}})
+    return {"kuramoto": {"R": float(R), "psi": float(psi)}}
 
 
-def sigma_field(G: Any) -> TraceMetadata:
+def sigma_field(G: TNFRGraph) -> TraceMetadata:
     sigma_vector_from_graph: _SigmaVectorFn = cast(
         _SigmaVectorFn,
         cached_import(
@@ -282,20 +357,17 @@ def sigma_field(G: Any) -> TraceMetadata:
         ),
     )
     sv = sigma_vector_from_graph(G)
-    return cast(
-        TraceMetadata,
-        {
-            "sigma": {
-                "x": float(sv.get("x", 0.0)),
-                "y": float(sv.get("y", 0.0)),
-                "mag": float(sv.get("mag", 0.0)),
-                "angle": float(sv.get("angle", 0.0)),
-            }
-        },
-    )
+    return {
+        "sigma": {
+            "x": float(sv.get("x", 0.0)),
+            "y": float(sv.get("y", 0.0)),
+            "mag": float(sv.get("mag", 0.0)),
+            "angle": float(sv.get("angle", 0.0)),
+        }
+    }
 
 
-def glyph_counts_field(G: Any) -> TraceMetadata:
+def glyph_counts_field(G: TNFRGraph) -> TraceMetadata:
     """Return glyph count snapshot.
 
     ``count_glyphs`` already produces a fresh mapping so no additional copy
@@ -303,21 +375,107 @@ def glyph_counts_field(G: Any) -> TraceMetadata:
     """
 
     cnt = count_glyphs(G, window=1)
-    return cast(TraceMetadata, {"glyphs": cnt})
-
+    return {"glyphs": cnt}
+
+
+TRACE_FIELD_SPECS: tuple[TraceFieldSpec, ...] = (
+    TraceFieldSpec(
+        name="gamma",
+        phase="before",
+        producer=gamma_field,
+        tiers=(
+            TelemetryVerbosity.BASIC,
+            TelemetryVerbosity.DETAILED,
+            TelemetryVerbosity.DEBUG,
+        ),
+    ),
+    TraceFieldSpec(
+        name="grammar",
+        phase="before",
+        producer=grammar_field,
+        tiers=(
+            TelemetryVerbosity.BASIC,
+            TelemetryVerbosity.DETAILED,
+            TelemetryVerbosity.DEBUG,
+        ),
+    ),
+    TraceFieldSpec(
+        name="selector",
+        phase="before",
+        producer=selector_field,
+        tiers=(
+            TelemetryVerbosity.BASIC,
+            TelemetryVerbosity.DETAILED,
+            TelemetryVerbosity.DEBUG,
+        ),
+    ),
+    TraceFieldSpec(
+        name="dnfr_weights",
+        phase="before",
+        producer=dnfr_weights_field,
+        tiers=(
+            TelemetryVerbosity.BASIC,
+            TelemetryVerbosity.DETAILED,
+            TelemetryVerbosity.DEBUG,
+        ),
+    ),
+    TraceFieldSpec(
+        name="si_weights",
+        phase="before",
+        producer=si_weights_field,
+        tiers=(
+            TelemetryVerbosity.BASIC,
+            TelemetryVerbosity.DETAILED,
+            TelemetryVerbosity.DEBUG,
+        ),
+    ),
+    TraceFieldSpec(
+        name="callbacks",
+        phase="before",
+        producer=callbacks_field,
+        tiers=(
+            TelemetryVerbosity.BASIC,
+            TelemetryVerbosity.DETAILED,
+            TelemetryVerbosity.DEBUG,
+        ),
+    ),
+    TraceFieldSpec(
+        name="thol_open_nodes",
+        phase="before",
+        producer=thol_state_field,
+        tiers=(
+            TelemetryVerbosity.BASIC,
+            TelemetryVerbosity.DETAILED,
+            TelemetryVerbosity.DEBUG,
+        ),
+    ),
+    TraceFieldSpec(
+        name="kuramoto",
+        phase="after",
+        producer=kuramoto_field,
+        tiers=(TelemetryVerbosity.DETAILED, TelemetryVerbosity.DEBUG),
+    ),
+    TraceFieldSpec(
+        name="sigma",
+        phase="after",
+        producer=sigma_field,
+        tiers=(TelemetryVerbosity.DETAILED, TelemetryVerbosity.DEBUG),
+    ),
+    TraceFieldSpec(
+        name="glyph_counts",
+        phase="after",
+        producer=glyph_counts_field,
+        tiers=(TelemetryVerbosity.DEBUG,),
+    ),
+)
 
-# Pre-register default fields
-register_trace_field("before", "gamma", gamma_field)
-register_trace_field("before", "grammar", grammar_field)
-register_trace_field("before", "selector", selector_field)
-register_trace_field("before", "dnfr_weights", dnfr_weights_field)
-register_trace_field("before", "si_weights", si_weights_field)
-register_trace_field("before", "callbacks", callbacks_field)
-register_trace_field("before", "thol_open_nodes", thol_state_field)
+TRACE_VERBOSITY_PRESETS = {
+    level.value: tuple(spec.name for spec in TRACE_FIELD_SPECS if level in spec.tiers)
+    for level in TelemetryVerbosity
+}
 
-register_trace_field("after", "kuramoto", kuramoto_field)
-register_trace_field("after", "sigma", sigma_field)
-register_trace_field("after", "glyph_counts", glyph_counts_field)
+for spec in TRACE_FIELD_SPECS:
+    register_trace_field(spec.phase, spec.name, spec.producer)
 
 
 # -------------------------
@@ -325,9 +483,8 @@ register_trace_field("after", "glyph_counts", glyph_counts_field)
 # -------------------------
 
 
-def register_trace(G) -> None:
-    """Enable before/after-step snapshots and dump operational metadata
-    to history.
+def register_trace(G: TNFRGraph) -> None:
+    """Enable before/after-step snapshots and dump operational metadata to history.
 
     Trace snapshots are stored as :class:`TraceSnapshot` entries in
     ``G.graph['history'][TRACE.history_key]`` with:
@@ -354,11 +511,11 @@ def register_trace(G) -> None:
     for phase in TRACE_FIELDS.keys():
         event = f"{phase}_step"
 
-        def _make_cb(ph):
-            def _cb(G, ctx: dict[str, Any] | None = None):
+        def _make_cb(ph: str) -> TraceCallback:
+            def _cb(graph: TNFRGraph, ctx: dict[str, Any]) -> None:
                 del ctx
 
-                _trace_capture(G, ph, TRACE_FIELDS.get(ph, {}))
+                _trace_capture(graph, ph, TRACE_FIELDS.get(ph, {}))
 
             return _cb
 

tnfr/trace.pyi

@@ -0,0 +1,40 @@
+from collections.abc import Iterable, Mapping
+from typing import Any, Callable, NamedTuple
+
+from .types import (
+    TNFRGraph,
+    TraceFieldFn,
+    TraceFieldMap,
+    TraceFieldRegistry,
+    TraceMetadata,
+    TraceSnapshot,
+)
+
+__all__: tuple[str, ...]
+
+def __getattr__(name: str) -> Any: ...
+
+class CallbackSpec(NamedTuple):
+    name: str | None
+    func: Callable[..., Any]
+
+kuramoto_R_psi: Callable[[TNFRGraph], tuple[float, float]]
+TRACE_FIELDS: TraceFieldRegistry
+
+def _callback_names(
+    callbacks: Mapping[str, CallbackSpec] | Iterable[CallbackSpec],
+) -> list[str]: ...
+def mapping_field(G: TNFRGraph, graph_key: str, out_key: str) -> TraceMetadata: ...
+def _trace_capture(G: TNFRGraph, phase: str, fields: TraceFieldMap) -> None: ...
+def register_trace_field(phase: str, name: str, func: TraceFieldFn) -> None: ...
+def gamma_field(G: TNFRGraph) -> TraceMetadata: ...
+def grammar_field(G: TNFRGraph) -> TraceMetadata: ...
+def dnfr_weights_field(G: TNFRGraph) -> TraceMetadata: ...
+def selector_field(G: TNFRGraph) -> TraceMetadata: ...
+def si_weights_field(G: TNFRGraph) -> TraceMetadata: ...
+def callbacks_field(G: TNFRGraph) -> TraceMetadata: ...
+def thol_state_field(G: TNFRGraph) -> TraceMetadata: ...
+def kuramoto_field(G: TNFRGraph) -> TraceMetadata: ...
+def sigma_field(G: TNFRGraph) -> TraceMetadata: ...
+def glyph_counts_field(G: TNFRGraph) -> TraceMetadata: ...
+def register_trace(G: TNFRGraph) -> None: ...