tnfr 6.0.0__py3-none-any.whl → 7.0.0__py3-none-any.whl

tnfr/rng.py

@@ -5,18 +5,19 @@ from __future__ import annotations
 import hashlib
 import random
 import struct
-import threading
-from collections.abc import Iterator, MutableMapping
-from dataclasses import dataclass
-from typing import Any, Generic, Hashable, TypeVar, cast
-
+from typing import Any, cast
 
 from cachetools import cached  # type: ignore[import-untyped]
+
 from .constants import DEFAULTS, get_param
-from .cache import CacheManager, InstrumentedLRUCache
-from .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
 
@@ -25,296 +26,14 @@ _DEFAULT_CACHE_MAXSIZE = int(DEFAULTS.get("JITTER_CACHE_SIZE", 128))
 _CACHE_MAXSIZE = _DEFAULT_CACHE_MAXSIZE
 _CACHE_LOCKED = False
 
-K = TypeVar("K", bound=Hashable)
-V = TypeVar("V")
-
-
-@dataclass
-class _SeedCacheState:
-    cache: InstrumentedLRUCache[tuple[int, int], int] | None
-    maxsize: int
-
-
-@dataclass
-class _CounterState(Generic[K]):
-    cache: InstrumentedLRUCache[K, int]
-    locks: dict[K, threading.RLock]
-    max_entries: int
-
-
-_RNG_CACHE_MANAGER = CacheManager(default_capacity=_DEFAULT_CACHE_MAXSIZE)
-
-
-class _SeedHashCache(MutableMapping[tuple[int, int], int]):
-    """Mutable mapping proxy exposing a configurable LRU cache."""
-
-    def __init__(
-        self,
-        *,
-        manager: CacheManager | None = None,
-        state_key: str = "seed_hash_cache",
-        default_maxsize: int = _DEFAULT_CACHE_MAXSIZE,
-    ) -> None:
-        self._manager = manager or _RNG_CACHE_MANAGER
-        self._state_key = state_key
-        self._default_maxsize = int(default_maxsize)
-        if not self._manager.has_override(self._state_key):
-            self._manager.configure(
-                overrides={self._state_key: self._default_maxsize}
-            )
-        self._manager.register(
-            self._state_key,
-            self._create_state,
-            reset=self._reset_state,
-        )
-
-    def _resolved_size(self, requested: int | None = None) -> int:
-        size = self._manager.get_capacity(
-            self._state_key,
-            requested=requested,
-            fallback=self._default_maxsize,
-        )
-        if size is None:
-            return 0
-        return int(size)
-
-    def _create_state(self) -> _SeedCacheState:
-        size = self._resolved_size()
-        if size <= 0:
-            return _SeedCacheState(cache=None, maxsize=0)
-        return _SeedCacheState(
-            cache=InstrumentedLRUCache(
-                size,
-                manager=self._manager,
-                metrics_key=self._state_key,
-            ),
-            maxsize=size,
-        )
-
-    def _reset_state(self, state: _SeedCacheState | None) -> _SeedCacheState:
-        return self._create_state()
-
-    def _get_state(self, *, create: bool = True) -> _SeedCacheState | None:
-        state = self._manager.get(self._state_key, create=create)
-        if state is None:
-            return None
-        if not isinstance(state, _SeedCacheState):
-            state = self._create_state()
-            self._manager.store(self._state_key, state)
-        return state
-
-    def configure(self, maxsize: int) -> None:
-        size = int(maxsize)
-        if size < 0:
-            raise ValueError("maxsize must be non-negative")
-        self._manager.configure(overrides={self._state_key: size})
-        self._manager.update(self._state_key, lambda _: self._create_state())
-
-    def __getitem__(self, key: tuple[int, int]) -> int:
-        state = self._get_state()
-        if state is None or state.cache is None:
-            raise KeyError(key)
-        value = state.cache[key]
-        self._manager.increment_hit(self._state_key)
-        return value
-
-    def __setitem__(self, key: tuple[int, int], value: int) -> None:
-        state = self._get_state()
-        if state is not None and state.cache is not None:
-            state.cache[key] = value
-
-    def __delitem__(self, key: tuple[int, int]) -> None:
-        state = self._get_state()
-        if state is None or state.cache is None:
-            raise KeyError(key)
-        del state.cache[key]
-
-    def __iter__(self) -> Iterator[tuple[int, int]]:
-        state = self._get_state(create=False)
-        if state is None or state.cache is None:
-            return iter(())
-        return iter(state.cache)
-
-    def __len__(self) -> int:
-        state = self._get_state(create=False)
-        if state is None or state.cache is None:
-            return 0
-        return len(state.cache)
-
-    def clear(self) -> None:  # type: ignore[override]
-        self._manager.clear(self._state_key)
-
-    @property
-    def maxsize(self) -> int:
-        state = self._get_state()
-        return 0 if state is None else state.maxsize
-
-    @property
-    def enabled(self) -> bool:
-        state = self._get_state(create=False)
-        return bool(state and state.cache is not None)
-
-    @property
-    def data(self) -> InstrumentedLRUCache[tuple[int, int], int] | None:
-        """Expose the underlying cache for diagnostics/tests."""
-
-        state = self._get_state(create=False)
-        return None if state is None else state.cache
-
-
-class ScopedCounterCache(Generic[K]):
-    """Thread-safe LRU cache storing monotonic counters by ``key``."""
-
-    def __init__(
-        self,
-        name: str,
-        max_entries: int | None = None,
-        *,
-        manager: CacheManager | None = None,
-        default_max_entries: int = _DEFAULT_CACHE_MAXSIZE,
-    ) -> None:
-        self._name = name
-        self._manager = manager or _RNG_CACHE_MANAGER
-        self._state_key = f"scoped_counter:{name}"
-        self._default_max_entries = int(default_max_entries)
-        requested = None if max_entries is None else int(max_entries)
-        if requested is not None and requested < 0:
-            raise ValueError("max_entries must be non-negative")
-        if not self._manager.has_override(self._state_key):
-            fallback = requested
-            if fallback is None:
-                fallback = self._default_max_entries
-            self._manager.configure(overrides={self._state_key: fallback})
-        elif requested is not None:
-            self._manager.configure(overrides={self._state_key: requested})
-        self._manager.register(
-            self._state_key,
-            self._create_state,
-            lock_factory=lambda: get_lock(name),
-            reset=self._reset_state,
-        )
-
-    def _resolved_entries(self, requested: int | None = None) -> int:
-        size = self._manager.get_capacity(
-            self._state_key,
-            requested=requested,
-            fallback=self._default_max_entries,
-        )
-        if size is None:
-            return 0
-        return int(size)
-
-    def _create_state(self, requested: int | None = None) -> _CounterState[K]:
-        size = self._resolved_entries(requested)
-        locks: dict[K, threading.RLock] = {}
-        return _CounterState(
-            cache=InstrumentedLRUCache(
-                size,
-                manager=self._manager,
-                metrics_key=self._state_key,
-                locks=locks,
-            ),
-            locks=locks,
-            max_entries=size,
-        )
-
-    def _reset_state(self, state: _CounterState[K] | None) -> _CounterState[K]:
-        return self._create_state()
-
-    def _get_state(self) -> _CounterState[K]:
-        state = self._manager.get(self._state_key)
-        if not isinstance(state, _CounterState):
-            state = self._create_state(0)
-            self._manager.store(self._state_key, state)
-        return state
-
-    @property
-    def lock(self) -> threading.Lock | threading.RLock:
-        """Return the lock guarding access to the underlying cache."""
-
-        return self._manager.get_lock(self._state_key)
-
-    @property
-    def max_entries(self) -> int:
-        """Return the configured maximum number of cached entries."""
-
-        return self._get_state().max_entries
-
-    @property
-    def cache(self) -> InstrumentedLRUCache[K, int]:
-        """Expose the instrumented cache for inspection."""
-
-        return self._get_state().cache
-
-    @property
-    def locks(self) -> dict[K, threading.RLock]:
-        """Return the mapping of per-key locks tracked by the cache."""
-
-        return self._get_state().locks
-
-    def configure(
-        self, *, force: bool = False, max_entries: int | None = None
-    ) -> None:
-        """Resize or reset the cache keeping previous settings."""
-
-        if max_entries is None:
-            size = self._resolved_entries()
-            update_policy = False
-        else:
-            size = int(max_entries)
-            if size < 0:
-                raise ValueError("max_entries must be non-negative")
-            update_policy = True
-
-        def _update(state: _CounterState[K] | None) -> _CounterState[K]:
-            if not isinstance(state, _CounterState) or force or state.max_entries != size:
-                locks: dict[K, threading.RLock] = {}
-                return _CounterState(
-                    cache=InstrumentedLRUCache(
-                        size,
-                        manager=self._manager,
-                        metrics_key=self._state_key,
-                        locks=locks,
-                    ),
-                    locks=locks,
-                    max_entries=size,
-                )
-            return cast(_CounterState[K], state)
-
-        if update_policy:
-            self._manager.configure(overrides={self._state_key: size})
-        self._manager.update(self._state_key, _update)
-
-    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."""
-
-        result: dict[str, Any] = {}
-
-        def _update(state: _CounterState[K] | None) -> _CounterState[K]:
-            if not isinstance(state, _CounterState):
-                state = self._create_state(0)
-            cache = state.cache
-            locks = state.locks
-            if key not in locks:
-                locks[key] = threading.RLock()
-            value = int(cache.get(key, 0))
-            cache[key] = value + 1
-            result["value"] = value
-            return state
-
-        self._manager.update(self._state_key, _update)
-        return int(result.get("value", 0))
-
-    def __len__(self) -> int:
-        return len(self.cache)
-
-
-_seed_hash_cache = _SeedHashCache()
+
+_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:
@@ -323,9 +42,7 @@ def _compute_seed_hash(seed_int: int, key_int: int) -> int:
         seed_int & MASK64,
         key_int & MASK64,
     )
-    return int.from_bytes(
-        hashlib.blake2b(seed_bytes, digest_size=8).digest(), "big"
-    )
+    return int.from_bytes(hashlib.blake2b(seed_bytes, digest_size=8).digest(), "big")
 
 
 @cached(cache=_seed_hash_cache, lock=_RNG_LOCK)

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,7 +8,7 @@ from __future__ import annotations
 
 import threading
 from operator import itemgetter
-from typing import Any, Mapping, TYPE_CHECKING, cast
+from typing import TYPE_CHECKING, Any, Mapping, cast
 from weakref import WeakKeyDictionary
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -16,11 +16,10 @@ if TYPE_CHECKING:  # pragma: no cover
 
 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 .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"}
 

tnfr/selector.pyi

@@ -5,7 +5,6 @@ from typing import Any, Mapping
 __all__: Any
 
 def __getattr__(name: str) -> Any: ...
-
 def _apply_selector_hysteresis(
     nd: dict[str, Any],
     Si: float,
@@ -14,6 +13,7 @@ def _apply_selector_hysteresis(
     thr: Mapping[str, float],
     margin: float | None,
 ) -> str | None: ...
+
 _calc_selector_score: Any
 _selector_norms: Any
 _selector_thresholds: Any

tnfr/sense.py

@@ -1,30 +1,29 @@
 """Sense calculations."""
 
 from __future__ import annotations
-from typing import Any, Callable, TypeVar
-from collections.abc import Iterable, Iterator, Mapping
+
 import math
 from collections import Counter
+from collections.abc import Iterable, Iterator, Mapping
 from itertools import tee
+from typing import Any, Callable, TypeVar
 
 import networkx as nx
 
-from .constants import get_aliases, get_graph_param
 from .alias import get_attr
-from .helpers.numeric import clamp01, kahan_sum_nd
-from .utils import get_numpy
 from .callback_utils import CallbackEvent, callback_manager
-from .glyph_history import (
-    ensure_history,
-    last_glyph,
-    count_glyphs,
-    append_metric,
-)
 from .config.constants import (
     ANGLE_MAP,
     GLYPHS_CANONICAL,
 )
+from .constants import get_graph_param
+from .constants.aliases import ALIAS_EPI, ALIAS_SI
+from .glyph_history import append_metric, count_glyphs, ensure_history
+from .glyph_runtime import last_glyph
+from .utils import clamp01, kahan_sum_nd
 from .types import NodeId, SigmaVector, TNFRGraph
+from .utils import get_numpy
+
 # -------------------------
 # Canon: circular glyph order and angles
 # -------------------------
@@ -74,9 +73,6 @@ def glyph_unit(g: str) -> complex:
     return _resolve_glyph(g, GLYPH_UNITS)
 
 
-ALIAS_SI = get_aliases("SI")
-ALIAS_EPI = get_aliases("EPI")
-
 MODE_FUNCS: dict[str, Callable[[Mapping[str, Any]], float]] = {
     "Si": lambda nd: clamp01(get_attr(nd, ALIAS_SI, 0.5)),
     "EPI": lambda nd: max(0.0, get_attr(nd, ALIAS_EPI, 0.0)),
@@ -145,7 +141,9 @@ def _sigma_from_iterable(
     number of processed values under the ``"n"`` key.
     """
 
