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

tnfr/types.py

@@ -2,10 +2,27 @@
 
 from __future__ import annotations
 
-from collections.abc import Callable, Hashable, Mapping, MutableMapping, Sequence
+from collections.abc import (
+    Callable,
+    Hashable,
+    Mapping,
+    MutableMapping,
+    MutableSequence,
+    Sequence,
+)
 from enum import Enum
-from typing import TYPE_CHECKING, Any, ContextManager, Iterable, Protocol, TypedDict
 from types import SimpleNamespace
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    ContextManager,
+    Iterable,
+    Protocol,
+    TypedDict,
+    runtime_checkable,
+)
+
+from numbers import Real
 
 from ._compat import TypeAlias
 
@@ -25,10 +42,15 @@ else:  # pragma: no cover - runtime fallback without numpy.typing
 __all__ = (
     "TNFRGraph",
     "Graph",
+    "ValidatorFunc",
     "NodeId",
     "Node",
     "GammaSpec",
     "EPIValue",
+    "BEPIProtocol",
+    "ensure_bepi",
+    "serialize_bepi",
+    "ZERO_BEPI_STORAGE",
     "DeltaNFR",
     "SecondDerivativeEPI",
     "Phase",
@@ -40,6 +62,7 @@ __all__ = (
     "GraphLike",
     "IntegratorProtocol",
     "Glyph",
+    "GlyphCode",
     "GlyphLoadDistribution",
     "GlyphSelector",
     "SelectorPreselectionMetrics",
@@ -50,9 +73,13 @@ __all__ = (
     "SelectorThresholds",
     "SelectorWeights",
     "TraceCallback",
+    "CallbackError",
     "TraceFieldFn",
     "TraceFieldMap",
     "TraceFieldRegistry",
+    "TraceMetadata",
+    "TraceSnapshot",
+    "RemeshMeta",
     "HistoryState",
     "DiagnosisNodeData",
     "DiagnosisSharedState",
@@ -69,18 +96,27 @@ __all__ = (
     "ArgSpec",
     "TNFRConfigValue",
     "SigmaVector",
+    "SigmaTrace",
     "FloatArray",
     "FloatMatrix",
     "NodeInitAttrMap",
+    "NodeAttrMap",
+    "GlyphogramRow",
+    "GlyphTimingTotals",
+    "GlyphTimingByNode",
+    "GlyphCounts",
+    "GlyphMetricsHistoryValue",
+    "GlyphMetricsHistory",
+    "MetricsListHistory",
+    "ParallelWijPayload",
 )
 
 
 if TYPE_CHECKING:  # pragma: no cover - import-time typing hook
     import networkx as nx
-    from .trace import TraceMetadata
+
     from .glyph_history import HistoryDict as _HistoryDict
     from .tokens import Token as _Token
-
     TNFRGraph: TypeAlias = nx.Graph
 else:  # pragma: no cover - runtime fallback without networkx
     TNFRGraph: TypeAlias = Any
@@ -98,6 +134,9 @@ else:  # pragma: no cover - runtime fallback without NumPy
 Graph: TypeAlias = TNFRGraph
 #: Backwards-compatible alias for :data:`TNFRGraph`.
 
+ValidatorFunc: TypeAlias = Callable[[TNFRGraph], None]
+"""Callable signature enforced by graph validation hooks."""
+
 NodeId: TypeAlias = Hashable
 #: Hashable identifier for a coherent TNFR node.
 
@@ -107,11 +146,90 @@ Node: TypeAlias = NodeId
 NodeInitAttrMap: TypeAlias = MutableMapping[str, float]
 #: Mutable mapping storing scalar node attributes during initialization.
 
+NodeAttrMap: TypeAlias = Mapping[str, Any]
+#: Read-only mapping exposing resolved node attributes during execution.
+
 GammaSpec: TypeAlias = Mapping[str, Any]
 #: Mapping describing Γ evaluation parameters for a node or graph.
 
-EPIValue: TypeAlias = float
-#: Scalar Primary Information Structure value carried by a node.
+@runtime_checkable
+class BEPIProtocol(Protocol):
+    """Structural contract describing BEPI-compatible values."""
+
+    f_continuous: Any
+    a_discrete: Any
+    x_grid: Any
+
+    def direct_sum(self, other: Any) -> Any: ...
+
+    def tensor(self, vector: Sequence[complex] | np.ndarray) -> np.ndarray: ...
+
+    def adjoint(self) -> Any: ...
+
+    def compose(
+        self,
+        transform: Callable[[np.ndarray], np.ndarray],
+        *,
+        spectral_transform: Callable[[np.ndarray], np.ndarray] | None = None,
+    ) -> Any: ...
+
+
+EPIValue: TypeAlias = BEPIProtocol
+#: BEPI Primary Information Structure carried by a node.
+
+ZERO_BEPI_STORAGE: dict[str, tuple[complex, ...] | tuple[float, ...]] = {
+    "continuous": (0j, 0j),
+    "discrete": (0j, 0j),
+    "grid": (0.0, 1.0),
+}
+"""Canonical zero element used as fallback when EPI data is missing."""
+
+
+def _is_scalar(value: Any) -> bool:
+    scalar_types: tuple[type[Any], ...]
+    np_scalar = getattr(np, "generic", None)
+    if np_scalar is None:
+        scalar_types = (int, float, complex, Real)
+    else:
+        scalar_types = (int, float, complex, Real, np_scalar)
+    return isinstance(value, scalar_types)
+
+
+def ensure_bepi(value: Any) -> "BEPIElement":
+    """Normalise arbitrary inputs into a :class:`~tnfr.mathematics.BEPIElement`."""
+
+    from .mathematics import BEPIElement as _BEPIElement
+
+    if isinstance(value, _BEPIElement):
+        return value
+    if _is_scalar(value):
+        scalar = complex(value)
+        return _BEPIElement((scalar, scalar), (scalar, scalar), (0.0, 1.0))
+    if isinstance(value, Mapping):
+        try:
+            continuous = value["continuous"]
+            discrete = value["discrete"]
+            grid = value["grid"]
+        except KeyError as exc:  # pragma: no cover - defensive
+            missing = exc.args[0]
+            raise ValueError(f"Missing '{missing}' key for BEPI serialization.") from exc
+        return _BEPIElement(continuous, discrete, grid)
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        if len(value) != 3:
+            raise ValueError("Sequential BEPI representations must contain 3 elements.")
+        continuous, discrete, grid = value
+        return _BEPIElement(continuous, discrete, grid)
+    raise TypeError(f"Unsupported BEPI value type: {type(value)!r}")
+
+
+def serialize_bepi(value: Any) -> dict[str, tuple[complex, ...] | tuple[float, ...]]:
+    """Serialise a BEPI element into canonical ``continuous/discrete/grid`` tuples."""
+
+    element = ensure_bepi(value)
+    continuous = tuple(complex(v) for v in element.f_continuous.tolist())
+    discrete = tuple(complex(v) for v in element.a_discrete.tolist())
+    grid = tuple(float(v) for v in element.x_grid.tolist())
+    return {"continuous": continuous, "discrete": discrete, "grid": grid}
 
 DeltaNFR: TypeAlias = float
 #: Scalar internal reorganisation driver ΔNFR applied to a node.
@@ -187,6 +305,16 @@ class SigmaVector(_SigmaVectorRequired, _SigmaVectorOptional):
     """Typed dictionary describing σ-vector telemetry."""
 
 
+class SigmaTrace(TypedDict):
+    """Time-aligned σ(t) trace exported alongside glyphograms."""
+
+    t: list[float]
+    sigma_x: list[float]
+    sigma_y: list[float]
+    mag: list[float]
+    angle: list[float]
+
+
 class SelectorThresholds(TypedDict):
     """Normalised thresholds applied by the glyph selector."""
 
@@ -229,8 +357,7 @@ class _DeltaNFRHookProtocol(Protocol):
         /,
         *args: Any,
         **kwargs: Any,
-    ) -> None:
-        ...
+    ) -> None: ...
 
 
 DeltaNFRHook: TypeAlias = _DeltaNFRHookProtocol
@@ -248,15 +375,23 @@ class GraphLike(Protocol):
     graph: dict[str, Any]
 
     def nodes(self, data: bool = ...) -> Iterable[Any]:
+        """Return an iterable of nodes mirroring NetworkX semantics."""
+
         ...
 
     def number_of_nodes(self) -> int:
+        """Return the total number of coherent nodes in the graph."""
+
         ...
 
     def neighbors(self, n: Any) -> Iterable[Any]:
+        """Yield adjacent nodes coupled to ``n`` within the structure."""
+
         ...
 
     def __iter__(self) -> Iterable[Any]:
+        """Iterate over nodes to allow direct structural traversals."""
+
         ...
 
 
@@ -272,6 +407,8 @@ class IntegratorProtocol(Protocol):
         method: str | None,
         n_jobs: int | None,
     ) -> None:
