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

tnfr/structural.py

@@ -1,201 +1,106 @@
+"""Structural analysis."""
+
 from __future__ import annotations
-"""API de operadores estructurales y secuencias TNFR.
-
-Este módulo ofrece:
-    - Factoría `create_nfr` para inicializar redes/nodos TNFR.
-    - Clases de operador (`Operador` y derivados) con interfaz común.
-    - Registro de operadores `OPERADORES`.
-    - Utilidades `validate_sequence` y `run_sequence` para ejecutar
-      secuencias canónicas de operadores.
-"""
-from typing import Iterable, Tuple, List
+
+from typing import Iterable
+
 import networkx as nx
 
+from .constants import EPI_PRIMARY, VF_PRIMARY, THETA_PRIMARY
 from .dynamics import (
     set_delta_nfr_hook,
-    update_epi_via_nodal_equation,
     dnfr_epi_vf_mixed,
 )
-from .operators import aplicar_glifo
-from .constants import ALIAS_EPI, ALIAS_VF, ALIAS_THETA
+from .types import DeltaNFRHook, NodeId, TNFRGraph
+from .operators.definitions import (
+    Operator,
+    Emission,
+    Reception,
+    Coherence,
+    Dissonance,
+    Coupling,
+    Resonance,
+    Silence,
+    Expansion,
+    Contraction,
+    SelfOrganization,
+    Mutation,
+    Transition,
+    Recursivity,
+)
+from .operators.registry import OPERATORS
+from .validation import validate_sequence
 
 
 # ---------------------------------------------------------------------------
-# 1) Factoría NFR
+# 1) NFR factory
 # ---------------------------------------------------------------------------
 
+
 def create_nfr(
     name: str,
     *,
     epi: float = 0.0,
     vf: float = 1.0,
     theta: float = 0.0,
-    graph: nx.Graph | None = None,
-    dnfr_hook=dnfr_epi_vf_mixed,
-) -> Tuple[nx.Graph, str]:
-    """Crea una red (graph) con un nodo NFR inicializado.
+    graph: TNFRGraph | None = None,
+    dnfr_hook: DeltaNFRHook = dnfr_epi_vf_mixed,
+) -> tuple[TNFRGraph, str]:
+    """Create a graph with an initialised NFR node.
 
