tnfr 3.0.3__py3-none-any.whl → 8.5.0__py3-none-any.whl

tnfr/constants/__init__.pyi

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Callable, TypeVar
+
+from ..types import GraphLike, TNFRConfigValue
+from .core import CORE_DEFAULTS as CORE_DEFAULTS
+from .core import REMESH_DEFAULTS as REMESH_DEFAULTS
+from .init import INIT_DEFAULTS as INIT_DEFAULTS
+from .metric import COHERENCE as COHERENCE
+from .metric import DIAGNOSIS as DIAGNOSIS
+from .metric import GRAMMAR_CANON as GRAMMAR_CANON
+from .metric import METRIC_DEFAULTS as METRIC_DEFAULTS
+from .metric import METRICS as METRICS
+from .metric import SIGMA as SIGMA
+from .metric import TRACE as TRACE
+
+T = TypeVar("T")
+
+__all__ = (
+    "CORE_DEFAULTS",
+    "INIT_DEFAULTS",
+    "REMESH_DEFAULTS",
+    "METRIC_DEFAULTS",
+    "SIGMA",
+    "TRACE",
+    "METRICS",
+    "GRAMMAR_CANON",
+    "COHERENCE",
+    "DIAGNOSIS",
+    "DEFAULTS",
+    "DEFAULT_SECTIONS",
+    "ALIASES",
+    "inject_defaults",
+    "merge_overrides",
+    "get_param",
+    "get_graph_param",
+    "get_aliases",
+    "VF_KEY",
+    "THETA_KEY",
+    "VF_PRIMARY",
+    "THETA_PRIMARY",
+    "DNFR_PRIMARY",
+    "EPI_PRIMARY",
+    "EPI_KIND_PRIMARY",
+    "SI_PRIMARY",
+    "dEPI_PRIMARY",
+    "D2EPI_PRIMARY",
+    "dVF_PRIMARY",
+    "D2VF_PRIMARY",
+    "dSI_PRIMARY",
+    "STATE_STABLE",
+    "STATE_TRANSITION",
+    "STATE_DISSONANT",
+    "CANONICAL_STATE_TOKENS",
+    "normalise_state_token",
+)
+
+ensure_node_offset_map: Callable[[GraphLike], None] | None
+DEFAULT_SECTIONS: Mapping[str, Mapping[str, TNFRConfigValue]]
+DEFAULTS: Mapping[str, TNFRConfigValue]
+ALIASES: dict[str, tuple[str, ...]]
+VF_KEY: str
+THETA_KEY: str
+VF_PRIMARY: str
+THETA_PRIMARY: str
+DNFR_PRIMARY: str
+EPI_PRIMARY: str
+EPI_KIND_PRIMARY: str
+SI_PRIMARY: str
+dEPI_PRIMARY: str
+D2EPI_PRIMARY: str
+dVF_PRIMARY: str
+D2VF_PRIMARY: str
+dSI_PRIMARY: str
+STATE_STABLE: str
+STATE_TRANSITION: str
+STATE_DISSONANT: str
+CANONICAL_STATE_TOKENS: frozenset[str]
+
+def inject_defaults(
+    G: GraphLike,
+    defaults: Mapping[str, TNFRConfigValue] = ...,
+    override: bool = ...,
+) -> None: ...
+def merge_overrides(G: GraphLike, **overrides: TNFRConfigValue) -> None: ...
+def get_param(G: GraphLike, key: str) -> TNFRConfigValue: ...
+def get_graph_param(
+    G: GraphLike, key: str, cast: Callable[[object], T] = ...
+) -> T | None: ...
+def get_aliases(key: str) -> tuple[str, ...]: ...
+def normalise_state_token(token: str) -> str: ...

tnfr/constants/aliases.py

@@ -0,0 +1,33 @@
+"""Shared alias constants for TNFR attributes."""
+
+from __future__ import annotations
+
+from . import get_aliases
+
+ALIAS_VF = get_aliases("VF")
+ALIAS_THETA = get_aliases("THETA")
+ALIAS_DNFR = get_aliases("DNFR")
+ALIAS_EPI = get_aliases("EPI")
+ALIAS_EPI_KIND = get_aliases("EPI_KIND")
+ALIAS_SI = get_aliases("SI")
+ALIAS_DEPI = get_aliases("DEPI")
+ALIAS_D2EPI = get_aliases("D2EPI")
+ALIAS_DVF = get_aliases("DVF")
+ALIAS_D2VF = get_aliases("D2VF")
+ALIAS_DSI = get_aliases("DSI")
+ALIAS_EMISSION_TIMESTAMP = get_aliases("EMISSION_TIMESTAMP")
+
+__all__ = [
+    "ALIAS_VF",
+    "ALIAS_THETA",
+    "ALIAS_DNFR",
+    "ALIAS_EPI",
+    "ALIAS_EPI_KIND",
+    "ALIAS_SI",
+    "ALIAS_DEPI",
+    "ALIAS_D2EPI",
+    "ALIAS_DVF",
+    "ALIAS_D2VF",
+    "ALIAS_DSI",
+    "ALIAS_EMISSION_TIMESTAMP",
+]