+        """Advance the nodal equation for ``graph`` using integrator configuration."""
+
         ...
 
 
@@ -293,24 +430,26 @@ class Glyph(str, Enum):
     REMESH = "REMESH"
 
 
+GlyphCode: TypeAlias = Glyph | str
+"""Glyph identifier accepted by selector pipelines and grammars."""
+
+
 GlyphLoadDistribution: TypeAlias = dict[Glyph | str, float]
 #: Normalised glyph load proportions keyed by :class:`Glyph` or aggregate labels.
 
+
 class _SelectorLifecycle(Protocol):
     """Protocol describing the selector lifecycle supported by the runtime."""
 
-    def __call__(self, graph: TNFRGraph, node: NodeId) -> Glyph | str:
-        ...
+    def __call__(self, graph: TNFRGraph, node: NodeId) -> GlyphCode: ...
 
-    def prepare(self, graph: TNFRGraph, nodes: Sequence[NodeId]) -> None:
-        ...
+    def prepare(self, graph: TNFRGraph, nodes: Sequence[NodeId]) -> None: ...
 
-    def select(self, graph: TNFRGraph, node: NodeId) -> Glyph | str:
-        ...
+    def select(self, graph: TNFRGraph, node: NodeId) -> GlyphCode: ...
 
 
 GlyphSelector: TypeAlias = (
-    Callable[[TNFRGraph, NodeId], Glyph | str] | _SelectorLifecycle
+    Callable[[TNFRGraph, NodeId], GlyphCode] | _SelectorLifecycle
 )
 #: Selector callable or object returning the glyph to apply for ``NodeId``.
 
