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

tnfr/extensions/medical/health_analyzers.py

@@ -0,0 +1,181 @@
+"""Specialized health analyzers for medical domain."""
+
+from typing import Any, Dict, List
+import networkx as nx
+
+
+class TherapeuticHealthAnalyzer:
+    """Specialized health analyzer for therapeutic contexts.
+
+    Computes domain-specific health dimensions beyond standard coherence
+    and sense index metrics, focusing on therapeutic effectiveness and
+    patient safety.
+
+    Examples
+    --------
+    >>> analyzer = TherapeuticHealthAnalyzer()
+    >>> G = nx.Graph()
+    >>> # ... set up network ...
+    >>> metrics = analyzer.analyze_therapeutic_health(
+    ...     G, ["emission", "reception", "coherence"]
+    ... )
+    >>> print(metrics["healing_potential"])
+    0.78
+    """
+
+    def analyze_therapeutic_health(
+        self, G: nx.Graph, sequence: List[str], **kwargs: Any
+    ) -> Dict[str, float]:
+        """Compute therapeutic-specific health metrics.
+
+        Parameters
+        ----------
+        G : nx.Graph
+            Network graph representing therapeutic system.
+        sequence : List[str]
+            Operator sequence to analyze.
+        **kwargs : Any
+            Additional analysis parameters.
+
+        Returns
+        -------
+        Dict[str, float]
+            Domain-specific health metrics with values in [0, 1]:
+            - healing_potential: Capacity for positive change
+            - trauma_safety: Safety from re-traumatization
+            - therapeutic_alliance: Strength of working relationship
+        """
+        metrics = {}
+
+        # Compute therapeutic dimensions
+        metrics["healing_potential"] = self._calculate_healing_potential(G, sequence)
+        metrics["trauma_safety"] = self._calculate_trauma_safety(G, sequence)
+        metrics["therapeutic_alliance"] = self._calculate_alliance_strength(G, sequence)
+
+        return metrics
+
+    def _calculate_healing_potential(self, G: nx.Graph, sequence: List[str]) -> float:
+        """Calculate capacity for positive therapeutic change.
+
+        Parameters
+        ----------
+        G : nx.Graph
+            Network graph.
+        sequence : List[str]
+            Operator sequence.
+
+        Returns
+        -------
+        float
+            Healing potential score [0, 1].
+        """
+        # Check for growth-promoting operators
+        growth_ops = {"expansion", "self_organization", "coupling"}
+        growth_count = sum(1 for op in sequence if op in growth_ops)
+
+        # Check for stabilizing operators
+        stability_ops = {"coherence", "resonance"}
+        stability_count = sum(1 for op in sequence if op in stability_ops)
+
+        # Balance between growth and stability
+        if len(sequence) == 0:
+            return 0.0
+
+        growth_ratio = growth_count / len(sequence)
+        stability_ratio = stability_count / len(sequence)
+
+        # Optimal balance: some growth, some stability
+        balance_score = min(growth_ratio + stability_ratio, 1.0)
+
+        # Factor in network connectivity (more connections = more resources)
+        if len(G.nodes()) > 0:
+            avg_degree = sum(dict(G.degree()).values()) / len(G.nodes())
+            connectivity_score = min(avg_degree / 5.0, 1.0)
+        else:
+            connectivity_score = 0.0
+
+        # Combine factors
+        healing_potential = 0.6 * balance_score + 0.4 * connectivity_score
+
+        return min(healing_potential, 1.0)
+
+    def _calculate_trauma_safety(self, G: nx.Graph, sequence: List[str]) -> float:
+        """Calculate safety from re-traumatization.
+
+        Parameters
+        ----------
+        G : nx.Graph
+            Network graph.
+        sequence : List[str]
+            Operator sequence.
+
+        Returns
+        -------
+        float
+            Trauma safety score [0, 1].
+        """
+        # Check for potentially destabilizing operators
+        destabilizing_ops = {"dissonance", "mutation"}
+        destabilizing_count = sum(1 for op in sequence if op in destabilizing_ops)
+
+        # Check for safety-promoting operators
+        safety_ops = {"silence", "coherence", "reception"}
+        safety_count = sum(1 for op in sequence if op in safety_ops)
+
+        if len(sequence) == 0:
+            return 1.0  # No sequence = no risk
+
+        # Safety depends on having stabilizing ops when using destabilizing ones
+        if destabilizing_count > 0:
+            # Need at least as many safety ops as destabilizing ops
+            safety_ratio = min(safety_count / destabilizing_count, 1.0)
+            base_safety = 0.5 + 0.5 * safety_ratio
+        else:
+            # No destabilizing ops = inherently safer
+            base_safety = 0.8 + 0.2 * (safety_count / len(sequence))
+
+        return min(base_safety, 1.0)
+
+    def _calculate_alliance_strength(self, G: nx.Graph, sequence: List[str]) -> float:
+        """Calculate strength of therapeutic alliance.
+
+        Parameters
+        ----------
+        G : nx.Graph
+            Network graph.
+        sequence : List[str]
+            Operator sequence.
+
+        Returns
+        -------
+        float
+            Alliance strength score [0, 1].
+        """
+        # Alliance built through connection operators
+        connection_ops = {"emission", "reception", "coupling", "resonance"}
+        connection_count = sum(1 for op in sequence if op in connection_ops)
+
+        # Coherence strengthens alliance
+        coherence_count = sequence.count("coherence")
+
+        if len(sequence) == 0:
+            return 0.0
+
+        # More connection = stronger alliance
+        connection_ratio = connection_count / len(sequence)
+
+        # Coherence multiplier
+        coherence_bonus = min(coherence_count * 0.1, 0.3)
+
+        # Network density as proxy for mutual understanding
+        if len(G.nodes()) > 1:
+            density = nx.density(G)
+        else:
+            density = 0.0
+
+        # Combine factors
+        alliance_strength = (
+            0.5 * connection_ratio + 0.3 * density + 0.2
+        ) + coherence_bonus
+
+        return min(alliance_strength, 1.0)

