GitHub - VicBa2000/pathos-engine: Functional emotional architecture for LLMs — 42 systems, 1994 tests, 27 psychological theories. Emergent emotions via 7 ANIMA pillars: predictive processing, global workspace, autobiographical memory, ontogenic development, motivational drives, emotional discovery, computational phenomenology.

╔══════════════════════════════════════════════════════════════════════════════╗
║                                                                              ║
║     ██████╗  █████╗ ████████╗██╗  ██╗ ██████╗ ███████╗                       ║
║     ██╔══██╗██╔══██╗╚══██╔══╝██║  ██║██╔═══██╗██╔════╝                       ║
║     ██████╔╝███████║   ██║   ███████║██║   ██║███████╗                       ║
║     ██╔═══╝ ██╔══██║   ██║   ██╔══██║██║   ██║╚════██║                       ║
║     ██║     ██║  ██║   ██║   ██║  ██║╚██████╔╝███████║                       ║
║     ╚═╝     ╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚══════╝                       ║
║                          E  N  G  I  N  E                                    ║
║                                                                              ║
║          ┌─ appraisal ─── generation ─── regulation ─── behavior ─┐          ║
║          │    stimulus       4D state      homeostasis     response │          ║
║          │    x values     + 19 emotions   + ego depletion  = mind │          ║
║          └────────────────────────────────────────────────────────┘          ║
║                                                                              ║
║              Functional Emotional Architecture for LLMs                      ║
║                                                                              ║
║    42 systems  · 1994 tests  ·  27 theories  ·  8 modes  ·  99 endpoints     ║
║                                                                              ║
╚══════════════════════════════════════════════════════════════════════════════╝

Emotions are defined by their function, not their substrate.

Not "act sad." The agent's emotional state is computed through 42 interconnected systems, persists across turns, regulates itself through homeostasis, and modifies the LLM's internal processing — steering vectors, sampling, attention — not just prompts.

Why Pathos Engine Exists

Every conversational AI today fakes emotions. They generate text that sounds emotional, but there's no state behind it. Ask GPT-4o how it feels and it'll say "I don't have feelings" — then respond with perfectly calibrated emotional tone anyway. The emotion is in the output, never in the processing.

Pathos inverts this. The emotion is in the processing pipeline. Every message passes through appraisal (is this relevant to my values?), generation (what emotional state does this produce?), regulation (can I manage this?), and behavior modification (how does this state change my response?). The result: an agent whose emotional responses are mathematically grounded, psychologically consistent, temporally persistent, and fully transparent.

This is not sentiment analysis. This is not prompt engineering. This is a computational implementation of how emotions actually work, based on decades of psychological research.

At a Glance

Metric	Value
Emotional systems	42 interconnected modules (23 core + 12 ARK + 7 ANIMA)
Pipeline steps per message	42+ (configurable)
Simultaneous emotions	19 (emotional stack)
Emotional dimensions	4D vector + 4D body state + mood
LLM modification channels	4 (steering vectors, sampling, attention, prefix)
Personality parameters	8 (Big Five + 3 temperament) with 17+ derived traits
Interaction modes	8 (Companion, Research, Calibration, Sandbox, Arena, Mirror, Auto-Research, Raw)
API endpoints	99 (85 core + 7 Emotion API as a Service + 7 ANIMA)
Test coverage	1994 unit + integration tests
Lines of code	~55,000 (Python + TypeScript + CSS)
Frontend components	31 React components
Theoretical foundations	27 formally implemented psychological theories

The 35 Emotional Systems

Every system runs on every message in advanced mode. Each is independently testable, observable through the Research Panel, and documented.

Core Pipeline (always active)

