affective-longing 0.1.0__py3-none-any.whl

affective_longing/__init__.py

@@ -0,0 +1,47 @@
+"""
+affective-longing: Emotional extension for AI companions.
+
+Built on revive-companion, adds:
+- Memory triggers (embedding similarity)
+- Relationship state machine (HMM + OU process)
+- AI self-emotion modeling (VAD model)
+
+Three layers, one decision:
+1. Memory — past memories trigger present longing
+2. Relationship — 6-stage lifecycle with OU decay
+3. Emotion — VAD model for AI's internal state
+"""
+
+from .emotion import Emotion, EmotionEngine, EmotionEngineConfig, EmotionalState
+from .engine import AffectiveLonging, AffectiveResult
+from .memory import MemoryStore, TriggerEngine
+from .relationship import (
+    Event,
+    OUProcess,
+    RelationshipStateMachine,
+    RelationshipState,
+    Stage,
+    TransitionConfig,
+)
+
+__all__ = [
+    # Core engine
+    "AffectiveLonging",
+    "AffectiveResult",
+    # Memory
+    "MemoryStore",
+    "TriggerEngine",
+    # Relationship
+    "Stage",
+    "RelationshipState",
+    "Event",
+    "RelationshipStateMachine",
+    "TransitionConfig",
+    "OUProcess",
+    # Emotion
+    "Emotion",
+    "EmotionalState",
+    "EmotionEngine",
+    "EmotionEngineConfig",
+]
+__version__ = "0.1.0"

affective_longing/emotion/__init__.py

@@ -0,0 +1,18 @@
+"""
+Emotion module — VAD model for AI companion's internal state.
+
+Components:
+- Emotion: Discrete emotion labels (joy, sadness, anger, etc.)
+- EmotionalState: VAD snapshot with emotion label
+- EmotionEngine: Manages emotional state with OU decay + events
+"""
+
+from .engine import EmotionEngine, EmotionEngineConfig
+from .vad import Emotion, EmotionalState
+
+__all__ = [
+    "Emotion",
+    "EmotionalState",
+    "EmotionEngine",
+    "EmotionEngineConfig",
+]

affective_longing/emotion/engine.py

