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

@@ -0,0 +1,104 @@
+"""Canonical glyph constants tied to configuration presets."""
+
+from __future__ import annotations
+
+import math
+from types import MappingProxyType
+from typing import Mapping
+
+from ..types import Glyph
+
+# -------------------------
+# Canonical order and functional classifications
+# -------------------------
+
+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
+)
+
+GLYPHS_CANONICAL_SET: frozenset[str] = frozenset(GLYPHS_CANONICAL)
+
+STABILIZERS: tuple[str, ...] = (
+    Glyph.IL.value,
+    Glyph.RA.value,
+    Glyph.UM.value,
+    Glyph.SHA.value,
+)
+
+DISRUPTORS: tuple[str, ...] = (
+    Glyph.OZ.value,
+    Glyph.ZHIR.value,
+    Glyph.NAV.value,
+    Glyph.THOL.value,
+)
+
+# 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(
+    {
+        "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),
+        "PP_num": (Glyph.SHA.value,),
+        "PP_den": (Glyph.REMESH.value,),
+    }
+)
+
+# -------------------------
+# Glyph angle map
+# -------------------------
+
+# 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]:
+    """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)
+
+    # Orientation rules
+    for idx, g in enumerate(STABILIZERS):
+        angles[g] = idx * math.pi / 4
+    for idx, g in enumerate(DISRUPTORS):
+        angles[g] = math.pi + idx * math.pi / 4
+
+    # Manual exceptions
+    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",
+    "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",
+)