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

tnfr/rng.py

@@ -0,0 +1,178 @@
+"""Deterministic RNG helpers."""
+
+from __future__ import annotations
+
+import hashlib
+import random
+import struct
+from typing import Any, cast
+
+from cachetools import cached  # type: ignore[import-untyped]
+
+from .constants import DEFAULTS, get_param
+from .locking import get_lock
+from .types import GraphLike, TNFRGraph
+from .utils import (
+    ScopedCounterCache,
+    _SeedHashCache,
+    build_cache_manager,
+    get_graph,
+)
+
+MASK64 = 0xFFFFFFFFFFFFFFFF
+
+_RNG_LOCK = get_lock("rng")
+_DEFAULT_CACHE_MAXSIZE = int(DEFAULTS.get("JITTER_CACHE_SIZE", 128))
+_CACHE_MAXSIZE = _DEFAULT_CACHE_MAXSIZE
+_CACHE_LOCKED = False
+
+_RNG_CACHE_MANAGER = build_cache_manager(default_capacity=_DEFAULT_CACHE_MAXSIZE)
+
+_seed_hash_cache = _SeedHashCache(
+    manager=_RNG_CACHE_MANAGER,
+    default_maxsize=_DEFAULT_CACHE_MAXSIZE,
+)
+
+
+def _compute_seed_hash(seed_int: int, key_int: int) -> int:
+    seed_bytes = struct.pack(
+        ">QQ",
+        seed_int & MASK64,
+        key_int & MASK64,
+    )
+    return int.from_bytes(hashlib.blake2b(seed_bytes, digest_size=8).digest(), "big")
+
+
+@cached(cache=_seed_hash_cache, lock=_RNG_LOCK)
+def _cached_seed_hash(seed_int: int, key_int: int) -> int:
+    return _compute_seed_hash(seed_int, key_int)
+
+
+def seed_hash(seed_int: int, key_int: int) -> int:
+    """Return a 64-bit hash derived from ``seed_int`` and ``key_int``."""
+
+    if _CACHE_MAXSIZE <= 0 or not _seed_hash_cache.enabled:
+        return _compute_seed_hash(seed_int, key_int)
+    return _cached_seed_hash(seed_int, key_int)
+
+
+seed_hash.cache_clear = cast(Any, _cached_seed_hash).cache_clear  # type: ignore[attr-defined]
+seed_hash.cache = _seed_hash_cache  # type: ignore[attr-defined]
+
+
+def _sync_cache_size(G: TNFRGraph | GraphLike | None) -> None:
+    """Synchronise cache size with ``G`` when needed."""
+
+    global _CACHE_MAXSIZE
+    if G is None or _CACHE_LOCKED:
+        return
+    size = get_cache_maxsize(G)
+    with _RNG_LOCK:
+        if size != _seed_hash_cache.maxsize:
+            _seed_hash_cache.configure(size)
+            _CACHE_MAXSIZE = _seed_hash_cache.maxsize
+
+
+def make_rng(
+    seed: int, key: int, G: TNFRGraph | GraphLike | None = None
+) -> random.Random:
+    """Create a reproducible RNG instance from seed and key.
+
+    This factory constructs a deterministic :class:`random.Random` generator
+    by hashing the seed and key together. The hash result is cached for
+    performance when the same (seed, key) pair is requested repeatedly.
+
+    Parameters
+    ----------
+    seed : int
+        Base random seed for the generator. Must be an integer.
+    key : int
+        Key used to derive a unique hash with the seed. Multiple keys
+        allow independent RNG streams from the same base seed.
+    G : TNFRGraph | GraphLike | None, optional
+        Graph containing JITTER_CACHE_SIZE parameter. When provided, the
+        internal cache size is synchronized with the graph configuration.
+
+    Returns
+    -------
+    random.Random
+        Deterministic random number generator seeded with hash(seed, key).
+
+    Notes
+    -----
+    The same (seed, key) pair always produces the same generator state,
+    ensuring reproducibility across TNFR simulations. Cache synchronization
+    with ``G`` allows adaptive caching based on simulation requirements.
+    """
+    _sync_cache_size(G)
+    seed_int = int(seed)
+    key_int = int(key)
+    return random.Random(seed_hash(seed_int, key_int))
+
+
+def clear_rng_cache() -> None:
+    """Clear cached seed hashes."""
+    if _seed_hash_cache.maxsize <= 0 or not _seed_hash_cache.enabled:
+        return
+    seed_hash.cache_clear()  # type: ignore[attr-defined]
+
+
+def get_cache_maxsize(G: TNFRGraph | GraphLike) -> int:
+    """Return RNG cache maximum size for ``G``."""
+    return int(get_param(G, "JITTER_CACHE_SIZE"))
+
+
+def cache_enabled(G: TNFRGraph | GraphLike | None = None) -> bool:
+    """Return ``True`` if RNG caching is enabled.
+
+    When ``G`` is provided, the cache size is synchronised with
+    ``JITTER_CACHE_SIZE`` stored in ``G``.
+    """
+    # Only synchronise the cache size with ``G`` when caching is enabled.  This
+    # preserves explicit calls to :func:`set_cache_maxsize(0)` which are used in
+    # tests to temporarily disable caching regardless of graph defaults.
+    if _seed_hash_cache.maxsize > 0:
+        _sync_cache_size(G)
+    return _seed_hash_cache.maxsize > 0
+
+
+def base_seed(G: TNFRGraph | GraphLike) -> int:
+    """Return base RNG seed stored in ``G.graph``."""
+    graph = get_graph(G)
+    return int(graph.get("RANDOM_SEED", 0))
+
+
+def _rng_for_step(seed: int, step: int) -> random.Random:
+    """Return deterministic RNG for a simulation ``step``."""
+
+    return make_rng(seed, step)
+
+
+def set_cache_maxsize(size: int) -> None:
+    """Update RNG cache maximum size.
+
+    ``size`` must be a non-negative integer; ``0`` disables caching.
+    Changing the cache size resets any cached seed hashes.
+    If caching is disabled, ``clear_rng_cache`` has no effect.
+    """
+
+    global _CACHE_MAXSIZE, _CACHE_LOCKED
+    new_size = int(size)
+    if new_size < 0:
+        raise ValueError("size must be non-negative")
+    with _RNG_LOCK:
+        _seed_hash_cache.configure(new_size)
+        _CACHE_MAXSIZE = _seed_hash_cache.maxsize
+    _CACHE_LOCKED = new_size != _DEFAULT_CACHE_MAXSIZE
+
+
+__all__ = (
+    "seed_hash",
+    "make_rng",
+    "get_cache_maxsize",
+    "set_cache_maxsize",
+    "base_seed",
+    "cache_enabled",
+    "clear_rng_cache",
+    "ScopedCounterCache",
+)

