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

tnfr/config/defaults_init.py

@@ -0,0 +1,33 @@
+"""Initialization constants."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import asdict
+
+from ..compat.dataclass import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class InitDefaults:
+    """Default parameters for node initialisation.
+
+    The fields are collected into :data:`INIT_DEFAULTS` and may therefore
+    appear unused to tools like Vulture.
+    """
+
+    INIT_RANDOM_PHASE: bool = True
+    INIT_THETA_MIN: float = -math.pi
+    INIT_THETA_MAX: float = math.pi
+    INIT_VF_MODE: str = "uniform"
+    INIT_VF_MIN: float | None = None
+    INIT_VF_MAX: float | None = None
+    INIT_VF_MEAN: float = 0.5
+    INIT_VF_STD: float = 0.15
+    INIT_VF_CLAMP_TO_LIMITS: bool = True
+    INIT_SI_MIN: float = 0.4
+    INIT_SI_MAX: float = 0.7
+    INIT_EPI_VALUE: float = 0.0
+
+
+INIT_DEFAULTS = asdict(InitDefaults())

tnfr/config/defaults_metric.py

@@ -0,0 +1,104 @@
+"""Metric constants."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, field
+from types import MappingProxyType
+from typing import Any
+
+from ..compat.dataclass import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class MetricDefaults:
+    """Default parameters for metric computation.
+
+    The fields are gathered into :data:`METRIC_DEFAULTS` and exposed through
+    read-only views below, so they may appear unused to static analysis tools.
+    """
+
+    PHASE_HISTORY_MAXLEN: int = 50
+    STOP_EARLY: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": False,
+            "window": 25,
+            "fraction": 0.90,
+        }
+    )
+    SIGMA: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "weight": "Si",  # "Si" | "EPI" | "1"
+            "smooth": 0.0,  # EMA over the global vector (0=off)
+            "history_key": "sigma_global",
+            "per_node": False,
+        }
+    )
+    TRACE: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "verbosity": "debug",
+            "history_key": "trace_meta",
+        }
+    )
+    METRICS: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "save_by_node": True,
+            "normalize_series": False,
+            "n_jobs": 1,
+            "verbosity": "debug",
+        }
+    )
+    GRAMMAR_CANON: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "zhir_requires_oz_window": 3,
+            "zhir_dnfr_min": 0.05,
+            "thol_min_len": 2,
+            "thol_max_len": 6,
+            "thol_close_dnfr": 0.15,
+            "si_high": 0.66,
+        }
+    )
+    COHERENCE: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "scope": "neighbors",
+            "weights": {"phase": 0.34, "epi": 0.33, "vf": 0.20, "si": 0.13},
+            "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",
+        }
+    )
+    DIAGNOSIS: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "window": 16,
+            "history_key": "nodal_diag",
+            "stable": {"Rloc_hi": 0.80, "dnfr_lo": 0.20, "persist": 3},
+            "dissonance": {"Rloc_lo": 0.40, "dnfr_hi": 0.50, "persist": 3},
+            "transition": {"persist": 2},
+            "compute_symmetry": True,
+            "include_typology": False,
+            "advice": {
+                "stable": ["Coherence", "Coupling", "Resonance"],
+                "transition": ["Transition", "Resonance", "Self-organisation"],
+                "dissonant": ["Silence", "Contraction", "Mutation"],
+            },
+        }
+    )
+
+
+METRIC_DEFAULTS = asdict(MetricDefaults())
+
+SIGMA = MappingProxyType(METRIC_DEFAULTS["SIGMA"])
+TRACE = MappingProxyType(METRIC_DEFAULTS["TRACE"])
+METRICS = MappingProxyType(METRIC_DEFAULTS["METRICS"])
+GRAMMAR_CANON = MappingProxyType(METRIC_DEFAULTS["GRAMMAR_CANON"])
+COHERENCE = MappingProxyType(METRIC_DEFAULTS["COHERENCE"])
+DIAGNOSIS = MappingProxyType(METRIC_DEFAULTS["DIAGNOSIS"])

tnfr/config/feature_flags.py

