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

tnfr/security/validation.py

@@ -0,0 +1,290 @@
+"""Input validation utilities for TNFR structural data.
+
+This module provides validation functions for TNFR-specific data types
+to ensure structural coherence when persisting or querying data.
+
+TNFR Structural Invariants
+---------------------------
+These validators enforce TNFR canonical invariants:
+1. Structural frequency (νf) in Hz_str units
+2. Phase (φ) in valid range [0, 2π]
+3. Coherence C(t) as non-negative value
+4. Sense index Si validation
+
+Example
+-------
+>>> validate_structural_frequency(0.5)  # Valid
+0.5
+>>> validate_phase_value(3.14)  # Valid
+3.14
+>>> validate_structural_frequency(-1.0)  # doctest: +SKIP
+Traceback (most recent call last):
+    ...
+ValueError: Structural frequency must be non-negative
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+
+def validate_structural_frequency(nu_f: float) -> float:
+    """Validate structural frequency (νf) value.
+
+    Structural frequency must be non-negative and expressed in Hz_str
+    (structural hertz), representing the nodal reorganization rate.
+
+    Parameters
+    ----------
+    nu_f : float
+        Structural frequency value to validate
+
+    Returns
+    -------
+    float
+        The validated frequency value
+
+    Raises
+    ------
+    ValueError
+        If the frequency is negative, NaN, or infinite
+
+    Example
+    -------
+    >>> validate_structural_frequency(0.5)
+    0.5
+    >>> validate_structural_frequency(0.0)  # Silence operator
+    0.0
+    >>> validate_structural_frequency(-0.1)  # doctest: +SKIP
+    Traceback (most recent call last):
+        ...
+    ValueError: Structural frequency must be non-negative, got -0.1
+    """
+    if not isinstance(nu_f, (int, float)):
+        raise ValueError(
+            f"Structural frequency must be numeric, got {type(nu_f).__name__}"
+        )
+
+    if math.isnan(nu_f):
+        raise ValueError("Structural frequency cannot be NaN")
+
+    if math.isinf(nu_f):
+        raise ValueError("Structural frequency cannot be infinite")
+
+    if nu_f < 0:
+        raise ValueError(f"Structural frequency must be non-negative, got {nu_f}")
+
+    return float(nu_f)
+
+
+def validate_phase_value(phase: float, *, allow_wrap: bool = True) -> float:
+    """Validate phase (φ) value.
+
+    Phase represents synchronization in the network and should be in the
+    range [0, 2π]. If allow_wrap is True, values outside this range are
+    automatically wrapped.
+
+    Parameters
+    ----------
+    phase : float
+        Phase value to validate
+    allow_wrap : bool, optional
+        If True, wrap phase to [0, 2π] range (default: True)
+
+    Returns
+    -------
+    float
+        The validated (and possibly wrapped) phase value
+
+    Raises
+    ------
+    ValueError
+        If phase is NaN, infinite, or outside valid range (when allow_wrap=False)
+
+    Example
+    -------
+    >>> validate_phase_value(1.57)  # π/2
+    1.57
+    >>> result = validate_phase_value(7.0)  # Wrapped to [0, 2π]
+    >>> 0.0 <= result <= 6.3
+    True
+    >>> validate_phase_value(7.0, allow_wrap=False)  # doctest: +SKIP
+    Traceback (most recent call last):
+        ...
+    ValueError: Phase must be in range [0, 2π], got 7.0
+    """
+    if not isinstance(phase, (int, float)):
+        raise ValueError(f"Phase must be numeric, got {type(phase).__name__}")
+
+    if math.isnan(phase):
+        raise ValueError("Phase cannot be NaN")
+
+    if math.isinf(phase):
+        raise ValueError("Phase cannot be infinite")
+
+    two_pi = 2 * math.pi
+
+    if allow_wrap:
+        # Wrap phase to [0, 2π] range
+        phase = phase % two_pi
+    else:
+        if not 0 <= phase <= two_pi:
+            raise ValueError(f"Phase must be in range [0, 2π], got {phase}")
+
+    return float(phase)
+
+
+def validate_coherence_value(coherence: float) -> float:
+    """Validate coherence C(t) value.
+
+    Coherence represents the total structural stability and must be
+    non-negative.
+
+    Parameters
+    ----------
+    coherence : float
+        Coherence value to validate
+
+    Returns
+    -------
+    float
+        The validated coherence value
+
+    Raises
+    ------
+    ValueError
+        If coherence is negative, NaN, or infinite
+
+    Example
+    -------
+    >>> validate_coherence_value(0.8)
+    0.8
+    >>> validate_coherence_value(0.0)  # Minimum coherence
+    0.0
+    >>> validate_coherence_value(-0.1)  # doctest: +SKIP
+    Traceback (most recent call last):
+        ...
+    ValueError: Coherence must be non-negative, got -0.1
+    """
+    if not isinstance(coherence, (int, float)):
+        raise ValueError(f"Coherence must be numeric, got {type(coherence).__name__}")
+
+    if math.isnan(coherence):
+        raise ValueError("Coherence cannot be NaN")
+
+    if math.isinf(coherence):
+        raise ValueError("Coherence cannot be infinite")
+
+    if coherence < 0:
+        raise ValueError(f"Coherence must be non-negative, got {coherence}")
+
+    return float(coherence)
+
+
+def validate_sense_index(si: float) -> float:
+    """Validate sense index (Si) value.
+
+    Sense index represents the capacity to generate stable reorganization.
+    Valid range is typically [0, 1] but can exceed 1 in high-coherence networks.
+
+    Parameters
+    ----------
+    si : float
+        Sense index value to validate
+
+    Returns
+    -------
+    float
+        The validated sense index value
+
+    Raises
+    ------
+    ValueError
+        If Si is negative, NaN, or infinite
+
+    Example
+    -------
+    >>> validate_sense_index(0.7)
+    0.7
+    >>> validate_sense_index(1.2)  # High coherence
+    1.2
+    >>> validate_sense_index(-0.1)  # doctest: +SKIP
+    Traceback (most recent call last):
+        ...
+    ValueError: Sense index must be non-negative, got -0.1
+    """
+    if not isinstance(si, (int, float)):
+        raise ValueError(f"Sense index must be numeric, got {type(si).__name__}")
+
+    if math.isnan(si):
+        raise ValueError("Sense index cannot be NaN")
+
+    if math.isinf(si):
+        raise ValueError("Sense index cannot be infinite")
+
+    if si < 0:
+        raise ValueError(f"Sense index must be non-negative, got {si}")
+
+    return float(si)
+
+
+def validate_nodal_input(data: dict[str, Any]) -> dict[str, Any]:
+    """Validate a complete nodal data structure.
+
+    This function validates all common NFR node attributes to ensure
+    structural coherence before database persistence.
+
+    Parameters
+    ----------
+    data : dict
+        Dictionary containing nodal attributes
+
+    Returns
+    -------
+    dict
+        The validated data dictionary
+
+    Raises
+    ------
+    ValueError
+        If any attribute fails validation
+
+    Example
+    -------
+    >>> data = {"nu_f": 0.5, "phase": 1.57, "delta_nfr": 0.1}
+    >>> validated = validate_nodal_input(data)
+    >>> validated["nu_f"]
+    0.5
+    """
+    validated = {}
+
+    if "nu_f" in data:
+        validated["nu_f"] = validate_structural_frequency(data["nu_f"])
+
+    if "phase" in data:
+        validated["phase"] = validate_phase_value(data["phase"])
+
+    if "coherence" in data:
+        validated["coherence"] = validate_coherence_value(data["coherence"])
+
+    if "si" in data or "sense_index" in data:
+        si_key = "si" if "si" in data else "sense_index"
+        validated[si_key] = validate_sense_index(data[si_key])
+
+    # Pass through other fields without validation
+    # (e.g., node_id, epi arrays, etc.)
+    for key, value in data.items():
+        if key not in validated:
+            validated[key] = value
+
+    return validated
+
+
+__all__ = (
+    "validate_coherence_value",
+    "validate_nodal_input",
+    "validate_phase_value",
+    "validate_sense_index",
+    "validate_structural_frequency",
+)

tnfr/selector.py

@@ -0,0 +1,247 @@
+"""Utilities to select structural operator symbols based on structural metrics.
+
+This module normalises thresholds, computes selection scores and applies
+hysteresis when assigning structural operator symbols (glyphs) to nodes.
+
+Each structural operator (Emission, Reception, Coherence, etc.) is represented
+by a glyph symbol (AL, EN, IL, etc.) that this module selects based on the
+node's current structural state.
+"""
+
+from __future__ import annotations
+
+import threading
+from operator import itemgetter
+from typing import TYPE_CHECKING, Any, Mapping, cast
+from weakref import WeakKeyDictionary
+
+if TYPE_CHECKING:  # pragma: no cover
+    import networkx as nx
+
+from .constants import DEFAULTS
+from .config.defaults_core import SELECTOR_THRESHOLD_DEFAULTS
+from .utils import clamp01
+from .metrics.common import compute_dnfr_accel_max
+from .types import SelectorNorms, SelectorThresholds, SelectorWeights
+from .utils import is_non_string_sequence
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .types import TNFRGraph
+
+HYSTERESIS_GLYPHS: set[str] = {"IL", "OZ", "ZHIR", "THOL", "NAV", "RA"}
+
+__all__ = (
+    "_selector_thresholds",
+    "_selector_norms",
+    "_calc_selector_score",
+    "_apply_selector_hysteresis",
+    "_selector_parallel_jobs",
+)
+
+_SelectorThresholdItems = tuple[tuple[str, float], ...]
+_SelectorThresholdCacheEntry = tuple[
+    _SelectorThresholdItems,
+    SelectorThresholds,
+]
+_SELECTOR_THRESHOLD_CACHE: WeakKeyDictionary[
+    "nx.Graph",
+    _SelectorThresholdCacheEntry,
+] = WeakKeyDictionary()
+_SELECTOR_THRESHOLD_CACHE_LOCK = threading.Lock()
+
+
+def _sorted_items(mapping: Mapping[str, float]) -> _SelectorThresholdItems:
+    """Return mapping items sorted by key.
+
+    Parameters
+    ----------
+    mapping : Mapping[str, float]
+        Mapping whose items will be sorted.
+
+    Returns
+    -------
+    tuple[tuple[str, float], ...]
+        Key-sorted items providing a hashable representation for memoisation.
+    """
+    return tuple(sorted(mapping.items()))
+
+
+def _compute_selector_thresholds(
+    thr_sel_items: _SelectorThresholdItems,
+) -> SelectorThresholds:
+    """Construct selector thresholds for a graph.
+
+    Parameters
+    ----------
+    thr_sel_items : tuple[tuple[str, float], ...]
+        Selector threshold items as ``(key, value)`` pairs.
+
+    Returns
+    -------
+    dict[str, float]
+        Normalised thresholds for selector metrics.
+    """
+    thr_sel = dict(thr_sel_items)
+
+    out: dict[str, float] = {}
+    for key, default in SELECTOR_THRESHOLD_DEFAULTS.items():
+        val = thr_sel.get(key, default)
+        out[key] = clamp01(float(val))
+    return cast(SelectorThresholds, out)
+
+
+def _selector_thresholds(G: "nx.Graph") -> SelectorThresholds:
+    """Return normalised thresholds for Si, ΔNFR and acceleration.
+
+    Parameters
+    ----------
+    G : nx.Graph
+        Graph whose configuration stores selector thresholds.
+
+    Returns
+    -------
+    dict[str, float]
+        Dictionary with clamped hi/lo thresholds, memoised per graph.
+    """
+    sel_defaults = DEFAULTS.get("SELECTOR_THRESHOLDS", {})
+    thr_sel = {**sel_defaults, **G.graph.get("SELECTOR_THRESHOLDS", {})}
+    thr_sel_items = _sorted_items(thr_sel)
+
+    with _SELECTOR_THRESHOLD_CACHE_LOCK:
+        cached = _SELECTOR_THRESHOLD_CACHE.get(G)
+        if cached is not None and cached[0] == thr_sel_items:
+            return cached[1]
+
+    thresholds = _compute_selector_thresholds(thr_sel_items)
+
+    with _SELECTOR_THRESHOLD_CACHE_LOCK:
+        cached = _SELECTOR_THRESHOLD_CACHE.get(G)
+        if cached is not None and cached[0] == thr_sel_items:
+            return cached[1]
+        _SELECTOR_THRESHOLD_CACHE[G] = (thr_sel_items, thresholds)
+    return thresholds
+
+
+def _selector_norms(G: "nx.Graph") -> SelectorNorms:
+    """Compute and cache selector norms for ΔNFR and acceleration.
+
+    Parameters
+    ----------
+    G : nx.Graph
+        Graph for which to compute maxima. Results are stored in ``G.graph``
+        under ``"_sel_norms"``.
+
+    Returns
+    -------
+    dict
+        Mapping with normalisation maxima for ``dnfr`` and ``accel``.
+    """
+    norms = compute_dnfr_accel_max(G)
+    G.graph["_sel_norms"] = norms
+    return norms
+
+
+def _calc_selector_score(
+    Si: float, dnfr: float, accel: float, weights: SelectorWeights
+) -> float:
+    """Compute weighted selector score.
+
+    Parameters
+    ----------
+    Si : float
+        Normalised sense index.
+    dnfr : float
+        Normalised absolute ΔNFR value.
+    accel : float
+        Normalised acceleration (|d²EPI/dt²|).
+    weights : dict[str, float]
+        Normalised weights for ``"w_si"``, ``"w_dnfr"`` and ``"w_accel"``.
+
+    Returns
+    -------
+    float
+        Final weighted score.
+    """
+    return (
+        weights["w_si"] * Si
+        + weights["w_dnfr"] * (1.0 - dnfr)
+        + weights["w_accel"] * (1.0 - accel)
+    )
+
+
+def _apply_selector_hysteresis(
+    nd: dict[str, Any],
+    Si: float,
+    dnfr: float,
+    accel: float,
+    thr: dict[str, float],
+    margin: float | None,
+) -> str | None:
+    """Apply hysteresis when values are near thresholds.
+
+    Parameters
+    ----------
+    nd : dict[str, Any]
+        Node attribute dictionary containing glyph history.
+    Si : float
+        Normalised sense index.
+    dnfr : float
+        Normalised absolute ΔNFR value.
+    accel : float
+        Normalised acceleration.
+    thr : dict[str, float]
+        Thresholds returned by :func:`_selector_thresholds`.
+    margin : float or None
+        When positive, distance from thresholds below which the previous
+        glyph is reused. Falsy margins disable hysteresis entirely, letting
+        selectors bypass the reuse logic.
+
+    Returns
+    -------
+    str or None
+        Previous glyph if hysteresis applies, otherwise ``None``.
+    """
+    # Batch extraction reduces dictionary lookups inside loops.
+    if not margin:
+        return None
+
+    si_hi, si_lo, dnfr_hi, dnfr_lo, accel_hi, accel_lo = itemgetter(
+        "si_hi", "si_lo", "dnfr_hi", "dnfr_lo", "accel_hi", "accel_lo"
+    )(thr)
+
+    d_si = min(abs(Si - si_hi), abs(Si - si_lo))
+    d_dn = min(abs(dnfr - dnfr_hi), abs(dnfr - dnfr_lo))
+    d_ac = min(abs(accel - accel_hi), abs(accel - accel_lo))
+    certeza = min(d_si, d_dn, d_ac)
+    if certeza < margin:
+        hist = nd.get("glyph_history")
+        if not is_non_string_sequence(hist) or not hist:
+            return None
+        prev = hist[-1]
+        if isinstance(prev, str) and prev in HYSTERESIS_GLYPHS:
+            return prev
+    return None
+
+
+def _selector_parallel_jobs(G: "TNFRGraph") -> int | None:
+    """Return worker count for selector helpers when parallelism is enabled.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph containing selector configuration.
+
+    Returns
+    -------
+    int | None
+        Number of parallel jobs to use, or None if parallelism is disabled
+        or invalid configuration is provided.
+    """
+    raw_jobs = G.graph.get("GLYPH_SELECTOR_N_JOBS")
+    try:
+        n_jobs = None if raw_jobs is None else int(raw_jobs)
+    except (TypeError, ValueError):
+        return None
+    if n_jobs is None or n_jobs <= 1:
+        return None
+    return n_jobs

tnfr/selector.pyi

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+def _apply_selector_hysteresis(
+    nd: dict[str, Any],
+    Si: float,
+    dnfr: float,
+    accel: float,
+    thr: Mapping[str, float],
+    margin: float | None,
+) -> str | None: ...
+
+_calc_selector_score: Any
+_selector_norms: Any
+_selector_thresholds: Any