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

tnfr/structural.pyi

@@ -0,0 +1,46 @@
+from typing import TYPE_CHECKING, Any, Callable, Hashable, Iterable
+
+from .operators.definitions import (
+    Operator,
+    Emission,
+    Reception,
+    Coherence,
+    Dissonance,
+    Coupling,
+    Resonance,
+    Silence,
+    Expansion,
+    Contraction,
+    SelfOrganization,
+    Mutation,
+    Transition,
+    Recursivity,
+)
+
+if TYPE_CHECKING:
+    import networkx as nx
+
+__all__: tuple[str, ...]
+
+
+def __getattr__(name: str) -> Any: ...
+
+
+def create_nfr(
+    name: str,
+    *,
+    epi: float = ...,
+    vf: float = ...,
+    theta: float = ...,
+    graph: "nx.Graph" | None = ...,
+    dnfr_hook: Callable[..., None] = ...,
+) -> tuple["nx.Graph", str]: ...
+
+
+OPERATORS: dict[str, Operator]
+
+
+def validate_sequence(names: Iterable[str]) -> tuple[bool, str]: ...
+
+
+def run_sequence(G: "nx.Graph", node: Hashable, ops: Iterable[Operator]) -> None: ...

tnfr/telemetry/__init__.py

@@ -0,0 +1,13 @@
+"""Telemetry helpers for shared observability settings."""
+
+from .verbosity import (
+    TelemetryVerbosity,
+    TELEMETRY_VERBOSITY_DEFAULT,
+    TELEMETRY_VERBOSITY_LEVELS,
+)
+
+__all__ = [
+    "TelemetryVerbosity",
+    "TELEMETRY_VERBOSITY_DEFAULT",
+    "TELEMETRY_VERBOSITY_LEVELS",
+]

tnfr/telemetry/verbosity.py

