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

tnfr/execution.py

@@ -4,28 +4,24 @@ from __future__ import annotations
 
 from collections import deque
 from collections.abc import Callable, Iterable, Sequence
-from typing import Any, Optional
+from typing import Any, Optional, cast
 
-import networkx as nx  # networkx is used at runtime
-
-from .collections_utils import (
-    MAX_MATERIALIZE_DEFAULT,
-    ensure_collection,
-    is_non_string_sequence,
-)
+from ._compat import TypeAlias
 from .constants import get_param
 from .dynamics import step
 from .flatten import _flatten
 from .glyph_history import ensure_history
-from .grammar import apply_glyph_with_grammar
-from .tokens import OpTag, TARGET, THOL, WAIT, Token
-from .types import Glyph
-
-Node = Any
-AdvanceFn = Callable[[Any], None]
+from .tokens import TARGET, THOL, WAIT, OpTag, Token
+from .types import Glyph, NodeId, TNFRGraph
+from .utils import MAX_MATERIALIZE_DEFAULT, ensure_collection, is_non_string_sequence
+from .validation import apply_glyph_with_grammar
+
+AdvanceFn = Callable[[TNFRGraph], None]
+TraceEntry = dict[str, Any]
+ProgramTrace: TypeAlias = deque[TraceEntry]
 HandlerFn = Callable[
-    [nx.Graph, Any, Optional[list[Node]], deque, AdvanceFn],
-    Optional[list[Node]],
+    [TNFRGraph, Any, Optional[Sequence[NodeId]], ProgramTrace, AdvanceFn],
+    Optional[Sequence[NodeId]],
 ]
 
 __all__ = [
@@ -44,25 +40,25 @@ __all__ = [
     "wait",
 ]
 
-
-CANONICAL_PRESET_NAME = "ejemplo_canonico"
+CANONICAL_PRESET_NAME = "canonical_example"
 CANONICAL_PROGRAM_TOKENS: tuple[Token, ...] = (
-    Glyph.SHA,
-    Glyph.AL,
-    Glyph.RA,
-    Glyph.ZHIR,
-    Glyph.NUL,
-    Glyph.THOL,
+    Glyph.SHA,  # silence - initial stabilization
+    Glyph.AL,  # emission - initiate pattern
+    Glyph.RA,  # reception - capture information
+    Glyph.OZ,  # dissonance - required before mutation (grammar rule)
+    Glyph.ZHIR,  # mutation - phase change
+    Glyph.NUL,  # contraction - compress structure
+    Glyph.THOL,  # self_organization - recursive reorganization
 )
 
 
-def _window(G) -> int:
+def _window(G: TNFRGraph) -> int:
     return int(get_param(G, "GLYPH_HYSTERESIS_WINDOW"))
 
 
 def _apply_glyph_to_targets(
-    G, g: Glyph | str, nodes: Optional[Iterable[Node]] = None
-):
+    G: TNFRGraph, g: Glyph | str, nodes: Optional[Iterable[NodeId]] = None
+) -> None:
     """Apply ``g`` to ``nodes`` (or all nodes) respecting the grammar."""
 
     nodes_iter = G.nodes() if nodes is None else nodes
