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

tnfr/sense.py

@@ -1,18 +1,18 @@
 """Sense calculations."""
 
 from __future__ import annotations
-from typing import TypeVar
-from collections.abc import Iterable, Mapping
+from typing import Any, Callable, TypeVar
+from collections.abc import Iterable, Iterator, Mapping
 import math
 from collections import Counter
 from itertools import tee
 
-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 .utils import get_numpy
 from .callback_utils import CallbackEvent, callback_manager
 from .glyph_history import (
     ensure_history,
@@ -20,12 +20,13 @@ from .glyph_history import (
     count_glyphs,
     append_metric,
 )
-from .constants_glyphs import (
+from .config.constants import (
     ANGLE_MAP,
     GLYPHS_CANONICAL,
 )
+from .types import NodeId, SigmaVector, TNFRGraph
 # -------------------------
-# Canon: orden circular de glyphs y ángulos
+# Canon: circular glyph order and angles
 # -------------------------
 
 GLYPH_UNITS: dict[str, complex] = {
@@ -45,7 +46,7 @@ __all__ = (
 )
 
 # -------------------------
-# Utilidades básicas
+# Basic utilities
 # -------------------------
 
 
@@ -58,7 +59,7 @@ 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:
@@ -76,17 +77,19 @@ def glyph_unit(g: str) -> complex:
 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 +99,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 +113,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 +130,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
@@ -159,15 +162,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 +191,32 @@ 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]:
+    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 +229,8 @@ 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:
     cfg = _sigma_cfg(G)
     nd = G.nodes[n]
     weight_mode = weight_mode or cfg.get("weight", "Si")
@@ -229,11 +240,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 +258,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,7 +276,7 @@ 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")
@@ -275,23 +287,23 @@ def sigma_vector_from_graph(
 
 
 # -------------------------
-# 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:
     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 +313,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 +329,11 @@ 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:
     callback_manager.register_callback(
         G,
         event=CallbackEvent.AFTER_STEP.value,
@@ -330,7 +342,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", [])

tnfr/sense.pyi

@@ -0,0 +1,30 @@
+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/structural.py

@@ -1,20 +1,39 @@
 """Structural analysis."""
 
 from __future__ import annotations
+
 from typing import Iterable
-import networkx as nx  # type: ignore[import-untyped]
 
+import networkx as nx
+
+from .constants import EPI_PRIMARY, VF_PRIMARY, THETA_PRIMARY
 from .dynamics import (
     set_delta_nfr_hook,
     dnfr_epi_vf_mixed,
 )
-from .grammar import apply_glyph_with_grammar
-from .types import Glyph
-from .constants import EPI_PRIMARY, VF_PRIMARY, THETA_PRIMARY
+from .types import DeltaNFRHook, NodeId, TNFRGraph
+from .operators.definitions import (
+    Operator,
+    Emission,
+    Reception,
+    Coherence,
+    Dissonance,
+    Coupling,
+    Resonance,
+    Silence,
+    Expansion,
+    Contraction,
+    SelfOrganization,
+    Mutation,
+    Transition,
+    Recursivity,
+)
+from .operators.registry import OPERATORS
+from .validation import validate_sequence
 
 
 # ---------------------------------------------------------------------------
-# 1) Factoría NFR
+# 1) NFR factory
 # ---------------------------------------------------------------------------
 
 
@@ -24,9 +43,9 @@ def create_nfr(
     epi: float = 0.0,
     vf: float = 1.0,
     theta: float = 0.0,
-    graph: nx.Graph | None = None,
-    dnfr_hook=dnfr_epi_vf_mixed,
-) -> tuple[nx.Graph, str]:
+    graph: TNFRGraph | None = None,
+    dnfr_hook: DeltaNFRHook = dnfr_epi_vf_mixed,
+) -> tuple[TNFRGraph, str]:
     """Create a graph with an initialised NFR node.
 
     Returns the tuple ``(G, name)`` for convenience.
@@ -44,278 +63,36 @@ def create_nfr(
     return G, name
 
 
-# ---------------------------------------------------------------------------
-# 2) Operadores estructurales como API de primer orden
-# ---------------------------------------------------------------------------
-
-
-class Operador:
-    """Base class for TNFR operators.
-
-    Each operator defines ``name`` (ASCII identifier) and ``glyph``
-    (símbolo TNFR canónico). Calling an instance applies the corresponding
-    symbol to the node.
-    """
-
-    name = "operador"
-    glyph = None  # tipo: str
-
-    def __call__(self, G: nx.Graph, node, **kw) -> None:
-        if self.glyph is None:
-            raise NotImplementedError("Operador sin glyph asignado")
-        apply_glyph_with_grammar(G, [node], self.glyph, kw.get("window"))
-
-
-class Emision(Operador):
-    """Aplicación del operador de emisión (símbolo ``AL``)."""
-
-    __slots__ = ()
-    name = "emision"
-    glyph = Glyph.AL.value
-
-
-class Recepcion(Operador):
-    """Operador de recepción (símbolo ``EN``)."""
-
-    __slots__ = ()
-    name = "recepcion"
-    glyph = Glyph.EN.value
-
-
-class Coherencia(Operador):
-    """Operador de coherencia (símbolo ``IL``)."""
-
-    __slots__ = ()
-    name = "coherencia"
-    glyph = Glyph.IL.value
-
-
-class Disonancia(Operador):
-    """Operador de disonancia (símbolo ``OZ``)."""
-
-    __slots__ = ()
-    name = "disonancia"
-    glyph = Glyph.OZ.value
-
-
-class Acoplamiento(Operador):
-    """Operador de acoplamiento (símbolo ``UM``)."""
-
-    __slots__ = ()
-    name = "acoplamiento"
-    glyph = Glyph.UM.value
-
-
-class Resonancia(Operador):
-    """Operador de resonancia (símbolo ``RA``)."""
-
-    __slots__ = ()
-    name = "resonancia"
-    glyph = Glyph.RA.value
-
-
-class Silencio(Operador):
-    """Operador de silencio (símbolo ``SHA``)."""
-
-    __slots__ = ()
-    name = "silencio"
-    glyph = Glyph.SHA.value
-
-
-class Expansion(Operador):
-    """Operador de expansión (símbolo ``VAL``)."""
-
-    __slots__ = ()
-    name = "expansion"
-    glyph = Glyph.VAL.value
-
-
-class Contraccion(Operador):
-    """Operador de contracción (símbolo ``NUL``)."""
-
-    __slots__ = ()
-    name = "contraccion"
-    glyph = Glyph.NUL.value
-
-
-class Autoorganizacion(Operador):
-    """Operador de autoorganización (símbolo ``THOL``)."""
-
-    __slots__ = ()
-    name = "autoorganizacion"
-    glyph = Glyph.THOL.value
-
-
-class Mutacion(Operador):
-    """Operador de mutación (símbolo ``ZHIR``)."""
-
-    __slots__ = ()
-    name = "mutacion"
-    glyph = Glyph.ZHIR.value
-
-
-class Transicion(Operador):
-    """Operador de transición (símbolo ``NAV``)."""
-
-    __slots__ = ()
-    name = "transicion"
-    glyph = Glyph.NAV.value
-
-
-class Recursividad(Operador):
-    """Operador de recursividad (símbolo ``REMESH``)."""
-
-    __slots__ = ()
-    name = "recursividad"
-    glyph = Glyph.REMESH.value
-
-
-OPERADORES: dict[str, type[Operador]] = {
-    Emision.name: Emision,
-    Recepcion.name: Recepcion,
-    Coherencia.name: Coherencia,
-    Disonancia.name: Disonancia,
-    Acoplamiento.name: Acoplamiento,
-    Resonancia.name: Resonancia,
-    Silencio.name: Silencio,
-    Expansion.name: Expansion,
-    Contraccion.name: Contraccion,
-    Autoorganizacion.name: Autoorganizacion,
-    Mutacion.name: Mutacion,
-    Transicion.name: Transicion,
-    Recursividad.name: Recursividad,
-}
-
-
 __all__ = (
     "create_nfr",
-    "Operador",
-    "Emision",
-    "Recepcion",
-    "Coherencia",
-    "Disonancia",
-    "Acoplamiento",
-    "Resonancia",
-    "Silencio",
+    "Operator",
+    "Emission",
+    "Reception",
+    "Coherence",
+    "Dissonance",
+    "Coupling",
+    "Resonance",
+    "Silence",
     "Expansion",
-    "Contraccion",
-    "Autoorganizacion",
-    "Mutacion",
-    "Transicion",
-    "Recursividad",
-    "OPERADORES",
+    "Contraction",
+    "SelfOrganization",
+    "Mutation",
+    "Transition",
+    "Recursivity",
+    "OPERATORS",
     "validate_sequence",
     "run_sequence",
 )
-# ---------------------------------------------------------------------------
-# 3) Motor de secuencias + validador sintáctico
-# ---------------------------------------------------------------------------
-
-
-_INICIO_VALIDOS = {"emision", "recursividad"}
-_TRAMO_INTERMEDIO = {"disonancia", "acoplamiento", "resonancia"}
-_CIERRE_VALIDO = {"silencio", "transicion", "recursividad"}
-
-
-def _validate_start(token: str) -> tuple[bool, str]:
-    """Ensure the sequence begins with a valid structural operator."""
-
-    if not isinstance(token, str):
-        return False, "tokens must be str"
-    if token not in _INICIO_VALIDOS:
-        return False, "must start with emission or recursion"
-    return True, ""
-
-
-def _validate_intermediate(
-    found_recepcion: bool, found_coherencia: bool, seen_intermedio: bool
-) -> tuple[bool, str]:
-    """Check that the central TNFR segment is present."""
-
-    if not (found_recepcion and found_coherencia):
-        return False, "missing input→coherence segment"
-    if not seen_intermedio:
-        return False, "missing tension/coupling/resonance segment"
-    return True, ""
-
-
-def _validate_end(last_token: str, open_thol: bool) -> tuple[bool, str]:
-    """Validate closing operator and any pending THOL blocks."""
-
-    if last_token not in _CIERRE_VALIDO:
-        return False, "sequence must end with silence/transition/recursion"
-    if open_thol:
-        return False, "THOL block without closure"
-    return True, ""
-
-
-def _validate_known_tokens(nombres_set: set[str]) -> tuple[bool, str]:
-    """Ensure all tokens map to canonical operators."""
-
-    desconocidos = nombres_set - OPERADORES.keys()
-    if desconocidos:
-        return False, f"unknown tokens: {', '.join(desconocidos)}"
-    return True, ""
-
-
-def _validate_token_sequence(nombres: list[str]) -> tuple[bool, str]:
-    """Validate token format and logical coherence in one pass."""
-
-    if not nombres:
-        return False, "empty sequence"
-
-    ok, msg = _validate_start(nombres[0])
-    if not ok:
-        return False, msg
-
-    nombres_set: set[str] = set()
-    found_recepcion = False
-    found_coherencia = False
-    seen_intermedio = False
-    open_thol = False
-
-    for n in nombres:
-        if not isinstance(n, str):
-            return False, "tokens must be str"
-        nombres_set.add(n)
-
-        if n == "recepcion" and not found_recepcion:
-            found_recepcion = True
-        elif found_recepcion and n == "coherencia" and not found_coherencia:
-            found_coherencia = True
-        elif found_coherencia and not seen_intermedio and n in _TRAMO_INTERMEDIO:
-            seen_intermedio = True
-
-        if n == "autoorganizacion":
-            open_thol = True
-        elif open_thol and n in {"silencio", "contraccion"}:
-            open_thol = False
-
-    ok, msg = _validate_known_tokens(nombres_set)
-    if not ok:
-        return False, msg
-    ok, msg = _validate_intermediate(found_recepcion, found_coherencia, seen_intermedio)
-    if not ok:
-        return False, msg
-    ok, msg = _validate_end(nombres[-1], open_thol)
-    if not ok:
-        return False, msg
-    return True, "ok"
-
-
-def validate_sequence(nombres: list[str]) -> tuple[bool, str]:
-    """Validate minimal TNFR syntax rules."""
-    return _validate_token_sequence(nombres)
 
 
-def run_sequence(G: nx.Graph, node, ops: Iterable[Operador]) -> None:
+def run_sequence(G: TNFRGraph, node: NodeId, ops: Iterable[Operator]) -> None:
     """Execute a sequence of operators on ``node`` after validation."""
 
     compute = G.graph.get("compute_delta_nfr")
     ops_list = list(ops)
-    nombres = [op.name for op in ops_list]
+    names = [op.name for op in ops_list]
 
-    ok, msg = validate_sequence(nombres)
+    ok, msg = validate_sequence(names)
     if not ok:
         raise ValueError(f"Invalid sequence: {msg}")