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

tnfr/errors/contextual.py

@@ -0,0 +1,492 @@
+"""Contextual error handling for TNFR operations.
+
+This module provides enhanced error messages that guide users to solutions
+while maintaining TNFR theoretical compliance. All errors include:
+
+1. Clear explanation of the violation
+2. Actionable suggestions for resolution
+3. Links to relevant documentation
+4. Context about the structural operation that failed
+
+Canonical Invariants Preserved
+------------------------------
+These errors enforce TNFR invariants from AGENTS.md:
+- Operator closure and sequence validity
+- Phase synchrony requirements for coupling
+- Frequency (νf) bounds in Hz_str units
+- ΔNFR semantic correctness
+- EPI coherence preservation
+"""
+
+from __future__ import annotations
+
+from difflib import get_close_matches
+from typing import Optional, List, Dict, Any
+
+__all__ = [
+    "TNFRUserError",
+    "OperatorSequenceError",
+    "NetworkConfigError",
+    "PhaseError",
+    "CoherenceError",
+    "FrequencyError",
+]
+
+
+class TNFRUserError(Exception):
+    """Base class for user-facing TNFR errors with helpful context.
+
+    All TNFR errors inherit from this class and provide:
+    - Human-readable error messages
+    - Actionable suggestions
+    - Documentation links
+    - Structural context
+
+    Parameters
+    ----------
+    message : str
+        Primary error message describing what went wrong.
+    suggestion : str, optional
+        Specific suggestion for how to fix the issue.
+    docs_url : str, optional
+        URL to relevant documentation section.
+    context : dict, optional
+        Additional context about the failed operation (node IDs, values, etc).
+
+    Examples
+    --------
+    >>> raise TNFRUserError(
+    ...     "Invalid structural frequency",
+    ...     suggestion="νf must be positive in Hz_str units",
+    ...     docs_url="https://tnfr.readthedocs.io/api/core.html#frequency"
+    ... )
+    """
+
+    def __init__(
+        self,
+        message: str,
+        suggestion: Optional[str] = None,
+        docs_url: Optional[str] = None,
+        context: Optional[Dict[str, Any]] = None,
+    ):
+        self.message = message
+        self.suggestion = suggestion
+        self.docs_url = docs_url
+        self.context = context or {}
+
+        # Build comprehensive error message
+        full_message = f"\n{'='*70}\n"
+        full_message += f"TNFR Error: {message}\n"
+        full_message += f"{'='*70}\n"
+
+        if suggestion:
+            full_message += f"\n💡 Suggestion: {suggestion}\n"
+
+        if context:
+            full_message += f"\n📊 Context:\n"
+            for key, value in context.items():
+                full_message += f"   • {key}: {value}\n"
+
+        if docs_url:
+            full_message += f"\n📚 Documentation: {docs_url}\n"
+
+        full_message += f"{'='*70}\n"
+
+        super().__init__(full_message)
+
+
+class OperatorSequenceError(TNFRUserError):
+    """Error raised when operator sequence violates TNFR grammar.
+
+    TNFR operators must be applied in valid sequences that respect
+    structural coherence. This error provides:
+    - The invalid sequence attempted
+    - Which operator violated the grammar
+    - Valid next operators
+    - Fuzzy matching for typos
+
+    Enforces Invariant #4: Operator closure from AGENTS.md
+
+    Parameters
+    ----------
+    invalid_operator : str
+        The operator that violated the grammar.
+    sequence_so_far : list of str
+        Operators successfully applied before the error.
+    valid_next : list of str, optional
+        Valid operators that can follow the current sequence.
+
+    Examples
+    --------
+    >>> raise OperatorSequenceError(
+    ...     "emision",
+    ...     ["reception", "coherence"],
+    ...     ["emission", "recursivity"]
+    ... )
+    """
+
+    # Valid TNFR operators (13 canonical operators)
+    VALID_OPERATORS = {
+        "emission",
+        "reception",
+        "coherence",
+        "dissonance",
+        "coupling",
+        "resonance",
+        "silence",
+        "expansion",
+        "contraction",
+        "self_organization",
+        "mutation",
+        "transition",
+        "recursivity",
+    }
+
+    # Operator aliases for user convenience
+    OPERATOR_ALIASES = {
+        "emit": "emission",
+        "receive": "reception",
+        "cohere": "coherence",
+        "couple": "coupling",
+        "resonate": "resonance",
+        "silent": "silence",
+        "expand": "expansion",
+        "contract": "contraction",
+        "self_organize": "self_organization",
+        "mutate": "mutation",
+        "recurse": "recursivity",
+    }
+
+    def __init__(
+        self,
+        invalid_operator: str,
+        sequence_so_far: Optional[List[str]] = None,
+        valid_next: Optional[List[str]] = None,
+    ):
+        sequence_so_far = sequence_so_far or []
+
+        # Try fuzzy matching for typos
+        all_valid = list(self.VALID_OPERATORS) + list(self.OPERATOR_ALIASES.keys())
+        matches = get_close_matches(invalid_operator, all_valid, n=3, cutoff=0.6)
+
+        suggestion_parts = []
+        if matches:
+            suggestion_parts.append(f"Did you mean one of: {', '.join(matches)}?")
+
+        if valid_next:
+            suggestion_parts.append(f"Valid next operators: {', '.join(valid_next)}")
+        else:
+            suggestion_parts.append(
+                f"Use one of the 13 canonical operators: "
+                f"{', '.join(sorted(self.VALID_OPERATORS))}"
+            )
+
+        suggestion = " ".join(suggestion_parts) if suggestion_parts else None
+
+        context = {
+            "invalid_operator": invalid_operator,
+            "sequence_so_far": (
+                " → ".join(sequence_so_far) if sequence_so_far else "empty"
+            ),
+            "operator_count": len(sequence_so_far),
+        }
+
+        super().__init__(
+            message=f"Invalid operator sequence: '{invalid_operator}' cannot be applied",
+            suggestion=suggestion,
+            docs_url="https://github.com/fermga/Teoria-de-la-naturaleza-fractal-resonante-TNFR-/blob/main/docs/source/api/operators.md",
+            context=context,
+        )
+
+
+class NetworkConfigError(TNFRUserError):
+    """Error raised when network configuration violates TNFR constraints.
+
+    This error validates configuration parameters and provides valid ranges
+    with physical/structural meaning.
+
+    Enforces multiple invariants:
+    - Invariant #2: Structural units (νf in Hz_str)
+    - Invariant #5: Phase check requirements
+    - Invariant #6: Node birth/collapse conditions
+
+    Parameters
+    ----------
+    parameter : str
+        The configuration parameter that is invalid.
+    value : any
+        The invalid value provided.
+    valid_range : tuple, optional
+        Valid range for the parameter (min, max).
+    reason : str, optional
+        Structural reason for the constraint.
+
+    Examples
+    --------
+    >>> raise NetworkConfigError(
+    ...     "vf",
+    ...     -0.5,
+    ...     (0.01, 100.0),
+    ...     "Structural frequency must be positive (Hz_str units)"
+    ... )
+    """
+
+    # Valid parameter ranges with structural meaning
+    PARAMETER_CONSTRAINTS = {
+        "vf": {
+            "range": (0.01, 100.0),
+            "unit": "Hz_str",
+            "description": "Structural frequency (reorganization rate)",
+        },
+        "phase": {
+            "range": (0.0, 2 * 3.14159),
+            "unit": "radians",
+            "description": "Phase angle for network synchrony",
+        },
+        "coherence": {
+            "range": (0.0, 1.0),
+            "unit": "dimensionless",
+            "description": "Structural stability measure C(t)",
+        },
+        "delta_nfr": {
+            "range": (-10.0, 10.0),
+            "unit": "dimensionless",
+            "description": "Internal reorganization gradient ΔNFR",
+        },
+        "epi": {
+            "range": (0.0, 1.0),
+            "unit": "dimensionless",
+            "description": "Primary Information Structure magnitude",
+        },
+        "edge_probability": {
+            "range": (0.0, 1.0),
+            "unit": "probability",
+            "description": "Network edge connection probability",
+        },
+        "num_nodes": {
+            "range": (1, 100000),
+            "unit": "count",
+            "description": "Number of nodes in network",
+        },
+    }
+
+    def __init__(
+        self,
+        parameter: str,
+        value: Any,
+        valid_range: Optional[tuple] = None,
+        reason: Optional[str] = None,
+    ):
+        # Get constraint info if available
+        constraint_info = self.PARAMETER_CONSTRAINTS.get(parameter)
+
+        if constraint_info and not valid_range:
+            valid_range = constraint_info["range"]
+            reason = reason or constraint_info["description"]
+
+        suggestion_parts = []
+        if valid_range:
+            min_val, max_val = valid_range
+            suggestion_parts.append(
+                f"'{parameter}' must be in range [{min_val}, {max_val}]"
+            )
+
+        if constraint_info:
+            suggestion_parts.append(f"Unit: {constraint_info['unit']}")
+
+        if reason:
+            suggestion_parts.append(f"Structural meaning: {reason}")
+
+        context = {
+            "parameter": parameter,
+            "provided_value": value,
+            "valid_range": (
+                f"[{valid_range[0]}, {valid_range[1]}]" if valid_range else "see docs"
+            ),
+        }
+
+        super().__init__(
+            message=f"Invalid network configuration for '{parameter}'",
+            suggestion=" | ".join(suggestion_parts) if suggestion_parts else None,
+            docs_url="https://github.com/fermga/Teoria-de-la-naturaleza-fractal-resonante-TNFR-/blob/main/docs/source/api/overview.md",
+            context=context,
+        )
+
+
+class PhaseError(TNFRUserError):
+    """Error raised when phase synchrony is violated.
+
+    TNFR requires explicit phase checking before coupling operations.
+    This error indicates phase incompatibility between nodes.
+
+    Enforces Invariant #5: Phase check from AGENTS.md
+
+    Parameters
+    ----------
+    node1 : str
+        First node ID.
+    node2 : str
+        Second node ID.
+    phase1 : float
+        Phase of first node (radians).
+    phase2 : float
+        Phase of second node (radians).
+    threshold : float
+        Phase difference threshold for coupling.
+
+    Examples
+    --------
+    >>> raise PhaseError("n1", "n2", 0.5, 2.8, 0.5)
+    """
+
+    def __init__(
+        self,
+        node1: str,
+        node2: str,
+        phase1: float,
+        phase2: float,
+        threshold: float = 0.5,
+    ):
+        phase_diff = abs(phase1 - phase2)
+
+        suggestion = (
+            f"Nodes cannot couple: phase difference ({phase_diff:.3f} rad) "
+            f"exceeds threshold ({threshold:.3f} rad). "
+            f"Apply phase synchronization or adjust threshold."
+        )
+
+        context = {
+            "node1": node1,
+            "node2": node2,
+            "phase1": f"{phase1:.3f} rad",
+            "phase2": f"{phase2:.3f} rad",
+            "phase_difference": f"{phase_diff:.3f} rad",
+            "threshold": f"{threshold:.3f} rad",
+        }
+
+        super().__init__(
+            message=f"Phase synchrony violation between nodes '{node1}' and '{node2}'",
+            suggestion=suggestion,
+            docs_url="https://github.com/fermga/Teoria-de-la-naturaleza-fractal-resonante-TNFR-/blob/main/GLOSSARY.md#phase",
+            context=context,
+        )
+
+
+class CoherenceError(TNFRUserError):
+    """Error raised when coherence operations violate monotonicity.
+
+    Coherence operator must not decrease C(t) except in controlled
+    dissonance tests. This error indicates unexpected coherence loss.
+
+    Enforces Invariant #1: EPI coherent form from AGENTS.md
+
+    Parameters
+    ----------
+    operation : str
+        The operation that caused coherence decrease.
+    before : float
+        Coherence C(t) before operation.
+    after : float
+        Coherence C(t) after operation.
+    node_id : str, optional
+        Node ID if the error is node-specific.
+
+    Examples
+    --------
+    >>> raise CoherenceError("coherence", 0.85, 0.42)
+    """
+
+    def __init__(
+        self,
+        operation: str,
+        before: float,
+        after: float,
+        node_id: Optional[str] = None,
+    ):
+        decrease = before - after
+        percent_loss = (decrease / before * 100) if before > 0 else 0
+
+        suggestion = (
+            f"Coherence decreased by {decrease:.3f} ({percent_loss:.1f}%). "
+            f"This violates the coherence monotonicity invariant. "
+            f"Check if this is a controlled dissonance test or if "
+            f"there's an unexpected structural instability."
+        )
+
+        context = {
+            "operation": operation,
+            "coherence_before": f"{before:.3f}",
+            "coherence_after": f"{after:.3f}",
+            "decrease": f"{decrease:.3f}",
+            "percent_loss": f"{percent_loss:.1f}%",
+        }
+
+        if node_id:
+            context["node_id"] = node_id
+
+        super().__init__(
+            message=f"Unexpected coherence decrease during '{operation}'",
+            suggestion=suggestion,
+            docs_url="https://github.com/fermga/Teoria-de-la-naturaleza-fractal-resonante-TNFR-/blob/main/AGENTS.md#canonical-invariants",
+            context=context,
+        )
+
+
+class FrequencyError(TNFRUserError):
+    """Error raised when structural frequency νf is invalid.
+
+    Structural frequency must be positive and expressed in Hz_str
+    (structural hertz) units. This error indicates frequency violations.
+
+    Enforces Invariant #2: Structural units from AGENTS.md
+
+    Parameters
+    ----------
+    node_id : str
+        Node ID with invalid frequency.
+    vf : float
+        The invalid frequency value.
+    operation : str, optional
+        Operation that triggered the check.
+
+    Examples
+    --------
+    >>> raise FrequencyError("n1", -0.5, "emission")
+    """
+
+    def __init__(
+        self,
+        node_id: str,
+        vf: float,
+        operation: Optional[str] = None,
+    ):
+        if vf <= 0:
+            suggestion = (
+                f"Structural frequency νf must be positive (Hz_str units). "
+                f"Set νf > 0 for node '{node_id}'. "
+                f"Typical range: 0.1 to 10.0 Hz_str."
+            )
+        elif vf > 100:
+            suggestion = (
+                f"Structural frequency νf = {vf:.3f} Hz_str is very high. "
+                f"Typical range: 0.1 to 10.0 Hz_str. "
+                f"Verify this is intentional."
+            )
+        else:
+            suggestion = f"Verify structural frequency for node '{node_id}'."
+
+        context = {
+            "node_id": node_id,
+            "vf": f"{vf:.3f} Hz_str",
+            "valid_range": "[0.01, 100.0] Hz_str",
+        }
+
+        if operation:
+            context["operation"] = operation
+
+        super().__init__(
+            message=f"Invalid structural frequency for node '{node_id}'",
+            suggestion=suggestion,
+            docs_url="https://github.com/fermga/Teoria-de-la-naturaleza-fractal-resonante-TNFR-/blob/main/GLOSSARY.md#structural-frequency",
+            context=context,
+        )

