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