chip-brain 1.0.0__tar.gz

chip_brain-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chip Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chip_brain-1.0.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: chip-brain
+Version: 1.0.0
+Summary: Brain-anatomical proto-AGI cognitive engine
+Author: Chip Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/Doorman11991/Chip
+Project-URL: Repository, https://github.com/Doorman11991/Chip
+Project-URL: Changelog, https://github.com/Doorman11991/Chip/blob/main/CHANGELOG.md
+Keywords: ai,agi,cognitive-architecture,reinforcement-learning,brain
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0
+Requires-Dist: transformers>=4.30
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# Chip — A Brain-Anatomical Proto-AGI
+
+Chip is a pure-Python cognitive engine modelled after the human brain. Every module lives in the brain region it belongs to, communicates through typed signals on a central bus, and can be disabled without crashing the system.
+
+It doesn't generate text. It doesn't call APIs. It *thinks* — in a 512-dimensional latent space where observations, emotions, memories, goals, and actions all share the same geometry.
+
+## Installation
+
+```bash
+# Option 1: pip (recommended)
+pip install chip-brain
+
+# Option 2: Docker
+docker run -it ghcr.io/doorman11991/chip:latest
+
+# Option 3: From source
+git clone https://github.com/Doorman11991/Chip.git
+cd Chip
+pip install torch transformers
+
+# (Optional) Copy the env template
+cp .env.example .env
+
+# Verify everything works
+python -c "from brain import ChipBrain; print(ChipBrain())"
+```
+
+**Requirements:**
+- Python 3.10–3.13 (3.14 has known numpy issues on Windows)
+- PyTorch 2.0+
+- HuggingFace Transformers 4.30+
+
+**Optional (for GPU acceleration):**
+- CUDA toolkit (NVIDIA)
+- DirectML (AMD on Windows)
+- MPS (Apple Silicon — automatic)
+
+The first call to the text encoder downloads IBM Granite-125m (~250MB) from HuggingFace. After that it's cached locally and loads in ~5 seconds. The Docker image pre-caches it at build time.
+
+## Quick Start
+
+```bash
+# Interactive session — just talk to it
+python run.py
+```
+
+```
+  Chip Brain — Interactive Session
+
+  Commands:
+    [text]     Feed an observation to the brain
+    status     Show brain state
+    mood       Show current mood and drives
+    thoughts   Show recent inner speech
+    goals      Show active goals
+    memory     Show memory stats
+    save       Force save to disk
+    quit       Save and exit
+
+you > I notice something strange in the corner of the room.
+
+  [tick 1] mood=Calm, confidence=0.49, |action|=0.42
+  thought: "I notice this feels novel. There is also a sense of risky."
+
+you > thoughts
+
+  [Calm] I notice this feels novel. There is also a sense of risky.
+
+you > status
+
+  tick:       1
+  mood:       Calm
+  top goal:   explore_frontier
+  confidence: 0.49
+  memories:   0
+  wm slots:   3/7
+```
+
+### As a Python library
+
+```python
+from brain import ChipBrain
+
+brain = ChipBrain().boot()
+
+# One cognitive tick from a text observation:
+action = brain.tick("I see an unfamiliar door at the end of the corridor.")
+
+# Feed reward, advance training:
+brain.train_step(reward=0.5, done=False)
+
+# Save state to disk:
+brain.shutdown()
+```
+
+## Requirements
+
+```
+pip install torch transformers
+```
+
+That's it. Two dependencies. Everything else is built from scratch.
+
+## Architecture
+
+```
+Chip/
+├── brain.py                 ← Consciousness loop (top-level orchestrator)
+├── interfaces/              ← White matter: ABCs, SignalBus, plugin slots
+├── thalamus/                ← Sensory relay: granite encoder, transformer backbone, attention bottleneck
+├── amygdala/                ← Emotion: valence, fear veto, habituation, arousal modulation
+├── hippocampus/             ← Memory: episodic store, recall, dreams, boundary detection, cognitive maps
+├── hypothalamus/            ← Drives: homeostasis, curiosity, energy, entropy temperature
+├── cerebrum/                ← Cognition: policy, working memory, world model, reasoning, goals, inner speech
+├── cerebellum/              ← Coordination: action smoothing, skill library, swarm consensus, emotional contagion
+├── brainstem/               ← Life support: training loop, health monitor, persistence, scheduling
+├── locomotion/              ← Network migration (cognitive snapshot serialisation)
+└── parasite/                ← Parasitic knowledge extraction from black-box models
+```
+
+## How It Works
+
+Everything is a 512-D vector on a unit sphere. Text, emotions, memories, actions, goals — all in the same space. Cosine similarity = semantic relatedness.
+
+**One tick flows like this:**
+
+1. **Thalamus** — Text enters via IBM Granite-125m (768→512 projection). Transformer backbone filters and routes tokens. Attention bottleneck selects the top-k most salient. Top-down query from previous tick's cerebrum biases what passes through.
+
+2. **Amygdala** — Fast emotional assessment (valence network). Habituation dampens repeated stimuli. Arousal gain signal sent to thalamus. Fear assessor can veto dangerous actions.
+
+3. **Hippocampus** — Retrieves top-3 relevant past episodes into working memory. Boundary detector auto-segments the stream via prediction-error spikes. Temporal abstractor compresses across timescales. Cognitive map tracks explored latent regions.
+
+4. **Hypothalamus** — 6-dim drive vector (arousal, energy, safety, engagement, curiosity, coherence). Curiosity reward from world model prediction error. Drive arbitrator picks the most urgent need. Entropy temperature adjusts exploration.
+
+5. **Cerebrum** — Working memory (7 slots). Policy selects action via dual-actor SAC with personality bias. Meta-cognition checks confidence; if low, fires 3-step reasoning chain. Inner speech surfaces thoughts in language. Contradiction detector checks new evidence against core beliefs. Goal stack manages hierarchical sub-goal planning.
+
+6. **Cerebellum** — Action smoothing (EMA). Skill library retrieval. Swarm consensus (if multi-node). Emotional contagion across nodes.
+
+7. **Brainstem** — SAC training update. Gradient clipping. Health monitoring (NaN detection). Periodic autosave to disk with HMAC-signed snapshots.
+
+## Key Design Decisions
+
+**One latent space.** No translation layers between modalities. Everything projects into the same 512-D sphere so any two things can be compared by dot product.
+
+**Signal bus, not imports.** Brain regions never import each other. They publish typed `NeuralSignal` objects on a priority-ordered bus. This makes the system testable, observable, and gracefully degradable.
+
+**Stop-gradient boundaries.** The world model trains on detached latents so it can't fight the policy optimizer for the backbone's representation.
+
+**Periodic language grounding.** Every 100 ticks, the brain translates its internal state into English ("I feel calm and curious"), encodes it with granite, and anchors the identity token to it. The subconscious drifts in language-grounded space, not arbitrary latent drift.
+
+**SLERP belief revision.** When new evidence contradicts a core belief, the belief embedding rotates on the unit sphere via spherical linear interpolation. Small contradictions → quiet revision. Large contradictions → narrative crisis that forces deliberation.
+
+**Active dreaming.** The hippocampus doesn't just replay memories — it identifies key decision points, imagines alternative actions via the world model, evaluates the counterfactual trajectories, and stores the best as synthetic memories. Creativity from imagination.
+
+## Plugin Slots
+
+Chip is designed to be embedded in a larger system. The host application provides:
+
+```python
+from interfaces.plugins import ITool, ToolRegistry, IEnvironment
+
+class MyTool(ITool):
+    name = "search"
+    def call(self, args): ...
+
+brain = ChipBrain(tool_registry=ToolRegistry()).boot()
+```
+
+Available extension points:
+- `ITool` / `ToolRegistry` — external tool dispatch
+- `IEnvironment` — step-based environment loop
+- `ISensor` — custom sensory modality
+- `IRewardSource` — external reward signal
+- `HookRegistry` — observe brain events (inner speech, contradictions, boundaries)
+
+## Persistence
+
+The brain autosaves to `.chip_state/` every N ticks:
+- HMAC-SHA256 signed snapshots (tamper-proof)
+- Atomic writes (crash-safe)
+- Rolling backups (corruption recovery)
+- Auto-restore on boot
+
+```python
+brain.save()      # manual save
+brain.shutdown()  # save + cleanup
+```
+
+## Tests
+
+```
+python scripts/e2e_brain_test.py                    # full brain against LM Studio endpoint
+python scripts/example_granite_integration.py       # granite embedder demo
+python scripts/test_feature_episodic_recall.py      # inference-time memory retrieval
+python scripts/test_feature_topdown_attention.py    # corticothalamic feedback loop
+python scripts/test_feature_persistence.py          # save/restore/crash recovery
+python scripts/test_feature_inner_speech.py         # internal monologue
+python scripts/test_feature_self_consistency.py     # contradiction detection + belief revision
+python scripts/test_feature_stability_fixes.py      # stop-gradient + Platt calibration
+python scripts/test_feature_goal_stack.py           # hierarchical sub-goal planning
+python scripts/test_feature_habit_boundary.py       # habituation + episodic boundaries
+python scripts/test_feature_contagion_dreaming.py   # emotional contagion + active dreaming
+```
+
+191 tests. All passing.
+
+## What This Is Not
+
+- Not a chatbot. It doesn't generate text.
+- Not a LangChain wrapper. No API calls in the loop.
+- Not a research toy. It persists state, handles crashes, and scales.
+- Not finished. It needs a real training environment to become intelligent.
+
+The architecture is complete. The intelligence emerges from training.
+
+## License
+
+See [LICENSE](LICENSE).

