From a268ea93578725c67e7f48857ce5de1460a15b0e Mon Sep 17 00:00:00 2001
From: Davi Dias <davifernandosousadias18@gmail.com>
Date: Sat, 6 Jun 2026 13:28:11 -0300
Subject: [PATCH] docs(claude.md): adicionado arquivo de contexto e claude.md

---
 CLAUDE.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..85e3651
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,62 @@
+# IA Gôndola Engine
+
+Serviço isolado de detecção YOLO e treinamento. Consumido exclusivamente pela `ia-gondola-api` via `IA_MOTOR_URL`.
+
+## Arquitetura
+
+```
+ia-gondola-api  →  POST /detectar  →  YOLO  →  [{box, conf, class}]
+                →  POST /treinar   →  triagem + treino → modelo atualizado no S3
+```
+
+## Estrutura
+
+```
+main.py          — todo o código (sem sub-módulos)
+Dockerfile
+requirements.txt
+```
+
+## Endpoints
+
+### `POST /detectar`
+
+Form-data: `ambiente` (str), `file` (imagem). Confidence threshold: 0.25.
+
+```json
+{ "status": "sucesso", "deteccoes": [{ "box": [x1,y1,x2,y2], "conf": 0.87, "class": 0 }] }
+```
+
+### `POST /treinar`
+
+Body JSON: `{ "ambiente": "gondola", "pular_triagem": false }`
+
+1. Lista `treinamento/{ambiente}/novos-treinamentos/` no S3
+2. Triagem (salvo `pular_triagem: true`): conf média ≥ 0.30 ou == 0 → `base-oficial`, < 0.30 → `descartados`
+3. Baixa `base-oficial`, redimensiona imagens > 4096px
+4. Treina: 30 épocas, imgsz=640, batch=16, device=cpu
+5. Salva `best.pt` em `modelos/{ambiente}/atual/cerebro.pt` + histórico versionado
+
+## 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/
+```
+
+## Convenções
+
+- `MODELOS_CARREGADOS` = dict em memória `{ambiente: YOLO}` — cache local em `/tmp/cerebro_{ambiente}.pt`
+- Se S3 tiver versão mais nova (LastModified), descarta cache e baixa novamente
+- Após treino, remove o ambiente de `MODELOS_CARREGADOS` para forçar reload
+- Todo o código em `main.py` — não criar sub-módulos
+
+## Como rodar
+
+```bash
+pip install -r requirements.txt
+uvicorn main:app --reload --port 8001
+```