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

tnfr/execution.py

@@ -4,28 +4,25 @@ from __future__ import annotations
 
 from collections import deque
 from collections.abc import Callable, Iterable, Sequence
-from typing import Any, Optional
+from typing import Any, Optional, cast
 
-import networkx as nx  # networkx is used at runtime
+from ._compat import TypeAlias
 
-from .collections_utils import (
-    MAX_MATERIALIZE_DEFAULT,
-    ensure_collection,
-    is_non_string_sequence,
-)
+from .utils import MAX_MATERIALIZE_DEFAULT, ensure_collection, is_non_string_sequence
 from .constants import get_param
 from .dynamics import step
 from .flatten import _flatten
 from .glyph_history import ensure_history
-from .grammar import apply_glyph_with_grammar
+from .validation.grammar import apply_glyph_with_grammar
 from .tokens import OpTag, TARGET, THOL, WAIT, Token
-from .types import Glyph
+from .types import Glyph, NodeId, TNFRGraph
 
-Node = Any
-AdvanceFn = Callable[[Any], None]
+AdvanceFn = Callable[[TNFRGraph], None]
+TraceEntry = dict[str, Any]
+ProgramTrace: TypeAlias = deque[TraceEntry]
 HandlerFn = Callable[
-    [nx.Graph, Any, Optional[list[Node]], deque, AdvanceFn],
-    Optional[list[Node]],
+    [TNFRGraph, Any, Optional[Sequence[NodeId]], ProgramTrace, AdvanceFn],
+    Optional[Sequence[NodeId]],
 ]
 
 __all__ = [
@@ -45,7 +42,7 @@ __all__ = [
 ]
 
 
-CANONICAL_PRESET_NAME = "ejemplo_canonico"
+CANONICAL_PRESET_NAME = "canonical_example"
 CANONICAL_PROGRAM_TOKENS: tuple[Token, ...] = (
     Glyph.SHA,
     Glyph.AL,
@@ -56,13 +53,13 @@ CANONICAL_PROGRAM_TOKENS: tuple[Token, ...] = (
 )
 
 
-def _window(G) -> int:
+def _window(G: TNFRGraph) -> int:
     return int(get_param(G, "GLYPH_HYSTERESIS_WINDOW"))
 
 
 def _apply_glyph_to_targets(
-    G, g: Glyph | str, nodes: Optional[Iterable[Node]] = None
-):
+    G: TNFRGraph, g: Glyph | str, nodes: Optional[Iterable[NodeId]] = None
+) -> None:
     """Apply ``g`` to ``nodes`` (or all nodes) respecting the grammar."""
 
     nodes_iter = G.nodes() if nodes is None else nodes
@@ -70,22 +67,22 @@ def _apply_glyph_to_targets(
     apply_glyph_with_grammar(G, nodes_iter, g, w)
 
 
-def _advance(G, step_fn: AdvanceFn):
+def _advance(G: TNFRGraph, step_fn: AdvanceFn) -> None:
     step_fn(G)
 
 
-def _record_trace(trace: deque, G, op: OpTag, **data) -> None:
+def _record_trace(trace: ProgramTrace, G: TNFRGraph, op: OpTag, **data: Any) -> None:
     trace.append({"t": float(G.graph.get("_t", 0.0)), "op": op.name, **data})
 
 
 def _advance_and_record(
-    G,
-    trace: deque,
+    G: TNFRGraph,
+    trace: ProgramTrace,
     label: OpTag,
     step_fn: AdvanceFn,
     *,
     times: int = 1,
-    **data,
+    **data: Any,
 ) -> None:
     for _ in range(times):
         _advance(G, step_fn)
@@ -93,40 +90,55 @@ def _advance_and_record(
 
 
 def _handle_target(
-    G, payload: TARGET, _curr_target, trace: deque, _step_fn: AdvanceFn
-):
+    G: TNFRGraph,
+    payload: TARGET,
+    _curr_target: Optional[Sequence[NodeId]],
+    trace: ProgramTrace,
+    _step_fn: AdvanceFn,
+) -> Sequence[NodeId]:
     """Handle a ``TARGET`` token and return the active node set."""
 
     nodes_src = G.nodes() if payload.nodes is None else payload.nodes
     nodes = ensure_collection(nodes_src, max_materialize=None)
-    curr_target = nodes if is_non_string_sequence(nodes) else tuple(nodes)
+    if is_non_string_sequence(nodes):
+        curr_target = cast(Sequence[NodeId], nodes)
+    else:
+        curr_target = tuple(nodes)
     _record_trace(trace, G, OpTag.TARGET, n=len(curr_target))
     return curr_target
 
 
 def _handle_wait(
-    G, steps: int, curr_target, trace: deque, step_fn: AdvanceFn
-):
+    G: TNFRGraph,
+    steps: int,
+    curr_target: Optional[Sequence[NodeId]],
+    trace: ProgramTrace,
+    step_fn: AdvanceFn,
+) -> Optional[Sequence[NodeId]]:
     _advance_and_record(G, trace, OpTag.WAIT, step_fn, times=steps, k=steps)
     return curr_target
 
 
 def _handle_glyph(
-    G,
-    g: str,
-    curr_target,
-    trace: deque,
+    G: TNFRGraph,
+    g: Glyph | str,
+    curr_target: Optional[Sequence[NodeId]],
+    trace: ProgramTrace,
     step_fn: AdvanceFn,
     label: OpTag = OpTag.GLYPH,
-):
+) -> Optional[Sequence[NodeId]]:
     _apply_glyph_to_targets(G, g, curr_target)
     _advance_and_record(G, trace, label, step_fn, g=g)
     return curr_target
 
 
 def _handle_thol(
-    G, g, curr_target, trace: deque, step_fn: AdvanceFn
-):
+    G: TNFRGraph,
+    g: Glyph | str | None,
+    curr_target: Optional[Sequence[NodeId]],
+    trace: ProgramTrace,
+    step_fn: AdvanceFn,
+) -> Optional[Sequence[NodeId]]:
     return _handle_glyph(
         G, g or Glyph.THOL.value, curr_target, trace, step_fn, label=OpTag.THOL
     )