tnfr/extensions/medical/health_analyzers.pyi

@@ -0,0 +1,9 @@
+"""Type stubs for tnfr.extensions.medical.health_analyzers"""
+
+from typing import Any, Dict, List
+import networkx as nx
+
+class TherapeuticHealthAnalyzer:
+    def analyze_therapeutic_health(
+        self, G: nx.Graph, sequence: List[str], **kwargs: Any
+    ) -> Dict[str, float]: ...

tnfr/extensions/medical/patterns.py

@@ -0,0 +1,163 @@
+"""Medical domain pattern definitions."""
+
+from ..base import PatternDefinition
+
+# Therapeutic Alliance Pattern
+THERAPEUTIC_ALLIANCE = PatternDefinition(
+    name="therapeutic_alliance",
+    sequence=["emission", "reception", "coherence", "resonance"],
+    description="Establishing therapeutic trust and rapport",
+    use_cases=[
+        "Initial therapy session - building connection",
+        "Re-establishing alliance after rupture",
+        "Deepening therapeutic relationship",
+    ],
+    health_requirements={
+        "min_coherence": 0.75,
+        "min_sense_index": 0.70,
+    },
+    domain_context={
+        "real_world_mapping": (
+            "Maps to Carl Rogers' therapeutic alliance concept: "
+            "emission (therapist presence), reception (active listening), "
+            "coherence (mutual understanding), resonance (empathic attunement)"
+        ),
+        "expected_outcomes": (
+            "Strong working alliance, patient feels heard and understood, "
+            "foundation for therapeutic work established"
+        ),
+        "failure_modes": (
+            "Premature coherence without genuine reception can feel inauthentic, "
+            "lack of resonance prevents deeper connection"
+        ),
+    },
+    examples=[
+        {
+            "name": "Initial Session - Trust Building",
+            "context": "First meeting with new patient, establishing safety",
+            "sequence": ["emission", "reception", "coherence", "resonance"],
+            "health_metrics": {"C_t": 0.82, "Si": 0.76},
+        },
+        {
+            "name": "Alliance Repair",
+            "context": "After misunderstanding, rebuilding connection",
+            "sequence": ["emission", "reception", "coherence", "resonance"],
+            "health_metrics": {"C_t": 0.79, "Si": 0.74},
+        },
+        {
+            "name": "Deepening Phase",
+            "context": "Moving from surface to deeper therapeutic work",
+            "sequence": ["emission", "reception", "coherence", "resonance"],
+            "health_metrics": {"C_t": 0.85, "Si": 0.81},
+        },
+    ],
+)
+
+# Crisis Intervention Pattern
+CRISIS_INTERVENTION = PatternDefinition(
+    name="crisis_intervention",
+    sequence=["dissonance", "silence", "coherence", "resonance"],
+    description="Stabilizing acute emotional distress",
+    use_cases=[
+        "Acute anxiety or panic attack",
+        "Emotional overwhelm during session",
+        "Crisis situation requiring immediate stabilization",
+    ],
+    health_requirements={
+        "min_coherence": 0.75,
+        "min_sense_index": 0.70,
+    },
+    domain_context={
+        "real_world_mapping": (
+            "Follows crisis intervention model: dissonance (acknowledge distress), "
+            "silence (create space/pause), coherence (stabilization techniques), "
+            "resonance (empathic grounding)"
+        ),
+        "expected_outcomes": (
+            "Reduced emotional intensity, restored sense of safety, "
+            "ability to engage in problem-solving"
+        ),
+        "failure_modes": (
+            "Skipping silence phase can escalate crisis, "
+            "insufficient coherence leaves patient dysregulated"
+        ),
+    },
+    examples=[
+        {
+            "name": "Panic Attack Intervention",
+            "context": "Patient experiencing acute panic in session",
+            "sequence": ["dissonance", "silence", "coherence", "resonance"],
+            "health_metrics": {"C_t": 0.78, "Si": 0.77},
+        },
+        {
+            "name": "Emotional Overwhelm",
+            "context": "Patient flooded with difficult emotions",
+            "sequence": ["dissonance", "silence", "coherence", "resonance"],
+            "health_metrics": {"C_t": 0.81, "Si": 0.79},
+        },
+        {
+            "name": "Acute Grief Response",
+            "context": "Managing intense grief reaction",
+            "sequence": ["dissonance", "silence", "coherence", "resonance"],
+            "health_metrics": {"C_t": 0.76, "Si": 0.75},
+        },
+    ],
+)
+
+# Integration Phase Pattern
+INTEGRATION_PHASE = PatternDefinition(
+    name="integration_phase",
+    sequence=["coupling", "self_organization", "expansion", "coherence"],
+    description="Integrating insights and new perspectives",
+    use_cases=[
+        "After breakthrough moment - consolidating learning",
+        "Connecting disparate experiences into coherent narrative",
+        "Expanding awareness to include new perspectives",
+    ],
+    health_requirements={
+        "min_coherence": 0.75,
+        "min_sense_index": 0.70,
+    },
+    domain_context={
+        "real_world_mapping": (
+            "Reflects integration process in therapy: coupling (connecting elements), "
+            "self_organization (natural meaning-making), expansion (broadening view), "
+            "coherence (consolidating new understanding)"
+        ),
+        "expected_outcomes": (
+            "Integrated self-narrative, expanded perspective, "
+            "sustainable new patterns of thinking/feeling"
+        ),
+        "failure_modes": (
+            "Premature expansion without coupling can be destabilizing, "
+            "lack of final coherence leaves insights fragmented"
+        ),
+    },
+    examples=[
+        {
+            "name": "Post-Breakthrough Integration",
+            "context": "After major insight, integrating into broader understanding",
+            "sequence": ["coupling", "self_organization", "expansion", "coherence"],
+            "health_metrics": {"C_t": 0.84, "Si": 0.80},
+        },
+        {
+            "name": "Narrative Coherence",
+            "context": "Building coherent life story from fragmented experiences",
+            "sequence": ["coupling", "self_organization", "expansion", "coherence"],
+            "health_metrics": {"C_t": 0.83, "Si": 0.78},
+        },
+        {
+            "name": "Perspective Expansion",
+            "context": "Including previously rejected aspects of self",
+            "sequence": ["coupling", "self_organization", "expansion", "coherence"],
+            "health_metrics": {"C_t": 0.86, "Si": 0.82},
+        },
+    ],
+)
+
+# Collect all patterns
+PATTERNS = {
+    "therapeutic_alliance": THERAPEUTIC_ALLIANCE,
+    "crisis_intervention": CRISIS_INTERVENTION,
+    "integration_phase": INTEGRATION_PHASE,
+}