-    Devuelve la tupla ``(G, name)`` para conveniencia.
+    Returns the tuple ``(G, name)`` for convenience.
     """
-    G = graph or nx.Graph()
+    G = graph if graph is not None else nx.Graph()
     G.add_node(
         name,
         **{
-            ALIAS_EPI[0]: float(epi),
-            ALIAS_VF[0]: float(vf),
-            ALIAS_THETA[0]: float(theta),
-        }
+            EPI_PRIMARY: float(epi),
+            VF_PRIMARY: float(vf),
+            THETA_PRIMARY: float(theta),
+        },
     )
     set_delta_nfr_hook(G, dnfr_hook)
     return G, name
 
 
-# ---------------------------------------------------------------------------
-# 2) Operadores estructurales como API de primer orden
-# ---------------------------------------------------------------------------
-
-
-class Operador:
-    """Base para operadores TNFR.
-
-    Cada operador define ``name`` (identificador ASCII) y ``glyph`` (glifo
-    canónico). La llamada ejecuta el glifo correspondiente sobre el nodo.
-    """
-
-    name = "operador"
-    glyph = None  # tipo: str
-
-    def __call__(self, G: nx.Graph, node, **kw) -> None:
-        if self.glyph is None:
-            raise NotImplementedError("Operador sin glifo asignado")
-        aplicar_glifo(G, node, self.glyph, **kw)
-
-
-# Derivados concretos -------------------------------------------------------
-class Emision(Operador):
-    name = "emision"
-    glyph = "A’L"
-
-
-class Recepcion(Operador):
-    name = "recepcion"
-    glyph = "E’N"
-
-
-class Coherencia(Operador):
-    name = "coherencia"
-    glyph = "I’L"
-
-
-class Disonancia(Operador):
-    name = "disonancia"
-    glyph = "O’Z"
-
-
-class Acoplamiento(Operador):
-    name = "acoplamiento"
-    glyph = "U’M"
-
-
-class Resonancia(Operador):
-    name = "resonancia"
-    glyph = "R’A"
-
-
-class Silencio(Operador):
-    name = "silencio"
-    glyph = "SH’A"
-
-
-class Expansion(Operador):
-    name = "expansion"
-    glyph = "VA’L"
-
-
-class Contraccion(Operador):
-    name = "contraccion"
-    glyph = "NU’L"
-
-
-class Autoorganizacion(Operador):
-    name = "autoorganizacion"
-    glyph = "T’HOL"
-
-
-class Mutacion(Operador):
-    name = "mutacion"
-    glyph = "Z’HIR"
-
-
-class Transicion(Operador):
-    name = "transicion"
-    glyph = "NA’V"
-
-
-class Recursividad(Operador):
-    name = "recursividad"
-    glyph = "RE’MESH"
-
-
-OPERADORES = {
-    op().name: op
-    for op in [
-        Emision,
-        Recepcion,
-        Coherencia,
-        Disonancia,
-        Acoplamiento,
-        Resonancia,
-        Silencio,
-        Expansion,
-        Contraccion,
-        Autoorganizacion,
-        Mutacion,
-        Transicion,
-        Recursividad,
-    ]
-}
-
-
-# ---------------------------------------------------------------------------
-# 3) Motor de secuencias + validador sintáctico
-# ---------------------------------------------------------------------------
-
-
-_INICIO_VALIDOS = {"emision", "recursividad"}
-_TRAMO_INTERMEDIO = {"disonancia", "acoplamiento", "resonancia"}
-_CIERRE_VALIDO = {"silencio", "transicion", "recursividad"}
-
+__all__ = (
+    "create_nfr",
+    "Operator",
+    "Emission",
+    "Reception",
+    "Coherence",
+    "Dissonance",
+    "Coupling",
+    "Resonance",
+    "Silence",
+    "Expansion",
+    "Contraction",
+    "SelfOrganization",
+    "Mutation",
+    "Transition",
+    "Recursivity",
+    "OPERATORS",
+    "validate_sequence",
+    "run_sequence",
+)
 
-def validate_sequence(nombres: List[str]) -> Tuple[bool, str]:
-    """Valida reglas mínimas de la sintaxis TNFR."""
-    if not nombres:
-        return False, "secuencia vacía"
-    if nombres[0] not in _INICIO_VALIDOS:
-        return False, "debe iniciar en emisión o recursividad"
-    try:
-        i_rec = nombres.index("recepcion")
-        i_coh = nombres.index("coherencia", i_rec + 1)
-    except ValueError:
-        return False, "falta tramo entrada→coherencia"
-    if not any(n in _TRAMO_INTERMEDIO for n in nombres[i_coh + 1 :]):
-        return False, "falta tramo de tensión/acoplamiento/resonancia"
-    if not any(n in _CIERRE_VALIDO for n in nombres[-2:]):
-        return False, "falta cierre (silencio/transición/recursividad)"
-    return True, "ok"
 
+def run_sequence(G: TNFRGraph, node: NodeId, ops: Iterable[Operator]) -> None:
+    """Execute a sequence of operators on ``node`` after validation."""
 
-def run_sequence(G: nx.Graph, node, ops: Iterable[Operador]) -> None:
-    """Ejecuta una secuencia validada de operadores sobre el nodo dado."""
+    compute = G.graph.get("compute_delta_nfr")
     ops_list = list(ops)
-    nombres = [op.name for op in ops_list]
-    ok, msg = validate_sequence(nombres)
+    names = [op.name for op in ops_list]
+
+    ok, msg = validate_sequence(names)
     if not ok:
-        raise ValueError(f"Secuencia no válida: {msg}")
+        raise ValueError(f"Invalid sequence: {msg}")
+
     for op in ops_list:
         op(G, node)
-        compute = G.graph.get("compute_delta_nfr")
         if callable(compute):
             compute(G)
-        update_epi_via_nodal_equation(G)
-
+        # ``update_epi_via_nodal_equation`` was previously invoked here to
+        # recalculate the EPI value after each operator. The responsibility for
+        # updating EPI now lies with the dynamics hook configured in
+        # ``compute_delta_nfr`` or with external callers.

tnfr/structural.pyi

@@ -0,0 +1,46 @@
+from typing import TYPE_CHECKING, Any, Callable, Hashable, Iterable
+
+from .operators.definitions import (
+    Operator,
+    Emission,
+    Reception,
+    Coherence,
+    Dissonance,
+    Coupling,
+    Resonance,
+    Silence,
+    Expansion,
+    Contraction,
+    SelfOrganization,
+    Mutation,
+    Transition,
+    Recursivity,
+)
+
+if TYPE_CHECKING:
+    import networkx as nx
+
+__all__: tuple[str, ...]
+
+
+def __getattr__(name: str) -> Any: ...
+
+
+def create_nfr(
+    name: str,
+    *,
+    epi: float = ...,
+    vf: float = ...,
+    theta: float = ...,
+    graph: "nx.Graph" | None = ...,
+    dnfr_hook: Callable[..., None] = ...,
+) -> tuple["nx.Graph", str]: ...
+
+
+OPERATORS: dict[str, Operator]
+
+
+def validate_sequence(names: Iterable[str]) -> tuple[bool, str]: ...
+
+
+def run_sequence(G: "nx.Graph", node: Hashable, ops: Iterable[Operator]) -> None: ...

tnfr/telemetry/__init__.py

@@ -0,0 +1,13 @@
+"""Telemetry helpers for shared observability settings."""
+
+from .verbosity import (
+    TelemetryVerbosity,
+    TELEMETRY_VERBOSITY_DEFAULT,
+    TELEMETRY_VERBOSITY_LEVELS,
+)
+
+__all__ = [
+    "TelemetryVerbosity",
+    "TELEMETRY_VERBOSITY_DEFAULT",
+    "TELEMETRY_VERBOSITY_LEVELS",
+]

tnfr/telemetry/verbosity.py

@@ -0,0 +1,37 @@
+"""Canonical telemetry verbosity presets for TNFR structures.
+
+Each level expresses how much structural context is exported in traces and
+metrics:
+
+* ``basic`` preserves lightweight coherence checks for quick health probes.
+* ``detailed`` adds phase alignment and coupling diagnostics to map resonance.
+* ``debug`` captures the full glyph narrative for deep structural forensics.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class TelemetryVerbosity(str, Enum):
+    """Enumerated verbosity tiers shared by trace and metrics pipelines."""
+
+    BASIC = "basic"
+    DETAILED = "detailed"
+    DEBUG = "debug"
+
+
+TELEMETRY_VERBOSITY_LEVELS: tuple[str, ...] = tuple(
+    level.value for level in TelemetryVerbosity
+)
+"""Ordered tuple of canonical telemetry verbosity identifiers."""
+
+TELEMETRY_VERBOSITY_DEFAULT: str = TelemetryVerbosity.DEBUG.value
+"""Default telemetry verbosity preserving complete structural capture."""
+
+
+__all__ = [
+    "TelemetryVerbosity",
+    "TELEMETRY_VERBOSITY_LEVELS",
+    "TELEMETRY_VERBOSITY_DEFAULT",
+]