tnfr/constants/aliases.pyi

@@ -0,0 +1,27 @@
+from _typeshed import Incomplete
+
+__all__ = [
+    "ALIAS_VF",
+    "ALIAS_THETA",
+    "ALIAS_DNFR",
+    "ALIAS_EPI",
+    "ALIAS_EPI_KIND",
+    "ALIAS_SI",
+    "ALIAS_DEPI",
+    "ALIAS_D2EPI",
+    "ALIAS_DVF",
+    "ALIAS_D2VF",
+    "ALIAS_DSI",
+]
+
+ALIAS_VF: Incomplete
+ALIAS_THETA: Incomplete
+ALIAS_DNFR: Incomplete
+ALIAS_EPI: Incomplete
+ALIAS_EPI_KIND: Incomplete
+ALIAS_SI: Incomplete
+ALIAS_DEPI: Incomplete
+ALIAS_D2EPI: Incomplete
+ALIAS_DVF: Incomplete
+ALIAS_D2VF: Incomplete
+ALIAS_DSI: Incomplete

tnfr/constants/init.py

@@ -0,0 +1,33 @@
+"""Initialization constants."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import asdict
+
+from ..compat.dataclass import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class InitDefaults:
+    """Default parameters for node initialisation.
+
+    The fields are collected into :data:`INIT_DEFAULTS` and may therefore
+    appear unused to tools like Vulture.
+    """
+
+    INIT_RANDOM_PHASE: bool = True
+    INIT_THETA_MIN: float = -math.pi
+    INIT_THETA_MAX: float = math.pi
+    INIT_VF_MODE: str = "uniform"
+    INIT_VF_MIN: float | None = None
+    INIT_VF_MAX: float | None = None
+    INIT_VF_MEAN: float = 0.5
+    INIT_VF_STD: float = 0.15
+    INIT_VF_CLAMP_TO_LIMITS: bool = True
+    INIT_SI_MIN: float = 0.4
+    INIT_SI_MAX: float = 0.7
+    INIT_EPI_VALUE: float = 0.0
+
+
+INIT_DEFAULTS = asdict(InitDefaults())

tnfr/constants/init.pyi

@@ -0,0 +1,12 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+INIT_DEFAULTS: Any
+InitDefaults: Any
+annotations: Any
+asdict: Any
+dataclass: Any
+math: Any

tnfr/constants/metric.py

@@ -0,0 +1,104 @@
+"""Metric constants."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, field
+from types import MappingProxyType
+from typing import Any
+
+from ..compat.dataclass import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class MetricDefaults:
+    """Default parameters for metric computation.
+
+    The fields are gathered into :data:`METRIC_DEFAULTS` and exposed through
+    read-only views below, so they may appear unused to static analysis tools.
+    """
+
+    PHASE_HISTORY_MAXLEN: int = 50
+    STOP_EARLY: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": False,
+            "window": 25,
+            "fraction": 0.90,
+        }
+    )
+    SIGMA: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "weight": "Si",  # "Si" | "EPI" | "1"
+            "smooth": 0.0,  # EMA over the global vector (0=off)
+            "history_key": "sigma_global",
+            "per_node": False,
+        }
+    )
+    TRACE: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "verbosity": "debug",
+            "history_key": "trace_meta",
+        }
+    )
+    METRICS: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "save_by_node": True,
+            "normalize_series": False,
+            "n_jobs": 1,
+            "verbosity": "debug",
+        }
+    )
+    GRAMMAR_CANON: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "zhir_requires_oz_window": 3,
+            "zhir_dnfr_min": 0.05,
+            "thol_min_len": 2,
+            "thol_max_len": 6,
+            "thol_close_dnfr": 0.15,
+            "si_high": 0.66,
+        }
+    )
+    COHERENCE: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "scope": "neighbors",
+            "weights": {"phase": 0.34, "epi": 0.33, "vf": 0.20, "si": 0.13},
+            "self_on_diag": True,
+            "store_mode": "sparse",
+            "threshold": 0.0,
+            "n_jobs": 1,
+            "history_key": "W_sparse",
+            "Wi_history_key": "W_i",
+            "stats_history_key": "W_stats",
+        }
+    )
+    DIAGNOSIS: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "window": 16,
+            "history_key": "nodal_diag",
+            "stable": {"Rloc_hi": 0.80, "dnfr_lo": 0.20, "persist": 3},
+            "dissonance": {"Rloc_lo": 0.40, "dnfr_hi": 0.50, "persist": 3},
+            "transition": {"persist": 2},
+            "compute_symmetry": True,
+            "include_typology": False,
+            "advice": {
+                "stable": ["Coherence", "Coupling", "Resonance"],
+                "transition": ["Transition", "Resonance", "Self-organisation"],
+                "dissonant": ["Silence", "Contraction", "Mutation"],
+            },
+        }
+    )
+
+
+METRIC_DEFAULTS = asdict(MetricDefaults())
+
+SIGMA = MappingProxyType(METRIC_DEFAULTS["SIGMA"])
+TRACE = MappingProxyType(METRIC_DEFAULTS["TRACE"])
+METRICS = MappingProxyType(METRIC_DEFAULTS["METRICS"])
+GRAMMAR_CANON = MappingProxyType(METRIC_DEFAULTS["GRAMMAR_CANON"])
+COHERENCE = MappingProxyType(METRIC_DEFAULTS["COHERENCE"])
+DIAGNOSIS = MappingProxyType(METRIC_DEFAULTS["DIAGNOSIS"])

