totemheart 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,16 +1,31 @@
1
1
  # Totemheart
2
2
 
3
- ![Totemheart banner](docs/banner.png)
3
+ ![Totemheart banner](https://raw.githubusercontent.com/AlejoMalia/Totemheart/main/docs/banner.png)
4
4
 
5
5
  [![License](https://img.shields.io/badge/license-MIT-blue?style=plastic)](LICENSE)
6
- [![Version](https://img.shields.io/badge/version-0.1.0-a1b858?style=plastic)](package.json)
6
+ [![Calibration](https://img.shields.io/badge/calibration-citation%20ledger-8a2be2?style=plastic)](CALIBRATION.md)
7
+ [![Version](https://img.shields.io/badge/version-0.1.2-a1b858?style=plastic)](package.json)
7
8
  [![Node](https://img.shields.io/badge/node-%3E%3D18-339933?style=plastic&logo=node.js&logoColor=white)](package.json)
8
- [![Tests](https://img.shields.io/badge/tests-75%20passing-brightgreen?style=plastic)](test/smoke.test.js)
9
+ [![Tests](https://img.shields.io/badge/tests-2298%20passing-brightgreen?style=plastic)](test)
9
10
  [![Mechanisms verified](https://img.shields.io/badge/mechanisms-72%20verified%20%2F%206%20covered%20%2F%200%20failed-brightgreen?style=plastic)](examples/verify-all-mechanisms.js)
10
11
 
11
- > The Tests/Mechanisms badges above are static, last updated by hand from a real local `npm test` / `npm run verify` run. There's no CI wired yet to keep them live, so treat them as a snapshot, not a guarantee they still pass on `main`.
12
+ > The Tests/Mechanisms badges above are static, last updated by hand from a real local `npm test` / `npm run verify` run. There's no CI wired yet to keep them live, so treat them as a snapshot, not a guarantee they still pass on `main`. Two later mechanism rounds (the 10 dynamics upgrades and `LoveHateEngine`) each ship their own dedicated live audit instead of being folded into the `verify` script above: `npm run upgrade-round-mock` (39/39) and `npm run lovehate-mock` (24/24). `npm test` runs [`test/`](test) in full: `regression/` (92, bug-fix guards and basic sanity), `integration/` (177, directed multi-mechanism scenarios, full-pipeline emergency routes crossed through real consecutive turns, exhaustive field-by-field serialization, malformed/hostile-input robustness, concurrent `processInput()` calls, real `OllamaProvider` unreachable-host fallback, and non-ES/EN language input), and `property/` (2029, deterministic parameter-grid checks over exact boundaries, combined-extreme OCEAN personality corners, and long-horizon saturation limits including 5000-turn memory/mood-window boundedness — no randomness, same result every run).
12
13
 
13
- **Totemheart** is a state machine for giving an AI a *consistent inner life* across a conversation: personality, mood, memory, stress, and social dynamics that persist and evolve, instead of every reply being computed from scratch. It's not a sentiment classifier and it doesn't make an AI "feel" in the way a person does. See [What this actually is](#what-this-actually-is) below before you build on top of it.
14
+ **Totemheart** is a deterministic control kernel for persistent cognition, not a sentiment classifier and not a prompt-engineering trick. It gives an AI a *consistent inner life* across a conversation: personality, mood, memory, stress, and social dynamics that persist and evolve through real control-theory and neuroscience-derived math, instead of every reply being computed from scratch off a mood label. See [What this actually is](#what-this-actually-is) below before you build on top of it.
15
+
16
+ ## How this differs from a sentiment-based chatbot layer
17
+
18
+ | | Typical "emotional AI" repo | Totemheart |
19
+ | --- | --- | --- |
20
+ | Core mechanism | Prompt engineering + emotion classifier | Dynamic system: every spike, decay, homeostatic pull and circadian phase interacts in real time and feeds the next turn |
21
+ | Emotion → output | Rule of thumb (`if arousal > 0.7, add exclamation marks`) | State-driven directives derived from the actual PAD vector and its recent trajectory |
22
+ | State | None, or a mood string overwritten each turn | Persistent, inspectable state object updated by real dynamics every turn |
23
+ | Signal processing | Raw score in, raw score out | Kalman filtering on arousal, PID with anti-windup on basic needs (stamina, hunger), cubic non-linear decay (a bigger offset from baseline is restored proportionally harder) |
24
+ | Memory | "Remembers everything" or nothing at all | REM-style consolidation on idle-time triggers, latent-weight decay toward a non-zero floor (not to zero), token-overlap reactivation instead of blind recall |
25
+ | Reward signal | Positive/negative sentiment score | Temporal-difference prediction error, `RPE = R_t + γ·V(S_t+1) − V(S_t)`, the same formulation used in reinforcement-learning neuroscience, with per-relationship eligibility traces |
26
+ | Relational memory | One bipolar "liked me / didn't" score | Affinity and Aversion tracked as two separate accumulators (`LoveHateEngine`), so real ambivalence is representable instead of averaging out to neutral |
27
+ | Stress response | A static "angry" threshold | Allostatic load raises reactivity to negative input the longer stress goes unaddressed, a real chronic-stress coupling, not a fixed multiplier |
28
+ | Persistence | "Save the mood to a database and hope" | `toJSON()` / rehydrate with round-trip verification in tests |
14
29
 
15
30
  ## What this actually is
16
31
 
@@ -53,7 +68,7 @@ Modeling the other person: trust, reputation, theory of mind, relationship memor
53
68
  | TheoryOfMind | EmotionalContagion | ChronicContagion | EpisodicMemory | ForgettingCurve |
54
69
  | Attachment | GuiltEngine | TribalCategorization | ReputationEngine | EgoProjection |
55
70
  | BystanderEffect | SelfModel | MonteCarloToM | FairnessMonitor | CounterfactualComparison |
56
- | GratitudeEngine | StatusEnvy | EgoConfidence | UncannyValleyDetector | |
71
+ | GratitudeEngine | StatusEnvy | EgoConfidence | UncannyValleyDetector | LoveHateEngine |
57
72
 
58
73
  ### 🎭 `behavior/`
59
74
 
@@ -101,6 +116,7 @@ Pluggable language backends, from a zero-dependency lexicon to a real transforme
101
116
  - **`LifeEventCatalog`**: 43/56 entries use the published Life Change Units from the [Holmes & Rahe (1967) SRRS](https://en.wikipedia.org/wiki/Holmes_and_Rahe_stress_scale); the other 13 (acute events the scale doesn't cover) are engineering estimates. Multiple matches in one turn are triangulated into a blended state.
102
117
  - **`SemanticSimilarity`**: requires an embedding backend (`embedProvider`); falls back to `EmotionalOntology` keyword matching without one.
103
118
  - **`InteroceptiveSignals`**: real math (derivative, tonic/phasic decomposition, DFT, thermal lag) on internal signals standing in for 4 sensors Totemheart doesn't have (pupil, skin conductance, HRV, flush). Feeds back into cognition only, never rendered.
119
+ - **`LoveHateEngine`**: tracks Affinity and Aversion as two SEPARATE per-user accumulators (not one bipolar scale), so a relationship can be genuinely ambivalent instead of averaging out to neutral. Real diminishing returns on Affinity, a self-reinforcing (kindling) slope on Aversion, an asymmetric decay rate (grudges outlast warmth), and a hysteresis-gated rupture/repair cycle that freezes dopaminergic wanting, damages ego health, and opens a real unresolved wound on rupture. See its own file for the full equations and citations.
104
120
 
105
121
  ### Internal scheduling
106
122
 
@@ -110,21 +126,21 @@ Pluggable language backends, from a zero-dependency lexicon to a real transforme
110
126
 
111
127
  ## How coherent is this, really?
112
128
 
113
- Short version: **~77-80% with an LLM connected, ~61-65% running standalone on the zero-dependency heuristic path, 0% subjective experience, by design and permanently.** Self-assessed, qualitative estimates of how much of each layer is grounded in real theory/technique vs. own engineering judgment. The headline is not an average of the row values below: it carries an additional discount for integrated-system validation that doesn't exist yet. Full citation ledger: [`CALIBRATION.md`](CALIBRATION.md).
129
+ Short version: **~79-82% with an LLM connected, ~63-67% running standalone on the zero-dependency heuristic path, 0% subjective experience, by design and permanently.** Self-assessed, qualitative estimates of how much of each layer is grounded in real theory/technique vs. own engineering judgment. The headline is not an average of the row values below: it carries an additional discount for integrated-system validation that doesn't exist yet. Full citation ledger: [`CALIBRATION.md`](CALIBRATION.md).
114
130
 
115
131
  | Layer | With LLM | Heuristic only | Grounded in |
116
132
  | --- | --- | --- | --- |
117
- | State engine | ~80-83% | same | PID control (anti-windup), Kalman filtering, prospect-theory loss aversion, TD reward-prediction-error, circumplex/PAD affect space, Holmes & Rahe life-event severity |
133
+ | State engine | ~82-85% | same | PID control (anti-windup, dynamic set points), Kalman filtering (now with real interoception-informed measurement noise), allostatic load (McEwen & Stellar 1993), prospect-theory loss aversion, TD reward-prediction-error with eligibility traces (Sutton & Barto), wanting/liking dissociation (Berridge & Robinson 1998), circumplex/PAD affect space with momentum/hysteresis, Holmes & Rahe life-event severity |
118
134
  | Semantic understanding | ~85-88% | ~68-73% | LLM: real language understanding. Heuristic: lexicon + concept-graph matching, keyword-triggered life-event detection, lexical-vs-context incongruence check, mean/variance anomaly detection, confidence-weighted routing between logical and affective reads |
119
- | Expression / output | ~90-93% | ~62-68% | Structured system-prompt injection, coherence validation against prior turns, attachment-weighted style adaptation, cognitive-load-derived output metadata |
120
- | Cross-turn continuity | ~91-94% | same | Persistent state serialization, asymmetric trust/reputation tracking, unresolved-memory flagging, idle-time-based consolidation, long-horizon memory decay with similarity-triggered reactivation |
135
+ | Expression / output | ~91-94% | ~64-70% | Structured system-prompt injection, coherence validation against prior turns, attachment-weighted style adaptation, a full-state-weighted action-tendency policy, real suppression-cost accrual, cognitive-load-derived output metadata |
136
+ | Cross-turn continuity | ~92-95% | same | Persistent state serialization, asymmetric trust/reputation tracking, attachment styles with rupture-and-repair (Bartholomew & Horowitz 1991; Gottman & Levenson 1992), memory reconsolidation on retrieval (Nader et al. 2000), unresolved-memory flagging with intrusive resurfacing, idle-time-based consolidation, long-horizon memory decay with similarity-triggered reactivation |
121
137
  | Subjective experience | **0%** | **0%** | Not a gap to close: no known way to build or verify this in any software |
122
138
 
123
139
  The headline stays below the row average because none of these numbers include validation against psychologist judges, regression against real labeled chat data, or real-user testing of whether the integrated pipeline reads as coherent. See `CALIBRATION.md` for what hasn't been empirically validated.
124
140
 
125
141
  ### Per-mechanism grounding
126
142
 
127
- The table above scores each functional layer as a whole. This scores five specific, individually-audited mechanisms instead: how much of *that one technique* is real citable theory vs. own engineering, independent of which layer it feeds.
143
+ The table above scores each functional layer as a whole. This scores ten specific, individually-audited mechanisms instead: how much of *that one technique* is real citable theory vs. own engineering, independent of which layer it feeds.
128
144
 
129
145
  | Mechanism | Grounded | Basis |
130
146
  | --- | --- | --- |
@@ -133,8 +149,13 @@ The table above scores each functional layer as a whole. This scores five specif
133
149
  | Forgetting curve + latent-memory reactivation | ~55-60% | Ebbinghaus (1885) grounds the general decay-over-time shape; the non-zero floor and keyword-triggered "spark" are its own design, not a reproduction of the classic curve (which decays to zero) |
134
150
  | REM-style consolidation | ~50-58% | Sleep-dependent memory consolidation is real (Diekelmann & Born 2010; McClelland et al. 1995) as a general phenomenon; the specific cooling formula and idle-time threshold are engineering estimates |
135
151
  | Expression debt / sensory-overload friction | ~35-42% | Cognitive load theory (Sweller 1988) motivates the general concept; the debt-accumulation-and-payback mechanic itself has no named psychological construct behind it, own design end to end |
152
+ | Dopaminergic wanting/liking split + TD(λ) eligibility traces | ~70-78% | Berridge & Robinson (1998) is a real, well-cited dissociation; Sutton & Barto's TD(λ) is a literal, standard reinforcement-learning algorithm applied to a per-relationship expectation store |
153
+ | Allostatic load / chronic-stress reactivity | ~58-66% | McEwen & Stellar (1993) and McEwen (1998) are real, well-cited theory; translating "wear from chronic stress" into a dynamic PID set point and a reactivity multiplier is its own control-systems engineering, not a reproduction of any measured allostatic-load curve |
154
+ | Attachment styles + rupture-and-repair | ~50-58% | Bartholomew & Horowitz's (1991) four-category model and the Gottman/Levenson rupture-and-repair literature are real; mapping OCEAN traits onto attachment-style buckets is our own engineering choice, explicitly not a validated psychometric equivalence |
155
+ | Vaillant defense hierarchy | ~55-63% | Vaillant's (1977) mature/neurotic/immature taxonomy is real, established clinical theory; the ego-health/cortisol-weighted tier-shifting mechanism that picks among them each turn is own design |
156
+ | `LoveHateEngine` dual-valence bond field | ~38-46% | The individual pieces it reuses (diminishing-returns accumulation, kindling, asymmetric decay, rupture-and-repair) each draw on real cited work; the specific coupled two-accumulator update equations are our own engineering design end to end, not a reproduction of any published relational model |
136
157
 
137
- All five passed a dedicated live audit (`npm run exhaustive-audit`, 25/25) confirming the code does what its own formulas claim. That's internal consistency, not psychological validation, and the percentages above already price that distinction in.
158
+ Every mechanism in this table passed a dedicated live audit: `npm run exhaustive-audit` (25/25) for the first five, `npm run upgrade-round-mock` (39/39) and `npm run lovehate-mock` (24/24) for the rest, confirming the code does what its own formulas claim. That's internal consistency, not psychological validation, and the percentages above already price that distinction in.
138
159
 
139
160
  ## Prerequisites
140
161
 
@@ -155,7 +176,7 @@ yarn add totemheart
155
176
  ```js
156
177
  import { Totemheart, Personality, VERSION } from 'totemheart'
157
178
 
158
- console.log( VERSION ) // '0.1.0', also available as Totemheart.VERSION and in toJSON().version
179
+ console.log( VERSION ) // '0.1.2', also available as Totemheart.VERSION and in toJSON().version
159
180
 
160
181
  const ai = new Totemheart( {
161
182
  personality: new Personality( { neuroticism: 0.7, agreeableness: 0.3 } ),
@@ -189,7 +210,7 @@ await client.chat.completions.create( {
189
210
 
190
211
  `result.structuredContext` gives you the same information as plain JSON if you'd rather build your own prompt formatting. Call `ai.getSystemPrompt()` on its own (no new turn) to seed the very first message of a conversation, or to refresh context after `ai.idle()`/`ai.tick()` shifts the mood between turns.
191
212
 
192
- Run `npm run demo` for a full scripted conversation showing decay, hedonic adaptation, dopaminergic surprise, sensory overload, and a generated system prompt in action. Run `npm test` for the mechanic-level test suite. Run `npm run stress-test` ([`examples/full-stress-test.js`](examples/full-stress-test.js)) for a before/after weight trace across a battery of positive/negative/severe shocks, repeated hostility, idle time passing, hardware latency, worn-path caching, and a group/bystander turn.
213
+ Run `npm run demo` for a full scripted conversation showing decay, hedonic adaptation, dopaminergic surprise, sensory overload, and a generated system prompt in action. Run `npm test` for the mechanic-level test suite. Run `npm run stress-test` ([`examples/full-stress-test.js`](examples/full-stress-test.js)) for a before/after weight trace across a battery of positive/negative/severe shocks, repeated hostility, idle time passing, hardware latency, worn-path caching, and a group/bystander turn. Run `npm run upgrade-round-mock` for the momentum/hysteresis, allostatic-load, wanting/liking, reconsolidation, attachment-style, graded-hijack, Vaillant-defense, expression-policy, resource-allocation, and circadian-coupling round, or `npm run lovehate-mock` for `LoveHateEngine`'s ambivalence, kindling, and rupture-and-repair cycle end to end.
193
214
 
194
215
  ### Real ML instead of heuristics: `TransformersProvider`
195
216
 
package/package.json CHANGED
@@ -1,62 +1,65 @@
1
1
  {
2
- "name": "totemheart",
3
- "version": "0.1.0",
4
- "description": "Totemheart is a modular emotional-simulation engine for AI: personality, mood, neurochemical dynamics, cognitive biases and social mechanics wired into a single pipeline that drives emotionally coherent, stateful behavior over a conversation.",
5
- "main": "src/index.js",
6
- "type": "module",
7
- "engines": {
8
- "node": ">=18"
9
- },
10
- "files": [
11
- "src"
12
- ],
13
- "keywords": [
14
- "totemheart",
15
- "library",
16
- "web",
17
- "intelligence",
18
- "ia",
19
- "emotion-engine",
20
- "personality",
21
- "robotic",
22
- "framework"
23
- ],
24
- "author": "Alejo Malia <alejomalia@gmail.com>",
25
- "license": "MIT",
26
- "publishConfig": {
27
- "access": "public",
28
- "registry": "https://registry.npmjs.org/"
29
- },
30
- "devDependencies": {
31
- "@typescript-eslint/eslint-plugin": "8.2.0",
32
- "@typescript-eslint/parser": "8.2.0",
33
- "eslint": "8.57.0",
34
- "eslint-plugin-align-assignments": "1.1.2",
35
- "eslint-plugin-align-import": "1.0.0",
36
- "eslint-plugin-canonical": "5.0.0",
37
- "eslint-plugin-html": "7.1.0",
38
- "eslint-plugin-import": "2.29.1",
39
- "eslint-plugin-jsdoc": "46.10.1",
40
- "eslint-plugin-json": "3.1.0",
41
- "eslint-plugin-jsonc": "2.13.0",
42
- "eslint-plugin-markdownlint": "0.5.0",
43
- "eslint-plugin-package-json": "0.12.2",
44
- "eslint-plugin-promise": "6.1.1",
45
- "eslint-plugin-yaml": "0.5.0",
46
- "typescript": "5.6.2",
47
- "vite": "5.4.4"
48
- },
49
- "extra": {
50
- "id": "totemheart",
51
- "productName": "Totemheart"
52
- },
53
- "scripts": {
54
- "demo": "node examples/demo.js",
55
- "verify": "node examples/verify-all-mechanisms.js",
56
- "stress-test": "node examples/full-stress-test.js",
57
- "personality-mock": "node examples/personality-mock.js",
58
- "rem-mock": "node examples/rem-conversation-mock.js",
59
- "exhaustive-audit": "node examples/exhaustive-audit-mock.js",
60
- "test": "node --test test/*.test.js"
61
- }
62
- }
2
+ "name": "totemheart",
3
+ "version": "0.1.2",
4
+ "description": "Totemheart is a modular emotional-simulation engine for AI: personality, mood, neurochemical dynamics, cognitive biases and social mechanics wired into a single pipeline that drives emotionally coherent, stateful behavior over a conversation.",
5
+ "main": "src/index.js",
6
+ "type": "module",
7
+ "engines": {
8
+ "node": ">=18"
9
+ },
10
+ "files": [
11
+ "src"
12
+ ],
13
+ "scripts": {
14
+ "demo": "node examples/demo.js",
15
+ "verify": "node examples/verify-all-mechanisms.js",
16
+ "stress-test": "node examples/full-stress-test.js",
17
+ "personality-mock": "node examples/personality-mock.js",
18
+ "rem-mock": "node examples/rem-conversation-mock.js",
19
+ "exhaustive-audit": "node examples/exhaustive-audit-mock.js",
20
+ "upgrade-round-mock": "node examples/upgrade-round-mock.js",
21
+ "lovehate-mock": "node examples/lovehate-mock.js",
22
+ "test": "node --test test/regression/*.test.js test/integration/*.test.js test/property/*.test.js"
23
+ },
24
+ "keywords": [
25
+ "totemheart",
26
+ "library",
27
+ "web",
28
+ "intelligence",
29
+ "ia",
30
+ "emotion-engine",
31
+ "personality",
32
+ "robotic",
33
+ "framework"
34
+ ],
35
+ "author": "Alejo Malia <alejomalia@gmail.com>",
36
+ "license": "MIT",
37
+ "publishConfig": {
38
+ "access": "public",
39
+ "registry": "https://registry.npmjs.org/"
40
+ },
41
+ "packageManager": "pnpm@9.7.0",
42
+ "devDependencies": {
43
+ "@typescript-eslint/eslint-plugin": "8.2.0",
44
+ "@typescript-eslint/parser": "8.2.0",
45
+ "eslint": "8.57.0",
46
+ "eslint-plugin-align-assignments": "1.1.2",
47
+ "eslint-plugin-align-import": "1.0.0",
48
+ "eslint-plugin-canonical": "5.0.0",
49
+ "eslint-plugin-html": "7.1.0",
50
+ "eslint-plugin-import": "2.29.1",
51
+ "eslint-plugin-jsdoc": "46.10.1",
52
+ "eslint-plugin-json": "3.1.0",
53
+ "eslint-plugin-jsonc": "2.13.0",
54
+ "eslint-plugin-markdownlint": "0.5.0",
55
+ "eslint-plugin-package-json": "0.12.2",
56
+ "eslint-plugin-promise": "6.1.1",
57
+ "eslint-plugin-yaml": "0.5.0",
58
+ "typescript": "5.6.2",
59
+ "vite": "5.4.4"
60
+ },
61
+ "extra": {
62
+ "id": "totemheart",
63
+ "productName": "Totemheart"
64
+ }
65
+ }