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

tnfr/utils/init.pyi

@@ -0,0 +1,85 @@
+from collections.abc import Callable, Iterable, Iterator, Mapping
+import logging
+from typing import Any, Hashable, Literal
+
+__all__: tuple[str, ...]
+
+def __getattr__(name: str) -> Any: ...
+
+
+class WarnOnce:
+    def __init__(self, logger: logging.Logger, msg: str, *, maxsize: int = ...) -> None: ...
+    def __call__(
+        self,
+        data: Mapping[Hashable, Any] | Hashable,
+        value: Any | None = ...,
+    ) -> None: ...
+    def clear(self) -> None: ...
+
+
+class LazyImportProxy:
+    def __init__(
+        self,
+        module_name: str,
+        attr: str | None,
+        emit: Literal["warn", "log", "both"],
+        fallback: Any | None,
+    ) -> None: ...
+    def __getattr__(self, name: str) -> Any: ...
+    def __call__(self, *args: Any, **kwargs: Any) -> Any: ...
+    def __bool__(self) -> bool: ...
+    def __iter__(self) -> Iterator[Any]: ...
+    def resolve(self) -> Any: ...
+
+
+class ImportRegistry:
+    limit: int
+    failed: Mapping[str, None]
+    warned: set[str]
+    lock: Any
+
+    def record_failure(self, key: str, *, module: str | None = ...) -> None: ...
+    def discard(self, key: str) -> None: ...
+    def mark_warning(self, module: str) -> bool: ...
+    def clear(self) -> None: ...
+    def __contains__(self, key: str) -> bool: ...
+
+
+EMIT_MAP: Mapping[str, Callable[[str], None]]
+IMPORT_LOG: ImportRegistry
+_IMPORT_STATE: ImportRegistry
+_LOGGING_CONFIGURED: bool
+_DEFAULT_CACHE_SIZE: int
+_FAILED_IMPORT_LIMIT: int
+
+
+def _configure_root() -> None: ...
+def _reset_import_state() -> None: ...
+def _reset_logging_state() -> None: ...
+def _warn_failure(module: str, attr: str | None, err: Exception) -> None: ...
+
+
+def cached_import(
+    module_name: str,
+    attr: str | None = ...,
+    *,
+    fallback: Any | None = ...,
+    emit: Literal["warn", "log", "both"] = ...,
+    lazy: bool = ...,
+) -> Any | None: ...
+
+
+def warm_cached_import(
+    module: str | tuple[str, str | None] | Iterable[str | tuple[str, str | None]],
+    *extra: str | tuple[str, str | None],
+    attr: str | None = ...,
+    fallback: Any | None = ...,
+    emit: Literal["warn", "log", "both"] = ...,
+    lazy: bool = ...,
+    resolve: bool = ...,
+) -> Any | dict[str, Any | None]: ...
+def get_logger(name: str) -> logging.Logger: ...
+def get_numpy() -> Any | None: ...
+def get_nodenx() -> Any | None: ...
+def prune_failed_imports(*modules: str) -> None: ...
+def warn_once(logger: logging.Logger, msg: str, *, maxsize: int = ...) -> WarnOnce: ...

tnfr/utils/io.py

