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

tnfr/sense.py

@@ -1,31 +1,39 @@
-"""Sense calculations."""
+"""Sense calculations and structural operator symbol vector analysis.
+
+This module implements the sense index (Si) calculation and related vector
+operations for analyzing the distribution of structural operator applications.
+
+The 'glyph rose' visualization represents the distribution of structural operator
+symbols in a circular format, where each glyph corresponds to an angle representing
+the associated structural operator.
+"""
 
 from __future__ import annotations
-from typing import TypeVar
-from collections.abc import Iterable, Mapping
+
 import math
 from collections import Counter
+from collections.abc import Iterable, Iterator, Mapping
 from itertools import tee
+from typing import Any, Callable, TypeVar
 
-import networkx as nx  # type: ignore[import-untyped]
+import networkx as nx
 
-from .constants import get_aliases, get_graph_param
 from .alias import get_attr
-from .helpers.numeric import clamp01, kahan_sum_nd
-from .import_utils import get_numpy
-from .callback_utils import CallbackEvent, callback_manager
-from .glyph_history import (
-    ensure_history,
-    last_glyph,
-    count_glyphs,
-    append_metric,
-)
-from .constants_glyphs import (
+from .utils import CallbackEvent, callback_manager
+from .config.constants import (
     ANGLE_MAP,
     GLYPHS_CANONICAL,
 )
+from .constants import get_graph_param
+from .constants.aliases import ALIAS_EPI, ALIAS_SI
+from .glyph_history import append_metric, count_glyphs, ensure_history
+from .glyph_runtime import last_glyph
+from .utils import clamp01, kahan_sum_nd
+from .types import NodeId, SigmaVector, TNFRGraph
+from .utils import get_numpy
+
 # -------------------------
-# Canon: orden circular de glyphs y ángulos
+# Canon: circular glyph order and angles
 # -------------------------
 
 GLYPH_UNITS: dict[str, complex] = {
@@ -45,10 +53,9 @@ __all__ = (
 )
 
 # -------------------------
-# Utilidades básicas
+# Basic utilities
 # -------------------------
 
-
 T = TypeVar("T")
 
 
@@ -58,35 +65,42 @@ def _resolve_glyph(g: str, mapping: Mapping[str, T]) -> T:
     try:
         return mapping[g]
     except KeyError as e:  # pragma: no cover - small helper
-        raise KeyError(f"Glyph desconocido: {g}") from e
+        raise KeyError(f"Unknown glyph: {g}") from e
 
 
 def glyph_angle(g: str) -> float:
-    """Return angle for glyph ``g``."""
+    """Return the canonical angle for structural operator symbol ``g``.
+
+    Each structural operator symbol (glyph) is mapped to a specific angle
+    in the circular representation used for sense vector calculations.
+    """
 
     return float(_resolve_glyph(g, ANGLE_MAP))
 
 
 def glyph_unit(g: str) -> complex:
-    """Return unit vector for glyph ``g``."""
+    """Return the unit vector for structural operator symbol ``g``.
 
-    return _resolve_glyph(g, GLYPH_UNITS)
+    Each structural operator symbol (glyph) corresponds to a unit vector
+    in the complex plane, used for aggregating operator applications.
+    """
 
+    return _resolve_glyph(g, GLYPH_UNITS)
 
-ALIAS_SI = get_aliases("SI")
-ALIAS_EPI = get_aliases("EPI")
 
-MODE_FUNCS = {
+MODE_FUNCS: dict[str, Callable[[Mapping[str, Any]], float]] = {
     "Si": lambda nd: clamp01(get_attr(nd, ALIAS_SI, 0.5)),
     "EPI": lambda nd: max(0.0, get_attr(nd, ALIAS_EPI, 0.0)),
 }
 
 
-def _weight(nd, mode: str) -> float:
+def _weight(nd: Mapping[str, Any], mode: str) -> float:
     return MODE_FUNCS.get(mode, lambda _: 1.0)(nd)
 
 
-def _node_weight(nd, weight_mode: str) -> tuple[str, float, complex] | None:
+def _node_weight(
+    nd: Mapping[str, Any], weight_mode: str
+) -> tuple[str, float, complex] | None:
     """Return ``(glyph, weight, weighted_unit)`` or ``None`` if no glyph."""
     g = last_glyph(nd)
     if not g:
@@ -96,7 +110,7 @@ def _node_weight(nd, weight_mode: str) -> tuple[str, float, complex] | None:
     return g, w, z
 
 
-def _sigma_cfg(G):
+def _sigma_cfg(G: TNFRGraph) -> dict[str, Any]:
     return get_graph_param(G, "SIGMA", dict)
 
 
@@ -110,7 +124,7 @@ def _to_complex(val: complex | float | int) -> complex:
     raise TypeError("values must be an iterable of real or complex numbers")
 
 
-def _empty_sigma(fallback_angle: float) -> dict[str, float]:
+def _empty_sigma(fallback_angle: float) -> SigmaVector:
     """Return an empty σ-vector with ``fallback_angle``.
 
     Helps centralise the default structure returned when no values are
@@ -127,14 +141,14 @@ def _empty_sigma(fallback_angle: float) -> dict[str, float]:
 
 
 # -------------------------
-# σ por nodo y σ global
+# σ per node and global σ
 # -------------------------
 
 
 def _sigma_from_iterable(
     values: Iterable[complex | float | int] | complex | float | int,
     fallback_angle: float = 0.0,
-) -> dict[str, float]:
+) -> SigmaVector:
     """Normalise vectors in the σ-plane.
 
     ``values`` may contain complex or real numbers; real inputs are promoted to
@@ -142,7 +156,9 @@ def _sigma_from_iterable(
     number of processed values under the ``"n"`` key.
     """
 
-    if isinstance(values, Iterable) and not isinstance(values, (str, bytes, bytearray, Mapping)):
+    if isinstance(values, Iterable) and not isinstance(
+        values, (str, bytes, bytearray, Mapping)
+    ):
         iterator = iter(values)
     else:
         iterator = iter((values,))
@@ -159,15 +175,15 @@ def _sigma_from_iterable(
         mag = float(np.hypot(x, y))
         ang = float(np.arctan2(y, x)) if mag > 0 else float(fallback_angle)
         return {
-            "x": x,
-            "y": y,
-            "mag": mag,
-            "angle": ang,
-            "n": cnt,
+            "x": float(x),
+            "y": float(y),
+            "mag": float(mag),
+            "angle": float(ang),
+            "n": int(cnt),
         }
     cnt = 0
 
-    def pair_iter():
+    def pair_iter() -> Iterator[tuple[float, float]]:
         nonlocal cnt
         for val in iterator:
             z = _to_complex(val)
@@ -188,24 +204,30 @@ def _sigma_from_iterable(
         "y": float(y),
         "mag": float(mag),
         "angle": float(ang),
-        "n": cnt,
+        "n": int(cnt),
     }
 
 
-def _ema_update(
-    prev: dict[str, float], current: dict[str, float], alpha: float
-) -> dict[str, float]:
+def _ema_update(prev: SigmaVector, current: SigmaVector, alpha: float) -> SigmaVector:
     """Exponential moving average update for σ vectors."""
     x = (1 - alpha) * prev["x"] + alpha * current["x"]
     y = (1 - alpha) * prev["y"] + alpha * current["y"]
     mag = math.hypot(x, y)
     ang = math.atan2(y, x)
-    return {"x": x, "y": y, "mag": mag, "angle": ang, "n": current.get("n", 0)}
+    return {
+        "x": float(x),
+        "y": float(y),
+        "mag": float(mag),
+        "angle": float(ang),
+        "n": int(current["n"]),
+    }
 
 
 def _sigma_from_nodes(
-    nodes: Iterable[dict], weight_mode: str, fallback_angle: float = 0.0
-) -> tuple[dict[str, float], list[tuple[str, float, complex]]]:
+    nodes: Iterable[Mapping[str, Any]],
+    weight_mode: str,
+    fallback_angle: float = 0.0,
+) -> tuple[SigmaVector, list[tuple[str, float, complex]]]:
     """Aggregate weighted glyph vectors for ``nodes``.
 
     Returns the aggregated σ vector and the list of ``(glyph, weight, vector)``
@@ -218,8 +240,10 @@ def _sigma_from_nodes(
 
 
 def sigma_vector_node(
-    G, n, weight_mode: str | None = None
-) -> dict[str, float] | None:
+    G: TNFRGraph, n: NodeId, weight_mode: str | None = None
+) -> SigmaVector | None:
+    """Return the σ vector for node ``n`` using the configured weighting."""
+
     cfg = _sigma_cfg(G)
     nd = G.nodes[n]
     weight_mode = weight_mode or cfg.get("weight", "Si")
@@ -229,11 +253,12 @@ def sigma_vector_node(
     g, w, _ = nws[0]
     if sv["mag"] == 0:
         sv["angle"] = glyph_angle(g)
-    sv.update({"glyph": g, "w": float(w)})
+    sv["glyph"] = g
+    sv["w"] = float(w)
     return sv
 
 
-def sigma_vector(dist: dict[str, float]) -> dict[str, float]:
+def sigma_vector(dist: Mapping[str, float]) -> SigmaVector:
     """Compute Σ⃗ from a glyph distribution.
 
     ``dist`` may contain raw counts or proportions. All ``(glyph, weight)``
@@ -246,8 +271,8 @@ def sigma_vector(dist: dict[str, float]) -> dict[str, float]:
 
 
 def sigma_vector_from_graph(
-    G: nx.Graph, weight_mode: str | None = None
-) -> dict[str, float]:
+    G: TNFRGraph, weight_mode: str | None = None
+) -> SigmaVector:
     """Global vector in the σ sense plane for a graph.
 
     Parameters
@@ -264,34 +289,34 @@ def sigma_vector_from_graph(
     """
 
     if not isinstance(G, nx.Graph):
-        raise TypeError("sigma_vector_from_graph requiere un networkx.Graph")
+        raise TypeError("sigma_vector_from_graph requires a networkx.Graph")
 
     cfg = _sigma_cfg(G)
     weight_mode = weight_mode or cfg.get("weight", "Si")
-    sv, _ = _sigma_from_nodes(
-        (nd for _, nd in G.nodes(data=True)), weight_mode
-    )
+    sv, _ = _sigma_from_nodes((nd for _, nd in G.nodes(data=True)), weight_mode)
     return sv
 
 
 # -------------------------
-# Historia / series
+# History / series
 # -------------------------
 
 
-def push_sigma_snapshot(G, t: float | None = None) -> None:
+def push_sigma_snapshot(G: TNFRGraph, t: float | None = None) -> None:
+    """Record a global σ snapshot (and optional per-node traces) for ``G``."""
+
     cfg = _sigma_cfg(G)
     if not cfg.get("enabled", True):
         return
 
-    # Cache local de la historia para evitar llamadas repetidas
+    # Local history cache to avoid repeated lookups
     hist = ensure_history(G)
     key = cfg.get("history_key", "sigma_global")
 
     weight_mode = cfg.get("weight", "Si")
     sv = sigma_vector_from_graph(G, weight_mode)
 
-    # Suavizado exponencial (EMA) opcional
+    # Optional exponential smoothing (EMA)
     alpha = float(cfg.get("smooth", 0.0))
     if alpha > 0 and hist.get(key):
         sv = _ema_update(hist[key][-1], sv, alpha)
@@ -301,11 +326,11 @@ def push_sigma_snapshot(G, t: float | None = None) -> None:
 
     append_metric(hist, key, sv)
 
-    # Conteo de glyphs por paso (útil para rosa glífica)
+    # Glyph count per step (useful for the glyph rose)
     counts = count_glyphs(G, last_only=True)
     append_metric(hist, "sigma_counts", {"t": current_t, **counts})
 
-    # Trayectoria por nodo (opcional)
+    # Optional per-node trajectory
     if cfg.get("per_node", False):
         per = hist.setdefault("sigma_per_node", {})
         for n, nd in G.nodes(data=True):
@@ -317,11 +342,13 @@ def push_sigma_snapshot(G, t: float | None = None) -> None:
 
 
 # -------------------------
-# Registro como callback automático (after_step)
+# Register as an automatic callback (after_step)
 # -------------------------
 
 
-def register_sigma_callback(G) -> None:
+def register_sigma_callback(G: TNFRGraph) -> None:
+    """Attach :func:`push_sigma_snapshot` to the ``AFTER_STEP`` callback bus."""
+
     callback_manager.register_callback(
         G,
         event=CallbackEvent.AFTER_STEP.value,
@@ -330,7 +357,7 @@ def register_sigma_callback(G) -> None:
     )
 
 
-def sigma_rose(G, steps: int | None = None) -> dict[str, int]:
+def sigma_rose(G: TNFRGraph, steps: int | None = None) -> dict[str, int]:
     """Histogram of glyphs in the last ``steps`` steps (or all)."""
     hist = ensure_history(G)
     counts = hist.get("sigma_counts", [])
@@ -340,9 +367,7 @@ def sigma_rose(G, steps: int | None = None) -> dict[str, int]:
         steps = int(steps)
         if steps < 0:
             raise ValueError("steps must be non-negative")
-        rows = (
-            counts if steps >= len(counts) else counts[-steps:]
-        )  # noqa: E203
+        rows = counts if steps >= len(counts) else counts[-steps:]  # noqa: E203
     else:
         rows = counts
     counter = Counter()

tnfr/sense.pyi

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Optional
+
+from .types import NodeId, SigmaVector, TNFRGraph
+
+__all__: tuple[str, ...]
+
+GLYPH_UNITS: dict[str, complex]
+
+def glyph_angle(g: str) -> float: ...
+def glyph_unit(g: str) -> complex: ...
+def push_sigma_snapshot(G: TNFRGraph, t: Optional[float] = None) -> None: ...
+def register_sigma_callback(G: TNFRGraph) -> None: ...
+def sigma_rose(G: TNFRGraph, steps: Optional[int] = None) -> dict[str, int]: ...
+def sigma_vector(dist: Mapping[str, float]) -> SigmaVector: ...
+def sigma_vector_from_graph(
+    G: TNFRGraph, weight_mode: Optional[str] = None
+) -> SigmaVector: ...
+def sigma_vector_node(
+    G: TNFRGraph, n: NodeId, weight_mode: Optional[str] = None
+) -> Optional[SigmaVector]: ...

tnfr/services/__init__.py

@@ -0,0 +1,17 @@
+"""Service layer for TNFR orchestration.
+
+This package provides the service layer that coordinates execution of TNFR
+operator sequences while maintaining clean separation of responsibilities
+across validation, execution, dynamics, and telemetry concerns.
+
+Public API
+----------
+TNFROrchestrator
+    Main orchestration service coordinating sequence execution.
+"""
+
+from __future__ import annotations
+
+from .orchestrator import TNFROrchestrator
+
+__all__ = ("TNFROrchestrator",)