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

tnfr/compat/numpy_stub.py

@@ -0,0 +1,155 @@
+"""Lightweight stub for numpy when it's not installed.
+
+This stub provides minimal type compatibility for numpy when it's not installed,
+allowing type checking to succeed. At runtime, actual numpy operations will fail
+with informative errors if called without the real numpy package.
+"""
+
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+__all__ = [
+    "ndarray",
+    "float64",
+    "float_",
+    "complex128",
+    "complexfloating",
+    "dtype",
+    "asarray",
+    "array",
+    "eye",
+    "zeros",
+    "ones",
+    "isfinite",
+    "all",
+    "allclose",
+    "diff",
+    "any",
+    "pi",
+]
+
+
+class _NotInstalledError(RuntimeError):
+    """Raised when trying to use numpy operations without numpy installed."""
+
+    def __init__(self, operation: str = "numpy operation") -> None:
+        super().__init__(
+            f"Cannot perform {operation}: numpy is not installed. "
+            "Install it with: pip install numpy"
+        )
+
+
+class ndarray:
+    """Stub for numpy.ndarray type."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        raise _NotInstalledError("array creation")
+
+    @property
+    def shape(self) -> tuple[int, ...]:
+        raise _NotInstalledError("array.shape")
+
+    @property
+    def ndim(self) -> int:
+        raise _NotInstalledError("array.ndim")
+
+    @property
+    def size(self) -> int:
+        raise _NotInstalledError("array.size")
+
+
+class dtype:
+    """Stub for numpy.dtype type."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        raise _NotInstalledError("dtype")
+
+
+class float64:
+    """Stub for numpy.float64 type."""
+
+    pass
+
+
+class float_:
+    """Stub for numpy.float_ type."""
+
+    pass
+
+
+class complex128:
+    """Stub for numpy.complex128 type."""
+
+    pass
+
+
+class complexfloating:
+    """Stub for numpy.complexfloating type."""
+
+    pass
+
+
+def asarray(*args: Any, **kwargs: Any) -> ndarray:
+    """Stub for numpy.asarray."""
+    raise _NotInstalledError("numpy.asarray")
+
+
+def array(*args: Any, **kwargs: Any) -> ndarray:
+    """Stub for numpy.array."""
+    raise _NotInstalledError("numpy.array")
+
+
+def eye(*args: Any, **kwargs: Any) -> ndarray:
+    """Stub for numpy.eye."""
+    raise _NotInstalledError("numpy.eye")
+
+
+def zeros(*args: Any, **kwargs: Any) -> ndarray:
+    """Stub for numpy.zeros."""
+    raise _NotInstalledError("numpy.zeros")
+
+
+def ones(*args: Any, **kwargs: Any) -> ndarray:
+    """Stub for numpy.ones."""
+    raise _NotInstalledError("numpy.ones")
+
+
+def isfinite(*args: Any, **kwargs: Any) -> Any:
+    """Stub for numpy.isfinite."""
+    raise _NotInstalledError("numpy.isfinite")
+
+
+def all(*args: Any, **kwargs: Any) -> Any:
+    """Stub for numpy.all."""
+    raise _NotInstalledError("numpy.all")
+
+
+def allclose(*args: Any, **kwargs: Any) -> Any:
+    """Stub for numpy.allclose."""
+    raise _NotInstalledError("numpy.allclose")
+
+
+def diff(*args: Any, **kwargs: Any) -> ndarray:
+    """Stub for numpy.diff."""
+    raise _NotInstalledError("numpy.diff")
+
+
+def any(*args: Any, **kwargs: Any) -> Any:
+    """Stub for numpy.any."""
+    raise _NotInstalledError("numpy.any")
+
+
+# Constants
+pi: float = 3.141592653589793
+
+
+if TYPE_CHECKING:
+    # Provide typing namespace for numpy.typing when used in TYPE_CHECKING blocks
+    class typing:
+        """Stub for numpy.typing module."""
+
+        class NDArray:
+            """Stub for numpy.typing.NDArray."""
+
+            pass

tnfr/config/__init__.py