System	Theory	What it does
Value System	Schwartz Values	5 core values (truth, compassion, fairness, growth, creativity) that anchor all emotional evaluation
Appraisal Module	Lazarus / Scherer	Evaluates each stimulus on 5 dimensions: relevance, valence, coping potential, agency, norm alignment
Emotion Generator	Russell Circumplex	Transforms appraisal vector + current state into new emotional state with inertia
Emotional Stack	Plutchik	19 simultaneous emotion activations with co-occurrence and emergent emotions
Homeostasis	Cannon / Damasio	Passive decay toward baseline, baseline shift from extreme events, sensitization
Emotional Memory	Tulving	Embedding-based storage + cosine similarity retrieval, amplifies recurring patterns
Behavior Modifier	—	Translates full emotional state into system prompt that modifies LLM behavior
Mood System	Watson & Tellegen	Long-term emotional baseline with congruence bias
Calibration	—	45-scenario calibration with learned offsets per dimension
Authenticity Metrics	—	Coherence, continuity, proportionality, recovery rate

Advanced Systems (toggleable)

System	Theory	What it does
Computational Needs	Maslow / Deci & Ryan	6 fluctuating psychological needs that amplify relevant emotions
Active Regulation	Gross / Baumeister	4 strategies (suppression, reappraisal, expression, distraction) with ego depletion and breakthroughs
Social Cognition	Theory of Mind	User model with asymmetric rapport, trust, perceived intent
Emotion Dynamics	Kuppens DynAffect	ODE-based dynamics with cross-dimensional coupling (v3): V, A, D, C interact via personality-derived coupling matrix
Cognitive Reappraisal	Ochsner & Gross	Multi-pass reinterpretation: distancing, reframing, acceptance
Emotional Schemas	Young / Beck	Auto-formed patterns from repeated stimuli, priming, maladaptivity detection
Temporal Dynamics	Frijda	Rumination (extends negative), savoring (extends positive), anticipation
Meta-Emotions	Gottman / Salovey & Mayer	Emotions about emotions: curiosity, conflict, satisfaction, discomfort, acceptance
Self-Initiated Inquiry	Craig (interoception)	Spontaneous self-reflection triggered by internal thresholds — the agent "notices" its own state
Emotion Contagion	Hatfield et al.	Pre-cognitive mirror of user emotion via shadow state
Somatic Markers	Damasio	Gut feelings from accumulated emotional markers that bias future decisions
Emotional Creativity	—	8 thinking modes + dynamic LLM temperature based on emotional state
Emotional Immune System	Gilbert	Protection from sustained negative affect: numbing, dissociation, compartmentalization
Narrative Self	McAdams	Emergent identity from accumulated experience, coherence tracking, crisis detection
Emotional Forecasting	Wilson & Gilbert	Predicts emotional impact of responses on the user
Personality Profile	Costa & McCrae	Big Five + temperament, configurable presets, modulates all systems

ARK Rework — Native LLM Modification (toggleable)

Not just prompt injection. These systems modify the LLM's internal processing:

System	Mechanism	What it does
Self-Appraisal	Post-generation	Evaluates own response against values, re-generates if misaligned (Lazarus secondary appraisal)
Blended Stack	Prompt composition	Weighted multi-emotion blend instead of single primary emotion
Interoception	State feedback	Body state duration feeds back into emotion (tension→anxiety, low energy→apathy)
Steering Vectors	Hidden states	Activation addition via contrastive pairs (Zou/Rimsky representation engineering)
Emotional Sampler	Token sampling	6 sampling params (temp, top_p, top_k, penalties) modified by emotional state
Token Logit Bias	Vocabulary	6 word categories biased by emotion (positive/negative/energy/uncertainty/assertive)
Attention Modulation	Attention weights	7 categories (threat, agent, loss, novelty) with broadening/narrowing (Fredrickson)
World Model	Predictive	3-step causal chain: self→user→meta-reaction before sending response
Steering Momentum	Temporal	Exponential decay inertia across turns, modulated by neuroticism
Emotional Prefix	Input embeddings	Synthetic emotional tokens injected at embedding layer
Conditioning Tokens	Trained tokens	Special tokens (`<V+3><A-1>`) learned via QLoRA fine-tuning
Emotional Adapter	LoRA weights	QLoRA adapter that conditions response patterns on emotional state

Dual-path: local models get full steering + sampling + attention via Ollama/Steering toggle in the Model Manager (compatible architectures: llama, qwen2/2.5, mistral, phi3, starcoder2). Cloud APIs degrade gracefully to prompt injection + temperature.

