tnfr 4.5.2__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

@@ -1,39 +1,47 @@
-"""Utilities to select glyphs based on structural metrics.
+"""Utilities to select structural operator symbols based on structural metrics.
 
 This module normalises thresholds, computes selection scores and applies
-hysteresis when assigning glyphs to nodes.
+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 Any, Mapping, TYPE_CHECKING
+from typing import TYPE_CHECKING, Any, Mapping, cast
 from weakref import WeakKeyDictionary
 
 if TYPE_CHECKING:  # pragma: no cover
-    import networkx as nx  # type: ignore[import-untyped]
+    import networkx as nx
 
 from .constants import DEFAULTS
-from .constants.core import SELECTOR_THRESHOLD_DEFAULTS
-from .helpers.numeric import clamp01
+from .config.defaults_core import SELECTOR_THRESHOLD_DEFAULTS
+from .utils import clamp01
 from .metrics.common import compute_dnfr_accel_max
-from .collections_utils import is_non_string_sequence
+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",
-    "_norms_para_selector",
+    "_selector_norms",
     "_calc_selector_score",
     "_apply_selector_hysteresis",
+    "_selector_parallel_jobs",
 )
 
-
+_SelectorThresholdItems = tuple[tuple[str, float], ...]
 _SelectorThresholdCacheEntry = tuple[
-    tuple[tuple[str, float], ...],
-    dict[str, float],
+    _SelectorThresholdItems,
+    SelectorThresholds,
 ]
 _SELECTOR_THRESHOLD_CACHE: WeakKeyDictionary[
     "nx.Graph",
@@ -42,7 +50,7 @@ _SELECTOR_THRESHOLD_CACHE: WeakKeyDictionary[
 _SELECTOR_THRESHOLD_CACHE_LOCK = threading.Lock()
 
 
-def _sorted_items(mapping: Mapping[str, float]) -> tuple[tuple[str, float], ...]:
+def _sorted_items(mapping: Mapping[str, float]) -> _SelectorThresholdItems:
     """Return mapping items sorted by key.
 
     Parameters
@@ -59,8 +67,8 @@ def _sorted_items(mapping: Mapping[str, float]) -> tuple[tuple[str, float], ...]
 
 
 def _compute_selector_thresholds(
-    thr_sel_items: tuple[tuple[str, float], ...],
-) -> dict[str, float]:
+    thr_sel_items: _SelectorThresholdItems,
+) -> SelectorThresholds:
     """Construct selector thresholds for a graph.
 
     Parameters
@@ -79,10 +87,10 @@ def _compute_selector_thresholds(
     for key, default in SELECTOR_THRESHOLD_DEFAULTS.items():
         val = thr_sel.get(key, default)
         out[key] = clamp01(float(val))
-    return out
+    return cast(SelectorThresholds, out)
 
 
-def _selector_thresholds(G: "nx.Graph") -> dict[str, float]:
+def _selector_thresholds(G: "nx.Graph") -> SelectorThresholds:
     """Return normalised thresholds for Si, ΔNFR and acceleration.
 
     Parameters
@@ -114,8 +122,8 @@ def _selector_thresholds(G: "nx.Graph") -> dict[str, float]:
     return thresholds
 
 
-def _norms_para_selector(G: "nx.Graph") -> dict:
-    """Compute and cache norms for ΔNFR and acceleration.
+def _selector_norms(G: "nx.Graph") -> SelectorNorms:
+    """Compute and cache selector norms for ΔNFR and acceleration.
 
     Parameters
     ----------
@@ -134,7 +142,7 @@ def _norms_para_selector(G: "nx.Graph") -> dict:
 
 
 def _calc_selector_score(
-    Si: float, dnfr: float, accel: float, weights: dict[str, float]
+    Si: float, dnfr: float, accel: float, weights: SelectorWeights
 ) -> float:
     """Compute weighted selector score.
 
@@ -167,7 +175,7 @@ def _apply_selector_hysteresis(
     dnfr: float,
     accel: float,
     thr: dict[str, float],
-    margin: float,
+    margin: float | None,
 ) -> str | None:
     """Apply hysteresis when values are near thresholds.
 
@@ -183,8 +191,10 @@ def _apply_selector_hysteresis(
         Normalised acceleration.
     thr : dict[str, float]
         Thresholds returned by :func:`_selector_thresholds`.
-    margin : float
-        Distance from thresholds below which the previous glyph is reused.
+    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
     -------
@@ -192,6 +202,9 @@ def _apply_selector_hysteresis(
         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)
@@ -208,3 +221,27 @@ def _apply_selector_hysteresis(
         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