diff --git a/.claude/skills/ia-gondola-engine/SKILL.md b/.claude/skills/ia-gondola-engine/SKILL.md new file mode 100644 index 0000000..3530c7a --- /dev/null +++ b/.claude/skills/ia-gondola-engine/SKILL.md @@ -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