tnfr/tokens.py

@@ -0,0 +1,61 @@
+"""Token primitives for the TNFR DSL."""
+
+from __future__ import annotations
+
+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.
+
+
+@dataclass(slots=True)
+class WAIT:
+    """Wait a number of steps without applying glyphs."""
+
+    steps: int = 1
+
+
+@dataclass(slots=True)
+class TARGET:
+    """Select the subset of nodes for subsequent glyphs."""
+
+    nodes: Optional[Iterable[Node]] = None  # ``None`` targets all nodes
+
+
+@dataclass(slots=True)
+class THOL:
+    """THOL block that opens self-organisation."""
+
+    body: Sequence[Any]
+    repeat: int = 1
+    force_close: Optional[Glyph] = None
+
+
+Token = Union[Glyph, WAIT, TARGET, THOL, str]
+
+# Sentinel used internally to mark the boundaries of a THOL block during flattening
+THOL_SENTINEL = object()
+
+
+class OpTag(Enum):
+    """Operation tags emitted by the flattening step."""
+
+    TARGET = auto()
+    WAIT = auto()
+    GLYPH = auto()
+    THOL = auto()
+
+
+__all__ = [
+    "Node",
+    "WAIT",
+    "TARGET",
+    "THOL",
+    "Token",
+    "THOL_SENTINEL",
+    "OpTag",
+]

tnfr/tokens.pyi

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Iterable, Optional, Sequence
+
+from .types import Glyph, NodeId
+from ._compat import TypeAlias
+
+__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 = ...
+    GLYPH = ...
+    THOL = ...