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

tnfr/cli/execution.py

@@ -2,10 +2,11 @@ from __future__ import annotations
 
 import argparse
 
+from copy import deepcopy
 from pathlib import Path
 from typing import Any, Optional
 
-import networkx as nx  # type: ignore[import-untyped]
+import networkx as nx
 
 from ..constants import METRIC_DEFAULTS
 from ..sense import register_sigma_callback
@@ -17,21 +18,24 @@ from ..metrics import (
 )
 from ..metrics.core import _metrics_step
 from ..trace import register_trace
-from ..execution import CANONICAL_PRESET_NAME, play, seq
+from ..execution import CANONICAL_PRESET_NAME, play
 from ..dynamics import (
     run,
     default_glyph_selector,
     parametric_glyph_selector,
     validate_canon,
 )
-from ..presets import get_preset
+from ..config.presets import (
+    PREFERRED_PRESET_NAMES,
+    get_preset,
+    legacy_preset_guidance,
+)
 from ..config import apply_config
 from ..io import read_structured_file, safe_write, StructuredFileError
 from ..glyph_history import ensure_history
-from ..ontosim import preparar_red
-from ..logging_utils import get_logger
-from ..types import Glyph
-from ..json_utils import json_dumps
+from ..ontosim import prepare_network
+from ..types import ProgramTokens
+from ..utils import get_logger, json_dumps
 from ..flatten import parse_program_tokens
 
 from .arguments import _args_to_dict
@@ -43,6 +47,8 @@ logger = get_logger(__name__)
 # inspect the full glyphogram series when needed.
 DEFAULT_SUMMARY_SERIES_LIMIT = 10
 
+_PREFERRED_PRESETS_DISPLAY = ", ".join(PREFERRED_PRESET_NAMES)
+
 
 def _save_json(path: str, data: Any) -> None:
     payload = json_dumps(data, ensure_ascii=False, indent=2, default=list)
@@ -133,6 +139,18 @@ def apply_cli_config(G: "nx.Graph", args: argparse.Namespace) -> None:
             "R0": args.gamma_R0,
         }
 
+    for attr, key in (
+        ("trace_verbosity", "TRACE"),
+        ("metrics_verbosity", "METRICS"),
+    ):
+        cfg = G.graph.get(key)
+        if not isinstance(cfg, dict):
+            cfg = deepcopy(METRIC_DEFAULTS[key])
+            G.graph[key] = cfg
+        value = getattr(args, attr, None)
+        if value is not None:
+            cfg["verbosity"] = value
+
 
 def register_callbacks_and_observer(G: "nx.Graph") -> None:
     _attach_callbacks(G)
@@ -144,12 +162,12 @@ def _build_graph_from_args(args: argparse.Namespace) -> "nx.Graph":
     apply_cli_config(G, args)
     if getattr(args, "observer", False):
         G.graph["ATTACH_STD_OBSERVER"] = True
-    preparar_red(G)
+    prepare_network(G)
     register_callbacks_and_observer(G)
     return G
 
 
-def _load_sequence(path: Path) -> list[Any]:
+def _load_sequence(path: Path) -> ProgramTokens:
     try:
         data = read_structured_file(path)
     except (StructuredFileError, OSError) as exc:
@@ -163,15 +181,29 @@ def _load_sequence(path: Path) -> list[Any]:
 
 
 def resolve_program(
-    args: argparse.Namespace, default: Optional[Any] = None
-) -> Optional[Any]:
+    args: argparse.Namespace, default: Optional[ProgramTokens] = None
+) -> Optional[ProgramTokens]:
     if getattr(args, "preset", None):
         try:
             return get_preset(args.preset)
         except KeyError as exc:
+            guidance = legacy_preset_guidance(args.preset)
+            if guidance is not None:
+                details = guidance
+            else:
+                details = (
+                    exc.args[0]
+                    if exc.args
+                    else "Legacy preset identifier rejected."
+                )
             logger.error(
-                "Preset desconocido '%s'. Usa --sequence-file para cargar secuencias personalizadas",
+                (
+                    "Unknown preset '%s'. Available presets: %s. %s "
+                    "Use --sequence-file to execute custom sequences."
+                ),
                 args.preset,
+                _PREFERRED_PRESETS_DISPLAY,
+                details,
             )
             raise SystemExit(1) from exc
     if getattr(args, "sequence_file", None):
@@ -180,7 +212,9 @@ def resolve_program(
 
 
 def run_program(
-    G: Optional["nx.Graph"], program: Optional[Any], args: argparse.Namespace
+    G: Optional["nx.Graph"],
+    program: Optional[ProgramTokens],
+    args: argparse.Namespace,
 ) -> "nx.Graph":
     if G is None:
         G = _build_graph_from_args(args)
@@ -208,7 +242,7 @@ def run_program(
 def _run_cli_program(
     args: argparse.Namespace,
     *,
-    default_program: Optional[Any] = None,
+    default_program: Optional[ProgramTokens] = None,
     graph: Optional["nx.Graph"] = None,
 ) -> tuple[int, Optional["nx.Graph"]]:
     try:
@@ -229,23 +263,23 @@ def _log_run_summaries(G: "nx.Graph", args: argparse.Namespace) -> None:
     if cfg_coh.get("enabled", True):
         Wstats = hist.get(cfg_coh.get("stats_history_key", "W_stats"), [])
         if Wstats:
-            logger.info("[COHERENCE] último paso: %s", Wstats[-1])
+            logger.info("[COHERENCE] last step: %s", Wstats[-1])
 
     if cfg_diag.get("enabled", True):
         last_diag = hist.get(cfg_diag.get("history_key", "nodal_diag"), [])
         if last_diag:
             sample = list(last_diag[-1].values())[:3]
-            logger.info("[DIAGNOSIS] ejemplo: %s", sample)
+            logger.info("[DIAGNOSIS] sample: %s", sample)
 
     if args.summary:
         summary_limit = getattr(args, "summary_limit", DEFAULT_SUMMARY_SERIES_LIMIT)
         summary, has_latency_values = build_metrics_summary(
             G, series_limit=summary_limit
         )
-        logger.info("Tg global: %s", summary["Tg_global"])
-        logger.info("Top operadores por Tg: %s", glyph_top(G, k=5))
+        logger.info("Global Tg: %s", summary["Tg_global"])
+        logger.info("Top operators by Tg: %s", glyph_top(G, k=5))
         if has_latency_values:
-            logger.info("Latencia media: %s", summary["latency_mean"])
+            logger.info("Average latency: %s", summary["latency_mean"])
 
 
 def cmd_run(args: argparse.Namespace) -> int:
@@ -261,7 +295,7 @@ def cmd_run(args: argparse.Namespace) -> int:
 def cmd_sequence(args: argparse.Namespace) -> int:
     if args.preset and args.sequence_file:
         logger.error(
-            "No se puede usar --preset y --sequence-file al mismo tiempo"
+            "Cannot use --preset and --sequence-file at the same time"
         )
         return 1
     code, _ = _run_cli_program(

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

@@ -32,5 +32,3 @@ def spec(opt: str, /, **kwargs: Any) -> tuple[str, dict[str, Any]]:
     )
     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.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 ..io 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,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