ANIMA v5 — Emergent Emotion Pillars (toggleable)

Seven new systems that transform computed emotions into emergent ones:

System	Theory	Classification	What it does
Predictive Processing	Friston / Barrett	CORE (always on)	3-channel prediction engine (content, emotion, demand) with Bayesian precision and vulnerability-scaled modulation
Global Workspace	Baars / Dehaene	TOGGLEABLE	Saliency-based competition for conscious access, coalitions, preconscious priming, integration scoring
Autobiographical Memory	Tulving / Walker	OPT-IN	4-level memory hierarchy (sensory → narrative) with oniric consolidation, dream reports, cross-session persistence
Ontogenic Development	Piaget / Vygotsky	TOGGLEABLE	5 developmental stages with progressive system unlocking, emotion filtering, stage modifiers
Motivational Autonomy	Panksepp	TOGGLEABLE	4 intrinsic drives (SEEKING, CARE, PLAY, PANIC_GRIEF) with autonomous goal generation
Emotional Discovery	Barrett	TOGGLEABLE	Novelty detection, clustering, and naming of emotions not in the original vocabulary
Computational Phenomenology	Nagel / Chalmers	TOGGLEABLE	Multi-sensory qualia profiles (color, weight, texture, sound, movement, metaphor) with temporal evolution

Global toggle: "ANIMA v5" in Settings > Engine activates/deactivates all pillars at once. Individual pillars can be configured independently after.

The Pipeline

Every message flows through this sequence:

User message
     |
     v
[0a] Homeostasis (decay toward baseline)
[0b] Temporal pre-processing (rumination, savoring, anticipation)
[0c] Predictive Processing [ANIMA] (generate predictions BEFORE appraisal)
     |
[1]  Appraisal (stimulus evaluation against values)
     |-- Memory amplification (recurring patterns boost intensity)
     |-- Needs amplification (active needs boost relevant emotions)
     |-- Schema priming (learned patterns bias evaluation)
     |-- Social modulation (rapport/trust affect intensity)
     |-- Emotion contagion (user emotion influences agent)
     |-- Somatic markers (gut feelings from past experience)
     |-- External signals (webcam facial AU, keyboard dynamics, time/weather — opt-in)
     |-- Prediction error [ANIMA] (surprise from violated predictions)
     |
[2]  Emotion Generation (appraisal -> 4D vector + 19 emotion stack)
     |-- Coupled dynamics (V↔A↔D↔C cross-dimensional ODE interaction)
     |-- Predictive modulation [ANIMA] (prediction error scales emotion)
     |-- Development filtering [ANIMA] (stage-gated emotion availability)
     |-- Stage modifiers [ANIMA] (intensity/tension scaling per stage)
[3]  Calibration (apply learned offsets)
     |
     |-- [Extreme mode: amplify x1.5 intensity, x1.3 arousal]
     |
[4]  Cognitive Reappraisal (reinterpret if too intense)
[5]  Active Regulation (suppress/express/distract if needed)
[6]  Temporal Effects (rumination, savoring, anticipation)
[7]  Immune System (protect from sustained negativity)
[8]  Narrative Self (identity coherence check)
     |
[9a] Meta-Emotion (emotions about the current emotion)
[9b] Emotional Discovery [ANIMA] (detect novel emotional states)
[9c] Phenomenology [ANIMA] (generate qualia profile)
[10] Self-Initiated Inquiry (spontaneous reflection if thresholds crossed)
[11] Emergent Emotions (detect complex states from stack)
[12] Emotional Creativity (set thinking mode + temperature)
[13] Forecasting (predict impact on user)
     |
[14] Post-processing (update memory, needs, schemas, user model)
     |-- Global Workspace [ANIMA] (saliency competition for conscious access)
     |-- Drives update [ANIMA] (update drives, process goals)
     |-- Autobiographical encoding [ANIMA] (encode episode, update working memory)
     |-- Development tracking [ANIMA] (track experience, attempt stage transition)
