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

tnfr/operators/definitions.py

@@ -0,0 +1,181 @@
+"""Definitions for canonical TNFR structural operators.
+
+English identifiers are the public API. Spanish wrappers were removed in
+TNFR 2.0, so downstream code must import these classes directly.
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from ..config.operator_names import (
+    COHERENCE,
+    COUPLING,
+    DISSONANCE,
+    EMISSION,
+    MUTATION,
+    RECEPTION,
+    RECURSIVITY,
+    RESONANCE,
+    SELF_ORGANIZATION,
+    SILENCE,
+    TRANSITION,
+    CONTRACTION,
+    EXPANSION,
+)
+from ..types import Glyph, TNFRGraph
+from .registry import register_operator
+
+__all__ = [
+    "Operator",
+    "Emission",
+    "Reception",
+    "Coherence",
+    "Dissonance",
+    "Coupling",
+    "Resonance",
+    "Silence",
+    "Expansion",
+    "Contraction",
+    "SelfOrganization",
+    "Mutation",
+    "Transition",
+    "Recursivity",
+]
+
+
+class Operator:
+    """Base class for TNFR operators.
+
+    Each operator defines ``name`` (ASCII identifier) and ``glyph``. Calling an
+    instance applies the corresponding glyph to the node.
+    """
+
+    name: ClassVar[str] = "operator"
+    glyph: ClassVar[Glyph | None] = None
+
+    def __call__(self, G: TNFRGraph, node: Any, **kw: Any) -> None:
+        if self.glyph is None:
+            raise NotImplementedError("Operator without assigned glyph")
+        from ..validation.grammar import (  # local import to avoid cycles
+            apply_glyph_with_grammar,
+        )
+
+        apply_glyph_with_grammar(G, [node], self.glyph, kw.get("window"))
+
+
+@register_operator
+class Emission(Operator):
+    """Emission operator (glyph ``AL``)."""
+
+    __slots__ = ()
+    name: ClassVar[str] = EMISSION
+    glyph: ClassVar[Glyph] = Glyph.AL
+
+
+@register_operator
+class Reception(Operator):
+    """Reception operator (glyph ``EN``)."""
+
+    __slots__ = ()
+    name: ClassVar[str] = RECEPTION
+    glyph: ClassVar[Glyph] = Glyph.EN
+
+
+@register_operator
+class Coherence(Operator):
+    """Coherence operator (glyph ``IL``)."""
+
+    __slots__ = ()
+    name: ClassVar[str] = COHERENCE
+    glyph: ClassVar[Glyph] = Glyph.IL
+
+
+@register_operator
+class Dissonance(Operator):
+    """Dissonance operator (glyph ``OZ``)."""
+
+    __slots__ = ()
+    name: ClassVar[str] = DISSONANCE
+    glyph: ClassVar[Glyph] = Glyph.OZ
+
+
+@register_operator
+class Coupling(Operator):
+    """Coupling operator (glyph ``UM``)."""
+
+    __slots__ = ()
+    name: ClassVar[str] = COUPLING
+    glyph: ClassVar[Glyph] = Glyph.UM
+
+
+@register_operator
+class Resonance(Operator):
+    """Resonance operator (glyph ``RA``)."""
+
+    __slots__ = ()
+    name: ClassVar[str] = RESONANCE
+    glyph: ClassVar[Glyph] = Glyph.RA
+
+
+@register_operator
+class Silence(Operator):
+    """Silence operator (glyph ``SHA``)."""
+
+    __slots__ = ()
+    name: ClassVar[str] = SILENCE
+    glyph: ClassVar[Glyph] = Glyph.SHA
+
+
+@register_operator
+class Expansion(Operator):
+    """Expansion operator (glyph ``VAL``)."""
+
+    __slots__ = ()
+    name: ClassVar[str] = EXPANSION
+    glyph: ClassVar[Glyph] = Glyph.VAL
+
+
+@register_operator
+class Contraction(Operator):
+    """Contraction operator (glyph ``NUL``)."""
+
+    __slots__ = ()
+    name: ClassVar[str] = CONTRACTION
+    glyph: ClassVar[Glyph] = Glyph.NUL
+
+
+@register_operator
+class SelfOrganization(Operator):
+    """Self-organization operator (glyph ``THOL``)."""
+
+    __slots__ = ()
+    name: ClassVar[str] = SELF_ORGANIZATION
+    glyph: ClassVar[Glyph] = Glyph.THOL
+
+
+@register_operator
+class Mutation(Operator):
+    """Mutation operator (glyph ``ZHIR``)."""
+
+    __slots__ = ()
+    name: ClassVar[str] = MUTATION
+    glyph: ClassVar[Glyph] = Glyph.ZHIR
+
+
+@register_operator
+class Transition(Operator):
+    """Transition operator (glyph ``NAV``)."""
+
+    __slots__ = ()
+    name: ClassVar[str] = TRANSITION
+    glyph: ClassVar[Glyph] = Glyph.NAV
+
+
+@register_operator
+class Recursivity(Operator):
+    """Recursivity operator (glyph ``REMESH``)."""
+
+    __slots__ = ()
+    name: ClassVar[str] = RECURSIVITY
+    glyph: ClassVar[Glyph] = Glyph.REMESH

tnfr/operators/definitions.pyi

@@ -0,0 +1,92 @@
+from typing import Any, ClassVar
+
+from ..types import Glyph, TNFRGraph
+
+__all__ = (
+    "Operator",
+    "Emission",
+    "Reception",
+    "Coherence",
+    "Dissonance",
+    "Coupling",
+    "Resonance",
+    "Silence",
+    "Expansion",
+    "Contraction",
+    "SelfOrganization",
+    "Mutation",
+    "Transition",
+    "Recursivity",
+)
+
+
+class Operator:
+    name: ClassVar[str]
+    glyph: ClassVar[Glyph | None]
+
+    def __call__(self, G: TNFRGraph, node: Any, **kw: Any) -> None: ...
+
+
+class Emission(Operator):
+    name: ClassVar[str]
+    glyph: ClassVar[Glyph]
+
+
+class Reception(Operator):
+    name: ClassVar[str]
+    glyph: ClassVar[Glyph]
+
+
+class Coherence(Operator):
+    name: ClassVar[str]
+    glyph: ClassVar[Glyph]
+
+
+class Dissonance(Operator):
+    name: ClassVar[str]
+    glyph: ClassVar[Glyph]
+
+
+class Coupling(Operator):
+    name: ClassVar[str]
+    glyph: ClassVar[Glyph]
+
+
+class Resonance(Operator):
+    name: ClassVar[str]
+    glyph: ClassVar[Glyph]
+
+
+class Silence(Operator):
+    name: ClassVar[str]
+    glyph: ClassVar[Glyph]
+
+
+class Expansion(Operator):
+    name: ClassVar[str]
+    glyph: ClassVar[Glyph]
+
+
+class Contraction(Operator):
+    name: ClassVar[str]
+    glyph: ClassVar[Glyph]
+
+
+class SelfOrganization(Operator):
+    name: ClassVar[str]
+    glyph: ClassVar[Glyph]
+
+
+class Mutation(Operator):
+    name: ClassVar[str]
+    glyph: ClassVar[Glyph]
+
+
+class Transition(Operator):
+    name: ClassVar[str]
+    glyph: ClassVar[Glyph]
+
+
+class Recursivity(Operator):
+    name: ClassVar[str]
+    glyph: ClassVar[Glyph]

tnfr/operators/jitter.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
-from typing import Any, TYPE_CHECKING
+import threading
+
+from typing import Any, TYPE_CHECKING, cast
 
 from cachetools import LRUCache
 
-from ..cache import ensure_node_offset_map
 from ..rng import (
     ScopedCounterCache,
     make_rng,
@@ -12,10 +13,12 @@ from ..rng import (
     clear_rng_cache as _clear_rng_cache,
     seed_hash,
 )
-from ..import_utils import get_nodonx
+from ..cache import CacheManager
+from ..utils import ensure_node_offset_map, get_nodenx
+from ..types import NodeId, TNFRGraph
 
 if TYPE_CHECKING:  # pragma: no cover - type checking only
-    from ..node import NodoProtocol
+    from ..node import NodeProtocol
 
 # Guarded by the cache lock to ensure thread-safe access. ``seq`` stores
 # per-scope jitter sequence counters in an LRU cache bounded to avoid
@@ -26,9 +29,44 @@ _JITTER_MAX_ENTRIES = 1024
 class JitterCache:
     """Container for jitter-related caches."""
 
-    def __init__(self, max_entries: int = _JITTER_MAX_ENTRIES) -> None:
-        self._sequence = ScopedCounterCache("jitter", max_entries)
-        self.settings: dict[str, Any] = {"max_entries": self._sequence.max_entries}
+    def __init__(
+        self,
+        max_entries: int = _JITTER_MAX_ENTRIES,
+        *,
+        manager: CacheManager | None = None,
+    ) -> None:
+        self._manager = manager or CacheManager()
+        if not self._manager.has_override("scoped_counter:jitter"):
+            self._manager.configure(
+                overrides={"scoped_counter:jitter": int(max_entries)}
+            )
+        self._sequence = ScopedCounterCache(
+            "jitter",
+            max_entries=None,
+            manager=self._manager,
+            default_max_entries=int(max_entries),
+        )
+        self._settings_key = "jitter_settings"
+        self._manager.register(
+            self._settings_key,
+            lambda: {"max_entries": self._sequence.max_entries},
+            reset=self._reset_settings,
+        )
+
+    def _reset_settings(self, settings: dict[str, Any] | None) -> dict[str, Any]:
+        return {"max_entries": self._sequence.max_entries}
+
+    def _refresh_settings(self) -> None:
+        self._manager.update(
+            self._settings_key,
+            lambda _: {"max_entries": self._sequence.max_entries},
+        )
+
+    @property
+    def manager(self) -> CacheManager:
+        """Expose the cache manager backing this cache."""
+
+        return self._manager
 
     @property
     def seq(self) -> LRUCache[tuple[int, int], int]:
@@ -37,7 +75,7 @@ class JitterCache:
         return self._sequence.cache
 
     @property
-    def lock(self):
+    def lock(self) -> threading.Lock | threading.RLock:
         """Return the lock protecting the sequence cache."""
 
         return self._sequence.lock
@@ -53,7 +91,13 @@ class JitterCache:
         """Set the maximum number of cached jitter sequences."""
 
         self._sequence.configure(max_entries=int(value))
-        self.settings["max_entries"] = self._sequence.max_entries
+        self._refresh_settings()
+
+    @property
+    def settings(self) -> dict[str, Any]:
+        """Return jitter cache settings stored on the manager."""
+
+        return cast(dict[str, Any], self._manager.get(self._settings_key))
 
     def setup(
         self, force: bool = False, max_entries: int | None = None
@@ -61,13 +105,14 @@ class JitterCache:
         """Ensure jitter cache matches the configured size."""
 
         self._sequence.configure(force=force, max_entries=max_entries)
-        self.settings["max_entries"] = self._sequence.max_entries
+        self._refresh_settings()
 
     def clear(self) -> None:
         """Clear cached RNGs and jitter state."""
 
         _clear_rng_cache()
         self._sequence.clear()
+        self._manager.clear(self._settings_key)
 
     def bump(self, key: tuple[int, int]) -> int:
         """Return current jitter sequence counter for ``key`` and increment it."""
@@ -78,8 +123,18 @@ class JitterCache:
 class JitterCacheManager:
     """Manager exposing the jitter cache without global reassignment."""
 
-    def __init__(self, cache: JitterCache | None = None) -> None:
-        self.cache = cache or JitterCache()
+    def __init__(
+        self,
+        cache: JitterCache | None = None,
+        *,
+        manager: CacheManager | None = None,
+    ) -> None:
+        if cache is not None:
+            self.cache = cache
+            self._manager = cache.manager
+        else:
+            self._manager = manager or CacheManager()
+            self.cache = JitterCache(manager=self._manager)
 
     # Convenience passthrough properties
     @property
@@ -91,17 +146,19 @@ class JitterCacheManager:
         return self.cache.settings
 
     @property
-    def lock(self):
+    def lock(self) -> threading.Lock | threading.RLock:
         return self.cache.lock
 
     @property
     def max_entries(self) -> int:
         """Return the maximum number of cached jitter entries."""
+
         return self.cache.max_entries
 
     @max_entries.setter
     def max_entries(self, value: int) -> None:
         """Set the maximum number of cached jitter entries."""
+
         self.cache.max_entries = value
 
     def setup(
@@ -112,6 +169,7 @@ class JitterCacheManager:
         ``max_entries`` may be provided to explicitly resize the cache.
         When omitted the existing ``cache.max_entries`` is preserved.
         """
