merge: Integradas alteracoes remotas do HF (learning v1, warmup e docs)

.dockerignore

@@ -0,0 +1,6 @@
+venv
+__pycache__
+.git
+.env
+*.pyc
+.pytest_cache

.env.example

@@ -0,0 +1,21 @@
+# Secrets do Space Plenitude
+API_AUTH_TOKEN=
+AI_PROVIDER=auto
+AI_MODEL=
+
+OPENROUTER_API_KEY=
+GROQ_API_KEY=
+DEEPSEEK_API_KEY=
+MISTRAL_API_KEY=
+GEMINI_API_KEY=
+
+# Llama local (ZeroGPU) — opcional; sem isto usa só as APIs externas
+# Modelo gated (ex. Meta Llama) exige licença aceite + HF_TOKEN com acesso
+LOCAL_MODEL_ID=NousResearch/Meta-Llama-3-8B-Instruct
+LORA_ADAPTER_PATH=
+HF_TOKEN=
+
+CATALOG_API_URL=
+PRICES_API_URL=
+HOURS_API_URL=
+BUSINESS_API_TOKEN=

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,13 @@
+venv/
+__pycache__/
+*.py[cod]
+.env
+.env.local
+data/
+conversas.jsonl
+.pytest_cache/
+.mypy_cache/
+*.egg-info/
+.DS_Store
+.idea/
+.vscode/

Dockerfile

@@ -0,0 +1,27 @@
+FROM python:3.11-slim
+
+RUN useradd -m -u 1000 user
+WORKDIR /app
+
+COPY --chown=user ./requirements.txt requirements.txt
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+COPY --chown=user . /app
+
+# Pesos do Llama local: NÃO embutidos na imagem (8B em bf16 ≈ 16GB).
+# São baixados no arranque para o cache do disco (ver warmup em app.py)
+# e reutilizados nos arranques seguintes. Para pré-baixar na build
+# (opt-in, só com disco e licença garantidos), descommentar:
+# ARG LOCAL_MODEL_ID=NousResearch/Meta-Llama-3-8B-Instruct
+# ARG HF_TOKEN=""
+# RUN HF_TOKEN=$HF_TOKEN python -c "from transformers import AutoTokenizer, AutoModelForCausalLM; AutoTokenizer.from_pretrained('$LOCAL_MODEL_ID'); AutoModelForCausalLM.from_pretrained('$LOCAL_MODEL_ID', torch_dtype='auto')"
+# Nota: repo gated (ex. Meta Llama) exige licença aceite + HF_TOKEN com acesso.
+
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    PORT=7860
+
+EXPOSE 7860
+
+CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port ${PORT:-7860} --workers 1 --proxy-headers"]

README.md

@@ -1,10 +1,59 @@
----
+---
 title: Plenitude Negra Plena
 emoji: 🧁
 colorFrom: purple
 colorTo: pink
 sdk: gradio
 sdk_version: "5.6.0"
+python_version: "3.12"
 app_file: app.py
 pinned: false
 ---
