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

tnfr/dynamics/sampling.py

@@ -1,3 +1,5 @@
+"""Sampling helpers used by runtime selectors and glyph application."""
+
 from __future__ import annotations
 
 from typing import cast

tnfr/dynamics/selectors.py

@@ -3,33 +3,36 @@
 from __future__ import annotations
 
 import math
-from abc import ABC, abstractmethod
 import sys
+from abc import ABC, abstractmethod
 from collections.abc import Mapping, MutableMapping, Sequence
 from concurrent.futures import ProcessPoolExecutor
 from dataclasses import dataclass
 from operator import itemgetter
 from typing import Any, cast
-
 from ..alias import collect_attr, get_attr
 from ..constants import get_graph_param, get_param
-from ..glyph_history import ensure_history, recent_glyph
-from ..helpers.numeric import clamp01
+from ..glyph_history import ensure_history
+from ..utils import clamp01, resolve_chunk_size
 from ..metrics.common import compute_dnfr_accel_max, merge_and_normalize_weights
 from ..operators import apply_glyph
+from ..validation import (
+    GrammarContext,
+    StructuralGrammarError,
+    enforce_canonical_grammar,
+    on_applied_glyph,
+    record_grammar_violation,
+)
 from ..selector import (
     _apply_selector_hysteresis,
     _calc_selector_score,
     _selector_norms,
     _selector_thresholds,
 )
-from ..types import Glyph, GlyphSelector, HistoryState, NodeId, TNFRGraph
+from ..types import Glyph, GlyphCode, GlyphSelector, HistoryState, NodeId, TNFRGraph
 from ..utils import get_numpy
-from ..validation.grammar import enforce_canonical_grammar, on_applied_glyph
+from ..validation import soft_grammar_filters
 from .aliases import ALIAS_D2EPI, ALIAS_DNFR, ALIAS_DSI, ALIAS_SI