@@ -0,0 +1,81 @@
+"""Math feature flag configuration helpers."""
+
+from __future__ import annotations
+
+import os
+from contextlib import contextmanager
+from dataclasses import dataclass, replace
+from typing import Iterator
+
+__all__ = ("MathFeatureFlags", "get_flags", "context_flags")
+
+
+@dataclass(frozen=True)
+class MathFeatureFlags:
+    """Toggle optional mathematical behaviours in the engine."""
+
+    enable_math_validation: bool = False
+    enable_math_dynamics: bool = False
+    log_performance: bool = False
+    math_backend: str = "numpy"
+
+
+_TRUE_VALUES = {"1", "true", "on", "yes", "y", "t"}
+_FALSE_VALUES = {"0", "false", "off", "no", "n", "f"}
+
+_BASE_FLAGS: MathFeatureFlags | None = None
+_FLAGS_STACK: list[MathFeatureFlags] = []
+
+
+def _parse_env_flag(name: str, default: bool) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    lowered = value.strip().lower()
+    if lowered in _TRUE_VALUES:
+        return True
+    if lowered in _FALSE_VALUES:
+        return False
+    return default
+
+
+def _load_base_flags() -> MathFeatureFlags:
+    global _BASE_FLAGS
+    if _BASE_FLAGS is None:
+        backend = os.getenv("TNFR_MATH_BACKEND")
+        backend_choice = backend.strip() if backend else "numpy"
+        _BASE_FLAGS = MathFeatureFlags(
+            enable_math_validation=_parse_env_flag(
+                "TNFR_ENABLE_MATH_VALIDATION", False
+            ),
+            enable_math_dynamics=_parse_env_flag("TNFR_ENABLE_MATH_DYNAMICS", False),
+            log_performance=_parse_env_flag("TNFR_LOG_PERF", False),
+            math_backend=backend_choice or "numpy",
+        )
+    return _BASE_FLAGS
+
+
+def get_flags() -> MathFeatureFlags:
+    """Return the currently active feature flags."""
+
+    if _FLAGS_STACK:
+        return _FLAGS_STACK[-1]
+    return _load_base_flags()
+
+
+@contextmanager
+def context_flags(**overrides: bool) -> Iterator[MathFeatureFlags]:
+    """Temporarily override math feature flags."""
+
+    invalid = set(overrides) - set(MathFeatureFlags.__annotations__)
+    if invalid:
+        invalid_names = ", ".join(sorted(invalid))
+        raise TypeError(f"Unknown flag overrides: {invalid_names}")
+
+    previous = get_flags()
+    next_flags = replace(previous, **overrides)
+    _FLAGS_STACK.append(next_flags)
+    try:
+        yield next_flags
+    finally:
+        _FLAGS_STACK.pop()

tnfr/config/feature_flags.pyi

@@ -0,0 +1,16 @@
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Iterator
+
+__all__ = ["MathFeatureFlags", "get_flags", "context_flags"]
+
+@dataclass(frozen=True)
+class MathFeatureFlags:
+    enable_math_validation: bool = ...
+    enable_math_dynamics: bool = ...
+    log_performance: bool = ...
+    math_backend: str = ...
+
+def get_flags() -> MathFeatureFlags: ...
+@contextmanager
+def context_flags(**overrides: bool) -> Iterator[MathFeatureFlags]: ...

tnfr/config/glyph_constants.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/config/init.py