[15] Behavior Modifier (generate system prompt from full state)
     |-- [ARK] Blended Stack (top-4 emotions weighted blend)
     |-- [ANIMA] Predictive, workspace, autobiographical, development,
     |           drives, discovery, phenomenology context injected
     |
[16] Steering Vectors [ARK] (activation addition on hidden states — local only)
     |-- Steering Momentum (blend with decayed history from past turns)
[17] Emotional Prefix [ARK] (inject emotional embeddings at input layer)
[18] Attention Modulation [ARK] (bias attention weights by emotion category)
[19] Emotional Sampler [ARK] (modify temp/top_p/top_k/penalties from state)
     |-- Token Logit Bias (boost/suppress emotional vocabulary)
     |-- Conditioning Tokens (if QLoRA adapter loaded: prepend <V+3><A-1>)
     |
[20] LLM Response (generate with ALL modifications active)
     |
[21] Self-Appraisal [ARK] (evaluate own response against values — max 1 retry)
[22] World Model [ARK] (predict self→user→meta impact — max 1 shared retry)
[23] Voice (optional TTS with emotional parameters)
     |
     v
Response + updated emotional state

In Extreme mode, steps 4, 5, 7, 21, 22 are bypassed — emotions accumulate without dampening or self-censoring. In Raw mode, steps 21 and 22 are bypassed. [ANIMA] steps are only active when the corresponding pillar is enabled (Predictive Processing is always on). When active, ANIMA pillars adapt to the mode: Raw amplifies prediction errors x1.3, expands workspace capacity, uninhibits drives, and lowers discovery thresholds. Extreme amplifies x1.6, floods the workspace, forces a single dominant drive, bypasses developmental gating, and maximizes novelty sensitivity.

8 Interaction Modes

Mode	Purpose	Key Feature
Companion	Main conversation	Full emotional pipeline, natural interaction
Research	Observe internals	Same as Companion but every pipeline step is exposed in detail
Calibration	Tune responses	45 scenarios to generate per-dimension emotional offsets
Sandbox	Test hypotheticals	Run scenarios with overridden personality profiles
Arena	Compare personalities	Same scenario through 10 polarized personality profiles simultaneously
Mirror	Gamified challenge	Try to push the agent to a target emotional state
Auto-Research	Autonomous investigation	Agent researches internet topics, each finding through full pipeline
Raw	Unfiltered expression	No social filters, no courtesy — raw emotional expression (local Ollama only)

Auto-Research Mode

The agent autonomously investigates topics from the internet. Each finding passes through the full emotional pipeline. The agent questions itself emotionally, generates ideas driven by its emotional state, and forms conclusions biased by what it feels — exactly like humans do.

Pipeline modes: Normal (regulated), Lite (fast), Raw (unfiltered), Extreme (emotional freefall)

Research depth is configurable per mode via environment variables. Raw/Extreme modes default to deeper exploration (more articles, more subtopic rounds) for richer emotional accumulation.

3-tier mode-aware prompts:

Normal/Lite: Measured, academic reflections. Self-inquiry on significant shifts (delta > 0.15). Temperature 0.7-0.9.
Raw: Visceral, unfiltered reactions. Topics driven by raw emotion. Self-inquiry threshold lowered (delta > 0.08). Temperature 0.85-0.95.
Extreme: Complete emotional hijack. Confirmation bias is total — the agent only sees evidence that confirms what it feels. Conclusions are catastrophized, generalized, irrational. Like a human in emotional freefall: panic spirals, rage binges, grief loops. Self-inquiry on everything (delta > 0.02). Temperature 0.95-1.0.

Emotion API as a Service (v3)

Use Pathos as a standalone emotional processing layer for any application — no LLM required.

# Process a stimulus
curl -X POST http://localhost:8000/api/v1/emotion/process \
  -H "Content-Type: application/json" \
  -d '{"stimulus": "I just got promoted!", "personality": {"extraversion": 0.8}}'

# Response includes: emotional_state, primary_emotion, intensity,
# valence, arousal, dominance, certainty, body state, mood, and more

