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

tnfr/config/presets.py

@@ -0,0 +1,104 @@
+"""Predefined TNFR configuration sequences.
+
+Only the canonical English preset identifiers are recognised.
+"""
+
+from __future__ import annotations
+
+from ..execution import (
+    CANONICAL_PRESET_NAME,
+    CANONICAL_PROGRAM_TOKENS,
+    block,
+    seq,
+    wait,
+)
+from ..types import Glyph, PresetTokens
+
+__all__ = (
+    "get_preset",
+    "PREFERRED_PRESET_NAMES",
+    "legacy_preset_guidance",
+)
+
+
+_PRIMARY_PRESETS: dict[str, PresetTokens] = {
+    "resonant_bootstrap": seq(
+        Glyph.AL,
+        Glyph.EN,
+        Glyph.IL,
+        Glyph.RA,
+        Glyph.VAL,
+        Glyph.UM,
+        wait(3),
+        Glyph.SHA,
+    ),
+    "contained_mutation": seq(
+        Glyph.AL,
+        Glyph.EN,
+        block(Glyph.OZ, Glyph.ZHIR, Glyph.IL, repeat=2),
+        Glyph.RA,
+        Glyph.SHA,
+    ),
+    "coupling_exploration": seq(
+        Glyph.AL,
+        Glyph.EN,
+        Glyph.IL,
+        Glyph.VAL,
+        Glyph.UM,
+        block(Glyph.OZ, Glyph.NAV, Glyph.IL, repeat=1),
+        Glyph.RA,
+        Glyph.SHA,
+    ),
+    "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,
+    ),
+    CANONICAL_PRESET_NAME: list(CANONICAL_PROGRAM_TOKENS),
+}
+
+PREFERRED_PRESET_NAMES: tuple[str, ...] = tuple(_PRIMARY_PRESETS.keys())
+
+_PRESETS: dict[str, PresetTokens] = {**_PRIMARY_PRESETS}
+
+
+_LEGACY_PRESET_ALIASES: dict[str, str] = {
+    "arranque_resonante": "resonant_bootstrap",
+    "mutacion_contenida": "contained_mutation",
+    "exploracion_acople": "coupling_exploration",
+    "ejemplo_canonico": CANONICAL_PRESET_NAME,
+}
+
+
+def legacy_preset_guidance(name: str) -> str | None:
+    """Return CLI guidance for historical preset aliases.
+
+    Parameters
+    ----------
+    name:
+        Identifier received from the CLI.
+
+    Returns
+    -------
+    str | None
+        A human readable guidance string when ``name`` matches a removed
+        alias. ``None`` when no dedicated guidance is available.
+    """
+
+    canonical = _LEGACY_PRESET_ALIASES.get(name)
+    if canonical is None:
+        return None
+    return (
+        f"Legacy preset identifier '{name}' was removed in TNFR 9.0. "
+        f"Use '{canonical}' instead."
+    )
+
+
+def get_preset(name: str) -> PresetTokens:
+    try:
+        return _PRESETS[name]
+    except KeyError:
+        raise KeyError(f"Preset not found: {name}") from None

tnfr/config/presets.pyi

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

tnfr/constants/__init__.py

@@ -2,10 +2,10 @@
 
 from __future__ import annotations
 
-from typing import Any, Callable
-from collections.abc import Mapping
 import copy
+from collections.abc import Mapping
 from types import MappingProxyType
+from typing import Callable, TypeVar, cast
 
 from .core import CORE_DEFAULTS, REMESH_DEFAULTS
 from .init import INIT_DEFAULTS
@@ -20,14 +20,51 @@ from .metric import (
 )
 
 from ..immutable import _is_immutable
+from ..types import GraphLike, TNFRConfigValue
+
+T = TypeVar("T")
+
+STATE_STABLE = "stable"
+STATE_TRANSITION = "transition"
+STATE_DISSONANT = "dissonant"
+
+CANONICAL_STATE_TOKENS = frozenset(
+    {STATE_STABLE, STATE_TRANSITION, STATE_DISSONANT}
+)
+
+def normalise_state_token(token: str) -> str:
+    """Return the canonical English token for ``token``.
+
+    The helper now enforces the English identifiers exclusively. Values that
+    do not match the canonical set raise :class:`ValueError` so callers can
+    surface explicit migration errors when legacy payloads are encountered.
+    """
+
+    if not isinstance(token, str):
+        raise TypeError("state token must be a string")
+
+    stripped = token.strip()
+    lowered = stripped.lower()
+
+    if stripped in CANONICAL_STATE_TOKENS:
+        return stripped
+
+    if lowered in CANONICAL_STATE_TOKENS:
+        return lowered
+
+    raise ValueError(
+        "state token must be one of 'stable', 'transition', or 'dissonant'"
+    )
 
 try:  # pragma: no cover - optional dependency