tnfr/execution.py

@@ -0,0 +1,223 @@
+"""Execution helpers for canonical TNFR programs."""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Callable, Iterable, Sequence
+from typing import Any, Optional, cast
+
+from ._compat import TypeAlias
+from .constants import get_param
+from .dynamics import step
+from .flatten import _flatten
+from .glyph_history import ensure_history
+from .tokens import TARGET, THOL, WAIT, OpTag, Token
+from .types import Glyph, NodeId, TNFRGraph
+from .utils import MAX_MATERIALIZE_DEFAULT, ensure_collection, is_non_string_sequence
+from .validation import apply_glyph_with_grammar
+
+AdvanceFn = Callable[[TNFRGraph], None]
+TraceEntry = dict[str, Any]
+ProgramTrace: TypeAlias = deque[TraceEntry]
+HandlerFn = Callable[
+    [TNFRGraph, Any, Optional[Sequence[NodeId]], ProgramTrace, AdvanceFn],
+    Optional[Sequence[NodeId]],
+]
+
+__all__ = [
+    "AdvanceFn",
+    "CANONICAL_PRESET_NAME",
+    "CANONICAL_PROGRAM_TOKENS",
+    "HANDLERS",
+    "_apply_glyph_to_targets",
+    "_record_trace",
+    "compile_sequence",
+    "basic_canonical_example",
+    "block",
+    "play",
+    "seq",
+    "target",
+    "wait",
+]
+
+CANONICAL_PRESET_NAME = "canonical_example"
+CANONICAL_PROGRAM_TOKENS: tuple[Token, ...] = (
+    Glyph.SHA,  # silence - initial stabilization
+    Glyph.AL,  # emission - initiate pattern
+    Glyph.RA,  # reception - capture information
+    Glyph.OZ,  # dissonance - required before mutation (grammar rule)
+    Glyph.ZHIR,  # mutation - phase change
+    Glyph.NUL,  # contraction - compress structure
+    Glyph.THOL,  # self_organization - recursive reorganization
+)
+
+
+def _window(G: TNFRGraph) -> int:
+    return int(get_param(G, "GLYPH_HYSTERESIS_WINDOW"))
+
+
+def _apply_glyph_to_targets(
+    G: TNFRGraph, g: Glyph | str, nodes: Optional[Iterable[NodeId]] = None
+) -> None:
+    """Apply ``g`` to ``nodes`` (or all nodes) respecting the grammar."""
+
+    nodes_iter = G.nodes() if nodes is None else nodes
+    w = _window(G)
+    apply_glyph_with_grammar(G, nodes_iter, g, w)
+
+
+def _advance(G: TNFRGraph, step_fn: AdvanceFn) -> None:
+    step_fn(G)
+
+
+def _record_trace(trace: ProgramTrace, G: TNFRGraph, op: OpTag, **data: Any) -> None:
+    """Append an operation snapshot to ``trace`` using graph time metadata."""
+
+    trace.append({"t": float(G.graph.get("_t", 0.0)), "op": op.name, **data})
+
+
+def _advance_and_record(
+    G: TNFRGraph,
+    trace: ProgramTrace,
+    label: OpTag,
+    step_fn: AdvanceFn,
+    *,
+    times: int = 1,
+    **data: Any,
+) -> None:
+    for _ in range(times):
+        _advance(G, step_fn)
+    _record_trace(trace, G, label, **data)
+
+
+def _handle_target(
+    G: TNFRGraph,
+    payload: TARGET,
+    _curr_target: Optional[Sequence[NodeId]],
+    trace: ProgramTrace,
+    _step_fn: AdvanceFn,
+) -> Sequence[NodeId]:
+    """Handle a ``TARGET`` token and return the active node set."""
+
+    nodes_src = G.nodes() if payload.nodes is None else payload.nodes
+    nodes = ensure_collection(nodes_src, max_materialize=None)
+    if is_non_string_sequence(nodes):
+        curr_target = cast(Sequence[NodeId], nodes)
+    else:
+        curr_target = tuple(nodes)
+    _record_trace(trace, G, OpTag.TARGET, n=len(curr_target))
+    return curr_target
+
+
+def _handle_wait(
+    G: TNFRGraph,
+    steps: int,
+    curr_target: Optional[Sequence[NodeId]],
+    trace: ProgramTrace,
+    step_fn: AdvanceFn,
+) -> Optional[Sequence[NodeId]]:
+    _advance_and_record(G, trace, OpTag.WAIT, step_fn, times=steps, k=steps)
+    return curr_target
+
+
+def _handle_glyph(
+    G: TNFRGraph,
+    g: Glyph | str,
+    curr_target: Optional[Sequence[NodeId]],
+    trace: ProgramTrace,
+    step_fn: AdvanceFn,
+    label: OpTag = OpTag.GLYPH,
+) -> Optional[Sequence[NodeId]]:
+    _apply_glyph_to_targets(G, g, curr_target)
+    _advance_and_record(G, trace, label, step_fn, g=g)
+    return curr_target
+
+
+def _handle_thol(
+    G: TNFRGraph,
+    g: Glyph | str | None,
+    curr_target: Optional[Sequence[NodeId]],
+    trace: ProgramTrace,
+    step_fn: AdvanceFn,
+) -> Optional[Sequence[NodeId]]:
+    return _handle_glyph(
+        G, g or Glyph.THOL.value, curr_target, trace, step_fn, label=OpTag.THOL
+    )
+
+
+HANDLERS: dict[OpTag, HandlerFn] = {
+    OpTag.TARGET: _handle_target,
+    OpTag.WAIT: _handle_wait,
+    OpTag.GLYPH: _handle_glyph,
+    OpTag.THOL: _handle_thol,
+}
+
+
+def play(
+    G: TNFRGraph, sequence: Sequence[Token], step_fn: Optional[AdvanceFn] = None
+) -> None:
+    """Execute a canonical sequence on graph ``G``."""
+
+    step_fn = step_fn or step
+
+    curr_target: Optional[Sequence[NodeId]] = None
+
+    history = ensure_history(G)
+    maxlen = int(get_param(G, "PROGRAM_TRACE_MAXLEN"))
+    trace_obj = history.get("program_trace")
+    trace: ProgramTrace
+    if not isinstance(trace_obj, deque) or trace_obj.maxlen != maxlen:
+        trace = cast(ProgramTrace, deque(trace_obj or [], maxlen=maxlen))
+        history["program_trace"] = trace
+    else:
+        trace = cast(ProgramTrace, trace_obj)
+
+    for op, payload in _flatten(sequence):
+        handler: HandlerFn | None = HANDLERS.get(op)
+        if handler is None:
+            raise ValueError(f"Unknown operation: {op}")
+        curr_target = handler(G, payload, curr_target, trace, step_fn)
+
+
+def compile_sequence(
+    sequence: Iterable[Token] | Sequence[Token] | Any,
+    *,
+    max_materialize: int | None = MAX_MATERIALIZE_DEFAULT,
+) -> list[tuple[OpTag, Any]]:
+    """Return the operations executed by :func:`play` for ``sequence``."""
+
+    return _flatten(sequence, max_materialize=max_materialize)
+
+
+def seq(*tokens: Token) -> list[Token]:
+    """Return a mutable list of ``tokens`` for explicit sequence editing."""
+
+    return list(tokens)
+
+
+def block(*tokens: Token, repeat: int = 1, close: Optional[Glyph] = None) -> THOL:
+    """Build a THOL block with optional repetition and forced closure."""
+
+    return THOL(body=list(tokens), repeat=repeat, force_close=close)
+
+
+def target(nodes: Optional[Iterable[NodeId]] = None) -> TARGET:
+    """Return a TARGET token selecting ``nodes`` (defaults to all nodes)."""
+
+    return TARGET(nodes=nodes)
+
+
+def wait(steps: int = 1) -> WAIT:
+    """Return a WAIT token forcing ``steps`` structural updates before resuming."""
+
+    return WAIT(steps=max(1, int(steps)))
+
+
+def basic_canonical_example() -> list[Token]:
+    """Return the canonical preset sequence.
+
+    Returns a copy of the canonical preset tokens to keep CLI defaults aligned
+    with :func:`tnfr.config.presets.get_preset`.
+    """
+
+    return list(CANONICAL_PROGRAM_TOKENS)