@@ -0,0 +1,235 @@
+"""
+Emotion engine — manages the AI companion's emotional state.
+
+Combines:
+1. OU processes (one per VAD dimension) for time decay
+2. Event-driven bumps (user actions affect emotions)
+3. Relationship state influence (cold war → low valence)
+
+Design:
+- Each VAD dimension has its own OU process
+- Events bump specific dimensions
+- Relationship state modulates baselines (e.g., COLD → lower valence baseline)
+- Emotions decay toward dynamic baselines over time
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+
+from ..relationship.ou_process import OUProcess
+from ..relationship.stages import Stage
+from .vad import Emotion, EmotionalState
+
+logger = logging.getLogger(__name__)
+
+
+# Event → (valence_bump, arousal_bump, dominance_bump)
+EVENT_BUMPS: dict[str, tuple[float, float, float]] = {
+    # Positive events
+    "reply_fast": (0.08, 0.05, 0.03),
+    "affection": (0.12, 0.08, 0.02),
+    "initiate": (0.10, 0.06, 0.05),
+    "long_message": (0.06, 0.04, 0.01),
+
+    # Negative events
+    "no_reply": (-0.06, 0.08, -0.05),
+    "reply_slow": (-0.03, 0.02, -0.02),
+    "long_silence": (-0.10, 0.10, -0.08),
+    "reject": (-0.12, 0.10, -0.10),
+    "fight": (-0.15, 0.15, -0.05),
+
+    # Recovery
+    "apology": (0.05, -0.05, 0.03),
+}
+
+# Relationship stage → baseline adjustments (V, A, D)
+STAGE_BASELINES: dict[Stage, tuple[float, float, float]] = {
+    Stage.COURTING: (0.2, 0.6, 0.3),    # Slightly positive, anxious, uncertain
+    Stage.SWEET: (0.7, 0.5, 0.5),       # Happy, moderate arousal, balanced
+    Stage.PASSIONATE: (0.8, 0.7, 0.6),  # Very happy, excited, confident
+    Stage.STABLE: (0.5, 0.3, 0.5),      # Content, calm, balanced
+    Stage.COLD: (-0.5, 0.5, 0.3),       # Unhappy, tense, low control
+    Stage.REPAIRING: (0.0, 0.5, 0.4),   # Neutral, attentive, cautious
+}
+
+
+@dataclass
+class EmotionEngineConfig:
+    """Configuration for emotion engine."""
+
+    # Default baselines (overridden by relationship stage)
+    valence_baseline: float = 0.3
+    arousal_baseline: float = 0.4
+    dominance_baseline: float = 0.5
+
+    # OU parameters
+    valence_reversion: float = 0.06   # Slow decay (emotions are sticky)
+    arousal_reversion: float = 0.10   # Faster decay (excitement fades)
+    dominance_reversion: float = 0.08
+
+    valence_volatility: float = 0.02
+    arousal_volatility: float = 0.03
+    dominance_volatility: float = 0.02
+
+
+class EmotionEngine:
+    """
+    Manages the AI companion's emotional state.
+
+    Example:
+        >>> engine = EmotionEngine(seed=42)
+        >>> engine.current_state
+        EmotionalState(😐 neutral, V=+0.30, A=0.40, D=0.50)
+
+        >>> engine.observe("affection")
+        >>> engine.current_state
+        EmotionalState(😊 joy, V=+0.42, A=0.48, D=0.52)
+
+        >>> engine.update_relationship_stage(Stage.COLD)
+        >>> engine.step_time(24)
+        >>> engine.current_state
+        EmotionalState(😢 sadness, V=-0.20, ...)
+    """
+
+    def __init__(
+        self,
+        config: EmotionEngineConfig | None = None,
+        seed: int | None = None,
+    ):
+        self.config = config or EmotionEngineConfig()
+
+        # OU processes for each dimension
+        self._valence = OUProcess(
+            baseline=self.config.valence_baseline,
+            reversion_speed=self.config.valence_reversion,
+            volatility=self.config.valence_volatility,
+            seed=seed,
+        )
+        self._arousal = OUProcess(
+            baseline=self.config.arousal_baseline,
+            reversion_speed=self.config.arousal_reversion,
+            volatility=self.config.arousal_volatility,
+            seed=(seed + 1) if seed is not None else None,
+        )
+        self._dominance = OUProcess(
+            baseline=self.config.dominance_baseline,
+            reversion_speed=self.config.dominance_reversion,
+            volatility=self.config.dominance_volatility,
+            seed=(seed + 2) if seed is not None else None,
+        )
+
+        # Valence is [-1, 1], not [0, 1], so we need special handling
+        self._valence.value = self.config.valence_baseline
+
+        self._current_stage: Stage | None = None
+
+        logger.info(
+            "EmotionEngine initialized: %s",
+            self.current_state,
+        )
+
+    @property
+    def current_state(self) -> EmotionalState:
+        """Current emotional snapshot."""
+        return EmotionalState(
+            valence=self._valence.value,
+            arousal=self._arousal.value,
+            dominance=self._dominance.value,
+        )
+
+    @property
+    def valence(self) -> float:
+        return self._valence.value
+
+    @property
+    def arousal(self) -> float:
+        return self._arousal.value
+
+    @property
+    def dominance(self) -> float:
+        return self._dominance.value
+
+    def observe(self, event: str) -> EmotionalState:
+        """
+        React to an event.
+
+        Args:
+            event: Event name (e.g., "reply_fast", "fight", "affection")
+
+        Returns:
+            New emotional state.
+        """
+        bumps = EVENT_BUMPS.get(event, (0.0, 0.0, 0.0))
+        v_bump, a_bump, d_bump = bumps
+
+        self._valence.bump(v_bump)
+        self._arousal.bump(a_bump)
+        self._dominance.bump(d_bump)
+
+        logger.debug(
+            "Emotion event=%s: bumps=(V%+.2f, A%+.2f, D%+.2f) → %s",
+            event,
+            v_bump,
+            a_bump,
+            d_bump,
+            self.current_state,
+        )
+
+        return self.current_state
+
+    def update_relationship_stage(self, stage: Stage) -> None:
+        """
+        Update emotional baselines based on relationship stage.
+
+        Call this when the relationship state machine transitions.
+        """
+        if stage == self._current_stage:
+            return
+
+        self._current_stage = stage
+        v_base, a_base, d_base = STAGE_BASELINES.get(
+            stage,
+            (self.config.valence_baseline,
+             self.config.arousal_baseline,
+             self.config.dominance_baseline),
+        )
+
+        self._valence.baseline = v_base
+        self._arousal.baseline = a_base
+        self._dominance.baseline = d_base
+
+        logger.info(
+            "Emotion baselines updated for stage=%s: (V=%.2f, A=%.2f, D=%.2f)",
+            stage.value,
+            v_base,
+            a_base,
+            d_base,
+        )
+
+    def step_time(self, dt: float = 1.0) -> EmotionalState:
+        """
+        Advance time — emotions decay toward baselines.
+
+        Args:
+            dt: Time step in hours.
+
+        Returns:
+            New emotional state.
+        """
+        self._valence.step(dt)
+        self._arousal.step(dt)
+        self._dominance.step(dt)
+
+        return self.current_state
+
+    def reset(self) -> None:
+        """Reset to default emotional state."""
+        self._valence.reset()
+        self._arousal.reset()
+        self._dominance.reset()
+        self._current_stage = None
+
+    def __repr__(self) -> str:
+        return f"EmotionEngine({self.current_state})"

affective_longing/emotion/vad.py

@@ -0,0 +1,116 @@
+"""
+VAD emotion model — Valence, Arousal, Dominance.
+
+Based on Russell's circumplex model of affect (1980) and
+Mehrabian's PAD (Pleasure-Arousal-Dominance) model (1996).
+
+Used in:
+- Sentiment analysis
+- Emotion recognition
+- Affective computing
+- Human-robot interaction
+
+Our use: Model the AI companion's "internal emotional state"
+as it interacts with the user over time.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Emotion(Enum):
+    """
+    Discrete emotion labels mapped from VAD space.
+
+    Based on Plutchik's wheel (1980) + modern affective computing.
+    """
+
+    JOY = "joy"                 # V+, A+, D+
+    TRUST = "trust"             # V+, A~, D~
+    CONTENTMENT = "contentment" # V+, A-, D~
+    EXCITEMENT = "excitement"   # V+, A+, D~
+    LOVE = "love"               # V++, A+, D~
+    ANTICIPATION = "anticipation" # V~, A+, D~
+    ANXIETY = "anxiety"         # V-, A+, D-
+    SADNESS = "sadness"         # V-, A-, D-
+    ANGER = "anger"             # V-, A+, D+
+    FEAR = "fear"               # V--, A++, D--
+    NEUTRAL = "neutral"         # V~, A~, D~
+
+    @staticmethod
+    def from_vad(valence: float, arousal: float, dominance: float) -> Emotion:
+        """Map continuous VAD to discrete emotion."""
+        # Thresholds
+        HIGH_V = 0.5
+        LOW_V = -0.5
+        HIGH_A = 0.6
+        LOW_A = 0.4
+        HIGH_D = 0.6
+        LOW_D = 0.4
+
+        if valence > HIGH_V:
+            if arousal > HIGH_A:
+                if dominance > HIGH_D:
+                    return Emotion.JOY
+                return Emotion.EXCITEMENT
+            elif arousal < LOW_A:
+                return Emotion.CONTENTMENT
+            else:
+                return Emotion.TRUST
+        elif valence < LOW_V:
+            if arousal > HIGH_A:
+                if dominance > HIGH_D:
+                    return Emotion.ANGER
+                elif dominance < LOW_D:
+                    return Emotion.FEAR
+                return Emotion.ANXIETY
+            elif arousal < LOW_A:
+                return Emotion.SADNESS
+            else:
+                return Emotion.ANXIETY
+        else:
+            # valence near zero
+            if arousal > HIGH_A:
+                return Emotion.ANTICIPATION
+            return Emotion.NEUTRAL
+
+
+@dataclass
+class EmotionalState:
+    """Full emotional snapshot."""
+
+    valence: float      # -1 (negative) to +1 (positive)
+    arousal: float      # 0 (calm) to 1 (excited)
+    dominance: float    # 0 (submissive) to 1 (dominant)
+
+    @property
+    def emotion(self) -> Emotion:
+        """Discrete emotion label."""
+        return Emotion.from_vad(self.valence, self.arousal, self.dominance)
+
+    @property
+    def emoji(self) -> str:
+        return {
+            Emotion.JOY: "😊",
+            Emotion.TRUST: "🤝",
+            Emotion.CONTENTMENT: "😌",
+            Emotion.EXCITEMENT: "🤩",
+            Emotion.LOVE: "❤️",
+            Emotion.ANTICIPATION: "🤔",
+            Emotion.ANXIETY: "😰",
+            Emotion.SADNESS: "😢",
+            Emotion.ANGER: "😠",
+            Emotion.FEAR: "😨",
+            Emotion.NEUTRAL: "😐",
+        }[self.emotion]
+
+    def __repr__(self) -> str:
+        return (
+            f"EmotionalState("
+            f"{self.emoji} {self.emotion.value}, "
+            f"V={self.valence:+.2f}, "
+            f"A={self.arousal:.2f}, "
+            f"D={self.dominance:.2f})"
+        )

