anima-engine 0.0.1__tar.gz

anima_engine-0.0.1/.gitignore

@@ -0,0 +1,51 @@
+# ----------------------
+# Python
+# ----------------------
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Test / coverage
+.coverage
+.coverage.*
+.pytest_cache/
+htmlcov/
+
+# Type checkers
+.mypy_cache/
+.pyright/
+.ruff_cache/
+
+# IDEs
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local data (usually not tracked)
+data/
+
+# Environment variables
+.env
+.env.*
+
+# uv lockfile (uncomment if you DON'T want it tracked)
+# uv.lock

anima_engine-0.0.1/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: anima-engine
+Version: 0.0.1
+Summary: Real-time continuous affect engine
+Requires-Python: >=3.12
+Requires-Dist: datasets>=2.0.0
+Requires-Dist: huggingface-hub>=1.4.0
+Requires-Dist: nltk>=3.8.1
+Requires-Dist: numpy>=2.2.0
+Requires-Dist: sentence-transformers>=5.2.0
+Requires-Dist: textstat>=0.7.3
+Requires-Dist: transformers>=5.1.0
+Provides-Extra: anchor
+Requires-Dist: ollama>=0.1.7; extra == 'anchor'
+Description-Content-Type: text/markdown
+
+# Anima
+
+```
+anima /ˈæn.ɪ.mə/
+
+the soul, especially the irrational part of the soul as distinguished from the rational mind.
+```
+Anima extracts a living emotional state from raw text, and outputs a vector that can be broadcast to any downstream consumer.  
+
+One example use is generating in-flight modifications to body language and changes in eye-color with the related [Reachy Mini Conversational App behavioral adapter](https://github.com/brainwavecollective/anima-reachy-conversation) for the [Reachy Mini](https://github.com/pollen-robotics/reachy_mini) robot.  To get a better sense of how the affect extraction engine works you can check out this [writeup explaining the approach](https://github.com/brainwavecollective/affection/blob/main/EMOTION_ENGINE.md).  
+
+You can get a quick sense for how the engine converts text to an emotional vector by running:  
+`uv run tests/smoke.py`  
+
+## Installation  
+
+`pip install anima-engine@git+https://github.com/brainwavecollective/anima-engine.git`
+
+## Acknowledgements  
+
+This project uses the NRC Valence, Arousal, and Dominance (VAD) Lexicon (v2.1) created by Saif M. Mohammad at the National Research Council Canada. Homepage: http://saifmohammad.com/WebPages/nrc-vad.html
+
+If you use this project in academic work, please cite:
+Mohammad, Saif M. (2025). NRC VAD Lexicon v2: Norms for Valence, Arousal, and Dominance for over 55k English Terms. arXiv:2503.23547.
+
+## About the Author  
+
+Daniel Ritchie is an independent technologist and founder of the Brain Wave Collective.  
+[LinkedIn](https://linkedin.com/in/danielritchie123)  
+[Email](mailto:daniel@brainwavecollective.ai)  

anima_engine-0.0.1/README.md

@@ -0,0 +1,30 @@
+# Anima
+
+```
+anima /ˈæn.ɪ.mə/
+
+the soul, especially the irrational part of the soul as distinguished from the rational mind.
+```
+Anima extracts a living emotional state from raw text, and outputs a vector that can be broadcast to any downstream consumer.  
+
+One example use is generating in-flight modifications to body language and changes in eye-color with the related [Reachy Mini Conversational App behavioral adapter](https://github.com/brainwavecollective/anima-reachy-conversation) for the [Reachy Mini](https://github.com/pollen-robotics/reachy_mini) robot.  To get a better sense of how the affect extraction engine works you can check out this [writeup explaining the approach](https://github.com/brainwavecollective/affection/blob/main/EMOTION_ENGINE.md).  
+
+You can get a quick sense for how the engine converts text to an emotional vector by running:  
+`uv run tests/smoke.py`  
+
+## Installation  
+
+`pip install anima-engine@git+https://github.com/brainwavecollective/anima-engine.git`
+
+## Acknowledgements  
+
+This project uses the NRC Valence, Arousal, and Dominance (VAD) Lexicon (v2.1) created by Saif M. Mohammad at the National Research Council Canada. Homepage: http://saifmohammad.com/WebPages/nrc-vad.html
+
+If you use this project in academic work, please cite:
+Mohammad, Saif M. (2025). NRC VAD Lexicon v2: Norms for Valence, Arousal, and Dominance for over 55k English Terms. arXiv:2503.23547.
+
+## About the Author  
+
+Daniel Ritchie is an independent technologist and founder of the Brain Wave Collective.  
+[LinkedIn](https://linkedin.com/in/danielritchie123)  
+[Email](mailto:daniel@brainwavecollective.ai)  

anima_engine-0.0.1/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "anima-engine"
+version = "0.0.1"
+description = "Real-time continuous affect engine"
+readme = "README.md"
+requires-python = ">=3.12"
+
+dependencies = [
+    "numpy>=2.2.0",
+    "sentence-transformers>=5.2.0",
+    "transformers>=5.1.0",
+    "huggingface-hub>=1.4.0",
+    "textstat>=0.7.3",
+    "nltk>=3.8.1",
+    "datasets>=2.0.0"
+]
+
+[project.optional-dependencies]
+anchor = [
+    "ollama>=0.1.7"
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/anima"]
+
+[dependency-groups]
+dev = [
+    "build>=1.4.0",
+]

anima_engine-0.0.1/src/anima/__init__.py

@@ -0,0 +1,7 @@
+"""Anima - Real-time emotional affect engine for robots."""
+
+from .anima import Anima
+from .config import Config
+from .utils.time_source import TimeSource
+
+__all__ = ["Anima", "Config", "TimeSource"]

anima_engine-0.0.1/src/anima/anima.py

@@ -0,0 +1,313 @@
+import asyncio
+import inspect
+import logging
+import time
+from collections import deque
+from concurrent.futures import ThreadPoolExecutor
+from typing import Callable, List, Optional
+
+import nltk
+import numpy as np
+
+from .transforms.cinematic import CinematicAmplifier
+from .extractors.local import OLLAMA_AVAILABLE, LocalExtractor
+from .transforms.blend import Blend
+from .config import Config
+from .extractors.fast import FastExtractor
+from .utils.time_source import TimeSource
+
+
+class Anima:
+    """
+    Real-time affect generation engine.
+
+    Produces continuous VADCC values from text input.
+    Owns its own loop and broadcasts state at fixed tick rate.
+    """
+
+    def __init__(self, config: Config):
+        self.config = config
+        self.config.validate()
+
+        self.logger = logging.getLogger("anima")
+        self.logger.setLevel(logging.DEBUG if self.config.debug else logging.INFO)
+
+        # Components (loaded in start())
+        self.extractor: Optional[FastExtractor] = None
+        self.amplifier: Optional[CinematicAmplifier] = None
+        self.anchor: Optional[LocalExtractor] = None
+        self.blend: Optional[Blend] = None
+
+        # Create time_source
+        self.clock = TimeSource()
+
+        # Runtime
+        self._running = False
+        self._loop_task: Optional[asyncio.Task] = None
+        self._anchor_executor: Optional[ThreadPoolExecutor] = None
+
+        self._subscribers: List[Callable[[List[float]], None]] = []
+
+        self._context_buffer = deque(maxlen=self.config.context_buffer_words)
+        self._transcript_count = 0
+
+        # --- Baseline coordination (race-free) ---
+        self._baseline_event = asyncio.Event()
+        self._baseline_task: Optional[asyncio.Task] = None
+        self._baseline_lock = asyncio.Lock()
+
+
+    # ---------------------------------------------------------
+    # Lifecycle
+    # ---------------------------------------------------------
+
+    async def start(self) -> None:
+        self.logger.info("Starting Anima...")
+
+        try:
+            nltk.data.find("tokenizers/punkt")
+        except LookupError:
+            nltk.download("punkt", quiet=True)
+
+        self.extractor = FastExtractor(
+            lexicon_path=self.config.nrc_lexicon_path,
+            model_name=self.config.sentence_model_name,
+            debug=self.config.debug,
+        )
+        self.amplifier = CinematicAmplifier()
+        self.blend = Blend(self.config, self.clock)
+
+        # ---- FULL PIPELINE WARMUP (direct, no executor) ----
+        self._extract_sentence_states_sync(
+            "Warmup sentence to initialize extractor and embedder."
+        )
+
+        # Anchor (optional)
+        if self.config.enable_anchor:
+            if not OLLAMA_AVAILABLE:
+                raise RuntimeError(
+                    "Anchor enabled but ollama is not installed. "
+                    "Install affect-engine[anchor]"
+                )
+            self.logger.info("Anchor enabled")
+
+            self.anchor = LocalExtractor(model=self.config.anchor_model_name)
+            self._anchor_executor = ThreadPoolExecutor(
+                max_workers=1,
+                thread_name_prefix="affect-anchor",
+            )
+        else:
+            self.logger.info("Anchor disabled")
+            self.anchor = None
+            self._anchor_executor = None
+
+        if self.config.warm_baseline_on_start:
+            await self._warm_baseline()
+
+        self._running = True
+        self._loop_task = asyncio.create_task(self._loop())
+
+        self.logger.info("Anima started")
+
+    async def stop(self) -> None:
+        self.logger.info("Stopping Anima...")
+
+        self._running = False
+
+        if self._loop_task:
+            self._loop_task.cancel()
+            try:
+                await self._loop_task
+            except asyncio.CancelledError:
+                pass
+
+        if self._baseline_task and not self._baseline_task.done():
+            self._baseline_task.cancel()
+            try:
+                await self._baseline_task
+            except asyncio.CancelledError:
+                pass
+
+        if self._anchor_executor:
+            self._anchor_executor.shutdown(wait=False)
+
+        self.logger.info("Anima stopped")
+
+    def subscribe(self, callback: Callable[[List[float]], None]) -> None:
+        self._subscribers.append(callback)
+
+    # ---------------------------------------------------------
+    # Public API
+    # ---------------------------------------------------------
+
+    async def process_text(
+        self,
+        text: str,
+        influence: Optional[float] = None,
+    ) -> dict:
+        """
+        Process text and apply a single burst driven by the most
+        emotionally dominant sentence.
+        """
+
+        if not self.blend or not self.extractor or not self.amplifier:
+            raise RuntimeError("Anima not started. Call `await engine.start()` first.")
+
+        t0 = time.perf_counter()
+
+        text = (text or "").strip()
+        if not text:
+            return {"anima": self.blend.current.tolist()}
+
+        self._transcript_count += 1
+        self._context_buffer.extend(text.split())
+
+        sentence_states, sentences = self._extract_sentence_states_sync(text)
+
+        if not sentence_states:
+            return {
+                "anima": self.blend.current.tolist(),
+                "sentences_processed": 0,
+                "transcript_count": self._transcript_count,
+            }
+
+        def _dominance_score(vibe: np.ndarray) -> float:
+            v, a, d = float(vibe[0]), float(vibe[1]), float(vibe[2])
+            magnitude = abs(v - 0.5) * 2.0 + abs(a - 0.5) + abs(d - 0.5)
+            negative_bias = max(0.0, 0.5 - v) * 3.5
+            return magnitude + negative_bias
+
+        dominant = max(sentence_states, key=_dominance_score)
+        mean_vibe = np.mean(sentence_states, axis=0)
+        final_burst = np.clip(0.85 * dominant + 0.15 * mean_vibe, 0.0, 1.0)
+
+        self.blend.apply_burst(final_burst, influence=influence)
+
+        if self.anchor:
+            self._baseline_event.set()
+
+        if self.logger.isEnabledFor(logging.DEBUG):
+            self.logger.debug("ENGINE total dt=%.3fs", time.perf_counter() - t0)
+
+        return {
+            "anima": self.blend.current.tolist(),
+            "sentences_processed": len(sentences),
+            "transcript_count": self._transcript_count,
+        }
+
+    # ---------------------------------------------------------
+    # Sync extraction (runs directly now)
+    # ---------------------------------------------------------
+
+    def _extract_sentence_states_sync(self, text: str):
+        sentences = nltk.sent_tokenize(text)
+        sentence_states: List[np.ndarray] = []
+
+        for sentence in sentences:
+            natural = np.array(self.extractor.extract(sentence))
+            post_passion = self.amplifier.amplify_passion(natural, self.config.passion)
+            post_drama = self.amplifier.snap_drama(post_passion, self.config.drama)
+
+            sentence_states.append(post_drama)
+
+            if self.config.debug:
+                self._log_telemetry(sentence, natural, post_passion, post_drama)
+
+        return sentence_states, sentences
+
+    # ---------------------------------------------------------
+    # Internal loop
+    # ---------------------------------------------------------
+
+    async def _loop(self) -> None:
+        interval = 1.0 / self.config.tick_rate_hz
+
+        while self._running:
+            self.clock.tick()
+            vibe = self.blend.tick()
+
+            for sub in self._subscribers:
+                try:
+                    result = sub(vibe)
+                    if inspect.isawaitable(result):
+                        asyncio.create_task(result)
+                except Exception:
+                    self.logger.exception("Subscriber error")
+
+            if self.anchor and self._baseline_event.is_set() and self._has_settled():
+                self._ensure_baseline_task()
+
+            await asyncio.sleep(interval)
+
+    # ---------------------------------------------------------
+    # Baseline (race-free, coalesced)
+    # ---------------------------------------------------------
+
+    def _ensure_baseline_task(self) -> None:
+        if self._baseline_task and not self._baseline_task.done():
+            return
+        self._baseline_task = asyncio.create_task(self._baseline_worker())
+
+    async def _baseline_worker(self) -> None:
+        async with self._baseline_lock:
+            if not self._baseline_event.is_set():
+                return
+
+            self._baseline_event.clear()
+
+            context_text = " ".join(
+                list(self._context_buffer)[-self.config.baseline_window_words :]
+            )
+            if not context_text.strip():
+                return
+
+            if not self.anchor or not self._anchor_executor:
+                return
+
+            loop = asyncio.get_running_loop()
+            baseline = await loop.run_in_executor(
+                self._anchor_executor,
+                self.anchor.extract_baseline,
+                context_text,
+            )
+
+            if baseline:
+                self.blend.apply_baseline(baseline)
+                self.logger.info("New baseline applied: %s", baseline)
+
+    async def _warm_baseline(self) -> None:
+        if not self.anchor:
+            return
+
+        self._baseline_event.set()
+        self._ensure_baseline_task()
+
+        if self._baseline_task:
+            await self._baseline_task
+
+    def _has_settled(self, threshold: float = 0.02) -> bool:
+        diff = np.abs(self.blend.current - self.blend.baseline)
+        return np.all(diff < threshold)
+
+    # ---------------------------------------------------------
+    # Debug telemetry
+    # ---------------------------------------------------------
+
+    def _log_telemetry(
+        self,
+        sentence: str,
+        natural: np.ndarray,
+        post_passion: np.ndarray,
+        post_drama: np.ndarray,
+    ) -> None:
+        if not self.logger.isEnabledFor(logging.DEBUG):
+            return
+
+        self.logger.debug("--------------------------------------------------")
+        self.logger.debug("TEXT: %s", sentence)
+        self.logger.debug("NATURAL: %s", natural.tolist())
+        self.logger.debug("PASSION: %s", post_passion.tolist())
+        self.logger.debug("DRAMA: %s", post_drama.tolist())
+        self.logger.debug("BASELINE: %s", self.blend.baseline.tolist())
+        self.logger.debug("--------------------------------------------------")
+

anima_engine-0.0.1/src/anima/config.py

@@ -0,0 +1,131 @@
+import logging
+import logging.config
+from dataclasses import dataclass, field
+from pathlib import Path
+from .utils.nrc_vad_lexicon import ensure_nrc_lexicon
+
+
+# ---------------------------------------------------------------------------
+# Third-party loggers: name → the minimum verbosity level required to unlock.
+# Ordered from least to most noisy — verbosity is cumulative (>= threshold).
+# ---------------------------------------------------------------------------
+_THIRD_PARTY_VERBOSITY: dict[str, int] = {
+    "httpx":    1,   # -v:   clean "HTTP Request: ..." summary lines
+    "fsspec":   2,   # -vv:  local file open/read events
+    "filelock": 2,   # -vv:  lock acquire/release events
+    "httpcore": 3,   # -vvv: full HTTP lifecycle (very noisy)
+}
+
+
+def _apply_logging(debug: bool, verbosity: int) -> None:
+    """
+    Configure logging for Anima.
+
+    debug=True  → your code logs at DEBUG; third-party stays quiet by default.
+    verbosity   → independently unlocks noisy third-party loggers:
+                  0  all third-party quiet (default)
+                  1  httpx INFO summaries
+                  2  + fsspec, filelock DEBUG
+                  3  + httpcore full HTTP lifecycle
+    """
+    logging.config.dictConfig({
+        "version": 1,
+        "disable_existing_loggers": False,
+        "formatters": {
+            "standard": {
+                "format": "%(asctime)s %(levelname)-8s %(name)s | %(message)s",
+                "datefmt": "%Y-%m-%d %H:%M:%S",
+            },
+        },
+        "handlers": {
+            "console": {
+                "class": "logging.StreamHandler",
+                "formatter": "standard",
+            },
+        },
+        "root": {
+            "handlers": ["console"],
+            "level": logging.DEBUG if debug else logging.INFO,
+        },
+    })
+
+    # Third-party loggers stay quiet regardless of debug,
+    # unlocking only when verbosity meets their threshold.
+    for name, unlocks_at in _THIRD_PARTY_VERBOSITY.items():
+        level = logging.DEBUG if verbosity >= unlocks_at else logging.WARNING
+        logging.getLogger(name).setLevel(level)
+
+
+@dataclass
+class Config:
+    """
+    Configuration for Anima.
+    All tuning parameters live here.
+    Mutate before calling engine.start().
+    """
+    # ---------------------------------------------------------
+    # Core Emotional Tuning
+    # ---------------------------------------------------------
+    passion: float = 2.25
+    drama: float = 0.65
+    default_influence: float = 0.22
+    baseline_influence: float = 0.70
+    dwell_seconds: float = 1.2
+    hold_seconds: float = 0.8
+    decay_rate: float = 0.06
+    tick_rate_hz: float = 10.0
+    # ---------------------------------------------------------
+    # Bounds
+    # ---------------------------------------------------------
+    min_vadcc: float = 0.0
+    max_vadcc: float = 1.0
+    # ---------------------------------------------------------
+    # NLP Models
+    # ---------------------------------------------------------
+    nrc_lexicon_path: str = "data/NRC-VAD-Lexicon-v2.1/NRC-VAD-Lexicon-v2.1.txt"
+    sentence_model_name: str = "all-MiniLM-L6-v2"
+    # ---------------------------------------------------------
+    # Anchor (Slow Baseline)
+    # ---------------------------------------------------------
+    enable_anchor: bool = False
+    anchor_model_name: str = "nemotron-mini:4b-instruct-q5_K_M"
+    warm_baseline_on_start: bool = True
+    baseline_window_words: int = 100
+    # ---------------------------------------------------------
+    # Context Tracking
+    # ---------------------------------------------------------
+    context_buffer_words: int = 200
+    # ---------------------------------------------------------
+    # Logging
+    # ---------------------------------------------------------
+    debug: bool = False
+    log_verbosity: int = 0
+    # Controls third-party logger noise, independent of debug.
+    # Third-party loggers stay quiet even when debug=True unless verbosity is raised.
+    #   0  quiet across the board (default)
+    #   1  httpx request summaries  (-v)
+    #   2  + fsspec, filelock       (-vv)
+    #   3  + httpcore full lifecycle (-vvv, very noisy)
+    # ---------------------------------------------------------
+    # Validation
+    # ---------------------------------------------------------
+    def validate(self) -> None:
+        if not (0.0 <= self.passion <= 5.0):
+            raise ValueError("passion must be between 0 and 5")
+        if not (0.0 <= self.drama <= 1.0):
+            raise ValueError("drama must be between 0 and 1")
+        if self.tick_rate_hz <= 0:
+            raise ValueError("tick_rate_hz must be positive")
+        if self.min_vadcc >= self.max_vadcc:
+            raise ValueError("min_vadcc must be < max_vadcc")
+        if not (0 <= self.log_verbosity <= 3):
+            raise ValueError("log_verbosity must be between 0 and 3")
+        ensure_nrc_lexicon(self.nrc_lexicon_path)
+        if not Path(self.nrc_lexicon_path).exists():
+            raise FileNotFoundError(
+                f"NRC lexicon not found at {self.nrc_lexicon_path}"
+            )
+
+    def apply_logging(self) -> None:
+        """Configure logging based on this config. Call once at startup."""
+        _apply_logging(self.debug, self.log_verbosity)

anima_engine-0.0.1/src/anima/extractors/__init__.py

@@ -0,0 +1,6 @@
+"""Extractors create emotional state vectors from text."""
+
+from .fast import FastExtractor
+from .local import LocalExtractor
+
+__all__ = ["FastExtractor", "LocalExtractor"]