@@ -335,9 +474,45 @@ TraceFieldMap: TypeAlias = Mapping[str, "TraceFieldFn"]
 TraceFieldRegistry: TypeAlias = dict[str, dict[str, "TraceFieldFn"]]
 #: Registry grouping trace field producers by capture phase.
 
+
+class TraceMetadata(TypedDict, total=False):
+    """Metadata captured by trace field producers across phases."""
+
+    gamma: Mapping[str, Any]
+    grammar: Mapping[str, Any]
+    selector: str | None
+    dnfr_weights: Mapping[str, Any]
+    si_weights: Mapping[str, Any]
+    si_sensitivity: Mapping[str, Any]
+    callbacks: Mapping[str, list[str] | None]
+    thol_open_nodes: int
+    kuramoto: Mapping[str, float]
+    sigma: Mapping[str, float]
+    glyphs: Mapping[str, int]
+
+
+class TraceSnapshot(TraceMetadata, total=False):
+    """Trace metadata snapshot recorded in TNFR history."""
+
+    t: float
+    phase: str
+
+
 HistoryState: TypeAlias = _HistoryDict | dict[str, Any]
 #: History container used to accumulate glyph metrics and logs for the graph.
 
+
+class CallbackError(TypedDict):
+    """Metadata captured for a failed callback invocation."""
+
+    event: str
+    step: int | None
+    error: str
+    traceback: str
+    fn: str
+    name: str | None
+
+
 TraceCallback: TypeAlias = Callable[[TNFRGraph, dict[str, Any]], None]
 #: Callback signature used by :func:`tnfr.trace.register_trace`.
 
@@ -381,3 +556,57 @@ NeighborStats: TypeAlias = tuple[
     Sequence[float] | None,
 ]
 """Bundle of neighbour accumulators for cosine, sine, EPI, νf and topology totals."""
