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

tnfr/trace.py

@@ -1,134 +1,369 @@
+"""Trace logging.
+
+Field helpers avoid unnecessary copying by reusing dictionaries stored on
+the graph whenever possible.  Callers are expected to treat returned
+structures as immutable snapshots.
+"""
+
 from __future__ import annotations
-from typing import Any, Dict, List, Optional
-from collections import Counter
 
-from .constants import DEFAULTS
-from .helpers import register_callback, ensure_history, last_glifo
+from functools import partial
+from typing import Any, Callable, Optional, Protocol, NamedTuple, TypedDict, cast
+from collections.abc import Iterable, Mapping
+
+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
+
+
+class _KuramotoFn(Protocol):
+    def __call__(self, G: Any) -> tuple[float, float]: ...
+
+
+class _SigmaVectorFn(Protocol):
+    def __call__(
+        self, G: Any, weight_mode: str | None = None
+    ) -> dict[str, float]: ...
+
+
+class CallbackSpec(NamedTuple):
+    """Specification for a registered callback."""
+
+    name: str | None
+    func: Callable[..., Any]
+
+
+class TraceMetadata(TypedDict, total=False):
+    """Metadata captured by trace field functions."""
+
+    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]
+
+
+class TraceSnapshot(TraceMetadata, total=False):
+    """Trace snapshot stored in the history."""
+
+    t: float
+    phase: str
+
+
+def _kuramoto_fallback(G: Any) -> tuple[float, float]:
+    return 0.0, 0.0
+
+
+kuramoto_R_psi: _KuramotoFn = cast(
+    _KuramotoFn,
+    cached_import("tnfr.gamma", "kuramoto_R_psi", fallback=_kuramoto_fallback),
+)
+
+
+def _sigma_fallback(
+    G: Any, _weight_mode: str | None = None
+) -> dict[str, float]:
+    """Return a null sigma vector regardless of ``_weight_mode``."""
+
+    return {"x": 0.0, "y": 0.0, "mag": 0.0, "angle": 0.0, "n": 0}
 
-try:
-    from .gamma import kuramoto_R_psi
-except Exception:  # pragma: no cover
-    def kuramoto_R_psi(G):
-        return 0.0, 0.0
 
-try:
-    from .sense import sigma_vector_global
-except Exception:  # pragma: no cover
-    def sigma_vector_global(G, *args, **kwargs):
-        return {"x": 1.0, "y": 0.0, "mag": 1.0, "angle": 0.0, "n": 0}
+# Public exports for this module
+__all__ = (
+    "CallbackSpec",
+    "TraceMetadata",
+    "TraceSnapshot",
+    "register_trace",
+    "register_trace_field",
+    "_callback_names",
+    "gamma_field",
+    "grammar_field",
+)
 
 # -------------------------
-# Defaults
+# Helpers
 # -------------------------
-DEFAULTS.setdefault("TRACE", {
-    "enabled": True,
-    "capture": ["gamma", "grammar", "selector", "dnfr_weights", "si_weights", "callbacks", "thol_state", "sigma", "kuramoto", "glifo_counts"],
-    "history_key": "trace_meta",
-})
+
+
+def _trace_setup(
+    G,
+) -> tuple[
+    Optional[dict[str, Any]], set[str], Optional[dict[str, Any]], Optional[str]
+]:
+    """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)
+    if not cfg.get("enabled", True):
+        return None, set(), None, None
+
+    capture: set[str] = set(cfg.get("capture", []))
+    hist = ensure_history(G)
+    key = cfg.get("history_key", "trace_meta")
+    return cfg, capture, hist, key
+
+
+def _callback_names(
+    callbacks: Mapping[str, CallbackSpec] | Iterable[CallbackSpec],
+) -> list[str]:
+    """Return callback names from ``callbacks``."""
+    if isinstance(callbacks, Mapping):
+        callbacks = callbacks.values()
+    return [
+        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."""
+    mapping = get_graph_mapping(
+        G, graph_key, f"G.graph[{graph_key!r}] no es un mapeo; se ignora"
+    )
+    if mapping is None:
+        return {}
+    return cast(TraceMetadata, {out_key: mapping})
+
 
 # -------------------------
-# Helpers
+# Builders
 # -------------------------
 