-    from ..cache import ensure_node_offset_map
+    from ..utils import ensure_node_offset_map as _ensure_node_offset_map
 except ImportError:  # noqa: BLE001 - allow any import error
-    ensure_node_offset_map = None
+    _ensure_node_offset_map = None
+
+ensure_node_offset_map: Callable[[GraphLike], None] | None = _ensure_node_offset_map
 
-# Secciones individuales exportadas
-DEFAULT_SECTIONS: Mapping[str, Mapping[str, Any]] = MappingProxyType(
+# Exported sections
+DEFAULT_SECTIONS: Mapping[str, Mapping[str, TNFRConfigValue]] = MappingProxyType(
     {
         "core": CORE_DEFAULTS,
         "init": INIT_DEFAULTS,
@@ -36,21 +73,23 @@ DEFAULT_SECTIONS: Mapping[str, Mapping[str, Any]] = MappingProxyType(
     }
 )
 
-# Diccionario combinado exportado
-# Unimos los diccionarios en orden de menor a mayor prioridad para que los
-# valores de ``METRIC_DEFAULTS`` sobrescriban al resto, como hacía
-# ``ChainMap``.
-DEFAULTS: Mapping[str, Any] = MappingProxyType(
+# Combined exported dictionary
+# Merge the dictionaries from lowest to highest priority so that
+# ``METRIC_DEFAULTS`` overrides the rest, mirroring the previous ``ChainMap``
+# behaviour.
+DEFAULTS: Mapping[str, TNFRConfigValue] = MappingProxyType(
     CORE_DEFAULTS | INIT_DEFAULTS | REMESH_DEFAULTS | METRIC_DEFAULTS
 )
 
 # -------------------------
-# Utilidades
+# Utilities
 # -------------------------
 
 
 def inject_defaults(
-    G, defaults: Mapping[str, Any] = DEFAULTS, override: bool = False
+    G: GraphLike,
+    defaults: Mapping[str, TNFRConfigValue] = DEFAULTS,
+    override: bool = False,
 ) -> None:
     """Inject ``defaults`` into ``G.graph``.
 
@@ -63,13 +102,17 @@ def inject_defaults(
     G.graph.setdefault("_tnfr_defaults_attached", False)
     for k, v in defaults.items():
         if override or k not in G.graph:
-            G.graph[k] = v if _is_immutable(v) else copy.deepcopy(v)
+            G.graph[k] = (
+                v
+                if _is_immutable(v)
+                else cast(TNFRConfigValue, copy.deepcopy(v))
+            )
     G.graph["_tnfr_defaults_attached"] = True
     if ensure_node_offset_map is not None:
         ensure_node_offset_map(G)
 
 
-def merge_overrides(G, **overrides) -> None:
+def merge_overrides(G: GraphLike, **overrides: TNFRConfigValue) -> None:
     """Apply specific changes to ``G.graph``.
 
     Non-immutable values are deep-copied to avoid shared state with
@@ -77,20 +120,26 @@ def merge_overrides(G, **overrides) -> None:
     """
     for key, value in overrides.items():
         if key not in DEFAULTS:
-            raise KeyError(f"Parámetro desconocido: '{key}'")
-        G.graph[key] = value if _is_immutable(value) else copy.deepcopy(value)
+            raise KeyError(f"Unknown parameter: '{key}'")
+        G.graph[key] = (
+            value
+            if _is_immutable(value)
+            else cast(TNFRConfigValue, copy.deepcopy(value))
+        )
 
 
-def get_param(G, key: str):
+def get_param(G: GraphLike, key: str) -> TNFRConfigValue:
     """Retrieve a parameter from ``G.graph`` or fall back to defaults."""
     if key in G.graph:
         return G.graph[key]
     if key not in DEFAULTS:
-        raise KeyError(f"Parámetro desconocido: '{key}'")
+        raise KeyError(f"Unknown parameter: '{key}'")
     return DEFAULTS[key]
 
 
-def get_graph_param(G, key: str, cast: Callable[[Any], Any] = float):
+def get_graph_param(
+    G: GraphLike, key: str, cast: Callable[[object], T] = float
+) -> T | None:
     """Return ``key`` from ``G.graph`` applying ``cast``.
 
     The ``cast`` argument must be a function (e.g. ``float``, ``int``,
@@ -101,14 +150,14 @@ def get_graph_param(G, key: str, cast: Callable[[Any], Any] = float):
     return None if val is None else cast(val)
 
 
-# Claves canónicas con nombres ASCII
+# Canonical keys with ASCII spellings
 VF_KEY = "νf"
-THETA_KEY = "θ"
+THETA_KEY = "theta"
 
-# Mapa de aliases para atributos nodales
+# Alias map for node attributes
 ALIASES: dict[str, tuple[str, ...]] = {
     "VF": (VF_KEY, "nu_f", "nu-f", "nu", "freq", "frequency"),
-    "THETA": (THETA_KEY, "theta", "fase", "phi", "phase"),
+    "THETA": (THETA_KEY, "phase"),
     "DNFR": ("ΔNFR", "delta_nfr", "dnfr"),
     "EPI": ("EPI", "psi", "PSI", "value"),
     "EPI_KIND": ("EPI_kind", "epi_kind", "source_glyph"),
@@ -171,4 +220,9 @@ __all__ = (
     "dVF_PRIMARY",
     "D2VF_PRIMARY",
     "dSI_PRIMARY",
+    "STATE_STABLE",
+    "STATE_TRANSITION",
+    "STATE_DISSONANT",
+    "CANONICAL_STATE_TOKENS",
+    "normalise_state_token",
 )

tnfr/constants/__init__.pyi

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Callable, TypeVar
+
+from .core import CORE_DEFAULTS as CORE_DEFAULTS, REMESH_DEFAULTS as REMESH_DEFAULTS
+from .init import INIT_DEFAULTS as INIT_DEFAULTS
+from .metric import (
+    COHERENCE as COHERENCE,
+    DIAGNOSIS as DIAGNOSIS,
+    GRAMMAR_CANON as GRAMMAR_CANON,
+    METRICS as METRICS,
+    METRIC_DEFAULTS as METRIC_DEFAULTS,
+    SIGMA as SIGMA,
+    TRACE as TRACE,
+)
+from ..types import GraphLike, TNFRConfigValue
+
+T = TypeVar("T")
+
+__all__ = (
+    "CORE_DEFAULTS",
+    "INIT_DEFAULTS",
+    "REMESH_DEFAULTS",
+    "METRIC_DEFAULTS",
+    "SIGMA",
+    "TRACE",
+    "METRICS",
+    "GRAMMAR_CANON",
+    "COHERENCE",
+    "DIAGNOSIS",
+    "DEFAULTS",
+    "DEFAULT_SECTIONS",
+    "ALIASES",
+    "inject_defaults",
+    "merge_overrides",
+    "get_param",
+    "get_graph_param",
+    "get_aliases",
+    "VF_KEY",
+    "THETA_KEY",
+    "VF_PRIMARY",
+    "THETA_PRIMARY",
+    "DNFR_PRIMARY",
+    "EPI_PRIMARY",
+    "EPI_KIND_PRIMARY",
+    "SI_PRIMARY",
+    "dEPI_PRIMARY",
+    "D2EPI_PRIMARY",
+    "dVF_PRIMARY",
+    "D2VF_PRIMARY",
+    "dSI_PRIMARY",
+    "STATE_STABLE",
+    "STATE_TRANSITION",
+    "STATE_DISSONANT",
+    "CANONICAL_STATE_TOKENS",
+    "normalise_state_token",
+)
+
+ensure_node_offset_map: Callable[[GraphLike], None] | None
+DEFAULT_SECTIONS: Mapping[str, Mapping[str, TNFRConfigValue]]
+DEFAULTS: Mapping[str, TNFRConfigValue]
+ALIASES: dict[str, tuple[str, ...]]
+VF_KEY: str
+THETA_KEY: str
+VF_PRIMARY: str
+THETA_PRIMARY: str
+DNFR_PRIMARY: str
+EPI_PRIMARY: str
+EPI_KIND_PRIMARY: str
+SI_PRIMARY: str
+dEPI_PRIMARY: str
+D2EPI_PRIMARY: str
+dVF_PRIMARY: str
+D2VF_PRIMARY: str
+dSI_PRIMARY: str
+STATE_STABLE: str
+STATE_TRANSITION: str
+STATE_DISSONANT: str
+CANONICAL_STATE_TOKENS: frozenset[str]
+
+
+def inject_defaults(
+    G: GraphLike,
+    defaults: Mapping[str, TNFRConfigValue] = ...,
+    override: bool = ...,
+) -> None: ...
+
+
+def merge_overrides(G: GraphLike, **overrides: TNFRConfigValue) -> None: ...
+
+
+def get_param(G: GraphLike, key: str) -> TNFRConfigValue: ...
+
+
+def get_graph_param(
+    G: GraphLike, key: str, cast: Callable[[object], T] = ...
+) -> T | None: ...
+
+
+def get_aliases(key: str) -> tuple[str, ...]: ...
+
+
+def normalise_state_token(token: str) -> str: ...

tnfr/constants/core.py

@@ -134,7 +134,7 @@ class RemeshDefaults:
     EPS_DNFR_STABLE: float = 1e-3
     EPS_DEPI_STABLE: float = 1e-3
     FRACTION_STABLE_REMESH: float = 0.80
-    REMESH_COOLDOWN_VENTANA: int = 20
+    REMESH_COOLDOWN_WINDOW: int = 20
     REMESH_COOLDOWN_TS: float = 0.0
     REMESH_REQUIRE_STABILITY: bool = True
     REMESH_STABILITY_WINDOW: int = 25
@@ -151,7 +151,6 @@ class RemeshDefaults:
     REMESH_ALPHA: float = 0.5
     REMESH_ALPHA_HARD: bool = False
 
-
 _core_defaults = asdict(CoreDefaults())
 _remesh_defaults = asdict(RemeshDefaults())
 

tnfr/constants/core.pyi

@@ -0,0 +1,17 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+CORE_DEFAULTS: Any
+CoreDefaults: Any
+Mapping: Any
+MappingProxyType: Any
+REMESH_DEFAULTS: Any
+RemeshDefaults: Any
+SELECTOR_THRESHOLD_DEFAULTS: Any
+annotations: Any
+asdict: Any
+dataclass: Any
+field: Any

tnfr/constants/init.pyi

@@ -0,0 +1,12 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+INIT_DEFAULTS: Any
+InitDefaults: Any
+annotations: Any
+asdict: Any
+dataclass: Any
+math: Any

tnfr/constants/metric.py

@@ -35,18 +35,7 @@ class MetricDefaults:
     TRACE: dict[str, Any] = field(
         default_factory=lambda: {
             "enabled": True,
-            "capture": [
-                "gamma",
-                "grammar",
-                "selector",
-                "dnfr_weights",
-                "si_weights",
-                "callbacks",
-                "thol_open_nodes",
-                "sigma",
-                "kuramoto",
-                "glyph_counts",
-            ],
+            "verbosity": "debug",
             "history_key": "trace_meta",
         }
     )
@@ -55,6 +44,8 @@ class MetricDefaults:
             "enabled": True,
             "save_by_node": True,
             "normalize_series": False,
+            "n_jobs": 1,
+            "verbosity": "debug",
         }
     )
     GRAMMAR_CANON: dict[str, Any] = field(
@@ -76,6 +67,7 @@ class MetricDefaults:
             "self_on_diag": True,
             "store_mode": "sparse",
             "threshold": 0.0,
+            "n_jobs": 1,
             "history_key": "W_sparse",
             "Wi_history_key": "W_i",
             "stats_history_key": "W_stats",

tnfr/constants/metric.pyi

@@ -0,0 +1,19 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+COHERENCE: Any
+DIAGNOSIS: Any
+GRAMMAR_CANON: Any
+METRICS: Any
+METRIC_DEFAULTS: Any
+MappingProxyType: Any
+MetricDefaults: Any
+SIGMA: Any
+TRACE: Any
+annotations: Any
+asdict: Any
+dataclass: Any
+field: Any

tnfr/constants_glyphs.py

@@ -1,98 +1,16 @@
-"""Default glyphs."""
+"""Backward compatibility shim for glyph constants."""
 
 from __future__ import annotations
 
-import math
-from types import MappingProxyType
-from typing import Mapping
+import warnings
 
-from .types import Glyph
+from .config.constants import *  # noqa: F401,F403 - re-export legacy API
+from .config.constants import __all__ as _CONFIG_ALL
 
-# -------------------------
-# Orden canónico y clasificaciones funcionales
-# -------------------------
-
-GLYPHS_CANONICAL: tuple[str, ...] = (
-    Glyph.AL.value,  # 0
-    Glyph.EN.value,  # 1
-    Glyph.IL.value,  # 2
-    Glyph.OZ.value,  # 3
-    Glyph.UM.value,  # 4
-    Glyph.RA.value,  # 5
-    Glyph.SHA.value,  # 6
-    Glyph.VAL.value,  # 7
-    Glyph.NUL.value,  # 8
-    Glyph.THOL.value,  # 9
-    Glyph.ZHIR.value,  # 10
-    Glyph.NAV.value,  # 11
-    Glyph.REMESH.value,  # 12
+warnings.warn(
+    "'tnfr.constants_glyphs' is deprecated; use 'tnfr.config.constants' instead",
+    DeprecationWarning,
+    stacklevel=2,
 )
 
-GLYPHS_CANONICAL_SET: frozenset[str] = frozenset(GLYPHS_CANONICAL)
-
-ESTABILIZADORES = (
-    Glyph.IL.value,
-    Glyph.RA.value,
-    Glyph.UM.value,
-    Glyph.SHA.value,
-)
-
-DISRUPTIVOS = (
-    Glyph.OZ.value,
-    Glyph.ZHIR.value,
-    Glyph.NAV.value,
-    Glyph.THOL.value,
-)
-
-# Mapa general de agrupaciones glíficas para referencia cruzada.
-GLYPH_GROUPS: Mapping[str, tuple[str, ...]] = MappingProxyType(
-    {
-        "estabilizadores": ESTABILIZADORES,
-        "disruptivos": DISRUPTIVOS,
-        # Grupos auxiliares para métricas morfosintácticas
-        "ID": (Glyph.OZ.value,),
-        "CM": (Glyph.ZHIR.value, Glyph.NAV.value),
-        "NE": (Glyph.IL.value, Glyph.THOL.value),
-        "PP_num": (Glyph.SHA.value,),
-        "PP_den": (Glyph.REMESH.value,),
-    }
-)
-
-# -------------------------
-# Mapa de ángulos glíficos
-# -------------------------
-
-# Ángulos canónicos para todos los glyphs reconocidos. Se calculan a partir
-# del orden canónico y reglas de orientación para las categorías
-# "estabilizadores" y "disruptivos".
-
-
-def _build_angle_map() -> dict[str, float]:
-    """Construir el mapa de ángulos en el plano σ."""
-    step = 2 * math.pi / len(GLYPHS_CANONICAL)
-    canonical = {g: i * step for i, g in enumerate(GLYPHS_CANONICAL)}
-    angles = dict(canonical)
-
-    # Reglas específicas de orientación
-    for idx, g in enumerate(ESTABILIZADORES):
-        angles[g] = idx * math.pi / 4
-    for idx, g in enumerate(DISRUPTIVOS):
-        angles[g] = math.pi + idx * math.pi / 4
-
-    # Excepciones manuales
-    angles[Glyph.VAL.value] = canonical[Glyph.RA.value]
-    angles[Glyph.NUL.value] = canonical[Glyph.ZHIR.value]
-    angles[Glyph.AL.value] = 0.0
-    return angles
-
-
-ANGLE_MAP: Mapping[str, float] = MappingProxyType(_build_angle_map())
-
-__all__ = (
-    "GLYPHS_CANONICAL",
-    "GLYPHS_CANONICAL_SET",
-    "ESTABILIZADORES",
-    "DISRUPTIVOS",
-    "GLYPH_GROUPS",
-    "ANGLE_MAP",
-)
+__all__ = _CONFIG_ALL

tnfr/constants_glyphs.pyi

@@ -0,0 +1,12 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+ANGLE_MAP: Any
+DISRUPTORS: Any
+STABILIZERS: Any
+GLYPHS_CANONICAL: Any
+GLYPHS_CANONICAL_SET: Any
+GLYPH_GROUPS: Any