@@ -70,22 +66,24 @@ def _apply_glyph_to_targets(
     apply_glyph_with_grammar(G, nodes_iter, g, w)
 
 
-def _advance(G, step_fn: AdvanceFn):
+def _advance(G: TNFRGraph, step_fn: AdvanceFn) -> None:
     step_fn(G)
 
 
-def _record_trace(trace: deque, G, op: OpTag, **data) -> None:
+def _record_trace(trace: ProgramTrace, G: TNFRGraph, op: OpTag, **data: Any) -> None:
+    """Append an operation snapshot to ``trace`` using graph time metadata."""
+
     trace.append({"t": float(G.graph.get("_t", 0.0)), "op": op.name, **data})
 
 
 def _advance_and_record(
-    G,
-    trace: deque,
+    G: TNFRGraph,
+    trace: ProgramTrace,
     label: OpTag,
     step_fn: AdvanceFn,
     *,
     times: int = 1,
-    **data,
+    **data: Any,
 ) -> None:
     for _ in range(times):
         _advance(G, step_fn)
@@ -93,40 +91,55 @@ def _advance_and_record(
 
 
 def _handle_target(
-    G, payload: TARGET, _curr_target, trace: deque, _step_fn: AdvanceFn
-):
+    G: TNFRGraph,
+    payload: TARGET,
+    _curr_target: Optional[Sequence[NodeId]],
+    trace: ProgramTrace,
+    _step_fn: AdvanceFn,
+) -> Sequence[NodeId]:
     """Handle a ``TARGET`` token and return the active node set."""
 
     nodes_src = G.nodes() if payload.nodes is None else payload.nodes
     nodes = ensure_collection(nodes_src, max_materialize=None)
-    curr_target = nodes if is_non_string_sequence(nodes) else tuple(nodes)
+    if is_non_string_sequence(nodes):
+        curr_target = cast(Sequence[NodeId], nodes)
+    else:
+        curr_target = tuple(nodes)
     _record_trace(trace, G, OpTag.TARGET, n=len(curr_target))
     return curr_target
 
 
 def _handle_wait(
-    G, steps: int, curr_target, trace: deque, step_fn: AdvanceFn
-):
+    G: TNFRGraph,
+    steps: int,
+    curr_target: Optional[Sequence[NodeId]],
+    trace: ProgramTrace,
+    step_fn: AdvanceFn,
+) -> Optional[Sequence[NodeId]]:
     _advance_and_record(G, trace, OpTag.WAIT, step_fn, times=steps, k=steps)
     return curr_target
 
 
 def _handle_glyph(
-    G,
-    g: str,
-    curr_target,
-    trace: deque,
+    G: TNFRGraph,
+    g: Glyph | str,
+    curr_target: Optional[Sequence[NodeId]],
+    trace: ProgramTrace,
     step_fn: AdvanceFn,
     label: OpTag = OpTag.GLYPH,
-):
+) -> Optional[Sequence[NodeId]]:
     _apply_glyph_to_targets(G, g, curr_target)
     _advance_and_record(G, trace, label, step_fn, g=g)
     return curr_target
 
 
 def _handle_thol(
-    G, g, curr_target, trace: deque, step_fn: AdvanceFn
-):
+    G: TNFRGraph,
+    g: Glyph | str | None,
+    curr_target: Optional[Sequence[NodeId]],
+    trace: ProgramTrace,
+    step_fn: AdvanceFn,
+) -> Optional[Sequence[NodeId]]:
     return _handle_glyph(
         G, g or Glyph.THOL.value, curr_target, trace, step_fn, label=OpTag.THOL
     )