+
+def _new_trace_meta(
+    G, phase: str
+) -> Optional[
+    tuple[TraceSnapshot, set[str], Optional[dict[str, Any]], Optional[str]]
+]:
+    """Initialise trace metadata for a ``phase``.
+
+    Wraps :func:`_trace_setup` and creates the base structure with timestamp
+    and current phase. Returns ``None`` if tracing is disabled.
+    """
+
+    cfg, capture, hist, key = _trace_setup(G)
+    if not cfg:
+        return None
+
+    meta: TraceSnapshot = {"t": float(G.graph.get("_t", 0.0)), "phase": phase}
+    return meta, capture, hist, key
+
+
 # -------------------------
 # Snapshots
 # -------------------------
 
-def _trace_before(G, *args, **kwargs):
-    if not G.graph.get("TRACE", DEFAULTS["TRACE"]).get("enabled", True):
+
+def _trace_capture(
+    G, phase: str, fields: Mapping[str, Callable[[Any], TraceMetadata]]
+) -> None:
+    """Capture ``fields`` for ``phase`` and store the snapshot.
+
+    A :class:`TraceSnapshot` is appended to the configured history when
+    tracing is active. If there is no active history or storage key the
+    capture is silently ignored.
+    """
+
+    res = _new_trace_meta(G, phase)
+    if not res:
         return
-    cfg = G.graph.get("TRACE", DEFAULTS["TRACE"])
-    capture: List[str] = list(cfg.get("capture", []))
-    hist = ensure_history(G)
-    key = cfg.get("history_key", "trace_meta")
 
-    meta: Dict[str, Any] = {"t": float(G.graph.get("_t", 0.0)), "phase": "before"}
+    meta, capture, hist, key = res
+    if not capture:
+        return
+    for name, getter in fields.items():
+        if name in capture:
+            meta.update(cast(TraceSnapshot, getter(G)))
+    if hist is None or key is None:
+        return
+    append_metric(hist, key, meta)
 
-    if "gamma" in capture:
-        meta["gamma"] = dict(G.graph.get("GAMMA", {}))
 
-    if "grammar" in capture:
-        meta["grammar"] = dict(G.graph.get("GRAMMAR_CANON", {}))
+# -------------------------
+# Registry
+# -------------------------
 
-    if "selector" in capture:
-        sel = G.graph.get("glyph_selector")
-        meta["selector"] = getattr(sel, "__name__", str(sel)) if sel else None
 
-    if "dnfr_weights" in capture:
-        mix = G.graph.get("DNFR_WEIGHTS")
-        if isinstance(mix, dict):
-            meta["dnfr_weights"] = dict(mix)
+TRACE_FIELDS: dict[str, dict[str, Callable[[Any], TraceMetadata]]] = {}
 
-    if "si_weights" in capture:
-        meta["si_weights"] = dict(G.graph.get("_Si_weights", {}))
-        meta["si_sensitivity"] = dict(G.graph.get("_Si_sensitivity", {}))
 
-    if "callbacks" in capture:
-        # si el motor guarda los callbacks, exponer nombres por fase
-        cb = G.graph.get("_callbacks")
-        if isinstance(cb, dict):
-            out = {k: [getattr(f, "__name__", "fn") for (_, f, *_rest) in v] if isinstance(v, list) else None for k, v in cb.items()}
-            meta["callbacks"] = out
+def register_trace_field(
+    phase: str, name: str, func: Callable[[Any], TraceMetadata]
+) -> None:
+    """Register ``func`` to populate trace field ``name`` during ``phase``."""
 
-    if "thol_state" in capture:
-        # cuántos nodos tienen bloque T’HOL abierto
-        th_open = 0
-        for n in G.nodes():
-            st = G.nodes[n].get("_GRAM", {})
-            if st.get("thol_open", False):
-                th_open += 1
-        meta["thol_open_nodes"] = th_open
+    TRACE_FIELDS.setdefault(phase, {})[name] = func
 
-    hist.setdefault(key, []).append(meta)
 
+gamma_field = partial(mapping_field, graph_key="GAMMA", out_key="gamma")
 
-def _trace_after(G, *args, **kwargs):
-    if not G.graph.get("TRACE", DEFAULTS["TRACE"]).get("enabled", True):
-        return
-    cfg = G.graph.get("TRACE", DEFAULTS["TRACE"])
-    capture: List[str] = list(cfg.get("capture", []))
-    hist = ensure_history(G)
-    key = cfg.get("history_key", "trace_meta")
 
