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

tnfr/telemetry/nu_f.pyi

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import MutableMapping
+from dataclasses import dataclass
+from typing import Any, Mapping, Sequence
+
+from ..types import GraphLike
+
+__all__ = (
+    "NuFWindow",
+    "NuFSnapshot",
+    "NuFTelemetryAccumulator",
+    "ensure_nu_f_telemetry",
+    "record_nu_f_window",
+)
+
+
+@dataclass
+class NuFWindow:
+    reorganisations: int
+    duration: float
+    start: float | None = ...
+    end: float | None = ...
+
+    def __post_init__(self) -> None: ...
+
+    @classmethod
+    def from_bounds(cls, reorganisations: int, start: float, end: float) -> NuFWindow: ...
+
+    def as_payload(self) -> Mapping[str, float | int | None]: ...
+
+
+@dataclass
+class NuFSnapshot:
+    windows: Sequence[NuFWindow]
+    total_reorganisations: int
+    total_duration: float
+    rate_hz_str: float | None
+    rate_hz: float | None
+    variance_hz_str: float | None
+    variance_hz: float | None
+    confidence_level: float | None
+    ci_lower_hz_str: float | None
+    ci_upper_hz_str: float | None
+    ci_lower_hz: float | None
+    ci_upper_hz: float | None
+
+    def as_payload(self) -> dict[str, Any]: ...
+
+
+class NuFTelemetryAccumulator:
+    _windows: deque[NuFWindow]
+
+    def __init__(
+        self,
+        *,
+        confidence_level: float = ...,
+        history_limit: int | None = ...,
+        window_limit: int | None = ...,
+        graph: GraphLike | MutableMapping[str, Any] | None = ...,
+    ) -> None: ...
+
+    @property
+    def confidence_level(self) -> float: ...
+
+    @property
+    def history_limit(self) -> int | None: ...
+
+    @property
+    def window_limit(self) -> int | None: ...
+
+    def attach_graph(
+        self, graph: GraphLike | MutableMapping[str, Any] | None
+    ) -> None: ...
+
+    def record_window(
+        self,
+        window: NuFWindow,
+        *,
+        graph: GraphLike | MutableMapping[str, Any] | None = ...,
+    ) -> NuFSnapshot: ...
+
+    def record_counts(
+        self,
+        reorganisations: int,
+        duration: float,
+        *,
+        start: float | None = ...,
+        end: float | None = ...,
+        graph: GraphLike | MutableMapping[str, Any] | None = ...,
+    ) -> NuFSnapshot: ...
+
+    def reset(self) -> None: ...
+
+    def snapshot(
+        self,
+        *,
+        graph: GraphLike | MutableMapping[str, Any] | None = ...,
+    ) -> NuFSnapshot: ...
+
+
+def ensure_nu_f_telemetry(
+    graph: GraphLike,
+    *,
+    confidence_level: float | None = ...,
+    history_limit: int | None = ...,
+    window_limit: int | None = ...,
+) -> NuFTelemetryAccumulator: ...
+
+
+def record_nu_f_window(
+    graph: GraphLike,
+    reorganisations: int,
+    duration: float,
+    *,
+    start: float | None = ...,
+    end: float | None = ...,
+    confidence_level: float | None = ...,
+    history_limit: int | None = ...,
+    window_limit: int | None = ...,
+) -> NuFSnapshot: ...
+

tnfr/tokens.py

@@ -6,10 +6,7 @@ from dataclasses import dataclass
 from enum import Enum, auto
 from typing import Any, Iterable, Optional, Sequence, Union
 
-from .types import Glyph, NodeId
-
-Node = NodeId
-#: Alias maintained for backwards compatibility with historical token helpers.
+from .types import Glyph, Node
 
 
 @dataclass(slots=True)

tnfr/tokens.pyi

@@ -4,36 +4,31 @@ from dataclasses import dataclass
 from enum import Enum
 from typing import Iterable, Optional, Sequence
 
-from .types import Glyph, NodeId
 from ._compat import TypeAlias
+from .types import Glyph, NodeId
 
 __all__: tuple[str, ...]
 
 Node: TypeAlias = NodeId
 
-
 @dataclass(slots=True)
 class WAIT:
     steps: int = 1
 
-
 @dataclass(slots=True)
 class TARGET:
     nodes: Optional[Iterable[Node]] = None
 
-
 @dataclass(slots=True)
 class THOL:
     body: Sequence["Token"]
     repeat: int = 1
     force_close: Optional[Glyph] = None
 