+
         if max_entries is not None:
             self.cache.setup(force=True, max_entries=max_entries)
         else:
@@ -119,6 +177,7 @@ class JitterCacheManager:
 
     def clear(self) -> None:
         """Clear cached RNGs and jitter state."""
+
         self.cache.clear()
 
     def bump(self, key: tuple[int, int]) -> int:
@@ -148,27 +207,31 @@ def reset_jitter_manager() -> None:
     _JITTER_MANAGER = None
 
 
-def _node_offset(G, n) -> int:
+def _node_offset(G: TNFRGraph, n: NodeId) -> int:
     """Deterministic node index used for jitter seeds."""
     mapping = ensure_node_offset_map(G)
     return int(mapping.get(n, 0))
 
 
-def _resolve_jitter_seed(node: NodoProtocol) -> tuple[int, int]:
-    NodoNX = get_nodonx()
-    if NodoNX is None:
-        raise ImportError("NodoNX is unavailable")
-    if isinstance(node, NodoNX):
-        return _node_offset(node.G, node.n), id(node.G)
+def _resolve_jitter_seed(node: NodeProtocol) -> tuple[int, int]:
+    node_nx_type = get_nodenx()
+    if node_nx_type is None:
+        raise ImportError("NodeNX is unavailable")
+    if isinstance(node, node_nx_type):
+        graph = cast(TNFRGraph, getattr(node, "G"))
+        node_id = cast(NodeId, getattr(node, "n"))
+        return _node_offset(graph, node_id), id(graph)
     uid = getattr(node, "_noise_uid", None)
     if uid is None:
         uid = id(node)
         setattr(node, "_noise_uid", uid)