tnfr/rng.pyi

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import random
+from .types import GraphLike, TNFRGraph
+from .utils import ScopedCounterCache as ScopedCounterCache
+
+__all__ = [
+    "seed_hash",
+    "make_rng",
+    "get_cache_maxsize",
+    "set_cache_maxsize",
+    "base_seed",
+    "cache_enabled",
+    "clear_rng_cache",
+    "ScopedCounterCache",
+]
+
+def seed_hash(seed_int: int, key_int: int) -> int: ...
+def make_rng(
+    seed: int, key: int, G: TNFRGraph | GraphLike | None = None
+) -> random.Random: ...
+def clear_rng_cache() -> None: ...
+def get_cache_maxsize(G: TNFRGraph | GraphLike) -> int: ...
+def cache_enabled(G: TNFRGraph | GraphLike | None = None) -> bool: ...
+def base_seed(G: TNFRGraph | GraphLike) -> int: ...
+def set_cache_maxsize(size: int) -> None: ...

tnfr/schemas/__init__.py

@@ -0,0 +1,8 @@
+"""JSON schema resources bundled with the TNFR engine."""
+
+from __future__ import annotations
+
+__all__ = ["package"]
+
+# Namespace packages need at least one attribute for static analysers.
+package = __name__

tnfr/schemas/grammar.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://tnfr.io/schemas/grammar.json",
+  "title": "TNFR Grammar Configuration",
+  "type": "object",
+  "definitions": {
+    "glyphCode": {
+      "description": "Canonical glyph identifier in uppercase notation.",
+      "type": "string",
+      "pattern": "^[A-Z][A-Z_]*$"
+    },
+    "probability": {
+      "description": "Threshold constrained to the [0, 1] interval.",
+      "type": "number",
+      "minimum": 0.0,
+      "maximum": 1.0
+    },
+    "cfg_soft": {
+      "type": "object",
+      "description": "Soft grammar preferences applied before canonical automaton rules.",
+      "properties": {
+        "window": {
+          "description": "History window inspected to avoid short-term glyph repetitions.",
+          "type": "integer",
+          "minimum": 0
+        },
+        "avoid_repeats": {
+          "description": "Glyph codes that should be substituted when repeated inside the window.",
+          "type": "array",
+          "items": { "$ref": "#/definitions/glyphCode" },
+          "uniqueItems": true
+        },
+        "fallbacks": {
+          "description": "Mapping of glyph codes to their explicit substitution when repetition is detected.",
+          "type": "object",
+          "additionalProperties": { "$ref": "#/definitions/glyphCode" }
+        },
+        "force_dnfr": {
+          "description": "Minimum |ΔNFR| normalised score that bypasses soft filtering.",
+          "$ref": "#/definitions/probability"
+        },
+        "force_accel": {
+          "description": "Minimum acceleration normalised score that bypasses soft filtering.",
+          "$ref": "#/definitions/probability"
+        }
+      },
+      "additionalProperties": true
+    },
+    "cfg_canon": {
+      "type": "object",
+      "description": "Canonical grammar thresholds enforced by the automaton.",
+      "properties": {
+        "enabled": {
+          "description": "Toggle canonical grammar enforcement during metric runs.",
+          "type": "boolean"
+        },
+        "zhir_requires_oz_window": {
+          "description": "Window requiring a DISSONANCE glyph before a MUTATION.",
+          "type": "integer",
+          "minimum": 0
+        },
+        "zhir_dnfr_min": {
+          "description": "Minimum normalised |ΔNFR| required to allow MUTATION without recent DISSONANCE.",
+          "type": "number",
+          "minimum": 0.0
+        },
+        "thol_min_len": {
+          "description": "Minimum number of THOL glyphs before canonical closure is allowed.",
+          "type": "integer",
+          "minimum": 0
+        },
+        "thol_max_len": {
+          "description": "Maximum number of THOL glyphs tolerated before forcing closure.",
+          "type": "integer",
+          "minimum": 0
+        },
+        "thol_close_dnfr": {
+          "description": "Upper bound on normalised |ΔNFR| that triggers THOL closure.",
+          "$ref": "#/definitions/probability"
+        },
+        "si_high": {
+          "description": "Sense index threshold: Si at or above this resolves THOL closures with silence; lower Si forces contraction.",
+          "$ref": "#/definitions/probability"
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "properties": {
+    "cfg_soft": { "$ref": "#/definitions/cfg_soft" },
+    "cfg_canon": { "$ref": "#/definitions/cfg_canon" }
+  },
+  "additionalProperties": false
+}

tnfr/sdk/__init__.py

@@ -0,0 +1,107 @@
+"""Simplified SDK for non-expert TNFR users.
+
+This module provides a high-level, user-friendly API for creating and
+simulating TNFR networks without requiring deep knowledge of the underlying
+theory. The SDK maintains full theoretical fidelity while hiding complexity
+through fluent interfaces, pre-configured templates, and domain-specific
+patterns.
+
+Public API
+----------
+TNFRNetwork
+    Fluent API for creating and evolving TNFR networks with method chaining.
+TNFRTemplates
+    Pre-configured templates for common domain-specific use cases.
+TNFRExperimentBuilder
+    Builder pattern for standard TNFR experiment workflows.
+NetworkResults
+    Structured results container for TNFR metrics and graph state.
+NetworkConfig
+    Configuration dataclass for network settings.
+
+Utilities
+---------
+compare_networks
+    Compare metrics across multiple networks.
+compute_network_statistics
+    Compute extended statistics for a network.
+export_to_json
+    Export network data to JSON file.
+import_from_json
+    Import network data from JSON file.
+format_comparison_table
+    Format network comparison as readable table.
+suggest_sequence_for_goal
+    Suggest operator sequence for a specific goal.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "TNFRNetwork",
+    "NetworkConfig",
+    "NetworkResults",
+    "TNFRTemplates",
+    "TNFRExperimentBuilder",
+    "TNFRAdaptiveSystem",
+    # Utilities
+    "compare_networks",
+    "compute_network_statistics",
+    "export_to_json",
+    "import_from_json",
+    "format_comparison_table",
+    "suggest_sequence_for_goal",
+]
+
+
+# Lazy imports to avoid circular dependencies and optional dependency issues
+def __getattr__(name: str):
+    """Lazy load SDK components."""
+    if name == "TNFRNetwork" or name == "NetworkConfig" or name == "NetworkResults":
+        from .fluent import TNFRNetwork, NetworkConfig, NetworkResults
+
+        if name == "TNFRNetwork":
+            return TNFRNetwork
+        elif name == "NetworkConfig":
+            return NetworkConfig
+        else:
+            return NetworkResults
+    elif name == "TNFRTemplates":
+        from .templates import TNFRTemplates
+
+        return TNFRTemplates
+    elif name == "TNFRExperimentBuilder":
+        from .builders import TNFRExperimentBuilder
+
+        return TNFRExperimentBuilder
+    elif name == "TNFRAdaptiveSystem":
+        from .adaptive_system import TNFRAdaptiveSystem
+
+        return TNFRAdaptiveSystem
+    elif name in [
+        "compare_networks",
+        "compute_network_statistics",
+        "export_to_json",
+        "import_from_json",
+        "format_comparison_table",
+        "suggest_sequence_for_goal",
+    ]:
+        from .utils import (
+            compare_networks,
+            compute_network_statistics,
+            export_to_json,
+            import_from_json,
+            format_comparison_table,
+            suggest_sequence_for_goal,
+        )
+
+        mapping = {
+            "compare_networks": compare_networks,
+            "compute_network_statistics": compute_network_statistics,
+            "export_to_json": export_to_json,
+            "import_from_json": import_from_json,
+            "format_comparison_table": format_comparison_table,
+            "suggest_sequence_for_goal": suggest_sequence_for_goal,
+        }
+        return mapping[name]
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

tnfr/sdk/__init__.pyi

@@ -0,0 +1,19 @@
+"""Type stubs for tnfr.sdk module."""
+
+from typing import Any
+
+__all__: tuple[str, ...]
+
+TNFRNetwork: Any
+NetworkConfig: Any
+NetworkResults: Any
+TNFRTemplates: Any
+TNFRExperimentBuilder: Any
+TNFRAdaptiveSystem: Any
+
+compare_networks: Any
+compute_network_statistics: Any
+export_to_json: Any
+import_from_json: Any
+format_comparison_table: Any
+suggest_sequence_for_goal: Any

tnfr/sdk/adaptive_system.py

@@ -0,0 +1,173 @@
+"""Unified adaptive system integrating all TNFR dynamic components.
+
+This module provides a high-level interface that combines feedback loops,
+adaptive sequence selection, homeostasis, learning, and metabolism into a
+single coherent adaptive system. It represents the complete implementation
+of TNFR autonomous evolution.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..types import TNFRGraph, NodeId
+
+from ..alias import get_attr
+from ..constants.aliases import ALIAS_DNFR
+from ..dynamics.feedback import StructuralFeedbackLoop
+from ..dynamics.adaptive_sequences import AdaptiveSequenceSelector
+from ..dynamics.homeostasis import StructuralHomeostasis
+from ..dynamics.learning import AdaptiveLearningSystem
+from ..dynamics.metabolism import StructuralMetabolism
+
+__all__ = ["TNFRAdaptiveSystem"]
+
+
+class TNFRAdaptiveSystem:
+    """Complete adaptive system integrating all TNFR dynamic components.
+
+    This class orchestrates feedback loops, sequence selection, homeostasis,
+    learning, and metabolism into autonomous evolution cycles. It provides
+    a single entry point for complex adaptive behaviors.
+
+    **Integrated Components:**
+
+    - **Feedback Loop**: Regulates coherence via operator selection
+    - **Sequence Selector**: Learns optimal operator trajectories
+    - **Homeostasis**: Maintains parameter equilibrium
+    - **Learning System**: Implements AL + T'HOL learning cycles
+    - **Metabolism**: Digests stimuli into structure
+
+    Parameters
+    ----------
+    graph : TNFRGraph
+        Graph containing the evolving node
+    node : NodeId
+        Identifier of the adaptive node
+    stress_normalization : float, default=0.2
+        ΔNFR value that corresponds to maximum stress (1.0)
+
+    Attributes
+    ----------
+    G : TNFRGraph
+        Graph reference
+    node : NodeId
+        Node identifier
+    feedback : StructuralFeedbackLoop
+        Feedback regulation component
+    sequence_selector : AdaptiveSequenceSelector
+        Adaptive sequence selection component
+    homeostasis : StructuralHomeostasis
+        Homeostatic regulation component
+    learning : AdaptiveLearningSystem
+        Adaptive learning component
+    metabolism : StructuralMetabolism
+        Structural metabolism component
+    STRESS_NORM : float
+        Normalization factor for stress measurement
+
+    Examples
+    --------
+    >>> from tnfr.structural import create_nfr
+    >>> from tnfr.sdk.adaptive_system import TNFRAdaptiveSystem
+    >>> G, node = create_nfr("adaptive_node")
+    >>> system = TNFRAdaptiveSystem(G, node)
+    >>> system.autonomous_evolution(num_cycles=20)
+
+    Notes
+    -----
+    The adaptive system implements complete TNFR autonomous evolution as
+    specified in the operational manual. Each cycle integrates:
+
+    1. Homeostatic regulation
+    2. Feedback-driven operator selection
+    3. Metabolic stress response
+    4. Learning consolidation
+
+    This creates self-regulating, adaptive structural dynamics.
+    """
+
+    STRESS_NORM = 0.2  # ΔNFR value corresponding to maximum stress
+
+    def __init__(
+        self,
+        graph: TNFRGraph,
+        node: NodeId,
+        stress_normalization: float = STRESS_NORM,
+    ) -> None:
+        self.G = graph
+        self.node = node
+        self.STRESS_NORM = float(stress_normalization)
+
+        # Initialize all components
+        self.feedback = StructuralFeedbackLoop(graph, node)
+        self.sequence_selector = AdaptiveSequenceSelector(graph, node)
+        self.homeostasis = StructuralHomeostasis(graph, node)
+        self.learning = AdaptiveLearningSystem(graph, node)
+        self.metabolism = StructuralMetabolism(graph, node)
+
+    def autonomous_evolution(self, num_cycles: int = 20) -> None:
+        """Execute complete autonomous evolution cycles.
+
+        Each cycle integrates adaptive components:
+
+        1. **Homeostasis**: Correct out-of-range parameters
+        2. **Feedback**: Regulate coherence via operator selection
+
+        Parameters
+        ----------
+        num_cycles : int, default=20
+            Number of evolution cycles to execute
+
+        Notes
+        -----
+        The integration follows TNFR principles:
+
+        - **Homeostasis first**: Ensure safe operating parameters
+        - **Feedback loops**: Maintain target coherence
+
+        This creates robust, adaptive, self-regulating dynamics.
+
+        **Advanced Usage:**
+
+        For full metabolic and learning cycles, use the component systems
+        directly:
+
+        - ``system.metabolism.adaptive_metabolism(stress)``
+        - ``system.learning.consolidate_memory()``
+
+        These require careful sequence design to comply with TNFR grammar.
+        """
+        for cycle in range(num_cycles):
+            # 1. Homeostatic regulation: maintain parameter equilibrium
+            self.homeostasis.maintain_equilibrium()
+
+            # 2. Feedback loop: regulate coherence
+            self.feedback.homeostatic_cycle(num_steps=3)
+
+    def _measure_stress(self) -> float:
+        """Measure structural stress level from ΔNFR.
+
+        Stress is proportional to reorganization pressure. High ΔNFR
+        indicates high stress requiring metabolic response.
+
+        Returns
+        -------
+        float
+            Stress level normalized to [0, 1]
+
+        Notes
+        -----
+        Stress mapping:
+
+        - ΔNFR = 0.0 → stress = 0.0 (no pressure)
+        - ΔNFR = 0.2 → stress = 1.0 (maximum pressure)
+        - Linear interpolation between
+
+        This normalization allows consistent stress response across
+        different system scales.
+        """
+        dnfr = get_attr(self.G.nodes[self.node], ALIAS_DNFR, 0.0)
+        # Normalize ΔNFR to [0, 1] stress level
+        return min(1.0, abs(dnfr) / self.STRESS_NORM)

tnfr/sdk/adaptive_system.pyi

@@ -0,0 +1,21 @@
+"""Type stubs for tnfr.sdk.adaptive_system module."""
+
+from ..types import TNFRGraph, NodeId
+from ..dynamics.feedback import StructuralFeedbackLoop
+from ..dynamics.adaptive_sequences import AdaptiveSequenceSelector
+from ..dynamics.homeostasis import StructuralHomeostasis
+from ..dynamics.learning import AdaptiveLearningSystem
+from ..dynamics.metabolism import StructuralMetabolism
+
+class TNFRAdaptiveSystem:
+    G: TNFRGraph
+    node: NodeId
+    feedback: StructuralFeedbackLoop
+    sequence_selector: AdaptiveSequenceSelector
+    homeostasis: StructuralHomeostasis
+    learning: AdaptiveLearningSystem
+    metabolism: StructuralMetabolism
+
+    def __init__(self, graph: TNFRGraph, node: NodeId) -> None: ...
+    def autonomous_evolution(self, num_cycles: int = ...) -> None: ...
+    def _measure_stress(self) -> float: ...