ROMFASTSQL/proxmox/lxc171-claude-agent/maria-whatsapp-bridge/README.md

# 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). Controlul (start/stop/restart,
documente, reindexare, sincronizare Google Drive) se face din **dashboard-ul
puntii Discord** (`../discord-bridge/dashboard/`), sectiunea "Maria — WhatsApp
+ RAG" — un singur panou comun pentru ambele punti de pe acest container, nu
un dashboard separat per serviciu.

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

../discord-bridge/dashboard/api.py -- panou comun; sectiunea Maria 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 |

## 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 puntii Discord si scaneaza codul QR din
# sectiunea "Maria — WhatsApp + RAG" -> cardul "Conectare WhatsApp"
```

## Dashboard (comun cu puntea Discord)

Nu exista un dashboard separat pentru Maria. Controlul se face din dashboard-ul
puntii Discord — vezi `../discord-bridge/README.md` pentru URL si autentificare
(`DASHBOARD_TOKEN` din `~/.claude-discord/env`, tunel SSH sau Tailscale la
`/claude`). Acolo, sectiunea "Maria — WhatsApp + RAG":
- start/stop/restart pentru puntea WhatsApp si consumer-ul RAG
- starea conexiunii WhatsApp si codul QR de asociere (cand nu e conectat)
- listare, adaugare si stergere documente din depozitul RAG
- reconstruire index manual, sau sincronizare Drive imediata
- ultimele linii din logurile fiecarui serviciu Maria (`whatsapp.log`/`rag.log`)

## Depozitul de documente

Fisiere `.txt`/`.md` in `~/.maria-bridge/documents/`. Se pot administra:
1. **manual din dashboard-ul comun** (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).