-    if isinstance(values, Iterable) and not isinstance(values, (str, bytes, bytearray, Mapping)):
+    if isinstance(values, Iterable) and not isinstance(
+        values, (str, bytes, bytearray, Mapping)
+    ):
         iterator = iter(values)
     else:
         iterator = iter((values,))
@@ -195,9 +193,7 @@ def _sigma_from_iterable(
     }
 
 
-def _ema_update(
-    prev: SigmaVector, current: SigmaVector, alpha: float
-) -> SigmaVector:
+def _ema_update(prev: SigmaVector, current: SigmaVector, alpha: float) -> SigmaVector:
     """Exponential moving average update for σ vectors."""
     x = (1 - alpha) * prev["x"] + alpha * current["x"]
     y = (1 - alpha) * prev["y"] + alpha * current["y"]
@@ -231,6 +227,8 @@ def _sigma_from_nodes(
 def sigma_vector_node(
     G: TNFRGraph, n: NodeId, weight_mode: str | None = None
 ) -> SigmaVector | None:
+    """Return the σ vector for node ``n`` using the configured weighting."""
+
     cfg = _sigma_cfg(G)
     nd = G.nodes[n]
     weight_mode = weight_mode or cfg.get("weight", "Si")
@@ -280,9 +278,7 @@ def sigma_vector_from_graph(
 
     cfg = _sigma_cfg(G)
     weight_mode = weight_mode or cfg.get("weight", "Si")
-    sv, _ = _sigma_from_nodes(
-        (nd for _, nd in G.nodes(data=True)), weight_mode
-    )
+    sv, _ = _sigma_from_nodes((nd for _, nd in G.nodes(data=True)), weight_mode)
     return sv
 
 
@@ -292,6 +288,8 @@ def sigma_vector_from_graph(
 
 
 def push_sigma_snapshot(G: TNFRGraph, t: float | None = None) -> None:
+    """Record a global σ snapshot (and optional per-node traces) for ``G``."""
+
     cfg = _sigma_cfg(G)
     if not cfg.get("enabled", True):
         return
@@ -334,6 +332,8 @@ def push_sigma_snapshot(G: TNFRGraph, t: float | None = None) -> None:
 
 
 def register_sigma_callback(G: TNFRGraph) -> None:
+    """Attach :func:`push_sigma_snapshot` to the ``AFTER_STEP`` callback bus."""
+
     callback_manager.register_callback(
         G,
         event=CallbackEvent.AFTER_STEP.value,
@@ -352,9 +352,7 @@ def sigma_rose(G: TNFRGraph, steps: int | None = None) -> dict[str, int]:
         steps = int(steps)
         if steps < 0:
             raise ValueError("steps must be non-negative")
-        rows = (
-            counts if steps >= len(counts) else counts[-steps:]
-        )  # noqa: E203
+        rows = counts if steps >= len(counts) else counts[-steps:]  # noqa: E203
     else:
         rows = counts
     counter = Counter()

tnfr/sense.pyi

@@ -10,21 +10,14 @@ __all__: tuple[str, ...]
 GLYPH_UNITS: dict[str, complex]
 
 def glyph_angle(g: str) -> float: ...
-
 def glyph_unit(g: str) -> complex: ...
-
 def push_sigma_snapshot(G: TNFRGraph, t: Optional[float] = None) -> None: ...
-
 def register_sigma_callback(G: TNFRGraph) -> None: ...
-
 def sigma_rose(G: TNFRGraph, steps: Optional[int] = None) -> dict[str, int]: ...
-
 def sigma_vector(dist: Mapping[str, float]) -> SigmaVector: ...
-
 def sigma_vector_from_graph(
     G: TNFRGraph, weight_mode: Optional[str] = None
 ) -> SigmaVector: ...
-
 def sigma_vector_node(
     G: TNFRGraph, n: NodeId, weight_mode: Optional[str] = None
 ) -> Optional[SigmaVector]: ...