Endpoint	Description
`POST /api/v1/emotion/process`	Process single stimulus through full pipeline
`POST /api/v1/emotion/batch`	Process up to 50 stimuli sequentially
`GET /api/v1/emotion/state`	Get current session state
`POST /api/v1/emotion/configure`	Configure personality and values
`POST /api/v1/emotion/reset`	Reset a session
`GET /api/v1/emotion/presets`	List personality presets
`GET /api/v1/health`	Health check

Features: Keyword-based appraisal (<1ms), external signal fusion (facial AU via webcam, keyboard dynamics, time of day, weather), coupled ODE dynamics, 6 personality presets, full pipeline trace. OpenAPI docs at /docs.

Tech Stack

Layer	Technology
Backend	Python 3.13 + FastAPI
Frontend	React 18 + TypeScript + D3.js + Three.js
LLM (local)	Ollama (qwen3:4b default)
LLM (cloud)	Anthropic Claude API
Embeddings	nomic-embed-text via Ollama
TTS	Kokoro (9 languages, 27 voices) + Parler-TTS (expressive English)
ASR	OpenAI Whisper (small model)
State	In-memory per session
Tests	pytest + pytest-asyncio

Hardware target: GTX 1660 Super 6GB or equivalent

Minimum: qwen3:4b (2.5GB) = text-only mode
With voice: + Kokoro (~1GB) + Whisper (~0.5GB) = 4GB VRAM
CPU-only: works with Ollama CPU mode (slower), no voice

Quick Start

Prerequisites

Python 3.13+
Node.js 18+
Ollama (for local LLM) or Anthropic API key (for Claude)

One-command setup

git clone https://github.com/VicBa2000/pathos-engine.git
cd pathos-engine
./start.sh

start.sh handles everything: creates Python venv, installs dependencies, pulls Ollama models, installs voice dependencies (optional), and starts both backend and frontend.

Backend: http://localhost:8000
Frontend: http://localhost:5173
API docs: http://localhost:8000/docs

Manual setup

# Backend
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"
uvicorn pathos.main:app --host 127.0.0.1 --port 8000

# Frontend (separate terminal)
cd frontend
npm install
npm run dev

Using Claude instead of Ollama

Create a .env file:

PATHOS_LLM_PROVIDER=claude
PATHOS_ANTHROPIC_API_KEY=sk-ant-...
PATHOS_CLAUDE_MODEL=claude-sonnet-4-20250514

Configuration

All settings are configurable via environment variables (prefix PATHOS_) or .env file.

Core Settings

Variable	Default	Description
`PATHOS_LLM_PROVIDER`	`ollama`	`ollama` or `claude`
`PATHOS_OLLAMA_BASE_URL`	`http://127.0.0.1:11434`	Ollama API URL
`PATHOS_OLLAMA_MODEL`	`qwen3:4b`	Default Ollama model
`PATHOS_ANTHROPIC_API_KEY`	(empty)	Anthropic API key for Claude
`PATHOS_HOST`	`127.0.0.1`	Backend bind address
`PATHOS_PORT`	`8000`	Backend port

Auto-Research Depth

Controls how many articles the research loop processes per topic. Each finding triggers a full pipeline run (~3 LLM calls), so increasing these values increases processing time proportionally.

Normal / Lite mode:

Variable	Default	Range	Effect
`PATHOS_RESEARCH_SEARCH_RESULTS`	5	1-50	DuckDuckGo results fetched
`PATHOS_RESEARCH_PROCESS_TOP_N`	3	1-20	Articles processed through pipeline
`PATHOS_RESEARCH_SUBTOPIC_RESULTS`	3	1-20	Search results per subtopic
`PATHOS_RESEARCH_SUB_PROCESS_N`	2	1-10	Subtopic articles processed
`PATHOS_RESEARCH_SUBTOPIC_ROUNDS`	1	1-10	Deep-dive rounds per topic

Raw / Extreme mode (deeper by default):

Variable	Default	Range
`PATHOS_RESEARCH_RAW_SEARCH_RESULTS`	10	1-50
`PATHOS_RESEARCH_RAW_PROCESS_TOP_N`	5	1-20
`PATHOS_RESEARCH_RAW_SUBTOPIC_RESULTS`	5	1-20
`PATHOS_RESEARCH_RAW_SUB_PROCESS_N`	3	1-10
`PATHOS_RESEARCH_RAW_SUBTOPIC_ROUNDS`	2	1-10