tnfr/constants/metric.pyi

@@ -0,0 +1,19 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+COHERENCE: Any
+DIAGNOSIS: Any
+GRAMMAR_CANON: Any
+METRICS: Any
+METRIC_DEFAULTS: Any
+MappingProxyType: Any
+MetricDefaults: Any
+SIGMA: Any
+TRACE: Any
+annotations: Any
+asdict: Any
+dataclass: Any
+field: Any

tnfr/core/__init__.py

@@ -0,0 +1,33 @@
+"""Core architectural components for TNFR engine.
+
+This package contains the foundational interfaces and dependency injection
+infrastructure that enable separation of responsibilities across the TNFR
+engine layers.
+
+Public API
+----------
+OperatorRegistry, ValidationService, DynamicsEngine, TelemetryCollector
+    Protocol interfaces defining contracts for each architectural layer.
+TNFRContainer
+    Dependency injection container for configuring engine components.
+"""
+
+from __future__ import annotations
+
+from .container import TNFRContainer
+from .interfaces import (
+    DynamicsEngine,
+    OperatorRegistry,
+    TelemetryCollector,
+    TraceContext,
+    ValidationService,
+)
+
+__all__ = (
+    "OperatorRegistry",
+    "ValidationService",
+    "DynamicsEngine",
+    "TelemetryCollector",
+    "TraceContext",
+    "TNFRContainer",
+)

tnfr/core/container.py

