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

tnfr/validation/soft_filters.py

@@ -0,0 +1,170 @@
+"""Soft grammar filters harmonising canonical selector heuristics."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+
+from ..alias import get_attr
+from ..constants.aliases import ALIAS_D2EPI
+from ..glyph_history import recent_glyph
+from ..types import Glyph
+from ..utils import clamp01
+from .rules import glyph_fallback, get_norm, normalized_dnfr
+
+if TYPE_CHECKING:  # pragma: no cover - import cycle guard
+    from collections.abc import Mapping
+    from ..operators.grammar import GrammarContext
+
+__all__ = (
+    "acceleration_norm",
+    "check_repeats",
+    "maybe_force",
+    "soft_grammar_filters",
+)
+
+
+def acceleration_norm(ctx: "GrammarContext", nd: "Mapping[str, Any]") -> float:
+    """Return the node acceleration normalised to ``[0, 1]``.
+
+    The computation uses the canonical ``accel_max`` bound stored in
+    :class:`~tnfr.operators.grammar.GrammarContext`.  Values beyond the bound are
+    clamped to preserve structural comparability with ΔNFR-based heuristics.
+    """
+
+    max_val = get_norm(ctx, "accel_max")
+    return clamp01(abs(get_attr(nd, ALIAS_D2EPI, 0.0)) / max_val)
+def check_repeats(
+    ctx: "GrammarContext", n: Any, cand: Glyph | str
+) -> Glyph | str:
+    """Swap ``cand`` when it breaches the configured repetition window.
+
+    The rule honours the soft grammar configuration stored in ``ctx.cfg_soft``:
+
+    * ``window`` specifies the history length inspected using
+      :func:`tnfr.glyph_history.recent_glyph`.
+    * ``avoid_repeats`` enumerates glyph codes to dodge within that window.
+    * ``fallbacks`` optionally map avoided glyph codes to explicit
+      replacements, defaulting to canonical fallbacks when unspecified.
+    """
+
+    nd = ctx.G.nodes[n]
+    cfg = ctx.cfg_soft
+    gwin = int(cfg.get("window", 0))
+    avoid = set(cfg.get("avoid_repeats", []))
+    fallbacks = cfg.get("fallbacks", {})
+    cand_key = cand.value if isinstance(cand, Glyph) else str(cand)
+    if gwin > 0 and cand_key in avoid and recent_glyph(nd, cand_key, gwin):
+        fallback = glyph_fallback(cand_key, fallbacks)
+        fallback_key = fallback.value if isinstance(fallback, Glyph) else str(fallback)
+        if fallback_key != cand_key:
+            return fallback
+        history: list[str] = []
+        for item in nd.get("glyph_history", ()): 
+            if isinstance(item, Glyph):
+                history.append(item.value)
+            else:
+                try:
+                    history.append(Glyph(str(item)).value)
+                except (TypeError, ValueError):
+                    history.append(str(item))
+        order = (*history[-gwin:], cand_key)
+        from ..operators import grammar as _grammar
+
+        def to_structural(value: Glyph | str) -> str:
+            default = value.value if isinstance(value, Glyph) else str(value)
+            result = _grammar.glyph_function_name(value, default=default)
+            return default if result is None else result
+
+        cand_name = to_structural(cand_key)
+        fallback_name = to_structural(fallback_key)
+        order_names = tuple(to_structural(item) for item in order)
+
+        raise _grammar.RepeatWindowError(
+            rule="repeat-window",
+            candidate=cand_name,
+            message=f"{cand_name} repeats within window {gwin}",
+            window=gwin,
+            order=order_names,
+            context={"fallback": fallback_name},
+        )
+    return cand
+
+
+def maybe_force(
+    ctx: "GrammarContext",
+    n: Any,
+    cand: Glyph | str,
+    original: Glyph | str,
+    accessor: Callable[["GrammarContext", "Mapping[str, Any]"], float],
+    key: str,
+) -> Glyph | str:
+    """Return ``original`` when ``accessor`` crosses the soft threshold ``key``.
+
+    ``accessor`` receives the grammar context and node attributes.  Whenever the
+    resulting score is greater than or equal to the configured threshold the
+    original candidate is restored, ensuring soft filters never override
+    high-confidence canonical choices.
+    """
+
+    if cand == original:
+        return cand
+    force_th = float(ctx.cfg_soft.get(key, 0.60))
+    if accessor(ctx, ctx.G.nodes[n]) >= force_th:
+        return original
+    return cand
+
+
+def _match_template(result: Glyph | str, template: Glyph | str) -> Glyph | str:
+    """Coerce ``result`` to mirror ``template``'s representation when possible."""
+
+    if isinstance(template, str) and isinstance(result, Glyph):
+        return result.value
+    if isinstance(template, Glyph) and isinstance(result, str):
+        try:
+            return Glyph(result)
+        except (TypeError, ValueError):
+            return result
+    return result
+
+
+def soft_grammar_filters(
+    ctx: "GrammarContext",
+    n: Any,
+    cand: Glyph | str,
+    *,
+    original: Glyph | str | None = None,
+    template: Glyph | str | None = None,
+) -> Glyph | str:
+    """Apply the canonical soft grammar pipeline for ``cand``.
+
+    The pipeline performs three ordered checks:
+
+    1. :func:`check_repeats` swaps recent repetitions for the configured
+       fallback glyphs.
+    2. :func:`maybe_force` with :func:`tnfr.validation.rules.normalized_dnfr`
+       restores the original glyph when ΔNFR already exceeds ``force_dnfr``.
+    3. :func:`maybe_force` with :func:`acceleration_norm` performs the same
+       safeguard using the ``force_accel`` threshold.
+
+    Parameters
+    ----------
+    ctx:
+        Active grammar context providing node access and configuration.
+    n:
+        Node identifier inside ``ctx.G``.
+    cand:
+        Candidate glyph (``Glyph`` or code string) to validate softly.
+    original:
+        Optional glyph used as the reference for :func:`maybe_force`.  When
+        omitted, ``cand`` before filtering is used as the anchor value.
+    template:
+        Optional value whose type will be preserved in the returned result.  By
+        default the original ``cand`` representation is used.
+    """
+
+    anchor = cand if original is None else original
+    filtered = check_repeats(ctx, n, cand)
+    filtered = maybe_force(ctx, n, filtered, anchor, normalized_dnfr, "force_dnfr")
+    filtered = maybe_force(ctx, n, filtered, anchor, acceleration_norm, "force_accel")
+    base_template = cand if template is None else template
+    return _match_template(filtered, base_template)

