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

tnfr/cli/execution.pyi

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any, Optional
+
+import networkx as nx
+
+from ..config import apply_config
+from ..config.presets import get_preset
+from ..constants import METRIC_DEFAULTS
+from ..dynamics import (
+    default_glyph_selector,
+    parametric_glyph_selector,
+    run,
+    validate_canon,
+)
+from ..execution import CANONICAL_PRESET_NAME, play, seq
+from ..flatten import parse_program_tokens
+from ..glyph_history import ensure_history
+from ..metrics import (
+    build_metrics_summary,
+    export_metrics,
+    glyph_top,
+    register_metrics_callbacks,
+)
+from ..metrics.core import _metrics_step
+from ..ontosim import prepare_network
+from ..sense import register_sigma_callback
+from ..trace import register_trace
+from ..types import Glyph, ProgramTokens
+from ..utils import (
+    StructuredFileError,
+    get_logger,
+    json_dumps,
+    read_structured_file,
+    safe_write,
+)
+from .arguments import _args_to_dict
+
+DEFAULT_SUMMARY_SERIES_LIMIT: int
+logger: Any
+
+def _save_json(path: str, data: Any) -> None: ...
+def _attach_callbacks(G: nx.Graph) -> None: ...
+def _persist_history(G: nx.Graph, args: argparse.Namespace) -> None: ...
+def build_basic_graph(args: argparse.Namespace) -> nx.Graph: ...
+def apply_cli_config(G: nx.Graph, args: argparse.Namespace) -> None: ...
+def register_callbacks_and_observer(G: nx.Graph) -> None: ...
+def _build_graph_from_args(args: argparse.Namespace) -> nx.Graph: ...
+def _load_sequence(path: Path) -> ProgramTokens: ...
+def resolve_program(
+    args: argparse.Namespace, default: Optional[ProgramTokens] = ...
+) -> Optional[ProgramTokens]: ...
+def run_program(
+    G: Optional[nx.Graph],
+    program: Optional[ProgramTokens],
+    args: argparse.Namespace,
+) -> nx.Graph: ...
+def _run_cli_program(
+    args: argparse.Namespace,
+    *,
+    default_program: Optional[ProgramTokens] = ...,
+    graph: Optional[nx.Graph] = ...,
+) -> tuple[int, Optional[nx.Graph]]: ...
+def _log_run_summaries(G: nx.Graph, args: argparse.Namespace) -> None: ...
+def cmd_run(args: argparse.Namespace) -> int: ...
+def cmd_sequence(args: argparse.Namespace) -> int: ...
+def cmd_metrics(args: argparse.Namespace) -> int: ...
+def cmd_profile_si(args: argparse.Namespace) -> int: ...

tnfr/cli/utils.py

@@ -2,8 +2,11 @@
 
 from __future__ import annotations
 
+from collections.abc import Iterable
 from typing import Any
 
+from ..utils import normalize_optional_int
+
 
 def spec(opt: str, /, **kwargs: Any) -> tuple[str, dict[str, Any]]:
     """Create an argument specification pair.
@@ -27,10 +30,22 @@ def spec(opt: str, /, **kwargs: Any) -> tuple[str, dict[str, Any]]:
     """
 
     kwargs = dict(kwargs)
-    kwargs.setdefault(
-        "dest", opt.lstrip("-").replace("-", "_").replace(".", "_")
-    )
+    kwargs.setdefault("dest", opt.lstrip("-").replace("-", "_").replace(".", "_"))
     kwargs.setdefault("default", None)
     return opt, kwargs
 
 
+def _parse_cli_variants(values: Iterable[Any] | None) -> list[int | None]:
+    """Return a stable list of integer/``None`` variants for the CLI options."""
+
+    if values is None:
+        return [None]
+    parsed: list[int | None] = []
+    seen: set[int | None] = set()
+    for raw in values:
+        coerced = normalize_optional_int(raw, strict=True)
+        if coerced in seen:
+            continue
+        seen.add(coerced)
+        parsed.append(coerced)
+    return parsed or [None]

tnfr/cli/utils.pyi

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+def spec(opt: str, /, **kwargs: Any) -> tuple[str, dict[str, Any]]: ...
+
+def _parse_cli_variants(values: Iterable[Any] | None) -> list[int | None]: ...

