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

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):

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