affective-longing

affective-longing 🧠💫

Emotional extension for AI companions — beyond timing, into feeling.

Built on revive-companion (Poisson timing + Bayesian inference).

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    AffectiveLonging                         │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Memory     │  │ Relationship │  │   Emotion    │      │
│  │              │  │              │  │              │      │
│  │ ChromaDB     │  │ HMM          │  │ VAD Model    │      │
│  │ Embeddings   │  │ OU Process   │  │ Valence      │      │
│  │ Similarity   │  │ 6 Stages     │  │ Arousal      │      │
│  │              │  │              │  │ Dominance    │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
│         │                 │                 │               │
│         └─────────────────┼─────────────────┘               │
│                           ▼                                 │
│                    tick() → AffectiveResult                 │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              revive-companion (base)                  │  │
│  │  Poisson Process → InfoGain → Bayesian → Decision   │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Three Layers

1. Memory — Past triggers present

Store conversations as embeddings. When current context matches past memories, longing probability gets a boost.

engine.remember("你喜欢下雨天", tags=["weather"])
engine.remember("我们第一次看电影是《星际穿越》", tags=["movie"])

# Later...
result = engine.tick(context="今天下雨了")
# → Triggers "你喜欢下雨天" with similarity 0.988
# → Longing boost: +15%

Theory: Sentence embeddings (all-MiniLM-L6-v2) + cosine similarity. Memory decay via Ebbinghaus forgetting curve.

2. Relationship — 6-stage lifecycle

Models relationship dynamics through discrete state transitions (HMM) + continuous emotional drift (Ornstein-Uhlenbeck process).

追求 → 甜蜜 → 热恋 → 平稳
  ↑                    ↓
  └──── 修复 ← 冷战 ←──┘

engine.observe("affection")   # intimacy +0.10
engine.observe("fight")       # conflict +0.20, may → 冷战
engine.step_time(hours=24)    # OU decay toward baseline

Theory:

• HMM: Hidden states (relationship stages), observed events (user actions). Transition matrix modulated by intimacy/conflict levels.
• Ornstein-Uhlenbeck: Mean-reverting stochastic process. dX = θ(μ - X)dt + σdW. Models how intimacy/conflict drift toward baselines over time.

3. Emotion — VAD model

AI companion's internal emotional state modeled as 3D vector (Valence, Arousal, Dominance). Mapped to 11 discrete emotions.

state = engine.emotion.current_state
# EmotionalState(😊 joy, V=+0.65, A=0.58, D=0.55)

Theory: Russell's Circumplex Model (1980) + Mehrabian's PAD model (1996). OU process for time decay, event-driven bumps for state changes.

Install

# Base (Poisson + Bayesian from revive-companion)
pip install affective-longing

# With memory support (sentence-transformers + chromadb)
pip install affective-longing[memory]

Quick Start

from affective_longing import AffectiveLonging

engine = AffectiveLonging(seed=42)

# 1. Store memories
engine.remember("你喜欢下雨天", tags=["weather"])
engine.remember("你说过最喜欢吃草莓蛋糕", tags=["food"])

# 2. Observe events
engine.observe("reply_fast")
engine.observe("affection")

# 3. Let time pass
engine.step_time(hours=12)

# 4. Tick with context
result = engine.tick(context="今天下雨了")

print(f"Base probability:    {result.base_probability:.1%}")
print(f"Memory trigger:      {result.memory_trigger}")
print(f"Similarity:          {result.memory_similarity:.3f}")
print(f"Boosted probability: {result.boosted_probability:.1%}")
print(f"Relationship:        {result.relationship_stage.value}")
print(f"Emotion:             {result.emotional_state.emoji} {result.emotional_state.emotion.value}")

if result.should_send:
    send_message(result.prompt)
    engine.record_send()

API Reference

AffectiveLonging

engine = AffectiveLonging(
    memory_persist_dir="./companion_memory_db",  # Where to store embeddings
    relationship_seed=None,                       # For reproducibility
    emotion_seed=None,
    **kwargs                                      # Passed to PoissonLove
)

Methods:

AffectiveResult

@dataclass
class AffectiveResult:
    # Decision
    should_send: bool
    base_probability: float

    # Memory
    memory_trigger: str | None
    memory_similarity: float
    longing_boost: float
    boosted_probability: float

    # Relationship
    relationship_stage: Stage
    intimacy: float
    conflict: float

    # Emotion
    emotional_state: EmotionalState

    # Output
    prompt: str
    reason: str

Events

Examples

Run the quickstarts:

# Memory triggers
python examples/quickstart.py

# Relationship state machine
python examples/quickstart_relationship.py

# VAD emotion engine
python examples/quickstart_emotion.py

# Full integration
python examples/quickstart_integrated.py

Tests

pip install -e ".[memory,test]"
pytest tests/ -v

62 tests covering all modules.

Theoretical Foundations

License

MIT