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

tnfr/constants/__init__.py

@@ -1,144 +1,56 @@
-"""Shared constants."""
+"""Shared constants (backward compatibility layer).
 
-from __future__ import annotations
+This module re-exports configuration from tnfr.config for backward compatibility.
+New code should import directly from tnfr.config.
+
+Migration Path:
+    Old: from tnfr.constants import DEFAULTS, inject_defaults
+    New: from tnfr.config import DEFAULTS, inject_defaults
+"""
 
-from typing import Any, Callable
-from collections.abc import Mapping
-import copy
-from types import MappingProxyType
+from __future__ import annotations
 
-from .core import CORE_DEFAULTS, REMESH_DEFAULTS
-from .init import INIT_DEFAULTS
-from .metric import (
+# Re-export all constants and utilities from tnfr.config
+from ..config import (
+    ALIASES,
+    CANONICAL_STATE_TOKENS,
+    COHERENCE,
+    CORE_DEFAULTS,
+    D2EPI_PRIMARY,
+    D2VF_PRIMARY,
+    DEFAULT_SECTIONS,
+    DEFAULTS,
+    DIAGNOSIS,
+    DNFR_PRIMARY,
+    EPI_KIND_PRIMARY,
+    EPI_PRIMARY,
+    GRAMMAR_CANON,
+    INIT_DEFAULTS,
     METRIC_DEFAULTS,
+    METRICS,
+    REMESH_DEFAULTS,
+    SI_PRIMARY,
     SIGMA,
+    STATE_DISSONANT,
+    STATE_STABLE,
+    STATE_TRANSITION,
+    THETA_KEY,
+    THETA_PRIMARY,
     TRACE,
-    METRICS,
-    GRAMMAR_CANON,
-    COHERENCE,
-    DIAGNOSIS,
-)
-
-from ..immutable import _is_immutable
-
-try:  # pragma: no cover - optional dependency
-    from ..cache import ensure_node_offset_map
-except ImportError:  # noqa: BLE001 - allow any import error
-    ensure_node_offset_map = None
-
-# Secciones individuales exportadas
-DEFAULT_SECTIONS: Mapping[str, Mapping[str, Any]] = MappingProxyType(
-    {
-        "core": CORE_DEFAULTS,
-        "init": INIT_DEFAULTS,
-        "remesh": REMESH_DEFAULTS,
-        "metric": METRIC_DEFAULTS,
-    }
+    VF_KEY,
+    VF_PRIMARY,
+    dEPI_PRIMARY,
+    dSI_PRIMARY,
+    dVF_PRIMARY,
+    ensure_node_offset_map,
+    get_aliases,
+    get_graph_param,
+    get_param,
+    inject_defaults,
+    merge_overrides,
+    normalise_state_token,
 )
 
-# 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(
-    CORE_DEFAULTS | INIT_DEFAULTS | REMESH_DEFAULTS | METRIC_DEFAULTS
-)
-
-# -------------------------
-# Utilidades
-# -------------------------
-
-
-def inject_defaults(
-    G, defaults: Mapping[str, Any] = DEFAULTS, override: bool = False
-) -> None:
-    """Inject ``defaults`` into ``G.graph``.
-
-    ``defaults`` is usually ``DEFAULTS``, combining all sub-dictionaries.
-    If ``override`` is ``True`` existing values are overwritten. Immutable
-    values (numbers, strings, tuples, etc.) are assigned directly. Tuples are
-    inspected recursively; if any element is mutable, a ``deepcopy`` is made
-    to avoid shared state.
-    """
-    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["_tnfr_defaults_attached"] = True
-    if ensure_node_offset_map is not None:
-        ensure_node_offset_map(G)
-
-
-def merge_overrides(G, **overrides) -> None:
-    """Apply specific changes to ``G.graph``.
-
-    Non-immutable values are deep-copied to avoid shared state with
-    :data:`DEFAULTS`.
-    """
-    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)
-
-
-def get_param(G, key: str):
-    """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}'")
-    return DEFAULTS[key]
-
-
-def get_graph_param(G, key: str, cast: Callable[[Any], Any] = float):
-    """Return ``key`` from ``G.graph`` applying ``cast``.
-
-    The ``cast`` argument must be a function (e.g. ``float``, ``int``,
-    ``bool``). If the stored value is ``None`` it is returned without
-    casting.
-    """
-    val = get_param(G, key)
-    return None if val is None else cast(val)
-
-
-# Claves canónicas con nombres ASCII
-VF_KEY = "νf"
-THETA_KEY = "θ"
-
-# Mapa de aliases para atributos nodales
-ALIASES: dict[str, tuple[str, ...]] = {
-    "VF": (VF_KEY, "nu_f", "nu-f", "nu", "freq", "frequency"),
-    "THETA": (THETA_KEY, "theta", "fase", "phi", "phase"),
-    "DNFR": ("ΔNFR", "delta_nfr", "dnfr"),
-    "EPI": ("EPI", "psi", "PSI", "value"),
-    "EPI_KIND": ("EPI_kind", "epi_kind", "source_glyph"),
-    "SI": ("Si", "sense_index", "S_i", "sense", "meaning_index"),
-    "DEPI": ("dEPI_dt", "dpsi_dt", "dEPI", "velocity"),
-    "D2EPI": ("d2EPI_dt2", "d2psi_dt2", "d2EPI", "accel"),
-    "DVF": ("dνf_dt", "dvf_dt", "dnu_dt", "dvf"),
-    "D2VF": ("d2νf_dt2", "d2vf_dt2", "d2nu_dt2", "B"),
-    "DSI": ("δSi", "delta_Si", "dSi"),
-}
-
-
-def get_aliases(key: str) -> tuple[str, ...]:
-    """Return alias tuple for canonical ``key``."""
-
-    return ALIASES[key]
-
-
-VF_PRIMARY = get_aliases("VF")[0]
-THETA_PRIMARY = get_aliases("THETA")[0]
-DNFR_PRIMARY = get_aliases("DNFR")[0]
-EPI_PRIMARY = get_aliases("EPI")[0]
-EPI_KIND_PRIMARY = get_aliases("EPI_KIND")[0]
-SI_PRIMARY = get_aliases("SI")[0]
-dEPI_PRIMARY = get_aliases("DEPI")[0]
-D2EPI_PRIMARY = get_aliases("D2EPI")[0]
-dVF_PRIMARY = get_aliases("DVF")[0]
-D2VF_PRIMARY = get_aliases("D2VF")[0]
-dSI_PRIMARY = get_aliases("DSI")[0]
-
 __all__ = (
     "CORE_DEFAULTS",
     "INIT_DEFAULTS",
@@ -171,4 +83,10 @@ __all__ = (
     "dVF_PRIMARY",
     "D2VF_PRIMARY",
     "dSI_PRIMARY",
+    "STATE_STABLE",
+    "STATE_TRANSITION",
+    "STATE_DISSONANT",
+    "CANONICAL_STATE_TOKENS",
+    "normalise_state_token",
+    "ensure_node_offset_map",
 )

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,33 @@
+"""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")
+ALIAS_EMISSION_TIMESTAMP = get_aliases("EMISSION_TIMESTAMP")
+
+__all__ = [
+    "ALIAS_VF",
+    "ALIAS_THETA",
+    "ALIAS_DNFR",
+    "ALIAS_EPI",
+    "ALIAS_EPI_KIND",
+    "ALIAS_SI",
+    "ALIAS_DEPI",
+    "ALIAS_D2EPI",
+    "ALIAS_DVF",
+    "ALIAS_D2VF",
+    "ALIAS_DSI",
+    "ALIAS_EMISSION_TIMESTAMP",
+]

