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

tnfr/glyph_history.py

@@ -0,0 +1,337 @@
+"""Utilities for tracking glyph emission history and related metrics."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+from collections import deque, Counter
+from itertools import islice
+from collections.abc import Iterable, Mapping, MutableMapping
+
+from .constants import get_param, normalise_state_token
+from .utils import ensure_collection, get_logger, validate_window
+from .types import TNFRGraph
+
+logger = get_logger(__name__)
+
+__all__ = (
+    "HistoryDict",
+    "push_glyph",
+    "recent_glyph",
+    "ensure_history",
+    "current_step_idx",
+    "append_metric",
+    "last_glyph",
+    "count_glyphs",
+)
+
+
+def _ensure_history(
+    nd: MutableMapping[str, Any], window: int, *, create_zero: bool = False
+) -> tuple[int, deque[str] | None]:
+    """Validate ``window`` and ensure ``nd['glyph_history']`` deque."""
+
+    v_window = validate_window(window)
+    if v_window == 0 and not create_zero:
+        return v_window, None
+    hist = nd.setdefault("glyph_history", deque(maxlen=v_window))
+    if not isinstance(hist, deque) or hist.maxlen != v_window:
+        # Rebuild deque from any iterable, ignoring raw strings/bytes and scalars
+        if isinstance(hist, (str, bytes, bytearray)):
+            items: Iterable[Any] = ()
+        else:
+            try:
+                items = ensure_collection(hist, max_materialize=None)
+            except TypeError:
+                logger.debug(
+                    "Discarding non-iterable glyph history value %r", hist
+                )
+                items = ()
+        hist = deque((str(item) for item in items), maxlen=v_window)
+        nd["glyph_history"] = hist
+    return v_window, hist
+
+
+def push_glyph(nd: MutableMapping[str, Any], glyph: str, window: int) -> None:
+    """Add ``glyph`` to node history with maximum size ``window``.
+
+    ``window`` validation and deque creation are handled by
+    :func:`_ensure_history`.
+    """
+
+    _, hist = _ensure_history(nd, window, create_zero=True)
+    hist.append(str(glyph))
+
+
+def recent_glyph(
+    nd: MutableMapping[str, Any], glyph: str, window: int
+) -> bool:
+    """Return ``True`` if ``glyph`` appeared in last ``window`` emissions.
+
+    ``window`` validation and deque creation are handled by
+    :func:`_ensure_history`. A ``window`` of zero returns ``False`` and
+    leaves ``nd`` unchanged. Negative values raise :class:`ValueError`.
+    """
+
+    v_window, hist = _ensure_history(nd, window)
+    if v_window == 0:
+        return False
+    gl = str(glyph)
+    return gl in hist
+
+
+class HistoryDict(dict[str, Any]):
+    """Dict specialized for bounded history series and usage counts.
+
+    Usage counts are tracked explicitly via :meth:`get_increment`. Accessing
+    keys through ``__getitem__`` or :meth:`get` does not affect the internal
+    counters, avoiding surprising evictions on mere reads. Counting is now
+    handled with :class:`collections.Counter` alone, relying on
+    :meth:`Counter.most_common` to locate least-used entries when required.
+
+    Parameters
+    ----------
+    data:
+        Initial mapping to populate the dictionary.
+    maxlen:
+        Maximum length for history lists stored as values.
+    """
+
+    def __init__(
+        self,
+        data: Mapping[str, Any] | None = None,
+        *,
+        maxlen: int = 0,
+    ) -> None:
+        super().__init__(data or {})
+        self._maxlen = maxlen
+        self._counts: Counter[str] = Counter()
+        if self._maxlen > 0:
+            for k, v in list(self.items()):
+                if isinstance(v, list):
+                    super().__setitem__(k, deque(v, maxlen=self._maxlen))
+                self._counts[k] = 0
+        else:
+            for k in self:
+                self._counts[k] = 0
+        # ``_heap`` is no longer required with ``Counter.most_common``.
+
+    def _increment(self, key: str) -> None:
+        """Increase usage count for ``key``."""
+        self._counts[key] += 1
+
+    def _to_deque(self, val: Any) -> deque[Any]:
+        """Coerce ``val`` to a deque respecting ``self._maxlen``.
+
+        ``Iterable`` inputs (excluding ``str`` and ``bytes``) are expanded into
+        the deque, while single values are wrapped. Existing deques are
+        returned unchanged.
+        """
+
+        if isinstance(val, deque):
+            return val
+        if isinstance(val, Iterable) and not isinstance(val, (str, bytes)):
+            return deque(val, maxlen=self._maxlen)
+        return deque([val], maxlen=self._maxlen)
+
+    def _resolve_value(self, key: str, default: Any, *, insert: bool) -> Any:
+        if insert:
+            val = super().setdefault(key, default)
+        else:
+            val = super().__getitem__(key)
+        if self._maxlen > 0:
+            if not isinstance(val, Mapping):
+                val = self._to_deque(val)
+            super().__setitem__(key, val)
+        return val
+
+    def get_increment(self, key: str, default: Any = None) -> Any:
+        insert = key not in self
+        val = self._resolve_value(key, default, insert=insert)
+        self._increment(key)
+        return val
+
+    def __getitem__(self, key: str) -> Any:  # type: ignore[override]
+        return self._resolve_value(key, None, insert=False)
+
+    def get(self, key: str, default: Any | None = None) -> Any:  # type: ignore[override]
+        try:
+            return self._resolve_value(key, None, insert=False)
+        except KeyError:
+            return default
+
+    def __setitem__(self, key: str, value: Any) -> None:  # type: ignore[override]
+        super().__setitem__(key, value)
+        if key not in self._counts:
+            self._counts[key] = 0
+
+    def setdefault(self, key: str, default: Any | None = None) -> Any:  # type: ignore[override]
+        insert = key not in self
+        val = self._resolve_value(key, default, insert=insert)
+        if insert:
+            self._counts[key] = 0
+        return val
+
+    def pop_least_used(self) -> Any:
+        """Remove and return the value with the smallest usage count."""
+        while self._counts:
+            key = min(self._counts, key=self._counts.get)
+            self._counts.pop(key, None)
+            if key in self:
+                return super().pop(key)
+        raise KeyError("HistoryDict is empty; cannot pop least used")
+
+    def pop_least_used_batch(self, k: int) -> None:
+        for _ in range(max(0, int(k))):
+            try:
+                self.pop_least_used()
+            except KeyError:
+                break
+
+
+def ensure_history(G: TNFRGraph) -> HistoryDict | dict[str, Any]:
+    """Ensure ``G.graph['history']`` exists and return it.
+
+    ``HISTORY_MAXLEN`` must be non-negative; otherwise a
+    :class:`ValueError` is raised. When ``HISTORY_MAXLEN`` is zero, a regular
+    ``dict`` is used.
+    """
+    maxlen, _ = _ensure_history({}, int(get_param(G, "HISTORY_MAXLEN")))
+    hist = G.graph.get("history")
+    sentinel_key = "_metrics_history_id"
+    replaced = False
+    if maxlen == 0:
+        if isinstance(hist, HistoryDict):
+            hist = dict(hist)
+            G.graph["history"] = hist
+            replaced = True
+        elif hist is None:
+            hist = {}
+            G.graph["history"] = hist
+            replaced = True
+        if replaced:
+            G.graph.pop(sentinel_key, None)
+        if isinstance(hist, MutableMapping):
+            _normalise_state_streams(hist)
+        return hist
+    if (
+        not isinstance(hist, HistoryDict)
+        or hist._maxlen != maxlen
+    ):
+        hist = HistoryDict(hist, maxlen=maxlen)
+        G.graph["history"] = hist
+        replaced = True
+    excess = len(hist) - maxlen
+    if excess > 0:
+        hist.pop_least_used_batch(excess)
+    if replaced:
+        G.graph.pop(sentinel_key, None)
+    _normalise_state_streams(cast(MutableMapping[str, Any], hist))
+    return hist
+
+
+def current_step_idx(G: TNFRGraph | Mapping[str, Any]) -> int:
+    """Return the current step index from ``G`` history."""
+
+    graph = getattr(G, "graph", G)
+    return len(graph.get("history", {}).get("C_steps", []))
+
+
+def append_metric(
+    hist: MutableMapping[str, list[Any]], key: str, value: Any
+) -> None:
+    """Append ``value`` to ``hist[key]`` list, creating it if missing."""
+    if key == "phase_state" and isinstance(value, str):
+        value = normalise_state_token(value)
+    elif key == "nodal_diag" and isinstance(value, Mapping):
+        snapshot: dict[Any, Any] = {}
+        for node, payload in value.items():
+            if isinstance(payload, Mapping):
+                state_value = payload.get("state")
+                if isinstance(payload, MutableMapping):
+                    updated = payload
+                else:
+                    updated = dict(payload)
+                if isinstance(state_value, str):
+                    updated["state"] = normalise_state_token(state_value)
+                snapshot[node] = updated
+            else:
+                snapshot[node] = payload
+        hist.setdefault(key, []).append(snapshot)
+        return
+
+    hist.setdefault(key, []).append(value)
+
+
+def last_glyph(nd: Mapping[str, Any]) -> str | None:
+    """Return the most recent glyph for node or ``None``."""
+    hist = nd.get("glyph_history")
+    return hist[-1] if hist else None
+
+
+def count_glyphs(
+    G: TNFRGraph, window: int | None = None, *, last_only: bool = False
+) -> Counter[str]:
+    """Count recent glyphs in the network.
+
+    If ``window`` is ``None``, the full history for each node is used. A
+    ``window`` of zero yields an empty :class:`Counter`. Negative values raise
+    :class:`ValueError`.
+    """
+
+    if window is not None:
+        window = validate_window(window)
+        if window == 0:
+            return Counter()
+
+    counts: Counter[str] = Counter()
+    for _, nd in G.nodes(data=True):
+        if last_only:
+            g = last_glyph(nd)
+            if g:
+                counts[g] += 1
+            continue
+        hist = nd.get("glyph_history")
+        if not hist:
+            continue
+        if window is None:
+            seq = hist
+        else:
+            start = max(len(hist) - window, 0)
+            seq = islice(hist, start, None)
+        counts.update(seq)
+
+    return counts
+
+
+def _normalise_state_streams(hist: MutableMapping[str, Any]) -> None:
+    """Normalise legacy state tokens stored in telemetry history."""
+
+    phase_state = hist.get("phase_state")
+    if isinstance(phase_state, deque):
+        canonical = [normalise_state_token(str(item)) for item in phase_state]
+        if canonical != list(phase_state):
+            phase_state.clear()
+            phase_state.extend(canonical)
+    elif isinstance(phase_state, list):
+        canonical = [normalise_state_token(str(item)) for item in phase_state]
+        if canonical != phase_state:
+            hist["phase_state"] = canonical
+
+    diag_history = hist.get("nodal_diag")
+    if isinstance(diag_history, list):
+        for snapshot in diag_history:
+            if not isinstance(snapshot, Mapping):
+                continue
+            for node, payload in snapshot.items():
+                if not isinstance(payload, Mapping):
+                    continue
+                state_value = payload.get("state")
+                if not isinstance(state_value, str):
+                    continue
+                canonical = normalise_state_token(state_value)
+                if canonical == state_value:
+                    continue
+                if isinstance(payload, MutableMapping):
+                    payload["state"] = canonical
+                else:
+                    snapshot[node] = {**payload, "state": canonical}

tnfr/glyph_history.pyi

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Mapping, MutableMapping
+from typing import Any
+
+from .types import TNFRGraph
+
+__all__: tuple[str, ...]
+
+
+class HistoryDict(dict[str, Any]):
+    _maxlen: int
+    _counts: Counter[str]
+
+    def __init__(
+        self, data: Mapping[str, Any] | None = ..., *, maxlen: int = ...
+    ) -> None: ...
+
+    def get_increment(self, key: str, default: Any = ...) -> Any: ...
+    def __getitem__(self, key: str) -> Any: ...
+    def get(self, key: str, default: Any | None = ...) -> Any: ...
+    def __setitem__(self, key: str, value: Any) -> None: ...
+    def setdefault(self, key: str, default: Any | None = ...) -> Any: ...
+    def pop_least_used(self) -> Any: ...
+    def pop_least_used_batch(self, k: int) -> None: ...
+
+
+def push_glyph(nd: MutableMapping[str, Any], glyph: str, window: int) -> None: ...
+
+
+def recent_glyph(
+    nd: MutableMapping[str, Any], glyph: str, window: int
+) -> bool: ...
+
+
+def ensure_history(G: TNFRGraph) -> HistoryDict | dict[str, Any]: ...
+
+
+def current_step_idx(G: TNFRGraph | Mapping[str, Any]) -> int: ...
+
+
+def append_metric(
+    hist: MutableMapping[str, list[Any]], key: str, value: Any
+) -> None: ...
+
+
+def last_glyph(nd: Mapping[str, Any]) -> str | None: ...
+
+
+def count_glyphs(
+    G: TNFRGraph, window: int | None = ..., *, last_only: bool = ...
+) -> Counter[str]: ...

tnfr/grammar.py

@@ -1,155 +1,25 @@
-from __future__ import annotations
-from typing import Dict, Any, Set
-
-from .constants import (
-    DEFAULTS,
-    ALIAS_SI, ALIAS_DNFR, ALIAS_EPI,
+"""Backwards compatibility layer for grammar helpers.
+
+The canonical implementations now live in :mod:`tnfr.validation`.  This
+module only re-exports them to avoid breaking external callers until the
+new import paths are fully adopted.
+"""
+
+from .validation.compatibility import CANON_COMPAT, CANON_FALLBACK
+from .validation.grammar import (
+    GrammarContext,
+    apply_glyph_with_grammar,
+    enforce_canonical_grammar,
+    on_applied_glyph,
+    _gram_state,
 )
-from .helpers import _get_attr, clamp01, reciente_glifo
-from collections import deque
-
-# Glifos nominales (para evitar typos)
-AL = "A’L"; EN = "E’N"; IL = "I’L"; OZ = "O’Z"; UM = "U’M"; RA = "R’A"; SHA = "SH’A"; VAL = "VA’L"; NUL = "NU’L"; THOL = "T’HOL"; ZHIR = "Z’HIR"; NAV = "NA’V"; REMESH = "RE’MESH"
-
-# -------------------------
-# Estado de gramática por nodo
-# -------------------------
-
-def _gram_state(nd: Dict[str, Any]) -> Dict[str, Any]:
-    """Crea/retorna el estado de gramática nodal.
-    Campos:
-      - thol_open (bool)
-      - thol_len (int)
-    """
-    st = nd.setdefault("_GRAM", {"thol_open": False, "thol_len": 0})
-    st.setdefault("thol_open", False)
-    st.setdefault("thol_len", 0)
-    return st
-
-# -------------------------
-# Compatibilidades canónicas (siguiente permitido)
-# -------------------------
-CANON_COMPAT: Dict[str, Set[str]] = {
-    # Inicio / apertura
-    AL:   {EN, RA, NAV, VAL, UM},
-    EN:   {IL, UM, RA, NAV},
-    # Estabilización / difusión / acople
-    IL:   {RA, VAL, UM, SHA},
-    UM:   {RA, IL, VAL, NAV},
-    RA:   {IL, VAL, UM, NAV},
-    VAL:  {UM, RA, IL, NAV},
-    # Disonancia → transición → mutación
-    OZ:   {ZHIR, NAV},
-    ZHIR: {IL, NAV},
-    NAV:  {OZ, ZHIR, RA, IL, UM},
-    # Cierres / latencias
-    SHA:  {AL, EN},
-    NUL:  {AL, IL},
-    # Bloques autoorganizativos
-    THOL: {OZ, ZHIR, NAV, RA, IL, UM, SHA, NUL},
-}
-
-# Fallbacks canónicos si una transición no está permitida
-CANON_FALLBACK: Dict[str, str] = {
-    AL: EN, EN: IL, IL: RA, UM: RA, RA: IL, VAL: RA, OZ: ZHIR, ZHIR: IL, NAV: RA, SHA: AL, NUL: AL, THOL: NAV,
-}
-
-# -------------------------
-# Cierres T’HOL y precondiciones Z’HIR
-# -------------------------
-
-def _dnfr_norm(G, nd) -> float:
-    # Normalizador robusto: usa historial de |ΔNFR| máx guardado por dynamics (si existe)
-    norms = G.graph.get("_sel_norms") or {}
-    dmax = float(norms.get("dnfr_max", 1.0)) or 1.0
-    return clamp01(abs(_get_attr(nd, ALIAS_DNFR, 0.0)) / dmax)
-
-
-def _si(G, nd) -> float:
-    return clamp01(_get_attr(nd, ALIAS_SI, 0.5))
-
-# -------------------------
-# Núcleo: forzar gramática sobre un candidato
-# -------------------------
-
-def enforce_canonical_grammar(G, n, cand: str) -> str:
-    """Valida/ajusta el glifo candidato según la gramática canónica.
-
-    Reglas clave:
-      - Compatibilidades de transición glífica (recorrido TNFR).
-      - O’Z→Z’HIR: la mutación requiere disonancia reciente o |ΔNFR| alto.
-      - T’HOL[...]: obliga cierre con SH’A o NU’L cuando el campo se estabiliza
-        o se alcanza el largo del bloque; mantiene estado por nodo.
-
-    Devuelve el glifo efectivo a aplicar.
-    """
-    nd = G.nodes[n]
-    st = _gram_state(nd)
-    cfg = G.graph.get("GRAMMAR_CANON", DEFAULTS.get("GRAMMAR_CANON", {}))
-
-    # 0) Si vienen glifos fuera del alfabeto, no tocamos
-    if cand not in CANON_COMPAT:
-        return cand
-
-    # 1) Precondición O’Z→Z’HIR: mutación requiere disonancia reciente o campo fuerte
-    if cand == ZHIR:
-        win = int(cfg.get("zhir_requires_oz_window", 3))
-        dn_min = float(cfg.get("zhir_dnfr_min", 0.05))
-        if not reciente_glifo(nd, OZ, win) and _dnfr_norm(G, nd) < dn_min:
-            cand = OZ  # forzamos paso por O’Z
-
-    # 2) Si estamos dentro de T’HOL, control de cierre obligado
-    if st.get("thol_open", False):
-        st["thol_len"] = int(st.get("thol_len", 0))
-        st["thol_len"] += 1
-        minlen = int(cfg.get("thol_min_len", 2))
-        maxlen = int(cfg.get("thol_max_len", 6))
-        close_dn = float(cfg.get("thol_close_dnfr", 0.15))
-        if st["thol_len"] >= maxlen or (st["thol_len"] >= minlen and _dnfr_norm(G, nd) <= close_dn):
-            cand = NUL if _si(G, nd) >= float(cfg.get("si_high", 0.66)) else SHA
-
-    # 3) Compatibilidades: si el anterior restringe el siguiente
-    prev = None
-    hist = nd.get("hist_glifos")
-    if hist:
-        try:
-            prev = list(hist)[-1]
-        except Exception:
-            prev = None
-    if prev in CANON_COMPAT and cand not in CANON_COMPAT[prev]:
-        cand = CANON_FALLBACK.get(prev, cand)
-
-    return cand
-
-# -------------------------
-# Post-selección: actualizar estado de gramática
-# -------------------------
-
-def on_applied_glifo(G, n, applied: str) -> None:
-    nd = G.nodes[n]
-    st = _gram_state(nd)
-    if applied == THOL:
-        st["thol_open"] = True
-        st["thol_len"] = 0
-    elif applied in (SHA, NUL):
-        st["thol_open"] = False
-        st["thol_len"] = 0
-    else:
-        pass
-
-# -------------------------
-# Integración con dynamics.step: helper de selección+aplicación
-# -------------------------
-
-def select_and_apply_with_grammar(G, n, selector, window: int) -> None:
-    """Aplica gramática canónica sobre la propuesta del selector.
 
-    El selector puede incluir una gramática **suave** (pre–filtro) como
-    `parametric_glyph_selector`; la presente función garantiza que la
-    gramática canónica tenga precedencia final.
-    """
-    from .operators import aplicar_glifo
-    cand = selector(G, n)
-    cand = enforce_canonical_grammar(G, n, cand)
-    aplicar_glifo(G, n, cand, window=window)
-    on_applied_glifo(G, n, cand)
+__all__ = [
+    "GrammarContext",
+    "CANON_COMPAT",
+    "CANON_FALLBACK",
+    "enforce_canonical_grammar",
+    "on_applied_glyph",
+    "apply_glyph_with_grammar",
+    "_gram_state",
+]

tnfr/grammar.pyi

@@ -0,0 +1,13 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+CANON_COMPAT: Any
+CANON_FALLBACK: Any
+GrammarContext: Any
+_gram_state: Any
+apply_glyph_with_grammar: Any
+enforce_canonical_grammar: Any
+on_applied_glyph: Any