@@ -0,0 +1,226 @@
+"""Dependency injection container for TNFR engine components.
+
+This module provides a lightweight dependency injection container that allows
+configuring and resolving engine components (validators, registries, dynamics
+engines, telemetry collectors) without hard-coding implementations.
+
+The container supports both singleton and factory registrations, enabling
+flexible composition of TNFR services while maintaining clean separation of
+concerns.
+
+Examples
+--------
+Create a container with default implementations:
+
+>>> container = TNFRContainer.create_default()
+>>> validator = container.get(ValidationService)
+>>> validator.validate_sequence(["emission", "coherence"])
+
+Register custom implementations:
+
+>>> container = TNFRContainer()
+>>> container.register_singleton(ValidationService, CustomValidator())
+>>> validator = container.get(ValidationService)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, TypeVar
+
+T = TypeVar("T")
+
+__all__ = ("TNFRContainer",)
+
+
+class TNFRContainer:
+    """Dependency injection container for TNFR engine components.
+
+    The container manages the lifecycle of engine services, allowing
+    registration of singletons (reused instances) or factories (fresh
+    instances on each request). This enables flexible configuration without
+    coupling client code to specific implementations.
+
+    Examples
+    --------
+    Basic usage with singleton registration:
+
+    >>> from tnfr.core.interfaces import ValidationService
+    >>> class MyValidator:
+    ...     def validate_sequence(self, seq):
+    ...         pass
+    ...     def validate_graph_state(self, graph):
+    ...         pass
+    >>> container = TNFRContainer()
+    >>> container.register_singleton(ValidationService, MyValidator())
+    >>> validator = container.get(ValidationService)
+
+    Factory registration for per-request instances:
+
+    >>> container.register_factory(ValidationService, MyValidator)
+    >>> v1 = container.get(ValidationService)
+    >>> v2 = container.get(ValidationService)
+    >>> v1 is not v2  # Different instances
+    True
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty container."""
+        self._instances: dict[Any, Any] = {}
+        self._factories: dict[Any, Callable[[], Any]] = {}
+        self._is_singleton: dict[Any, bool] = {}  # Track singleton status
+
+    def register_singleton(self, interface: type[T], implementation: T) -> None:
+        """Register an implementation as a singleton.
+
+        The provided instance will be cached and returned for all subsequent
+        requests for this interface.
+
+        Parameters
+        ----------
+        interface : type
+            The interface or abstract type to register against.
+        implementation : T
+            The concrete instance to return for this interface.
+
+        Examples
+        --------
+        >>> container = TNFRContainer()
+        >>> container.register_singleton(ValidationService, MyValidator())
+        """
+        # Store as a factory that returns the same instance
+        self._factories[interface] = lambda: implementation
+        self._is_singleton[interface] = True
+
+    def register_factory(
+        self, interface: type[T], factory_func: Callable[[], T]
+    ) -> None:
+        """Register a factory function for creating instances.
+
+        The factory will be called each time the interface is requested,
+        allowing fresh instances or cached instances depending on the
+        factory implementation.
+
+        Parameters
+        ----------
+        interface : type
+            The interface or abstract type to register against.
+        factory_func : callable
+            Function that creates and returns an instance of the interface.
+
+        Examples
+        --------
+        >>> container = TNFRContainer()
+        >>> container.register_factory(ValidationService, MyValidator)
+        """
+        self._factories[interface] = factory_func
+        self._is_singleton[interface] = False
+
+    def get(self, interface: type[T]) -> T:
+        """Retrieve an instance implementing the specified interface.
+
+        For singleton registrations, returns the cached instance. For factory
+        registrations, calls the factory to produce an instance.
+
+        Parameters
+        ----------
+        interface : type
+            The interface type to resolve.
+
+        Returns
+        -------
+        T
+            Instance implementing the interface.
+
+        Raises
+        ------
+        ValueError
+            When no factory is registered for the interface.
+
+        Examples
+        --------
+        >>> container = TNFRContainer()
+        >>> container.register_singleton(ValidationService, MyValidator())
+        >>> validator = container.get(ValidationService)
+        """
+        # Check if we have a cached singleton instance
+        if interface in self._instances:
+            return self._instances[interface]
+
+        # Check if we have a factory registered
+        if interface not in self._factories:
+            raise ValueError(
+                f"No factory registered for {interface}. "
+                f"Use register_singleton() or register_factory() first."
+            )
+
+        # Call factory
+        instance = self._factories[interface]()
+
+        # Cache only if registered as singleton
+        if self._is_singleton.get(interface, False):
+            self._instances[interface] = instance
+
+        return instance
+
+    def has(self, interface: type) -> bool:
+        """Check if an interface has a registered factory.
+
+        Parameters
+        ----------
+        interface : type
+            The interface type to check.
+
+        Returns
+        -------
+        bool
+            True if a factory is registered for this interface.
+        """
+        return interface in self._factories
+
+    @classmethod
+    def create_default(cls) -> TNFRContainer:
+        """Create a container with default TNFR implementations.
+
+        This factory method registers the standard implementations of all
+        core interfaces, making it easy to get started with the TNFR engine
+        without manual configuration.
+
+        Returns
+        -------
+        TNFRContainer
+            Container configured with default implementations.
+
+        Examples
+        --------
+        >>> container = TNFRContainer.create_default()
+        >>> validator = container.get(ValidationService)
+        >>> # Use validator with default implementation
+
+        Notes
+        -----
+        The default implementations are imported lazily to avoid circular
+        dependencies. Custom implementations can be registered after creation
+        to override defaults.
+        """
+        from .default_implementations import (
+            DefaultDynamicsEngine,
+            DefaultOperatorRegistry,
+            DefaultTelemetryCollector,
+            DefaultValidationService,
+        )
+        from .interfaces import (
+            DynamicsEngine,
+            OperatorRegistry,
+            TelemetryCollector,
+            ValidationService,
+        )
+
+        container = cls()
+
+        # Register default implementations as singletons
+        container.register_singleton(ValidationService, DefaultValidationService())
+        container.register_singleton(OperatorRegistry, DefaultOperatorRegistry())
+        container.register_singleton(DynamicsEngine, DefaultDynamicsEngine())
+        container.register_singleton(TelemetryCollector, DefaultTelemetryCollector())
+
+        return container