README.md

metadata

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