-from .._compat import TypeAlias
-
-GlyphCode: TypeAlias = Glyph | str
 
 __all__ = (
     "GlyphCode",
@@ -92,23 +95,12 @@ def _soft_grammar_prefilter(
     G: TNFRGraph,
     n: NodeId,
     cand: GlyphCode,
-    dnfr: float,
-    accel: float,
 ) -> GlyphCode:
     """Soft grammar: avoid repetitions before the canonical one."""
 
-    gram = get_graph_param(G, "GRAMMAR", dict)
-    gwin = int(gram.get("window", 3))
-    avoid = {str(item) for item in gram.get("avoid_repeats", [])}
-    force_dn = float(gram.get("force_dnfr", 0.60))
-    force_ac = float(gram.get("force_accel", 0.60))
-    fallbacks = cast(Mapping[str, GlyphCode], gram.get("fallbacks", {}))
-    nd = G.nodes[n]
-    cand_key = str(cand)
-    if cand_key in avoid and recent_glyph(nd, cand_key, gwin):
-        if not (dnfr >= force_dn or accel >= force_ac):
-            cand = fallbacks.get(cand_key, cand)
-    return cand
+    ctx = GrammarContext.from_graph(G)
+    filtered = soft_grammar_filters(ctx, n, cand)
+    return cast(GlyphCode, filtered)
 
 
 def _selector_normalized_metrics(
@@ -125,9 +117,9 @@ def _selector_normalized_metrics(
 def _selector_base_choice(
     Si: float, dnfr: float, accel: float, thr: Mapping[str, float]
 ) -> GlyphCode:
-    si_hi, si_lo, dnfr_hi, acc_hi = itemgetter(
-        "si_hi", "si_lo", "dnfr_hi", "accel_hi"
-    )(thr)
+    si_hi, si_lo, dnfr_hi, acc_hi = itemgetter("si_hi", "si_lo", "dnfr_hi", "accel_hi")(
+        thr
+    )
     if Si >= si_hi:
         return "IL"
     if Si <= si_lo:
@@ -140,6 +132,8 @@ def _selector_base_choice(
 
 
 def _configure_selector_weights(G: TNFRGraph) -> Mapping[str, float]:
+    """Load and cache selector weight configuration from graph parameters."""
+
     weights = merge_and_normalize_weights(
         G, "SELECTOR_WEIGHTS", ("w_si", "w_dnfr", "w_accel")
     )
@@ -202,11 +196,13 @@ def _parametric_selector_logic(G: TNFRGraph, n: NodeId) -> GlyphCode:
 
     cand = _apply_score_override(cand, score, dnfr, thr["dnfr_lo"])
 
-    return _soft_grammar_prefilter(G, n, cand, dnfr, accel)
+    return _soft_grammar_prefilter(G, n, cand)
 
 
 @dataclass(slots=True)
 class _SelectorPreselection:
+    """Precomputed selector context shared across glyph decisions."""
+
     kind: str
     metrics: Mapping[Any, tuple[float, float, float]]
     base_choices: Mapping[Any, GlyphCode]
@@ -265,10 +261,14 @@ class DefaultGlyphSelector(AbstractSelector):
         self._prepared_graph_id: int | None = None
 
     def prepare(self, graph: TNFRGraph, nodes: Sequence[NodeId]) -> None:
+        """Precompute default selector metrics for ``nodes``."""
+
         self._preselection = _build_default_preselection(graph, nodes)
         self._prepared_graph_id = id(graph)
 
     def select(self, graph: TNFRGraph, node: NodeId) -> GlyphCode:
+        """Return the canonical glyph for ``node`` using cached metrics when available."""
+
         if self._prepared_graph_id == id(graph):
             preselection = self._preselection
         else:
@@ -288,12 +288,16 @@ class ParametricGlyphSelector(AbstractSelector):
         self._prepared_graph_id: int | None = None
 
     def prepare(self, graph: TNFRGraph, nodes: Sequence[NodeId]) -> None:
+        """Precompute parametric selector metrics and hysteresis thresholds."""
+
         _selector_norms(graph)
         _configure_selector_weights(graph)
         self._preselection = _build_param_preselection(graph, nodes)
         self._prepared_graph_id = id(graph)
 
     def select(self, graph: TNFRGraph, node: NodeId) -> GlyphCode:
+        """Return the parametric glyph decision for ``node``."""
+
         if self._prepared_graph_id == id(graph):
             preselection = self._preselection
         else:
@@ -317,17 +321,29 @@ def _choose_glyph(
     al_max: int,
     en_max: int,
 ) -> GlyphCode:
+    """Return glyph for ``n`` considering forced lags and canonical grammar."""
+
     if h_al[n] > al_max:
         return Glyph.AL
     if h_en[n] > en_max:
         return Glyph.EN
     g = selector(G, n)
     if use_canon:
-        g = enforce_canonical_grammar(G, n, g)
+        try:
+            g = enforce_canonical_grammar(G, n, g)
+        except StructuralGrammarError as err:
+            nd = G.nodes[n]
+            history = tuple(str(item) for item in nd.get("glyph_history", ()))
+            selector_name = getattr(selector, "__name__", selector.__class__.__name__)
+            err.attach_context(node=n, selector=selector_name, history=history, stage="selector")
+            record_grammar_violation(G, n, err, stage="selector")
+            raise
     return g
 
 
 def _selector_parallel_jobs(G: TNFRGraph) -> int | None:
+    """Return worker count for selector helpers when parallelism is enabled."""
+
     raw_jobs = G.graph.get("GLYPH_SELECTOR_N_JOBS")
     try:
         n_jobs = None if raw_jobs is None else int(raw_jobs)
@@ -339,8 +355,10 @@ def _selector_parallel_jobs(G: TNFRGraph) -> int | None:
 
 
 def _selector_metrics_chunk(
-    args: tuple[list[float], list[float], list[float], float, float]
+    args: tuple[list[float], list[float], list[float], float, float],
 ) -> tuple[list[float], list[float], list[float]]:
+    """Normalise metric chunk values for multiprocessing execution."""
+
     si_values, dnfr_values, accel_values, dnfr_max, accel_max = args
     si_seq = [clamp01(float(v)) for v in si_values]
     dnfr_seq = [abs(float(v)) / dnfr_max for v in dnfr_values]
@@ -354,6 +372,8 @@ def _collect_selector_metrics(
     norms: Mapping[str, float],
     n_jobs: int | None = None,
 ) -> dict[Any, tuple[float, float, float]]:
+    """Return normalised (Si, ΔNFR, acceleration) triples for ``nodes``."""
+
     if not nodes:
         return {}
 
@@ -369,12 +389,16 @@ def _collect_selector_metrics(
     if np_mod is not None:
         si_seq_np = collect_attr(G, nodes, ALIAS_SI, 0.5, np=np_mod).astype(float)
         si_seq_np = np_mod.clip(si_seq_np, 0.0, 1.0)
-        dnfr_seq_np = np_mod.abs(
-            collect_attr(G, nodes, ALIAS_DNFR, 0.0, np=np_mod).astype(float)
-        ) / dnfr_max
-        accel_seq_np = np_mod.abs(
-            collect_attr(G, nodes, ALIAS_D2EPI, 0.0, np=np_mod).astype(float)
-        ) / accel_max
+        dnfr_seq_np = (
+            np_mod.abs(collect_attr(G, nodes, ALIAS_DNFR, 0.0, np=np_mod).astype(float))
+            / dnfr_max
+        )
+        accel_seq_np = (
+            np_mod.abs(
+                collect_attr(G, nodes, ALIAS_D2EPI, 0.0, np=np_mod).astype(float)
+            )
+            / accel_max
+        )
 
         si_seq = si_seq_np.tolist()
         dnfr_seq = dnfr_seq_np.tolist()
@@ -390,7 +414,12 @@ def _collect_selector_metrics(
             dnfr_seq = [abs(float(v)) / dnfr_max for v in dnfr_values]
             accel_seq = [abs(float(v)) / accel_max for v in accel_values]
         else:
-            chunk_size = max(1, math.ceil(len(nodes) / worker_count))
+            approx_chunk = math.ceil(len(nodes) / worker_count) if worker_count else None
+            chunk_size = resolve_chunk_size(
+                approx_chunk,
+                len(nodes),
+                minimum=1,
+            )
             chunk_bounds = [
                 (start, min(start + chunk_size, len(nodes)))
                 for start in range(0, len(nodes), chunk_size)
@@ -400,7 +429,9 @@ def _collect_selector_metrics(
             dnfr_seq = []
             accel_seq = []
 
-            def _args_iter() -> Sequence[tuple[list[float], list[float], list[float], float, float]]:
+            def _args_iter() -> (
+                Sequence[tuple[list[float], list[float], list[float], float, float]]
+            ):
                 for start, end in chunk_bounds:
                     yield (
                         si_values[start:end],
@@ -449,7 +480,7 @@ def _compute_default_base_choices(
 
 
 def _param_base_worker(
-    args: tuple[Mapping[str, float], list[tuple[Any, tuple[float, float, float]]]]
+    args: tuple[Mapping[str, float], list[tuple[Any, tuple[float, float, float]]]],
 ) -> list[tuple[Any, str]]:
     thresholds, chunk = args
     return [
@@ -473,11 +504,13 @@ def _compute_param_base_choices(
             for node, (Si, dnfr, accel) in items
         }
 
-    chunk_size = max(1, math.ceil(len(items) / n_jobs))
-    chunks = [
-        items[i : i + chunk_size]
-        for i in range(0, len(items), chunk_size)
-    ]
+    approx_chunk = math.ceil(len(items) / n_jobs) if n_jobs else None
+    chunk_size = resolve_chunk_size(
+        approx_chunk,
+        len(items),
+        minimum=1,
+    )
+    chunks = [items[i : i + chunk_size] for i in range(0, len(items), chunk_size)]
     base: dict[Any, str] = {}
     args = ((thresholds, chunk) for chunk in chunks)
     executor_cls = ProcessPoolExecutor
@@ -498,6 +531,8 @@ def _prepare_selector_preselection(
     selector: GlyphSelector,
     nodes: Sequence[NodeId],
 ) -> _SelectorPreselection | None:
+    """Build cached selector metrics when ``selector`` supports them."""
+
     if selector is default_glyph_selector:
         return _build_default_preselection(G, nodes)
     if selector is parametric_glyph_selector:
@@ -511,6 +546,8 @@ def _resolve_preselected_glyph(
     selector: GlyphSelector,
     preselection: _SelectorPreselection | None,
 ) -> GlyphCode:
+    """Return glyph for ``n`` using ``preselection`` shortcuts when possible."""
+
     if preselection is None:
         return selector(G, n)
 
@@ -534,15 +571,13 @@ def _resolve_preselected_glyph(
             cand = _selector_base_choice(Si, dnfr, accel, thresholds)
 
         nd = G.nodes[n]
-        hist_cand = _apply_selector_hysteresis(
-            nd, Si, dnfr, accel, thresholds, margin
-        )
+        hist_cand = _apply_selector_hysteresis(nd, Si, dnfr, accel, thresholds, margin)
         if hist_cand is not None:
             return hist_cand
 
         score = _compute_selector_score(G, nd, Si, dnfr, accel, cand)
         cand = _apply_score_override(cand, score, dnfr, thresholds["dnfr_lo"])
-        return _soft_grammar_prefilter(G, n, cand, dnfr, accel)
+        return _soft_grammar_prefilter(G, n, cand)
 
     return selector(G, n)
 
@@ -553,20 +588,19 @@ def _glyph_proposal_worker(
         TNFRGraph,
         GlyphSelector,
         _SelectorPreselection | None,
-    ]
+    ],
 ) -> list[tuple[NodeId, GlyphCode]]:
     nodes, G, selector, preselection = args
     return [
-        (n, _resolve_preselected_glyph(G, n, selector, preselection))
-        for n in nodes
+        (n, _resolve_preselected_glyph(G, n, selector, preselection)) for n in nodes
     ]
 
 
 def _apply_glyphs(G: TNFRGraph, selector: GlyphSelector, hist: HistoryState) -> None:
+    """Apply glyph decisions across the graph updating hysteresis trackers."""
+
     window = int(get_param(G, "GLYPH_HYSTERESIS_WINDOW"))
-    use_canon = bool(
-        get_graph_param(G, "GRAMMAR_CANON", dict).get("enabled", False)
-    )
+    use_canon = bool(get_graph_param(G, "GRAMMAR_CANON", dict).get("enabled", False))
     al_max = get_graph_param(G, "AL_MAX_LAG", int)
     en_max = get_graph_param(G, "EN_MAX_LAG", int)
 
@@ -601,11 +635,14 @@ def _apply_glyphs(G: TNFRGraph, selector: GlyphSelector, hist: HistoryState) ->
         n_jobs = _selector_parallel_jobs(G)
         if n_jobs is None:
             for n in to_select:
-                decisions[n] = _resolve_preselected_glyph(
-                    G, n, selector, preselection
-                )
+                decisions[n] = _resolve_preselected_glyph(G, n, selector, preselection)
         else:
-            chunk_size = max(1, math.ceil(len(to_select) / n_jobs))
+            approx_chunk = math.ceil(len(to_select) / n_jobs) if n_jobs else None
+            chunk_size = resolve_chunk_size(
+                approx_chunk,
+                len(to_select),
+                minimum=1,
+            )
             chunks = [
                 to_select[idx : idx + chunk_size]
                 for idx in range(0, len(to_select), chunk_size)
@@ -617,9 +654,7 @@ def _apply_glyphs(G: TNFRGraph, selector: GlyphSelector, hist: HistoryState) ->
                     dynamics_module, "ProcessPoolExecutor", ProcessPoolExecutor
                 )
             with executor_cls(max_workers=n_jobs) as executor:
-                args_iter = (
-                    (chunk, G, selector, preselection) for chunk in chunks
-                )
+                args_iter = ((chunk, G, selector, preselection) for chunk in chunks)
                 for results in executor.map(_glyph_proposal_worker, args_iter):
                     for node, glyph in results:
                         decisions[node] = glyph
@@ -657,6 +692,8 @@ def _apply_glyphs(G: TNFRGraph, selector: GlyphSelector, hist: HistoryState) ->
 
 
 def _apply_selector(G: TNFRGraph) -> GlyphSelector:
+    """Resolve the glyph selector callable configured on ``G``."""
+
     raw_selector = G.graph.get("glyph_selector")
 
     selector: GlyphSelector
@@ -673,8 +710,10 @@ def _apply_selector(G: TNFRGraph) -> GlyphSelector:
     else:
         selector = default_glyph_selector
 
-    if isinstance(selector, ParametricGlyphSelector) or selector is parametric_glyph_selector:
+    if (
+        isinstance(selector, ParametricGlyphSelector)
+        or selector is parametric_glyph_selector
+    ):
         _selector_norms(G)
         _configure_selector_weights(G)
     return selector
-

tnfr/execution.py

@@ -7,15 +7,14 @@ from collections.abc import Callable, Iterable, Sequence
 from typing import Any, Optional, cast
 
 from ._compat import TypeAlias
-
-from .utils import MAX_MATERIALIZE_DEFAULT, ensure_collection, is_non_string_sequence
 from .constants import get_param
 from .dynamics import step
 from .flatten import _flatten
 from .glyph_history import ensure_history
-from .validation.grammar import apply_glyph_with_grammar
-from .tokens import OpTag, TARGET, THOL, WAIT, Token
+from .tokens import TARGET, THOL, WAIT, OpTag, Token
 from .types import Glyph, NodeId, TNFRGraph
+from .utils import MAX_MATERIALIZE_DEFAULT, ensure_collection, is_non_string_sequence
+from .validation import apply_glyph_with_grammar
 
 AdvanceFn = Callable[[TNFRGraph], None]
 TraceEntry = dict[str, Any]
@@ -72,6 +71,8 @@ def _advance(G: TNFRGraph, step_fn: AdvanceFn) -> None:
 
 
 def _record_trace(trace: ProgramTrace, G: TNFRGraph, op: OpTag, **data: Any) -> None:
+    """Append an operation snapshot to ``trace`` using graph time metadata."""
+
     trace.append({"t": float(G.graph.get("_t", 0.0)), "op": op.name, **data})
 
 
@@ -189,25 +190,31 @@ def compile_sequence(
 
 
 def seq(*tokens: Token) -> list[Token]:
+    """Return a mutable list of ``tokens`` for explicit sequence editing."""
+
     return list(tokens)
 
 
-def block(
-    *tokens: Token, repeat: int = 1, close: Optional[Glyph] = None
-) -> THOL:
+def block(*tokens: Token, repeat: int = 1, close: Optional[Glyph] = None) -> THOL:
+    """Build a THOL block with optional repetition and forced closure."""
+
     return THOL(body=list(tokens), repeat=repeat, force_close=close)
 
 
 def target(nodes: Optional[Iterable[NodeId]] = None) -> TARGET:
+    """Return a TARGET token selecting ``nodes`` (defaults to all nodes)."""
+
     return TARGET(nodes=nodes)
 
 
 def wait(steps: int = 1) -> WAIT:
+    """Return a WAIT token forcing ``steps`` structural updates before resuming."""
+
     return WAIT(steps=max(1, int(steps)))
 
 
 def basic_canonical_example() -> list[Token]:
-    """Reference canonical sequence.
+    """Return the canonical preset sequence.
 
     Returns a copy of the canonical preset tokens to keep CLI defaults aligned
     with :func:`tnfr.config.presets.get_preset`.

tnfr/execution.pyi

@@ -5,16 +5,13 @@ from collections.abc import Callable, Iterable, Sequence
 from typing import Any, Optional
 
 from ._compat import TypeAlias
-
-from .tokens import OpTag, TARGET, THOL, WAIT, Token
+from .tokens import TARGET, THOL, WAIT, OpTag, Token
 from .types import Glyph, NodeId, TNFRGraph
 
 __all__: list[str]
 
-
 def __getattr__(name: str) -> Any: ...
 
-
 AdvanceFn = Callable[[TNFRGraph], None]
 TraceEntry = dict[str, Any]
 ProgramTrace: TypeAlias = deque[TraceEntry]
@@ -27,39 +24,22 @@ CANONICAL_PRESET_NAME: str
 CANONICAL_PROGRAM_TOKENS: tuple[Token, ...]
 HANDLERS: dict[OpTag, HandlerFn]
 
-
 def _apply_glyph_to_targets(
     G: TNFRGraph, g: Glyph | str, nodes: Iterable[NodeId] | None = ...
 ) -> None: ...
-
-
-def _record_trace(trace: ProgramTrace, G: TNFRGraph, op: OpTag, **data: Any) -> None: ...
-
-
+def _record_trace(
+    trace: ProgramTrace, G: TNFRGraph, op: OpTag, **data: Any
+) -> None: ...
 def compile_sequence(
     sequence: Iterable[Token] | Sequence[Token] | Any,
     *,
     max_materialize: int | None = ...,
 ) -> list[tuple[OpTag, Any]]: ...
-
-
 def play(
     G: TNFRGraph, sequence: Sequence[Token], step_fn: Optional[AdvanceFn] = ...
 ) -> None: ...
-
-
 def seq(*tokens: Token) -> list[Token]: ...
-
-
-def block(
-    *tokens: Token, repeat: int = ..., close: Glyph | None = ...
-) -> THOL: ...
-
-
+def block(*tokens: Token, repeat: int = ..., close: Glyph | None = ...) -> THOL: ...
 def target(nodes: Iterable[NodeId] | None = ...) -> TARGET: ...
-
-
 def wait(steps: int = ...) -> WAIT: ...
-
-
 def basic_canonical_example() -> list[Token]: ...

tnfr/flatten.py

@@ -7,6 +7,9 @@ from dataclasses import dataclass
 from itertools import chain
 from typing import Any, Callable
 
+from .config.constants import GLYPHS_CANONICAL_SET
+from .tokens import TARGET, THOL, THOL_SENTINEL, WAIT, OpTag, Token
+from .types import Glyph
 from .utils import (
     MAX_MATERIALIZE_DEFAULT,
     STRING_TYPES,
@@ -14,9 +17,6 @@ from .utils import (
     flatten_structure,
     normalize_materialize_limit,
 )
-from .config.constants import GLYPHS_CANONICAL_SET
-from .tokens import THOL, TARGET, WAIT, OpTag, THOL_SENTINEL, Token
-from .types import Glyph
 
 __all__ = [
     "THOLEvaluator",
@@ -124,9 +124,13 @@ class THOLEvaluator:
         self._started = False
 
     def __iter__(self) -> "THOLEvaluator":
+        """Return the evaluator itself to stream THOL expansion."""
+
         return self
 
     def __next__(self) -> Token | object:
+        """Yield the next token or :data:`THOL_SENTINEL` during evaluation."""
+
         if not self._started:
             self._started = True
             return THOL_SENTINEL

tnfr/flatten.pyi

@@ -7,20 +7,13 @@ from .tokens import THOL, Token
 
 __all__: list[str]
 
-
 def __getattr__(name: str) -> Any: ...
 
-
 class THOLEvaluator(Iterator[Token | object]):
-    def __init__(
-        self, item: THOL, *, max_materialize: int | None = ...
-    ) -> None: ...
-
+    def __init__(self, item: THOL, *, max_materialize: int | None = ...) -> None: ...
     def __iter__(self) -> THOLEvaluator: ...
-
     def __next__(self) -> Token | object: ...
 
-
 def parse_program_tokens(
     obj: Iterable[Any] | Sequence[Any] | Any,
     *,