tnfr/config/__init__.py

@@ -0,0 +1,13 @@
+"""Configuration package for TNFR.
+
+This package groups helpers and canonical defaults that orchestrate how
+configuration payloads interact with the engine.  The public API mirrors the
+previous module level functions so downstream importers remain stable.
+"""
+
+from __future__ import annotations
+
+from .feature_flags import context_flags, get_flags
+from .init import apply_config, load_config
+
+__all__ = ("load_config", "apply_config", "get_flags", "context_flags")

tnfr/config/__init__.pyi

@@ -0,0 +1,10 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+apply_config: Any
+load_config: Any
+get_flags: Any
+context_flags: Any

tnfr/{constants_glyphs.py → config/constants.py}

@@ -1,4 +1,4 @@
-"""Default glyphs."""
+"""Canonical glyph constants tied to configuration presets."""
 
 from __future__ import annotations
 
@@ -6,10 +6,10 @@ import math
 from types import MappingProxyType
 from typing import Mapping
 
-from .types import Glyph
+from ..types import Glyph
 
 # -------------------------
-# Orden canónico y clasificaciones funcionales
+# Canonical order and functional classifications
 # -------------------------
 
 GLYPHS_CANONICAL: tuple[str, ...] = (
@@ -30,26 +30,31 @@ GLYPHS_CANONICAL: tuple[str, ...] = (
 
 GLYPHS_CANONICAL_SET: frozenset[str] = frozenset(GLYPHS_CANONICAL)
 
-ESTABILIZADORES = (
+STABILIZERS: tuple[str, ...] = (
     Glyph.IL.value,
     Glyph.RA.value,
     Glyph.UM.value,
     Glyph.SHA.value,
 )
 
-DISRUPTIVOS = (
+DISRUPTORS: tuple[str, ...] = (
     Glyph.OZ.value,
     Glyph.ZHIR.value,
     Glyph.NAV.value,
     Glyph.THOL.value,
 )
 
-# Mapa general de agrupaciones glíficas para referencia cruzada.
+# General map of glyph groupings for cross-reference.
+#
+# Spanish keys (``estabilizadores`` / ``disruptivos``) were removed in TNFR 7.0
+# to keep the public surface English-only. Code that still referenced those
+# identifiers must switch to the canonical ``stabilizers`` / ``disruptors``
+# entries or maintain a private compatibility layer.
 GLYPH_GROUPS: Mapping[str, tuple[str, ...]] = MappingProxyType(
     {
-        "estabilizadores": ESTABILIZADORES,
-        "disruptivos": DISRUPTIVOS,
-        # Grupos auxiliares para métricas morfosintácticas
+        "stabilizers": STABILIZERS,
+        "disruptors": DISRUPTORS,
+        # Auxiliary groups for morphosyntactic metrics
         "ID": (Glyph.OZ.value,),
         "CM": (Glyph.ZHIR.value, Glyph.NAV.value),
         "NE": (Glyph.IL.value, Glyph.THOL.value),
@@ -59,27 +64,28 @@ GLYPH_GROUPS: Mapping[str, tuple[str, ...]] = MappingProxyType(
 )
 
 # -------------------------
-# Mapa de ángulos glíficos
+# Glyph angle map
 # -------------------------
 
-# Ángulos canónicos para todos los glyphs reconocidos. Se calculan a partir
-# del orden canónico y reglas de orientación para las categorías
-# "estabilizadores" y "disruptivos".
+# Canonical angles for all recognised glyphs. They are computed from the
+# canonical order and orientation rules for the "stabilizers" and
+# "disruptors" categories.
 
 
 def _build_angle_map() -> dict[str, float]:
-    """Construir el mapa de ángulos en el plano σ."""
+    """Build the angle map in the σ-plane."""
+
     step = 2 * math.pi / len(GLYPHS_CANONICAL)
     canonical = {g: i * step for i, g in enumerate(GLYPHS_CANONICAL)}
     angles = dict(canonical)
 
-    # Reglas específicas de orientación
-    for idx, g in enumerate(ESTABILIZADORES):
+    # Orientation rules
+    for idx, g in enumerate(STABILIZERS):
         angles[g] = idx * math.pi / 4
-    for idx, g in enumerate(DISRUPTIVOS):
+    for idx, g in enumerate(DISRUPTORS):
         angles[g] = math.pi + idx * math.pi / 4
 
-    # Excepciones manuales
+    # Manual exceptions
     angles[Glyph.VAL.value] = canonical[Glyph.RA.value]
     angles[Glyph.NUL.value] = canonical[Glyph.ZHIR.value]
     angles[Glyph.AL.value] = 0.0
@@ -91,8 +97,8 @@ ANGLE_MAP: Mapping[str, float] = MappingProxyType(_build_angle_map())
 __all__ = (
     "GLYPHS_CANONICAL",
     "GLYPHS_CANONICAL_SET",
-    "ESTABILIZADORES",
-    "DISRUPTIVOS",
+    "STABILIZERS",
+    "DISRUPTORS",
     "GLYPH_GROUPS",
     "ANGLE_MAP",
 )

tnfr/config/constants.pyi

@@ -0,0 +1,12 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+ANGLE_MAP: Any
+DISRUPTORS: Any
+STABILIZERS: Any
+GLYPHS_CANONICAL: Any
+GLYPHS_CANONICAL_SET: Any
+GLYPH_GROUPS: Any

tnfr/config/feature_flags.py

@@ -0,0 +1,83 @@
+"""Math feature flag configuration helpers."""
+
+from __future__ import annotations
+
+import os
+from contextlib import contextmanager
+from dataclasses import dataclass, replace
+from typing import Iterator
+
+__all__ = ("MathFeatureFlags", "get_flags", "context_flags")
+
+
+@dataclass(frozen=True)
+class MathFeatureFlags:
+    """Toggle optional mathematical behaviours in the engine."""
+
+    enable_math_validation: bool = False
+    enable_math_dynamics: bool = False
+    log_performance: bool = False
+    math_backend: str = "numpy"
+
+
+_TRUE_VALUES = {"1", "true", "on", "yes", "y", "t"}
+_FALSE_VALUES = {"0", "false", "off", "no", "n", "f"}
+
+_BASE_FLAGS: MathFeatureFlags | None = None
+_FLAGS_STACK: list[MathFeatureFlags] = []
+
+
+def _parse_env_flag(name: str, default: bool) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    lowered = value.strip().lower()
+    if lowered in _TRUE_VALUES:
+        return True
+    if lowered in _FALSE_VALUES:
+        return False
+    return default
+
+
+def _load_base_flags() -> MathFeatureFlags:
+    global _BASE_FLAGS
+    if _BASE_FLAGS is None:
+        backend = os.getenv("TNFR_MATH_BACKEND")
+        backend_choice = backend.strip() if backend else "numpy"
+        _BASE_FLAGS = MathFeatureFlags(
+            enable_math_validation=_parse_env_flag(
+                "TNFR_ENABLE_MATH_VALIDATION", False
+            ),
+            enable_math_dynamics=_parse_env_flag(
+                "TNFR_ENABLE_MATH_DYNAMICS", False
+            ),
+            log_performance=_parse_env_flag("TNFR_LOG_PERF", False),
+            math_backend=backend_choice or "numpy",
+        )
+    return _BASE_FLAGS
+
+
+def get_flags() -> MathFeatureFlags:
+    """Return the currently active feature flags."""
+
+    if _FLAGS_STACK:
+        return _FLAGS_STACK[-1]
+    return _load_base_flags()
+
+
+@contextmanager
+def context_flags(**overrides: bool) -> Iterator[MathFeatureFlags]:
+    """Temporarily override math feature flags."""
+
+    invalid = set(overrides) - set(MathFeatureFlags.__annotations__)
+    if invalid:
+        invalid_names = ", ".join(sorted(invalid))
+        raise TypeError(f"Unknown flag overrides: {invalid_names}")
+
+    previous = get_flags()
+    next_flags = replace(previous, **overrides)
+    _FLAGS_STACK.append(next_flags)
+    try:
+        yield next_flags
+    finally:
+        _FLAGS_STACK.pop()

tnfr/{config.py → config/init.py}

@@ -1,21 +1,23 @@
-"""Configuration utilities."""
+"""Core configuration helpers."""
 
 from __future__ import annotations
-from typing import Any, TYPE_CHECKING
+
 from collections.abc import Mapping
 from pathlib import Path
-from .io import read_structured_file
+from typing import TYPE_CHECKING, Any
 
-from .constants import inject_defaults
+from ..constants import inject_defaults
+from ..utils import read_structured_file
 
 if TYPE_CHECKING:  # pragma: no cover - only for type checkers
-    import networkx as nx  # type: ignore[import-untyped]
+    import networkx as nx
 
 __all__ = ("load_config", "apply_config")
 
 
 def load_config(path: str | Path) -> Mapping[str, Any]:
     """Read a JSON/YAML file and return a mapping with parameters."""
+
     path_obj = path if isinstance(path, Path) else Path(path)
     data = read_structured_file(path_obj)
     if not isinstance(data, Mapping):
@@ -23,10 +25,12 @@ def load_config(path: str | Path) -> Mapping[str, Any]:
     return data
 
 
-def apply_config(G: nx.Graph, path: str | Path) -> None:
+def apply_config(G: "nx.Graph", path: str | Path) -> None:
     """Inject parameters from ``path`` into ``G.graph``.
 
-    Reuses :func:`inject_defaults` to keep canonical default semantics.
+    Reuses :func:`tnfr.constants.inject_defaults` to keep canonical default
+    semantics.
     """
+
     cfg = load_config(path)
     inject_defaults(G, cfg, override=True)

tnfr/config/init.pyi

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

tnfr/config/operator_names.py

@@ -0,0 +1,93 @@
+"""Canonical operator name constants and reusable sets."""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Canonical operator identifiers (English tokens)
+EMISSION = "emission"
+RECEPTION = "reception"
+COHERENCE = "coherence"
+DISSONANCE = "dissonance"
+COUPLING = "coupling"
+RESONANCE = "resonance"
+SILENCE = "silence"
+EXPANSION = "expansion"
+CONTRACTION = "contraction"
+SELF_ORGANIZATION = "self_organization"
+MUTATION = "mutation"
+TRANSITION = "transition"
+RECURSIVITY = "recursivity"
+
+
+# Canonical collections -------------------------------------------------------
+
+CANONICAL_OPERATOR_NAMES = frozenset(
+    {
+        EMISSION,
+        RECEPTION,
+        COHERENCE,
+        DISSONANCE,
+        COUPLING,
+        RESONANCE,
+        SILENCE,
+        EXPANSION,
+        CONTRACTION,
+        SELF_ORGANIZATION,
+        MUTATION,
+        TRANSITION,
+        RECURSIVITY,
+    }
+)
+
+ALL_OPERATOR_NAMES = CANONICAL_OPERATOR_NAMES
+ENGLISH_OPERATOR_NAMES = CANONICAL_OPERATOR_NAMES
+
+VALID_START_OPERATORS = frozenset({EMISSION, RECURSIVITY})
+INTERMEDIATE_OPERATORS = frozenset({DISSONANCE, COUPLING, RESONANCE})
+VALID_END_OPERATORS = frozenset({SILENCE, TRANSITION, RECURSIVITY})
+SELF_ORGANIZATION_CLOSURES = frozenset({SILENCE, CONTRACTION})
+
+
+def canonical_operator_name(name: str) -> str:
+    """Return the canonical operator token for ``name``."""
+
+    return name
+
+
+def operator_display_name(name: str) -> str:
+    """Return the display label for ``name`` (currently the canonical token)."""
+
+    return canonical_operator_name(name)
+
+
+__all__ = [
+    "EMISSION",
+    "RECEPTION",
+    "COHERENCE",
+    "DISSONANCE",
+    "COUPLING",
+    "RESONANCE",
+    "SILENCE",
+    "EXPANSION",
+    "CONTRACTION",
+    "SELF_ORGANIZATION",
+    "MUTATION",
+    "TRANSITION",
+    "RECURSIVITY",
+    "CANONICAL_OPERATOR_NAMES",
+    "ENGLISH_OPERATOR_NAMES",
+    "ALL_OPERATOR_NAMES",
+    "VALID_START_OPERATORS",
+    "INTERMEDIATE_OPERATORS",
+    "VALID_END_OPERATORS",
+    "SELF_ORGANIZATION_CLOSURES",
+    "canonical_operator_name",
+    "operator_display_name",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Provide a consistent ``AttributeError`` when names are missing."""
+
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

tnfr/config/operator_names.pyi

@@ -0,0 +1,28 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+ALL_OPERATOR_NAMES: Any
+CANONICAL_OPERATOR_NAMES: Any
+COHERENCE: Any
+CONTRACTION: Any
+COUPLING: Any
+DISSONANCE: Any
+EMISSION: Any
+ENGLISH_OPERATOR_NAMES: Any
+EXPANSION: Any
+INTERMEDIATE_OPERATORS: Any
+MUTATION: Any
+RECEPTION: Any
+RECURSIVITY: Any
+RESONANCE: Any
+SELF_ORGANIZATION: Any
+SELF_ORGANIZATION_CLOSURES: Any
+SILENCE: Any
+TRANSITION: Any
+VALID_END_OPERATORS: Any
+VALID_START_OPERATORS: Any
+canonical_operator_name: Any
+operator_display_name: Any

tnfr/config/presets.py

@@ -0,0 +1,84 @@
+"""Predefined TNFR configuration sequences.
+
+Only the canonical English preset identifiers are recognised.
+"""
+
+from __future__ import annotations
+
+from ..execution import (
+    CANONICAL_PRESET_NAME,
+    CANONICAL_PROGRAM_TOKENS,
+    block,
+    seq,
+    wait,
+)
+from ..types import Glyph, PresetTokens
+
+__all__ = (
+    "get_preset",
+    "PREFERRED_PRESET_NAMES",
+    "legacy_preset_guidance",
+)
+
+
+_PRIMARY_PRESETS: dict[str, PresetTokens] = {
+    "resonant_bootstrap": seq(
+        Glyph.AL,
+        Glyph.EN,
+        Glyph.IL,
+        Glyph.RA,
+        Glyph.VAL,
+        Glyph.UM,
+        wait(3),
+        Glyph.SHA,
+    ),
+    "contained_mutation": seq(
+        Glyph.AL,
+        Glyph.EN,
+        block(Glyph.OZ, Glyph.ZHIR, Glyph.IL, repeat=2),
+        Glyph.RA,
+        Glyph.SHA,
+    ),
+    "coupling_exploration": seq(
+        Glyph.AL,
+        Glyph.EN,
+        Glyph.IL,
+        Glyph.VAL,
+        Glyph.UM,
+        block(Glyph.OZ, Glyph.NAV, Glyph.IL, repeat=1),
+        Glyph.RA,
+        Glyph.SHA,
+    ),
+    "fractal_expand": seq(
+        block(Glyph.THOL, Glyph.VAL, Glyph.UM, repeat=2, close=Glyph.NUL),
+        Glyph.RA,
+    ),
+    "fractal_contract": seq(
+        block(Glyph.THOL, Glyph.NUL, Glyph.UM, repeat=2, close=Glyph.SHA),
+        Glyph.RA,
+    ),
+    CANONICAL_PRESET_NAME: list(CANONICAL_PROGRAM_TOKENS),
+}
+
+PREFERRED_PRESET_NAMES: tuple[str, ...] = tuple(_PRIMARY_PRESETS.keys())
+
+_PRESETS: dict[str, PresetTokens] = {**_PRIMARY_PRESETS}
+
+
+def legacy_preset_guidance(name: str) -> str | None:
+    """Return CLI guidance for preset lookups.
+
+    Legacy aliases were removed; the function now always returns ``None``.
+    ``name`` is accepted to preserve the public helper signature.
+    """
+
+    return None
+
+
+def get_preset(name: str) -> PresetTokens:
+    """Return the preset token sequence identified by ``name``."""
+
+    try:
+        return _PRESETS[name]
+    except KeyError:
+        raise KeyError(f"Preset not found: {name}") from None

tnfr/config/presets.pyi

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