+
+GlyphogramRow: TypeAlias = MutableMapping[str, float]
+"""Row exported by glyph timing summaries."""
+
+GlyphTimingTotals: TypeAlias = MutableMapping[str, float]
+"""Aggregate glyph timing totals keyed by glyph code."""
+
+GlyphTimingByNode: TypeAlias = MutableMapping[
+    Any, MutableMapping[str, MutableSequence[float]]
+]
+"""Glyph timing segments stored per node during audits."""
+
+GlyphCounts: TypeAlias = Mapping[str, int]
+"""Glyph occurrence counters keyed by glyph code."""
+
+GlyphMetricsHistoryValue: TypeAlias = MutableMapping[Any, Any] | MutableSequence[Any]
+"""Flexible container used by glyph history accumulators."""
+
+GlyphMetricsHistory: TypeAlias = MutableMapping[str, GlyphMetricsHistoryValue]
+"""History map storing glyph metrics by identifier."""
+
+MetricsListHistory: TypeAlias = MutableMapping[str, list[Any]]
+"""Mapping associating glyph metric identifiers with time series."""
+
+
+class RemeshMeta(TypedDict, total=False):
+    """Event metadata persisted after applying REMESH coherence operators."""
+
+    alpha: float
+    alpha_source: str
+    tau_global: int
+    tau_local: int
+    step: int | None
+    topo_hash: str | None
+    epi_mean_before: float
+    epi_mean_after: float
+    epi_checksum_before: str
+    epi_checksum_after: str
+    stable_frac_last: float
+    phase_sync_last: float
+    glyph_disr_last: float
+
+
+class ParallelWijPayload(TypedDict):
+    """Container for broadcasting Wij coherence components to worker pools."""
+
+    epi_vals: Sequence[float]
+    vf_vals: Sequence[float]
+    si_vals: Sequence[float]
+    cos_vals: Sequence[float]
+    sin_vals: Sequence[float]
+    weights: tuple[float, float, float, float]
+    epi_range: float
+    vf_range: float

tnfr/types.pyi

@@ -1,7 +1,12 @@
-from typing import Any, Callable, ContextManager, Iterable, Protocol, cast
-from collections.abc import Hashable, Mapping, Sequence
+from collections.abc import (
+    Hashable,
+    Mapping,
+    MutableMapping,
+    MutableSequence,
+    Sequence,
+)
 from enum import Enum
-from typing import TypedDict
+from typing import Any, Callable, ContextManager, Iterable, Protocol, TypedDict, cast
 
 from ._compat import TypeAlias
 
@@ -25,20 +30,96 @@ except Exception:
 
     np = cast(Any, _FallbackNumpy())
 
-from .tokens import Token
-from .trace import TraceMetadata
 from .glyph_history import HistoryDict as _HistoryDict
-
-__all__: tuple[str, ...]
+from .tokens import Token
+__all__: tuple[str, ...] = (
+    "TNFRGraph",
+    "Graph",
+    "ValidatorFunc",
+    "NodeId",
+    "Node",
+    "GammaSpec",
+    "EPIValue",
+    "BEPIProtocol",
+    "ensure_bepi",
+    "serialize_bepi",
+    "ZERO_BEPI_STORAGE",
+    "DeltaNFR",
+    "SecondDerivativeEPI",
+    "Phase",
+    "StructuralFrequency",
+    "SenseIndex",
+    "CouplingWeight",
+    "CoherenceMetric",
+    "DeltaNFRHook",
+    "GraphLike",
+    "IntegratorProtocol",
+    "Glyph",
+    "GlyphCode",
+    "GlyphLoadDistribution",
+    "GlyphSelector",
+    "SelectorPreselectionMetrics",
+    "SelectorPreselectionChoices",
+    "SelectorPreselectionPayload",
+    "SelectorMetrics",
+    "SelectorNorms",
+    "SelectorThresholds",
+    "SelectorWeights",
+    "TraceCallback",
+    "CallbackError",
+    "TraceFieldFn",
+    "TraceFieldMap",
+    "TraceFieldRegistry",
+    "TraceMetadata",
+    "TraceSnapshot",
+    "HistoryState",
+    "DiagnosisNodeData",
+    "DiagnosisSharedState",
+    "DiagnosisPayload",
+    "DiagnosisResult",
+    "DiagnosisPayloadChunk",
+    "DiagnosisResultList",
+    "DnfrCacheVectors",
+    "DnfrVectorMap",
+    "NeighborStats",
+    "TimingContext",
+    "PresetTokens",
+    "ProgramTokens",
+    "ArgSpec",
+    "TNFRConfigValue",
+    "SigmaVector",
+    "SigmaTrace",
+    "FloatArray",
+    "FloatMatrix",
+    "NodeInitAttrMap",
+    "NodeAttrMap",
+    "GlyphogramRow",
+    "GlyphTimingTotals",
+    "GlyphTimingByNode",
+    "GlyphCounts",
+    "GlyphMetricsHistoryValue",
+    "GlyphMetricsHistory",
+    "MetricsListHistory",
+    "ParallelWijPayload",
+    "RemeshMeta",
+)
 
 def __getattr__(name: str) -> Any: ...
 
 TNFRGraph: TypeAlias = nx.Graph
 Graph: TypeAlias = TNFRGraph
