Machine Learning & Treinamento¶

O Oraculo utiliza XGBoost (Extreme Gradient Boosting) para classificacao binaria: prever se um usuario vai converter ou abandonar a landing page.

Visao Geral¶

graph LR
    A[Dados de Sessao<br/>MongoDB] --> B[Feature Engineering]
    B --> C[Treinamento<br/>XGBoost]
    C --> D[Artefato .pkl<br/>MinIO S3]
    D --> E[Predicao<br/>em tempo real]
    E --> F{P conversao < threshold?}
    F -->|Sim| G[Dispara Modal]
    F -->|Nao| H[Nao faz nada]

Algoritmo¶

Propriedade	Valor
Algoritmo	XGBClassifier (XGBoost)
Tipo	Classificacao Binaria
Alvo	`Y = 1` (conversao) / `Y = 0` (abandono)
Formato	Pickle (.pkl)
Storage	MinIO (S3-compatible)

Features¶

As features sao extraidas dos dados comportamentais coletados pelo Tracker SDK:

Feature	Tipo	Descricao	Relevancia
`mouseVelocity`	float	Velocidade media do mouse (px/s)	Alta - usuarios engajados movem o mouse mais
`maxScrollDepth`	int	Profundidade maxima de scroll (0-100%)	Alta - scroll profundo indica interesse
`idleTime`	float	Tempo ocioso acumulado (s)	Media - muito idle pode indicar desinteresse
`sessionTime`	float	Tempo total na pagina (s)	Alta - tempo correlaciona com conversao
`scrollVelocity`	float	Velocidade de scroll (px/s)	Media - scroll rapido pode ser scan
`focusChanges`	int	Trocas de foco da janela	Media - muitas trocas indicam distracao
`lastClickedTag`	string	Tag HTML do ultimo clique	Baixa - contextualizacao
`pageVisibility`	string	Estado da aba (visible/hidden)	Media - aba escondida = desinteresse

Label (Variavel Alvo)¶

A label e definida pelo Success Event configurado no datasource:

Y = 1 (Conversao): Sessao onde o usuario clicou em um elemento que corresponde ao seletor do Success Event (ex: botao de compra)
Y = 0 (Abandono): Sessao onde o usuario saiu sem interagir com nenhum Success Event

Treinamento Automatico¶

O treinamento e gerenciado pelo APScheduler na Models API com tres jobs:

1. Check Initial Training¶

Frequencia: A cada 6 horas
Condicao: Datasource com modelo nao treinado (trained = false)
Trigger: Quando session_count >= initial_checkpoint (default: 10.000)

flowchart TD
    A[Cron: Check Initial Training] --> B{Modelo treinado?}
    B -->|Sim| Z[Skip]
    B -->|Nao| C{Sessoes >= initial_checkpoint?}
    C -->|Nao| Z
    C -->|Sim| D[Busca dados do MongoDB]
    D --> E[Treina XGBoost]
    E --> F[Salva .pkl no MinIO]
    F --> G[Cria model_version]
    G --> H[Promove versao]
    H --> I[Atualiza modelo: trained = true]

2. Check Retrain¶

Frequencia: A cada 6 horas
Condicao: Modelo treinado com need_train = true
Trigger: Quando session_count >= retrain_checkpoint (default: 50.000)

3. Daily Scheduled Training¶

Frequencia: Diariamente as 2:00 AM
Acao: Retreina todos os modelos configurados com dados atualizados

Metricas de Avaliacao¶

Apos cada treinamento, as seguintes metricas sao calculadas e armazenadas:

Metrica	Descricao
Accuracy	Proporcao de predicoes corretas
Precision	Proporcao de verdadeiros positivos entre os preditos positivos
Recall	Proporcao de verdadeiros positivos entre os reais positivos
F1 Score	Media harmonica de precision e recall
AUC	Area sob a curva ROC

Exemplo de metricas:

{
  "accuracy": 0.82,
  "precision": 0.78,
  "recall": 0.85,
  "f1_score": 0.81,
  "auc": 0.89
}

Versionamento¶

Cada treinamento gera uma nova model_version:

graph LR
    M[Model] --> V1[Version 1<br/>DEPRECATED]
    M --> V2[Version 2<br/>DEPRECATED]
    M --> V3[Version 3<br/>READY ativo]

    style V3 fill:#10b981,color:#fff

Operacoes de Versionamento¶

Operacao	Endpoint	Descricao
Listar versoes	`GET /api/v1/models/{id}/versions`	Todas as versoes
Versao ativa	`GET /api/v1/models/{id}/active-version`	Versao em producao
Promover	`POST /api/v1/models/{id}/versions/{vid}/promote`	Tornar versao ativa
Rollback	`POST /api/v1/models/{id}/rollback`	Voltar versao anterior

Fluxo de Predicao¶

sequenceDiagram
    participant T as Tracker API
    participant P as Predict Endpoint
    participant C as Prediction Cache
    participant S3 as MinIO
    participant M as XGBoost Model

    T->>P: POST /api/v1/predict
    P->>C: Busca cache (session_id)

    alt Cache encontrado
        C-->>P: Resultado cacheado
        P-->>T: {cached: true, ...}
    else Primeira predicao
        P->>S3: Carrega modelo (se nao em memoria)
        S3-->>P: Artefato .pkl
        P->>M: predict_proba(features)
        M-->>P: probability
        P->>C: Salva no cache
        P-->>T: {cached: false, probability, should_trigger, ...}
    end

Cache de Modelos¶

Modelos carregados ficam em cache in-memory para evitar I/O repetido ao MinIO
O cache e limpo via POST /api/v1/predict/clear-cache ou ao promover nova versao
Cada datasource tem no maximo 1 modelo em memoria

Cache de Predicoes¶

Predicoes sao armazenadas na tabela prediction_cache (PostgreSQL)
Garante idempotencia: mesma sessao nunca recebe duas predicoes diferentes
Previne re-exibicao de modal apos ja ter sido mostrado

Configuracao¶

Variaveis de Ambiente¶

Variavel	Default	Descricao
`MODEL_TRAIN_THRESHOLD`	10000	Sessoes minimas para 1o treino
`TRAINING_CHECK_INTERVAL`	6	Intervalo de check em horas
`MINIO_ENDPOINT`	localhost:9000	Endpoint do MinIO
`MINIO_ACCESS_KEY`	-	Access key do MinIO
`MINIO_SECRET_KEY`	-	Secret key do MinIO
`MINIO_BUCKET`	oraculo-models	Nome do bucket

Checkpoints por Datasource¶

Cada datasource pode ter checkpoints customizados:

initial_checkpoint (default: 10.000): Numero de sessoes para o primeiro treinamento
retrain_checkpoint (default: 50.000): Numero de novas sessoes para retreinar