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

tnfr/execution.py

@@ -0,0 +1,216 @@
+"""Execution helpers for canonical TNFR programs."""
+
+from __future__ import annotations
+
+from collections import deque
+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 .types import Glyph, NodeId, TNFRGraph
+
+AdvanceFn = Callable[[TNFRGraph], None]
+TraceEntry = dict[str, Any]
+ProgramTrace: TypeAlias = deque[TraceEntry]
+HandlerFn = Callable[
+    [TNFRGraph, Any, Optional[Sequence[NodeId]], ProgramTrace, AdvanceFn],
+    Optional[Sequence[NodeId]],
+]
+
+__all__ = [
+    "AdvanceFn",
+    "CANONICAL_PRESET_NAME",
+    "CANONICAL_PROGRAM_TOKENS",
+    "HANDLERS",
+    "_apply_glyph_to_targets",
+    "_record_trace",
+    "compile_sequence",
+    "basic_canonical_example",
+    "block",
+    "play",
+    "seq",
+    "target",
+    "wait",
+]
+
+
+CANONICAL_PRESET_NAME = "canonical_example"
+CANONICAL_PROGRAM_TOKENS: tuple[Token, ...] = (
+    Glyph.SHA,
+    Glyph.AL,
+    Glyph.RA,
+    Glyph.ZHIR,
+    Glyph.NUL,
+    Glyph.THOL,
+)
+
+
+def _window(G: TNFRGraph) -> int:
+    return int(get_param(G, "GLYPH_HYSTERESIS_WINDOW"))
+
+
+def _apply_glyph_to_targets(
+    G: TNFRGraph, g: Glyph | str, nodes: Optional[Iterable[NodeId]] = None
+) -> None:
+    """Apply ``g`` to ``nodes`` (or all nodes) respecting the grammar."""
+
+    nodes_iter = G.nodes() if nodes is None else nodes
+    w = _window(G)
+    apply_glyph_with_grammar(G, nodes_iter, g, w)
+
+
+def _advance(G: TNFRGraph, step_fn: AdvanceFn) -> None:
+    step_fn(G)
+
+
+def _record_trace(trace: ProgramTrace, G: TNFRGraph, op: OpTag, **data: Any) -> None:
+    trace.append({"t": float(G.graph.get("_t", 0.0)), "op": op.name, **data})
+
+
+def _advance_and_record(
+    G: TNFRGraph,
+    trace: ProgramTrace,
+    label: OpTag,
+    step_fn: AdvanceFn,
+    *,
+    times: int = 1,
+    **data: Any,
+) -> None:
+    for _ in range(times):
+        _advance(G, step_fn)
+    _record_trace(trace, G, label, **data)
+
+
+def _handle_target(
+    G: TNFRGraph,
+    payload: TARGET,
+    _curr_target: Optional[Sequence[NodeId]],
+    trace: ProgramTrace,
+    _step_fn: AdvanceFn,
+) -> Sequence[NodeId]:
+    """Handle a ``TARGET`` token and return the active node set."""
+
+    nodes_src = G.nodes() if payload.nodes is None else payload.nodes
+    nodes = ensure_collection(nodes_src, max_materialize=None)
+    if is_non_string_sequence(nodes):
+        curr_target = cast(Sequence[NodeId], nodes)
+    else:
+        curr_target = tuple(nodes)
+    _record_trace(trace, G, OpTag.TARGET, n=len(curr_target))
+    return curr_target
+
+
+def _handle_wait(
+    G: TNFRGraph,
+    steps: int,
+    curr_target: Optional[Sequence[NodeId]],
+    trace: ProgramTrace,
+    step_fn: AdvanceFn,
+) -> Optional[Sequence[NodeId]]:
+    _advance_and_record(G, trace, OpTag.WAIT, step_fn, times=steps, k=steps)
+    return curr_target
+
+
+def _handle_glyph(
+    G: TNFRGraph,
+    g: Glyph | str,
+    curr_target: Optional[Sequence[NodeId]],
+    trace: ProgramTrace,
+    step_fn: AdvanceFn,
+    label: OpTag = OpTag.GLYPH,
+) -> Optional[Sequence[NodeId]]:
+    _apply_glyph_to_targets(G, g, curr_target)
+    _advance_and_record(G, trace, label, step_fn, g=g)
+    return curr_target
+
+
+def _handle_thol(
+    G: TNFRGraph,
+    g: Glyph | str | None,
+    curr_target: Optional[Sequence[NodeId]],
+    trace: ProgramTrace,
+    step_fn: AdvanceFn,
+) -> Optional[Sequence[NodeId]]:
+    return _handle_glyph(
+        G, g or Glyph.THOL.value, curr_target, trace, step_fn, label=OpTag.THOL
+    )
+
+
+HANDLERS: dict[OpTag, HandlerFn] = {
+    OpTag.TARGET: _handle_target,
+    OpTag.WAIT: _handle_wait,
+    OpTag.GLYPH: _handle_glyph,
+    OpTag.THOL: _handle_thol,
+}
+
+
+def play(
+    G: TNFRGraph, sequence: Sequence[Token], step_fn: Optional[AdvanceFn] = None
+) -> None:
+    """Execute a canonical sequence on graph ``G``."""
+
+    step_fn = step_fn or step
+
+    curr_target: Optional[Sequence[NodeId]] = None
+
+    history = ensure_history(G)
+    maxlen = int(get_param(G, "PROGRAM_TRACE_MAXLEN"))
+    trace_obj = history.get("program_trace")
+    trace: ProgramTrace
+    if not isinstance(trace_obj, deque) or trace_obj.maxlen != maxlen:
+        trace = cast(ProgramTrace, deque(trace_obj or [], maxlen=maxlen))
+        history["program_trace"] = trace
+    else:
+        trace = cast(ProgramTrace, trace_obj)
+
+    for op, payload in _flatten(sequence):
+        handler: HandlerFn | None = HANDLERS.get(op)
+        if handler is None:
+            raise ValueError(f"Unknown operation: {op}")
+        curr_target = handler(G, payload, curr_target, trace, step_fn)
+
+
+def compile_sequence(
+    sequence: Iterable[Token] | Sequence[Token] | Any,
+    *,
+    max_materialize: int | None = MAX_MATERIALIZE_DEFAULT,
+) -> list[tuple[OpTag, Any]]:
+    """Return the operations executed by :func:`play` for ``sequence``."""
+
+    return _flatten(sequence, max_materialize=max_materialize)
+
+
+def seq(*tokens: Token) -> list[Token]:
+    return list(tokens)
+
+
+def block(
+    *tokens: Token, repeat: int = 1, close: Optional[Glyph] = None
+) -> THOL:
+    return THOL(body=list(tokens), repeat=repeat, force_close=close)
+
+
+def target(nodes: Optional[Iterable[NodeId]] = None) -> TARGET:
+    return TARGET(nodes=nodes)
+
+
+def wait(steps: int = 1) -> WAIT:
+    return WAIT(steps=max(1, int(steps)))
+
+
+def basic_canonical_example() -> list[Token]:
+    """Reference canonical sequence.
+
+    Returns a copy of the canonical preset tokens to keep CLI defaults aligned
+    with :func:`tnfr.config.presets.get_preset`.
+    """
+
+    return list(CANONICAL_PROGRAM_TOKENS)

