Add Maria WhatsApp+RAG bridge as a service (LXC 171)
Move the /tmp prototype (Baileys bridge + RAG consumer) into git as a proper sibling project to discord-bridge/: own systemd --user units (whatsapp bridge, rag consumer, dashboard, periodic Drive sync timer), a filesystem document store with a stdlib control dashboard (start/ stop/restart, document CRUD, reindex, Google Drive sync via rclone), and an idempotent ops/install.sh following the same conventions. Co-Authored-By: Claude Agent <noreply@anthropic.com>
This commit is contained in:
Claude Agent
140
proxmox/lxc171-claude-agent/maria-whatsapp-bridge/README.md
Normal file
140
proxmox/lxc171-claude-agent/maria-whatsapp-bridge/README.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# Punte WhatsApp + RAG pentru Maria (LXC 171)
|
||||
|
||||
Bot de suport ROA pe WhatsApp: puntea WhatsApp (Baileys) primeste mesajele,
|
||||
consumer-ul RAG raspunde folosind DOAR informatiile dintr-un depozit de
|
||||
documente indexat cu embeddings (Ollama), iar un dashboard web controleaza
|
||||
totul (start/stop/restart, documente, reindexare, sincronizare Google Drive).
|
||||
|
||||
Continua prototipul descris in
|
||||
`claude-agent/docs/maria-whatsapp-rag-prototype.md` (construit initial in
|
||||
`/tmp/maria-bridge/`) — aici e mutat in git, ca serviciu persistent.
|
||||
|
||||
Nu confunda cu:
|
||||
- **Maria pe Flowise** (`vfp_roaauto/COMUN/utile/chatbot/`) — chatbot web separat.
|
||||
- **Echo / `echo-whatsapp-bridge.service`** (LXC 110 moltbot) — alt bot, alta punte.
|
||||
- **Punte Discord -> Claude Code** (`discord-bridge/`, acelasi container) — alt
|
||||
proiect, alt scop (comanda Claude Code de pe Discord, nu suport RAG).
|
||||
|
||||
## Arhitectura
|
||||
|
||||
```
|
||||
WhatsApp (self-chat, sau numarul legat)
|
||||
|
|
||||
v
|
||||
whatsapp/index.js (Baileys) -- API HTTP :8099 (/status /send /messages /react /qr)
|
||||
|
|
||||
v
|
||||
rag/consumer.py -- polling la /messages, RAG stateless (FARA memorie intre mesaje)
|
||||
| vezi docs/maria-whatsapp-rag-prototype.md pentru motiv
|
||||
v
|
||||
rag/store.py -- depozit documente (.txt/.md) in ~/.maria-bridge/documents/
|
||||
rag/indexer.py -- chunking + embeddings Ollama -> rag_index.json
|
||||
rag/sync.py -- rclone pull din Google Drive + reindexare conditionata
|
||||
|
||||
dashboard/api.py -- panou web (stdlib, fara dependinte), :18792
|
||||
controleaza maria-whatsapp.service + maria-rag.service,
|
||||
gestioneaza documentele si declanseaza sincronizare/reindexare
|
||||
```
|
||||
|
||||
Servicii `systemctl --user` (vezi `ops/`):
|
||||
|
||||
| Unitate | Ce face |
|
||||
|---|---|
|
||||
| `maria-whatsapp.service` | Puntea Baileys (Node), port 8099 |
|
||||
| `maria-rag.service` | Consumer RAG (Python), polling + raspunsuri |
|
||||
| `maria-sync.service` + `.timer` | Sincronizare Drive + reindexare, la 10 min |
|
||||
| `maria-dashboard.service` | Panou de control, port 18792 |
|
||||
|
||||
## Instalare
|
||||
|
||||
```bash
|
||||
cd maria-whatsapp-bridge
|
||||
./ops/install.sh # creeaza ~/.maria-bridge/, venv, npm install, symlink-uri unit
|
||||
```
|
||||
|
||||
Completeaza manual `~/.maria-bridge/env` (copiat din `ops/env.example` la prima
|
||||
rulare): cel putin `LLM_URL` (backend-ul de chat) si, daca vrei sincronizare
|
||||
automata cu Drive, `DRIVE_REMOTE`.
|
||||
|
||||
Bridge-ul WhatsApp NU porneste automat la instalare — cere scanarea unui cod QR
|
||||
(actiune manuala, o singura data):
|
||||
|
||||
```bash
|
||||
./ops/install.sh --start
|
||||
# apoi deschide dashboard-ul (tunel SSH catre 127.0.0.1:18792) si scaneaza
|
||||
# codul QR din cardul "Conectare WhatsApp"
|
||||
```
|
||||
|
||||
## Dashboard
|
||||
|
||||
```bash
|
||||
ssh -L 18792:127.0.0.1:18792 -N claude@10.0.20.171 &
|
||||
# apoi: http://localhost:18792
|
||||
```
|
||||
|
||||
Autentificare cu `DASHBOARD_TOKEN` din `~/.maria-bridge/env` (generat automat
|
||||
de `install.sh`). `DASHBOARD_AUTH=off` in env dezactiveaza login-ul — foloseste
|
||||
DOAR daca panoul ramane strict pe 127.0.0.1/tunel SSH.
|
||||
|
||||
Ce poti face din panou:
|
||||
- start/stop/restart pentru puntea WhatsApp si consumer-ul RAG
|
||||
- vezi starea conexiunii WhatsApp si codul QR de asociere (cand nu e conectat)
|
||||
- listezi, adaugi si stergi documente din depozitul RAG
|
||||
- reconstruiesti indexul manual, sau declansezi o sincronizare Drive imediata
|
||||
- citesti ultimele linii din logurile fiecarui serviciu
|
||||
|
||||
## Depozitul de documente
|
||||
|
||||
Fisiere `.txt`/`.md` in `~/.maria-bridge/documents/`. Se pot administra:
|
||||
1. **manual din dashboard** (adaugare/stergere text, reindexare automata la salvare);
|
||||
2. **prin sincronizare Google Drive** — vezi mai jos.
|
||||
|
||||
## Sincronizare cu Google Drive
|
||||
|
||||
Sursa: dosarul `D:\GoogleDrive\romfast\document_store` de pe Windows (Google
|
||||
Drive Desktop). Containerul e headless, deci sincronizarea foloseste
|
||||
**rclone cu un cont de serviciu** — nu OAuth interactiv in browser.
|
||||
|
||||
Pasi (o singura data):
|
||||
|
||||
1. **Instaleaza rclone** pe container: `sudo apt-get install -y rclone`.
|
||||
2. **Creeaza un cont de serviciu Google** cu acces la Drive API (Google Cloud
|
||||
Console -> IAM -> Service Accounts -> Create -> descarca cheia JSON).
|
||||
3. **Partajeaza folderul** `document_store` din Google Drive cu adresa de email
|
||||
a contului de serviciu (click dreapta pe folder -> Share), exact cum ai
|
||||
partaja cu o persoana. Fara acest pas, contul de serviciu nu vede nimic.
|
||||
4. Pune cheia JSON pe container, ex. `~/.maria-bridge/gdrive-service-account.json`
|
||||
(0600).
|
||||
5. Configureaza remote-ul rclone (`rclone config`, fara sesiune interactiva de
|
||||
browser cu tip `service_account_file`):
|
||||
```
|
||||
rclone config create gdrive drive \
|
||||
scope=drive.readonly \
|
||||
service_account_file=/home/claude/.maria-bridge/gdrive-service-account.json
|
||||
```
|
||||
6. Gaseste ID-ul folderului `document_store` (din URL-ul Drive) si testeaza:
|
||||
```
|
||||
rclone lsf gdrive: --drive-root-folder-id=<FOLDER_ID>
|
||||
```
|
||||
Sau, mai simplu, foloseste calea prin nume daca folderul e in "My Drive" al
|
||||
contului care a facut share (rclone urmareste shared-with-me cu
|
||||
`--drive-shared-with-me` daca e nevoie).
|
||||
7. Pune tinta gasita in `~/.maria-bridge/env`:
|
||||
```
|
||||
DRIVE_REMOTE=gdrive:romfast/document_store
|
||||
```
|
||||
8. Testeaza manual: `systemctl --user start maria-sync.service` apoi
|
||||
`journalctl --user -u maria-sync -n 50`, sau butonul „sincronizeaza din Drive
|
||||
acum" din dashboard.
|
||||
|
||||
Dupa configurare, `maria-sync.timer` trage la fiecare 10 minute; reindexarea
|
||||
ruleaza DOAR daca s-a schimbat efectiv ceva in depozit (amprenta pe nume +
|
||||
mtime + marime, vezi `rag/sync.py`), ca sa nu reface embeddings degeaba.
|
||||
|
||||
## Context conversational
|
||||
|
||||
`rag/consumer.py` nu retine memorie intre mesaje — fiecare intrebare e o
|
||||
interogare RAG independenta (system prompt + top-K chunk-uri + intrebare).
|
||||
Vezi `claude-agent/docs/maria-whatsapp-rag-prototype.md` pentru motiv si
|
||||
comparatie cu celelalte punti (Discord: context nelimitat + `/new`; Maria pe
|
||||
Flowise: fereastra fixa de 5 schimburi).
|
||||
Reference in New Issue
Block a user