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

tnfr/core/default_implementations.py

@@ -0,0 +1,329 @@
+"""Default implementations of TNFR core interfaces.
+
+This module provides concrete implementations of the architectural interfaces
+that wrap existing TNFR functionality. These implementations maintain backward
+compatibility while enabling the new modular architecture.
+
+Classes
+-------
+DefaultValidationService
+    Wraps tnfr.validation for sequence and graph validation.
+DefaultOperatorRegistry
+    Wraps tnfr.operators.registry for operator management.
+DefaultDynamicsEngine
+    Wraps tnfr.dynamics for ΔNFR computation and integration.
+DefaultTelemetryCollector
+    Wraps tnfr.metrics for coherence and sense index computation.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..types import TNFRGraph
+    from ..operators.definitions import Operator
+
+__all__ = (
+    "DefaultValidationService",
+    "DefaultOperatorRegistry",
+    "DefaultDynamicsEngine",
+    "DefaultTelemetryCollector",
+)
+
+
+class DefaultValidationService:
+    """Default implementation of ValidationService using tnfr.validation.
+
+    This implementation wraps the existing validation infrastructure to
+    provide the ValidationService interface without modifying existing code.
+    """
+
+    def validate_sequence(self, sequence: list[str]) -> None:
+        """Validate operator sequence using canonical grammar rules.
+
+        Parameters
+        ----------
+        sequence : list of str
+            Operator tokens to validate.
+
+        Raises
+        ------
+        ValueError
+            When sequence violates TNFR grammar or operator closure.
+        """
+        from ..validation import validate_sequence as _validate_sequence
+
+        # validate_sequence returns ValidationOutcome
+        outcome = _validate_sequence(sequence)
+        if not outcome.passed:
+            summary_message = outcome.summary.get("message", "validation failed")
+            raise ValueError(f"Invalid sequence: {summary_message}")
+
+    def validate_graph_state(self, graph: TNFRGraph) -> None:
+        """Validate graph state using canonical validators.
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph to validate.
+
+        Raises
+        ------
+        ValueError
+            When graph state violates structural invariants.
+        """
+        from ..validation import run_validators
+
+        # run_validators raises on failure by default
+        run_validators(graph)
+
+
+class DefaultOperatorRegistry:
+    """Default implementation of OperatorRegistry using tnfr.operators.
+
+    This implementation wraps the global OPERATORS registry to provide
+    the OperatorRegistry interface.
+    """
+
+    def get_operator(self, token: str) -> Operator:
+        """Retrieve operator by token from global registry.
+
+        Parameters
+        ----------
+        token : str
+            Operator identifier.
+
+        Returns
+        -------
+        Operator
+            The structural operator implementation (class, not instance).
+
+        Raises
+        ------
+        KeyError
+            When token is not registered.
+        """
+        from ..operators.registry import get_operator_class
+
+        # get_operator_class returns the operator class
+        return get_operator_class(token)
+
+    def register_operator(self, operator: Operator) -> None:
+        """Register operator in global registry.
+
+        Parameters
+        ----------
+        operator : Operator
+            Operator to register.
+        """
+        from ..operators.registry import OPERATORS
+
+        # Register by operator name
+        OPERATORS[operator.name] = operator.__class__
+
+
+class DefaultDynamicsEngine:
+    """Default implementation of DynamicsEngine using tnfr.dynamics.
+
+    This implementation wraps existing dynamics functions to provide
+    the DynamicsEngine interface.
+    """
+
+    def update_delta_nfr(self, graph: TNFRGraph) -> None:
+        """Compute ΔNFR using configured hook.
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph to update.
+        """
+        # Get the configured ΔNFR hook from graph metadata
+        compute = graph.graph.get("compute_delta_nfr")
+        if callable(compute):
+            compute(graph)
+
+    def integrate_nodal_equation(self, graph: TNFRGraph) -> None:
+        """Integrate nodal equation to update EPI.
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph to integrate.
+        """
+        from ..dynamics.integrators import update_epi_via_nodal_equation
+
+        # Use default integration parameters from graph
+        dt = graph.graph.get("dt", 0.1)
+        update_epi_via_nodal_equation(graph, dt=dt)
+
+    def coordinate_phase_coupling(self, graph: TNFRGraph) -> None:
+        """Coordinate phase synchronization.
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph whose phase is coordinated.
+        """
+        from ..dynamics.coordination import coordinate_global_local_phase
+
+        # Coordinate phase using default parameters
+        coordinate_global_local_phase(graph)
+
+
+class DefaultTraceContext:
+    """Default trace context for telemetry collection.
+
+    This context manager captures graph state before and after operator
+    application, recording transitions for structural analysis.
+    """
+
+    def __init__(self, graph: TNFRGraph):
+        """Initialize trace context.
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph being traced.
+        """
+        self.graph = graph
+        self.transitions: list[dict[str, Any]] = []
+
+    def __enter__(self):
+        """Enter trace context."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Exit trace context."""
+        # Save transitions when exiting context
+        self._save_transitions()
+        return False
+
+    def _save_transitions(self) -> None:
+        """Save transitions to graph metadata."""
+        if self.transitions:
+            existing = self.graph.graph.get("_trace_transitions", [])
+            existing_copy = list(existing)  # Make a copy to avoid mutation
+            existing_copy.extend(self.transitions)
+            self.graph.graph["_trace_transitions"] = existing_copy
+
+    def capture_state(self, graph: TNFRGraph) -> dict[str, Any]:
+        """Capture current graph state.
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph to capture.
+
+        Returns
+        -------
+        dict
+            State snapshot.
+        """
+        from ..metrics.common import compute_coherence
+
+        # Capture key metrics
+        return {
+            "coherence": compute_coherence(graph),
+            "node_count": graph.number_of_nodes(),
+            "edge_count": (
+                graph.number_of_edges() if hasattr(graph, "number_of_edges") else 0
+            ),
+        }
+
+    def record_transition(
+        self,
+        operator_token: str,
+        pre_state: dict[str, Any],
+        post_state: dict[str, Any],
+    ) -> None:
+        """Record operator transition.
+
+        Parameters
+        ----------
+        operator_token : str
+            Operator that caused transition.
+        pre_state : dict
+            State before operator.
+        post_state : dict
+            State after operator.
+        """
+        self.transitions.append(
+            {
+                "operator": operator_token,
+                "pre": pre_state,
+                "post": post_state,
+                "delta_coherence": post_state["coherence"] - pre_state["coherence"],
+            }
+        )
+
+
+class DefaultTelemetryCollector:
+    """Default implementation of TelemetryCollector using tnfr.metrics.
+
+    This implementation wraps existing metrics functions to provide
+    the TelemetryCollector interface.
+    """
+
+    @contextmanager
+    def trace_context(self, graph: TNFRGraph):
+        """Create trace context for operator execution.
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph being traced.
+
+        Yields
+        ------
+        DefaultTraceContext
+            Context for capturing transitions.
+        """
+        context = DefaultTraceContext(graph)
+        try:
+            yield context
+        finally:
+            # Ensure transitions are saved using the helper method
+            context._save_transitions()
+
+    def compute_coherence(self, graph: TNFRGraph) -> float:
+        """Compute global coherence C(t).
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph to measure.
+
+        Returns
+        -------
+        float
+            Coherence value in [0, 1].
+        """
+        from ..metrics.common import compute_coherence
+
+        return compute_coherence(graph)
+
+    def compute_sense_index(self, graph: TNFRGraph) -> dict[str, Any]:
+        """Compute sense index Si.
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph to measure.
+
+        Returns
+        -------
+        dict
+            Sense index metrics.
+        """
+        from ..metrics.sense_index import compute_Si
+
+        result = compute_Si(graph)
+
+        # Ensure we return a dict
+        if isinstance(result, dict):
+            return result
+        else:
+            # If compute_Si returns a scalar, wrap it
+            return {"Si": result}

