docs: adicionado skill

2026-06-06 13:42:51 -03:00
parent a268ea9357
commit 8bdb28cdc1
1 changed files with 109 additions and 0 deletions
@@ -0,0 +1,109 @@
+---
+name: ia-gondola-engine
+description: "Carrega o contexto completo do projeto ia-gondola-engine. Use sempre que iniciar um chat neste repo."
+compatibility: claude-code-only
+---
+
+# Contexto — ia-gondola-engine
+
+Serviço isolado de detecção YOLO e treinamento. Consumido exclusivamente pela `ia-gondola-api` via `IA_MOTOR_URL`.
+
+## Papel no sistema
+
+```
+ia-gondola-api  →  POST {IA_MOTOR_URL}/detectar  →  YOLO  →  [{box, conf, class}]
+                →  POST {IA_MOTOR_URL}/treinar   →  triagem + treino → modelo no S3
+```
+
+## Estrutura
+
+```
+main.py          — todo o código (FastAPI simples, sem sub-módulos)
+Dockerfile
+requirements.txt
+```
+
+Intencionalmente minimalista — não tem banco, não tem pastas internas.
+
+## Endpoints
+
+### `POST /detectar`
+
+Form-data: `ambiente` (str), `file` (upload de imagem).
+
+```json
+// Resposta
+{
+  "status": "sucesso",
+  "deteccoes": [
+    { "box": [x1, y1, x2, y2], "conf": 0.87, "class": 0 }
+  ]
+}
+```
+
+Confidence threshold no detect: `0.25`.
+
+### `POST /treinar`
+
+Body JSON: `{ "ambiente": "gondola", "pular_triagem": false }`
+
+**Fluxo completo:**
+1. Lista `treinamento/{ambiente}/novos-treinamentos/` no S3
+2. **Triagem** (a menos que `pular_triagem: true`):
+   - Prediz cada imagem com o modelo atual (conf threshold 0.1)
+   - `conf média >= 0.30` OU `conf == 0` → move para `base-oficial`
+   - `conf média < 0.30` → move para `descartados`
+3. Baixa toda a `base-oficial` para `/tmp/dataset_{ambiente}/`
+4. Redimensiona imagens > 4096px (`redimensionar_imagem`)
+5. Gera `data.yaml` com train=val=img_dir, nc=1
+6. Treina: 30 épocas, imgsz=640, batch=16, device=cpu
+7. Salva `best.pt`:
+   - `modelos/{ambiente}/atual/cerebro.pt` (substitui)
+   - `modelos/{ambiente}/versionamento/cerebro_{YYYYMMDD_HHMM}.pt` (histórico)
+
+## Organização S3
+
+```
+modelos/{ambiente}/atual/cerebro.pt                            ← em produção
+modelos/{ambiente}/versionamento/cerebro_YYYYMMDD_HHMM.pt     ← histórico
+treinamento/{ambiente}/novos-treinamentos/                     ← aguardando triagem (img + .txt)
+treinamento/{ambiente}/base-oficial/                           ← aprovados pela triagem
+treinamento/{ambiente}/descartados/                            ← reprovados
+```
+
+Ambientes ativos: `"gondola"` (produtos), `"etiqueta"` (etiquetas de preço).
+
+## Cache de modelos
+
+- `MODELOS_CARREGADOS` = dict Python `{ambiente: YOLO}` — evita reload a cada request
+- Arquivo local: `/tmp/cerebro_{ambiente}.pt`
+- Se `LastModified` do S3 > `mtime` local → descarta cache, baixa novamente
+- Após treino, o modelo do ambiente treinado é removido de `MODELOS_CARREGADOS` para forçar reload
+
+## Env vars
+
+| Variável | Descrição |
+|----------|-----------|
+| `BUCKET_NAME` | Nome do bucket S3 (default: `ia-gondola-projeto-2024`) |
+| `AWS_ACCESS_KEY_ID` | |
+| `AWS_SECRET_ACCESS_KEY` | |
+| `AWS_DEFAULT_REGION` | |
+
+## Como rodar
+
+```bash
+pip install -r requirements.txt
+uvicorn main:app --reload --port 8001
+```
+
+```bash
+docker build -t ia-gondola-engine .
+docker run -p 8001:8000 --env-file .env ia-gondola-engine
+```
+
+## Convenções
+
+- Todo o código em `main.py` — não criar sub-módulos
+- Triagem usa `conf threshold 0.30` (ajustado manualmente, comentado no código)
+- `pular_triagem: true` é útil quando as imagens já foram pré-validadas
+- Este serviço não tem estado persistente próprio — tudo no S3