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

tnfr/operators/remesh.py

@@ -1,27 +1,79 @@
 from __future__ import annotations
+
 import hashlib
 import heapq
+import random
 from operator import ge, le
 from functools import cache
 from itertools import combinations
 from io import StringIO
 from collections import deque
+from collections.abc import Hashable, Iterable, Mapping, MutableMapping, Sequence
 from statistics import fmean, StatisticsError
+from types import ModuleType
+from typing import Any, TypedDict, cast
+
+from .._compat import TypeAlias
 
-from ..cache import edge_version_update
 from ..constants import DEFAULTS, REMESH_DEFAULTS, get_aliases, get_param
 from ..helpers.numeric import kahan_sum_nd
 from ..alias import get_attr, set_attr
 from ..rng import make_rng
 from ..callback_utils import CallbackEvent, callback_manager
 from ..glyph_history import append_metric, ensure_history, current_step_idx
-from ..import_utils import cached_import
+from ..utils import cached_import, edge_version_update
+
+CommunityGraph: TypeAlias = Any
+NetworkxModule: TypeAlias = ModuleType
+CommunityModule: TypeAlias = ModuleType
+RemeshEdge: TypeAlias = tuple[Hashable, Hashable]
+NetworkxModules: TypeAlias = tuple[NetworkxModule, CommunityModule]
+
+
+class RemeshMeta(TypedDict, total=False):
+    alpha: float
+    alpha_source: str
+    tau_global: int
+    tau_local: int
+    step: int | None
+    topo_hash: str | None
+    epi_mean_before: float
+    epi_mean_after: float
+    epi_checksum_before: str
+    epi_checksum_after: str
+    stable_frac_last: float
+    phase_sync_last: float
+    glyph_disr_last: float
+
+
+RemeshConfigValue: TypeAlias = bool | float | int
+
+
+def _as_float(value: Any, default: float = 0.0) -> float:
+    """Best-effort conversion to ``float`` returning ``default`` on failure."""
+
+    if value is None:
+        return default
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _ordered_edge(u: Hashable, v: Hashable) -> RemeshEdge:
+    """Return a deterministic ordering for an undirected edge."""
+
+    return (u, v) if repr(u) <= repr(v) else (v, u)
+
 
 ALIAS_EPI = get_aliases("EPI")
 
 
+COOLDOWN_KEY = "REMESH_COOLDOWN_WINDOW"
+
+
 @cache
-def _get_networkx_modules():
+def _get_networkx_modules() -> NetworkxModules:
     nx = cached_import("networkx")
     if nx is None:
         raise ImportError(
@@ -34,30 +86,31 @@ def _get_networkx_modules():
             "networkx.algorithms.community is required for community-based "
             "operations; install 'networkx' to enable this feature"
         )
-    return nx, nx_comm
+    return cast(NetworkxModule, nx), cast(CommunityModule, nx_comm)
 
 
-def _remesh_alpha_info(G):
+def _remesh_alpha_info(G: CommunityGraph) -> tuple[float, str]:
     """Return ``(alpha, source)`` with explicit precedence."""
     if bool(
         G.graph.get("REMESH_ALPHA_HARD", REMESH_DEFAULTS["REMESH_ALPHA_HARD"])
     ):