chip_brain-1.0.0/README.md

@@ -0,0 +1,218 @@
+# Chip — A Brain-Anatomical Proto-AGI
+
+Chip is a pure-Python cognitive engine modelled after the human brain. Every module lives in the brain region it belongs to, communicates through typed signals on a central bus, and can be disabled without crashing the system.
+
+It doesn't generate text. It doesn't call APIs. It *thinks* — in a 512-dimensional latent space where observations, emotions, memories, goals, and actions all share the same geometry.
+
+## Installation
+
+```bash
+# Option 1: pip (recommended)
+pip install chip-brain
+
+# Option 2: Docker
+docker run -it ghcr.io/doorman11991/chip:latest
+
+# Option 3: From source
+git clone https://github.com/Doorman11991/Chip.git
+cd Chip
+pip install torch transformers
+
+# (Optional) Copy the env template
+cp .env.example .env
+
+# Verify everything works
+python -c "from brain import ChipBrain; print(ChipBrain())"
+```
+
+**Requirements:**
+- Python 3.10–3.13 (3.14 has known numpy issues on Windows)
+- PyTorch 2.0+
+- HuggingFace Transformers 4.30+
+
+**Optional (for GPU acceleration):**
+- CUDA toolkit (NVIDIA)
+- DirectML (AMD on Windows)
+- MPS (Apple Silicon — automatic)
+
+The first call to the text encoder downloads IBM Granite-125m (~250MB) from HuggingFace. After that it's cached locally and loads in ~5 seconds. The Docker image pre-caches it at build time.
+
+## Quick Start
+
+```bash
+# Interactive session — just talk to it
+python run.py
+```
+
+```
+  Chip Brain — Interactive Session
+
+  Commands:
+    [text]     Feed an observation to the brain
+    status     Show brain state
+    mood       Show current mood and drives
+    thoughts   Show recent inner speech
+    goals      Show active goals
+    memory     Show memory stats
+    save       Force save to disk
+    quit       Save and exit
+
+you > I notice something strange in the corner of the room.
+
+  [tick 1] mood=Calm, confidence=0.49, |action|=0.42
+  thought: "I notice this feels novel. There is also a sense of risky."
+
+you > thoughts
+
+  [Calm] I notice this feels novel. There is also a sense of risky.
+
+you > status
+
+  tick:       1
+  mood:       Calm
+  top goal:   explore_frontier
+  confidence: 0.49
+  memories:   0
+  wm slots:   3/7
+```
+
+### As a Python library
+
+```python
+from brain import ChipBrain
+
+brain = ChipBrain().boot()
+
+# One cognitive tick from a text observation:
+action = brain.tick("I see an unfamiliar door at the end of the corridor.")
+
+# Feed reward, advance training:
+brain.train_step(reward=0.5, done=False)
+
+# Save state to disk:
+brain.shutdown()
+```
+
+## Requirements
+
+```
+pip install torch transformers
+```
+
+That's it. Two dependencies. Everything else is built from scratch.
+
+## Architecture
+
+```
+Chip/
+├── brain.py                 ← Consciousness loop (top-level orchestrator)
+├── interfaces/              ← White matter: ABCs, SignalBus, plugin slots
+├── thalamus/                ← Sensory relay: granite encoder, transformer backbone, attention bottleneck
+├── amygdala/                ← Emotion: valence, fear veto, habituation, arousal modulation
+├── hippocampus/             ← Memory: episodic store, recall, dreams, boundary detection, cognitive maps
+├── hypothalamus/            ← Drives: homeostasis, curiosity, energy, entropy temperature
+├── cerebrum/                ← Cognition: policy, working memory, world model, reasoning, goals, inner speech
+├── cerebellum/              ← Coordination: action smoothing, skill library, swarm consensus, emotional contagion
+├── brainstem/               ← Life support: training loop, health monitor, persistence, scheduling
+├── locomotion/              ← Network migration (cognitive snapshot serialisation)
+└── parasite/                ← Parasitic knowledge extraction from black-box models
+```
+
+## How It Works
+
+Everything is a 512-D vector on a unit sphere. Text, emotions, memories, actions, goals — all in the same space. Cosine similarity = semantic relatedness.
+
+**One tick flows like this:**
+
+1. **Thalamus** — Text enters via IBM Granite-125m (768→512 projection). Transformer backbone filters and routes tokens. Attention bottleneck selects the top-k most salient. Top-down query from previous tick's cerebrum biases what passes through.
+
+2. **Amygdala** — Fast emotional assessment (valence network). Habituation dampens repeated stimuli. Arousal gain signal sent to thalamus. Fear assessor can veto dangerous actions.
+
+3. **Hippocampus** — Retrieves top-3 relevant past episodes into working memory. Boundary detector auto-segments the stream via prediction-error spikes. Temporal abstractor compresses across timescales. Cognitive map tracks explored latent regions.
+
+4. **Hypothalamus** — 6-dim drive vector (arousal, energy, safety, engagement, curiosity, coherence). Curiosity reward from world model prediction error. Drive arbitrator picks the most urgent need. Entropy temperature adjusts exploration.
+
+5. **Cerebrum** — Working memory (7 slots). Policy selects action via dual-actor SAC with personality bias. Meta-cognition checks confidence; if low, fires 3-step reasoning chain. Inner speech surfaces thoughts in language. Contradiction detector checks new evidence against core beliefs. Goal stack manages hierarchical sub-goal planning.
+
+6. **Cerebellum** — Action smoothing (EMA). Skill library retrieval. Swarm consensus (if multi-node). Emotional contagion across nodes.
+
+7. **Brainstem** — SAC training update. Gradient clipping. Health monitoring (NaN detection). Periodic autosave to disk with HMAC-signed snapshots.
+
+## Key Design Decisions
+
+**One latent space.** No translation layers between modalities. Everything projects into the same 512-D sphere so any two things can be compared by dot product.
+
+**Signal bus, not imports.** Brain regions never import each other. They publish typed `NeuralSignal` objects on a priority-ordered bus. This makes the system testable, observable, and gracefully degradable.
+
+**Stop-gradient boundaries.** The world model trains on detached latents so it can't fight the policy optimizer for the backbone's representation.
+
+**Periodic language grounding.** Every 100 ticks, the brain translates its internal state into English ("I feel calm and curious"), encodes it with granite, and anchors the identity token to it. The subconscious drifts in language-grounded space, not arbitrary latent drift.
+
+**SLERP belief revision.** When new evidence contradicts a core belief, the belief embedding rotates on the unit sphere via spherical linear interpolation. Small contradictions → quiet revision. Large contradictions → narrative crisis that forces deliberation.
+
+**Active dreaming.** The hippocampus doesn't just replay memories — it identifies key decision points, imagines alternative actions via the world model, evaluates the counterfactual trajectories, and stores the best as synthetic memories. Creativity from imagination.
+
+## Plugin Slots
+
+Chip is designed to be embedded in a larger system. The host application provides:
+
+```python
+from interfaces.plugins import ITool, ToolRegistry, IEnvironment
+
+class MyTool(ITool):
+    name = "search"
+    def call(self, args): ...
+
+brain = ChipBrain(tool_registry=ToolRegistry()).boot()
+```
+
+Available extension points:
+- `ITool` / `ToolRegistry` — external tool dispatch
+- `IEnvironment` — step-based environment loop
+- `ISensor` — custom sensory modality
+- `IRewardSource` — external reward signal
+- `HookRegistry` — observe brain events (inner speech, contradictions, boundaries)
+
+## Persistence
+
+The brain autosaves to `.chip_state/` every N ticks:
+- HMAC-SHA256 signed snapshots (tamper-proof)
+- Atomic writes (crash-safe)
+- Rolling backups (corruption recovery)
+- Auto-restore on boot
+
+```python
+brain.save()      # manual save
+brain.shutdown()  # save + cleanup
+```
+
+## Tests
+
+```
+python scripts/e2e_brain_test.py                    # full brain against LM Studio endpoint
+python scripts/example_granite_integration.py       # granite embedder demo
+python scripts/test_feature_episodic_recall.py      # inference-time memory retrieval
+python scripts/test_feature_topdown_attention.py    # corticothalamic feedback loop
+python scripts/test_feature_persistence.py          # save/restore/crash recovery
+python scripts/test_feature_inner_speech.py         # internal monologue
+python scripts/test_feature_self_consistency.py     # contradiction detection + belief revision
+python scripts/test_feature_stability_fixes.py      # stop-gradient + Platt calibration
+python scripts/test_feature_goal_stack.py           # hierarchical sub-goal planning
+python scripts/test_feature_habit_boundary.py       # habituation + episodic boundaries
+python scripts/test_feature_contagion_dreaming.py   # emotional contagion + active dreaming
+```
+
+191 tests. All passing.
+
+## What This Is Not
+
+- Not a chatbot. It doesn't generate text.
+- Not a LangChain wrapper. No API calls in the loop.
+- Not a research toy. It persists state, handles crashes, and scales.
+- Not finished. It needs a real training environment to become intelligent.
+
+The architecture is complete. The intelligence emerges from training.
+
+## License
+
+See [LICENSE](LICENSE).

chip_brain-1.0.0/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.
+"""

chip_brain-1.0.0/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"]