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

tnfr/dynamics/learning.py

@@ -0,0 +1,310 @@
+"""Adaptive learning system for TNFR.
+
+This module implements high-level adaptive learning dynamics combining
+emission (AL) and self-organization (T'HOL) operators into canonical
+learning cycles. All functionality reuses existing TNFR infrastructure.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+from ..alias import get_attr
+from ..constants.aliases import ALIAS_EPI, ALIAS_DNFR
+from ..operators.definitions import (
+    Coherence,
+    Contraction,
+    Dissonance,
+    Emission,
+    Mutation,
+    Operator,
+    Reception,
+    Recursivity,
+    Resonance,
+    SelfOrganization,
+    Silence,
+    Transition,
+)
+from ..structural import run_sequence
+from ..types import TNFRGraph
+
+__all__ = ["AdaptiveLearningSystem"]
+
+
+class AdaptiveLearningSystem:
+    """System for adaptive learning using TNFR operators.
+
+    This class orchestrates adaptive learning cycles combining emission (AL),
+    reception (EN), self-organization (T'HOL), and stabilization (IL) operators.
+    It implements the canonical learning sequences defined in the TNFR manual.
+
+    All methods reuse existing operators and run_sequence infrastructure.
+
+    Parameters
+    ----------
+    graph : TNFRGraph
+        Graph containing the learning node.
+    node : Any
+        Node identifier for the learning entity.
+    learning_rate : float, default=1.0
+        Sensitivity to dissonance that triggers reorganization. Higher values
+        make the system more responsive to novel stimuli.
+    consolidation_threshold : float, default=0.7
+        ΔNFR threshold below which the system stabilizes. Lower values mean
+        earlier consolidation.
+
+    Attributes
+    ----------
+    G : TNFRGraph
+        Reference to the graph.
+    node : Any
+        Node being managed.
+    learning_rate : float
+        Configured learning sensitivity.
+    consolidation_threshold : float
+        Configured consolidation trigger.
+
+    Examples
+    --------
+    >>> from tnfr.structural import create_nfr
+    >>> from tnfr.dynamics.learning import AdaptiveLearningSystem
+    >>> G, node = create_nfr("learner", epi=0.3, vf=1.0)
+    >>> system = AdaptiveLearningSystem(G, node, learning_rate=0.8)
+    >>> # Basic learning cycle
+    >>> system.learn_from_input(stimulus=0.5, consolidate=True)
+    >>> # Consolidate memory
+    >>> system.consolidate_memory()
+    """
+
+    def __init__(
+        self,
+        graph: TNFRGraph,
+        node: Any,
+        learning_rate: float = 1.0,
+        consolidation_threshold: float = 0.7,
+    ) -> None:
+        """Initialize adaptive learning system."""
+        self.G = graph
+        self.node = node
+        self.learning_rate = learning_rate
+        self.consolidation_threshold = consolidation_threshold
+
+    def learn_from_input(
+        self,
+        stimulus: float,
+        consolidate: bool = True,
+    ) -> None:
+        """Execute learning cycle from external stimulus.
+
+        Implements canonical learning sequence following TNFR grammar:
+        - AL (Emission): Activate learning readiness
+        - EN (Reception): Receive stimulus
+        - IL (Coherence): Stabilize before dissonance (grammar requirement)
+        - OZ (Dissonance): If stimulus is dissonant
+        - T'HOL (SelfOrganization): Reorganize if needed
+        - NUL (Contraction): Close T'HOL block (grammar requirement)
+        - IL (Coherence): Consolidate if requested
+        - SHA (Silence): End sequence properly
+
+        Parameters
+        ----------
+        stimulus : float
+            External input value to learn from.
+        consolidate : bool, default=True
+            Whether to stabilize after learning.
+
+        Notes
+        -----
+        Reuses run_sequence and existing operators for all transformations.
+        Dissonance detection uses current EPI from node attributes.
+        Sequences must follow TNFR grammar rules including T'HOL closure.
+
+        **Grammar compliance:**
+
+        - T'HOL (SelfOrganization) blocks require closure with NUL (Contraction) or SHA (Silence)
+        - Dissonance should be preceded by stabilization (Coherence)
+        """
+        sequence: list[Operator] = [Emission(), Reception()]
+
+        # Check if stimulus is dissonant (requires reorganization)
+        if self._is_dissonant(stimulus):
+            # For dissonant input, follow grammar-compliant reorganization
+            # T'HOL block must be closed with SILENCE or CONTRACTION
+            sequence.extend(
+                [
+                    Coherence(),  # Stabilize before dissonance (grammar)
+                    Dissonance(),  # Introduce controlled instability
+                    SelfOrganization(),  # Autonomous reorganization
+                    Silence(),  # Close T'HOL block and end sequence (grammar requirement)
+                ]
+            )
+        else:
+            # Non-dissonant: simpler path with optional consolidation
+            if consolidate:
+                sequence.append(Coherence())
+            sequence.append(Silence())  # Always end with terminal operator
+
+        # Execute using canonical run_sequence
+        run_sequence(self.G, self.node, sequence)
+
+    def _is_dissonant(self, stimulus: float) -> bool:
+        """Determine if stimulus requires reorganization.
+
+        Parameters
+        ----------
+        stimulus : float
+            External stimulus value.
+
+        Returns
+        -------
+        bool
+            True if stimulus differs significantly from current EPI.
+
+        Notes
+        -----
+        Reuses get_attr for accessing node EPI canonically.
+        """
+        current_epi = float(get_attr(self.G.nodes[self.node], ALIAS_EPI, 0.0))
+        return abs(stimulus - current_epi) > self.learning_rate
+
+    def consolidate_memory(self) -> None:
+        """Execute memory consolidation cycle.
+
+        Implements canonical consolidation sequence:
+        - AL (Emission): Reactivate for consolidation
+        - EN (Reception): Integrate memory
+        - IL (Coherence): Stabilize structure
+        - REMESH (Recursivity): Recursive consolidation
+
+        Notes
+        -----
+        Reuses run_sequence and existing operators for consolidation.
+        This sequence is useful for post-learning stabilization.
+        Follows TNFR grammar: must start with emission and include reception->coherence.
+        """
+        sequence = [Emission(), Reception(), Coherence(), Recursivity()]
+        run_sequence(self.G, self.node, sequence)
+
+    def adaptive_cycle(self, num_iterations: int = 10) -> None:
+        """Execute full adaptive learning cycle with exploration.
+
+        Implements iterative learning with conditional stabilization:
+        - Each iteration: AL -> EN -> IL -> THOL with closure
+        - Stabilizes with SILENCE if ΔNFR below threshold
+        - Continues exploring with DISSONANCE if ΔNFR above threshold
+
+        Parameters
+        ----------
+        num_iterations : int, default=10
+            Number of learning iterations to execute.
+
+        Notes
+        -----
+        Reuses operators and _should_stabilize logic for adaptive behavior.
+        Each iteration applies a grammar-compliant sequence.
+        T'HOL requires proper context (AL -> EN -> IL) and closure (SILENCE/CONTRACTION).
+        """
+        for _ in range(num_iterations):
+            # Grammar-compliant activation sequence
+            Emission()(self.G, self.node)
+            Reception()(self.G, self.node)
+            Coherence()(self.G, self.node)
+
+            # Self-organization: autonomous reorganization
+            SelfOrganization()(self.G, self.node)
+
+            # T'HOL requires closure
+            Silence()(self.G, self.node)
+
+    def _should_stabilize(self) -> bool:
+        """Decide whether to stabilize based on current ΔNFR.
+
+        Returns
+        -------
+        bool
+            True if ΔNFR is below consolidation threshold.
+
+        Notes
+        -----
+        Reuses get_attr for accessing ΔNFR canonically.
+        Low ΔNFR indicates structure is settling and ready for consolidation.
+        """
+        dnfr = abs(float(get_attr(self.G.nodes[self.node], ALIAS_DNFR, 0.0)))
+        return dnfr < self.consolidation_threshold
+
+    def deep_learning_cycle(self) -> None:
+        """Execute deep learning with crisis and reorganization.
+
+        Implements canonical deep learning sequence:
+        AL -> EN -> IL -> OZ -> THOL -> IL -> (SHA or NUL)
+
+        The final operator (SHA/SILENCE or NUL/CONTRACTION) is selected by
+        the TNFR grammar based on structural conditions:
+        - SHA (SILENCE) if Si >= si_high (high sense index)
+        - NUL (CONTRACTION) if Si < si_high (low sense index)
+
+        This is canonical THOL closure behavior per TNFR sec.4.
+
+        Notes
+        -----
+        Reuses run_sequence with predefined deep learning pattern.
+        Grammar may adaptively select the appropriate THOL closure.
+        """
+        sequence = [
+            Emission(),
+            Reception(),
+            Coherence(),
+            Dissonance(),
+            SelfOrganization(),
+            Coherence(),
+            Silence(),  # Grammar may replace with Contraction if Si < si_high
+        ]
+        run_sequence(self.G, self.node, sequence)
+
+    def exploratory_learning_cycle(self) -> None:
+        """Execute exploratory learning with enhanced propagation.
+
+        Implements canonical exploratory learning sequence:
+        AL -> EN -> IL -> OZ -> THOL -> IL -> SHA
+
+        After self-organization, coherence stabilizes and closes T'HOL,
+        then silence terminates.
+
+        Notes
+        -----
+        Reuses run_sequence with predefined exploratory pattern.
+        This is similar to deep_learning_cycle but focuses on consolidation.
+        Supports operational fractality (nested THOL allowed per sec.3.7).
+        """
+        sequence = [
+            Emission(),
+            Reception(),
+            Coherence(),
+            Dissonance(),
+            SelfOrganization(),
+            Coherence(),  # Stabilize and close T'HOL
+            Silence(),  # Terminal operator
+        ]
+        run_sequence(self.G, self.node, sequence)
+
+    def adaptive_mutation_cycle(self) -> None:
+        """Execute transformative learning with mutation.
+
+        Implements canonical adaptive mutation sequence:
+        AL -> EN -> IL -> OZ -> ZHIR -> NAV
+
+        Notes
+        -----
+        Reuses run_sequence with predefined mutation pattern.
+        This represents transformative learning with phase transitions.
+        Follows TNFR grammar: dissonance before mutation, ends with transition.
+        """
+        sequence = [
+            Emission(),
+            Reception(),
+            Coherence(),
+            Dissonance(),
+            Mutation(),
+            Transition(),
+        ]
+        run_sequence(self.G, self.node, sequence)

tnfr/dynamics/learning.pyi

@@ -0,0 +1,33 @@
+"""Type stubs for adaptive learning module."""
+
+from typing import Any
+
+from ..types import TNFRGraph
+
+class AdaptiveLearningSystem:
+    """System for adaptive learning using TNFR operators."""
+
+    G: TNFRGraph
+    node: Any
+    learning_rate: float
+    consolidation_threshold: float
+
+    def __init__(
+        self,
+        graph: TNFRGraph,
+        node: Any,
+        learning_rate: float = ...,
+        consolidation_threshold: float = ...,
+    ) -> None: ...
+    def learn_from_input(
+        self,
+        stimulus: float,
+        consolidate: bool = ...,
+    ) -> None: ...
+    def _is_dissonant(self, stimulus: float) -> bool: ...
+    def consolidate_memory(self) -> None: ...
+    def adaptive_cycle(self, num_iterations: int = ...) -> None: ...
+    def _should_stabilize(self) -> bool: ...
+    def deep_learning_cycle(self) -> None: ...
+    def exploratory_learning_cycle(self) -> None: ...
+    def adaptive_mutation_cycle(self) -> None: ...

tnfr/dynamics/metabolism.py

@@ -0,0 +1,254 @@
+"""Structural metabolism implementation for TNFR.
+
+T'HOL (Self-Organization) as metabolic process: receiving external stimuli,
+reorganizing them autonomously into internal structure, and stabilizing results.
+
+This module implements metabolic cycles that use T'HOL as the engine of
+structural transformation and adaptation.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..types import NodeId, TNFRGraph
+
+from ..alias import get_attr
+from ..constants.aliases import ALIAS_DNFR
+
+__all__ = [
+    "StructuralMetabolism",
+    "digest_stimulus",
+    "adaptive_metabolism",
+    "cascading_reorganization",
+]
+
+
+class StructuralMetabolism:
+    """Implements T'HOL-based structural metabolism cycles.
+
+    T'HOL is not just self-organization - it's **structural metabolism**:
+    the capacity to digest external experience and reorganize it into
+    internal structure without external instruction.
+
+    **Metabolic Characteristics:**
+
+    - **Reception (EN)**: Ingests external stimulus
+    - **Reorganization (THOL)**: Autonomously transforms stimulus to structure
+    - **Stabilization (IL)**: Consolidates new structural configuration
+
+    This creates a complete metabolic cycle: EN → THOL → IL
+
+    Parameters
+    ----------
+    graph : TNFRGraph
+        Graph containing the metabolizing node
+    node : NodeId
+        Identifier of the node performing metabolism
+
+    Attributes
+    ----------
+    G : TNFRGraph
+        Reference to the graph
+    node : NodeId
+        Reference to the node identifier
+    metabolic_rate : float
+        Scaling factor for metabolic intensity (default 1.0)
+
+    Examples
+    --------
+    >>> from tnfr.structural import create_nfr
+    >>> from tnfr.dynamics.metabolism import StructuralMetabolism
+    >>> G, node = create_nfr("cell", epi=0.5, vf=1.0)
+    >>> metabolism = StructuralMetabolism(G, node)
+    >>> # Digest external stimulus
+    >>> metabolism.digest(0.3)  # doctest: +SKIP
+    >>> # Result: stimulus integrated and reorganized structurally
+    """
+
+    def __init__(self, graph: TNFRGraph, node: NodeId) -> None:
+        """Initialize structural metabolism for a node.
+
+        Parameters
+        ----------
+        graph : TNFRGraph
+            Graph containing the node
+        node : NodeId
+            Node identifier
+        """
+        self.G = graph
+        self.node = node
+        self.metabolic_rate = 1.0
+
+    def digest(self, tau: float = 0.08) -> None:
+        """Metabolize external stimulus through complete metabolic cycle.
+
+        Implements the canonical metabolic sequence: EN → THOL → IL
+
+        1. Reception (EN): Receives external stimulus from neighbors
+        2. Reorganization (THOL): Autonomously transforms into structure
+        3. Stabilization (IL): Consolidates the result
+
+        Parameters
+        ----------
+        tau : float
+            Bifurcation threshold for THOL (default 0.08)
+
+        Notes
+        -----
+        The metabolic rate modulates the intensity of each operation.
+        Lower tau increases likelihood of bifurcation during reorganization.
+        """
+        from ..operators.definitions import Reception, SelfOrganization, Coherence
+
+        # 1. Receive external stimulus
+        Reception()(self.G, self.node)
+
+        # 2. Reorganize metabolically (T'HOL with controlled bifurcation)
+        SelfOrganization()(self.G, self.node, tau=tau)
+
+        # 3. Stabilize result
+        Coherence()(self.G, self.node)
+
+    def adaptive_metabolism(self, stress_level: float) -> None:
+        """Adapt metabolic response to stress level.
+
+        High stress (dissonance) triggers deeper reorganization with
+        increased bifurcation probability. Low stress allows gentler
+        metabolic cycles.
+
+        Parameters
+        ----------
+        stress_level : float
+            Level of structural stress/dissonance (0.0 to 1.0+)
+            - < 0.5: Moderate stress, gentle reorganization
+            - >= 0.5: High stress, deep reorganization with dissonance
+
+        Notes
+        -----
+        This implements adaptive structural metabolism where the depth
+        of reorganization scales with environmental pressure.
+        """
+        from ..operators.definitions import (
+            Dissonance,
+            SelfOrganization,
+            Coherence,
+        )
+
+        if stress_level >= 0.5:
+            # High stress: dissonance + deep reorganization
+            # Apply operators individually to avoid grammar restrictions
+            Dissonance()(self.G, self.node)  # Introduce controlled instability
+            SelfOrganization()(
+                self.G, self.node, tau=0.08
+            )  # Deep reorganization (likely bifurcates)
+            Coherence()(self.G, self.node)  # Stabilize new configuration
+        else:
+            # Moderate stress: gentle reorganization
+            # Higher tau reduces bifurcation probability
+            SelfOrganization()(self.G, self.node, tau=0.15)
+
+    def cascading_reorganization(self, depth: int = 3) -> None:
+        """Execute recursive T'HOL cascade.
+
+        Applies T'HOL multiple times with progressively decreasing
+        bifurcation thresholds, creating nested structural reorganization.
+
+        This implements operational fractality: reorganization at multiple
+        scales simultaneously.
+
+        Parameters
+        ----------
+        depth : int
+            Number of cascade levels (default 3)
+
+        Notes
+        -----
+        Each level uses tau = 0.1 * (0.8 ^ level), creating progressively
+        more sensitive bifurcation at deeper levels.
+
+        **Warning**: Deep cascades (depth > 5) may create highly complex
+        nested structures. Monitor structural complexity metrics.
+        """
+        from ..operators.definitions import SelfOrganization
+
+        for level in range(depth):
+            # Decreasing threshold: deeper levels bifurcate more easily
+            tau = 0.1 * (0.8**level)
+            SelfOrganization()(self.G, self.node, tau=tau)
+
+
+def digest_stimulus(G: TNFRGraph, node: NodeId, tau: float = 0.08) -> None:
+    """Functional interface for single metabolic cycle.
+
+    Equivalent to `StructuralMetabolism(G, node).digest(tau)`.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph containing the node
+    node : NodeId
+        Node identifier
+    tau : float
+        Bifurcation threshold
+
+    Examples
+    --------
+    >>> from tnfr.structural import create_nfr
+    >>> from tnfr.dynamics.metabolism import digest_stimulus
+    >>> G, node = create_nfr("neuron", epi=0.4, vf=1.2)
+    >>> digest_stimulus(G, node, tau=0.1)  # doctest: +SKIP
+    """
+    metabolism = StructuralMetabolism(G, node)
+    metabolism.digest(tau)
+
+
+def adaptive_metabolism(G: TNFRGraph, node: NodeId, stress: float) -> None:
+    """Functional interface for adaptive metabolic response.
+
+    Equivalent to `StructuralMetabolism(G, node).adaptive_metabolism(stress)`.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph containing the node
+    node : NodeId
+        Node identifier
+    stress : float
+        Stress level (0.0 to 1.0+)
+
+    Examples
+    --------
+    >>> from tnfr.structural import create_nfr
+    >>> from tnfr.dynamics.metabolism import adaptive_metabolism
+    >>> G, node = create_nfr("organism", epi=0.6, vf=1.0)
+    >>> adaptive_metabolism(G, node, stress=0.7)  # doctest: +SKIP
+    """
+    metabolism = StructuralMetabolism(G, node)
+    metabolism.adaptive_metabolism(stress)
+
+
+def cascading_reorganization(G: TNFRGraph, node: NodeId, depth: int = 3) -> None:
+    """Functional interface for cascading reorganization.
+
+    Equivalent to `StructuralMetabolism(G, node).cascading_reorganization(depth)`.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph containing the node
+    node : NodeId
+        Node identifier
+    depth : int
+        Cascade depth
+
+    Examples
+    --------
+    >>> from tnfr.structural import create_nfr
+    >>> from tnfr.dynamics.metabolism import cascading_reorganization
+    >>> G, node = create_nfr("system", epi=0.7, vf=1.1)
+    >>> cascading_reorganization(G, node, depth=3)  # doctest: +SKIP
+    """
+    metabolism = StructuralMetabolism(G, node)
+    metabolism.cascading_reorganization(depth)