tnfr/execution.pyi

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from collections import deque
+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 .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]
+HandlerFn = Callable[
+    [TNFRGraph, Any, Sequence[NodeId] | None, ProgramTrace, AdvanceFn],
+    Sequence[NodeId] | None,
+]
+
+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 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 target(nodes: Iterable[NodeId] | None = ...) -> TARGET: ...
+
+
+def wait(steps: int = ...) -> WAIT: ...
+
+
+def basic_canonical_example() -> list[Token]: ...

tnfr/flatten.py

@@ -0,0 +1,283 @@
+"""Flattening utilities to compile TNFR token sequences."""
+
+from __future__ import annotations
+
+from collections.abc import Collection, Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from itertools import chain
+from typing import Any, Callable
+
+from .utils import (
+    MAX_MATERIALIZE_DEFAULT,
+    STRING_TYPES,
+    ensure_collection,
+    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",
+    "parse_program_tokens",
+]
+
+
+@dataclass
+class TholFrame:
+    """Execution frame used to evaluate nested THOL blocks."""
+
+    seq: Sequence[Token]
+    index: int
+    remaining: int
+    closing: Glyph | None
+
+
+def _iter_source(
+    seq: Iterable[Token] | Sequence[Token] | Any,
+    *,
+    max_materialize: int | None,
+) -> Iterable[Any]:
+    """Yield items from ``seq`` enforcing ``max_materialize`` when needed."""
+
+    if isinstance(seq, Collection) and not isinstance(seq, STRING_TYPES):
+        return seq
+
+    if isinstance(seq, STRING_TYPES):
+        return (seq,)
+
+    if not isinstance(seq, Iterable):
+        raise TypeError(f"{seq!r} is not iterable")
+
+    limit = normalize_materialize_limit(max_materialize)
+    if limit is None:
+        return seq
+    if limit == 0:
+        return ()
+
+    iterator = iter(seq)
+
+    def _preview() -> Iterable[Any]:
+        for idx, item in enumerate(iterator):
+            yield item
+            if idx >= limit:
+                break
+
+    preview = ensure_collection(
+        _preview(),
+        max_materialize=limit,
+    )
+
+    if not preview:
+        return ()
+
+    return chain(preview, iterator)
+
+
+def _push_thol_frame(
+    frames: list[TholFrame],
+    item: THOL,
+    *,
+    max_materialize: int | None,
+) -> None:
+    """Validate ``item`` and append a frame for its evaluation."""
+
+    repeats = int(item.repeat)
+    if repeats < 1:
+        raise ValueError("repeat must be ≥1")
+    if item.force_close is not None and not isinstance(item.force_close, Glyph):
+        raise ValueError("force_close must be a Glyph")
+    closing = (
+        item.force_close
+        if isinstance(item.force_close, Glyph)
+        and item.force_close in {Glyph.SHA, Glyph.NUL}
+        else None
+    )
+    seq0 = ensure_collection(
+        item.body,
+        max_materialize=max_materialize,
+        error_msg=f"THOL body exceeds max_materialize={max_materialize}",
+    )
+    frames.append(
+        TholFrame(
+            seq=seq0,
+            index=0,
+            remaining=repeats,
+            closing=closing,
+        )
+    )
+
+
+class THOLEvaluator:
+    """Generator that expands a :class:`THOL` block lazily."""
+
+    def __init__(
+        self,
+        item: THOL,
+        *,
+        max_materialize: int | None = MAX_MATERIALIZE_DEFAULT,
+    ) -> None:
+        self._frames: list[TholFrame] = []
+        _push_thol_frame(self._frames, item, max_materialize=max_materialize)
+        self._max_materialize = max_materialize
+        self._started = False
+
+    def __iter__(self) -> "THOLEvaluator":
+        return self
+
+    def __next__(self) -> Token | object:
+        if not self._started:
+            self._started = True
+            return THOL_SENTINEL
+        while self._frames:
+            frame = self._frames[-1]
+            seq = frame.seq
+            idx = frame.index
+            if idx < len(seq):
+                token = seq[idx]
+                frame.index = idx + 1
+                if isinstance(token, THOL):
+                    _push_thol_frame(
+                        self._frames,
+                        token,
+                        max_materialize=self._max_materialize,
+                    )
+                    return THOL_SENTINEL
+                return token
+            else:
+                cl = frame.closing
+                frame.remaining -= 1
+                if frame.remaining > 0:
+                    frame.index = 0
+                else:
+                    self._frames.pop()
+                if cl is not None:
+                    return cl
+        raise StopIteration
+
+
+def _flatten_target(
+    item: TARGET,
+    ops: list[tuple[OpTag, Any]],
+) -> None:
+    ops.append((OpTag.TARGET, item))
+
+
+def _flatten_wait(
+    item: WAIT,
+    ops: list[tuple[OpTag, Any]],
+) -> None:
+    steps = max(1, int(getattr(item, "steps", 1)))
+    ops.append((OpTag.WAIT, steps))
+
+
+def _flatten_glyph(
+    item: Glyph | str,
+    ops: list[tuple[OpTag, Any]],
+) -> None:
+    g = item.value if isinstance(item, Glyph) else str(item)
+    if g not in GLYPHS_CANONICAL_SET:
+        raise ValueError(f"Non-canonical glyph: {g}")
+    ops.append((OpTag.GLYPH, g))
+
+
+_TOKEN_DISPATCH: dict[type, Callable[[Any, list[tuple[OpTag, Any]]], None]] = {
+    TARGET: _flatten_target,
+    WAIT: _flatten_wait,
+    Glyph: _flatten_glyph,
+    str: _flatten_glyph,
+}
+
+
+def _coerce_mapping_token(
+    mapping: Mapping[str, Any],
+    *,
+    max_materialize: int | None,
+) -> Token:
+    if len(mapping) != 1:
+        raise ValueError(f"Invalid token mapping: {mapping!r}")
+    key, value = next(iter(mapping.items()))
+    if key == "WAIT":
+        return WAIT(int(value))
+    if key == "TARGET":
+        return TARGET(value)
+    if key != "THOL":
+        raise ValueError(f"Unrecognized token: {key!r}")
+    if not isinstance(value, Mapping):
+        raise TypeError("THOL specification must be a mapping")
+
+    close = value.get("close")
+    if isinstance(close, str):
+        close_enum = Glyph.__members__.get(close)
+        if close_enum is None:
+            raise ValueError(f"Unknown closing glyph: {close!r}")
+        close = close_enum
+    elif close is not None and not isinstance(close, Glyph):
+        raise TypeError("THOL close glyph must be a Glyph or string name")
+
+    body = parse_program_tokens(value.get("body", []), max_materialize=max_materialize)
+    repeat = int(value.get("repeat", 1))
+    return THOL(body=body, repeat=repeat, force_close=close)
+
+
+def parse_program_tokens(
+    obj: Iterable[Any] | Sequence[Any] | Any,
+    *,
+    max_materialize: int | None = MAX_MATERIALIZE_DEFAULT,
+) -> list[Token]:
+    """Materialize ``obj`` into a list of canonical tokens.
+
+    The function accepts the same iterables handled by :func:`_flatten`,
+    including dictionaries describing ``WAIT``, ``TARGET`` and ``THOL`` tokens.
+    Nested iterables are flattened following :func:`flatten_structure` rules.
+    """
+
+    sequence = _iter_source(obj, max_materialize=max_materialize)
+
+    def _expand(item: Any) -> Iterable[Any] | None:
+        if isinstance(item, Mapping):
+            return (_coerce_mapping_token(item, max_materialize=max_materialize),)
+        return None
+
+    tokens: list[Token] = []
+    for item in flatten_structure(sequence, expand=_expand):
+        if isinstance(item, (Glyph, WAIT, TARGET, THOL, str)):
+            tokens.append(item)
+            continue
+        raise TypeError(f"Unsupported token: {item!r}")
+    return tokens
+
+
+def _flatten(
+    seq: Iterable[Token] | Sequence[Token] | Any,
+    *,
+    max_materialize: int | None = MAX_MATERIALIZE_DEFAULT,
+) -> list[tuple[OpTag, Any]]:
+    """Return a list of operations ``(op, payload)`` where ``op`` ∈ :class:`OpTag`."""
+
+    ops: list[tuple[OpTag, Any]] = []
+    sequence = _iter_source(seq, max_materialize=max_materialize)
+
+    def _expand(item: Any) -> Iterable[Any] | None:
+        if isinstance(item, THOL):
+            return THOLEvaluator(item, max_materialize=max_materialize)
+        if isinstance(item, Mapping):
+            token = _coerce_mapping_token(item, max_materialize=max_materialize)
+            return (token,)
+        return None
+
+    for item in flatten_structure(sequence, expand=_expand):
+        if item is THOL_SENTINEL:
+            ops.append((OpTag.THOL, Glyph.THOL.value))
+            continue
+        handler = _TOKEN_DISPATCH.get(type(item))
+        if handler is None:
+            for cls, candidate in _TOKEN_DISPATCH.items():
+                if isinstance(item, cls):
+                    handler = candidate
+                    break
+        if handler is None:
+            raise TypeError(f"Unsupported token: {item!r}")
+        handler(item, ops)
+    return ops

tnfr/flatten.pyi

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, Sequence
+from typing import Any
+
+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 __iter__(self) -> THOLEvaluator: ...
+
+    def __next__(self) -> Token | object: ...
+
+
+def parse_program_tokens(
+    obj: Iterable[Any] | Sequence[Any] | Any,
+    *,
+    max_materialize: int | None = ...,
+) -> list[Token]: ...