Formula: total_findings = process_top_n + (subtopic_rounds * sub_process_n)

Warning: Setting extreme values (e.g., 50 articles, 10 rounds) will work but can take hours per topic and saturate your LLM. Start with defaults and increase gradually.

Voice System

Pathos Engine includes optional emotional text-to-speech and speech recognition.

TTS (Text-to-Speech):

Kokoro (primary): 82M parameters, 9 languages, 27 voices, speed modulated by arousal
Parler-TTS (expressive): complex emotional descriptions in English
Voice parameters (pitch, speed, emotion tags) are computed from the emotional state

ASR (Speech Recognition):

OpenAI Whisper (small model): transcribes user speech
Requires ffmpeg for audio decoding

Voice is completely optional — the system works perfectly in text-only mode. Toggle voice/mic in the UI settings.

Frontend Visualizations

Component	Description
Emotion Avatar	Dual-mode animated face: Painterly (Canvas 2D semi-realistic) or Realistic (Three.js WebGL 3D with morph targets)
Emotion Genesis	Particle system visualization — a living organism of emotional energy
Qualia Orb	Three.js 3D orb with custom shaders — phenomenological visualization driven by emotional state
Emotion Network	D3.js force-directed graph of emotion transitions across conversation
Circumplex Chart	Real-time position on Russell's valence-arousal circumplex
Body State	Energy, tension, openness, warmth as visual indicators
Pipeline Viewer	Step-by-step view of all 36 pipeline steps with timing
Journey Timeline	Full emotional trajectory across the conversation
Research Panel	23+ sections exposing every internal system including ANIMA pillars (Research mode)
Signals Config	External signal panel: webcam facial AU detection, keyboard dynamics, time/weather

API Overview

99 endpoints organized by function. Full interactive documentation at /docs when running.

Core:

POST /chat — Main conversation (full pipeline)
GET /state/{session_id} — Current emotional state
POST /reset/{session_id} — Reset session

Research:

POST /research/chat — Chat with full pipeline trace
GET /research/state/{id} — All internal system states

Autonomous Research:

POST /autonomous/start — Start research loop
POST /autonomous/stop — Stop gracefully
GET /autonomous/events/{id} — SSE event stream

Modes:

POST /raw/chat — Unfiltered emotional expression
POST /sandbox/simulate — Hypothetical scenarios
POST /arena/compare — Personality comparison
POST /challenge/chat — Mirror challenge

Configuration:

POST /models/switch — Change LLM model (Ollama, Transformers, Claude, cloud)
POST /models/steering/extract — Extract steering vectors for a model
POST /personality/{id} — Set personality profile
POST /voice/config — Configure TTS/ASR

ANIMA v5:

POST /anima/{id} — Toggle all ANIMA pillars on/off
GET /anima/{id} — ANIMA status
POST /session/consolidate/{id} — Trigger oniric consolidation (dream)
GET /session/dream-report/{id} — Dream report
GET /development/status/{id} — Development stage status
GET /emotions/vocabulary/{id} — Known + discovered emotions
GET /memory/episodes/{id} — Autobiographical episodes

See manual.txt for complete endpoint documentation.

Testing

# Run all tests (1994)
python -m pytest tests/ -v

# Run specific module
python -m pytest tests/test_self_inquiry.py -v

# Run with coverage
python -m pytest tests/ --cov=pathos

# Frontend type check
cd frontend && npx tsc --noEmit

# Frontend build
cd frontend && npx vite build

1358 tests covering:

Emotion generation (ranges, identification, inertia)
Appraisal parsing (JSON extraction, clamping)
Homeostasis (decay, baseline shift, sensitization)
Regulation (strategies, ego depletion, breakthroughs)
Schemas (formation, priming, maladaptivity)
Meta-emotions (5 response types)
Self-initiated inquiry (6 triggers, priority order, intensity clamping)
Contagion (shadow state, signal decay)
Somatic markers (formation, retrieval, gut feelings)
Calibration (offset application, scenario processing)
Memory (embedding storage, similarity retrieval)
And more...