-        val = float(
-            G.graph.get("REMESH_ALPHA", REMESH_DEFAULTS["REMESH_ALPHA"])
+        val = _as_float(
+            G.graph.get("REMESH_ALPHA", REMESH_DEFAULTS["REMESH_ALPHA"]),
+            float(REMESH_DEFAULTS["REMESH_ALPHA"]),
         )
         return val, "REMESH_ALPHA"
     gf = G.graph.get("GLYPH_FACTORS", DEFAULTS.get("GLYPH_FACTORS", {}))
     if "REMESH_alpha" in gf:
-        return float(gf["REMESH_alpha"]), "GLYPH_FACTORS.REMESH_alpha"
+        return _as_float(gf["REMESH_alpha"]), "GLYPH_FACTORS.REMESH_alpha"
     if "REMESH_ALPHA" in G.graph:
-        return float(G.graph["REMESH_ALPHA"]), "REMESH_ALPHA"
+        return _as_float(G.graph["REMESH_ALPHA"]), "REMESH_ALPHA"
     return (
         float(REMESH_DEFAULTS["REMESH_ALPHA"]),
         "REMESH_DEFAULTS.REMESH_ALPHA",
     )
 
 
-def _snapshot_topology(G, nx):
+def _snapshot_topology(G: CommunityGraph, nx: NetworkxModule) -> str | None:
     """Return a hash representing the current graph topology."""
     try:
         n_nodes = G.number_of_nodes()
@@ -69,12 +122,12 @@ def _snapshot_topology(G, nx):
         return None
 
 
-def _snapshot_epi(G):
+def _snapshot_epi(G: CommunityGraph) -> tuple[float, str]:
     """Return ``(mean, checksum)`` of the node EPI values."""
     buf = StringIO()
     values = []
     for n, data in G.nodes(data=True):
-        v = float(get_attr(data, ALIAS_EPI, 0.0))
+        v = _as_float(get_attr(data, ALIAS_EPI, 0.0))
         values.append(v)
         buf.write(f"{str(n)}:{round(v, 6)};")
     total = kahan_sum_nd(((v,) for v in values), dims=1)[0]
@@ -83,7 +136,7 @@ def _snapshot_epi(G):
     return float(mean_val), checksum
 
 
-def _log_remesh_event(G, meta):
+def _log_remesh_event(G: CommunityGraph, meta: RemeshMeta) -> None:
     """Store remesh metadata and optionally log and trigger callbacks."""
     G.graph["_REMESH_META"] = meta
     if G.graph.get("REMESH_LOG_EVENTS", REMESH_DEFAULTS["REMESH_LOG_EVENTS"]):
@@ -94,7 +147,7 @@ def _log_remesh_event(G, meta):
     )
 
 
-def apply_network_remesh(G) -> None:
+def apply_network_remesh(G: CommunityGraph) -> None:
     """Network-scale REMESH using ``_epi_hist`` with multi-scale memory."""
     nx, _ = _get_networkx_modules()
     tau_g = int(get_param(G, "REMESH_TAU_GLOBAL"))
@@ -113,9 +166,9 @@ def apply_network_remesh(G) -> None:
     epi_mean_before, epi_checksum_before = _snapshot_epi(G)
 
     for n, nd in G.nodes(data=True):
-        epi_now = get_attr(nd, ALIAS_EPI, 0.0)
-        epi_old_l = float(past_l.get(n, epi_now))
-        epi_old_g = float(past_g.get(n, epi_now))
+        epi_now = _as_float(get_attr(nd, ALIAS_EPI, 0.0))
+        epi_old_l = _as_float(past_l.get(n) if isinstance(past_l, Mapping) else None, epi_now)
+        epi_old_g = _as_float(past_g.get(n) if isinstance(past_g, Mapping) else None, epi_now)
         mixed = (1 - alpha) * epi_now + alpha * epi_old_l
         mixed = (1 - alpha) * mixed + alpha * epi_old_g
         set_attr(nd, ALIAS_EPI, mixed)
@@ -123,7 +176,7 @@ def apply_network_remesh(G) -> None:
     epi_mean_after, epi_checksum_after = _snapshot_epi(G)
 
     step_idx = current_step_idx(G)
