Add model card README

README.md

@@ -0,0 +1,143 @@
+---
+language:
+- en
+license: apache-2.0
+tags:
+- emotion-detection
+- emotional-intelligence
+- mental-health
+- wellbeing
+- psychology
+- text-classification
+- multi-label-classification
+- deberta
+- distillation
+pipeline_tag: text-classification
+library_name: resonance-layer
+---
+
+# Resonance — Emotional Intelligence Layer for LLMs
+
+**resonance-layer** sits between your users and your LLM. It reads the emotion behind what someone writes and injects that context before the LLM responds.
+
+```python
+from resonance import Resonance
+
+r = Resonance(user_id="your-user-id")
+context = r.process("I've been so anxious about this")
+llm.chat(system=context.to_prompt(), message=message)
+```
+
+That's it. The LLM now knows the emotional state, psychological signals, and longitudinal pattern for this user — before it says a word.
+
+---
+
+## The problem this solves
+
+Text doesn't carry emotion. When someone types *"I'm fine"* or *"whatever, doesn't matter"* — the LLM sees words. It has no idea if that person is exhausted, shutting down, or genuinely okay.
+
+Resonance gives it that context, continuously, per user, without any extra effort from the developer or the user.
+
+---
+
+## What this model detects
+
+This is a custom 86M parameter student model distilled from three specialist teachers, trained on real human emotional expression across 29 datasets (~740K rows).
+
+**18 output heads across 4 groups:**
+
+| Group | Heads |
+|---|---|
+| Core | Primary emotion (7-class), VAD continuous, CNN local patterns, confidence calibration |
+| Frameworks | Secondary emotion (21-class TONE), PERMA ×5, Window of Tolerance, reappraisal/suppression, Wise Mind |
+| Ethics | Crisis detection, alexithymia screening |
+| SDT | Autonomy, competence, relatedness |
+
+All framework scores are **continuous outputs**, not binary flags — grounded in the clinical research each framework comes from.
+
+**What makes it different from general emotion models:**
+
+The three specialist teachers each cover a distinct psychological blind spot:
+- **T1 (DeBERTa-v3-large + CNN):** shame/guilt separation with PoliGuilt typing — the distinction most models collapse or miss entirely
+- **T2 (XLNet-large):** anger and complex social context
+- **T3 (ELECTRA-large):** fear, PERMA wellbeing, and efficiency
+
+---
+
+## Installation
+
+```bash
+pip install resonance-layer
+```
+
+Weights download automatically on first use (~700MB). Fully local after that — no API call, no data leaving your infrastructure.
+
+---
+
+## Quick start
+
+```python
+from resonance import Resonance
+
+r = Resonance(user_id="alice")
+result = r.process("I keep second-guessing everything I do")
+
+print(result.primary_emotion)        # e.g. "anxiety"
+print(result.vad)                    # valence, arousal, dominance
+print(result.perma)                  # PERMA scores across 5 dimensions
+print(result.crisis_detected)        # always check this first
+print(result.to_prompt())            # ready-made system prompt context
+```
+
+**If `crisis_detected` is True, surface a crisis resource immediately.** This is non-negotiable — it's in the ethics documentation and built into the API contract.
+
+---
+
+## Longitudinal learning
+
+Resonance learns in two ways per user:
+
+1. **Passive** — every call to `r.process()` updates the user's local profile. Patterns, suppression signals, regulation style — all accumulate silently. The LLM gets richer context with every conversation.
+2. **Active** — explicit corrections (e.g. a user tapping a different emotion chip) feed directly into per-user reinforcement and adjust future detections for them specifically.
+
+Both paths are local. No opt-in required.
+
+---
+
+## Upgrading from v1
+
+```bash
+pip install --upgrade resonance-layer
+```
+
+No API changes. Drop-in replacement.
+
+---
+
+## Honest limitations
+
+- Shame F1 is the lowest of any class — it's the hardest psychological distinction to learn
+- Sadness is weaker than anger, fear, and joy
+- Some high-arousal distress returns as surprise
+- All gaps are documented in the repo
+
+---
+
+## Architecture
+
+- **Student:** 86M parameter DeBERTa-v3-base, 18 active heads
+- **Teachers:** DeBERTa-v3-large+CNN (T1), XLNet-large (T2), ELECTRA-large (T3)
+- **Distillation:** Multi-teacher knowledge distillation with per-head weighting, mutual information maximisation, born-again networks, uncertainty-aware loss
+- **Training data:** 29 datasets, ~740K rows, 7 locked dataset rules (commercial licence, institutional/peer-reviewed, real human expression, framework-mapped, not too narrow, no gated access, no severe class imbalance)
+
+---
+
+## Links
+
+- **PyPI:** [resonance-layer](https://pypi.org/project/resonance-layer/)
+- **GitHub:** [wpferrell/Resonance](https://github.com/wpferrell/Resonance)
+- **Docs & landing page:** [resonance-layer.com](https://resonance-layer.com)
+
+---
+
+*Named after Jody. She walks into a room and just knows. That's the standard.*