-
 Token: TypeAlias = Glyph | WAIT | TARGET | THOL | str
 
 THOL_SENTINEL: object
 
-
 class OpTag(Enum):
     TARGET = ...
     WAIT = ...

tnfr/trace.py

@@ -8,18 +8,16 @@ structures as immutable snapshots.
 from __future__ import annotations
 
 import warnings
-
-from typing import Any, Callable, Protocol, NamedTuple, TypedDict, cast
 from collections.abc import Iterable, Mapping
 from types import MappingProxyType
+from typing import Any, Callable, NamedTuple, Protocol, cast
 
 from .constants import TRACE
-from .glyph_history import ensure_history, count_glyphs, append_metric
-from .utils import cached_import, get_graph_mapping, is_non_string_sequence
+from .glyph_history import append_metric, count_glyphs, ensure_history
 from .metrics.sense_index import _normalise_si_sensitivity_mapping
 from .telemetry.verbosity import (
-    TelemetryVerbosity,
     TELEMETRY_VERBOSITY_DEFAULT,
+    TelemetryVerbosity,
 )
 from .types import (
     SigmaVector,
@@ -28,19 +26,18 @@ from .types import (
     TraceFieldFn,
     TraceFieldMap,
     TraceFieldRegistry,
+    TraceMetadata,
+    TraceSnapshot,
 )
+from .utils import cached_import, get_graph_mapping, is_non_string_sequence
 
 
 class _KuramotoFn(Protocol):
-    def __call__(self, G: TNFRGraph) -> tuple[float, float]:
-        ...
+    def __call__(self, G: TNFRGraph) -> tuple[float, float]: ...
 
 
 class _SigmaVectorFn(Protocol):
-    def __call__(
-        self, G: TNFRGraph, weight_mode: str | None = None
-    ) -> SigmaVector:
-        ...
+    def __call__(self, G: TNFRGraph, weight_mode: str | None = None) -> SigmaVector: ...
 
 
 class CallbackSpec(NamedTuple):
@@ -50,29 +47,6 @@ class CallbackSpec(NamedTuple):
     func: Callable[..., Any]
 
 
-class TraceMetadata(TypedDict, total=False):
-    """Metadata captured by trace field functions."""
-
-    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 snapshot stored in the history."""
-
-    t: float
-    phase: str
-
-
 class TraceFieldSpec(NamedTuple):
     """Declarative specification for a trace field producer."""
 
@@ -153,9 +127,7 @@ kuramoto_R_psi: _KuramotoFn = cast(
 )
 
 
-def _sigma_fallback(
-    G: TNFRGraph, _weight_mode: str | None = None
-) -> SigmaVector:
+def _sigma_fallback(G: TNFRGraph, _weight_mode: str | None = None) -> SigmaVector:
     """Return a null sigma vector regardless of ``_weight_mode``."""
 
     return {"x": 0.0, "y": 0.0, "mag": 0.0, "angle": 0.0, "n": 0}
@@ -187,7 +159,7 @@ def _trace_setup(
     dict[str, Any] | None,
     str | None,
 ]:
-    """Common configuration for trace snapshots.
+    """Prepare common configuration for trace snapshots.
 
     Returns the active configuration, capture set, history and key under
     which metadata will be stored. If tracing is disabled returns
@@ -212,9 +184,7 @@ def _callback_names(
     if isinstance(callbacks, Mapping):
         callbacks = callbacks.values()
     return [
-        cb.name
-        if cb.name is not None
-        else str(getattr(cb.func, "__name__", "fn"))
+        cb.name if cb.name is not None else str(getattr(cb.func, "__name__", "fn"))
         for cb in callbacks
     ]
 
@@ -223,7 +193,7 @@ EMPTY_MAPPING: Mapping[str, Any] = MappingProxyType({})
 
 
 def mapping_field(G: TNFRGraph, graph_key: str, out_key: str) -> TraceMetadata:
-    """Helper to copy mappings from ``G.graph`` into trace output."""
+    """Copy mappings from ``G.graph`` into trace output."""
     mapping = get_graph_mapping(
         G, graph_key, f"G.graph[{graph_key!r}] is not a mapping; ignoring"
     )
@@ -259,9 +229,7 @@ def _new_trace_meta(
 # -------------------------
 
 
-def _trace_capture(
-    G: TNFRGraph, phase: str, fields: TraceFieldMap
-) -> None:
+def _trace_capture(G: TNFRGraph, phase: str, fields: TraceFieldMap) -> None:
     """Capture ``fields`` for ``phase`` and store the snapshot.
 
     A :class:`TraceSnapshot` is appended to the configured history when
@@ -292,19 +260,21 @@ def _trace_capture(
 TRACE_FIELDS: TraceFieldRegistry = {}
 
 
-def register_trace_field(
-    phase: str, name: str, func: TraceFieldFn
-) -> None:
+def register_trace_field(phase: str, name: str, func: TraceFieldFn) -> None:
     """Register ``func`` to populate trace field ``name`` during ``phase``."""
 
     TRACE_FIELDS.setdefault(phase, {})[name] = func
 
 
 def gamma_field(G: TNFRGraph) -> TraceMetadata:
+    """Expose γ-field metadata stored under ``G.graph['GAMMA']``."""
+
     return mapping_field(G, "GAMMA", "gamma")
 
 
 def grammar_field(G: TNFRGraph) -> TraceMetadata:
+    """Expose canonical grammar metadata for trace emission."""
+
     return mapping_field(G, "GRAMMAR_CANON", "grammar")
 
 
@@ -500,9 +470,7 @@ TRACE_FIELD_SPECS: tuple[TraceFieldSpec, ...] = (
 )
 
 TRACE_VERBOSITY_PRESETS = {
-    level.value: tuple(
-        spec.name for spec in TRACE_FIELD_SPECS if level in spec.tiers
-    )
+    level.value: tuple(spec.name for spec in TRACE_FIELD_SPECS if level in spec.tiers)
     for level in TelemetryVerbosity
 }
 
@@ -516,8 +484,7 @@ for spec in TRACE_FIELD_SPECS:
 
 
 def register_trace(G: TNFRGraph) -> None:
-    """Enable before/after-step snapshots and dump operational metadata
-    to history.
+    """Enable before/after-step snapshots and dump operational metadata to history.
 
     Trace snapshots are stored as :class:`TraceSnapshot` entries in
     ``G.graph['history'][TRACE.history_key]`` with:

tnfr/trace.pyi

@@ -1,68 +1,40 @@
-from typing import Any, Callable, NamedTuple, TypedDict
 from collections.abc import Iterable, Mapping
+from typing import Any, Callable, NamedTuple
 
-from .types import TNFRGraph, TraceFieldFn, TraceFieldMap, TraceFieldRegistry
+from .types import (
+    TNFRGraph,
+    TraceFieldFn,
+    TraceFieldMap,
+    TraceFieldRegistry,
+    TraceMetadata,
+    TraceSnapshot,
+)
 
 __all__: tuple[str, ...]
 
 def __getattr__(name: str) -> Any: ...
 
-
 class CallbackSpec(NamedTuple):
     name: str | None
     func: Callable[..., Any]
 
-
-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
-
-
 kuramoto_R_psi: Callable[[TNFRGraph], tuple[float, float]]
 TRACE_FIELDS: TraceFieldRegistry
 
 def _callback_names(
     callbacks: Mapping[str, CallbackSpec] | Iterable[CallbackSpec],
 ) -> list[str]: ...
-
 def mapping_field(G: TNFRGraph, graph_key: str, out_key: str) -> TraceMetadata: ...
-
 def _trace_capture(G: TNFRGraph, phase: str, fields: TraceFieldMap) -> None: ...
-
 def register_trace_field(phase: str, name: str, func: TraceFieldFn) -> None: ...
-
 def gamma_field(G: TNFRGraph) -> TraceMetadata: ...
-
 def grammar_field(G: TNFRGraph) -> TraceMetadata: ...
-
 def dnfr_weights_field(G: TNFRGraph) -> TraceMetadata: ...
-
 def selector_field(G: TNFRGraph) -> TraceMetadata: ...
-
 def si_weights_field(G: TNFRGraph) -> TraceMetadata: ...
-
 def callbacks_field(G: TNFRGraph) -> TraceMetadata: ...
-
 def thol_state_field(G: TNFRGraph) -> TraceMetadata: ...
-
 def kuramoto_field(G: TNFRGraph) -> TraceMetadata: ...
-
 def sigma_field(G: TNFRGraph) -> TraceMetadata: ...
-
 def glyph_counts_field(G: TNFRGraph) -> TraceMetadata: ...
-
 def register_trace(G: TNFRGraph) -> None: ...