@@ -0,0 +1,224 @@
+"""Canonical TNFR configuration system.
+
+This package provides the unified configuration system for TNFR, consolidating:
+- TNFRConfig class with structural invariant validation
+- Secure configuration management (moved from secure_config.py)
+- All default configurations organized by subsystem
+- TNFR semantic mapping (νf, θ, ΔNFR)
+
+Single import path philosophy:
+    from tnfr.config import TNFRConfig, DEFAULTS, get_param
+
+Key Changes (Phase 3):
+- Consolidated constants from constants/ package
+- Integrated secure_config functionality
+- Added TNFR invariant validation
+- Explicit structural coherence principles
+"""
+
+from __future__ import annotations
+
+from .defaults import (
+    COHERENCE,
+    CORE_DEFAULTS,
+    DEFAULT_SECTIONS,
+    DEFAULTS,
+    DIAGNOSIS,
+    GRAMMAR_CANON,
+    INIT_DEFAULTS,
+    METRIC_DEFAULTS,
+    METRICS,
+    REMESH_DEFAULTS,
+    SIGMA,
+    TRACE,
+)
+from .feature_flags import context_flags, get_flags
+from .init import apply_config, load_config
+from .thresholds import (
+    EPSILON_MIN_EMISSION,
+    EPI_LATENT_MAX,
+    MIN_NETWORK_DEGREE_COUPLING,
+    VF_BASAL_THRESHOLD,
+)
+from .tnfr_config import (
+    ALIASES,
+    CANONICAL_STATE_TOKENS,
+    D2EPI_PRIMARY,
+    D2VF_PRIMARY,
+    DNFR_KEY,
+    DNFR_PRIMARY,
+    EPI_KIND_PRIMARY,
+    EPI_PRIMARY,
+    SI_PRIMARY,
+    STATE_DISSONANT,
+    STATE_STABLE,
+    STATE_TRANSITION,
+    THETA_KEY,
+    THETA_PRIMARY,
+    TNFRConfig,
+    TNFRConfigError,
+    VF_KEY,
+    VF_PRIMARY,
+    dEPI_PRIMARY,
+    dSI_PRIMARY,
+    dVF_PRIMARY,
+    get_aliases,
+    normalise_state_token,
+)
+
+# Import compatibility utilities from constants (for backward compat)
+# These will be re-exported through constants/__init__.py
+try:
+    from ..utils import ensure_node_offset_map as _ensure_node_offset_map
+except ImportError:
+    _ensure_node_offset_map = None
+
+ensure_node_offset_map = _ensure_node_offset_map
+
+
+# Legacy function wrappers that use TNFRConfig internally
+def inject_defaults(G, defaults=None, override=False):
+    """Inject defaults into graph (backward compatible wrapper).
+
+    Uses TNFRConfig internally for validation.
+    """
+    config = TNFRConfig(defaults=defaults or DEFAULTS, validate_invariants=True)
+    config.inject_defaults(G, defaults=defaults or DEFAULTS, override=override)
+
+
+def merge_overrides(G, **overrides):
+    """Apply specific overrides to graph configuration.
+
+    Parameters
+    ----------
+    G : GraphLike
+        The graph whose configuration should be updated.
+    **overrides
+        Keyword arguments mapping parameter names to new values.
+
+    Raises
+    ------
+    KeyError
+        If any parameter name is not present in DEFAULTS.
+    """
+    import copy
+    from ..immutable import _is_immutable
+    from ..types import TNFRConfigValue
+    from typing import cast
+
+    for key, value in overrides.items():
+        if key not in DEFAULTS:
+            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):
+    """Retrieve parameter from graph or defaults.
+
+    Parameters
+    ----------
+    G : GraphLike
+        Graph containing configuration.
+    key : str
+        Parameter name.
+
+    Returns
+    -------
+    TNFRConfigValue
+        Configuration value.
+
+    Raises
+    ------
+    KeyError
+        If key not found in graph or DEFAULTS.
+    """
+    if key in G.graph:
+        return G.graph[key]
+    if key not in DEFAULTS:
+        raise KeyError(f"Unknown parameter: '{key}'")
+    return DEFAULTS[key]
+
+
+def get_graph_param(G, key: str, cast_fn=float):
+    """Return parameter from graph applying cast function.
+
+    Parameters
+    ----------
+    G : GraphLike
+        Graph containing configuration.
+    key : str
+        Parameter name.
+    cast_fn : callable, default=float
+        Function to cast value (e.g., float, int, bool).
+
+    Returns
+    -------
+    Any
+        Casted parameter value, or None if value is None.
+    """
+    val = get_param(G, key)
+    return None if val is None else cast_fn(val)
+
+
+__all__ = (
+    # Main configuration class
+    "TNFRConfig",
+    "TNFRConfigError",
+    # File-based configuration
+    "load_config",
+    "apply_config",
+    # Feature flags
+    "get_flags",
+    "context_flags",
+    # Defaults and sections
+    "DEFAULTS",
+    "DEFAULT_SECTIONS",
+    "CORE_DEFAULTS",
+    "INIT_DEFAULTS",
+    "REMESH_DEFAULTS",
+    "METRIC_DEFAULTS",
+    "SIGMA",
+    "TRACE",
+    "METRICS",
+    "GRAMMAR_CANON",
+    "COHERENCE",
+    "DIAGNOSIS",
+    # Operator precondition thresholds
+    "EPI_LATENT_MAX",
+    "VF_BASAL_THRESHOLD",
+    "EPSILON_MIN_EMISSION",
+    "MIN_NETWORK_DEGREE_COUPLING",
+    # TNFR semantic aliases
+    "ALIASES",
+    "VF_KEY",
+    "THETA_KEY",
+    "DNFR_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 tokens
+    "STATE_STABLE",
+    "STATE_TRANSITION",
+    "STATE_DISSONANT",
+    "CANONICAL_STATE_TOKENS",
+    # Utility functions
+    "get_aliases",
+    "normalise_state_token",
+    "inject_defaults",
+    "merge_overrides",
+    "get_param",
+    "get_graph_param",
+    "ensure_node_offset_map",
+)

