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

tnfr/cli/execution.pyi

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any, Optional
+
+import networkx as nx
+
+from ..constants import METRIC_DEFAULTS
+from ..dynamics import (
+    run,
+    default_glyph_selector,
+    parametric_glyph_selector,
+    validate_canon,
+)
+from ..execution import CANONICAL_PRESET_NAME, play, seq
+from ..flatten import parse_program_tokens
+from ..glyph_history import ensure_history
+from ..io import read_structured_file, safe_write, StructuredFileError
+from ..metrics import (
+    register_metrics_callbacks,
+    glyph_top,
+    export_metrics,
+    build_metrics_summary,
+)
+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 get_logger, json_dumps
+from ..config import apply_config
+from ..config.presets import get_preset
+
+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: ...

tnfr/cli/utils.py

@@ -0,0 +1,34 @@
+"""Utilities for CLI modules."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def spec(opt: str, /, **kwargs: Any) -> tuple[str, dict[str, Any]]:
+    """Create an argument specification pair.
+
+    Parameters
+    ----------
+    opt:
+        Option string to register, e.g. ``"--foo"``.
+    **kwargs:
+        Keyword arguments forwarded to
+        :meth:`argparse.ArgumentParser.add_argument`.
+
+    Returns
+    -------
+    tuple[str, dict[str, Any]]
+        A pair suitable for collecting into argument specification sequences.
+        If ``dest`` is not provided it is
+        derived from ``opt`` by stripping leading dashes and replacing dots and
+        hyphens with underscores. ``default`` defaults to ``None`` so missing
+        options can be filtered easily.
+    """
+
+    kwargs = dict(kwargs)
+    kwargs.setdefault(
+        "dest", opt.lstrip("-").replace("-", "_").replace(".", "_")
+    )
+    kwargs.setdefault("default", None)
+    return opt, kwargs

tnfr/cli/utils.pyi

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

tnfr/config/__init__.py

@@ -0,0 +1,12 @@
+"""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 .init import apply_config, load_config
+
+__all__ = ("load_config", "apply_config")

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/constants.py

@@ -0,0 +1,104 @@
+"""Canonical glyph constants tied to configuration presets."""
+
+from __future__ import annotations
+
+import math
+from types import MappingProxyType
+from typing import Mapping
+
+from ..types import Glyph
+
+# -------------------------
+# Canonical order and functional classifications
+# -------------------------
+
+GLYPHS_CANONICAL: tuple[str, ...] = (
+    Glyph.AL.value,  # 0
+    Glyph.EN.value,  # 1
+    Glyph.IL.value,  # 2
+    Glyph.OZ.value,  # 3
+    Glyph.UM.value,  # 4
+    Glyph.RA.value,  # 5
+    Glyph.SHA.value,  # 6
+    Glyph.VAL.value,  # 7
+    Glyph.NUL.value,  # 8
+    Glyph.THOL.value,  # 9
+    Glyph.ZHIR.value,  # 10
+    Glyph.NAV.value,  # 11
+    Glyph.REMESH.value,  # 12
+)
+
+GLYPHS_CANONICAL_SET: frozenset[str] = frozenset(GLYPHS_CANONICAL)
+
+STABILIZERS: tuple[str, ...] = (
+    Glyph.IL.value,
+    Glyph.RA.value,
+    Glyph.UM.value,
+    Glyph.SHA.value,
+)
+
+DISRUPTORS: tuple[str, ...] = (
+    Glyph.OZ.value,
+    Glyph.ZHIR.value,
+    Glyph.NAV.value,
+    Glyph.THOL.value,
+)
+
+# 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(
+    {
+        "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),
+        "PP_num": (Glyph.SHA.value,),
+        "PP_den": (Glyph.REMESH.value,),
+    }
+)
+
+# -------------------------
+# Glyph angle map
+# -------------------------
+
+# 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]:
+    """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)
+
+    # Orientation rules
+    for idx, g in enumerate(STABILIZERS):
+        angles[g] = idx * math.pi / 4
+    for idx, g in enumerate(DISRUPTORS):
+        angles[g] = math.pi + idx * math.pi / 4
+
+    # Manual exceptions
+    angles[Glyph.VAL.value] = canonical[Glyph.RA.value]
+    angles[Glyph.NUL.value] = canonical[Glyph.ZHIR.value]
+    angles[Glyph.AL.value] = 0.0
+    return angles
+
+
+ANGLE_MAP: Mapping[str, float] = MappingProxyType(_build_angle_map())
+
+__all__ = (
+    "GLYPHS_CANONICAL",
+    "GLYPHS_CANONICAL_SET",
+    "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/init.py

@@ -0,0 +1,36 @@
+"""Core configuration helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from ..constants import inject_defaults
+from ..io import read_structured_file
+
+if TYPE_CHECKING:  # pragma: no cover - only for type checkers
+    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):
+        raise ValueError("Configuration file must contain an object")
+    return data
+
+
+def apply_config(G: "nx.Graph", path: str | Path) -> None:
+    """Inject parameters from ``path`` into ``G.graph``.
+
+    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,106 @@
+"""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})
+
+
+_LEGACY_COLLECTION_ALIASES: dict[str, str] = {
+    "INICIO_VALIDOS": "VALID_START_OPERATORS",
+    "TRAMO_INTERMEDIO": "INTERMEDIATE_OPERATORS",
+    "CIERRE_VALIDO": "VALID_END_OPERATORS",
+    "AUTOORGANIZACION_CIERRES": "SELF_ORGANIZATION_CLOSURES",
+}
+
+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 guidance for legacy operator collection aliases."""
+
+    canonical = _LEGACY_COLLECTION_ALIASES.get(name)
+    if canonical is not None:
+        raise AttributeError(
+            f"module '{__name__}' has no attribute '{name}'; use '{canonical}' instead."
+        )
+    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,104 @@
+"""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}
+
+
+_LEGACY_PRESET_ALIASES: dict[str, str] = {
+    "arranque_resonante": "resonant_bootstrap",
+    "mutacion_contenida": "contained_mutation",
+    "exploracion_acople": "coupling_exploration",
+    "ejemplo_canonico": CANONICAL_PRESET_NAME,
+}
+
+
+def legacy_preset_guidance(name: str) -> str | None:
+    """Return CLI guidance for historical preset aliases.
+
+    Parameters
+    ----------
+    name:
+        Identifier received from the CLI.
+
+    Returns
+    -------
+    str | None
+        A human readable guidance string when ``name`` matches a removed
+        alias. ``None`` when no dedicated guidance is available.
+    """
+
+    canonical = _LEGACY_PRESET_ALIASES.get(name)
+    if canonical is None:
+        return None
+    return (
+        f"Legacy preset identifier '{name}' was removed in TNFR 9.0. "
+        f"Use '{canonical}' instead."
+    )
+
+
+def get_preset(name: str) -> PresetTokens:
+    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