@@ -0,0 +1,157 @@
+"""Serialisation helpers for TNFR, including JSON convenience wrappers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from typing import Any, Callable
+
+from .init import cached_import, get_logger, warn_once
+
+__all__ = (
+    "JsonDumpsParams",
+    "DEFAULT_PARAMS",
+    "json_dumps",
+    "clear_orjson_param_warnings",
+)
+
+_ORJSON_PARAMS_MSG = (
+    "'ensure_ascii', 'separators', 'cls' and extra kwargs are ignored when using orjson: %s"
+)
+
+logger = get_logger(__name__)
+
+_warn_ignored_params_once = warn_once(logger, _ORJSON_PARAMS_MSG)
+
+
+def clear_orjson_param_warnings() -> None:
+    """Reset cached warnings for ignored :mod:`orjson` parameters."""
+
+    _warn_ignored_params_once.clear()
+
+
+def _format_ignored_params(combo: frozenset[str]) -> str:
+    """Return a stable representation for ignored parameter combinations."""
+
+    return "{" + ", ".join(map(repr, sorted(combo))) + "}"
+
+
+@dataclass(frozen=True)
+class JsonDumpsParams:
+    """Container describing the parameters used by :func:`json_dumps`."""
+
+    sort_keys: bool = False
+    default: Callable[[Any], Any] | None = None
+    ensure_ascii: bool = True
+    separators: tuple[str, str] = (",", ":")
+    cls: type[json.JSONEncoder] | None = None
+    to_bytes: bool = False
+
+
+DEFAULT_PARAMS = JsonDumpsParams()
+
+
+def _collect_ignored_params(
+    params: JsonDumpsParams, extra_kwargs: dict[str, Any]
+) -> frozenset[str]:
+    """Return a stable set of parameters ignored by :mod:`orjson`."""
+
+    ignored: set[str] = set()
+    if params.ensure_ascii is not True:
+        ignored.add("ensure_ascii")
+    if params.separators != (",", ":"):
+        ignored.add("separators")
+    if params.cls is not None:
+        ignored.add("cls")
+    if extra_kwargs:
+        ignored.update(extra_kwargs.keys())
+    return frozenset(ignored)
+
+
+def _json_dumps_orjson(
+    orjson: Any,
+    obj: Any,
+    params: JsonDumpsParams,
+    **kwargs: Any,
+) -> bytes | str:
+    """Serialize using :mod:`orjson` and warn about unsupported parameters."""
+
+    ignored = _collect_ignored_params(params, kwargs)
+    if ignored:
+        _warn_ignored_params_once(ignored, _format_ignored_params(ignored))
+
+    option = orjson.OPT_SORT_KEYS if params.sort_keys else 0
+    data = orjson.dumps(obj, option=option, default=params.default)
+    return data if params.to_bytes else data.decode("utf-8")
+
+
+def _json_dumps_std(
+    obj: Any,
+    params: JsonDumpsParams,
+    **kwargs: Any,
+) -> bytes | str:
+    """Serialize using the standard library :func:`json.dumps`."""
+
+    result = json.dumps(
+        obj,
+        sort_keys=params.sort_keys,
+        ensure_ascii=params.ensure_ascii,
+        separators=params.separators,
+        cls=params.cls,
+        default=params.default,
+        **kwargs,
+    )
+    return result if not params.to_bytes else result.encode("utf-8")
+
+
+def json_dumps(
+    obj: Any,
+    *,
+    sort_keys: bool = False,
+    default: Callable[[Any], Any] | None = None,
+    ensure_ascii: bool = True,
+    separators: tuple[str, str] = (",", ":"),
+    cls: type[json.JSONEncoder] | None = None,
+    to_bytes: bool = False,
+    **kwargs: Any,
+) -> bytes | str:
+    """Serialize ``obj`` to JSON using ``orjson`` when available."""
+
+    if not isinstance(sort_keys, bool):
+        raise TypeError("sort_keys must be a boolean")
+    if default is not None and not callable(default):
+        raise TypeError("default must be callable when provided")
+    if not isinstance(ensure_ascii, bool):
+        raise TypeError("ensure_ascii must be a boolean")
+    if not isinstance(separators, tuple) or len(separators) != 2:
+        raise TypeError("separators must be a tuple of two strings")
+    if not all(isinstance(part, str) for part in separators):
+        raise TypeError("separators must be a tuple of two strings")
+    if cls is not None:
+        if not isinstance(cls, type) or not issubclass(cls, json.JSONEncoder):
+            raise TypeError("cls must be a subclass of json.JSONEncoder")
+    if not isinstance(to_bytes, bool):
+        raise TypeError("to_bytes must be a boolean")
+
+    if (
+        sort_keys is False
+        and default is None
+        and ensure_ascii is True
+        and separators == (",", ":")
+        and cls is None
+        and to_bytes is False
+    ):
+        params = DEFAULT_PARAMS
+    else:
+        params = JsonDumpsParams(
+            sort_keys=sort_keys,
+            default=default,
+            ensure_ascii=ensure_ascii,
+            separators=separators,
+            cls=cls,
+            to_bytes=to_bytes,
+        )
+    orjson = cached_import("orjson", emit="log")
+    if orjson is not None:
+        return _json_dumps_orjson(orjson, obj, params, **kwargs)
+    return _json_dumps_std(obj, params, **kwargs)

tnfr/utils/io.pyi

@@ -0,0 +1,10 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+DEFAULT_PARAMS: Any
+JsonDumpsParams: Any
+clear_orjson_param_warnings: Any
+json_dumps: Any

tnfr/utils/validators.py

@@ -0,0 +1,130 @@
+"""Validation utilities for TNFR graph structures."""
+
+from __future__ import annotations
+
+import numbers
+import sys
+
+from collections.abc import Mapping
+from typing import Callable, Sequence
+
+from .._compat import TypeAlias
+
+from ..alias import get_attr
+from ..config.constants import GLYPHS_CANONICAL_SET
+from ..constants import get_aliases, get_param
+from ..helpers.numeric import within_range
+from ..types import (
+    EPIValue,
+    NodeId,
+    StructuralFrequency,
+    TNFRGraph,
+)
+ALIAS_EPI = get_aliases("EPI")
+ALIAS_VF = get_aliases("VF")
+
+ValidatorFunc: TypeAlias = Callable[[TNFRGraph], None]
+"""Callable signature expected for validation routines."""
+
+NodeData = Mapping[str, object]
+"""Read-only node attribute mapping used by validators."""
+
+AliasSequence = Sequence[str]
+"""Sequence of accepted attribute aliases."""
+
+__all__ = ("validate_window", "run_validators")
+
+
+def validate_window(window: int, *, positive: bool = False) -> int:
+    """Validate ``window`` as an ``int`` and return it.
+
+    Non-integer values raise :class:`TypeError`. When ``positive`` is ``True``
+    the value must be strictly greater than zero; otherwise it may be zero.
+    Negative values always raise :class:`ValueError`.
+    """
+
+    if isinstance(window, bool) or not isinstance(window, numbers.Integral):
+        raise TypeError("'window' must be an integer")
+    if window < 0 or (positive and window == 0):
+        kind = "positive" if positive else "non-negative"
+        raise ValueError(f"'window'={window} must be {kind}")
+    return int(window)
+
+
+def _require_attr(data: NodeData, alias: AliasSequence, node: NodeId, name: str) -> float:
+    """Return attribute value or raise if missing."""
+
+    mapping: dict[str, object]
+    if isinstance(data, dict):
+        mapping = data
+    else:
+        mapping = dict(data)
+    val = get_attr(mapping, alias, None)
+    if val is None:
+        raise ValueError(f"Missing {name} attribute in node {node}")
+    return float(val)
+
+
+def _validate_sigma(graph: TNFRGraph) -> None:
+    from ..sense import sigma_vector_from_graph
+
+    sv = sigma_vector_from_graph(graph)
+    if sv.get("mag", 0.0) > 1.0 + sys.float_info.epsilon:
+        raise ValueError("σ norm exceeds 1")
+
+
+GRAPH_VALIDATORS: tuple[ValidatorFunc, ...] = (_validate_sigma,)
+"""Ordered collection of graph-level validators."""
+
+
+def _check_epi_vf(
+    epi: EPIValue,
+    vf: StructuralFrequency,
+    epi_min: float,
+    epi_max: float,
+    vf_min: float,
+    vf_max: float,
+    node: NodeId,
+) -> None:
+    _check_range(epi, epi_min, epi_max, "EPI", node)
+    _check_range(vf, vf_min, vf_max, "VF", node)
+
+
+def _out_of_range_msg(name: str, node: NodeId, val: float) -> str:
+    return f"{name} out of range in node {node}: {val}"
+
+
+def _check_range(
+    val: float,
+    lower: float,
+    upper: float,
+    name: str,
+    node: NodeId,
+    tol: float = 1e-9,
+) -> None:
+    if not within_range(val, lower, upper, tol):
+        raise ValueError(_out_of_range_msg(name, node, val))
+
+
+def _check_glyph(glyph: str | None, node: NodeId) -> None:
+    if glyph and glyph not in GLYPHS_CANONICAL_SET:
+        raise KeyError(f"Invalid glyph {glyph} in node {node}")
+
+
+def run_validators(graph: TNFRGraph) -> None:
+    """Run all invariant validators on ``G`` with a single node pass."""
+    from ..glyph_history import last_glyph
+
+    epi_min = float(get_param(graph, "EPI_MIN"))
+    epi_max = float(get_param(graph, "EPI_MAX"))
+    vf_min = float(get_param(graph, "VF_MIN"))
+    vf_max = float(get_param(graph, "VF_MAX"))
+
+    for node, data in graph.nodes(data=True):
+        epi = EPIValue(_require_attr(data, ALIAS_EPI, node, "EPI"))
+        vf = StructuralFrequency(_require_attr(data, ALIAS_VF, node, "VF"))
+        _check_epi_vf(epi, vf, epi_min, epi_max, vf_min, vf_max, node)
+        _check_glyph(last_glyph(data), node)
+
+    for validator in GRAPH_VALIDATORS:
+        validator(graph)

tnfr/utils/validators.pyi

@@ -0,0 +1,19 @@
+from collections.abc import Mapping
+from typing import Callable, Sequence
+
+from ..types import TNFRGraph
+from .._compat import TypeAlias
+
+ValidatorFunc: TypeAlias = Callable[[TNFRGraph], None]
+NodeData: TypeAlias = Mapping[str, object]
+AliasSequence: TypeAlias = Sequence[str]
+
+__all__: tuple[str, ...]
+
+def __getattr__(name: str) -> object: ...
+
+def validate_window(window: int, *, positive: bool = ...) -> int: ...
+
+def run_validators(graph: TNFRGraph) -> None: ...
+
+GRAPH_VALIDATORS: tuple[ValidatorFunc, ...]

tnfr/validation/__init__.py

@@ -0,0 +1,25 @@
+"""Validation helpers for TNFR sequences."""
+
+from .compatibility import CANON_COMPAT, CANON_FALLBACK
+from .grammar import (
+    GrammarContext,
+    apply_glyph_with_grammar,
+    enforce_canonical_grammar,
+    on_applied_glyph,
+)
+from .rules import coerce_glyph, glyph_fallback, normalized_dnfr, get_norm
+from .syntax import validate_sequence
+
+__all__ = (
+    "validate_sequence",
+    "GrammarContext",
+    "apply_glyph_with_grammar",
+    "enforce_canonical_grammar",
+    "on_applied_glyph",
+    "coerce_glyph",
+    "glyph_fallback",
+    "normalized_dnfr",
+    "get_norm",
+    "CANON_COMPAT",
+    "CANON_FALLBACK",
+)

tnfr/validation/__init__.pyi

@@ -0,0 +1,17 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+CANON_COMPAT: Any
+CANON_FALLBACK: Any
+GrammarContext: Any
+apply_glyph_with_grammar: Any
+coerce_glyph: Any
+enforce_canonical_grammar: Any
+get_norm: Any
+glyph_fallback: Any
+normalized_dnfr: Any
+on_applied_glyph: Any
+validate_sequence: Any

tnfr/validation/compatibility.py

@@ -0,0 +1,59 @@
+"""Canonical TNFR compatibility tables.
+
+This module centralises the canonical transitions that keep TNFR
+coherence consistent across refactors.  It is intentionally lightweight
+so :mod:`tnfr.validation.grammar` can depend on it without introducing
+cycles.
+"""
+
+from __future__ import annotations
+
+from ..types import Glyph
+
+__all__ = ["CANON_COMPAT", "CANON_FALLBACK"]
+
+# Canonical compatibilities (allowed next glyphs)
+CANON_COMPAT: dict[Glyph, set[Glyph]] = {
+    # Opening / initiation
+    Glyph.AL: {Glyph.EN, Glyph.RA, Glyph.NAV, Glyph.VAL, Glyph.UM},
+    Glyph.EN: {Glyph.IL, Glyph.UM, Glyph.RA, Glyph.NAV},
+    # Stabilisation / diffusion / coupling
+    Glyph.IL: {Glyph.RA, Glyph.VAL, Glyph.UM, Glyph.SHA},
+    Glyph.UM: {Glyph.RA, Glyph.IL, Glyph.VAL, Glyph.NAV},
+    Glyph.RA: {Glyph.IL, Glyph.VAL, Glyph.UM, Glyph.NAV},
+    Glyph.VAL: {Glyph.UM, Glyph.RA, Glyph.IL, Glyph.NAV},
+    # Dissonance → transition → mutation
+    Glyph.OZ: {Glyph.ZHIR, Glyph.NAV},
+    Glyph.ZHIR: {Glyph.IL, Glyph.NAV},
+    Glyph.NAV: {Glyph.OZ, Glyph.ZHIR, Glyph.RA, Glyph.IL, Glyph.UM},
+    # Closures / latent states
+    Glyph.SHA: {Glyph.AL, Glyph.EN},
+    Glyph.NUL: {Glyph.AL, Glyph.IL},
+    # Self-organising blocks
+    Glyph.THOL: {
+        Glyph.OZ,
+        Glyph.ZHIR,
+        Glyph.NAV,
+        Glyph.RA,
+        Glyph.IL,
+        Glyph.UM,
+        Glyph.SHA,
+        Glyph.NUL,
+    },
+}
+
+# Canonical fallbacks when a transition is not allowed
+CANON_FALLBACK: dict[Glyph, Glyph] = {
+    Glyph.AL: Glyph.EN,
+    Glyph.EN: Glyph.IL,
+    Glyph.IL: Glyph.RA,
+    Glyph.NAV: Glyph.RA,
+    Glyph.NUL: Glyph.AL,
+    Glyph.OZ: Glyph.ZHIR,
+    Glyph.RA: Glyph.IL,
+    Glyph.SHA: Glyph.AL,
+    Glyph.THOL: Glyph.NAV,
+    Glyph.UM: Glyph.RA,
+    Glyph.VAL: Glyph.RA,
+    Glyph.ZHIR: Glyph.IL,
+}

tnfr/validation/compatibility.pyi

@@ -0,0 +1,8 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+CANON_COMPAT: Any
+CANON_FALLBACK: Any

tnfr/validation/grammar.py

@@ -0,0 +1,149 @@
+"""Canonical grammar enforcement utilities."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any, Optional, TYPE_CHECKING, cast
+
+from ..constants import DEFAULTS, get_param
+from ..operators import apply_glyph
+from ..types import Glyph, NodeId, TNFRGraph
+from .compatibility import CANON_COMPAT
+from . import rules as _rules
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from ..node import NodeProtocol
+
+__all__ = [
+    "GrammarContext",
+    "_gram_state",
+    "enforce_canonical_grammar",
+    "on_applied_glyph",
+    "apply_glyph_with_grammar",
+]
+
+
+@dataclass
+class GrammarContext:
+    """Shared context for grammar helpers.
+
+    Collects graph-level settings to reduce positional parameters across
+    helper functions.
+    """
+
+    G: TNFRGraph
+    cfg_soft: dict[str, Any]
+    cfg_canon: dict[str, Any]
+    norms: dict[str, Any]
+
+    @classmethod
+    def from_graph(cls, G: TNFRGraph) -> "GrammarContext":
+        """Create a :class:`GrammarContext` for ``G``."""
+
+        return cls(
+            G=G,
+            cfg_soft=G.graph.get("GRAMMAR", DEFAULTS.get("GRAMMAR", {})),
+            cfg_canon=G.graph.get(
+                "GRAMMAR_CANON", DEFAULTS.get("GRAMMAR_CANON", {})
+            ),
+            norms=G.graph.get("_sel_norms") or {},
+        )
+
+
+# -------------------------
+# Per-node grammar state
+# -------------------------
+
+def _gram_state(nd: dict[str, Any]) -> dict[str, Any]:
+    """Create or return the node grammar state."""
+
+    return nd.setdefault("_GRAM", {"thol_open": False, "thol_len": 0})
+
+
+# -------------------------
+# Core: enforce grammar on a candidate
+# -------------------------
+
+def enforce_canonical_grammar(
+    G: TNFRGraph,
+    n: NodeId,
+    cand: Glyph | str,
+    ctx: Optional[GrammarContext] = None,
+) -> Glyph | str:
+    """Validate and adjust a candidate glyph according to canonical grammar."""
+
+    if ctx is None:
+        ctx = GrammarContext.from_graph(G)
+
+    nd = ctx.G.nodes[n]
+    st = _gram_state(nd)
+
+    raw_cand = cand
+    cand = _rules.coerce_glyph(cand)
+    input_was_str = isinstance(raw_cand, str)
+
+    # 0) If glyphs outside the alphabet arrive, leave untouched
+    if not isinstance(cand, Glyph) or cand not in CANON_COMPAT:
+        return raw_cand if input_was_str else cand
+
+    original = cand
+    cand = _rules._check_repeats(ctx, n, cand)
+
+    cand = _rules._maybe_force(ctx, n, cand, original, _rules.normalized_dnfr, "force_dnfr")
+    cand = _rules._maybe_force(ctx, n, cand, original, _rules._accel_norm, "force_accel")
+    cand = _rules._check_oz_to_zhir(ctx, n, cand)
+    cand = _rules._check_thol_closure(ctx, n, cand, st)
+    cand = _rules._check_compatibility(ctx, n, cand)
+
+    coerced_final = _rules.coerce_glyph(cand)
+    if input_was_str:
+        if isinstance(coerced_final, Glyph):
+            return coerced_final.value
+        return str(cand)
+    return coerced_final if isinstance(coerced_final, Glyph) else cand
+
+
+# -------------------------
+# Post-selection: update grammar state
+# -------------------------
+
+def on_applied_glyph(G: TNFRGraph, n: NodeId, applied: Glyph | str) -> None:
+    nd = G.nodes[n]
+    st = _gram_state(nd)
+    try:
+        glyph = applied if isinstance(applied, Glyph) else Glyph(str(applied))
+    except ValueError:
+        glyph = None
+
+    if glyph is Glyph.THOL:
+        st["thol_open"] = True
+        st["thol_len"] = 0
+    elif glyph in (Glyph.SHA, Glyph.NUL):
+        st["thol_open"] = False
+        st["thol_len"] = 0
+
+
+# -------------------------
+# Direct application with canonical grammar
+# -------------------------
+
+def apply_glyph_with_grammar(
+    G: TNFRGraph,
+    nodes: Optional[Iterable[NodeId | "NodeProtocol"]],
+    glyph: Glyph | str,
+    window: Optional[int] = None,
+) -> None:
+    """Apply ``glyph`` to ``nodes`` enforcing the canonical grammar."""
+
+    if window is None:
+        window = get_param(G, "GLYPH_HYSTERESIS_WINDOW")
+
+    g_str = glyph.value if isinstance(glyph, Glyph) else str(glyph)
+    iter_nodes = G.nodes() if nodes is None else nodes
+    ctx = GrammarContext.from_graph(G)
+    for node_ref in iter_nodes:
+        node_id = cast(NodeId, getattr(node_ref, "n", node_ref))
+        g_eff = enforce_canonical_grammar(G, node_id, g_str, ctx)
+        apply_glyph(G, node_id, g_eff, window=window)
+        on_applied_glyph(G, node_id, g_eff)

tnfr/validation/grammar.pyi

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