Skip to content

Commit f880b58

Browse files
ruanfluxruanflux
committed
Initial release: ChatRel v0.1.0
Apply 7 psychology frameworks (Sternberg, Knapp, ECR-R attachment, Gottman, Social Penetration, Critical Slowing, LIWC) to a chat history with a partner. Produces 5 interactive HTML reports + a memory book + a portal, all generated locally. Includes: - 5 hand-curated Chinese lexicons (depth, attachment, conflict, external threats, stopwords) grounded in source literature - 5 analyzers producing metrics JSON - 6 Plotly-based HTML renderers + portal - Telegram / WeChat / generic CSV+JSON adapters - Synthetic 90-day demo data generator (no real chat required) - Unified CLI: chatrel {sample, analyze, depth, attachment, conflict, external, memory, portal} - Docs: methodology.md, limitations.md, schema.md, lexicons.md - GitHub Actions CI (3 OS x 3 Python versions) - 3 smoke tests (all green) Privacy: .gitignore blocks chat data, decrypted DBs, and generated reports. No bundled decryption — links to external tools in docs.
0 parents  commit f880b58

44 files changed

Lines changed: 5049 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/test.yml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
name: Tests
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
test:
11+
runs-on: ${{ matrix.os }}
12+
strategy:
13+
fail-fast: false
14+
matrix:
15+
os: [ubuntu-latest, windows-latest, macos-latest]
16+
python-version: ["3.10", "3.11", "3.12"]
17+
18+
steps:
19+
- uses: actions/checkout@v4
20+
21+
- name: Set up Python ${{ matrix.python-version }}
22+
uses: actions/setup-python@v5
23+
with:
24+
python-version: ${{ matrix.python-version }}
25+
cache: pip
26+
27+
- name: Install ChatRel
28+
run: |
29+
python -m pip install --upgrade pip
30+
pip install -e ".[dev]"
31+
32+
- name: Run tests
33+
run: python -m pytest tests/ -v
34+
35+
- name: Smoke-test CLI
36+
shell: bash
37+
run: |
38+
chatrel sample --out /tmp/demo.json --days 60
39+
chatrel analyze /tmp/demo.json --out /tmp/out --no-html
40+
ls -la /tmp/out

