---
title: Plenitude Negra Plena
emoji: 🧁
colorFrom: purple
colorTo: pink
sdk: gradio
sdk_version: 6.29.1
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. Cerebras → 3. OpenRouter → 4. Groq → 5. DeepSeek → 6. Mistral → 7. Gemini.
Cada nível que falha cai para o seguinte; `AI_PROVIDER` força um específico primeiro.
Provedores sem chave são saltados. Cerebras tem free tier generoso (1M tokens/dia,
sem cartão; contexto 8K no free): cria a chave em cloud.cerebras.ai e define
`CEREBRAS_API_KEY`. Modelos OpenRouter com `:free` também valem como degrau gratuito.
Quota ZeroGPU esgotada? O local entra em pausa até ao reset (lê o "Try again in"
do erro) e o fallback fica imediato — sem esperar o scheduler recusar.
O Llama local (`local_llm.py`, `NousResearch/Meta-Llama-3-8B-Instruct` por defeito,
LoRA opcional via `LORA_ADAPTER_PATH` — pasta local ou id do Hub, ex. `user/meu-lora`,
com download automático e confirmação de adaptadores ativos no log) é 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