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

tnfr/validation/sequence_validator.py

@@ -0,0 +1,162 @@
+"""Semantic validation for TNFR operator sequences.
+
+This module validates the semantic correctness of operator sequences beyond
+syntactic grammar rules. It checks for patterns that may indicate structural
+instability or non-canonical reorganization.
+"""
+
+from __future__ import annotations
+
+from .invariants import InvariantSeverity, InvariantViolation
+
+__all__ = [
+    "SequenceSemanticValidator",
+]
+
+
+class SequenceSemanticValidator:
+    """Validates semantics of operator sequences."""
+
+    def __init__(self) -> None:
+        """Initialize semantic validator with default rules."""
+        # Semantic rules between operators
+        self.semantic_rules: dict[str, dict] = {
+            "mutation_without_stabilization": {
+                "pattern": ["mutation"],
+                "not_followed_by": ["coherence", "silence"],
+                "severity": InvariantSeverity.WARNING,
+                "message": "Mutation should be followed by stabilization (coherence or silence)",
+            },
+            "excessive_dissonance": {
+                "pattern": ["dissonance", "dissonance", "dissonance"],
+                "severity": InvariantSeverity.ERROR,
+                "message": "Excessive consecutive dissonance may destabilize structure",
+            },
+            "contraction_after_silence": {
+                "pattern": ["silence", "contraction"],
+                "severity": InvariantSeverity.WARNING,
+                "message": "Contraction immediately after silence may be redundant",
+            },
+            "excessive_recursivity": {
+                "pattern": ["recursivity", "recursivity", "recursivity"],
+                "severity": InvariantSeverity.WARNING,
+                "message": "Excessive consecutive recursivity may indicate inefficient sequence design",
+            },
+            "silence_after_mutation": {
+                "pattern": ["mutation", "silence"],
+                "severity": InvariantSeverity.INFO,
+                "message": "Silence after mutation preserves the new phase state (valid pattern)",
+            },
+        }
+
+    def validate_semantic_sequence(
+        self, sequence: list[str]
+    ) -> list[InvariantViolation]:
+        """Validates semantics of the operator sequence.
+
+        Parameters
+        ----------
+        sequence : list[str]
+            List of operator names in sequence.
+
+        Returns
+        -------
+        list[InvariantViolation]
+            List of semantic violations found.
+        """
+        violations: list[InvariantViolation] = []
+
+        for rule_name, rule in self.semantic_rules.items():
+            violations.extend(self._check_rule(sequence, rule_name, rule))
+
+        return violations
+
+    def _check_rule(
+        self, sequence: list[str], rule_name: str, rule: dict
+    ) -> list[InvariantViolation]:
+        """Verifies a specific semantic rule.
+
+        Parameters
+        ----------
+        sequence : list[str]
+            Operator sequence to check.
+        rule_name : str
+            Name of the rule being checked.
+        rule : dict
+            Rule definition with pattern and constraints.
+
+        Returns
+        -------
+        list[InvariantViolation]
+            Violations found for this rule.
+        """
+        violations: list[InvariantViolation] = []
+        pattern = rule["pattern"]
+
+        # Search for patterns in the sequence
+        for i in range(len(sequence) - len(pattern) + 1):
+            if sequence[i : i + len(pattern)] == pattern:
+
+                # If there are no additional constraints, the pattern itself is a violation
+                if "not_followed_by" not in rule and "not_preceded_by" not in rule:
+                    violations.append(
+                        InvariantViolation(
+                            invariant_id=0,
+                            severity=rule["severity"],
+                            description=f"Semantic rule violation: {rule['message']}",
+                            suggestion=rule.get(
+                                "suggestion", "Review operator sequence"
+                            ),
+                        )
+                    )
+                    continue
+
+                # Verificar reglas 'not_followed_by'
+                if "not_followed_by" in rule:
+                    next_pos = i + len(pattern)
+                    if next_pos < len(sequence):
+                        next_op = sequence[next_pos]
+                        if next_op not in rule["not_followed_by"]:
+                            violations.append(
+                                InvariantViolation(
+                                    invariant_id=0,  # Semántica, no invariante numérico
+                                    severity=rule["severity"],
+                                    description=f"Semantic rule violation: {rule['message']}",
+                                    suggestion=f"Consider adding one of: {rule['not_followed_by']}",
+                                )
+                            )
+                    # Si es el último operador y la regla requiere algo después
+                    elif next_pos == len(sequence):
+                        violations.append(
+                            InvariantViolation(
+                                invariant_id=0,
+                                severity=rule["severity"],
+                                description=f"Semantic rule violation: {rule['message']}",
+                                suggestion=f"Sequence should end with one of: {rule['not_followed_by']}",
+                            )
+                        )
+
+                # Verificar reglas 'not_preceded_by'
+                if "not_preceded_by" in rule:
+                    if i == 0:  # No hay operador anterior
+                        violations.append(
+                            InvariantViolation(
+                                invariant_id=0,
+                                severity=rule["severity"],
+                                description=f"Semantic rule violation: {rule['message']}",
+                                suggestion=f"Sequence should start with one of: {rule['not_preceded_by']}",
+                            )
+                        )
+                    else:
+                        prev_op = sequence[i - 1]
+                        if prev_op not in rule["not_preceded_by"]:
+                            violations.append(
+                                InvariantViolation(
+                                    invariant_id=0,
+                                    severity=rule["severity"],
+                                    description=f"Semantic rule violation: {rule['message']}",
+                                    suggestion=f"'{pattern[0]}' should be preceded by one of: {rule['not_preceded_by']}",
+                                )
+                            )
+
+        return violations

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.validation.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,32 @@
+from __future__ import annotations
+
+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,164 @@
+"""Spectral validation helpers aligned with the TNFR canonical interface."""
+
+from __future__ import annotations
+
+from ..compat.dataclass 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,42 @@
+from __future__ import annotations
+
+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",)