tnfr 4.5.2__py3-none-any.whl → 7.0.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,43 @@ _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
+_RNG_CACHE_MANAGER = build_cache_manager(default_capacity=_DEFAULT_CACHE_MAXSIZE)
 
-    @property
-    def cache(self) -> LRUCache[K, int]:
-        """Expose the underlying ``LRUCache`` for inspection."""
 
-        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)
+
 
+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: Any | None) -> None:
+
+def _sync_cache_size(G: TNFRGraph | GraphLike | None) -> None:
     """Synchronise cache size with ``G`` when needed."""
 
     global _CACHE_MAXSIZE
@@ -169,12 +70,14 @@ 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
+            _CACHE_MAXSIZE = _seed_hash_cache.maxsize
 
 
-def make_rng(seed: int, key: int, G: Any | None = None) -> random.Random:
+def make_rng(
+    seed: int, key: int, G: TNFRGraph | GraphLike | 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
@@ -188,17 +91,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 +110,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 +141,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,14 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+ScopedCounterCache: Any
+base_seed: Any
+cache_enabled: Any
+clear_rng_cache: Any
+get_cache_maxsize: Any
+make_rng: Any
+seed_hash: Any
+set_cache_maxsize: Any

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/selector.py

@@ -8,32 +8,33 @@ from __future__ import annotations
 
 import threading
 from operator import itemgetter
-from typing import Any, Mapping, TYPE_CHECKING
+from typing import TYPE_CHECKING, Any, Mapping, cast
 from weakref import WeakKeyDictionary
 
 if TYPE_CHECKING:  # pragma: no cover
-    import networkx as nx  # type: ignore[import-untyped]
+    import networkx as nx
 
 from .constants import DEFAULTS
 from .constants.core import SELECTOR_THRESHOLD_DEFAULTS
-from .helpers.numeric import clamp01
+from .utils import clamp01
 from .metrics.common import compute_dnfr_accel_max
-from .collections_utils import is_non_string_sequence
-
+from .types import SelectorNorms, SelectorThresholds, SelectorWeights
+from .utils import is_non_string_sequence
 
 HYSTERESIS_GLYPHS: set[str] = {"IL", "OZ", "ZHIR", "THOL", "NAV", "RA"}
 
 __all__ = (
     "_selector_thresholds",
-    "_norms_para_selector",
+    "_selector_norms",
     "_calc_selector_score",
     "_apply_selector_hysteresis",
 )
 
 
+_SelectorThresholdItems = tuple[tuple[str, float], ...]
 _SelectorThresholdCacheEntry = tuple[
-    tuple[tuple[str, float], ...],
-    dict[str, float],
+    _SelectorThresholdItems,
+    SelectorThresholds,
 ]
 _SELECTOR_THRESHOLD_CACHE: WeakKeyDictionary[
     "nx.Graph",
@@ -42,7 +43,7 @@ _SELECTOR_THRESHOLD_CACHE: WeakKeyDictionary[
 _SELECTOR_THRESHOLD_CACHE_LOCK = threading.Lock()
 
 
-def _sorted_items(mapping: Mapping[str, float]) -> tuple[tuple[str, float], ...]:
+def _sorted_items(mapping: Mapping[str, float]) -> _SelectorThresholdItems:
     """Return mapping items sorted by key.
 
     Parameters
@@ -59,8 +60,8 @@ def _sorted_items(mapping: Mapping[str, float]) -> tuple[tuple[str, float], ...]
 
 
 def _compute_selector_thresholds(
-    thr_sel_items: tuple[tuple[str, float], ...],
-) -> dict[str, float]:
+    thr_sel_items: _SelectorThresholdItems,
+) -> SelectorThresholds:
     """Construct selector thresholds for a graph.
 
     Parameters
@@ -79,10 +80,10 @@ def _compute_selector_thresholds(
     for key, default in SELECTOR_THRESHOLD_DEFAULTS.items():
         val = thr_sel.get(key, default)
         out[key] = clamp01(float(val))
-    return out
+    return cast(SelectorThresholds, out)
 
 
-def _selector_thresholds(G: "nx.Graph") -> dict[str, float]:
+def _selector_thresholds(G: "nx.Graph") -> SelectorThresholds:
     """Return normalised thresholds for Si, ΔNFR and acceleration.
 
     Parameters
@@ -114,8 +115,8 @@ def _selector_thresholds(G: "nx.Graph") -> dict[str, float]:
     return thresholds
 
 
-def _norms_para_selector(G: "nx.Graph") -> dict:
-    """Compute and cache norms for ΔNFR and acceleration.
+def _selector_norms(G: "nx.Graph") -> SelectorNorms:
+    """Compute and cache selector norms for ΔNFR and acceleration.
 
     Parameters
     ----------
@@ -134,7 +135,7 @@ def _norms_para_selector(G: "nx.Graph") -> dict:
 
 
 def _calc_selector_score(
-    Si: float, dnfr: float, accel: float, weights: dict[str, float]
+    Si: float, dnfr: float, accel: float, weights: SelectorWeights
 ) -> float:
     """Compute weighted selector score.
 
@@ -167,7 +168,7 @@ def _apply_selector_hysteresis(
     dnfr: float,
     accel: float,
     thr: dict[str, float],
-    margin: float,
+    margin: float | None,
 ) -> str | None:
     """Apply hysteresis when values are near thresholds.
 
@@ -183,8 +184,10 @@ def _apply_selector_hysteresis(
         Normalised acceleration.
     thr : dict[str, float]
         Thresholds returned by :func:`_selector_thresholds`.
-    margin : float
-        Distance from thresholds below which the previous glyph is reused.
+    margin : float or None
+        When positive, distance from thresholds below which the previous
+        glyph is reused. Falsy margins disable hysteresis entirely, letting
+        selectors bypass the reuse logic.
 
     Returns
     -------
@@ -192,6 +195,9 @@ def _apply_selector_hysteresis(
         Previous glyph if hysteresis applies, otherwise ``None``.
     """
     # Batch extraction reduces dictionary lookups inside loops.
+    if not margin:
+        return None
+
     si_hi, si_lo, dnfr_hi, dnfr_lo, accel_hi, accel_lo = itemgetter(
         "si_hi", "si_lo", "dnfr_hi", "dnfr_lo", "accel_hi", "accel_lo"
     )(thr)

tnfr/selector.pyi

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+def _apply_selector_hysteresis(
+    nd: dict[str, Any],
+    Si: float,
+    dnfr: float,
+    accel: float,
+    thr: Mapping[str, float],
+    margin: float | None,
+) -> str | None: ...
+
+_calc_selector_score: Any
+_selector_norms: Any
+_selector_thresholds: Any