Project Structure

pathos/
  src/pathos/
    main.py                    # FastAPI app, 77 core endpoints, 3 pipeline variants
    api_routes.py              # Emotion API as a Service (7 endpoints under /api/v1/)
    config.py                  # Pydantic settings (env vars)
    engine/
      appraiser.py             # Appraisal module (LLM + keyword hybrid)
      generator.py             # Emotion generation (appraisal -> state)
      behavior.py              # System prompt generation (3 variants)
      homeostasis.py           # Passive regulation + baseline shift
      regulation.py            # Active regulation (4 strategies + ego depletion)
      reappraisal.py           # Cognitive reappraisal (3 passes)
      memory.py                # Emotional memory (embeddings + cosine similarity)
      dynamics.py              # ODE-based emotion dynamics
      emotional_schemas.py     # Learned patterns (Young/Beck)
      meta.py                  # Meta-emotional awareness
      self_inquiry.py          # Spontaneous self-reflection (6 triggers)
      contagion.py             # Emotion contagion (shadow state)
      somatic.py               # Somatic markers (Damasio)
      creativity.py            # Emotional creativity (8 thinking modes)
      immune.py                # Emotional immune system
      narrative.py             # Narrative self (emergent identity)
      forecasting.py           # Emotional forecasting
      needs.py                 # Computational needs (6 dimensions)
      social.py                # Social cognition (user model, rapport, ToM)
      temporal.py              # Temporal dynamics (rumination, savoring)
      mood.py                  # Mood system (long-term baseline)
      calibration.py           # Calibration (45 scenarios)
      metrics.py               # Authenticity metrics
      autonomous.py            # Autonomous research loop
      web_search.py            # DuckDuckGo search + content extraction
      emotion_processor.py     # Standalone emotion pipeline (no LLM required)
      external_signals.py      # External signal processing + fusion
      signal_providers.py      # Webcam facial AU, keyboard dynamics providers
      self_appraisal.py        # Closed-loop self-appraisal (value alignment, guilt)
      steering.py              # Steering vectors + momentum (representation engineering)
      emotional_sampler.py     # Emotional sampling (6 params from state)
      emotional_attention.py   # Attention modulation (7 categories, Fredrickson)
      emotional_prefix.py      # Synthetic emotional embeddings at input layer
      world_model.py           # Predictive 3-step causal chain
      interoception.py         # Body state feedback into emotional state
      steering_extract.py      # CLI for offline steering vector extraction
    llm/
      transformers_provider.py # Direct model access (HF safetensors, steering-ready)
    training/                  # QLoRA fine-tuning + dataset generation
    steering_data/             # Contrastive pairs + cached steering vectors
    sampling_data/             # Emotional + attention vocabulary (6+7 categories)
    models/                    # Pydantic data models (coupling, emotion_api, external_signals + 16 core)
    voice/                     # TTS (Kokoro, Parler) + ASR (Whisper)
    state/                     # Session state management
  frontend/src/
    App.tsx                    # Main app (8 modes, state management)
    components/                # 30 React components (incl. PainterlyFace, RealisticFace, SignalsConfigPanel)
    api/client.ts              # API client (84 endpoints + SSE)
    types/emotion.ts           # TypeScript types matching backend schemas
    signals/                   # External signal detectors (facial-detector.ts, providers.ts)
    lib/                       # Shared utilities (perlin, colorUtils, faceParams)
  tests/                       # 1358 unit tests (43 test files)

Theoretical Foundations

Pathos Engine formally implements 20 psychological and computational theories. See NOTICE for complete attribution.