tnfr/extensions/medical/patterns.pyi

@@ -0,0 +1,8 @@
+"""Type stubs for tnfr.extensions.medical.patterns"""
+
+from ..base import PatternDefinition
+
+THERAPEUTIC_ALLIANCE: PatternDefinition
+CRISIS_INTERVENTION: PatternDefinition
+INTEGRATION_PHASE: PatternDefinition
+PATTERNS: dict[str, PatternDefinition]

tnfr/flatten.py

@@ -0,0 +1,262 @@
+"""Flattening utilities to compile TNFR token sequences."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, Callable, cast
+
+from .config.constants import GLYPHS_CANONICAL_SET
+from .tokens import TARGET, THOL, THOL_SENTINEL, WAIT, OpTag, Token
+from .types import Glyph
+from .utils import MAX_MATERIALIZE_DEFAULT, ensure_collection, flatten_structure
+
+__all__ = [
+    "THOLEvaluator",
+    "parse_program_tokens",
+]
+
+
+@dataclass
+class TholFrame:
+    """Execution frame used to evaluate nested THOL blocks."""
+
+    seq: Sequence[Token]
+    index: int
+    remaining: int
+    closing: Glyph | None
+
+
+def _iter_source(
+    seq: Iterable[Token] | Sequence[Token] | Any,
+    *,
+    max_materialize: int | None,
+) -> Iterable[Any]:
+    """Yield items from ``seq`` enforcing ``max_materialize`` when needed."""
+
+    _, view = ensure_collection(
+        cast(Iterable[Token], seq),
+        max_materialize=max_materialize,
+        return_view=True,
+    )
+    return view
+
+
+def _push_thol_frame(
+    frames: list[TholFrame],
+    item: THOL,
+    *,
+    max_materialize: int | None,
+) -> None:
+    """Validate ``item`` and append a frame for its evaluation."""
+
+    repeats = int(item.repeat)
+    if repeats < 1:
+        raise ValueError("repeat must be ≥1")
+    if item.force_close is not None and not isinstance(item.force_close, Glyph):
+        raise ValueError("force_close must be a Glyph")
+    # TNFR invariant: THOL blocks must close to maintain operator closure (§3.4)
+    # Only SHA (silence) and NUL (contraction) are valid THOL closures
+    # Default to NUL (contraction) when no valid closure specified
+    closing = (
+        item.force_close
+        if isinstance(item.force_close, Glyph)
+        and item.force_close in {Glyph.SHA, Glyph.NUL}
+        else (Glyph.NUL if item.force_close is None else None)
+    )
+    seq0 = ensure_collection(
+        item.body,
+        max_materialize=max_materialize,
+        error_msg=f"THOL body exceeds max_materialize={max_materialize}",
+    )
+    frames.append(
+        TholFrame(
+            seq=seq0,
+            index=0,
+            remaining=repeats,
+            closing=closing,
+        )
+    )
+
+
+class THOLEvaluator:
+    """Generator that expands a :class:`THOL` block lazily."""
+
+    def __init__(
+        self,
+        item: THOL,
+        *,
+        max_materialize: int | None = MAX_MATERIALIZE_DEFAULT,
+    ) -> None:
+        self._frames: list[TholFrame] = []
+        _push_thol_frame(self._frames, item, max_materialize=max_materialize)
+        self._max_materialize = max_materialize
+        self._started = False
+
+    def __iter__(self) -> "THOLEvaluator":
+        """Return the evaluator itself to stream THOL expansion."""
+
+        return self
+
+    def __next__(self) -> Token | object:
+        """Yield the next token or :data:`THOL_SENTINEL` during evaluation."""
+
+        if not self._started:
+            self._started = True
+            return THOL_SENTINEL
+        while self._frames:
+            frame = self._frames[-1]
+            seq = frame.seq
+            idx = frame.index
+            if idx < len(seq):
+                token = seq[idx]
+                frame.index = idx + 1
+                if isinstance(token, THOL):
+                    _push_thol_frame(
+                        self._frames,
+                        token,
+                        max_materialize=self._max_materialize,
+                    )
+                    return THOL_SENTINEL
+                return token
+            else:
+                cl = frame.closing
+                frame.remaining -= 1
+                if frame.remaining > 0:
+                    frame.index = 0
+                else:
+                    self._frames.pop()
+                if cl is not None:
+                    return cl
+        raise StopIteration
+
+
+def _flatten_target(
+    item: TARGET,
+    ops: list[tuple[OpTag, Any]],
+) -> None:
+    ops.append((OpTag.TARGET, item))
+
+
+def _flatten_wait(
+    item: WAIT,
+    ops: list[tuple[OpTag, Any]],
+) -> None:
+    steps = max(1, int(getattr(item, "steps", 1)))
+    ops.append((OpTag.WAIT, steps))
+
+
+def _flatten_glyph(
+    item: Glyph | str,
+    ops: list[tuple[OpTag, Any]],
+) -> None:
+    g = item.value if isinstance(item, Glyph) else str(item)
+    if g not in GLYPHS_CANONICAL_SET:
+        raise ValueError(f"Non-canonical glyph: {g}")
+    ops.append((OpTag.GLYPH, g))
+
+
+_TOKEN_DISPATCH: dict[type, Callable[[Any, list[tuple[OpTag, Any]]], None]] = {
+    TARGET: _flatten_target,
+    WAIT: _flatten_wait,
+    Glyph: _flatten_glyph,
+    str: _flatten_glyph,
+}
+
+
+def _coerce_mapping_token(
+    mapping: Mapping[str, Any],
+    *,
+    max_materialize: int | None,
+) -> Token:
+    if len(mapping) != 1:
+        raise ValueError(f"Invalid token mapping: {mapping!r}")
+    key, value = next(iter(mapping.items()))
+    if key == "WAIT":
+        # Handle both formats: {"WAIT": 1} and {"WAIT": {"steps": 1}}
+        if isinstance(value, Mapping):
+            steps = value.get("steps", 1)
+        else:
+            steps = value
+        return WAIT(int(steps))
+    if key == "TARGET":
+        return TARGET(value)
+    if key != "THOL":
+        raise ValueError(f"Unrecognized token: {key!r}")
+    if not isinstance(value, Mapping):
+        raise TypeError("THOL specification must be a mapping")
+
+    close = value.get("close")
+    if isinstance(close, str):
+        close_enum = Glyph.__members__.get(close)
+        if close_enum is None:
+            raise ValueError(f"Unknown closing glyph: {close!r}")
+        close = close_enum
+    elif close is not None and not isinstance(close, Glyph):
+        raise TypeError("THOL close glyph must be a Glyph or string name")
+
+    body = parse_program_tokens(value.get("body", []), max_materialize=max_materialize)
+    repeat = int(value.get("repeat", 1))
+    return THOL(body=body, repeat=repeat, force_close=close)
+
+
+def parse_program_tokens(
+    obj: Iterable[Any] | Sequence[Any] | Any,
+    *,
+    max_materialize: int | None = MAX_MATERIALIZE_DEFAULT,
+) -> list[Token]:
+    """Materialize ``obj`` into a list of canonical tokens.
+
+    The function accepts the same iterables handled by :func:`_flatten`,
+    including dictionaries describing ``WAIT``, ``TARGET`` and ``THOL`` tokens.
+    Nested iterables are flattened following :func:`flatten_structure` rules.
+    """
+
+    sequence = _iter_source(obj, max_materialize=max_materialize)
+
+    def _expand(item: Any) -> Iterable[Any] | None:
+        if isinstance(item, Mapping):
+            return (_coerce_mapping_token(item, max_materialize=max_materialize),)
+        return None
+
+    tokens: list[Token] = []
+    for item in flatten_structure(sequence, expand=_expand):
+        if isinstance(item, (Glyph, WAIT, TARGET, THOL, str)):
+            tokens.append(item)
+            continue
+        raise TypeError(f"Unsupported token: {item!r}")
+    return tokens
+
+
+def _flatten(
+    seq: Iterable[Token] | Sequence[Token] | Any,
+    *,
+    max_materialize: int | None = MAX_MATERIALIZE_DEFAULT,
+) -> list[tuple[OpTag, Any]]:
+    """Return a list of operations ``(op, payload)`` where ``op`` ∈ :class:`OpTag`."""
+
+    ops: list[tuple[OpTag, Any]] = []
+    sequence = _iter_source(seq, max_materialize=max_materialize)
+
+    def _expand(item: Any) -> Iterable[Any] | None:
+        if isinstance(item, THOL):
+            return THOLEvaluator(item, max_materialize=max_materialize)
+        if isinstance(item, Mapping):
+            token = _coerce_mapping_token(item, max_materialize=max_materialize)
+            return (token,)
+        return None
+
+    for item in flatten_structure(sequence, expand=_expand):
+        if item is THOL_SENTINEL:
+            ops.append((OpTag.THOL, Glyph.THOL.value))
+            continue
+        handler = _TOKEN_DISPATCH.get(type(item))
+        if handler is None:
+            for cls, candidate in _TOKEN_DISPATCH.items():
+                if isinstance(item, cls):
+                    handler = candidate
+                    break
+        if handler is None:
+            raise TypeError(f"Unsupported token: {item!r}")
+        handler(item, ops)
+    return ops

tnfr/flatten.pyi

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, Sequence
+from typing import Any
+
+from .tokens import THOL, Token
+
+__all__: list[str]
+
+def __getattr__(name: str) -> Any: ...
+
+class THOLEvaluator(Iterator[Token | object]):
+    def __init__(self, item: THOL, *, max_materialize: int | None = ...) -> None: ...
+    def __iter__(self) -> THOLEvaluator: ...
+    def __next__(self) -> Token | object: ...
+
+def parse_program_tokens(
+    obj: Iterable[Any] | Sequence[Any] | Any,
+    *,
+    max_materialize: int | None = ...,
+) -> list[Token]: ...