@@ -0,0 +1,37 @@
+"""Canonical telemetry verbosity presets for TNFR structures.
+
+Each level expresses how much structural context is exported in traces and
+metrics:
+
+* ``basic`` preserves lightweight coherence checks for quick health probes.
+* ``detailed`` adds phase alignment and coupling diagnostics to map resonance.
+* ``debug`` captures the full glyph narrative for deep structural forensics.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class TelemetryVerbosity(str, Enum):
+    """Enumerated verbosity tiers shared by trace and metrics pipelines."""
+
+    BASIC = "basic"
+    DETAILED = "detailed"
+    DEBUG = "debug"
+
+
+TELEMETRY_VERBOSITY_LEVELS: tuple[str, ...] = tuple(
+    level.value for level in TelemetryVerbosity
+)
+"""Ordered tuple of canonical telemetry verbosity identifiers."""
+
+TELEMETRY_VERBOSITY_DEFAULT: str = TelemetryVerbosity.DEBUG.value
+"""Default telemetry verbosity preserving complete structural capture."""
+
+
+__all__ = [
+    "TelemetryVerbosity",
+    "TELEMETRY_VERBOSITY_LEVELS",
+    "TELEMETRY_VERBOSITY_DEFAULT",
+]

tnfr/tokens.py

@@ -6,9 +6,10 @@ from dataclasses import dataclass
 from enum import Enum, auto
 from typing import Any, Iterable, Optional, Sequence, Union
 
-from .types import Glyph
+from .types import Glyph, NodeId
 
-Node = Any
+Node = NodeId
+#: Alias maintained for backwards compatibility with historical token helpers.
 
 
 @dataclass(slots=True)

tnfr/tokens.pyi

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Iterable, Optional, Sequence
+
+from .types import Glyph, NodeId
+from ._compat import TypeAlias
+
+__all__: tuple[str, ...]
+
+Node: TypeAlias = NodeId
+
+
+@dataclass(slots=True)
+class WAIT:
+    steps: int = 1
+
+
+@dataclass(slots=True)
+class TARGET:
+    nodes: Optional[Iterable[Node]] = None
+
+
+@dataclass(slots=True)
+class THOL:
+    body: Sequence["Token"]
+    repeat: int = 1
+    force_close: Optional[Glyph] = None
+
+
+Token: TypeAlias = Glyph | WAIT | TARGET | THOL | str
+
+THOL_SENTINEL: object
+
+
+class OpTag(Enum):
+    TARGET = ...
+    WAIT = ...
+    GLYPH = ...
+    THOL = ...

tnfr/trace.py

@@ -7,25 +7,40 @@ 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 typing import Any, Callable, Protocol, NamedTuple, TypedDict, cast
 from collections.abc import Iterable, Mapping
+from types import MappingProxyType
 
 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 .utils import cached_import, get_graph_mapping, is_non_string_sequence
+from .metrics.sense_index import _normalise_si_sensitivity_mapping
+from .telemetry.verbosity import (
+    TelemetryVerbosity,
+    TELEMETRY_VERBOSITY_DEFAULT,
+)
+from .types import (
+    SigmaVector,
+    TNFRGraph,
+    TraceCallback,
+    TraceFieldFn,
+    TraceFieldMap,
+    TraceFieldRegistry,
+)
 
 
 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]: ...
+        self, G: TNFRGraph, weight_mode: str | None = None
+    ) -> SigmaVector:
+        ...
 
 
 class CallbackSpec(NamedTuple):
@@ -58,7 +73,77 @@ class TraceSnapshot(TraceMetadata, total=False):
     phase: str
 
 
-def _kuramoto_fallback(G: Any) -> tuple[float, float]:
+class TraceFieldSpec(NamedTuple):
+    """Declarative specification for a trace field producer."""
+
+    name: str
+    phase: str
+    producer: TraceFieldFn
+    tiers: tuple[TelemetryVerbosity, ...]
+
+
+TRACE_VERBOSITY_DEFAULT = TELEMETRY_VERBOSITY_DEFAULT
+TRACE_VERBOSITY_PRESETS: dict[str, tuple[str, ...]] = {}
+_TRACE_CAPTURE_ALIASES: Mapping[str, str] = MappingProxyType(
+    {
+        "glyphs": "glyph_counts",
+    }
+)
+
+
+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 _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
 
 
@@ -69,8 +154,8 @@ kuramoto_R_psi: _KuramotoFn = cast(
 
 
 def _sigma_fallback(
-    G: Any, _weight_mode: str | None = None
-) -> dict[str, float]:
+    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 +164,7 @@ def _sigma_fallback(
 # Public exports for this module
 __all__ = (
     "CallbackSpec",
+    "TraceFieldSpec",
     "TraceMetadata",
     "TraceSnapshot",
     "register_trace",
@@ -94,9 +180,12 @@ __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.
 
@@ -105,13 +194,14 @@ def _trace_setup(
     ``(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
 
 
@@ -129,14 +219,17 @@ def _callback_names(
     ]
 
 
-def mapping_field(G: Any, graph_key: str, out_key: str) -> TraceMetadata:
+EMPTY_MAPPING: Mapping[str, Any] = MappingProxyType({})
+
+
+def mapping_field(G: TNFRGraph, 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"
+        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 +238,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
@@ -169,7 +260,7 @@ def _new_trace_meta(
 
 
 def _trace_capture(
-    G, phase: str, fields: Mapping[str, Callable[[Any], TraceMetadata]]
+    G: TNFRGraph, phase: str, fields: TraceFieldMap
 ) -> None:
     """Capture ``fields`` for ``phase`` and store the snapshot.
 
@@ -187,7 +278,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 +289,68 @@ 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]
+    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:
+    return mapping_field(G, "GAMMA", "gamma")
 
 
-grammar_field = partial(mapping_field, graph_key="GRAMMAR_CANON", out_key="grammar")
+def grammar_field(G: TNFRGraph) -> TraceMetadata:
+    return mapping_field(G, "GRAMMAR_CANON", "grammar")
 
 
-dnfr_weights_field = partial(
-    mapping_field, graph_key="DNFR_WEIGHTS", out_key="dnfr_weights"
-)
+def dnfr_weights_field(G: TNFRGraph) -> TraceMetadata:
+    return mapping_field(G, "DNFR_WEIGHTS", "dnfr_weights")
 
 
-def selector_field(G: Any) -> TraceMetadata:
+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
 
-def si_weights_field(G: Any) -> TraceMetadata:
+    return {"si_sensitivity": MappingProxyType(normalised)}
+
+
+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 +360,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 +387,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 +405,109 @@ 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,7 +515,7 @@ register_trace_field("after", "glyph_counts", glyph_counts_field)
 # -------------------------
 
 
-def register_trace(G) -> None:
+def register_trace(G: TNFRGraph) -> None:
     """Enable before/after-step snapshots and dump operational metadata
     to history.
 
@@ -354,11 +544,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