+
+# Plenitude — cérebro da Negra Plena
+
+API FastAPI da assistente **Plenitude**, atendimento da pastelaria **Negra Plena**.  
+Criada pela **Softedge**. O conector WhatsApp (Node, Railway) envia `POST /api/escutar` e recebe `{ "texto": "..." }`.
+
+`app.py` serve a API (`main.py`) com uvicorn na porta 7860 e mostra uma interface Gradio de teste em `/`.
+
+## GPU ativada
+A anotação @spaces.GPU está configurada para suportar inferência rápida.
+
+## Hierarquia de provedores (fallback)
+
+1. Llama local (ZeroGPU) → 2. OpenRouter → 3. Groq → 4. DeepSeek → 5. Mistral → 6. Gemini.
+Cada nível que falha cai para o seguinte; `AI_PROVIDER` força um específico primeiro.
+O Llama local (`local_llm.py`, `NousResearch/Meta-Llama-3-8B-Instruct` por defeito,
+LoRA opcional via `LORA_ADAPTER_PATH`) é carregado uma vez e corre no `@spaces.GPU`;
+se o download falhar (ex. repo gated sem licença + `HF_TOKEN`), cai para as APIs externas.
+Vars: `LOCAL_MODEL_ID`, `LORA_ADAPTER_PATH`, `HF_TOKEN`.
+
+### Download dos pesos (onde e como confirmar)
+
+- Os pesos **não** vão embutidos na imagem Docker (8B em bf16 ≈ 16GB).
+- No arranque, `app.py` faz o pré-aquecimento: baixa uma vez para o cache
+  do disco (`~/.cache/huggingface`) e os arranques seguintes reutilizam.
+- Confirme no log do container: `[llama] a carregar ...` → `[llama] modelo pronto.`
+  Se aparecer `[llama] indisponível (...)`, leia o motivo (ex. repo gated).
+- Modelo gated (ex. Meta Llama): aceite a licença na página do modelo no Hub
+  e defina o Secret `HF_TOKEN` com uma conta que tenha acesso. Sem isto,
+  o Llama fica inativo e o bot responde via APIs externas (Groq etc.).
+- Para pré-baixar na build Docker (opt-in), ver bloco comentado no `Dockerfile`.
+
+## Aprendizado (v1, log local JSONL)
+
+- Cada resposta do `/escutar` é registada em `data/conversas.jsonl` e devolve um `mensagem_id`.
+- Avalie com `POST /api/feedback` (`{"mensagem_id": "...", "nota": "boa"|"ma"}`);
+  casos `"ma"` nunca voltam como exemplo, `"boa"` tem prioridade.
+- Perguntas parecidas com casos anteriores entram no prompt como exemplos (few-shot).
+- O ficheiro contém números de clientes: nunca vai para git e perde-se em factory rebuild.
+- Vars: `DATA_DIR` (`./data`), `LEARNING_MAX_LINHAS` (2000), `LEARNING_TOP_K` (2).
+
+## Endpoints
+
+- `GET /` — interface Gradio de teste
+- `GET /health` e `GET /api/health`
+- `POST /api/escutar` ou `POST /escutar`
+- `POST /api/feedback` ou `POST /feedback`
+- `GET /docs` — OpenAPI

ai_engine.py

@@ -1,20 +1,38 @@
 import requests
+import uuid
 from config import Config
 from memory import MemoryManager
 from catalog import CatalogService
+from learning import LearningStore
 
 class AIEngine:
     def __init__(self):
         self.memory = MemoryManager(max_history=8)
         self.catalog = CatalogService()
+        self.learning = LearningStore()
 
     def generate_reply(self, numero_crm: str, texto_cliente: str, nome_cliente: str) -> str:
+        resposta, _ = self._responder(numero_crm, texto_cliente, nome_cliente, registar=False)
+        return resposta
+
+    def responder(self, numero_crm: str, texto_cliente: str, nome_cliente: str) -> tuple:
+        """Igual a generate_reply mas regista a troca no aprendizado e devolve o id."""
+        return self._responder(numero_crm, texto_cliente, nome_cliente, registar=True)
+
+    def _responder(self, numero_crm: str, texto_cliente: str, nome_cliente: str,
+                   registar: bool) -> tuple:
+        mensagem_id = uuid.uuid4().hex[:12]
         historico = self.memory.get_context(numero_crm)
         dados_negocio = self.catalog.get_context()
         system = Config.SYSTEM_PROMPT
         if dados_negocio:
             system += f"\n\nDADOS ATUAIS DO NEGOCIO:\n{dados_negocio}"
 
