Queimad AI CLI

CLI minimalista em Python para orquestrar tarefas de dataset, treinamento e (futuro) serving para detecção de fumaça/fogo. Foco: estrutura limpa com poucas dependências.

Requisitos

• Python 3.9+ (recomendado 3.11)
• Poetry

Instalação do Poetry (documentação oficial)

• Site: https://python-poetry.org/
• Instalação: https://python-poetry.org/docs/#installation

Exemplo (Linux/macOS):

curl -sSL https://install.python-poetry.org | python3 -
poetry --version

Ambiente virtual (Poetry)

• Virtualenvs: https://python-poetry.org/docs/configuration/#virtualenvscreate

Dicas:

poetry config virtualenvs.in-project true  # venv dentro do projeto (opcional e recomendado)
poetry env use python3                     # selecionar o Python

Instalar dependências

Base (CLI):

poetry install

Extras opcionais:

# Para dataset (Roboflow)
poetry install -E dataset
# Para treino/avaliação (Ultralytics + Torch + Torchvision)
poetry install -E train

Observação PyTorch/Torchvision:

• Siga a doc oficial: https://pytorch.org/get-started/locally/
• Em ambientes CPU-only, pode ser necessário instalar via índice oficial:

poetry run pip install --index-url https://download.pytorch.org/whl/cpu torch torchvision

Problema comum em Linux: ModuleNotFoundError: _bz2

• Instale os headers do bzip2 e recompile Python ou instale o pacote do SO:
  • Ubuntu/Debian: sudo apt-get install -y libbz2-1.0 libbz2-dev
  • Se o Python foi compilado manualmente, reinstale com suporte a bz2 após instalar libbz2-dev.

Executar o CLI

# Com venv ativado (opcional: poetry shell)
aicore --help

# Sem ativar o shell
poetry run aicore --help

Subcomandos:

• aicore dataset (check, extract, download, configure)
• aicore train (run, metrics, predict, tune)
• aicore serve (placeholder)

Configuração persistente (.env)

• O CLI lê valores do .env na raiz do projeto (carregado automaticamente via python-dotenv).
• Copie o arquivo de exemplo e preencha:

cp .env.example .env

• Preencha ao menos as variáveis do Roboflow se for usar dataset download:

ROBOFLOW_API_KEY=...
ROBOFLOW_WORKSPACE=...
ROBOFLOW_PROJECT=...
ROBOFLOW_VERSION=...

Salvar configurações do Roboflow e dataset via CLI (opcional, grava no .env):

poetry run aicore dataset configure \
  --api-key "$ROBOFLOW_API_KEY" \
  --workspace wildfire \
  --project smoke-fire-detection \
  --version 1 \
  --dataset-path data/wildfire_dataset

Ajustar defaults de treino:

poetry run aicore train tune \
  --model-size s \
  --imgsz 640 \
  --epochs 50 \
  --batch 8 \
  --patience 50 \
  --use-gpu true \
  --runs-path runs

Variáveis suportadas no .env:

• AICORE_DATASET_PATH (default: data/wildfire_dataset)
• AICORE_RUNS_PATH (default: runs)
• AICORE_YOLO_MODEL_SIZE (default: s)
• AICORE_YOLO_INPUT_SIZE (default: 640)
• AICORE_TRAINING_EPOCHS (default: 50)
• AICORE_TRAINING_BATCH_SIZE (default: 8)
• AICORE_TRAINING_PATIENCE (default: 50)
• AICORE_USE_GPU (default: 1)
• ROBOFLOW_API_KEY (requerida para download)
• ROBOFLOW_WORKSPACE (slug do workspace)
• ROBOFLOW_PROJECT (slug do projeto)
• ROBOFLOW_VERSION (número da versão)

Fluxo recomendado

1. Configurar ambiente e defaults (uma vez):

poetry config virtualenvs.in-project true
poetry install -E dataset -E train
cp .env.example .env  # edite valores
poetry run aicore dataset configure --api-key "$ROBOFLOW_API_KEY" --workspace wildfire --project smoke-fire-detection --version 1
poetry run aicore train tune --model-size s --imgsz 640 --epochs 50 --batch 8 --patience 50 --use-gpu true

2. Baixar/extrair dataset:

# via Roboflow (usa .env por padrão)
poetry run aicore dataset download
# ou extrair um zip YOLOv8
poetry run aicore dataset extract wildfire.v10-origin.yolov8.zip

3. Treinar:

poetry run aicore train run
# ou sobrescrever temporariamente
poetry run aicore train run --epochs 100 --imgsz 640 --batch 16

4. Métricas:

poetry run aicore train metrics

5. Predição:

poetry run aicore train predict images/

Estrutura

.
├── pyproject.toml
├── README.md
├── .env.example
├── src/
│   └── aicore/
│       ├── __init__.py
│       ├── cli.py
│       ├── config.py
│       └── commands/
│           ├── dataset.py
│           ├── train.py
│           └── serve.py
└── .gitignore

Próximos passos

• Expandir serve para API/local e streaming.
• Adicionar presets de hyperparams e perfis (rápido vs. completo).

Links oficiais

• Typer: https://typer.tiangolo.com/
• Poetry: https://python-poetry.org/docs/
• PyTorch: https://pytorch.org/get-started/locally/
• Ultralytics YOLOv8: https://docs.ultralytics.com/
• Roboflow: https://docs.roboflow.com/