Skip to content
Atreides

Quickstart

Objetivo

Subir o caminho local completo:

HTTP -> Airflow -> infra/jobs

A stack local usa:

  • ClickHouse para metadados do Atreides;
  • Postgres separado apenas para metadados internos do Airflow;
  • MinIO como S3 compatível para snapshots e artefatos;
  • MLflow local;
  • Airflow standalone para DAGs;
  • JWT HS256 gerado pelo próprio repositório.

Pré-requisitos

  • Python 3.12
  • uv
  • just
  • Docker com Compose

Sequência mínima

  1. Instale dependências e copie o ambiente local:
Terminal window
uv sync
cp .env.local.example .env
  1. Suba a stack local com Airflow:
Terminal window
docker compose -f compose.yml up -d clickhouse minio mlflow minio-init airflow

Esse comando também sobe ClickHouse, MinIO, MLflow e cria os buckets locais.

  1. Aplique as migrations ClickHouse do Atreides:
Terminal window
just db-init
  1. Crie uma definição mínima:
Terminal window
just seed-local-model-definition
  1. Suba a API HTTP:
Terminal window
just serve-http
  1. Gere um token local:
Terminal window
just setup-local-auth 01956c73-9c1f-7fb7-94b1-a2c5bc65d901 local-operator

Verificações rápidas

Sem auth:

Terminal window
curl http://127.0.0.1:8000/healthz

Airflow local:

Terminal window
open http://127.0.0.1:8080

MLflow local:

Terminal window
open http://127.0.0.1:5000

Com auth:

Terminal window
AUTH_HEADER="$(just setup-local-auth 01956c73-9c1f-7fb7-94b1-a2c5bc65d901 local-operator)"
curl -H "$AUTH_HEADER" http://127.0.0.1:8000/healthz

Disparando treino end to end

O caminho mais curto para validar o fluxo completo é usar o script HTTP local. Ele gera ./tmp/local-demand.csv, pede um JWT local pelo just setup-local-auth e submete o treino no endpoint protegido:

Terminal window
just example-http-training

Se preferir montar o curl manualmente, prepare antes um CSV com as colunas canônicas de demanda em ./tmp/local-demand.csv:

organization_id,sku_id,store_id,sku_system,sku_key,store_system,store_key,grain,period_start,quantity,uom,source,created_at

Depois dispare o treino pelo endpoint HTTP:

Terminal window
AUTH_HEADER="$(just setup-local-auth 01956c73-9c1f-7fb7-94b1-a2c5bc65d901 local-operator)"
curl -X POST \
  -H "$AUTH_HEADER" \
  -H 'Content-Type: application/json' \
  http://127.0.0.1:8000/v1/model-definitions/01956c73-9c1f-7fb7-94b1-a2c5bc65d940/training-jobs \
  -d "{\"input_path\":\"$(pwd)/tmp/local-demand.csv\",\"source_format\":\"csv\"}"

A resposta inclui run_id, dag_id, orchestrator, snapshot_id e status. Use o run_id para acompanhar o DAG run no Airflow.

Para testar o caminho com configuração versionada antes do disparo, use o manifesto local:

Terminal window
just config-validate examples/local_model_definition_config.json
just config-apply examples/local_model_definition_config.json

Esse manifesto configura horizonte, estratégia, feature recipe, projeção sku_store e regras que validam o DemandSnapshotManifest criado pelo job de materialização. Depois repita o curl de treino acima; a API continua apenas enfileirando o DAG, enquanto Airflow executa a materialização, lê o manifesto do snapshot e roda o treino.

Executando direto para depuração

Para depurar treino dentro do processo Python, sem HTTP e sem Airflow:

Terminal window
just example-direct-training

Esse exemplo é o mesmo entrypoint importável em Jupyter documentado em Execução programática local. Ele materializa o snapshot, projeta as séries e chama diretamente os use cases control.modeling.training.use_cases.train_model_candidates(...) e control.modeling.promotion.use_cases.promote_trained_candidates(...).

Troubleshooting

Infra local parada:

Terminal window
docker compose -f compose.yml down
docker compose -f compose.yml up -d clickhouse minio mlflow minio-init airflow

Logs do Airflow:

Terminal window
docker compose -f compose.yml logs -f airflow

Buckets/MinIO:

  • o serviço minio-init cria atreides-demand e atreides-artifacts.

Próximos passos