-    meta: Dict[str, Any] = {"t": float(G.graph.get("_t", 0.0)), "phase": "after"}
+grammar_field = partial(mapping_field, graph_key="GRAMMAR_CANON", out_key="grammar")
+
+
+dnfr_weights_field = partial(
+    mapping_field, graph_key="DNFR_WEIGHTS", out_key="dnfr_weights"
+)
+
+
+def selector_field(G: Any) -> TraceMetadata:
+    sel = G.graph.get("glyph_selector")
+    return cast(TraceMetadata, {"selector": getattr(sel, "__name__", str(sel)) if sel else None})
+
+
+_si_weights_field = partial(mapping_field, graph_key="_Si_weights", out_key="si_weights")
+
+
+_si_sensitivity_field = partial(
+    mapping_field, graph_key="_Si_sensitivity", out_key="si_sensitivity"
+)
+
+
+def si_weights_field(G: Any) -> TraceMetadata:
+    """Return sense-plane weights and sensitivity."""
+
+    return cast(
+        TraceMetadata,
+        {
+            **(_si_weights_field(G) or {"si_weights": {}}),
+            **(_si_sensitivity_field(G) or {"si_sensitivity": {}}),
+        },
+    )
 
-    if "kuramoto" in capture:
-        R, psi = kuramoto_R_psi(G)
-        meta["kuramoto"] = {"R": float(R), "psi": float(psi)}
 
-    if "sigma" in capture:
-        sv = sigma_vector_global(G)
-        meta["sigma"] = {"x": float(sv.get("x", 1.0)), "y": float(sv.get("y", 0.0)), "mag": float(sv.get("mag", 1.0)), "angle": float(sv.get("angle", 0.0))}
+def callbacks_field(G: Any) -> TraceMetadata:
+    cb = G.graph.get("callbacks")
+    if not isinstance(cb, Mapping):
+        return {}
+    out: dict[str, list[str] | None] = {}
+    for phase, cb_map in cb.items():
+        if isinstance(cb_map, Mapping) or is_non_string_sequence(cb_map):
+            out[phase] = _callback_names(cb_map)
+        else:
+            out[phase] = None
+    return cast(TraceMetadata, {"callbacks": out})
 
-    if "glifo_counts" in capture:
-        cnt = Counter()
-        for n in G.nodes():
-            g = last_glifo(G.nodes[n])
-            if g:
-                cnt[g] += 1
-        meta["glifos"] = dict(cnt)
 
-    hist.setdefault(key, []).append(meta)
+def thol_state_field(G: Any) -> 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})
+
+
+def kuramoto_field(G: Any) -> TraceMetadata:
+    R, psi = kuramoto_R_psi(G)
+    return cast(TraceMetadata, {"kuramoto": {"R": float(R), "psi": float(psi)}})
+
+
+def sigma_field(G: Any) -> TraceMetadata:
+    sigma_vector_from_graph: _SigmaVectorFn = cast(
+        _SigmaVectorFn,
+        cached_import(
+            "tnfr.sense",
+            "sigma_vector_from_graph",
+            fallback=_sigma_fallback,
+        ),
+    )
+    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)),
+            }
+        },
+    )
+
+
+def glyph_counts_field(G: Any) -> TraceMetadata:
+    """Return glyph count snapshot.
+
+    ``count_glyphs`` already produces a fresh mapping so no additional copy
+    is taken.  Treat the returned mapping as read-only.
+    """
+
+    cnt = count_glyphs(G, window=1)
+    return cast(TraceMetadata, {"glyphs": cnt})
+
+
+# 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)
+
+register_trace_field("after", "kuramoto", kuramoto_field)
+register_trace_field("after", "sigma", sigma_field)
+register_trace_field("after", "glyph_counts", glyph_counts_field)
 
 
 # -------------------------
 # API
 # -------------------------
 
+
 def register_trace(G) -> None:
-    """Activa snapshots before/after step y vuelca metadatos operativos en history.
-
-    Guarda en G.graph['history'][TRACE.history_key] una lista de entradas {'phase': 'before'|'after', ...} con:
-      - gamma: especificación activa de Γi(R)
-      - grammar: configuración de gramática canónica
-      - selector: nombre del selector glífico
-      - dnfr_weights: mezcla ΔNFR declarada en el motor
-      - si_weights: pesos α/β/γ y sensibilidad de Si
-      - callbacks: callbacks registrados por fase (si están en G.graph['_callbacks'])
-      - thol_open_nodes: cuántos nodos tienen bloque T’HOL abierto
-      - kuramoto: (R, ψ) de la red
-      - sigma: vector global del plano del sentido
-      - glifos: conteos por glifo tras el paso
+    """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:
+      - gamma: active Γi(R) specification
+      - grammar: canonical grammar configuration
+      - selector: glyph selector name
+      - dnfr_weights: ΔNFR mix declared in the engine
+      - si_weights: α/β/γ weights and Si sensitivity
+      - callbacks: callbacks registered per phase (if in
+        ``G.graph['callbacks']``)
+      - thol_open_nodes: how many nodes have an open THOL block
+      - kuramoto: network ``(R, ψ)``
+      - sigma: global sense-plane vector
+      - glyphs: glyph counts after the step
+
+    Field helpers reuse graph dictionaries and expect them to be treated as
+    immutable snapshots by consumers.
     """
-    register_callback(G, when="before_step", func=_trace_before, name="trace_before")
-    register_callback(G, when="after_step", func=_trace_after, name="trace_after")
+    if G.graph.get("_trace_registered"):
+        return
+
+    from .callback_utils import callback_manager
+
+    for phase in TRACE_FIELDS.keys():
+        event = f"{phase}_step"
+
+        def _make_cb(ph):
+            def _cb(G, ctx: dict[str, Any] | None = None):
+                del ctx
+
+                _trace_capture(G, ph, TRACE_FIELDS.get(ph, {}))
+
+            return _cb
+
+        callback_manager.register_callback(
+            G, event=event, func=_make_cb(phase), name=f"trace_{phase}"
+        )
+
+    G.graph["_trace_registered"] = True

tnfr/types.py

@@ -1,18 +1,44 @@
+"""Type definitions and protocols shared across the engine."""
+
 from __future__ import annotations
-from dataclasses import dataclass, field
-from typing import Dict, Any
-
-
-@dataclass
-class NodeState:
-    EPI: float = 0.0
-    vf: float = 1.0   # νf
-    theta: float = 0.0  # θ
-    Si: float = 0.5
-    epi_kind: str = ""
-    extra: Dict[str, Any] = field(default_factory=dict)
-
-    def to_attrs(self) -> Dict[str, Any]:
-        d = {"EPI": self.EPI, "νf": self.vf, "θ": self.theta, "Si": self.Si, "EPI_kind": self.epi_kind}
-        d.update(self.extra)
-        return d
+
+from enum import Enum
+from typing import Any, Iterable, Protocol
+
+__all__ = ("GraphLike", "Glyph")
+
+
+class GraphLike(Protocol):
+    """Protocol for graph objects used throughout TNFR metrics.
+
+    The metrics helpers assume a single coherent graph interface so that
+    coherence, resonance and derived indicators read/write data through the
+    same structural access points.
+    """
+
+    graph: dict[str, Any]
+
+    def nodes(self, data: bool = ...) -> Iterable[Any]: ...
+
+    def number_of_nodes(self) -> int: ...
+
+    def neighbors(self, n: Any) -> Iterable[Any]: ...
+
+    def __iter__(self) -> Iterable[Any]: ...
+
+class Glyph(str, Enum):
+    """Canonical TNFR glyphs."""
+
+    AL = "AL"
+    EN = "EN"
+    IL = "IL"
+    OZ = "OZ"
+    UM = "UM"
+    RA = "RA"
+    SHA = "SHA"
+    VAL = "VAL"
+    NUL = "NUL"
+    THOL = "THOL"
+    ZHIR = "ZHIR"
+    NAV = "NAV"
+    REMESH = "REMESH"

tnfr/validators.py

@@ -1,38 +1,84 @@
-"""Validadores de invariantes TNFR."""
+"""Validation utilities."""
 
 from __future__ import annotations
-from typing import Iterable
 
-from .constants import ALIAS_EPI, DEFAULTS
-from .helpers import _get_attr
-from .sense import sigma_vector_global, GLYPHS_CANONICAL
-from .helpers import last_glifo
+import numbers
+import sys
 
+from .constants import get_aliases, get_param
+from .alias import get_attr
+from .sense import sigma_vector_from_graph
+from .helpers.numeric import within_range
+from .constants_glyphs import GLYPHS_CANONICAL_SET
 
-def _validate_epi(G) -> None:
-    emin = float(G.graph.get("EPI_MIN", DEFAULTS.get("EPI_MIN", -1.0)))
-    emax = float(G.graph.get("EPI_MAX", DEFAULTS.get("EPI_MAX", 1.0)))
-    for n in G.nodes():
-        x = float(_get_attr(G.nodes[n], ALIAS_EPI, 0.0))
-        if not (emin - 1e-9 <= x <= emax + 1e-9):
-            raise ValueError(f"EPI fuera de rango en nodo {n}: {x}")
+ALIAS_EPI = get_aliases("EPI")
+ALIAS_VF = get_aliases("VF")
+
+__all__ = ("validate_window", "run_validators")
+
+
+def validate_window(window: int, *, positive: bool = False) -> int:
+    """Validate ``window`` as an ``int`` and return it.
+
+    Non-integer values raise :class:`TypeError`. When ``positive`` is ``True``
+    the value must be strictly greater than zero; otherwise it may be zero.
+    Negative values always raise :class:`ValueError`.
+    """
+
+    if isinstance(window, bool) or not isinstance(window, numbers.Integral):
+        raise TypeError("'window' must be an integer")
+    if window < 0 or (positive and window == 0):
+        kind = "positive" if positive else "non-negative"
+        raise ValueError(f"'window'={window} must be {kind}")
+    return int(window)
+
+
+def _require_attr(data, alias, node, name):
+    """Return attribute value or raise if missing."""
+    val = get_attr(data, alias, None)
+    if val is None:
+        raise ValueError(f"Missing {name} attribute in node {node}")
+    return val
 
 
 def _validate_sigma(G) -> None:
-    sv = sigma_vector_global(G)
-    if sv.get("mag", 0.0) > 1.0 + 1e-9:
-        raise ValueError("Norma de σ excede 1")
+    sv = sigma_vector_from_graph(G)
+    if sv.get("mag", 0.0) > 1.0 + sys.float_info.epsilon:
+        raise ValueError("σ norm exceeds 1")
+
 
+def _check_epi_vf(epi, vf, epi_min, epi_max, vf_min, vf_max, n):
+    _check_range(epi, epi_min, epi_max, "EPI", n)
+    _check_range(vf, vf_min, vf_max, "VF", n)
 
-def _validate_glifos(G) -> None:
-    for n in G.nodes():
-        g = last_glifo(G.nodes[n])
-        if g and g not in GLYPHS_CANONICAL:
-            raise ValueError(f"Glifo inválido {g} en nodo {n}")
+
+def _out_of_range_msg(name, node, val):
+    return f"{name} out of range in node {node}: {val}"
+
+
+def _check_range(val, lower, upper, name, node, tol: float = 1e-9):
+    if not within_range(val, lower, upper, tol):
+        raise ValueError(_out_of_range_msg(name, node, val))
+
+
+def _check_glyph(g, n):
+    if g and g not in GLYPHS_CANONICAL_SET:
+        raise KeyError(f"Invalid glyph {g} in node {n}")
 
 
 def run_validators(G) -> None:
-    """Ejecuta todos los validadores de invariantes sobre ``G``."""
-    _validate_epi(G)
+    """Run all invariant validators on ``G`` with a single node pass."""
+    from .glyph_history import last_glyph
+
+    epi_min = float(get_param(G, "EPI_MIN"))
+    epi_max = float(get_param(G, "EPI_MAX"))
+    vf_min = float(get_param(G, "VF_MIN"))
+    vf_max = float(get_param(G, "VF_MAX"))
+
+    for n, data in G.nodes(data=True):
+        epi = _require_attr(data, ALIAS_EPI, n, "EPI")
+        vf = _require_attr(data, ALIAS_VF, n, "VF")
+        _check_epi_vf(epi, vf, epi_min, epi_max, vf_min, vf_max, n)
+        _check_glyph(last_glyph(data), n)
+
     _validate_sigma(G)
-    _validate_glifos(G)