@@ -141,20 +153,23 @@ HANDLERS: dict[OpTag, HandlerFn] = {
 
 
 def play(
-    G, sequence: Sequence[Token], step_fn: Optional[AdvanceFn] = None
+    G: TNFRGraph, sequence: Sequence[Token], step_fn: Optional[AdvanceFn] = None
 ) -> None:
     """Execute a canonical sequence on graph ``G``."""
 
     step_fn = step_fn or step
 
-    curr_target: Optional[list[Node]] = None
+    curr_target: Optional[Sequence[NodeId]] = None
 
     history = ensure_history(G)
     maxlen = int(get_param(G, "PROGRAM_TRACE_MAXLEN"))
-    trace = history.get("program_trace")
-    if not isinstance(trace, deque) or trace.maxlen != maxlen:
-        trace = deque(trace or [], maxlen=maxlen)
+    trace_obj = history.get("program_trace")
+    trace: ProgramTrace
+    if not isinstance(trace_obj, deque) or trace_obj.maxlen != maxlen:
+        trace = cast(ProgramTrace, deque(trace_obj or [], maxlen=maxlen))
         history["program_trace"] = trace
+    else:
+        trace = cast(ProgramTrace, trace_obj)
 
     for op, payload in _flatten(sequence):
         handler: HandlerFn | None = HANDLERS.get(op)
@@ -183,7 +198,7 @@ def block(
     return THOL(body=list(tokens), repeat=repeat, force_close=close)
 
 
-def target(nodes: Optional[Iterable[Node]] = None) -> TARGET:
+def target(nodes: Optional[Iterable[NodeId]] = None) -> TARGET:
     return TARGET(nodes=nodes)
 
 
@@ -195,7 +210,7 @@ def basic_canonical_example() -> list[Token]:
     """Reference canonical sequence.
 
     Returns a copy of the canonical preset tokens to keep CLI defaults aligned
-    with :func:`tnfr.presets.get_preset`.
+    with :func:`tnfr.config.presets.get_preset`.
     """
 
     return list(CANONICAL_PROGRAM_TOKENS)

tnfr/execution.pyi

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Callable, Iterable, Sequence
+from typing import Any, Optional
+
+from ._compat import TypeAlias
+
+from .tokens import OpTag, TARGET, THOL, WAIT, Token
+from .types import Glyph, NodeId, TNFRGraph
+
+__all__: list[str]
+
+
+def __getattr__(name: str) -> Any: ...
+
+
+AdvanceFn = Callable[[TNFRGraph], None]
+TraceEntry = dict[str, Any]
+ProgramTrace: TypeAlias = deque[TraceEntry]
+HandlerFn = Callable[
+    [TNFRGraph, Any, Sequence[NodeId] | None, ProgramTrace, AdvanceFn],
+    Sequence[NodeId] | None,
+]
+
+CANONICAL_PRESET_NAME: str
+CANONICAL_PROGRAM_TOKENS: tuple[Token, ...]
+HANDLERS: dict[OpTag, HandlerFn]
+
+
+def _apply_glyph_to_targets(
+    G: TNFRGraph, g: Glyph | str, nodes: Iterable[NodeId] | None = ...
+) -> None: ...
+
+
+def _record_trace(trace: ProgramTrace, G: TNFRGraph, op: OpTag, **data: Any) -> None: ...
+
+
+def compile_sequence(
+    sequence: Iterable[Token] | Sequence[Token] | Any,
+    *,
+    max_materialize: int | None = ...,
+) -> list[tuple[OpTag, Any]]: ...
+
+
+def play(
+    G: TNFRGraph, sequence: Sequence[Token], step_fn: Optional[AdvanceFn] = ...
+) -> None: ...
+
+
+def seq(*tokens: Token) -> list[Token]: ...
+
+
+def block(
+    *tokens: Token, repeat: int = ..., close: Glyph | None = ...
+) -> THOL: ...
+
+
+def target(nodes: Iterable[NodeId] | None = ...) -> TARGET: ...
+
+
+def wait(steps: int = ...) -> WAIT: ...
+
+
+def basic_canonical_example() -> list[Token]: ...

tnfr/flatten.py

@@ -7,14 +7,14 @@ from dataclasses import dataclass
 from itertools import chain
 from typing import Any, Callable
 
-from .collections_utils import (
+from .utils import (
     MAX_MATERIALIZE_DEFAULT,
+    STRING_TYPES,
     ensure_collection,
     flatten_structure,
-    STRING_TYPES,
     normalize_materialize_limit,
 )
-from .constants_glyphs import GLYPHS_CANONICAL_SET
+from .config.constants import GLYPHS_CANONICAL_SET
 from .tokens import THOL, TARGET, WAIT, OpTag, THOL_SENTINEL, Token
 from .types import Glyph
 
@@ -126,7 +126,7 @@ class THOLEvaluator:
     def __iter__(self) -> "THOLEvaluator":
         return self
 
-    def __next__(self):
+    def __next__(self) -> Token | object:
         if not self._started:
             self._started = True
             return THOL_SENTINEL
@@ -211,7 +211,7 @@ def _coerce_mapping_token(
     if isinstance(close, str):
         close_enum = Glyph.__members__.get(close)
         if close_enum is None:
-            raise ValueError(f"Glyph de cierre desconocido: {close!r}")
+            raise ValueError(f"Unknown closing glyph: {close!r}")
         close = close_enum
     elif close is not None and not isinstance(close, Glyph):
         raise TypeError("THOL close glyph must be a Glyph or string name")
@@ -235,7 +235,7 @@ def parse_program_tokens(
 
     sequence = _iter_source(obj, max_materialize=max_materialize)
 
-    def _expand(item: Any):
+    def _expand(item: Any) -> Iterable[Any] | None:
         if isinstance(item, Mapping):
             return (_coerce_mapping_token(item, max_materialize=max_materialize),)
         return None
@@ -259,7 +259,7 @@ def _flatten(
     ops: list[tuple[OpTag, Any]] = []
     sequence = _iter_source(seq, max_materialize=max_materialize)
 
-    def _expand(item: Any):
+    def _expand(item: Any) -> Iterable[Any] | None:
         if isinstance(item, THOL):
             return THOLEvaluator(item, max_materialize=max_materialize)
         if isinstance(item, Mapping):

tnfr/flatten.pyi

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, Sequence
+from typing import Any
+
+from .tokens import THOL, Token
+
+__all__: list[str]
+
+
+def __getattr__(name: str) -> Any: ...
+
+
+class THOLEvaluator(Iterator[Token | object]):
+    def __init__(
+        self, item: THOL, *, max_materialize: int | None = ...
+    ) -> None: ...
+
+    def __iter__(self) -> THOLEvaluator: ...
+
+    def __next__(self) -> Token | object: ...
+
+
+def parse_program_tokens(
+    obj: Iterable[Any] | Sequence[Any] | Any,
+    *,
+    max_materialize: int | None = ...,
+) -> list[Token]: ...

tnfr/gamma.py

@@ -9,16 +9,18 @@ from collections.abc import Mapping
 from functools import lru_cache
 from types import MappingProxyType
 
-from .constants import DEFAULTS, get_aliases
-from .alias import get_attr
-from .graph_utils import get_graph_mapping
-from .cache import edge_version_cache, node_set_checksum
-from .json_utils import json_dumps
-from .logging_utils import get_logger
+from .constants import DEFAULTS
+from .alias import get_theta_attr
+from .types import GammaSpec, NodeId, TNFRGraph
+from .utils import (
+    edge_version_cache,
+    get_graph_mapping,
+    get_logger,
+    json_dumps,
+    node_set_checksum,
+)
 from .metrics.trig_cache import get_trig_cache
 
-ALIAS_THETA = get_aliases("THETA")
-
 
 logger = get_logger(__name__)
 
@@ -44,7 +46,7 @@ def _default_gamma_spec() -> tuple[bytes, str]:
     return dumped, hash_
 
 
-def _ensure_kuramoto_cache(G, t) -> None:
+def _ensure_kuramoto_cache(G: TNFRGraph, t: float | int) -> None:
     """Cache ``(R, ψ)`` for the current step ``t`` using
     ``edge_version_cache``."""
     checksum = G.graph.get("_dnfr_nodes_checksum")
@@ -63,7 +65,7 @@ def _ensure_kuramoto_cache(G, t) -> None:
     G.graph["_kuramoto_cache"] = entry
 
 
-def kuramoto_R_psi(G) -> tuple[float, float]:
+def kuramoto_R_psi(G: TNFRGraph) -> tuple[float, float]:
     """Return ``(R, ψ)`` for Kuramoto order using θ from all nodes."""
     max_steps = int(G.graph.get("KURAMOTO_CACHE_STEPS", 1))
     trig = get_trig_cache(G, cache_size=max_steps)
@@ -78,7 +80,9 @@ def kuramoto_R_psi(G) -> tuple[float, float]:
     return R, psi
 
 
-def _kuramoto_common(G, node, _cfg):
+def _kuramoto_common(
+    G: TNFRGraph, node: NodeId, _cfg: GammaSpec
+) -> tuple[float, float, float]:
     """Return ``(θ_i, R, ψ)`` for Kuramoto-based Γ functions.
 
     Reads cached global order ``R`` and mean phase ``ψ`` and obtains node
@@ -88,11 +92,12 @@ def _kuramoto_common(G, node, _cfg):
     cache = G.graph.get("_kuramoto_cache", {})
     R = float(cache.get("R", 0.0))
     psi = float(cache.get("psi", 0.0))
-    th_i = get_attr(G.nodes[node], ALIAS_THETA, 0.0)
+    th_val = get_theta_attr(G.nodes[node], 0.0)
+    th_i = float(th_val if th_val is not None else 0.0)
     return th_i, R, psi
 
 
-def _read_gamma_raw(G) -> Mapping[str, Any] | None:
+def _read_gamma_raw(G: TNFRGraph) -> GammaSpec | None:
     """Return raw Γ specification from ``G.graph['GAMMA']``.
 
     The returned value is the direct contents of ``G.graph['GAMMA']`` when
@@ -104,11 +109,13 @@ def _read_gamma_raw(G) -> Mapping[str, Any] | None:
     if raw is None or isinstance(raw, Mapping):
         return raw
     return get_graph_mapping(
-        G, "GAMMA", "G.graph['GAMMA'] no es un mapeo; se usa {'type': 'none'}"
+        G,
+        "GAMMA",
+        "G.graph['GAMMA'] is not a mapping; using {'type': 'none'}",
     )
 
 
-def _get_gamma_spec(G) -> Mapping[str, Any]:
+def _get_gamma_spec(G: TNFRGraph) -> GammaSpec:
     """Return validated Γ specification caching results.
 
     The raw value from ``G.graph['GAMMA']`` is cached together with the
@@ -122,7 +129,7 @@ def _get_gamma_spec(G) -> Mapping[str, Any]:
     cached_spec = G.graph.get("_gamma_spec")
     cached_hash = G.graph.get("_gamma_spec_hash")
 
-    def _hash_mapping(mapping: Mapping[str, Any]) -> str:
+    def _hash_mapping(mapping: GammaSpec) -> str:
         dumped = json_dumps(mapping, sort_keys=True, to_bytes=True)
         return hashlib.blake2b(dumped, digest_size=16).hexdigest()
 
@@ -166,7 +173,7 @@ def _get_gamma_spec(G) -> Mapping[str, Any]:
 
 
 def _gamma_params(
-    cfg: Mapping[str, Any], **defaults: float
+    cfg: GammaSpec, **defaults: float
 ) -> tuple[float, ...]:
     """Return normalized Γ parameters from ``cfg``.
 
@@ -185,18 +192,20 @@ def _gamma_params(
 
 
 # -----------------
-# Γi(R) canónicos
+# Canonical Γi(R)
 # -----------------
 
 
-def gamma_none(G, node, t, cfg: dict[str, Any]) -> float:
+def gamma_none(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float:
     return 0.0
 
 
 def _gamma_kuramoto(
-    G,
-    node,
-    cfg: Mapping[str, Any],
+    G: TNFRGraph,
+    node: NodeId,
+    cfg: GammaSpec,
     builder: Callable[..., float],
     **defaults: float,
 ) -> float:
@@ -224,7 +233,9 @@ def _builder_tanh(th_i: float, R: float, psi: float, beta: float, k: float, R0:
     return beta * math.tanh(k * (R - R0)) * math.cos(th_i - psi)
 
 
-def gamma_kuramoto_linear(G, node, t, cfg: dict[str, Any]) -> float:
+def gamma_kuramoto_linear(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float:
     """Linear Kuramoto coupling for Γi(R).
 
     Formula: Γ = β · (R - R0) · cos(θ_i - ψ)
@@ -239,13 +250,17 @@ def gamma_kuramoto_linear(G, node, t, cfg: dict[str, Any]) -> float:
     return _gamma_kuramoto(G, node, cfg, _builder_linear, beta=0.0, R0=0.0)
 
 
-def gamma_kuramoto_bandpass(G, node, t, cfg: dict[str, Any]) -> float:
+def gamma_kuramoto_bandpass(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float:
     """Γ = β · R(1-R) · sign(cos(θ_i - ψ))"""
 
     return _gamma_kuramoto(G, node, cfg, _builder_bandpass, beta=0.0)
 
 
-def gamma_kuramoto_tanh(G, node, t, cfg: dict[str, Any]) -> float:
+def gamma_kuramoto_tanh(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float:
     """Saturating tanh coupling for Γi(R).
 
     Formula: Γ = β · tanh(k·(R - R0)) · cos(θ_i - ψ)
@@ -257,7 +272,9 @@ def gamma_kuramoto_tanh(G, node, t, cfg: dict[str, Any]) -> float:
     return _gamma_kuramoto(G, node, cfg, _builder_tanh, beta=0.0, k=1.0, R0=0.0)
 
 
-def gamma_harmonic(G, node, t, cfg: dict[str, Any]) -> float:
+def gamma_harmonic(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float:
     """Harmonic forcing aligned with the global phase field.
 
     Formula: Γ = β · sin(ω·t + φ) · cos(θ_i - ψ)
@@ -271,13 +288,13 @@ def gamma_harmonic(G, node, t, cfg: dict[str, Any]) -> float:
 
 
 class GammaEntry(NamedTuple):
-    fn: Callable[[Any, Any, Any, dict[str, Any]], float]
+    fn: Callable[[TNFRGraph, NodeId, float | int, GammaSpec], float]
     needs_kuramoto: bool
 
 
-# ``GAMMA_REGISTRY`` asocia el nombre del acoplamiento con un
-# ``GammaEntry`` donde ``fn`` es la función evaluadora y
-# ``needs_kuramoto`` indica si requiere precomputar el orden global de fase.
+# ``GAMMA_REGISTRY`` associates each coupling name with a ``GammaEntry`` where
+# ``fn`` is the evaluation function and ``needs_kuramoto`` indicates whether
+# the global phase order must be precomputed.
 GAMMA_REGISTRY: dict[str, GammaEntry] = {
     "none": GammaEntry(gamma_none, False),
     "kuramoto_linear": GammaEntry(gamma_kuramoto_linear, True),
@@ -288,9 +305,9 @@ GAMMA_REGISTRY: dict[str, GammaEntry] = {
 
 
 def eval_gamma(
-    G,
-    node,
-    t,
+    G: TNFRGraph,
+    node: NodeId,
+    t: float | int,
     *,
     strict: bool = False,
     log_level: int | None = None,
@@ -300,8 +317,8 @@ def eval_gamma(
 
     If ``strict`` is ``True`` exceptions raised during evaluation are
     propagated instead of returning ``0.0``. Likewise, if the specified
-    Γ type is not registered a warning is emitted (o ``ValueError`` en
-    modo estricto) y se usa ``gamma_none``.
+    Γ type is not registered a warning is emitted (or ``ValueError`` in
+    strict mode) and ``gamma_none`` is used.
 
     ``log_level`` controls the logging level for captured errors when
     ``strict`` is ``False``. If omitted, ``logging.ERROR`` is used in
@@ -311,7 +328,7 @@ def eval_gamma(
     spec_type = spec.get("type", "none")
     reg_entry = GAMMA_REGISTRY.get(spec_type)
     if reg_entry is None:
-        msg = f"Tipo GAMMA desconocido: {spec_type}"
+        msg = f"Unknown GAMMA type: {spec_type}"
         if strict:
             raise ValueError(msg)
         logger.warning(msg)
@@ -330,7 +347,7 @@ def eval_gamma(
         )
         logger.log(
             level,
-            "Fallo al evaluar Γi para nodo %s en t=%s: %s: %s",
+            "Failed to evaluate Γi for node %s at t=%s: %s: %s",
             node,
             t,
             exc.__class__.__name__,

tnfr/gamma.pyi

@@ -0,0 +1,40 @@
+from typing import Callable, NamedTuple
+
+from .types import GammaSpec, NodeId, TNFRGraph
+
+__all__: tuple[str, ...]
+
+class GammaEntry(NamedTuple):
+    fn: Callable[[TNFRGraph, NodeId, float | int, GammaSpec], float]
+    needs_kuramoto: bool
+
+GAMMA_REGISTRY: dict[str, GammaEntry]
+
+def kuramoto_R_psi(G: TNFRGraph) -> tuple[float, float]: ...
+
+def gamma_none(G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec) -> float: ...
+
+def gamma_kuramoto_linear(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float: ...
+
+def gamma_kuramoto_bandpass(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float: ...
+
+def gamma_kuramoto_tanh(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float: ...
+
+def gamma_harmonic(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float: ...
+
+def eval_gamma(
+    G: TNFRGraph,
+    node: NodeId,
+    t: float | int,
+    *,
+    strict: bool = ...,
+    log_level: int | None = ...,
+) -> float: ...