Apply 7 empirically-grounded psychology frameworks to your chat history with a partner. 100% local · privacy-preserving · Chinese + English.
中文 README · Methodology · Limitations · Schema · Changelog
Most chat analyzers give you a word cloud, a sentiment line, and a heatmap. ChatRel does the opposite: it takes the dyadic interaction signals you already generated — seven months of messages with your partner — and maps them onto the frameworks relationship scientists have actually studied for 40+ years:
| Framework | What it measures | Anchor citation |
|---|---|---|
| Sternberg Triangular | Intimacy × Passion × Commitment as three separable axes | Sternberg (1986) |
| Knapp Stages | 10-stage model of relational development (Initiating → Bonding, then Differentiating → Terminating) | Knapp (1978) |
| ECR-R Attachment | Anxiety × Avoidance dimensions, mapped to Bartholomew 4-category types | Fraley, Waller & Brennan (2000); Bartholomew & Horowitz (1991) |
| Gottman 5:1 + Four Horsemen | Positive-to-negative interaction ratio; criticism/contempt/defensiveness/stonewalling density | Gottman (1994) |
| Social Penetration | Self-disclosure depth layered from shallow → core | Altman & Taylor (1973) |
| Critical Slowing (EWS) | Rising variance + AR(1) as early-warning for regime shifts | Scheffer et al. (2009) |
| LIWC (Chinese proxy) | Function-word / cognitive / affective markers | Pennebaker et al. |
Output is seven linked interactive HTML reports (Plotly-based), one per framework plus a curated memory book and a portal index. Everything runs on your machine. No data is ever sent anywhere.
All images below are generated from the synthetic demo dataset (sample_data/synthetic_couple.json) that ships with the repo — no real chat data.
| Depth / Sternberg / Knapp | Attachment & 12-week forecast |
|---|---|
 |
 |
| Conflict-repair events | External-threat resilience |
 |
 |
| Auto-curated memory book | Portal |
 |
 |
git clone https://github.com/ruanflux/chatrel.git
cd chatrel
pip install -e .Requires Python 3.10+. Dependencies: jieba, snownlp, pandas, numpy, plotly.
chatrel sample --out sample_data/synthetic_couple.json
chatrel analyze sample_data/synthetic_couple.json --out ./output
open ./output/index.html # or start on WindowsThis generates a ~2 000-message fictional 90-day couple chat containing every signal the analyzers look for, then runs the full pipeline. Everything in output/ is derived from fake data you can freely screenshot.
ChatRel reads a canonical chat JSON (see docs/schema.md):
{
"me_name": "Alex",
"partner_name": "Sam",
"messages": [
{"ts": 1700000000, "role": "me", "text": "hi", "type": "text"},
{"ts": 1700000010, "role": "partner", "text": "hey!"}
]
}- Telegram: export from Telegram Desktop → Settings → Advanced → Export Telegram data → JSON, then
python -m chatrel.adapters.telegram result.json --out chat.json
- WeChat: ChatRel does not bundle WeChat decryption. See
src/chatrel/adapters/wechat.py— it points you to external tools and provides a helper to consume their output. - Generic CSV / JSON:
python -m chatrel.adapters.generic path.csv --out chat.json— works for anyts,role,textdump.
Write your own adapter: it only needs to return a chatrel.schema.Chat.
chatrel sample # Generate synthetic demo chat
chatrel analyze chat.json --out ./output
# Run everything + portal index.html
chatrel depth chat.json # Sternberg + Knapp + IDS only
chatrel attachment chat.json # ECR-R + Gottman + 12-week forecast
chatrel conflict chat.json # Conflict-repair events
chatrel external chat.json # Poaching / resilience analysis
chatrel memory chat.json # Auto-curated memory book
chatrel portal --out ./output # Rebuild index from existing metricsAll subcommands accept --out (defaults to ./output) and --no-html (metrics only).
Each analyzer writes a metrics_*.json under the output directory; a corresponding HTML renderer turns that JSON into an interactive report. The seven outputs are:
| File | Content |
|---|---|
depth_metrics.json + depth_report.html |
Weekly signal time series · Sternberg triad scores · Knapp phase anchors · composite Intimacy Depth Score (IDS) · milestones · private lexicon |
attachment_forecast.json + attachment_forecast_report.html |
ECR-R scores · Bartholomew classification · couple-dynamic type · 12-week 3-scenario forecast · Gottman weekly P:N · four horsemen · critical slowing EWS |
conflict_events.json + conflict_report.html |
Detected conflict windows with initiator/peak/first-apology/recovery · monthly trend · repair-pattern stats |
resilience_metrics.json + resilience_report.html |
External-threat exposure · exclusivity/trust/we-ness density · 2 h response style · composite Resilience Index · joint stress coping |
memory_book_data.json + memory_book.html |
10 chapters of auto-curated moments: firsts / sweetest / deepest / private lexicon / top days / role-specific best, with client-side search |
index.html |
Portal linking all of the above |
ChatRel processes everything locally and makes zero network calls.
- Your chat JSON never leaves the machine.
- The generated reports are standalone HTML; Plotly is loaded from a CDN at view time (you can swap to local by editing
renderers/common.py). .gitignoreblocks accidental commits of chat data and generated reports. Review it before pushing.- The synthetic sample is the only bundled demo dataset — never commit real data.
You're analyzing a real person who hasn't read your lexicon. A few constraints that ChatRel bakes in but cannot enforce:
- The tool produces proxy signals, not diagnoses. Do not tell someone they "are" Anxious-Preoccupied.
- Attachment "types" are dimensional, contextual, and change with safety. The 2D scatter is a starting point, not a label.
- Forecasts are damped linear extrapolation with mean reversion, not probabilistic predictions. Do not tell someone "we'll break up in six weeks."
- If you decide to discuss findings with your partner, discuss the patterns (who apologizes more, when rituals dip), not the scores.
- New lexicons (English, Japanese, Spanish, …) are very welcome — open an issue or PR.
- New adapters (WhatsApp, iMessage, Discord, …) likewise.
- Eval data with expert-annotated ground truth would substantially improve validation — we'd love to collaborate.
MIT © ChatRel contributors.
Built on top of: jieba, SnowNLP, Plotly. The psychology frameworks are cited inline and in docs/methodology.md.