‎.gitignore‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# ---- NEVER COMMIT CHAT DATA ----
2+
# Your own chat exports — keep these out of the repo at all costs.
3+
chat_*.json
4+
chats/
5+
*.msg.json
6+
*_chat.json
7+
my_chat.json
8+
private_chat.json
9+
10+
# Decrypted WeChat databases (if you use the wechat adapter)
11+
decrypted/
12+
xwechat_files/
13+
all_keys.json
14+
*.db
15+
*.db-shm
16+
*.db-wal
17+
*.kvdb*
18+
19+
# Generated per-couple outputs
20+
output/
21+
reports/
22+
metrics_*.json
23+
depth_metrics.json
24+
attachment_forecast.json
25+
conflict_events.json
26+
resilience_metrics.json
27+
memory_book_data.json
28+
bot_data.json
29+
*.html
30+
!docs/screenshots/*.html # synthetic-data demo pages are OK
31+
32+
# ---- Standard Python ----
33+
__pycache__/
34+
*.py[cod]
35+
*$py.class
36+
*.so
37+
*.egg
38+
*.egg-info/
39+
dist/
40+
build/
41+
.eggs/
42+
.pytest_cache/
43+
.coverage
44+
.coverage.*
45+
.tox/
46+
htmlcov/
47+
.mypy_cache/
48+
.ruff_cache/
49+
.hypothesis/
50+
51+
# Environments
52+
.env
53+
.venv
54+
venv/
55+
env/
56+
ENV/
57+
58+
# Editors
59+
.idea/
60+
.vscode/
61+
*.swp
62+
*.swo
63+
.DS_Store
64+
Thumbs.db
65+
66+
# Jupyter
67+
.ipynb_checkpoints/
68+
69+
# Plotly artifacts
70+
plotly_chrome/

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 ChatRel contributors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# ChatRel
2+
3+
**Apply 7 empirically-grounded psychology frameworks to your chat history with a partner. 100% local, privacy-preserving. Chinese + English.**
4+
5+
[中文 README](README.zh.md) · [Methodology](docs/methodology.md) · [Limitations](docs/limitations.md) · [Schema](docs/schema.md)
6+
7+
---
8+
9+
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 — in seven months of messaging your partner — and maps them onto the frameworks relationship scientists have actually studied for 40+ years:
10+
11+
| Framework | What it measures | Anchor citation |
12+
|---|---|---|
13+
| **Sternberg Triangular** | Intimacy × Passion × Commitment as three separable axes | Sternberg (1986) |
14+
| **Knapp Stages** | 10-stage model of relational development (Initiating → Bonding, then Differentiating → Terminating) | Knapp (1978) |
15+
| **ECR-R Attachment** | Anxiety × Avoidance dimensions, mapped to Bartholomew 4-category types | Fraley, Waller & Brennan (2000); Bartholomew & Horowitz (1991) |
16+
| **Gottman 5:1 + Four Horsemen** | Positive-to-negative interaction ratio; criticism/contempt/defensiveness/stonewalling density | Gottman (1994) |
17+
| **Social Penetration** | Self-disclosure depth layered from shallow → core | Altman & Taylor (1973) |
18+
| **Critical Slowing (EWS)** | Rising variance + AR(1) as early-warning for regime shifts | Scheffer et al. (2009) |
19+
| **LIWC (Chinese proxy)** | Function-word / cognitive / affective markers | Pennebaker et al. |
20+
21+
**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.
22+
23+
## Screenshots
24+
25+
<!-- screenshots go in docs/screenshots/; commit ones generated from synthetic data only -->
26+
27+
`docs/screenshots/` contains demo images generated from the synthetic dataset shipped in `sample_data/`.
28+
29+
## Install
30+
31+
```bash
32+
git clone https://github.com/marycollins6715569-alt/chatrel.git
33+
cd chatrel
34+
pip install -e .
35+
```
36+
37+
Requires Python 3.10+. Dependencies: `jieba`, `snownlp`, `pandas`, `numpy`, `plotly`.
38+
39+
## Demo (no data required)
40+
41+
```bash
42+
chatrel sample --out sample_data/synthetic_couple.json
43+
chatrel analyze sample_data/synthetic_couple.json --out ./output
44+
open ./output/index.html # or start on Windows
45+
```
46+
47+
This 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.
48+
49+
## Real data
50+
51+
ChatRel reads a canonical chat JSON (see [docs/schema.md](docs/schema.md)):
52+
53+
```json
54+
{
55+
"me_name": "Alex",
56+
"partner_name": "Sam",
57+
"messages": [
58+
{"ts": 1700000000, "role": "me", "text": "hi", "type": "text"},
59+
{"ts": 1700000010, "role": "partner", "text": "hey!"}
60+
]
61+
}
62+
```
63+
64+
### Adapters
65+
66+
* **Telegram**: export from Telegram Desktop → Settings → Advanced → Export Telegram data → JSON, then
67+
```bash
68+
python -m chatrel.adapters.telegram result.json --out chat.json
69+
```
70+
* **WeChat**: ChatRel does **not** bundle WeChat decryption. See [`src/chatrel/adapters/wechat.py`](src/chatrel/adapters/wechat.py) — it points you to external tools and provides a helper to consume their output.
71+
* **Generic CSV / JSON**: `python -m chatrel.adapters.generic path.csv --out chat.json` — works for any `ts,role,text` dump.
72+
73+
Write your own adapter: it only needs to return a `chatrel.schema.Chat`.
74+
75+
## CLI
76+
77+
```bash
78+
chatrel sample # Generate synthetic demo chat
79+
chatrel analyze chat.json --out ./output
80+
# Run everything + portal index.html
81+
chatrel depth chat.json # Sternberg + Knapp + IDS only
82+
chatrel attachment chat.json # ECR-R + Gottman + 12-week forecast
83+
chatrel conflict chat.json # Conflict-repair events
84+
chatrel external chat.json # Poaching / resilience analysis
85+
chatrel memory chat.json # Auto-curated memory book
86+
chatrel portal --out ./output # Rebuild index from existing metrics
87+
```
88+
89+
All subcommands accept `--out` (defaults to `./output`) and `--no-html` (metrics only).
90+
91+
## What you get
92+
93+
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:
94+
95+
| File | Content |
96+
|---|---|
97+
| `depth_metrics.json` + `depth_report.html` | Weekly signal time series · Sternberg triad scores · Knapp phase anchors · composite Intimacy Depth Score (IDS) · milestones · private lexicon |
98+
| `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 |
99+
| `conflict_events.json` + `conflict_report.html` | Detected conflict windows with initiator/peak/first-apology/recovery · monthly trend · repair-pattern stats |
100+
| `resilience_metrics.json` + `resilience_report.html` | External-threat exposure · exclusivity/trust/we-ness density · 2 h response style · composite Resilience Index · joint stress coping |
101+
| `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 |
102+
| `index.html` | Portal linking all of the above |
103+
104+
## Privacy
105+
106+
**ChatRel processes everything locally and makes zero network calls.**
107+
108+
* Your chat JSON never leaves the machine.
109+
* 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`).
110+
* `.gitignore` blocks accidental commits of chat data and generated reports. Review it before pushing.
111+
* The synthetic sample is the only bundled demo dataset — never commit real data.
112+
113+
## Ethics
114+
115+
You're analyzing a real person who hasn't read your lexicon. A few constraints that ChatRel bakes in but cannot enforce:
116+
117+
* The tool produces **proxy signals**, not diagnoses. Do not tell someone they "are" Anxious-Preoccupied.
118+
* Attachment "types" are dimensional, contextual, and change with safety. The 2D scatter is a starting point, not a label.
119+
* Forecasts are damped linear extrapolation with mean reversion, **not** probabilistic predictions. Do not tell someone "we'll break up in six weeks."
120+
* If you decide to discuss findings with your partner, discuss the **patterns** (who apologizes more, when rituals dip), not the scores.
121+
122+
## Contributing
123+
124+
* New lexicons (English, Japanese, Spanish, …) are very welcome — open an issue or PR.
125+
* New adapters (WhatsApp, iMessage, Discord, …) likewise.
126+
* Eval data with expert-annotated ground truth would substantially improve validation — we'd love to collaborate.
127+
128+
## License
129+
130+
MIT © ChatRel contributors.
131+
132+
## Acknowledgements
133+
134+
Built on top of: [jieba](https://github.com/fxsjy/jieba), [SnowNLP](https://github.com/isnowfy/snownlp), [Plotly](https://plotly.com/python/). The psychology frameworks are cited inline and in [`docs/methodology.md`](docs/methodology.md).

0 commit comments

Comments
 (0)