tnfr 4.5.2__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/{json_utils.py → utils/io.py}

@@ -1,11 +1,4 @@
-"""JSON helpers with optional :mod:`orjson` support.
-
-This module lazily imports :mod:`orjson` on first use of :func:`json_dumps`.
-The fast serializer is brought in through
-``tnfr.import_utils.cached_import``; its cache and failure registry can be
-reset using ``cached_import.cache_clear()`` and
-:func:`tnfr.import_utils.prune_failed_imports`.
-"""
+"""Serialisation helpers for TNFR, including JSON convenience wrappers."""
 
 from __future__ import annotations
 
@@ -13,8 +6,14 @@ from dataclasses import dataclass
 import json
 from typing import Any, Callable
 
-from .import_utils import cached_import
-from .logging_utils import get_logger, warn_once
+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"
@@ -33,6 +32,7 @@ def clear_orjson_param_warnings() -> None:
 
 def _format_ignored_params(combo: frozenset[str]) -> str:
     """Return a stable representation for ignored parameter combinations."""
+
     return "{" + ", ".join(map(repr, sorted(combo))) + "}"
 
 
@@ -91,6 +91,7 @@ def _json_dumps_std(
     **kwargs: Any,
 ) -> bytes | str:
     """Serialize using the standard library :func:`json.dumps`."""
+
     result = json.dumps(
         obj,
         sort_keys=params.sort_keys,
@@ -114,14 +115,8 @@ def json_dumps(
     to_bytes: bool = False,
     **kwargs: Any,
 ) -> bytes | str:
-    """Serialize ``obj`` to JSON using ``orjson`` when available.
-
-    Returns a ``str`` by default. Pass ``to_bytes=True`` to obtain a ``bytes``
-    result. When :mod:`orjson` is used, the ``ensure_ascii``, ``separators``,
-    ``cls`` and any additional keyword arguments are ignored because they are
-    not supported by :func:`orjson.dumps`. A warning is emitted whenever such
-    ignored parameters are detected.
-    """
+    """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):

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