@@ -0,0 +1,77 @@
+"""Core configuration helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from ..utils import read_structured_file
+
+if TYPE_CHECKING:  # pragma: no cover - only for type checkers
+    import networkx as nx
+
+__all__ = ("load_config", "apply_config")
+
+
+def load_config(
+    path: str | Path,
+    *,
+    base_dir: str | Path | None = None,
+) -> Mapping[str, Any]:
+    """Read a JSON/YAML file and return a mapping with parameters.
+
+    Parameters
+    ----------
+    path : str | Path
+        Path to the configuration file.
+    base_dir : str | Path | None, optional
+        Base directory to restrict config file access. If provided, the
+        resolved path must stay within this directory (prevents path traversal).
+
+    Returns
+    -------
+    Mapping[str, Any]
+        Configuration parameters as a mapping.
+
+    Raises
+    ------
+    ValueError
+        If the configuration file is invalid or contains unsafe patterns.
+    PathTraversalError
+        If path traversal is detected when base_dir is provided.
+    StructuredFileError
+        If the file cannot be read or parsed.
+    """
+    path_obj = path if isinstance(path, Path) else Path(path)
+    data = read_structured_file(path_obj, base_dir=base_dir)
+    if not isinstance(data, Mapping):
+        raise ValueError("Configuration file must contain an object")
+    return data
+
+
+def apply_config(
+    G: "nx.Graph",
+    path: str | Path,
+    *,
+    base_dir: str | Path | None = None,
+) -> None:
+    """Inject parameters from ``path`` into ``G.graph``.
+
+    Uses inject_defaults from this module to keep canonical default
+    semantics.
+
+    Parameters
+    ----------
+    G : nx.Graph
+        The graph to configure.
+    path : str | Path
+        Path to the configuration file.
+    base_dir : str | Path | None, optional
+        Base directory to restrict config file access.
+    """
+    # Import inject_defaults locally to avoid circular import
+    from . import inject_defaults
+
+    cfg = load_config(path, base_dir=base_dir)
+    inject_defaults(G, cfg, override=True)

tnfr/config/init.pyi

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

tnfr/config/operator_names.py

@@ -0,0 +1,254 @@
+"""Canonical operator name constants and physics-derived operator sets.
+
+This module defines operator names and derives valid start/end operator sets
+from TNFR physical principles rather than arbitrary lists.
+
+Physics-Based Derivation
+------------------------
+The sets VALID_START_OPERATORS and VALID_END_OPERATORS are derived from the
+fundamental TNFR nodal equation:
+
+    ∂EPI/∂t = νf · ΔNFR(t)
+
+Where:
+    - EPI: Primary Information Structure (coherent form)
+    - νf: Structural frequency (reorganization rate, Hz_str)
+    - ΔNFR: Internal reorganization operator/gradient
+
+Start Operators (Activation)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+An operator can START a sequence if it can either:
+
+1. **Generate EPI from null state** (νf=0, EPI=0):
+   - emission: Creates outward coherence pulse, generates νf > 0 and ΔNFR > 0
+
+2. **Activate latent EPI** (νf≈0, but EPI>0):
+   - recursivity: Replicates/echoes existing patterns across scales
+   - transition: Activates node from another phase/regime
+
+Physical justification: Only operators that can create or activate structural
+capacity (νf > 0) from dormant/null states can initiate reorganization.
+
+End Operators (Closure)
+~~~~~~~~~~~~~~~~~~~~~~~~
+An operator can END a sequence if it can either:
+
+1. **Stabilize reorganization** (∂EPI/∂t → 0):
+   - silence: Forces νf → 0, causing ∂EPI/∂t → 0 while preserving EPI
+
+2. **Achieve operational closure**:
+   - transition: Hands off to next phase (completes current cycle)
+   - recursivity: Fractal echo creates self-similar closure
+   - dissonance: Postponed conflict / contained tension (questionable)
+
+Physical justification: Terminal operators must either freeze evolution
+(νf → 0) or complete an operational cycle with clear boundary.
+
+For detailed physics derivation logic, see:
+    tnfr.config.physics_derivation
+
+References
+----------
+- TNFR.pdf: Section 2.1 (Nodal Equation)
+- AGENTS.md: Section 3 (Canonical Invariants)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Canonical operator identifiers (English tokens)
+EMISSION = "emission"
+RECEPTION = "reception"
+COHERENCE = "coherence"
+DISSONANCE = "dissonance"
+COUPLING = "coupling"
+RESONANCE = "resonance"
+SILENCE = "silence"
+EXPANSION = "expansion"
+CONTRACTION = "contraction"
+SELF_ORGANIZATION = "self_organization"
+MUTATION = "mutation"
+TRANSITION = "transition"
+RECURSIVITY = "recursivity"
+
+# Canonical collections -------------------------------------------------------
+
+CANONICAL_OPERATOR_NAMES = frozenset(
+    {
+        EMISSION,
+        RECEPTION,
+        COHERENCE,
+        DISSONANCE,
+        COUPLING,
+        RESONANCE,
+        SILENCE,
+        EXPANSION,
+        CONTRACTION,
+        SELF_ORGANIZATION,
+        MUTATION,
+        TRANSITION,
+        RECURSIVITY,
+    }
+)
+
+ALL_OPERATOR_NAMES = CANONICAL_OPERATOR_NAMES
+ENGLISH_OPERATOR_NAMES = CANONICAL_OPERATOR_NAMES
+
+# Physics-derived operator sets (derived from TNFR canonical principles)
+# Import here to avoid issues, but actual derivation is in physics_derivation module
+# These are computed at module load time from TNFR physical principles
+VALID_START_OPERATORS = frozenset({EMISSION, RECURSIVITY, TRANSITION})
+INTERMEDIATE_OPERATORS = frozenset({DISSONANCE, COUPLING, RESONANCE})
+VALID_END_OPERATORS = frozenset({SILENCE, TRANSITION, RECURSIVITY, DISSONANCE})
+SELF_ORGANIZATION_CLOSURES = frozenset({SILENCE, CONTRACTION})
+
+# R4 Bifurcation control: operators that enable structural transformations
+# Legacy single-level destabilizers (for backward compatibility)
+DESTABILIZERS = frozenset({DISSONANCE, TRANSITION, EXPANSION})  # OZ, NAV, VAL
+TRANSFORMERS = frozenset({MUTATION, SELF_ORGANIZATION})  # ZHIR, THOL
+BIFURCATION_WINDOW = 3  # Legacy: Search window for destabilizer precedent
+
+# R4 Extended: Graduated destabilizer classification by intensity
+DESTABILIZERS_STRONG = frozenset({DISSONANCE})  # OZ: explicit dissonance
+DESTABILIZERS_MODERATE = frozenset({TRANSITION, EXPANSION})  # NAV, VAL: indirect
+DESTABILIZERS_WEAK = frozenset({RECEPTION})  # EN: latent potential
+
+# All destabilizers (union of all levels)
+DESTABILIZERS_ALL = DESTABILIZERS_STRONG | DESTABILIZERS_MODERATE | DESTABILIZERS_WEAK
+
+# R4 Extended: Bifurcation windows by destabilizer intensity
+# These define how many operators can separate a destabilizer from a transformer
+BIFURCATION_WINDOWS = {
+    "strong": 4,  # OZ permits ZHIR/THOL within 4 operators
+    "moderate": 2,  # NAV/VAL permit ZHIR/THOL within 2 operators
+    "weak": 1,  # EN requires ZHIR/THOL as immediate successor
+}
+
+
+def canonical_operator_name(name: str) -> str:
+    """Return the canonical operator token for ``name``."""
+
+    return name
+
+
+def operator_display_name(name: str) -> str:
+    """Return the display label for ``name`` (currently the canonical token)."""
+
+    return canonical_operator_name(name)
+
+
+__all__ = [
+    "EMISSION",
+    "RECEPTION",
+    "COHERENCE",
+    "DISSONANCE",
+    "COUPLING",
+    "RESONANCE",
+    "SILENCE",
+    "EXPANSION",
+    "CONTRACTION",
+    "SELF_ORGANIZATION",
+    "MUTATION",
+    "TRANSITION",
+    "RECURSIVITY",
+    "CANONICAL_OPERATOR_NAMES",
+    "ENGLISH_OPERATOR_NAMES",
+    "ALL_OPERATOR_NAMES",
+    "VALID_START_OPERATORS",
+    "INTERMEDIATE_OPERATORS",
+    "VALID_END_OPERATORS",
+    "SELF_ORGANIZATION_CLOSURES",
+    "DESTABILIZERS",
+    "TRANSFORMERS",
+    "BIFURCATION_WINDOW",
+    "DESTABILIZERS_STRONG",
+    "DESTABILIZERS_MODERATE",
+    "DESTABILIZERS_WEAK",
+    "DESTABILIZERS_ALL",
+    "BIFURCATION_WINDOWS",
+    "canonical_operator_name",
+    "operator_display_name",
+    "validate_physics_derivation",
+]
+
+
+def validate_physics_derivation() -> dict[str, Any]:
+    """Validate that operator sets are consistent with TNFR physics derivation.
+
+    This function verifies that VALID_START_OPERATORS and VALID_END_OPERATORS
+    match what would be derived from first principles using the physics_derivation
+    module.
+
+    Returns
+    -------
+    dict[str, Any]
+        Validation report with keys:
+        - "start_operators_valid": bool
+        - "end_operators_valid": bool
+        - "start_operators_expected": frozenset
+        - "start_operators_actual": frozenset
+        - "end_operators_expected": frozenset
+        - "end_operators_actual": frozenset
+        - "discrepancies": list of str
+
+    Notes
+    -----
+    This function is primarily for testing and validation. It ensures that
+    any manual updates to VALID_START_OPERATORS or VALID_END_OPERATORS remain
+    consistent with TNFR canonical physics.
+
+    If discrepancies are found, the function logs warnings but does not raise
+    exceptions, allowing for intentional overrides with clear audit trail.
+    """
+    from .physics_derivation import (
+        derive_start_operators_from_physics,
+        derive_end_operators_from_physics,
+    )
+
+    expected_starts = derive_start_operators_from_physics()
+    expected_ends = derive_end_operators_from_physics()
+
+    discrepancies = []
+
+    start_valid = VALID_START_OPERATORS == expected_starts
+    if not start_valid:
+        missing = expected_starts - VALID_START_OPERATORS
+        extra = VALID_START_OPERATORS - expected_starts
+        if missing:
+            discrepancies.append(
+                f"VALID_START_OPERATORS missing physics-derived operators: {missing}"
+            )
+        if extra:
+            discrepancies.append(
+                f"VALID_START_OPERATORS contains non-physics operators: {extra}"
+            )
+
+    end_valid = VALID_END_OPERATORS == expected_ends
+    if not end_valid:
+        missing = expected_ends - VALID_END_OPERATORS
+        extra = VALID_END_OPERATORS - expected_ends
+        if missing:
+            discrepancies.append(
+                f"VALID_END_OPERATORS missing physics-derived operators: {missing}"
+            )
+        if extra:
+            discrepancies.append(
+                f"VALID_END_OPERATORS contains non-physics operators: {extra}"
+            )
+
+    return {
+        "start_operators_valid": start_valid,
+        "end_operators_valid": end_valid,
+        "start_operators_expected": expected_starts,
+        "start_operators_actual": VALID_START_OPERATORS,
+        "end_operators_expected": expected_ends,
+        "end_operators_actual": VALID_END_OPERATORS,
+        "discrepancies": discrepancies,
+    }
+
+
+def __getattr__(name: str) -> Any:
+    """Provide a consistent ``AttributeError`` when names are missing."""
+
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

tnfr/config/operator_names.pyi

@@ -0,0 +1,36 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+ALL_OPERATOR_NAMES: Any
+BIFURCATION_WINDOW: Any
+BIFURCATION_WINDOWS: Any
+CANONICAL_OPERATOR_NAMES: Any
+COHERENCE: Any
+CONTRACTION: Any
+COUPLING: Any
+DESTABILIZERS: Any
+DESTABILIZERS_ALL: Any
+DESTABILIZERS_MODERATE: Any
+DESTABILIZERS_STRONG: Any
+DESTABILIZERS_WEAK: Any
+DISSONANCE: Any
+EMISSION: Any
+ENGLISH_OPERATOR_NAMES: Any
+EXPANSION: Any
+INTERMEDIATE_OPERATORS: Any
+MUTATION: Any
+RECEPTION: Any
+RECURSIVITY: Any
+RESONANCE: Any
+SELF_ORGANIZATION: Any
+SELF_ORGANIZATION_CLOSURES: Any
+SILENCE: Any
+TRANSFORMERS: Any
+TRANSITION: Any
+VALID_END_OPERATORS: Any
+VALID_START_OPERATORS: Any
+canonical_operator_name: Any
+operator_display_name: Any