tnfr/validation/soft_filters.pyi

@@ -0,0 +1,37 @@
+from typing import Any, Callable, Mapping
+
+from ..types import Glyph
+from .grammar import GrammarContext
+
+__all__ = (
+    "acceleration_norm",
+    "check_repeats",
+    "maybe_force",
+    "soft_grammar_filters",
+)
+
+
+def acceleration_norm(ctx: GrammarContext, nd: Mapping[str, Any]) -> float: ...
+
+
+def check_repeats(ctx: GrammarContext, n: Any, cand: Glyph | str) -> Glyph | str: ...
+
+
+def maybe_force(
+    ctx: GrammarContext,
+    n: Any,
+    cand: Glyph | str,
+    original: Glyph | str,
+    accessor: Callable[[GrammarContext, Mapping[str, Any]], float],
+    key: str,
+) -> Glyph | str: ...
+
+
+def soft_grammar_filters(
+    ctx: GrammarContext,
+    n: Any,
+    cand: Glyph | str,
+    *,
+    original: Glyph | str | None = ...,
+    template: Glyph | str | None = ...,
+) -> Glyph | str: ...

tnfr/validation/spectral.py

@@ -0,0 +1,159 @@
+"""Spectral validation helpers aligned with the TNFR canonical interface."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping, Sequence
+
+import numpy as np
+
+from ..mathematics.operators import CoherenceOperator, FrequencyOperator
+from ..mathematics.spaces import HilbertSpace
+from ..mathematics.runtime import (
+    coherence as runtime_coherence,
+    frequency_positive as runtime_frequency_positive,
+    normalized as runtime_normalized,
+    stable_unitary as runtime_stable_unitary,
+)
+from . import ValidationOutcome, Validator
+
+__all__ = ("NFRValidator",)
+
+
+@dataclass(slots=True)
+class NFRValidator(Validator[np.ndarray]):
+    """Validate spectral states against TNFR canonical invariants."""
+
+    hilbert_space: HilbertSpace
+    coherence_operator: CoherenceOperator
+    coherence_threshold: float
+    frequency_operator: FrequencyOperator | None = None
+    atol: float = 1e-9
+
+    def _compute_summary(
+        self,
+        state: Sequence[complex] | np.ndarray,
+        *,
+        enforce_frequency_positivity: bool | None = None,
+    ) -> tuple[bool, dict[str, Any], np.ndarray]:
+        vector = self.hilbert_space.project(state)
+
+        normalized_passed, norm_value = runtime_normalized(
+            vector, self.hilbert_space, atol=self.atol
+        )
+        if np.isclose(norm_value, 0.0, atol=self.atol):
+            raise ValueError("Cannot normalise a null state vector.")
+        normalised_vector = vector / norm_value
+
+        coherence_passed, coherence_value = runtime_coherence(
+            normalised_vector,
+            self.coherence_operator,
+            self.coherence_threshold,
+            normalise=False,
+            atol=self.atol,
+        )
+
+        frequency_summary: dict[str, Any] | None = None
+        freq_ok = True
+        if self.frequency_operator is not None:
+            if enforce_frequency_positivity is None:
+                enforce_frequency_positivity = True
+
+            runtime_summary = runtime_frequency_positive(
+                normalised_vector,
+                self.frequency_operator,
+                normalise=False,
+                enforce=enforce_frequency_positivity,
+                atol=self.atol,
+            )
+            freq_ok = bool(runtime_summary["passed"])
+            frequency_summary = {
+                **runtime_summary,
+                "enforced": runtime_summary["enforce"],
+            }
+            frequency_summary.pop("enforce", None)
+        elif enforce_frequency_positivity:
+            raise ValueError("Frequency positivity enforcement requested without operator.")
+
+        unitary_passed, unitary_norm = runtime_stable_unitary(
+            normalised_vector,
+            self.coherence_operator,
+            self.hilbert_space,
+            normalise=False,
+            atol=self.atol,
+        )
+
+        summary: dict[str, Any] = {
+            "normalized": bool(normalized_passed),
+            "coherence": {
+                "passed": bool(coherence_passed),
+                "value": coherence_value,
+                "threshold": self.coherence_threshold,
+            },
+            "frequency": frequency_summary,
+            "unitary_stability": {
+                "passed": bool(unitary_passed),
+                "norm_after": unitary_norm,
+            },
+        }
+
+        overall = bool(normalized_passed and coherence_passed and freq_ok and unitary_passed)
+        return overall, summary, normalised_vector
+
+    def validate(
+        self,
+        subject: Sequence[complex] | np.ndarray,
+        /,
+        *,
+        enforce_frequency_positivity: bool | None = None,
+    ) -> ValidationOutcome[np.ndarray]:
+        """Return :class:`ValidationOutcome` for ``subject``."""
+
+        overall, summary, normalised_vector = self._compute_summary(
+            subject, enforce_frequency_positivity=enforce_frequency_positivity
+        )
+        artifacts = {"normalised_state": normalised_vector}
+        return ValidationOutcome(
+            subject=normalised_vector,
+            passed=overall,
+            summary=summary,
+            artifacts=artifacts,
+        )
+
+    def validate_state(
+        self,
+        state: Sequence[complex] | np.ndarray,
+        *,
+        enforce_frequency_positivity: bool | None = None,
+    ) -> tuple[bool, dict[str, Any]]:
+        """Backward compatible validation returning ``(passed, summary)``."""
+
+        overall, summary, _ = self._compute_summary(
+            state, enforce_frequency_positivity=enforce_frequency_positivity
+        )
+        return overall, summary
+
+    def report(self, outcome: ValidationOutcome[np.ndarray]) -> str:
+        """Return a human-readable report naming failed conditions."""
+
+        summary = outcome.summary
+        failed_checks: list[str] = []
+        if not summary.get("normalized", False):
+            failed_checks.append("normalization")
+
+        coherence_summary = summary.get("coherence", {})
+        if not coherence_summary.get("passed", False):
+            failed_checks.append("coherence threshold")
+
+        frequency_summary = summary.get("frequency")
+        if isinstance(frequency_summary, Mapping) and not frequency_summary.get("passed", False):
+            failed_checks.append("frequency positivity")
+
+        unitary_summary = summary.get("unitary_stability", {})
+        if not unitary_summary.get("passed", False):
+            failed_checks.append("unitary stability")
+
+        if not failed_checks:
+            return "All validation checks passed."
+        return "Failed checks: " + ", ".join(failed_checks) + "."
+

tnfr/validation/spectral.pyi

@@ -0,0 +1,46 @@
+from typing import Any, Mapping, Sequence
+
+import numpy as np
+
+from ..mathematics.operators import CoherenceOperator, FrequencyOperator
+from ..mathematics.spaces import HilbertSpace
+from . import ValidationOutcome, Validator
+
+
+class NFRValidator(Validator[np.ndarray]):
+    hilbert_space: HilbertSpace
+    coherence_operator: CoherenceOperator
+    coherence_threshold: float
+    frequency_operator: FrequencyOperator | None
+    atol: float
+
+    def __init__(
+        self,
+        hilbert_space: HilbertSpace,
+        coherence_operator: CoherenceOperator,
+        *,
+        coherence_threshold: float,
+        frequency_operator: FrequencyOperator | None = ...,
+        atol: float = ...,
+    ) -> None: ...
+
+    def validate(
+        self,
+        subject: Sequence[complex] | np.ndarray,
+        /,
+        *,
+        enforce_frequency_positivity: bool | None = ...,
+    ) -> ValidationOutcome[np.ndarray]: ...  # type: ignore[override]
+
+    def validate_state(
+        self,
+        state: Sequence[complex] | np.ndarray,
+        *,
+        enforce_frequency_positivity: bool | None = ...,
+    ) -> tuple[bool, Mapping[str, Any]]: ...
+
+    def report(self, outcome: ValidationOutcome[np.ndarray]) -> str: ...
+
+
+__all__ = ("NFRValidator",)
+

tnfr/validation/syntax.py

@@ -0,0 +1,40 @@
+"""Deprecated entry point for sequence validation.
+
+Projects should import :func:`tnfr.operators.grammar.validate_sequence` directly;
+this shim remains only for backwards compatibility and will be removed in a
+future release.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+import warnings
+
+from . import ValidationOutcome
+from ..operators import grammar as _canonical
+from ..operators.grammar import validate_sequence as _validate_sequence
+
+__all__ = ("validate_sequence",)
+
+warnings.warn(
+    "'tnfr.validation.syntax' is deprecated; use 'tnfr.operators.grammar' "
+    "for sequence validation.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+
+def validate_sequence(
+    names: Iterable[str] | object = _canonical._MISSING, **kwargs: Any
+) -> ValidationOutcome[tuple[str, ...]]:
+    """Proxy to :func:`tnfr.operators.grammar.validate_sequence`."""
+
+    warnings.warn(
+        "'tnfr.validation.syntax.validate_sequence' is deprecated; "
+        "use 'tnfr.operators.grammar.validate_sequence' instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return _validate_sequence(names, **kwargs)
+

tnfr/validation/syntax.pyi

@@ -0,0 +1,10 @@
+from collections.abc import Iterable
+
+from . import ValidationOutcome
+
+__all__ = ("validate_sequence",)
+
+
+def validate_sequence(
+    names: Iterable[str] | object = ..., **kwargs: object
+) -> ValidationOutcome[tuple[str, ...]]: ...

tnfr/validation/window.py

@@ -0,0 +1,39 @@
+"""Primitive window validation helpers without heavy dependencies."""
+
+from __future__ import annotations
+
+import numbers
+
+__all__ = ["validate_window"]
+
+
+def validate_window(window: int, *, positive: bool = False) -> int:
+    """Validate ``window`` as an integer and return it.
+
+    Parameters
+    ----------
+    window:
+        Value to coerce into an integer window size.
+    positive:
+        When ``True`` the window must be strictly greater than zero; otherwise
+        zero is accepted. Negative values are never permitted.
+
+    Returns
+    -------
+    int
+        The validated integer window size.
+
+    Raises
+    ------
+    TypeError
+        If ``window`` is not an integer value.
+    ValueError
+        If ``window`` violates the positivity constraint.
+    """
+
+    if isinstance(window, bool) or not isinstance(window, numbers.Integral):
+        raise TypeError("'window' must be an integer")
+    if window < 0 or (positive and window == 0):
+        kind = "positive" if positive else "non-negative"
+        raise ValueError(f"'window'={window} must be {kind}")
+    return int(window)

tnfr/validation/window.pyi

@@ -0,0 +1 @@
+def validate_window(window: int, *, positive: bool = ...) -> int: ...

tnfr/viz/__init__.py

@@ -0,0 +1,9 @@
+"""Visualization helpers for TNFR telemetry."""
+
+from .matplotlib import plot_coherence_matrix, plot_phase_sync, plot_spectrum_path
+
+__all__ = [
+    "plot_coherence_matrix",
+    "plot_phase_sync",
+    "plot_spectrum_path",
+]