ia-gondola-engine/.claude/skills/ia-gondola-engine/SKILL.md

name, description, compatibility

name	description	compatibility
ia-gondola-engine	Carrega o contexto completo do projeto ia-gondola-engine. Use sempre que iniciar um chat neste repo.	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).

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

pip install -r requirements.txt
uvicorn main:app --reload --port 8001

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