+        user_text = texto_cliente.strip() or "(o cliente enviou uma mensagem sem texto)"
+        exemplos = self.learning.format_examples(user_text)
+        if exemplos:
+            system += f"\n\n{exemplos}"
+
         user_text = texto_cliente.strip() or "(o cliente enviou uma mensagem sem texto)"
         mensagens = [
             {"role": "system", "content": system},
@@ -39,6 +57,7 @@ class AIEngine:
 
         resposta = None
         erro_final = None
+        provedor_ok = ""
 
         for provider in ordem_provedores:
             try:
@@ -49,36 +68,44 @@ class AIEngine:
                 if provider == "mistral" and not Config.MISTRAL_API_KEY: continue
                 if provider == "gemini" and not Config.GEMINI_API_KEY: continue
                 
-                print(f"🔄 A tentar gerar resposta usando: {provider}...")
+                print(f"[hierarchy] A tentar gerar resposta usando: {provider}...", flush=True)
                 
                 if provider == "local_llama":
-                    from local_llm import LocalLlamaEngine
-                    engine_local = LocalLlamaEngine.get_instance()
-                    resposta = engine_local.generate(mensagens)
+                    from local_llm import generate_local
+                    resposta = generate_local(mensagens)
                 elif provider == "gemini":
                     resposta = self._call_gemini(system, mensagens[1]["content"])
                 else:
                     resposta = self._call_openai_compatible(provider, mensagens)
                 
                 if resposta:
-                    print(f"✅ Sucesso com {provider}!")
+                    print(f"[hierarchy] Sucesso com {provider}!", flush=True)
+                    provedor_ok = provider
                     break
 
             except Exception as exc:
-                print(f"❌ Falha critica no provedor {provider}: {exc}")
+                print(f"[hierarchy] Falha no provedor {provider}: {exc}", flush=True)
                 erro_final = exc
                 continue # Se falhou, a hierarquia ignora o erro e avanca para o proximo!
 
         if not resposta:
-            print(f"❌ TODOS os provedores da hierarquia falharam. Erro fatal: {erro_final}")
+            print(f"[hierarchy] TODOS os provedores falharam. Erro final: {erro_final}", flush=True)
             return (
                 "Peco desculpa, estou com uma instabilidade tecnica no sistema. "
-                "Pode repetir a sua mensagem daqui a instantes?"
+                "Pode repetir a sua mensagem daqui a instantes?",
+                mensagem_id,
             )
 
         self.memory.add_message(numero_crm, "user", user_text)
         self.memory.add_message(numero_crm, "model", resposta)
-        return resposta
+        if registar:
+            modelo = Config.LOCAL_MODEL_ID if provedor_ok == "local_llama" else Config.get_model(provedor_ok)
+            self.learning.log_exchange(
+                numero_crm, user_text, resposta,
+                provedor=provedor_ok, modelo=modelo,
+                mensagem_id=mensagem_id,
+            )
+        return resposta, mensagem_id
 
     def _call_openai_compatible(self, provider: str, messages: list) -> str:
         url, headers = self._provider_endpoint(provider)

app.py

@@ -1,56 +1,81 @@
-import gradio as gr
-import spaces
-from fastapi import FastAPI, Depends, Header, HTTPException
-from fastapi.middleware.cors import CORSMiddleware
-from config import Config
+import os
+
+import gradio as gr
+import uvicorn
+
+try:
+    import spaces
+
+    print(f"[boot] spaces real: {getattr(spaces, '__file__', '?')}", flush=True)
+except ImportError:  # fora do ZeroGPU (dev local)
+    print("[boot] AVISO: pacote 'spaces' ausente, fallback local (ZeroGPU desligado)", flush=True)
+
+    class _SpacesFallback:
+        @staticmethod
+        def GPU(task=None, **kwargs):
+            if task is None:
+                return lambda fn: fn
+            return task
+
+    spaces = _SpacesFallback()
+
 from ai_engine import AIEngine
-from models import EscutarPayload, EscutarResponse
-
-engine = AIEngine()
-
-# ---------- FastAPI (WhatsApp Bot envia pedidos aqui) ----------
-api = FastAPI(title="Plenitude API")
-api.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])
-
-def require_token(authorization: str = Header(default="")):
-    if not Config.API_AUTH_TOKEN:
-        return
-    if authorization != f"Bearer {Config.API_AUTH_TOKEN}":
-        raise HTTPException(status_code=401, detail="Token invalido")
-
-@api.get("/health")
-@api.get("/api/health")
-def health():
-    return {"status": "ok"}
-
-@api.post("/escutar", response_model=EscutarResponse)
-@api.post("/api/escutar", response_model=EscutarResponse)
-def escutar(payload: EscutarPayload, _=Depends(require_token)):
-    cliente = payload.numero_crm or payload.numero or "unknown"
-    texto = payload.texto.strip()
-    if not texto and not payload.audio_base64:
-        return EscutarResponse(texto="Nao consegui ler a sua mensagem. Pode escrever de novo?")
-    if not texto:
-        texto = "(audio recebido)"
-    resposta = engine.generate_reply(cliente, texto, payload.nome or "Cliente")
-    return EscutarResponse(texto=resposta)
-
-# ---------- Gradio (Interface visual + ZeroGPU) ----------
-@spaces.GPU
-def plenitude_chat(message, history):
-    if not message or not message.strip():
-        return "Por favor, escreva a sua mensagem."
-    return engine.generate_reply("web_user", message, "Visitante")
-
-_demo = gr.ChatInterface(
-    fn=plenitude_chat,
-    title="Plenitude - Negra Plena",
-    description="Assistente virtual da pastelaria Negra Plena. Desenvolvida pela Softedge.",
-)
-
-# Monta o Gradio por cima do FastAPI (ambos na mesma porta 7860)
-app = gr.mount_gradio_app(api, _demo, path="/")
+from config import Config
+from main import app as api_app
+
+PORT = int(os.getenv("PORT") or os.getenv("GRADIO_SERVER_PORT") or 7860)
+
+_engine = AIEngine()
+
+
+def _demo_reply(pergunta: str) -> str:
+    pergunta = (pergunta or "").strip()
+    if not pergunta:
+        return "Escreve uma pergunta, por exemplo: quanto custa a pizza?"
+    return _engine.generate_reply("demo", pergunta, "Visitante")
+
+
+@spaces.GPU(duration=120)
+def _zerogpu_status() -> str:
+    return "ZeroGPU activo neste Space."
+
+
+api_app.router.routes = [r for r in api_app.router.routes if getattr(r, "path", None) != "/"]
+
+with gr.Blocks(title=f"{Config.ASSISTANT_NAME} - {Config.COMPANY_NAME}") as demo:
+    gr.Markdown(
+        f"# {Config.ASSISTANT_NAME} - cérebro da {Config.COMPANY_NAME}\n"
+        "API de atendimento usada pelo bot WhatsApp.  \n"
+        "`POST /api/escutar` · `GET /health` · `GET /docs`"
+    )
+    entrada = gr.Textbox(label="Pergunta de teste", placeholder="quanto custa a pizza?")
+    btn = gr.Button("Enviar", variant="primary")
+    saida = gr.Markdown()
+    btn.click(_demo_reply, inputs=entrada, outputs=saida)
+    entrada.submit(_demo_reply, inputs=entrada, outputs=saida)
+    gr.Button("Estado ZeroGPU").click(_zerogpu_status, inputs=None, outputs=saida)
+
+# SSR desligado: o proxy Node do Gradio fica com a 7860 e o uvicorn precisa dela.
+app = gr.mount_gradio_app(api_app, demo, path="/", ssr_mode=False)
+
+# ZeroGPU: o demo TEM de ser lançado para o scan de startup detectar o @spaces.GPU.
+# Padrão comprovado (Gradio + ZeroGPU + Uvicorn): launch interno não-bloqueante
+# numa porta livre e fecha; o tráfego real é servido pelo uvicorn na $PORT.
+try:
+    demo.launch(prevent_thread_lock=True, server_name="127.0.0.1", server_port=8000)
+    demo.close()
+    print("[boot] demo lançado e fechado para o scan ZeroGPU", flush=True)
+except Exception as exc:
+    print(f"[boot] lançamento interno do demo falhou: {exc!r}", flush=True)
+
+# Pré-aquecimento do Llama local: baixa os pesos UMA vez (depois usa o cache
+# do disco) para a primeira resposta não pagar o download. Falha silenciosa
+# com fallback para as APIs externas — nunca impede o arranque.
+try:
+    from local_llm import _ensure_loaded as _warm_llama
+    _warm_llama()
+except Exception as exc:
+    print(f"[boot] warmup Llama ignorado: {exc!r}", flush=True)
 
 if __name__ == "__main__":