-    meta = {
+    meta: RemeshMeta = {
         "alpha": alpha,
         "alpha_source": alpha_src,
         "tau_global": tau_g,
@@ -148,7 +201,11 @@ def apply_network_remesh(G) -> None:
     _log_remesh_event(G, meta)
 
 
-def _mst_edges_from_epi(nx, nodes, epi):
+def _mst_edges_from_epi(
+    nx: NetworkxModule,
+    nodes: Sequence[Hashable],
+    epi: Mapping[Hashable, float],
+) -> set[RemeshEdge]:
     """Return MST edges based on absolute EPI distance."""
     H = nx.Graph()
     H.add_nodes_from(nodes)
@@ -156,12 +213,18 @@ def _mst_edges_from_epi(nx, nodes, epi):
         (u, v, abs(epi[u] - epi[v])) for u, v in combinations(nodes, 2)
     )
     return {
-        tuple(sorted((u, v)))
+        _ordered_edge(u, v)
         for u, v in nx.minimum_spanning_edges(H, data=False)
     }
 
 
-def _knn_edges(nodes, epi, k_val, p_rewire, rnd):
+def _knn_edges(
+    nodes: Sequence[Hashable],
+    epi: Mapping[Hashable, float],
+    k_val: int,
+    p_rewire: float,
+    rnd: random.Random,
+) -> set[RemeshEdge]:
     """Edges linking each node to its ``k`` nearest neighbours in EPI."""
     new_edges = set()
     node_set = set(nodes)
@@ -179,17 +242,21 @@ def _knn_edges(nodes, epi, k_val, p_rewire, rnd):
                 choices = list(node_set - {u, v})
                 if choices:
                     v = rnd.choice(choices)
-            new_edges.add(tuple(sorted((u, v))))
+            new_edges.add(_ordered_edge(u, v))
     return new_edges
 
 
-def _community_graph(comms, epi, nx):
+def _community_graph(
+    comms: Iterable[Iterable[Hashable]],
+    epi: Mapping[Hashable, float],
+    nx: NetworkxModule,
+) -> CommunityGraph:
     """Return community graph ``C`` with mean EPI per community."""
     C = nx.Graph()
     for idx, comm in enumerate(comms):
         members = list(comm)
         try:
-            epi_mean = fmean(epi[n] for n in members)
+            epi_mean = fmean(_as_float(epi.get(n)) for n in members)
         except StatisticsError:
             epi_mean = 0.0
         C.add_node(idx)
@@ -197,16 +264,21 @@ def _community_graph(comms, epi, nx):
         C.nodes[idx]["members"] = members
     for i, j in combinations(C.nodes(), 2):
         w = abs(
-            get_attr(C.nodes[i], ALIAS_EPI, 0.0)
-            - get_attr(C.nodes[j], ALIAS_EPI, 0.0)
+            _as_float(get_attr(C.nodes[i], ALIAS_EPI, 0.0))
+            - _as_float(get_attr(C.nodes[j], ALIAS_EPI, 0.0))
         )
         C.add_edge(i, j, weight=w)
-    return C
+    return cast(CommunityGraph, C)
 
 
-def _community_k_neighbor_edges(C, k_val, p_rewire, rnd):
+def _community_k_neighbor_edges(
+    C: CommunityGraph,
+    k_val: int,
+    p_rewire: float,
+    rnd: random.Random,
+) -> tuple[set[RemeshEdge], dict[int, int], list[tuple[int, int, int]]]:
     """Edges linking each community to its ``k`` nearest neighbours."""
-    epi_vals = {n: get_attr(C.nodes[n], ALIAS_EPI, 0.0) for n in C.nodes()}
+    epi_vals = {n: _as_float(get_attr(C.nodes[n], ALIAS_EPI, 0.0)) for n in C.nodes()}
     ordered = sorted(C.nodes(), key=lambda v: epi_vals[v])
     new_edges = set()
     attempts = {n: 0 for n in C.nodes()}
@@ -240,7 +312,7 @@ def _community_k_neighbor_edges(C, k_val, p_rewire, rnd):
                 if choices:
                     v = rnd.choice(choices)
                     rewired_now = True
-            new_edges.add(tuple(sorted((u, v))))
+            new_edges.add(_ordered_edge(u, v))
             attempts[u] += 1
             if rewired_now:
                 rewired.append((u, original_v, v))
@@ -249,16 +321,16 @@ def _community_k_neighbor_edges(C, k_val, p_rewire, rnd):
 
 
 def _community_remesh(
-    G,
-    epi,
-    k_val,
-    p_rewire,
-    rnd,
-    nx,
-    nx_comm,
-    mst_edges,
-    n_before,
-):
+    G: CommunityGraph,
+    epi: Mapping[Hashable, float],
+    k_val: int,
+    p_rewire: float,
+    rnd: random.Random,
+    nx: NetworkxModule,
+    nx_comm: CommunityModule,
+    mst_edges: Iterable[RemeshEdge],
+    n_before: int,
+) -> None:
     """Remesh ``G`` replacing nodes by modular communities."""
     comms = list(nx_comm.greedy_modularity_communities(G))
     if len(comms) <= 1:
@@ -268,7 +340,9 @@ def _community_remesh(
         return
     C = _community_graph(comms, epi, nx)
     mst_c = nx.minimum_spanning_tree(C, weight="weight")
-    new_edges = set(mst_c.edges())
+    new_edges: set[RemeshEdge] = {
+        _ordered_edge(u, v) for u, v in mst_c.edges()
+    }
     extra_edges, attempts, rewired_edges = _community_k_neighbor_edges(
         C, k_val, p_rewire, rnd
     )
@@ -312,7 +386,7 @@ def _community_remesh(
 
 
 def apply_topological_remesh(
-    G,
+    G: CommunityGraph,
     mode: str | None = None,
     *,
     k: int | None = None,
@@ -342,7 +416,7 @@ def apply_topological_remesh(
         )
     mode = str(mode)
     nx, nx_comm = _get_networkx_modules()
-    epi = {n: get_attr(G.nodes[n], ALIAS_EPI, 0.0) for n in nodes}
+    epi = {n: _as_float(get_attr(G.nodes[n], ALIAS_EPI, 0.0)) for n in nodes}
     mst_edges = _mst_edges_from_epi(nx, nodes, epi)
     default_k = int(
         G.graph.get(
@@ -374,7 +448,11 @@ def apply_topological_remesh(
         G.add_edges_from(new_edges)
 
 
-def _extra_gating_ok(hist, cfg, w_estab):
+def _extra_gating_ok(
+    hist: MutableMapping[str, Sequence[float]],
+    cfg: Mapping[str, RemeshConfigValue],
+    w_estab: int,
+) -> bool:
     """Check additional stability gating conditions."""
     checks = [
         ("phase_sync", "REMESH_MIN_PHASE_SYNC", ge),
@@ -388,14 +466,24 @@ def _extra_gating_ok(hist, cfg, w_estab):
         if series is not None and len(series) >= w_estab:
             win = series[-w_estab:]
             avg = sum(win) / len(win)
-            if not op(avg, cfg[cfg_key]):
+            threshold = _as_float(cfg[cfg_key])
+            if not op(avg, threshold):
                 return False
     return True
 
 
 def apply_remesh_if_globally_stable(
-    G, pasos_estables_consecutivos: int | None = None
+    G: CommunityGraph,
+    stable_step_window: int | None = None,
+    **kwargs: Any,
 ) -> None:
+    if kwargs:
+        unexpected = ", ".join(sorted(kwargs))
+        raise TypeError(
+            "apply_remesh_if_globally_stable() got unexpected keyword argument(s): "
+            f"{unexpected}"
+        )
+
     params = [
         (
             "REMESH_STABILITY_WINDOW",
@@ -432,20 +520,16 @@ def apply_remesh_if_globally_stable(
             float,
             REMESH_DEFAULTS["REMESH_MIN_SI_HI_FRAC"],
         ),
-        (
-            "REMESH_COOLDOWN_VENTANA",
-            int,
-            REMESH_DEFAULTS["REMESH_COOLDOWN_VENTANA"],
-        ),
+        (COOLDOWN_KEY, int, REMESH_DEFAULTS[COOLDOWN_KEY]),
         ("REMESH_COOLDOWN_TS", float, REMESH_DEFAULTS["REMESH_COOLDOWN_TS"]),
     ]
     cfg = {}
     for key, conv, _default in params:
         cfg[key] = conv(get_param(G, key))
-    frac_req = float(get_param(G, "FRACTION_STABLE_REMESH"))
+    frac_req = _as_float(get_param(G, "FRACTION_STABLE_REMESH"))
     w_estab = (
-        pasos_estables_consecutivos
-        if pasos_estables_consecutivos is not None
+        stable_step_window
+        if stable_step_window is not None
         else cfg["REMESH_STABILITY_WINDOW"]
     )
 
@@ -463,10 +547,10 @@ def apply_remesh_if_globally_stable(
 
     last = G.graph.get("_last_remesh_step", -(10**9))
     step_idx = len(sf)
-    if step_idx - last < cfg["REMESH_COOLDOWN_VENTANA"]:
+    if step_idx - last < cfg[COOLDOWN_KEY]:
         return
-    t_now = float(G.graph.get("_t", 0.0))
-    last_ts = float(G.graph.get("_last_remesh_ts", -1e12))
+    t_now = _as_float(G.graph.get("_t", 0.0))
+    last_ts = _as_float(G.graph.get("_last_remesh_ts", -1e12))
     if (
         cfg["REMESH_COOLDOWN_TS"] > 0
         and (t_now - last_ts) < cfg["REMESH_COOLDOWN_TS"]

tnfr/presets.py

@@ -1,60 +1,15 @@
-"""Predefined configurations."""
+"""Backward compatibility shim for configuration presets."""
 
 from __future__ import annotations
-from .execution import (
-    CANONICAL_PRESET_NAME,
-    CANONICAL_PROGRAM_TOKENS,
-    block,
-    seq,
-    wait,
-)
-from .types import Glyph
-
-__all__ = ("get_preset",)
 
+import warnings
 
-_PRESETS = {
-    "arranque_resonante": seq(
-        Glyph.AL,
-        Glyph.EN,
-        Glyph.IL,
-        Glyph.RA,
-        Glyph.VAL,
-        Glyph.UM,
-        wait(3),
-        Glyph.SHA,
-    ),
-    "mutacion_contenida": seq(
-        Glyph.AL,
-        Glyph.EN,
-        block(Glyph.OZ, Glyph.ZHIR, Glyph.IL, repeat=2),
-        Glyph.RA,
-        Glyph.SHA,
-    ),
-    "exploracion_acople": seq(
-        Glyph.AL,
-        Glyph.EN,
-        Glyph.IL,
-        Glyph.VAL,
-        Glyph.UM,
-        block(Glyph.OZ, Glyph.NAV, Glyph.IL, repeat=1),
-        Glyph.RA,
-        Glyph.SHA,
-    ),
-    CANONICAL_PRESET_NAME: list(CANONICAL_PROGRAM_TOKENS),
-    # Topologías fractales: expansión/contracción modular
-    "fractal_expand": seq(
-        block(Glyph.THOL, Glyph.VAL, Glyph.UM, repeat=2, close=Glyph.NUL),
-        Glyph.RA,
-    ),
-    "fractal_contract": seq(
-        block(Glyph.THOL, Glyph.NUL, Glyph.UM, repeat=2, close=Glyph.SHA),
-        Glyph.RA,
-    ),
-}
+from .config.presets import get_preset
 
+warnings.warn(
+    "'tnfr.presets' is deprecated; use 'tnfr.config.presets' instead",
+    DeprecationWarning,
+    stacklevel=2,
+)
 
-def get_preset(name: str):
-    if name not in _PRESETS:
-        raise KeyError(f"Preset no encontrado: {name}")
-    return _PRESETS[name]
+__all__ = ("get_preset",)

tnfr/presets.pyi

@@ -0,0 +1,7 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+get_preset: Any