tnfr/config/__init__.pyi

@@ -0,0 +1,10 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+apply_config: Any
+load_config: Any
+get_flags: Any
+context_flags: Any

tnfr/{constants_glyphs.py → config/constants.py}

@@ -1,4 +1,4 @@
-"""Default glyphs."""
+"""Canonical glyph constants tied to configuration presets."""
 
 from __future__ import annotations
 
@@ -6,10 +6,10 @@ import math
 from types import MappingProxyType
 from typing import Mapping
 
-from .types import Glyph
+from ..types import Glyph
 
 # -------------------------
-# Orden canónico y clasificaciones funcionales
+# Canonical order and functional classifications
 # -------------------------
 
 GLYPHS_CANONICAL: tuple[str, ...] = (
@@ -30,26 +30,31 @@ GLYPHS_CANONICAL: tuple[str, ...] = (
 
 GLYPHS_CANONICAL_SET: frozenset[str] = frozenset(GLYPHS_CANONICAL)
 
-ESTABILIZADORES = (
+STABILIZERS: tuple[str, ...] = (
     Glyph.IL.value,
     Glyph.RA.value,
     Glyph.UM.value,
     Glyph.SHA.value,
 )
 
-DISRUPTIVOS = (
+DISRUPTORS: tuple[str, ...] = (
     Glyph.OZ.value,
     Glyph.ZHIR.value,
     Glyph.NAV.value,
     Glyph.THOL.value,
 )
 
-# Mapa general de agrupaciones glíficas para referencia cruzada.
+# General map of glyph groupings for cross-reference.
+#
+# Spanish keys (``estabilizadores`` / ``disruptivos``) were removed in TNFR 7.0
+# to keep the public surface English-only. Code that still referenced those
+# identifiers must switch to the canonical ``stabilizers`` / ``disruptors``
+# entries or maintain a private compatibility layer.
 GLYPH_GROUPS: Mapping[str, tuple[str, ...]] = MappingProxyType(
     {
-        "estabilizadores": ESTABILIZADORES,
-        "disruptivos": DISRUPTIVOS,
-        # Grupos auxiliares para métricas morfosintácticas
+        "stabilizers": STABILIZERS,
+        "disruptors": DISRUPTORS,
+        # Auxiliary groups for morphosyntactic metrics
         "ID": (Glyph.OZ.value,),
         "CM": (Glyph.ZHIR.value, Glyph.NAV.value),
         "NE": (Glyph.IL.value, Glyph.THOL.value),
@@ -59,27 +64,28 @@ GLYPH_GROUPS: Mapping[str, tuple[str, ...]] = MappingProxyType(
 )
 
 # -------------------------
-# Mapa de ángulos glíficos
+# Glyph angle map
 # -------------------------
 
-# Á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".
+# Canonical angles for all recognised glyphs. They are computed from the
+# canonical order and orientation rules for the "stabilizers" and
+# "disruptors" categories.
 
 
 def _build_angle_map() -> dict[str, float]:
-    """Construir el mapa de ángulos en el plano σ."""
+    """Build the angle map in the σ-plane."""
+
     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):
+    # Orientation rules
+    for idx, g in enumerate(STABILIZERS):
         angles[g] = idx * math.pi / 4
-    for idx, g in enumerate(DISRUPTIVOS):
+    for idx, g in enumerate(DISRUPTORS):
         angles[g] = math.pi + idx * math.pi / 4
 
-    # Excepciones manuales
+    # Manual exceptions
     angles[Glyph.VAL.value] = canonical[Glyph.RA.value]
     angles[Glyph.NUL.value] = canonical[Glyph.ZHIR.value]
     angles[Glyph.AL.value] = 0.0
@@ -91,8 +97,8 @@ ANGLE_MAP: Mapping[str, float] = MappingProxyType(_build_angle_map())
 __all__ = (
     "GLYPHS_CANONICAL",
     "GLYPHS_CANONICAL_SET",
-    "ESTABILIZADORES",
-    "DISRUPTIVOS",
+    "STABILIZERS",
+    "DISRUPTORS",
     "GLYPH_GROUPS",
     "ANGLE_MAP",
 )

tnfr/config/constants.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

tnfr/config/defaults.py

@@ -0,0 +1,54 @@
+"""Consolidated TNFR configuration defaults.
+
+This module provides all default configuration values organized by subsystem,
+following TNFR structural coherence principles.
+"""
+
+from __future__ import annotations
+
+from types import MappingProxyType
+from typing import Mapping
+
+from ..types import TNFRConfigValue
+from .defaults_core import CORE_DEFAULTS, REMESH_DEFAULTS
+from .defaults_init import INIT_DEFAULTS
+from .defaults_metric import (
+    COHERENCE,
+    DIAGNOSIS,
+    GRAMMAR_CANON,
+    METRIC_DEFAULTS,
+    METRICS,
+    SIGMA,
+    TRACE,
+)
+
+# Exported sections organized by subsystem
+DEFAULT_SECTIONS: Mapping[str, Mapping[str, TNFRConfigValue]] = MappingProxyType(
+    {
+        "core": CORE_DEFAULTS,
+        "init": INIT_DEFAULTS,
+        "remesh": REMESH_DEFAULTS,
+        "metric": METRIC_DEFAULTS,
+    }
+)
+
+# Combined defaults with priority: CORE < INIT < REMESH < METRIC
+# METRIC_DEFAULTS has highest priority to match previous ChainMap behavior
+DEFAULTS: Mapping[str, TNFRConfigValue] = MappingProxyType(
+    CORE_DEFAULTS | INIT_DEFAULTS | REMESH_DEFAULTS | METRIC_DEFAULTS
+)
+
+__all__ = (
+    "DEFAULTS",
+    "DEFAULT_SECTIONS",
+    "CORE_DEFAULTS",
+    "INIT_DEFAULTS",
+    "REMESH_DEFAULTS",
+    "METRIC_DEFAULTS",
+    "SIGMA",
+    "TRACE",
+    "METRICS",
+    "GRAMMAR_CANON",
+    "COHERENCE",
+    "DIAGNOSIS",
+)

tnfr/{constants/core.py → config/defaults_core.py}

@@ -2,10 +2,11 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass, asdict, field
-from typing import Any, Mapping
+from dataclasses import asdict, field
 from types import MappingProxyType
+from typing import Any, Mapping
 
+from ..compat.dataclass import dataclass
 
 SELECTOR_THRESHOLD_DEFAULTS: Mapping[str, float] = MappingProxyType(
     {
@@ -33,8 +34,10 @@ class CoreDefaults:
     EPI_MIN: float = -1.0
     EPI_MAX: float = 1.0
     VF_MIN: float = 0.0
-    VF_MAX: float = 1.0
+    VF_MAX: float = 10.0
     THETA_WRAP: bool = True
+    CLIP_MODE: str = "hard"
+    CLIP_SOFT_K: float = 3.0
     DNFR_WEIGHTS: dict[str, float] = field(
         default_factory=lambda: {
             "phase": 0.34,
@@ -72,6 +75,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,
@@ -79,12 +83,27 @@ class CoreDefaults:
             "IL_dnfr_factor": 0.7,
             "OZ_dnfr_factor": 1.3,
             "UM_theta_push": 0.25,
+            "UM_vf_sync": 0.10,
+            "UM_dnfr_reduction": 0.15,
             "RA_epi_diff": 0.15,
+            "RA_vf_amplification": 0.05,
+            "RA_phase_coupling": 0.10,  # Canonical phase alignment strengthening
             "SHA_vf_factor": 0.85,
-            "VAL_scale": 1.15,
+            # Conservative scaling (1.05) prevents EPI overflow near boundaries
+            # while maintaining meaningful expansion capacity. Critical threshold:
+            # EPI × 1.05 = 1.0 when EPI ≈ 0.952 (vs previous threshold ≈ 0.870).
+            # This preserves structural identity at boundary (EPI_MAX as identity frontier).
+            "VAL_scale": 1.05,
             "NUL_scale": 0.85,
+            # NUL canonical ΔNFR densification factor: implements structural pressure
+            # concentration due to volume reduction. When V' = V × 0.85, density increases
+            # by ~1.176× geometrically. Canonical value 1.35 accounts for nonlinear
+            # structural effects at smaller scales, per TNFR theory.
+            "NUL_densification_factor": 1.35,
             "THOL_accel": 0.10,
-            "ZHIR_theta_shift": 1.57079632679,
+            # ZHIR now uses canonical transformation by default (θ → θ' based on ΔNFR)
+            # To use fixed shift, explicitly set ZHIR_theta_shift in graph
+            "ZHIR_theta_shift_factor": 0.3,  # Canonical transformation magnitude
             "NAV_jitter": 0.05,
             "NAV_eta": 0.5,
             "REMESH_alpha": 0.5,
@@ -121,6 +140,40 @@ class CoreDefaults:
     VALIDATORS_STRICT: bool = False
     PROGRAM_TRACE_MAXLEN: int = 50
     HISTORY_MAXLEN: int = 0
+    NODAL_EQUATION_CLIP_AWARE: bool = True
+    NODAL_EQUATION_TOLERANCE: float = 1e-9
+    # THOL (Self-organization) vibrational metabolism parameters
+    THOL_METABOLIC_ENABLED: bool = True
+    THOL_METABOLIC_GRADIENT_WEIGHT: float = 0.15
+    THOL_METABOLIC_COMPLEXITY_WEIGHT: float = 0.10
+    THOL_BIFURCATION_THRESHOLD: float = 0.1
+
+    # THOL network propagation and cascade parameters
+    THOL_PROPAGATION_ENABLED: bool = True
+    THOL_MIN_COUPLING_FOR_PROPAGATION: float = 0.5
+    THOL_PROPAGATION_ATTENUATION: float = 0.7
+    THOL_CASCADE_MIN_NODES: int = 3
+
+    # THOL precondition thresholds
+    THOL_MIN_EPI: float = 0.2  # Minimum EPI for bifurcation
+    THOL_MIN_VF: float = 0.1  # Minimum structural frequency for reorganization
+    THOL_MIN_DEGREE: int = 1  # Minimum network connectivity
+    THOL_MIN_HISTORY_LENGTH: int = 3  # Minimum EPI history for acceleration computation
+    THOL_ALLOW_ISOLATED: bool = False  # Require network context by default
+    THOL_MIN_COLLECTIVE_COHERENCE: float = 0.3  # Minimum collective coherence for sub-EPI ensemble
+
+    # VAL (Expansion) precondition thresholds
+    VAL_MAX_VF: float = 10.0  # Maximum structural frequency threshold
+    VAL_MIN_DNFR: float = 1e-6  # Minimum positive ΔNFR for coherent expansion (very low to minimize breaking changes)
+    VAL_MIN_EPI: float = 0.2  # Minimum EPI for coherent expansion base
+    VAL_CHECK_NETWORK_CAPACITY: bool = False  # Optional network capacity validation
+    VAL_MAX_NETWORK_SIZE: int = 1000  # Maximum network size if capacity checking enabled
+
+    # VAL (Expansion) metric thresholds (Issue #2724)
+    VAL_BIFURCATION_THRESHOLD: float = 0.3  # Threshold for |∂²EPI/∂t²| bifurcation detection
+    VAL_MIN_COHERENCE: float = 0.5  # Minimum local coherence for healthy expansion
+    VAL_FRACTAL_RATIO_MIN: float = 0.5  # Minimum vf_growth/epi_growth ratio for fractality
+    VAL_FRACTAL_RATIO_MAX: float = 2.0  # Maximum vf_growth/epi_growth ratio for fractality
 
 
 @dataclass(frozen=True, slots=True)
@@ -134,7 +187,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