+ValidatorFunc: TypeAlias = Callable[[TNFRGraph], None]
 NodeId: TypeAlias = Hashable
 Node: TypeAlias = NodeId
+NodeInitAttrMap: TypeAlias = MutableMapping[str, float]
+NodeAttrMap: TypeAlias = Mapping[str, Any]
 GammaSpec: TypeAlias = Mapping[str, Any]
-EPIValue: TypeAlias = float
+class BEPIProtocol(Protocol): ...
+
+EPIValue: TypeAlias = BEPIProtocol
+ZERO_BEPI_STORAGE: dict[str, tuple[complex, ...] | tuple[float, ...]]
+def ensure_bepi(value: Any) -> "BEPIElement": ...
+def serialize_bepi(value: Any) -> dict[str, tuple[complex, ...] | tuple[float, ...]]: ...
 DeltaNFR: TypeAlias = float
 SecondDerivativeEPI: TypeAlias = float
 Phase: TypeAlias = float
@@ -48,8 +129,43 @@ CouplingWeight: TypeAlias = float
 CoherenceMetric: TypeAlias = float
 TimingContext: TypeAlias = ContextManager[None]
 PresetTokens: TypeAlias = Sequence[Token]
+ProgramTokens: TypeAlias = Sequence[Token]
+ArgSpec: TypeAlias = tuple[str, Mapping[str, Any]]
+
+TNFRConfigScalar: TypeAlias = bool | int | float | str | None
+TNFRConfigSequence: TypeAlias = Sequence[TNFRConfigScalar]
+TNFRConfigValue: TypeAlias = (
+    TNFRConfigScalar | TNFRConfigSequence | Mapping[str, "TNFRConfigValue"]
+)
+
+class _SigmaVectorRequired(TypedDict):
+    x: float
+    y: float
+    mag: float
+    angle: float
+    n: int
+
+
+class _SigmaVectorOptional(TypedDict, total=False):
+    glyph: str
+    w: float
+    t: float
 
 
+class SigmaVector(_SigmaVectorRequired, _SigmaVectorOptional): ...
+
+
+class SigmaTrace(TypedDict):
+    t: list[float]
+    sigma_x: list[float]
+    sigma_y: list[float]
+    mag: list[float]
+    angle: list[float]
+
+
+FloatArray: TypeAlias = np.ndarray
+FloatMatrix: TypeAlias = np.ndarray
+
 class SelectorThresholds(TypedDict):
     si_hi: float
     si_lo: float
@@ -58,13 +174,11 @@ class SelectorThresholds(TypedDict):
     accel_hi: float
     accel_lo: float
 
-
 class SelectorWeights(TypedDict):
     w_si: float
     w_dnfr: float
     w_accel: float
 
-
 SelectorMetrics: TypeAlias = tuple[float, float, float]
 SelectorNorms: TypeAlias = Mapping[str, float]
 
@@ -107,19 +221,56 @@ class Glyph(str, Enum):
     NAV = "NAV"
     REMESH = "REMESH"
 
+GlyphCode: TypeAlias = Glyph | str
 GlyphLoadDistribution: TypeAlias = dict[Glyph | str, float]
