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

tnfr/services/orchestrator.py

@@ -0,0 +1,325 @@
+"""Service orchestration layer for TNFR engine.
+
+This module provides the TNFROrchestrator service that coordinates execution
+of operator sequences with clear separation of responsibilities:
+
+1. Validation (delegated to ValidationService)
+2. Execution (coordinated through OperatorRegistry)
+3. Dynamics (delegated to DynamicsEngine)
+4. Telemetry (delegated to TelemetryCollector)
+
+The orchestrator maintains the nodal equation ∂EPI/∂t = νf · ΔNFR(t) while
+ensuring that each layer operates independently and can be replaced without
+affecting the others.
+
+Examples
+--------
+Execute a sequence with default services:
+
+>>> from tnfr.core.container import TNFRContainer
+>>> from tnfr.services.orchestrator import TNFROrchestrator
+>>> from tnfr.structural import create_nfr
+>>>
+>>> container = TNFRContainer.create_default()
+>>> orchestrator = TNFROrchestrator.from_container(container)
+>>> G, node = create_nfr("seed", epi=1.0, vf=2.0)
+>>> orchestrator.execute_sequence(G, node, ["emission", "coherence"])
+
+Execute with custom services:
+
+>>> class CustomValidator:
+...     def validate_sequence(self, seq):
+...         print(f"Validating {seq}")
+...     def validate_graph_state(self, graph):
+...         pass
+>>>
+>>> container = TNFRContainer()
+>>> container.register_singleton(ValidationService, CustomValidator())
+>>> # ... register other services
+>>> orchestrator = TNFROrchestrator.from_container(container)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Iterable
+
+if TYPE_CHECKING:
+    from ..core.interfaces import (
+        DynamicsEngine,
+        OperatorRegistry,
+        TelemetryCollector,
+        ValidationService,
+    )
+    from ..types import NodeId, TNFRGraph
+    from ..operators.definitions import Operator
+
+__all__ = ("TNFROrchestrator",)
+
+
+class TNFROrchestrator:
+    """Orchestrates TNFR sequence execution with separated responsibilities.
+
+    The orchestrator coordinates validation, execution, dynamics updates, and
+    telemetry collection without directly implementing any of these concerns.
+    Each responsibility is delegated to a specialized service, enabling
+    flexible composition and testing.
+
+    Attributes
+    ----------
+    _validator : ValidationService
+        Service for validating sequences and graph states.
+    _registry : OperatorRegistry
+        Service for retrieving operator implementations.
+    _dynamics : DynamicsEngine
+        Service for computing ΔNFR and integrating nodal equation.
+    _telemetry : TelemetryCollector
+        Service for collecting metrics and traces.
+
+    Examples
+    --------
+    Create orchestrator with dependency injection:
+
+    >>> from tnfr.core.container import TNFRContainer
+    >>> container = TNFRContainer.create_default()
+    >>> orch = TNFROrchestrator.from_container(container)
+
+    Execute a validated sequence:
+
+    >>> from tnfr.structural import create_nfr
+    >>> G, node = create_nfr("test", epi=1.0, vf=1.0)
+    >>> orch.execute_sequence(G, node, ["emission", "coherence"])
+    """
+
+    def __init__(
+        self,
+        validator: ValidationService,
+        registry: OperatorRegistry,
+        dynamics: DynamicsEngine,
+        telemetry: TelemetryCollector,
+    ):
+        """Initialize orchestrator with injected services.
+
+        Parameters
+        ----------
+        validator : ValidationService
+            Service for validation.
+        registry : OperatorRegistry
+            Service for operator lookup.
+        dynamics : DynamicsEngine
+            Service for dynamics computation.
+        telemetry : TelemetryCollector
+            Service for telemetry collection.
+        """
+        self._validator = validator
+        self._registry = registry
+        self._dynamics = dynamics
+        self._telemetry = telemetry
+
+    @classmethod
+    def from_container(cls, container) -> TNFROrchestrator:
+        """Create orchestrator from dependency injection container.
+
+        Parameters
+        ----------
+        container : TNFRContainer
+            Container with registered services.
+
+        Returns
+        -------
+        TNFROrchestrator
+            Configured orchestrator instance.
+
+        Examples
+        --------
+        >>> from tnfr.core.container import TNFRContainer
+        >>> container = TNFRContainer.create_default()
+        >>> orch = TNFROrchestrator.from_container(container)
+        """
+        from ..core.interfaces import (
+            DynamicsEngine,
+            OperatorRegistry,
+            TelemetryCollector,
+            ValidationService,
+        )
+
+        return cls(
+            validator=container.get(ValidationService),
+            registry=container.get(OperatorRegistry),
+            dynamics=container.get(DynamicsEngine),
+            telemetry=container.get(TelemetryCollector),
+        )
+
+    def execute_sequence(
+        self,
+        graph: TNFRGraph,
+        node: NodeId,
+        sequence: Iterable[str | Operator],
+        *,
+        enable_telemetry: bool = False,
+    ) -> None:
+        """Execute operator sequence with separated responsibilities.
+
+        This method coordinates the full execution pipeline:
+        1. Validate sequence against TNFR grammar
+        2. Convert tokens to operator instances
+        3. Apply each operator with telemetry (optional)
+        4. Update ΔNFR after each operator
+        5. Integrate nodal equation
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph containing the target node.
+        node : NodeId
+            Node identifier to receive operators.
+        sequence : iterable of str or Operator
+            Operator tokens or instances to apply.
+        enable_telemetry : bool, optional
+            Whether to capture detailed telemetry traces. Default is False.
+
+        Raises
+        ------
+        ValueError
+            When sequence validation fails or operators are unknown.
+
+        Examples
+        --------
+        Execute with string tokens:
+
+        >>> from tnfr.structural import create_nfr
+        >>> G, n = create_nfr("node1", epi=1.0)
+        >>> orch = TNFROrchestrator.from_container(container)
+        >>> orch.execute_sequence(G, n, ["emission", "coherence"])
+
+        Execute with telemetry enabled:
+
+        >>> orch.execute_sequence(G, n, ["emission"], enable_telemetry=True)
+        >>> # Check transitions in G.graph["_trace_transitions"]
+        """
+        # Convert sequence to list and extract operator tokens
+        ops_list = list(sequence)
+
+        # Separate tokens from Operator instances
+        tokens = []
+        operator_instances = []
+        for item in ops_list:
+            if isinstance(item, str):
+                tokens.append(item)
+                operator_instances.append(None)  # Will resolve later
+            else:
+                # Assume it's an Operator instance
+                tokens.append(item.name)
+                operator_instances.append(item)
+
+        # Step 1: Validation (delegated to ValidationService)
+        if tokens:  # Skip validation for empty sequences
+            self._validator.validate_sequence(tokens)
+
+        # Step 2: Execution with optional telemetry
+        if enable_telemetry:
+            with self._telemetry.trace_context(graph) as tracer:
+                self._execute_with_telemetry(
+                    graph, node, tokens, operator_instances, tracer
+                )
+        else:
+            self._execute_without_telemetry(graph, node, tokens, operator_instances)
+
+    def _execute_with_telemetry(
+        self, graph, node, tokens, operator_instances, tracer
+    ) -> None:
+        """Execute sequence with telemetry capture."""
+        for token, op_instance in zip(tokens, operator_instances):
+            # Pre-execution: capture state
+            pre_state = tracer.capture_state(graph)
+
+            # Execution: apply operator
+            if op_instance is None:
+                operator_cls = self._registry.get_operator(token)
+                operator_cls()(graph, node)  # Instantiate and call
+            else:
+                op_instance(graph, node)
+
+            # Post-execution: update dynamics
+            self._dynamics.update_delta_nfr(graph)
+
+            # Telemetry: record transition
+            post_state = tracer.capture_state(graph)
+            tracer.record_transition(token, pre_state, post_state)
+
+    def _execute_without_telemetry(
+        self, graph, node, tokens, operator_instances
+    ) -> None:
+        """Execute sequence without telemetry overhead."""
+        for token, op_instance in zip(tokens, operator_instances):
+            # Execution: apply operator
+            if op_instance is None:
+                operator_cls = self._registry.get_operator(token)
+                operator_cls()(graph, node)  # Instantiate and call
+            else:
+                op_instance(graph, node)
+
+            # Post-execution: update dynamics
+            self._dynamics.update_delta_nfr(graph)
+
+    def validate_only(self, sequence: list[str]) -> None:
+        """Validate sequence without executing.
+
+        This method is useful for pre-flight checks before committing to
+        execution.
+
+        Parameters
+        ----------
+        sequence : list of str
+            Operator tokens to validate.
+
+        Raises
+        ------
+        ValueError
+            When sequence violates grammar rules.
+
+        Examples
+        --------
+        >>> orch.validate_only(["emission", "coherence"])  # OK
+        >>> orch.validate_only(["unknown_op"])  # Raises ValueError
+        """
+        self._validator.validate_sequence(sequence)
+
+    def get_coherence(self, graph: TNFRGraph) -> float:
+        """Get current coherence C(t) from telemetry service.
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph to measure.
+
+        Returns
+        -------
+        float
+            Current coherence value.
+
+        Examples
+        --------
+        >>> coherence = orch.get_coherence(G)
+        >>> print(f"C(t) = {coherence:.3f}")
+        """
+        return self._telemetry.compute_coherence(graph)
+
+    def get_sense_index(self, graph: TNFRGraph) -> dict:
+        """Get sense index Si from telemetry service.
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph to measure.
+
+        Returns
+        -------
+        dict
+            Sense index metrics.
+
+        Examples
+        --------
+        >>> si_metrics = orch.get_sense_index(G)
+        >>> print(f"Si = {si_metrics['Si']:.3f}")
+        """
+        return self._telemetry.compute_sense_index(graph)

tnfr/sparse/__init__.py

@@ -0,0 +1,39 @@
+"""Sparse representations for memory-efficient TNFR networks.
+
+This module provides memory-optimized graph representations that reduce
+per-node memory footprint from ~8.5KB to <1KB while preserving all TNFR
+canonical invariants.
+
+Canonical Invariants Preserved
+------------------------------
+1. Nodal equation: ∂EPI/∂t = νf · ΔNFR(t)
+2. Sparse storage: only non-default values stored
+3. Cache coherence: intelligent caching for repeated computations
+4. Deterministic computation: same inputs yield same outputs
+
+Examples
+--------
+Create a sparse graph with 10,000 nodes:
+
+>>> from tnfr.sparse import SparseTNFRGraph
+>>> graph = SparseTNFRGraph(node_count=10000, expected_density=0.1)
+>>> footprint = graph.memory_footprint()
+>>> print(f"Memory per node: {footprint.per_node_kb:.2f} KB")  # doctest: +SKIP
+Memory per node: 0.85 KB
+"""
+
+from __future__ import annotations
+
+from .representations import (
+    CompactAttributeStore,
+    MemoryReport,
+    SparseCache,
+    SparseTNFRGraph,
+)
+
+__all__ = [
+    "SparseTNFRGraph",
+    "CompactAttributeStore",
+    "MemoryReport",
+    "SparseCache",
+]