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 atualizado no S3

Estrutura

main.py          — todo o código (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 (imagem). Confidence threshold: 0.25.

{ "status": "sucesso", "deteccoes": [{ "box": [x1,y1,x2,y2], "conf": 0.87, "class": 0 }] }

POST /treinar

Body JSON: { "ambiente": "gondola", "pular_triagem": false }

Fluxo completo:

1. Lista treinamento/{ambiente}/novos-treinamentos/ no S3
2. Triagem (salvo pular_triagem: true):
   • Prediz cada imagem com o modelo atual (conf threshold 0.1)
   • conf média >= 0.15 OU conf == 0 → move para base-oficial
   • conf média < 0.15 → move para descartados
3. Baixa toda a base-oficial para /tmp/dataset_{ambiente}/
4. Redimensiona imagens > 4096px
5. Gera data.yaml com train=val=img_dir, nc=1
6. Treina: 20 épocas (fine-tuning) / 30 épocas (do zero), imgsz=640, batch=8, 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
modelos/{ambiente}/versionamento/cerebro_YYYYMMDD_HHMM.pt
treinamento/{ambiente}/novos-treinamentos/
treinamento/{ambiente}/base-oficial/
treinamento/{ambiente}/descartados/

Ambientes ativos: "gondola" (produtos), "etiqueta" (etiquetas de preço).

Cache de modelos

• MODELOS_CARREGADOS = dict {ambiente: YOLO} — evita reload a cada request
• Arquivo local: /tmp/cerebro_{ambiente}.pt
• Se LastModified do S3 > mtime local → descarta cache e baixa novamente
• Após treino, o ambiente treinado é removido de MODELOS_CARREGADOS para forçar reload

Env vars

Variável	Descrição
BUCKET_NAME	Nome do bucket S3
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_DEFAULT_REGION

Convenções

• Todo o código em main.py — não criar sub-módulos
• Triagem usa conf threshold 0.15 (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

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