tnfr/core/interfaces.py

@@ -0,0 +1,279 @@
+"""Core interfaces defining the TNFR architectural contracts.
+
+This module defines Protocol-based interfaces that separate responsibilities
+across the TNFR engine layers. Each protocol specifies the minimal contract
+required for a component to participate in the structural orchestration without
+imposing implementation details.
+
+Protocols (Interfaces)
+----------------------
+OperatorRegistry
+    Maps operator tokens to structural operator implementations.
+ValidationService
+    Validates sequences and graph states against TNFR invariants.
+DynamicsEngine
+    Computes ΔNFR, integrates the nodal equation, and coordinates phase.
+TelemetryCollector
+    Captures coherence metrics, sense index, and structural traces.
+
+Notes
+-----
+These interfaces use :class:`typing.Protocol` to enable duck typing and
+structural subtyping. Implementations do not need to explicitly inherit from
+these protocols; they need only provide the specified methods with compatible
+signatures.
+
+Examples
+--------
+Custom validation service implementing ValidationService protocol:
+
+>>> class StrictValidator:
+...     def validate_sequence(self, sequence):
+...         # Custom validation logic
+...         pass
+...     def validate_graph_state(self, graph):
+...         # Custom graph validation
+...         pass
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from ..types import TNFRGraph, NodeId
+    from ..operators.definitions import Operator
+
+__all__ = (
+    "OperatorRegistry",
+    "ValidationService",
+    "DynamicsEngine",
+    "TelemetryCollector",
+    "TraceContext",
+)
+
+
+@runtime_checkable
+class OperatorRegistry(Protocol):
+    """Interface for registering and retrieving structural operators.
+
+    The operator registry maintains the mapping between operator tokens
+    (strings or Glyph codes) and their concrete implementations. It ensures
+    that only canonical operators are accessible during sequence execution.
+    """
+
+    def get_operator(self, token: str) -> Operator:
+        """Retrieve operator implementation for the given token.
+
+        Parameters
+        ----------
+        token : str
+            Operator identifier (e.g., "emission", "coherence").
+
+        Returns
+        -------
+        Operator
+            The structural operator implementation.
+
+        Raises
+        ------
+        KeyError
+            When the token does not map to a registered operator.
+        """
+        ...
+
+    def register_operator(self, operator: Operator) -> None:
+        """Register a structural operator implementation.
+
+        Parameters
+        ----------
+        operator : Operator
+            The operator to register in the global registry.
+        """
+        ...
+
+
+@runtime_checkable
+class ValidationService(Protocol):
+    """Interface for validating sequences and graph states.
+
+    The validation service guards TNFR invariants by checking operator
+    sequences against grammar rules and ensuring graph states remain within
+    canonical bounds (νf, phase, ΔNFR ranges).
+    """
+
+    def validate_sequence(self, sequence: list[str]) -> None:
+        """Validate an operator sequence against TNFR grammar.
+
+        Parameters
+        ----------
+        sequence : list of str
+            Operator tokens to validate as a trajectory.
+
+        Raises
+        ------
+        ValueError
+            When the sequence violates TNFR grammar rules or operator closure.
+        """
+        ...
+
+    def validate_graph_state(self, graph: TNFRGraph) -> None:
+        """Validate graph state against structural invariants.
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph whose node attributes (EPI, νf, θ, ΔNFR) are validated.
+
+        Raises
+        ------
+        ValueError
+            When node attributes violate canonical bounds or type constraints.
+        """
+        ...
+
+
+@runtime_checkable
+class DynamicsEngine(Protocol):
+    """Interface for computing ΔNFR and integrating the nodal equation.
+
+    The dynamics engine orchestrates the temporal evolution of nodes by
+    computing internal reorganization gradients (ΔNFR), integrating the
+    nodal equation ∂EPI/∂t = νf · ΔNFR(t), and coordinating phase coupling
+    across the network.
+    """
+
+    def update_delta_nfr(self, graph: TNFRGraph) -> None:
+        """Compute and update ΔNFR for all nodes in the graph.
+
+        This method implements the canonical ΔNFR computation using
+        configured hooks (e.g., dnfr_epi_vf_mixed, dnfr_laplacian).
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph whose node ΔNFR attributes are updated.
+        """
+        ...
+
+    def integrate_nodal_equation(self, graph: TNFRGraph) -> None:
+        """Integrate the nodal equation to update EPI, νf, and phase.
+
+        This method applies the canonical integrator to advance EPI based on
+        the structural frequency and ΔNFR gradient, while optionally
+        adapting νf and coordinating phase synchrony.
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph whose nodes evolve according to ∂EPI/∂t = νf · ΔNFR(t).
+        """
+        ...
+
+    def coordinate_phase_coupling(self, graph: TNFRGraph) -> None:
+        """Coordinate phase synchronization across coupled nodes.
+
+        This method ensures that phase relationships between connected nodes
+        respect resonance conditions and structural coupling strength.
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph whose phase attributes are coordinated.
+        """
+        ...
+
+
+@runtime_checkable
+class TraceContext(Protocol):
+    """Interface for trace context managers used by telemetry collectors."""
+
+    def capture_state(self, graph: TNFRGraph) -> dict[str, Any]:
+        """Capture current graph state for telemetry.
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph whose state is captured.
+
+        Returns
+        -------
+        dict
+            State snapshot including coherence, phase, νf distributions.
+        """
+        ...
+
+    def record_transition(
+        self,
+        operator_token: str,
+        pre_state: dict[str, Any],
+        post_state: dict[str, Any],
+    ) -> None:
+        """Record operator transition in telemetry traces.
+
+        Parameters
+        ----------
+        operator_token : str
+            The operator that caused the transition.
+        pre_state : dict
+            State before operator application.
+        post_state : dict
+            State after operator application.
+        """
+        ...
+
+
+@runtime_checkable
+class TelemetryCollector(Protocol):
+    """Interface for collecting telemetry and structural traces.
+
+    The telemetry collector measures coherence (C(t)), sense index (Si),
+    and captures structural traces documenting how operators reorganize
+    the network over time.
+    """
+
+    def trace_context(self, graph: TNFRGraph) -> TraceContext:
+        """Create a trace context for capturing operator effects.
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph being traced.
+
+        Returns
+        -------
+        TraceContext
+            Context manager for capturing state transitions.
+        """
+        ...
+
+    def compute_coherence(self, graph: TNFRGraph) -> float:
+        """Compute total coherence C(t) across the network.
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph whose coherence is measured.
+
+        Returns
+        -------
+        float
+            Global coherence value C(t) ∈ [0, 1], where higher values
+            indicate greater structural stability.
+        """
+        ...
+
+    def compute_sense_index(self, graph: TNFRGraph) -> dict[str, Any]:
+        """Compute sense index (Si) measuring reorganization capacity.
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph whose sense index is computed.
+
+        Returns
+        -------
+        dict
+            Sense index metrics including total Si and per-node contributions.
+        """
+        ...