tnfr/constants/aliases.pyi

@@ -0,0 +1,27 @@
+from _typeshed import Incomplete
+
+__all__ = [
+    "ALIAS_VF",
+    "ALIAS_THETA",
+    "ALIAS_DNFR",
+    "ALIAS_EPI",
+    "ALIAS_EPI_KIND",
+    "ALIAS_SI",
+    "ALIAS_DEPI",
+    "ALIAS_D2EPI",
+    "ALIAS_DVF",
+    "ALIAS_D2VF",
+    "ALIAS_DSI",
+]
+
+ALIAS_VF: Incomplete
+ALIAS_THETA: Incomplete
+ALIAS_DNFR: Incomplete
+ALIAS_EPI: Incomplete
+ALIAS_EPI_KIND: Incomplete
+ALIAS_SI: Incomplete
+ALIAS_DEPI: Incomplete
+ALIAS_D2EPI: Incomplete
+ALIAS_DVF: Incomplete
+ALIAS_D2VF: Incomplete
+ALIAS_DSI: Incomplete

tnfr/constants/init.py

@@ -2,8 +2,10 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass, asdict
 import math
+from dataclasses import asdict
+
+from ..compat.dataclass import 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,11 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass, asdict, field
-from typing import Any
+from dataclasses import asdict, field
 from types import MappingProxyType
+from typing import Any
+
+from ..compat.dataclass import dataclass
 
 
 @dataclass(frozen=True, slots=True)
@@ -27,7 +29,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 +37,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 +46,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 +69,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/core/__init__.py

@@ -0,0 +1,33 @@
+"""Core architectural components for TNFR engine.
+
+This package contains the foundational interfaces and dependency injection
+infrastructure that enable separation of responsibilities across the TNFR
+engine layers.
+
+Public API
+----------
+OperatorRegistry, ValidationService, DynamicsEngine, TelemetryCollector
+    Protocol interfaces defining contracts for each architectural layer.
+TNFRContainer
+    Dependency injection container for configuring engine components.
+"""
+
+from __future__ import annotations
+
+from .container import TNFRContainer
+from .interfaces import (
+    DynamicsEngine,
+    OperatorRegistry,
+    TelemetryCollector,
+    TraceContext,
+    ValidationService,
+)
+
+__all__ = (
+    "OperatorRegistry",
+    "ValidationService",
+    "DynamicsEngine",
+    "TelemetryCollector",
+    "TraceContext",
+    "TNFRContainer",
+)