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

tnfr/constants/__init__.py

@@ -2,32 +2,68 @@
 
 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 ..immutable import _is_immutable
+from ..types import GraphLike, TNFRConfigValue
 from .core import CORE_DEFAULTS, REMESH_DEFAULTS
 from .init import INIT_DEFAULTS
 from .metric import (
+    COHERENCE,
+    DIAGNOSIS,
+    GRAMMAR_CANON,
     METRIC_DEFAULTS,
+    METRICS,
     SIGMA,
     TRACE,
-    METRICS,
-    GRAMMAR_CANON,
-    COHERENCE,
-    DIAGNOSIS,
 )
 
-from ..immutable import _is_immutable
+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 +72,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 +101,15 @@ 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 +117,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 +147,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 +217,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,92 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Callable, TypeVar
+
+from ..types import GraphLike, TNFRConfigValue
+from .core import CORE_DEFAULTS as CORE_DEFAULTS
+from .core import REMESH_DEFAULTS as REMESH_DEFAULTS
+from .init import INIT_DEFAULTS as INIT_DEFAULTS
+from .metric import COHERENCE as COHERENCE
+from .metric import DIAGNOSIS as DIAGNOSIS
+from .metric import GRAMMAR_CANON as GRAMMAR_CANON
+from .metric import METRIC_DEFAULTS as METRIC_DEFAULTS
+from .metric import METRICS as METRICS
+from .metric import SIGMA as SIGMA
+from .metric import TRACE as TRACE
+
+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/aliases.py

@@ -0,0 +1,31 @@
+"""Shared alias constants for TNFR attributes."""
+
+from __future__ import annotations
+
+from . import get_aliases
+
+ALIAS_VF = get_aliases("VF")
+ALIAS_THETA = get_aliases("THETA")
+ALIAS_DNFR = get_aliases("DNFR")
+ALIAS_EPI = get_aliases("EPI")
+ALIAS_EPI_KIND = get_aliases("EPI_KIND")
+ALIAS_SI = get_aliases("SI")
+ALIAS_DEPI = get_aliases("DEPI")
+ALIAS_D2EPI = get_aliases("D2EPI")
+ALIAS_DVF = get_aliases("DVF")
+ALIAS_D2VF = get_aliases("D2VF")
+ALIAS_DSI = get_aliases("DSI")
+
+__all__ = [
+    "ALIAS_VF",
+    "ALIAS_THETA",
+    "ALIAS_DNFR",
+    "ALIAS_EPI",
+    "ALIAS_EPI_KIND",
+    "ALIAS_SI",
+    "ALIAS_DEPI",
+    "ALIAS_D2EPI",
+    "ALIAS_DVF",
+    "ALIAS_D2VF",
+    "ALIAS_DSI",
+]

tnfr/constants/core.py

@@ -2,10 +2,9 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass, asdict, field
-from typing import Any, Mapping
+from dataclasses import asdict, dataclass, field
 from types import MappingProxyType
-
+from typing import Any, Mapping
 
 SELECTOR_THRESHOLD_DEFAULTS: Mapping[str, float] = MappingProxyType(
     {
@@ -72,6 +71,7 @@ class CoreDefaults:
     GLYPH_SELECTOR_MARGIN: float = 0.05
     VF_ADAPT_TAU: int = 5
     VF_ADAPT_MU: float = 0.1
+    HZ_STR_BRIDGE: float = 1.0
     GLYPH_FACTORS: dict[str, float] = field(
         default_factory=lambda: {
             "AL_boost": 0.05,
@@ -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

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.py

@@ -2,8 +2,8 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass, asdict
 import math
+from dataclasses import asdict, dataclass
 
 
 @dataclass(frozen=True, slots=True)

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

@@ -2,9 +2,9 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass, asdict, field
-from typing import Any
+from dataclasses import asdict, dataclass, field
 from types import MappingProxyType
+from typing import Any
 
 
 @dataclass(frozen=True, slots=True)
@@ -27,7 +27,7 @@ class MetricDefaults:
         default_factory=lambda: {
             "enabled": True,
             "weight": "Si",  # "Si" | "EPI" | "1"
-            "smooth": 0.0,  # EMA sobre el vector global (0=off)
+            "smooth": 0.0,  # EMA over the global vector (0=off)
             "history_key": "sigma_global",
             "per_node": False,
         }
@@ -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