-GlyphSelector: TypeAlias = Callable[[TNFRGraph, NodeId], Glyph | str]
+
+
+class _SelectorLifecycle(Protocol):
+    def __call__(self, graph: TNFRGraph, node: NodeId) -> GlyphCode: ...
+    def prepare(self, graph: TNFRGraph, nodes: Sequence[NodeId]) -> None: ...
+    def select(self, graph: TNFRGraph, node: NodeId) -> GlyphCode: ...
+
+
+GlyphSelector: TypeAlias = Callable[[TNFRGraph, NodeId], GlyphCode] | _SelectorLifecycle
 SelectorPreselectionMetrics: TypeAlias = Mapping[Any, SelectorMetrics]
 SelectorPreselectionChoices: TypeAlias = Mapping[Any, Glyph | str]
 SelectorPreselectionPayload: TypeAlias = tuple[
     SelectorPreselectionMetrics,
     SelectorPreselectionChoices,
 ]
-TraceFieldFn: TypeAlias = Callable[[TNFRGraph], TraceMetadata]
-TraceFieldMap: TypeAlias = Mapping[str, TraceFieldFn]
-TraceFieldRegistry: TypeAlias = dict[str, dict[str, TraceFieldFn]]
+TraceFieldFn: TypeAlias = Callable[[TNFRGraph], "TraceMetadata"]
+TraceFieldMap: TypeAlias = Mapping[str, "TraceFieldFn"]
+TraceFieldRegistry: TypeAlias = dict[str, dict[str, "TraceFieldFn"]]
+
+class TraceMetadata(TypedDict, total=False):
+    gamma: Mapping[str, Any]
+    grammar: Mapping[str, Any]
+    selector: str | None
+    dnfr_weights: Mapping[str, Any]
+    si_weights: Mapping[str, Any]
+    si_sensitivity: Mapping[str, Any]
+    callbacks: Mapping[str, list[str] | None]
+    thol_open_nodes: int
+    kuramoto: Mapping[str, float]
+    sigma: Mapping[str, float]
+    glyphs: Mapping[str, int]
+
+class TraceSnapshot(TraceMetadata, total=False):
+    t: float
+    phase: str
 HistoryState: TypeAlias = _HistoryDict | dict[str, Any]
 TraceCallback: TypeAlias = Callable[[TNFRGraph, dict[str, Any]], None]
+
+
+class CallbackError(TypedDict):
+    event: str
+    step: int | None
+    error: str
+    traceback: str
+    fn: str
+    name: str | None
+
+
 DiagnosisNodeData: TypeAlias = Mapping[str, Any]
 DiagnosisSharedState: TypeAlias = Mapping[str, Any]
 DiagnosisPayload: TypeAlias = dict[str, Any]
@@ -143,3 +294,38 @@ NeighborStats: TypeAlias = tuple[
     Sequence[float] | None,
     Sequence[float] | None,
 ]
+
+GlyphogramRow: TypeAlias = MutableMapping[str, float]
+GlyphTimingTotals: TypeAlias = MutableMapping[str, float]
+GlyphTimingByNode: TypeAlias = MutableMapping[
+    Any, MutableMapping[str, MutableSequence[float]]
+]
+GlyphCounts: TypeAlias = Mapping[str, int]
+GlyphMetricsHistoryValue: TypeAlias = MutableMapping[Any, Any] | MutableSequence[Any]
+GlyphMetricsHistory: TypeAlias = MutableMapping[str, GlyphMetricsHistoryValue]
+MetricsListHistory: TypeAlias = MutableMapping[str, list[Any]]
+
+class RemeshMeta(TypedDict, total=False):
+    alpha: float
+    alpha_source: str
+    tau_global: int
+    tau_local: int
+    step: int | None
+    topo_hash: str | None
+    epi_mean_before: float
+    epi_mean_after: float
+    epi_checksum_before: str
+    epi_checksum_after: str
+    stable_frac_last: float
+    phase_sync_last: float
+    glyph_disr_last: float
+
+class ParallelWijPayload(TypedDict):
+    epi_vals: Sequence[float]
+    vf_vals: Sequence[float]
+    si_vals: Sequence[float]
+    cos_vals: Sequence[float]
+    sin_vals: Sequence[float]
+    weights: tuple[float, float, float, float]
+    epi_range: float
+    vf_range: float