@@ -141,20 +154,23 @@ HANDLERS: dict[OpTag, HandlerFn] = {
 
 
 def play(
-    G, sequence: Sequence[Token], step_fn: Optional[AdvanceFn] = None
+    G: TNFRGraph, sequence: Sequence[Token], step_fn: Optional[AdvanceFn] = None
 ) -> None:
     """Execute a canonical sequence on graph ``G``."""
 
     step_fn = step_fn or step
 
-    curr_target: Optional[list[Node]] = None
+    curr_target: Optional[Sequence[NodeId]] = None
 
     history = ensure_history(G)
     maxlen = int(get_param(G, "PROGRAM_TRACE_MAXLEN"))
-    trace = history.get("program_trace")
-    if not isinstance(trace, deque) or trace.maxlen != maxlen:
-        trace = deque(trace or [], maxlen=maxlen)
+    trace_obj = history.get("program_trace")
+    trace: ProgramTrace
+    if not isinstance(trace_obj, deque) or trace_obj.maxlen != maxlen:
+        trace = cast(ProgramTrace, deque(trace_obj or [], maxlen=maxlen))
         history["program_trace"] = trace
+    else:
+        trace = cast(ProgramTrace, trace_obj)
 
     for op, payload in _flatten(sequence):
         handler: HandlerFn | None = HANDLERS.get(op)
@@ -174,28 +190,34 @@ def compile_sequence(
 
 
 def seq(*tokens: Token) -> list[Token]:
+    """Return a mutable list of ``tokens`` for explicit sequence editing."""
+
     return list(tokens)
 
 
-def block(
-    *tokens: Token, repeat: int = 1, close: Optional[Glyph] = None
-) -> THOL:
+def block(*tokens: Token, repeat: int = 1, close: Optional[Glyph] = None) -> THOL:
+    """Build a THOL block with optional repetition and forced closure."""
+
     return THOL(body=list(tokens), repeat=repeat, force_close=close)
 
 
-def target(nodes: Optional[Iterable[Node]] = None) -> TARGET:
+def target(nodes: Optional[Iterable[NodeId]] = None) -> TARGET:
+    """Return a TARGET token selecting ``nodes`` (defaults to all nodes)."""
+
     return TARGET(nodes=nodes)
 
 
 def wait(steps: int = 1) -> WAIT:
+    """Return a WAIT token forcing ``steps`` structural updates before resuming."""
+
     return WAIT(steps=max(1, int(steps)))
 
 
 def basic_canonical_example() -> list[Token]:
-    """Reference canonical sequence.
+    """Return the canonical preset sequence.
 
     Returns a copy of the canonical preset tokens to keep CLI defaults aligned
-    with :func:`tnfr.presets.get_preset`.
+    with :func:`tnfr.config.presets.get_preset`.
     """
 
     return list(CANONICAL_PROGRAM_TOKENS)

tnfr/execution.pyi

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Callable, Iterable, Sequence
+from typing import Any, Optional
+
+from ._compat import TypeAlias
+from .tokens import TARGET, THOL, WAIT, OpTag, Token
+from .types import Glyph, NodeId, TNFRGraph
+
+__all__: list[str]
+
+def __getattr__(name: str) -> Any: ...
+
+AdvanceFn = Callable[[TNFRGraph], None]
+TraceEntry = dict[str, Any]
+ProgramTrace: TypeAlias = deque[TraceEntry]
+HandlerFn = Callable[
+    [TNFRGraph, Any, Sequence[NodeId] | None, ProgramTrace, AdvanceFn],
+    Sequence[NodeId] | None,
+]
+
+CANONICAL_PRESET_NAME: str
+CANONICAL_PROGRAM_TOKENS: tuple[Token, ...]
+HANDLERS: dict[OpTag, HandlerFn]
+
+def _apply_glyph_to_targets(
+    G: TNFRGraph, g: Glyph | str, nodes: Iterable[NodeId] | None = ...
+) -> None: ...
+def _record_trace(
+    trace: ProgramTrace, G: TNFRGraph, op: OpTag, **data: Any
+) -> None: ...
+def compile_sequence(
+    sequence: Iterable[Token] | Sequence[Token] | Any,
+    *,
+    max_materialize: int | None = ...,
+) -> list[tuple[OpTag, Any]]: ...
+def play(
+    G: TNFRGraph, sequence: Sequence[Token], step_fn: Optional[AdvanceFn] = ...
+) -> None: ...
+def seq(*tokens: Token) -> list[Token]: ...
+def block(*tokens: Token, repeat: int = ..., close: Glyph | None = ...) -> THOL: ...
+def target(nodes: Iterable[NodeId] | None = ...) -> TARGET: ...
+def wait(steps: int = ...) -> WAIT: ...
+def basic_canonical_example() -> list[Token]: ...

tnfr/extensions/__init__.py

@@ -0,0 +1,205 @@
+"""Extension registry for TNFR domain extensions.
+
+Manages registration, discovery, and access to community-contributed domain
+extensions. Maintains a global registry of extensions while ensuring thread-safe
+access and validation of extension requirements.
+"""
+
+from typing import Dict, List, Optional, Type
+from .base import TNFRExtension, PatternDefinition, CookbookRecipe
+
+
+class ExtensionRegistry:
+    """Registry for managing TNFR domain extensions.
+
+    Provides centralized registration and discovery of domain extensions,
+    ensuring extensions are properly validated and accessible to the TNFR
+    engine and user applications.
+
+    Examples
+    --------
+    >>> from tnfr.extensions import registry
+    >>> from tnfr.extensions.medical import MedicalExtension
+    >>>
+    >>> # Register extension
+    >>> ext = MedicalExtension()
+    >>> registry.register_extension(ext)
+    >>>
+    >>> # List available domains
+    >>> domains = registry.list_extensions()
+    >>> print(domains)  # ['medical', ...]
+    >>>
+    >>> # Get domain patterns
+    >>> patterns = registry.get_domain_patterns("medical")
+    """
+
+    def __init__(self) -> None:
+        """Initialize empty extension registry."""
+        self._extensions: Dict[str, TNFRExtension] = {}
+
+    def register_extension(self, extension: TNFRExtension) -> None:
+        """Register a new domain extension.
+
+        Parameters
+        ----------
+        extension : TNFRExtension
+            Extension instance to register.
+
+        Raises
+        ------
+        ValueError
+            If extension with same domain name already registered.
+        TypeError
+            If extension does not inherit from TNFRExtension.
+        """
+        if not isinstance(extension, TNFRExtension):
+            raise TypeError(
+                f"Extension must inherit from TNFRExtension, got {type(extension)}"
+            )
+
+        domain_name = extension.get_domain_name()
+
+        if domain_name in self._extensions:
+            raise ValueError(f"Extension for domain '{domain_name}' already registered")
+
+        self._extensions[domain_name] = extension
+
+    def unregister_extension(self, domain_name: str) -> None:
+        """Unregister an extension.
+
+        Parameters
+        ----------
+        domain_name : str
+            Domain name of extension to remove.
+
+        Raises
+        ------
+        KeyError
+            If domain not found in registry.
+        """
+        if domain_name not in self._extensions:
+            raise KeyError(f"Extension '{domain_name}' not found in registry")
+
+        del self._extensions[domain_name]
+
+    def get_extension(self, domain_name: str) -> Optional[TNFRExtension]:
+        """Get extension by domain name.
+
+        Parameters
+        ----------
+        domain_name : str
+            Domain name identifier.
+
+        Returns
+        -------
+        Optional[TNFRExtension]
+            Extension instance if found, None otherwise.
+        """
+        return self._extensions.get(domain_name)
+
+    def list_extensions(self) -> List[str]:
+        """List all registered extension domain names.
+
+        Returns
+        -------
+        List[str]
+            Sorted list of registered domain names.
+        """
+        return sorted(self._extensions.keys())
+
+    def get_domain_patterns(self, domain_name: str) -> Dict[str, PatternDefinition]:
+        """Get pattern definitions for a specific domain.
+
+        Parameters
+        ----------
+        domain_name : str
+            Domain name identifier.
+
+        Returns
+        -------
+        Dict[str, PatternDefinition]
+            Mapping of pattern names to definitions.
+
+        Raises
+        ------
+        KeyError
+            If domain not found in registry.
+        """
+        extension = self.get_extension(domain_name)
+        if extension is None:
+            raise KeyError(f"Extension '{domain_name}' not found in registry")
+
+        return extension.get_pattern_definitions()
+
+    def get_domain_health_analyzers(self, domain_name: str) -> Dict[str, Type]:
+        """Get health analyzers for a specific domain.
+
+        Parameters
+        ----------
+        domain_name : str
+            Domain name identifier.
+
+        Returns
+        -------
+        Dict[str, Type]
+            Mapping of analyzer names to analyzer classes.
+
+        Raises
+        ------
+        KeyError
+            If domain not found in registry.
+        """
+        extension = self.get_extension(domain_name)
+        if extension is None:
+            raise KeyError(f"Extension '{domain_name}' not found in registry")
+
+        return extension.get_health_analyzers()
+
+    def get_domain_recipes(self, domain_name: str) -> Dict[str, CookbookRecipe]:
+        """Get cookbook recipes for a specific domain.
+
+        Parameters
+        ----------
+        domain_name : str
+            Domain name identifier.
+
+        Returns
+        -------
+        Dict[str, CookbookRecipe]
+            Mapping of recipe names to recipe definitions.
+
+        Raises
+        ------
+        KeyError
+            If domain not found in registry.
+        """
+        extension = self.get_extension(domain_name)
+        if extension is None:
+            raise KeyError(f"Extension '{domain_name}' not found in registry")
+
+        return extension.get_cookbook_recipes()
+
+    def get_all_patterns(self) -> Dict[str, Dict[str, PatternDefinition]]:
+        """Get all patterns from all registered extensions.
+
+        Returns
+        -------
+        Dict[str, Dict[str, PatternDefinition]]
+            Nested mapping: domain_name -> pattern_name -> PatternDefinition.
+        """
+        all_patterns = {}
+        for domain_name, extension in self._extensions.items():
+            all_patterns[domain_name] = extension.get_pattern_definitions()
+
+        return all_patterns
+
+    def clear(self) -> None:
+        """Clear all registered extensions.
+
+        Primarily useful for testing and reinitialization.
+        """
+        self._extensions.clear()
+
+
+# Global registry instance
+registry = ExtensionRegistry()

tnfr/extensions/__init__.pyi

@@ -0,0 +1,18 @@
+"""Type stubs for tnfr.extensions"""
+
+from typing import Dict, List, Optional, Type
+from .base import TNFRExtension, PatternDefinition, CookbookRecipe
+
+class ExtensionRegistry:
+    def __init__(self) -> None: ...
+    def register_extension(self, extension: TNFRExtension) -> None: ...
+    def unregister_extension(self, domain_name: str) -> None: ...
+    def get_extension(self, domain_name: str) -> Optional[TNFRExtension]: ...
+    def list_extensions(self) -> List[str]: ...
+    def get_domain_patterns(self, domain_name: str) -> Dict[str, PatternDefinition]: ...
+    def get_domain_health_analyzers(self, domain_name: str) -> Dict[str, Type]: ...
+    def get_domain_recipes(self, domain_name: str) -> Dict[str, CookbookRecipe]: ...
+    def get_all_patterns(self) -> Dict[str, Dict[str, PatternDefinition]]: ...
+    def clear(self) -> None: ...
+
+registry: ExtensionRegistry

tnfr/extensions/base.py

@@ -0,0 +1,173 @@
+"""Base classes for TNFR domain extensions.
+
+This module provides the foundation for community-contributed domain extensions
+to TNFR Grammar 2.0. Extensions allow domain experts to add specialized patterns,
+health analyzers, and tools while maintaining canonical TNFR invariants.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Type
+
+
+@dataclass
+class PatternDefinition:
+    """Definition of a domain-specific structural pattern.
+
+    Captures a validated sequence of structural operators and its domain context,
+    ensuring patterns maintain TNFR canonical requirements while providing
+    domain-specific semantics.
+
+    Attributes
+    ----------
+    name : str
+        Unique identifier for the pattern within its domain.
+    sequence : List[str]
+        Ordered list of structural operator identifiers.
+    description : str
+        Human-readable explanation of what the pattern achieves.
+    use_cases : List[str]
+        Real-world scenarios where this pattern applies.
+    health_requirements : Dict[str, float]
+        Minimum health metrics (C(t), Si) required for pattern validity.
+    domain_context : Dict[str, Any]
+        Domain-specific metadata explaining real-world mapping.
+    examples : List[Dict[str, Any]]
+        Validated examples demonstrating pattern effectiveness.
+    """
+
+    name: str
+    sequence: List[str]
+    description: str
+    use_cases: List[str] = field(default_factory=list)
+    health_requirements: Dict[str, float] = field(default_factory=dict)
+    domain_context: Dict[str, Any] = field(default_factory=dict)
+    examples: List[Dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class CookbookRecipe:
+    """Validated recipe for a common domain scenario.
+
+    Provides a tested sequence configuration with parameters and expected outcomes,
+    allowing practitioners to apply proven patterns to their specific contexts.
+
+    Attributes
+    ----------
+    name : str
+        Unique identifier for the recipe.
+    description : str
+        What this recipe achieves in domain terms.
+    sequence : List[str]
+        Structural operator sequence.
+    parameters : Dict[str, Any]
+        Recommended parameters (νf, phase, etc.).
+    expected_health : Dict[str, float]
+        Expected health metrics (C(t), Si) for successful application.
+    validation : Dict[str, Any]
+        Validation metadata (test count, success rate, notes).
+    """
+
+    name: str
+    description: str
+    sequence: List[str]
+    parameters: Dict[str, Any] = field(default_factory=dict)
+    expected_health: Dict[str, float] = field(default_factory=dict)
+    validation: Dict[str, Any] = field(default_factory=dict)
+
+
+class TNFRExtension(ABC):
+    """Abstract base class for TNFR domain extensions.
+
+    Domain extensions provide specialized patterns, health analyzers, and tools
+    for specific application domains while maintaining TNFR canonical invariants.
+    All extensions must implement the core abstract methods to ensure consistent
+    structure and discoverability.
+
+    Examples
+    --------
+    >>> class MedicalExtension(TNFRExtension):
+    ...     def get_domain_name(self) -> str:
+    ...         return "medical"
+    ...
+    ...     def get_pattern_definitions(self) -> Dict[str, PatternDefinition]:
+    ...         return {
+    ...             "therapeutic_alliance": PatternDefinition(
+    ...                 name="therapeutic_alliance",
+    ...                 sequence=["emission", "reception", "coherence"],
+    ...                 description="Establishing therapeutic trust",
+    ...                 use_cases=["Initial therapy session", "Crisis intervention"],
+    ...             )
+    ...         }
+    ...
+    ...     def get_health_analyzers(self) -> Dict[str, Type]:
+    ...         from .health_analyzers import TherapeuticHealthAnalyzer
+    ...         return {"therapeutic": TherapeuticHealthAnalyzer}
+    """
+
+    @abstractmethod
+    def get_domain_name(self) -> str:
+        """Return the unique domain identifier.
+
+        Returns
+        -------
+        str
+            Domain name (lowercase, underscore-separated).
+        """
+        pass
+
+    @abstractmethod
+    def get_pattern_definitions(self) -> Dict[str, PatternDefinition]:
+        """Return domain-specific pattern definitions.
+
+        Returns
+        -------
+        Dict[str, PatternDefinition]
+            Mapping of pattern names to their definitions.
+        """
+        pass
+
+    @abstractmethod
+    def get_health_analyzers(self) -> Dict[str, Type]:
+        """Return domain-specific health analyzer classes.
+
+        Returns
+        -------
+        Dict[str, Type]
+            Mapping of analyzer names to analyzer classes.
+        """
+        pass
+
+    def get_cookbook_recipes(self) -> Dict[str, CookbookRecipe]:
+        """Return validated recipes for common scenarios.
+
+        Returns
+        -------
+        Dict[str, CookbookRecipe]
+            Mapping of recipe names to recipe definitions. Empty dict if none.
+        """
+        return {}
+
+    def get_visualization_tools(self) -> Dict[str, Type]:
+        """Return domain-specific visualization tools.
+
+        Returns
+        -------
+        Dict[str, Type]
+            Mapping of visualizer names to visualizer classes. Empty dict if none.
+        """
+        return {}
+
+    def get_metadata(self) -> Dict[str, Any]:
+        """Return extension metadata.
+
+        Returns
+        -------
+        Dict[str, Any]
+            Metadata including version, author, description, etc.
+        """
+        return {
+            "domain": self.get_domain_name(),
+            "version": "1.0.0",
+            "description": self.__doc__ or "No description provided",
+        }