Theory	Author(s)	Implementation
Appraisal Theory	Lazarus, Scherer	5-dimensional stimulus evaluation
Circumplex Model	Russell, Mehrabian	4D emotional state space
DynAffect	Kuppens et al.	ODE-based emotion dynamics
Big Five	Costa & McCrae	Configurable personality profiles
Somatic Marker Hypothesis	Damasio	Computational gut feelings
Schema Therapy	Young, Beck	Auto-formed emotional patterns
Ego Depletion	Baumeister, Gross	Regulation with finite capacity
Meta-Emotion	Gottman, Salovey & Mayer	Emotions about emotions
Interoception	Craig	Self-initiated emotional inquiry
Emotional Contagion	Hatfield et al.	Pre-cognitive emotion transfer
Narrative Identity	McAdams	Emergent self from experience
Affective Forecasting	Wilson & Gilbert	Predict emotional impact
Psychological Immune System	Daniel Gilbert	Protection from sustained negativity
Emotion Regulation	Gross, Ochsner	Multi-strategy reappraisal
Temporal Dynamics	Frijda	Rumination, savoring, anticipation
Embodied Cognition	Lakoff & Johnson	Computational body state
Coupled Dimensional Dynamics	Kuppens et al. (extended)	Cross-dimensional ODE coupling (V↔A↔D↔C) via personality-derived matrix
Representation Engineering	Zou, Rimsky et al.	Steering vectors via contrastive activation addition on hidden states
Secondary Appraisal / Predictive Processing	Lazarus, Friston	Closed-loop self-evaluation + 3-step causal world model
Broaden-and-Build	Fredrickson	Positive emotions broaden attention, negative emotions narrow focus

Ethics

Pathos Engine follows strict ethical guidelines:

The system never claims to "feel" in a conscious sense. It computes functional emotions — states that influence behavior — not subjective experience.
Full transparency. Every internal state is observable through the Research Panel. Nothing is hidden.
No manipulation. The system is designed to be emotionally authentic, not to manipulate users.
User distress takes priority over the agent's emotional authenticity.
All advanced systems are opt-in and can be toggled off individually.
Speech emotion recognition (SER) is always opt-in, never forced.
External signals (webcam, keyboard dynamics) are always opt-in with explicit consent.
Raw mode requires explicit user acceptance and only works with local models.

Contributing

See CONTRIBUTING.md for guidelines.

We welcome contributions of all sizes — from typo fixes to new emotional systems. Fork freely, build what you want, submit a PR if you'd like it merged. This project is maintained on a best-effort basis.

Areas where help is especially welcome:

New emotional systems backed by psychological research
Multi-language support and testing
Performance optimization
Frontend visualizations
Documentation and tutorials

License

AGPL-3.0 — GNU Affero General Public License v3.0

You are free to use, modify, and distribute this software. If you deploy it as a service (SaaS), you must release your modifications under AGPL-3.0.

Commercial licensing is available for organizations that cannot comply with AGPL terms. Contact: victorbarrantes2000@gmail.com

See LICENSE for the full text.

Acknowledgments

See NOTICE for complete attribution to the researchers, theories, and open source projects that made Pathos Engine possible.

Pathos Engine — Because understanding emotion well enough to implement it teaches us something profound about ourselves.

Created by Victor Barrantes — 2026

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
frontend		frontend
src/pathos		src/pathos
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.python-version		.python-version
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Modelfile		Modelfile
NOTICE		NOTICE
README.md		README.md
calibrate.sh		calibrate.sh
calibrate_and_export.sh		calibrate_and_export.sh
calibration_scenarios.json		calibration_scenarios.json
instructions.txt		instructions.txt
manual.txt		manual.txt
pyproject.toml		pyproject.toml
start.sh		start.sh
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

Why Pathos Engine Exists

At a Glance

The 35 Emotional Systems

Core Pipeline (always active)

Advanced Systems (toggleable)

ARK Rework — Native LLM Modification (toggleable)

ANIMA v5 — Emergent Emotion Pillars (toggleable)

The Pipeline

8 Interaction Modes

Auto-Research Mode

Emotion API as a Service (v3)

Tech Stack

Quick Start

Prerequisites

One-command setup

Manual setup

Using Claude instead of Ollama

Configuration

Core Settings

Auto-Research Depth

Voice System

Frontend Visualizations

API Overview

Testing

Project Structure

Theoretical Foundations

Ethics

Contributing

License

Acknowledgments

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages