Quickstart

Resultado esperado

Ao final deste quickstart, você terá validado:

1. ambiente Python e dependências sincronizados;
2. fluxo crítico de treino/promoção e fallback funcionando;
3. documentação local disponível para navegação.

Tempo médio: 10 a 15 minutos.

Pré-requisitos

Item	Versão/expectativa
Python	3.14 (definido em .python-version)
uv	instalado e disponível no terminal
Node.js + npm	necessários para build do site em docs/

1. Preparar o ambiente Python

uv sync

2. Validar o ciclo crítico da engine

Rodar os casos críticos de aplicação (treino/promoção e fallback):

make test-engine

Rodar o slice MLOps com persistência/registry/observabilidade:

make test-integration
make test-registry-smoke
make test-observability-smoke

Rodar o gate padrão de qualidade do projeto:

make lint
make typecheck
make test

Opcionalmente, subir um MLflow local para inspecionar tracking/registry:

make mlflow-ui

3. Subir a documentação local

Instalar dependências do site e iniciar servidor de docs:

make docs-install
make docs-dev

Para validar build de produção:

make docs-build

4. Checklist de sucesso

• make test-engine passa sem falhas.
• make test-integration passa cobrindo persistência e adapters MLOps.
• make test passa com a suíte completa.
• make docs-build conclui sem erros.
• Você consegue abrir o site de docs em modo dev local.

Problemas comuns

Sintoma	Causa provável	Ação recomendada
uv sync falha	uv ausente ou versão incompatível	Instalar/atualizar uv e repetir o comando
make test-engine falha por import	ambiente não sincronizado	Rodar uv sync novamente
make docs-build falha	dependências de docs/ não instaladas	Rodar make docs-install e repetir

Próximos passos

1. Ler Treinamento e promoção.
2. Ler Previsão com fallback.
3. Revisar Fluxos principais para detalhes de execução.