-    return int(uid), id(node)
+    graph = cast(TNFRGraph | None, getattr(node, "G", None))
+    scope = graph if graph is not None else node
+    return int(uid), id(scope)
 
 
 def random_jitter(
-    node: NodoProtocol,
+    node: NodeProtocol,
     amplitude: float,
 ) -> float:
     """Return deterministic noise in ``[-amplitude, amplitude]`` for ``node``.
@@ -184,7 +247,7 @@ def random_jitter(
     seed_root = base_seed(node.G)
     seed_key, scope_id = _resolve_jitter_seed(node)
 
-    cache_key = (seed_root, scope_id)
+    cache_key = (seed_root, scope_id, seed_key)
     seq = 0
     if cache_enabled(node.G):
         manager = get_jitter_manager()

tnfr/operators/jitter.pyi

@@ -0,0 +1,11 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+JitterCache: Any
+JitterCacheManager: Any
+get_jitter_manager: Any
+random_jitter: Any
+reset_jitter_manager: Any

tnfr/operators/registry.py

@@ -0,0 +1,80 @@
+"""Registry mapping operator names to their classes."""
+
+from __future__ import annotations
+
+import importlib
+import pkgutil
+from typing import Any, TYPE_CHECKING
+
+from ..config.operator_names import canonical_operator_name
+
+if TYPE_CHECKING:  # pragma: no cover - type checking only
+    from .definitions import Operator
+
+
+OPERATORS: dict[str, type["Operator"]] = {}
+
+
+def register_operator(cls: type["Operator"]) -> type["Operator"]:
+    """Register ``cls`` under its declared ``name`` in :data:`OPERATORS`."""
+
+    name = getattr(cls, "name", None)
+    if not isinstance(name, str) or not name:
+        raise ValueError(
+            f"Operator {cls.__name__} must declare a non-empty 'name' attribute"
+        )
+
+    existing = OPERATORS.get(name)
+    if existing is not None and existing is not cls:
+        raise ValueError(f"Operator '{name}' is already registered")
+
+    OPERATORS[name] = cls
+    return cls
+
+
+def get_operator_class(name: str) -> type["Operator"]:
+    """Return the operator class registered for ``name`` or its canonical alias."""
+
+    try:
+        return OPERATORS[name]
+    except KeyError:
+        canonical = canonical_operator_name(name)
+        if canonical == name:
+            raise
+        try:
+            return OPERATORS[canonical]
+        except KeyError as exc:  # pragma: no cover - defensive branch
+            raise KeyError(name) from exc
+
+
+def discover_operators() -> None:
+    """Import all operator submodules so their decorators run."""
+
+    package = importlib.import_module("tnfr.operators")
+    package_path = getattr(package, "__path__", None)
+    if not package_path:
+        return
+
+    if getattr(package, "_operators_discovered", False):  # pragma: no cover - cache
+        return
+
+    prefix = f"{package.__name__}."
+    for module_info in pkgutil.walk_packages(package_path, prefix):
+        if module_info.name == f"{prefix}registry":
+            continue
+        importlib.import_module(module_info.name)
+
+    setattr(package, "_operators_discovered", True)
+
+
+__all__ = ("OPERATORS", "register_operator", "discover_operators", "get_operator_class")
+
+
+def __getattr__(name: str) -> Any:
+    """Provide guidance for legacy registry aliases."""
+
+    if name == "OPERADORES":
+        raise AttributeError(
+            f"module '{__name__}' has no attribute '{name}'; use 'OPERATORS' instead."
+        )
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

tnfr/operators/registry.pyi

@@ -0,0 +1,15 @@
+from typing import Any
+
+from .definitions import Operator
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+OPERATORS: dict[str, type[Operator]]
+
+def discover_operators() -> None: ...
+
+def register_operator(cls: type[Operator]) -> type[Operator]: ...
+
+def get_operator_class(name: str) -> type[Operator]: ...