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

tnfr/rng.py

@@ -2,17 +2,22 @@
 
 from __future__ import annotations
 
-import random
 import hashlib
+import random
 import struct
-from collections.abc import Iterator, MutableMapping
-from typing import Any, Generic, Hashable, TypeVar
+from typing import Any, cast
 
+from cachetools import cached  # type: ignore[import-untyped]
 
-from cachetools import LRUCache, cached
 from .constants import DEFAULTS, get_param
-from .graph_utils import get_graph
 from .locking import get_lock
+from .types import GraphLike, TNFRGraph
+from .utils import (
+    ScopedCounterCache,
+    _SeedHashCache,
+    build_cache_manager,
+    get_graph,
+)
 
 MASK64 = 0xFFFFFFFFFFFFFFFF
 
@@ -21,147 +26,41 @@ _DEFAULT_CACHE_MAXSIZE = int(DEFAULTS.get("JITTER_CACHE_SIZE", 128))
 _CACHE_MAXSIZE = _DEFAULT_CACHE_MAXSIZE
 _CACHE_LOCKED = False
 
-K = TypeVar("K", bound=Hashable)
-
-
-class _SeedHashCache(MutableMapping[tuple[int, int], int]):
-    """Mutable mapping proxy exposing a configurable LRU cache."""
-
-    def __init__(self, maxsize: int) -> None:
-        self._maxsize = 0
-        self._cache: LRUCache[tuple[int, int], int] | None = None
-        self.configure(maxsize)
-
-    def configure(self, maxsize: int) -> None:
-        """Configure internal cache size, clearing previous entries."""
-
-        self._maxsize = int(maxsize)
-        if self._maxsize <= 0:
-            self._cache = None
-        else:
-            self._cache = LRUCache(maxsize=self._maxsize)
-
-    def __getitem__(self, key: tuple[int, int]) -> int:
-        if self._cache is None:
-            raise KeyError(key)
-        return self._cache[key]
-
-    def __setitem__(self, key: tuple[int, int], value: int) -> None:
-        if self._cache is not None:
-            self._cache[key] = value
-
-    def __delitem__(self, key: tuple[int, int]) -> None:
-        if self._cache is None:
-            raise KeyError(key)
-        del self._cache[key]
-
-    def __iter__(self) -> Iterator[tuple[int, int]]:
-        if self._cache is None:
-            return iter(())
-        return iter(self._cache)
-
-    def __len__(self) -> int:
-        if self._cache is None:
-            return 0
-        return len(self._cache)
-
-    def clear(self) -> None:  # type: ignore[override]
-        if self._cache is not None:
-            self._cache.clear()
-
-    @property
-    def maxsize(self) -> int:
-        return self._maxsize
-
-    @property
-    def enabled(self) -> bool:
-        return self._cache is not None
-
-    @property
-    def data(self) -> LRUCache[tuple[int, int], int] | None:
-        """Expose the underlying cache for diagnostics/tests."""
-
-        return self._cache
-
-
-class ScopedCounterCache(Generic[K]):
-    """Thread-safe LRU cache storing monotonic counters by ``key``."""
-
-    def __init__(self, name: str, max_entries: int) -> None:
-        if max_entries < 0:
-            raise ValueError("max_entries must be non-negative")
-        self._lock = get_lock(name)
-        self._max_entries = int(max_entries)
-        self._cache: LRUCache[K, int] = LRUCache(maxsize=self._max_entries)
-
-    @property
-    def lock(self):
-        """Return the lock guarding access to the underlying cache."""
-
-        return self._lock
-
-    @property
-    def max_entries(self) -> int:
-        """Return the configured maximum number of cached entries."""
-
-        return self._max_entries
-
-    @property
-    def cache(self) -> LRUCache[K, int]:
-        """Expose the underlying ``LRUCache`` for inspection."""
+_RNG_CACHE_MANAGER = build_cache_manager(default_capacity=_DEFAULT_CACHE_MAXSIZE)
 
-        return self._cache
-
-    def configure(
-        self, *, force: bool = False, max_entries: int | None = None
-    ) -> None:
-        """Resize or reset the cache keeping previous settings."""
-
-        size = self._max_entries if max_entries is None else int(max_entries)
-        if size < 0:
-            raise ValueError("max_entries must be non-negative")
-        with self._lock:
-            if size != self._max_entries:
-                self._max_entries = size
-                force = True
-            if force:
-                self._cache = LRUCache(maxsize=self._max_entries)
-
-    def clear(self) -> None:
-        """Clear stored counters preserving ``max_entries``."""
-
-        self.configure(force=True)
-
-    def bump(self, key: K) -> int:
-        """Return current counter for ``key`` and increment it atomically."""
+_seed_hash_cache = _SeedHashCache(
+    manager=_RNG_CACHE_MANAGER,
+    default_maxsize=_DEFAULT_CACHE_MAXSIZE,
+)
 
-        with self._lock:
-            value = int(self._cache.get(key, 0))
-            self._cache[key] = value + 1
-            return value
 
-    def __len__(self) -> int:
-        return len(self._cache)
+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")
 
 
-_seed_hash_cache = _SeedHashCache(_CACHE_MAXSIZE)
+@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)
 
 
-@cached(cache=_seed_hash_cache, lock=_RNG_LOCK)
 def seed_hash(seed_int: int, key_int: int) -> int:
     """Return a 64-bit hash derived from ``seed_int`` and ``key_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"
-    )
+    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)
 
 
-def _sync_cache_size(G: Any | None) -> None:
+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
@@ -169,16 +68,41 @@ def _sync_cache_size(G: Any | None) -> None:
         return
     size = get_cache_maxsize(G)
     with _RNG_LOCK:
-        if size != _CACHE_MAXSIZE:
+        if size != _seed_hash_cache.maxsize:
             _seed_hash_cache.configure(size)
-            _CACHE_MAXSIZE = size
-
-
-def make_rng(seed: int, key: int, G: Any | None = None) -> random.Random:
-    """Return a ``random.Random`` for ``seed`` and ``key``.
-
-    When ``G`` is provided, ``JITTER_CACHE_SIZE`` is read from ``G`` and the
-    internal cache size is updated accordingly.
+            _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)
@@ -188,17 +112,17 @@ def make_rng(seed: int, key: int, G: Any | None = None) -> random.Random:
 
 def clear_rng_cache() -> None:
     """Clear cached seed hashes."""
-    if _CACHE_MAXSIZE <= 0 or not _seed_hash_cache.enabled:
+    if _seed_hash_cache.maxsize <= 0 or not _seed_hash_cache.enabled:
         return
-    seed_hash.cache_clear()
+    seed_hash.cache_clear()  # type: ignore[attr-defined]
 
 
-def get_cache_maxsize(G: Any) -> int:
+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: Any | None = None) -> bool:
+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
@@ -207,12 +131,12 @@ def cache_enabled(G: Any | None = None) -> bool:
     # 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 _CACHE_MAXSIZE > 0:
+    if _seed_hash_cache.maxsize > 0:
         _sync_cache_size(G)
-    return _CACHE_MAXSIZE > 0
+    return _seed_hash_cache.maxsize > 0
 
 
-def base_seed(G: Any) -> int:
+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))
@@ -238,7 +162,7 @@ def set_cache_maxsize(size: int) -> None:
         raise ValueError("size must be non-negative")
     with _RNG_LOCK:
         _seed_hash_cache.configure(new_size)
-        _CACHE_MAXSIZE = new_size
+        _CACHE_MAXSIZE = _seed_hash_cache.maxsize
     _CACHE_LOCKED = new_size != _DEFAULT_CACHE_MAXSIZE
 
 

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