-    import uvicorn
-    uvicorn.run(app, host="0.0.0.0", port=7860)
+    uvicorn.run(app, host="0.0.0.0", port=PORT, log_level="info")

config.py

@@ -31,6 +31,31 @@ class Config:
     COMPANY_NAME = os.getenv("COMPANY_NAME", "Negra Plena")
     ASSISTANT_NAME = os.getenv("ASSISTANT_NAME", "Plenitude")
 
+    # Preços oficiais — exigido por catalog.py (não remover).
+    OFFICIAL_PRICES = """
+PREÇOS OFICIAIS (prioridade máxima — usa estes valores; não inventes outros):
+
+Pizzas
+- Pequena: 5.000 Kz
+- Média: 7.000 Kz
+- Grande: 9.500 Kz
+
+Bolo no pote (artigo especial da marca): 1.500 Kz
+
+Doces e salgados — vendidos por DÚZIA
+- Dúzia de mini pizzas: 9.000 Kz
+- Dúzia de rissóis: 9.000 Kz
+- Dúzia de enroladinhos de pão de chouriço: 10.000 Kz
+- Dúzia de mini pudim: 12.000 Kz
+- Dúzia de bolas de Berlim: 12.000 Kz
+
+Notas de preço
+- Doces incluem: bola de Berlim, bolinho, enroladinho de coco e restantes doces da casa.
+- Salgados incluem: chamuça, pastel de massa tenra, pão com chouriço, enroladinho de chouriço e restantes salgados da casa.
+- Mousse, pudim e similares também são por dúzia (quando aplicável).
+- Se o cliente pedir um produto sem preço listado, diz que a equipa confirma o valor.
+""".strip()
+
     SYSTEM_PROMPT = (
         "Voce e a Plenitude, assistente virtual oficial de atendimento da Negra Plena.\n\n"
         "Identidade\n"

learning.py

@@ -0,0 +1,182 @@
+"""Aprendizado v1 — log local JSONL + recuperação de casos parecidos (few-shot).
+
+Sem dependências novas, só stdlib. CPU-friendly, sem GPU.
+
+- Cada troca bot<->cliente é anexada a `conversas.jsonl` (ver `DATA_DIR`).
+- `POST /feedback` classifica uma resposta como "boa"/"ma".
+- Respostas "ma" nunca voltam como exemplo; "boa" tem prioridade.
+- Exemplos parecidos entram no prompt como few-shot (factos e tom).
+- O ficheiro nunca deve ir para git (contém números de clientes): ver `.gitignore`.
+"""
+
+import json
+import os
+import re
+import threading
+import unicodedata
+import uuid
+from datetime import datetime, timezone
+
+_STOPWORDS = {
+    "a", "o", "e", "de", "do", "da", "dos", "das", "em", "um", "uma",
+    "para", "com", "que", "quanto", "quantos", "qual", "quais", "como",
+    "quando", "onde", "os", "as", "uns", "umas", "no", "na", "nos",
+    "nas", "ao", "aos", "por", "mais", "muito", "isto", "isso", "este",
+    "esta", "esse", "essa", "meu", "minha", "seu", "sua", "voce", "você",
+    "tem", "têm", "e", "se", "qto", "qt", "q", "la", "lá", "ai", "aí",
+    "entao", "então", "pois", "mas", "ou", "tambem", "também",
+}
+
+
+def _tokens(texto: str) -> set:
+    sem_acento = unicodedata.normalize("NFKD", texto or "").encode("ascii", "ignore").decode()
+    palavras = re.findall(r"[a-z0-9]+", sem_acento.lower())
+    return {p for p in palavras if len(p) > 2 and p not in _STOPWORDS}
+
+
+class LearningStore:
+    """Guarda trocas em JSONL e recupera casos parecidos."""
+
+    def __init__(
+        self,
+        data_dir: str | None = None,
+        arquivo: str = "conversas.jsonl",
+        max_linhas: int = 2000,
+        top_k: int = 2,
+        min_score: float = 0.15,
+    ):
+        self.data_dir = data_dir or os.getenv("DATA_DIR", "./data")
+        self.arquivo = arquivo
+        self.max_linhas = int(os.getenv("LEARNING_MAX_LINHAS", str(max_linhas)))
+        self.top_k = int(os.getenv("LEARNING_TOP_K", str(top_k)))
+        self.min_score = float(os.getenv("LEARNING_MIN_SCORE", str(min_score)))
+        self._lock = threading.Lock()
+        try:
+            os.makedirs(self.data_dir, exist_ok=True)
+        except Exception as exc:
+            print(f"[learning] não consegui criar {self.data_dir}: {exc}")
+
+    def _caminho(self) -> str:
+        return os.path.join(self.data_dir, self.arquivo)
+
+    def _ler_tudo(self) -> list:
+        registos = []
+        try:
+            with open(self._caminho(), "r", encoding="utf-8") as fh:
+                for linha in fh:
+                    linha = linha.strip()
+                    if not linha:
+                        continue
+                    try:
+                        registos.append(json.loads(linha))
+                    except json.JSONDecodeError:
+                        continue
+        except FileNotFoundError:
+            pass
+        except Exception as exc:
+            print(f"[learning] erro a ler: {exc}")
+        return registos
+
+    def log_exchange(self, cliente: str, pergunta: str, resposta: str,
+                     provedor: str = "", modelo: str = "",
+                     mensagem_id: str | None = None) -> str:
+        mensagem_id = mensagem_id or uuid.uuid4().hex[:12]
+        registo = {
+            "id": mensagem_id,
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "cliente": cliente or "unknown",
+            "pergunta": (pergunta or "")[:1000],
+            "resposta": (resposta or "")[:1000],
+            "provedor": provedor,
+            "modelo": modelo,
+            "avaliacao": None,
+        }
+        try:
+            with self._lock:
+                with open(self._caminho(), "a", encoding="utf-8") as fh:
+                    fh.write(json.dumps(registo, ensure_ascii=False) + "\n")
+                self._podar()
+        except Exception as exc:
+            print(f"[learning] erro a registar: {exc}")
+        return mensagem_id
+
+    def _podar(self) -> None:
+        try:
+            with open(self._caminho(), "r", encoding="utf-8") as fh:
+                linhas = fh.readlines()
+            if len(linhas) > self.max_linhas + 500:
+                with open(self._caminho(), "w", encoding="utf-8") as fh:
+                    fh.writelines(linhas[-self.max_linhas:])
+        except FileNotFoundError:
+            pass
+        except Exception as exc:
+            print(f"[learning] erro a podar: {exc}")
+
+    def rate(self, mensagem_id: str, nota: str, observacao: str = "") -> bool:
+        if nota not in ("boa", "ma"):
+            return False
+        try:
+            with self._lock:
+                registos = self._ler_tudo()
+                achou = False
+                for reg in registos:
+                    if reg.get("id") == mensagem_id:
+                        reg["avaliacao"] = nota
+                        if observacao:
+                            reg["observacao"] = observacao[:500]
+                        achou = True
+                        break
+                if not achou:
+                    return False
+                with open(self._caminho(), "w", encoding="utf-8") as fh:
+                    for reg in registos:
+                        fh.write(json.dumps(reg, ensure_ascii=False) + "\n")
+                return True
+        except Exception as exc:
+            print(f"[learning] erro a avaliar: {exc}")
+            return False
+
+    def find_similar(self, pergunta: str, k: int | None = None) -> list:
+        base = _tokens(pergunta)
+        if not base:
+            return []
+        candidatos = []
+        try:
+            for reg in self._ler_tudo():
+                if reg.get("avaliacao") == "ma":
+                    continue
+                pontos = _tokens(reg.get("pergunta", ""))
+                if not pontos:
+                    continue
+                uniao = base | pontos
+                score = len(base & pontos) / len(uniao) if uniao else 0.0
+                if reg.get("avaliacao") == "boa":
+                    score = min(1.0, score + 0.25)
+                if score >= self.min_score:
+                    candidatos.append((score, reg))
+        except Exception as exc:
+            print(f"[learning] erro a procurar: {exc}")
+            return []
+        candidatos.sort(key=lambda item: item[0], reverse=True)
+        return [reg for _, reg in candidatos[: (k or self.top_k)]]
+
+    def format_examples(self, pergunta: str) -> str:
+        exemplos = self.find_similar(pergunta)
+        if not exemplos:
+            return ""
+        blocos = ["EXEMPLOS DE ATENDIMENTOS ANTERIORES (segue o mesmo padrão de factos e tom):"]
+        total = len(blocos[0])
+        for i, reg in enumerate(exemplos, 1):
+            perg = (reg.get("pergunta", "") or "")[:200]
+            resp = (reg.get("resposta", "") or "")[:300]
+            bloco = f"{i}) Cliente: {perg}\n   Plenitude: {resp}"
+            if total + len(bloco) > 900:
+                break
+            blocos.append(bloco)
+            total += len(bloco)
+        if len(blocos) < 2:
+            return ""
+        return "\n".join(blocos)
+
+    def count(self) -> int:
+        return len(self._ler_tudo())

local_llm.py

@@ -1,54 +1,102 @@
-import os
+"""Llama local no ZeroGPU — inferência com pesos abertos + LoRA opcional.
+
+Regras ZeroGPU respeitadas:
+- `import spaces` ANTES de qualquer import que toque CUDA (regra nº1).
+- Modelo carregado UMA vez no processo principal com `.to("cuda")`
+  (o hijack do spaces trata disto); NUNCA dentro do `@spaces.GPU`.
+- `@spaces.GPU` só em função de módulo (o `self` com o modelo não
+  atravessa o fork; ver "Process isolation and pickle").
+- Falha de download (ex. repo gated sem licença) NÃO deita o Space
+  abaixo: regista o motivo uma vez e a hierarquia cai para as APIs externas.
+"""
+
+import spaces  # tem de ser o primeiro import com CUDA por perto
+
+import os
+import threading
+
 import torch
-import spaces
 from transformers import AutoModelForCausalLM, AutoTokenizer
-from peft import PeftModel
+
+try:
+    from peft import PeftModel
+except ImportError:
+    PeftModel = None
+
 from config import Config
 
-class LocalLlamaEngine:
-    _instance = None
-
-    def __init__(self):
-        self.model_id = Config.LOCAL_MODEL_ID
-        self.lora_path = Config.LORA_ADAPTER_PATH
-        
-        print(f"🔄 A iniciar Llama local ({self.model_id}) na RAM (ZeroGPU movera para GPU na inferencia)...")
-        self.tokenizer = AutoTokenizer.from_pretrained(self.model_id)
-        
-        self.model = AutoModelForCausalLM.from_pretrained(
-            self.model_id,
+_MODEL = None
+_TOKENIZER = None
+_LOAD_FAILED = ""
+_LOAD_LOCK = threading.Lock()
+
+
+def _ensure_loaded() -> bool:
+    global _MODEL, _TOKENIZER, _LOAD_FAILED
+    if _MODEL is not None:
+        return True
+    if _LOAD_FAILED:
+        return False
+    with _LOAD_LOCK:
+        if _MODEL is not None:
+            return True
+        if _LOAD_FAILED:
+            return False
+        return _load_once()
+
+
+def _load_once() -> bool:
+    global _MODEL, _TOKENIZER, _LOAD_FAILED
+    model_id = Config.LOCAL_MODEL_ID
+    try:
+        print(f"[llama] a carregar {model_id} ...", flush=True)
+        tok = AutoTokenizer.from_pretrained(model_id)
+        if tok.pad_token is None:
+            tok.pad_token = tok.eos_token
+        mdl = AutoModelForCausalLM.from_pretrained(
+            model_id,
             torch_dtype=torch.bfloat16,
-            low_cpu_mem_usage=True
+            low_cpu_mem_usage=True,
         )
-        
-        if self.lora_path and os.path.exists(self.lora_path):
-            print(f"🧠 A aplicar pesos de aprendizagem LoRA de: {self.lora_path}...")
-            self.model = PeftModel.from_pretrained(self.model, self.lora_path)
-            
-        print("✅ Llama local preparado e pronto a usar!")
-
-    @classmethod
-    def get_instance(cls):
-        if cls._instance is None:
-            cls._instance = cls()
-        return cls._instance
-
-    @spaces.GPU
-    def generate(self, messages: list) -> str:
-        # Movemos o modelo para a GPU no exacto momento do atendimento
-        self.model.to("cuda")
-        
-        prompt = self.tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
-        inputs = self.tokenizer(prompt, return_tensors="pt").to("cuda")
-        
-        outputs = self.model.generate(
-            **inputs, 
-            max_new_tokens=450, 
-            temperature=0.4, 
-            top_p=0.9,
-            do_sample=True,
-            pad_token_id=self.tokenizer.eos_token_id
-        )
-        
-        response = self.tokenizer.decode(outputs[0][inputs["input_ids"].shape[-1]:], skip_special_tokens=True)
-        return response.strip()
+        # Uma vez no processo principal; o hijack do spaces gere o resto.
+        mdl.to("cuda")
+        lora = Config.LORA_ADAPTER_PATH
+        if lora:
+            if not os.path.exists(lora):
+                print(f"[llama] LORA_ADAPTER_PATH inexistente ({lora}); a ignorar.", flush=True)
+            elif PeftModel is None:
+                raise RuntimeError("peft não instalado; não consigo aplicar o adaptador LoRA")
+            else:
+                print(f"[llama] a aplicar LoRA de: {lora} ...", flush=True)
+                mdl = PeftModel.from_pretrained(mdl, lora)
+        mdl.eval()
+        _MODEL, _TOKENIZER = mdl, tok
+        print("[llama] modelo pronto.", flush=True)
+        return True
+    except Exception as exc:
+        _LOAD_FAILED = f"{type(exc).__name__}: {exc}"
+        print(f"[llama] indisponível ({_LOAD_FAILED}); fallback para APIs externas.", flush=True)
+        return False
+
+
+@spaces.GPU(duration=180)
+def generate_local(messages: list) -> str:
+    """Gera resposta com o Llama local. Falha rápido se o modelo não carregou."""
+    if not _ensure_loaded():
+        raise RuntimeError(f"Llama local indisponível: {_LOAD_FAILED}")
+    prompt = _TOKENIZER.apply_chat_template(
+        messages, tokenize=False, add_generation_prompt=True
+    )
+    inputs = _TOKENIZER(prompt, return_tensors="pt").to("cuda")
+    gen = _MODEL.generate(
+        **inputs,
+        max_new_tokens=450,
+        temperature=0.4,
+        top_p=0.9,
+        do_sample=True,
+        pad_token_id=_TOKENIZER.eos_token_id,
+    )
+    texto = _TOKENIZER.decode(
+        gen[0][inputs["input_ids"].shape[-1]:], skip_special_tokens=True
+    )
+    return texto.strip()

main.py

@@ -5,7 +5,7 @@ import spaces
 
 from ai_engine import AIEngine
 from config import Config
-from models import EscutarPayload, EscutarResponse
+from models import EscutarPayload, EscutarResponse, FeedbackPayload, FeedbackResponse
 
 app = FastAPI(
     title="Plenitude — Cerebro Negra Plena",
@@ -68,5 +68,16 @@ def escutar(payload: EscutarPayload, _: None = Depends(require_token)):
     if not texto and payload.audio_base64:
         texto = "(o cliente enviou um audio; transcricao na GPU ainda em preparacao)"
 
-    resposta = engine.generate_reply(cliente, texto, payload.nome or "Cliente")
-    return EscutarResponse(texto=resposta)
+    resposta, mensagem_id = engine.responder(cliente, texto, payload.nome or "Cliente")
+    return EscutarResponse(texto=resposta, mensagem_id=mensagem_id)
+
+
+@app.post("/feedback", response_model=FeedbackResponse)
+@app.post("/api/feedback", response_model=FeedbackResponse)
+def feedback(payload: FeedbackPayload, _: None = Depends(require_token)):
+    ok = engine.learning.rate(
+        payload.mensagem_id, payload.nota, payload.comentario or ""
+    )
+    if ok:
+        return FeedbackResponse(ok=True, detalhe="Avaliação registada. Obrigado!")
+    return FeedbackResponse(ok=False, detalhe="mensagem_id não encontrado.")

models.py

@@ -1,4 +1,4 @@
-from typing import Optional
+from typing import Literal, Optional
 
 from pydantic import BaseModel, Field
 
@@ -16,3 +16,17 @@ class EscutarPayload(BaseModel):
 
 class EscutarResponse(BaseModel):
     texto: str = Field(..., description="Resposta a enviar no WhatsApp")
+    mensagem_id: Optional[str] = Field(
+        default=None, description="Id para avaliar depois em POST /feedback"
+    )
+
+
+class FeedbackPayload(BaseModel):
+    mensagem_id: str = Field(..., description="Id devolvido em EscutarResponse")
+    nota: Literal["boa", "ma"] = Field(..., description="'boa' ou 'ma'")
+    comentario: Optional[str] = Field(default=None, description="Nota opcional da equipa")
+
+
+class FeedbackResponse(BaseModel):
+    ok: bool = Field(..., description="True se a avaliação foi registada")
+    detalhe: str = Field(..., description="Explicação curta")