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), 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).