chip-brain 1.0.0__py3-none-any.whl

amygdala/__init__.py

@@ -0,0 +1,7 @@
+"""
+amygdala/ — Emotion processing.
+
+Valence network, mood tracking, fear/risk assessment,
+emotional memory tagging, and arousal-based attention modulation.
+Analogous to the amygdala: fear, emotional memories, threat detection.
+"""

amygdala/affective_forecast.py

@@ -0,0 +1,154 @@
+"""
+amygdala/affective_forecast.py — Predict future valence of a trajectory.
+
+The world model predicts future *states*. This module predicts future
+*feelings* — how a trajectory will make the agent feel over time. This
+lets the cerebrum pick actions not just by predicted reward, but by
+anticipated emotional outcome.
+
+    predicted_valence_trajectory = forecast(z_trajectory)
+
+Use cases:
+    - Avoid actions that lead to sustained negative valence (learned anxiety)
+    - Prefer actions that lead to engagement (learned motivation)
+    - Detect "emotional dead ends" (trajectories that flatten to neutral)
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+import torch
+import torch.nn as nn
+
+
+class AffectiveForecaster(nn.Module):
+    """
+    Predicts the valence trajectory for a sequence of latent states.
+
+    Architecture: small GRU over the trajectory, outputs per-step valence
+    predictions in [-1, 1].
+
+    Args:
+        latent_dim:  Dimensionality of latent states.
+        hidden_dim:  GRU hidden size.
+    """
+
+    def __init__(self, latent_dim: int = 512, hidden_dim: int = 128) -> None:
+        super().__init__()
+        self.gru = nn.GRU(latent_dim, hidden_dim, batch_first=True)
+        self.head = nn.Sequential(
+            nn.Linear(hidden_dim, 64),
+            nn.GELU(),
+            nn.Linear(64, 1),
+            nn.Tanh(),
+        )
+
+    def forward(self, trajectory: torch.Tensor) -> torch.Tensor:
+        """
+        Predict valence at each step of a trajectory.
+
+        Args:
+            trajectory: (B, T, D) latent state sequence.
+
+        Returns:
+            (B, T, 1) predicted valence at each timestep.
+        """
+        h, _ = self.gru(trajectory)       # (B, T, hidden)
+        return self.head(h)               # (B, T, 1)
+
+    def forecast_mean(self, trajectory: torch.Tensor) -> torch.Tensor:
+        """
+        Predict the average valence over a trajectory.
+
+        Returns:
+            (B, 1) mean predicted valence.
+        """
+        per_step = self.forward(trajectory)
+        return per_step.mean(dim=1)
+
+    def forecast_final(self, trajectory: torch.Tensor) -> torch.Tensor:
+        """
+        Predict the valence at the END of the trajectory.
+
+        Returns:
+            (B, 1) final-step valence prediction.
+        """
+        per_step = self.forward(trajectory)
+        return per_step[:, -1, :]
+
+    def compare_trajectories(
+        self,
+        traj_a: torch.Tensor,
+        traj_b: torch.Tensor,
+    ) -> Tuple[float, float]:
+        """
+        Compare two trajectories by predicted emotional outcome.
+
+        Returns:
+            (mean_valence_a, mean_valence_b) — higher is emotionally preferred.
+        """
+        va = float(self.forecast_mean(traj_a).mean().item())
+        vb = float(self.forecast_mean(traj_b).mean().item())
+        return va, vb
+
+    def emotional_dead_end(
+        self,
+        trajectory: torch.Tensor,
+        threshold: float = 0.05,
+    ) -> bool:
+        """
+        Detect if a trajectory leads to emotional flatness (stagnation).
+
+        A dead end is where predicted valence variance across time is
+        near zero AND mean valence is near zero. The agent isn't feeling
+        anything — neither good nor bad. Often worse than negative valence
+        (which at least indicates engagement).
+
+        Returns:
+            True if the trajectory is an emotional dead end.
+        """
+        per_step = self.forward(trajectory)  # (B, T, 1)
+        var = per_step.var(dim=1).mean().item()
+        mean = per_step.mean().abs().item()
+        return var < threshold and mean < threshold
+
+
+class AffectiveForecasterTrainer:
+    """
+    Trains the forecaster on observed (trajectory, actual_valence) pairs.
+
+    Call `update()` with real episodes and their actual valences from the
+    emotional core. The forecaster learns to predict future affect.
+    """
+
+    def __init__(self, forecaster: AffectiveForecaster, lr: float = 1e-4) -> None:
+        self.forecaster = forecaster
+        self.optimizer = torch.optim.Adam(forecaster.parameters(), lr=lr)
+        self._step = 0
+
+    def update(
+        self,
+        trajectory: torch.Tensor,
+        actual_valences: torch.Tensor,
+    ) -> float:
+        """
+        One training step.
+
+        Args:
+            trajectory:      (B, T, D) latent state sequences.
+            actual_valences: (B, T, 1) actual valences observed.
+
+        Returns:
+            Scalar MSE loss.
+        """
+        self.optimizer.zero_grad()
+        predicted = self.forecaster(trajectory)
+        loss = nn.functional.mse_loss(predicted, actual_valences.detach())
+        loss.backward()
+        self.optimizer.step()
+        self._step += 1
+        return loss.item()
+
+
+__all__ = ["AffectiveForecaster", "AffectiveForecasterTrainer"]

amygdala/arousal_modulator.py

@@ -0,0 +1,92 @@
+"""
+amygdala/arousal_modulator.py — Attention gain control.
+
+High arousal (fear, excitement) narrows attention to the most salient
+features. Low arousal (calm, fatigue) broadens attention. The amygdala
+modulates this gain signal and sends it to the thalamus to adjust
+attention sensitivity in the transformer backbone.
+"""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+
+
+class ArousalModulator(nn.Module):
+    """
+    Computes an attention gain signal from the current arousal level.
+
+    The gain is applied as a multiplicative bias to the transformer's
+    attention scores in the thalamus:
+        scores ← scores * gain_scale
+
+    High arousal → gain > 1.0 (sharper, more focused attention)
+    Low arousal  → gain < 1.0 (softer, more diffuse attention)
+
+    Args:
+        d_model:        Latent dimensionality.
+        arousal_dim:    Dimensionality of the arousal input vector.
+                        Defaults to 1 (scalar arousal from homeostasis).
+    """
+
+    def __init__(self, d_model: int, arousal_dim: int = 1) -> None:
+        super().__init__()
+        self.d_model = d_model
+
+        # Maps arousal level → per-head gain scale
+        self.gain_net = nn.Sequential(
+            nn.Linear(arousal_dim, 32),
+            nn.GELU(),
+            nn.Linear(32, 1),
+        )
+        # Initialise to output 0 so gain starts at sigmoid(0) = 0.5 → scale = 1.0
+        nn.init.zeros_(self.gain_net[-1].weight)
+        nn.init.zeros_(self.gain_net[-1].bias)
+
+    def forward(self, arousal: torch.Tensor) -> torch.Tensor:
+        """
+        Compute attention gain scale from arousal level.
+
+        Args:
+            arousal: (B, 1) or scalar arousal value in [0, 1].
+
+        Returns:
+            (B, 1) gain scale. Values > 1.0 sharpen attention,
+            values < 1.0 soften it.
+        """
+        if arousal.dim() == 0:
+            arousal = arousal.unsqueeze(0).unsqueeze(0)
+        elif arousal.dim() == 1:
+            arousal = arousal.unsqueeze(-1)
+
+        # Map [0,1] arousal to gain: 0.5 arousal → gain 1.0 (neutral)
+        raw = self.gain_net(arousal)
+        # Sigmoid centred at 0 → range (0, 1), then scale to (0.5, 2.0)
+        gain = 0.5 + 1.5 * torch.sigmoid(raw)
+        return gain
+
+    def get_valence_bias(
+        self,
+        arousal: torch.Tensor,
+        valence: torch.Tensor,
+    ) -> torch.Tensor:
+        """
+        Compute the combined arousal+valence attention bias for the thalamus.
+
+        This is the signal sent via "arousal_gain" on the SignalBus.
+
+        Args:
+            arousal: (B, 1) arousal level.
+            valence: (B, 1) emotional valence.
+
+        Returns:
+            (B, 1) combined bias for transformer attention scores.
+        """
+        gain = self.forward(arousal)
+        # Valence shifts the bias direction: positive valence → attend to
+        # rewarding features; negative valence → attend to threat features
+        return gain * valence
+
+
+__all__ = ["ArousalModulator"]

amygdala/emotional_core.py

@@ -0,0 +1,199 @@
+"""
+amygdala/emotional_core.py — Emotion processing centre.
+
+The amygdala processes emotions, especially fear and threat responses.
+It tags memories with emotional significance and modulates attention
+based on arousal state. This module is the computational equivalent:
+mood tracking, homeostatic drives, and the valence network that maps
+latent states to emotional tone.
+
+Moved from: core/emotional_core.py
+"""
+
+from __future__ import annotations
+from typing import Tuple
+import torch
+import torch.nn as nn
+from thalamus.latent_alignment import LatentAligner
+
+
+class MoodState:
+    """
+    Tracks a single named emotion and the reason for the most recent change.
+    Performs no tensor operations — pure bookkeeping.
+    """
+
+    def __init__(self, initial_mood: str, valid_vocab: dict) -> None:
+        if initial_mood not in valid_vocab:
+            raise ValueError(
+                f"Initial mood '{initial_mood}' not in vocabulary: "
+                f"{list(valid_vocab.keys())}"
+            )
+        self._mood: str = initial_mood
+        self._reason: str = "Initialization"
+        self._vocab: dict = valid_vocab
+
+    @property
+    def name(self) -> str:
+        return self._mood
+
+    @property
+    def reason(self) -> str:
+        return self._reason
+
+    def transition(self, new_mood: str, reason: str) -> None:
+        if new_mood not in self._vocab:
+            print(f"[MoodState] Unknown mood '{new_mood}'; transition ignored.")
+            return
+        self._mood = new_mood
+        self._reason = reason
+
+
+class HomeostasisState:
+    """
+    4-D homeostatic drive vector: [arousal, energy, safety, engagement].
+    Clamped to [0,1]. strain() = L2 distance from target setpoint.
+    """
+
+    def __init__(
+        self,
+        initial: Tuple[float, float, float, float] = (0.5, 0.8, 1.0, 0.5),
+        target: Tuple[float, float, float, float] = (0.8, 1.0, 0.7, 0.6),
+    ) -> None:
+        self._state = nn.Parameter(torch.tensor(list(initial)), requires_grad=False)
+        self._target = torch.tensor(list(target))
+
+    @property
+    def vector(self) -> torch.Tensor:
+        return self._state
+
+    def update(
+        self,
+        action_impact: float,
+        environment_surprise: float,
+        policy_violation: float = 0.0,
+        tool_failure_rate: float = 0.0,
+        task_success: float = 0.0,
+    ) -> None:
+        self._state[0] += 0.05 * environment_surprise
+        self._state[1] -= 0.02 * action_impact
+        self._state[2] -= 0.10 * float(policy_violation)
+        self._state[3] -= 0.05 * float(tool_failure_rate)
+        self._state[3] += 0.03 * float(task_success)
+        self._state.clamp_(0, 1)
+
+    def strain(self) -> torch.Tensor:
+        target = self._target.to(self._state.device)
+        return torch.norm(self._state - target)
+
+
+class EmotionalCore(nn.Module):
+    """
+    Amygdala: orchestrates mood + homeostasis + valence network.
+
+    Responsibilities:
+      1. Discrete mood bookkeeping (MoodState).
+      2. Homeostatic drive updates (HomeostasisState).
+      3. Learned valence network: (latent_state ‖ internal_state) → scalar ∈ (−1, +1).
+
+    Publishes to SignalBus:
+      "valence_update"     → cerebrum   (current emotional valence)
+      "arousal_gain"       → thalamus   (attention sensitivity scale)
+      "homeostasis_update" → hypothalamus (internal state vector)
+    """
+
+    def __init__(
+        self,
+        latent_aligner: LatentAligner,
+        initial_mood: str = "Calm",
+        hidden_dim: int = 512,
+    ) -> None:
+        super().__init__()
+        self._aligner = latent_aligner
+        self._mood = MoodState(initial_mood, latent_aligner.emotion_vocab)
+        self._homeostasis = HomeostasisState()
+        self.internal_state = self._homeostasis._state
+        self.valence_network = nn.Sequential(
+            nn.Linear(hidden_dim + 4, 128),
+            nn.ReLU(),
+            nn.Linear(128, 1),
+            nn.Tanh(),
+        )
+
+    def current_mood(self) -> Tuple[str, torch.Tensor]:
+        mood_id = self._aligner.emotion_vocab[self._mood.name]
+        idx = torch.tensor(
+            [mood_id], dtype=torch.long,
+            device=self._aligner.emotion_embeddings.weight.device,
+        )
+        vector = self._aligner.emotion_embeddings(idx).squeeze(0).detach()
+        return self._mood.name, vector
+
+    def mood_swing(self, new_mood: str, reason: str) -> None:
+        self._mood.transition(new_mood, reason)
+
+    def reason_for_mood_change(self) -> str:
+        return self._mood.reason
+
+    def set_mood_angry(self, reason: str) -> None:
+        self.mood_swing("Angry", reason)
+
+    def set_mood_sad(self, reason: str) -> None:
+        self.mood_swing("Sad", reason)
+
+    def set_mood_happy(self, reason: str) -> None:
+        self.mood_swing("Happy", reason)
+
+    def set_mood_calm(self, reason: str) -> None:
+        self.mood_swing("Calm", reason)
+
+    def auto_transition_mood(
+        self, valence: float, arousal: float, reason: str = "auto_circumplex",
+    ) -> str:
+        v = float(max(-1.0, min(1.0, valence)))
+        a = float(max(0.0, min(1.0, arousal)))
+        v_pos = v > 0.10
+        v_neg = v < -0.10
+        a_high = a > 0.60
+        a_low = a < 0.40
+
+        if a_high and v_pos:
+            new_mood = "Happy"
+        elif a_high and v_neg:
+            new_mood = "Angry"
+        elif a_low and v_neg:
+            new_mood = "Sad"
+        elif a_low and v_pos:
+            new_mood = "Calm"
+        else:
+            return self._mood.name
+
+        if new_mood != self._mood.name:
+            self._mood.transition(new_mood, reason)
+        return new_mood
+
+    def update_homeostasis(
+        self,
+        action_impact: float,
+        environment_surprise: float,
+        policy_violation: float = 0.0,
+        tool_failure_rate: float = 0.0,
+        task_success: float = 0.0,
+    ) -> None:
+        self._homeostasis.update(
+            action_impact=action_impact,
+            environment_surprise=environment_surprise,
+            policy_violation=policy_violation,
+            tool_failure_rate=tool_failure_rate,
+            task_success=task_success,
+        )
+
+    def calculate_strain(self) -> torch.Tensor:
+        return self._homeostasis.strain()
+
+    def get_valence(self, latent_state: torch.Tensor) -> torch.Tensor:
+        s = self._homeostasis.vector
+        if latent_state.dim() > 1:
+            s = s.unsqueeze(0).expand(latent_state.size(0), -1)
+        combined = torch.cat([latent_state, s], dim=-1)
+        return self.valence_network(combined)

amygdala/emotional_memory.py

@@ -0,0 +1,147 @@
+"""
+amygdala/emotional_memory.py — Emotion-tagged memory encoding.
+
+The amygdala tags memories with emotional significance at encoding time.
+Traumatic or highly rewarding experiences are remembered more vividly
+than neutral ones. This module biases hippocampal memory retrieval
+toward emotionally significant episodes.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Tuple
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+
+class EmotionalMemoryTagger(nn.Module):
+    """
+    Tags latent states with emotional significance scores at encoding time.
+
+    The significance score is used by the hippocampus to weight replay
+    sampling — high-significance memories are replayed more often.
+
+    Significance formula:
+        σ = α · |valence| + β · arousal + γ · surprise
+
+    Where surprise = ||z_predicted - z_actual||₂ (from world model).
+
+    Args:
+        alpha:   Weight on valence magnitude.
+        beta:    Weight on arousal level.
+        gamma:   Weight on prediction surprise.
+    """
+
+    def __init__(
+        self,
+        alpha: float = 0.4,
+        beta: float = 0.3,
+        gamma: float = 0.3,
+    ) -> None:
+        super().__init__()
+        self.alpha = alpha
+        self.beta = beta
+        self.gamma = gamma
+
+    def compute_significance(
+        self,
+        valence: torch.Tensor,
+        arousal: torch.Tensor,
+        surprise: Optional[torch.Tensor] = None,
+    ) -> torch.Tensor:
+        """
+        Compute emotional significance score for a batch of experiences.
+
+        Args:
+            valence:  (B, 1) emotional valence in [-1, 1].
+            arousal:  (B, 1) arousal level in [0, 1].
+            surprise: (B, 1) optional prediction error from world model.
+
+        Returns:
+            (B, 1) significance score in [0, 1].
+        """
+        sig = self.alpha * valence.abs() + self.beta * arousal
+        if surprise is not None:
+            sig = sig + self.gamma * surprise
+        return torch.clamp(sig, 0.0, 1.0)
+
+    def tag_episode(
+        self,
+        states: torch.Tensor,
+        valences: torch.Tensor,
+        arousal: float,
+        surprise: Optional[float] = None,
+    ) -> Dict:
+        """
+        Create an emotion-tagged episode dict for the hippocampus.
+
+        Args:
+            states:   (T, D) state sequence.
+            valences: (T, 1) valence sequence.
+            arousal:  Scalar arousal level.
+            surprise: Optional scalar prediction surprise.
+
+        Returns:
+            Dict with 'states', 'significance', 'emotional_tag'.
+        """
+        arousal_t = torch.tensor([[arousal]])
+        surprise_t = torch.tensor([[surprise]]) if surprise is not None else None
+
+        mean_valence = valences.mean().unsqueeze(0).unsqueeze(0)
+        sig = self.compute_significance(mean_valence, arousal_t, surprise_t)
+
+        return {
+            "states": states,
+            "significance": float(sig.item()),
+            "emotional_tag": {
+                "mean_valence": float(mean_valence.item()),
+                "arousal": arousal,
+                "surprise": surprise or 0.0,
+            },
+        }
+
+
+class EmotionalRetrievalBias(nn.Module):
+    """
+    Biases memory retrieval queries toward emotionally congruent memories.
+
+    Mood-congruent memory: humans recall memories that match their current
+    mood more easily. This module implements the same bias: when the agent
+    is in a high-arousal state, it preferentially retrieves high-arousal
+    memories.
+
+    Args:
+        d_model:  Latent dimensionality.
+    """
+
+    def __init__(self, d_model: int) -> None:
+        super().__init__()
+        # Projects emotional state into query space
+        self.emotion_to_query = nn.Linear(4, d_model)  # 4 = homeostasis dims
+
+    def bias_query(
+        self,
+        base_query: torch.Tensor,
+        homeostasis_vector: torch.Tensor,
+        strength: float = 0.3,
+    ) -> torch.Tensor:
+        """
+        Add an emotional bias to a memory retrieval query.
+
+        Args:
+            base_query:          (B, D) base retrieval query.
+            homeostasis_vector:  (4,) current homeostatic state.
+            strength:            How strongly to bias the query.
+
+        Returns:
+            (B, D) emotionally-biased query.
+        """
+        if homeostasis_vector.dim() == 1:
+            homeostasis_vector = homeostasis_vector.unsqueeze(0)
+        emotion_bias = self.emotion_to_query(homeostasis_vector)  # (1, D)
+        return base_query + strength * emotion_bias
+
+
+__all__ = ["EmotionalMemoryTagger", "EmotionalRetrievalBias"]