affective_longing/engine.py

@@ -0,0 +1,288 @@
+"""
+AffectiveLonging — unified emotional extension engine.
+
+Integrates three modules:
+1. Memory triggers (embedding similarity → longing boost)
+2. Relationship state machine (HMM + OU → stage transitions)
+3. AI self-emotion (VAD model → emotional state)
+
+Usage:
+    engine = AffectiveLonging()
+
+    # Store memories
+    engine.remember("你喜欢下雨天", tags=["weather"])
+
+    # Main loop
+    result = engine.tick(context="今天下雨了")
+    if result.should_send:
+        send(result.prompt)
+
+    # Observe events
+    engine.observe("reply_fast")
+
+    # Time passes
+    engine.step_time(hours=12)
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from revive_my_lover import PoissonLove
+
+from .emotion import EmotionEngine, EmotionalState
+from .memory import MemoryStore, TriggerEngine
+from .relationship import Event, RelationshipStateMachine, RelationshipState, Stage
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AffectiveResult:
+    """Full result of an AffectiveLonging tick."""
+
+    # Base decision
+    should_send: bool
+    base_probability: float
+
+    # Memory trigger
+    memory_trigger: str | None = None
+    memory_similarity: float = 0.0
+    longing_boost: float = 0.0
+    boosted_probability: float = 0.0
+
+    # Relationship
+    relationship_stage: Stage = Stage.COURTING
+    intimacy: float = 0.5
+    conflict: float = 0.1
+
+    # Emotion
+    emotional_state: EmotionalState | None = None
+
+    # Prompt
+    prompt: str = ""
+    reason: str = ""
+
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class AffectiveLonging:
+    """
+    Unified emotional engagement engine.
+
+    Combines three layers:
+    1. Memory — past memories trigger present longing
+    2. Relationship — 6-stage lifecycle with OU decay
+    3. Emotion — VAD model for AI's internal state
+
+    Args:
+        memory_persist_dir: Where to store memory embeddings.
+        relationship_seed: Seed for relationship state machine.
+        emotion_seed: Seed for emotion engine.
+        **kwargs: Passed to PoissonLove (config, seed, etc.)
+
+    Example:
+        >>> engine = AffectiveLonging()
+        >>> engine.remember("你喜欢下雨天")
+        >>> engine.observe("reply_fast")
+        >>> result = engine.tick(context="今天下雨了")
+        >>> result.emotional_state
+        EmotionalState(😊 joy, V=+0.45, A=0.52, D=0.55)
+    """
+
+    def __init__(
+        self,
+        memory_persist_dir: str = "./companion_memory_db",
+        relationship_seed: int | None = None,
+        emotion_seed: int | None = None,
+        **kwargs,
+    ):
+        # Base engine (revive-companion)
+        self._base = PoissonLove(**kwargs)
+
+        # Memory layer
+        self.memory = MemoryStore(persist_dir=memory_persist_dir)
+        self.trigger = TriggerEngine(self.memory)
+
+        # Relationship layer
+        self.relationship = RelationshipStateMachine(seed=relationship_seed)
+
+        # Emotion layer
+        self.emotion = EmotionEngine(seed=emotion_seed)
+
+        logger.info("AffectiveLonging initialized with 3 layers")
+
+    # ── Memory API ──
+
+    def remember(
+        self, text: str, tags: list[str] | None = None, **metadata
+    ) -> str:
+        """
+        Store a memory for future triggering.
+
+        Args:
+            text: The memory content (e.g., "你喜欢下雨天").
+            tags: Optional tags for filtering.
+            **metadata: Additional metadata.
+
+        Returns:
+            Memory ID.
+        """
+        meta = dict(metadata)
+        if tags:
+            meta["tags"] = ",".join(tags)
+        return self.memory.add(text, metadata=meta)
+
+    # ── Event API ──
+
+    def observe(self, event: str) -> None:
+        """
+        Observe an event and update relationship + emotion.
+
+        Maps string event names to:
+        - Relationship Event enum
+        - Emotion engine bumps
+
+        Args:
+            event: One of: reply_fast, reply_slow, no_reply, long_silence,
+                   affection, fight, apology, initiate, reject, long_message
+        """
+        # Update relationship state
+        try:
+            rel_event = Event(event)
+            self.relationship.observe(rel_event)
+        except ValueError:
+            logger.warning("Unknown relationship event: %s", event)
+
+        # Update emotion engine
+        self.emotion.observe(event)
+
+        # Sync emotion baselines with relationship stage
+        self.emotion.update_relationship_stage(self.relationship.stage)
+
+        logger.debug(
+            "Observed event=%s, stage=%s, emotion=%s",
+            event,
+            self.relationship.stage.value,
+            self.emotion.current_state.emotion.value,
+        )
+
+    def step_time(self, hours: float = 1.0) -> None:
+        """
+        Let time pass — decays relationship intimacy/conflict and emotion.
+
+        Args:
+            hours: Hours to advance.
+        """
+        self.relationship.step_time(hours)
+        self.emotion.step_time(hours)
+
+        # Keep emotion baselines in sync
+        self.emotion.update_relationship_stage(self.relationship.stage)
+
+    # ── Tick API ──
+
+    def tick(
+        self,
+        now: datetime | None = None,
+        context: str = "",
+    ) -> AffectiveResult:
+        """
+        Run one tick of the full pipeline.
+
+        Flow:
+        1. Base Poisson tick (timing decision)
+        2. Memory trigger (if context provided)
+        3. Package result with relationship + emotion state
+
+        Args:
+            now: Current time.
+            context: Situation text for memory matching.
+
+        Returns:
+            AffectiveResult with all layers' state.
+        """
+        # 1. Base engine
+        base_result = self._base.tick(now=now)
+
+        # 2. Memory trigger
+        trigger_text = None
+        trigger_sim = 0.0
+        boost = 0.0
+        boosted_prob = base_result.probability
+
+        if context and self.memory.count() > 0:
+            trigger_info = self.trigger.compute_trigger_score(context)
+            if trigger_info["memories"]:
+                trigger_text = trigger_info["memories"][0]["text"]
+                trigger_sim = trigger_info["max_similarity"]
+                boost = trigger_info["trigger_score"]
+                boosted_prob = self.trigger.boost_longing(
+                    base_result.probability, context
+                )
+
+        # 3. Build result
+        rel_state = self.relationship.current_state
+        emo_state = self.emotion.current_state
+
+        return AffectiveResult(
+            should_send=base_result.should_send,
+            base_probability=base_result.probability,
+            memory_trigger=trigger_text,
+            memory_similarity=trigger_sim,
+            longing_boost=boost,
+            boosted_probability=boosted_prob,
+            relationship_stage=rel_state.stage,
+            intimacy=rel_state.intimacy,
+            conflict=rel_state.conflict,
+            emotional_state=emo_state,
+            prompt=base_result.prompt,
+            reason=base_result.reason,
+        )
+
+    # ── Pass-through API ──
+
+    def record_reply(self, **kwargs) -> None:
+        """Record user reply — passes to base engine."""
+        self._base.record_reply(**kwargs)
+
+    def record_send(self, **kwargs) -> None:
+        """Record that we sent — passes to base engine."""
+        self._base.record_send(**kwargs)
+
+    # ── State API ──
+
+    def get_state(self) -> dict:
+        """Get full system state snapshot."""
+        rel = self.relationship.current_state
+        emo = self.emotion.current_state
+        return {
+            "relationship": {
+                "stage": rel.stage.value,
+                "stage_display": rel.stage.display_name,
+                "intimacy": rel.intimacy,
+                "conflict": rel.conflict,
+                "confidence": rel.confidence,
+            },
+            "emotion": {
+                "emotion": emo.emotion.value,
+                "emoji": emo.emoji,
+                "valence": emo.valence,
+                "arousal": emo.arousal,
+                "dominance": emo.dominance,
+            },
+            "memory_count": self.memory.count(),
+        }
+
+    def __repr__(self) -> str:
+        rel = self.relationship.current_state
+        emo = self.emotion.current_state
+        return (
+            f"AffectiveLonging("
+            f"stage={rel.stage.display_name}, "
+            f"{emo.emoji} {emo.emotion.value}, "
+            f"memories={self.memory.count()})"
+        )