Models API (Python FastAPI)¶

Base URL: http://localhost:8000 Tecnologia: Python 3.11+ / FastAPI Autenticacao: Nenhuma (chamada internamente pela Tracker API)

Predicao¶

Fazer Predicao¶

POST /api/v1/predict

Endpoint principal de predicao. Recebe features de uma sessao e retorna a probabilidade de conversao.

Idempotente

Este endpoint e idempotente: a mesma session_id sempre retorna o mesmo resultado. Predicoes sao cacheadas no PostgreSQL para evitar re-predicao apos o modal ser exibido.

Request Body:

{
  "landing_page": "660e8400-e29b-41d4-a716-446655440000",
  "session_id": "abc123-session-id",
  "features": {
    "mouseVelocity": 12.5,
    "scrollDepth": 65,
    "idleTime": 2.3,
    "sessionTime": 45.2,
    "scrollVelocity": 3.2,
    "focusChanges": 2,
    "lastClickedTag": "BUTTON",
    "pageVisibility": "visible"
  }
}

Campo	Tipo	Descricao
`landing_page`	UUID	ID do datasource
`session_id`	string	ID unico da sessao
`features`	object	Features comportamentais extraidas do tracker

Features utilizadas pelo modelo:

Feature	Tipo	Descricao
`mouseVelocity`	float	Velocidade media do mouse (px/s)
`scrollDepth`	int	Profundidade maxima de scroll (0-100%)
`idleTime`	float	Tempo ocioso acumulado (s)
`sessionTime`	float	Tempo total na pagina (s)
`scrollVelocity`	float	Velocidade de scroll (px/s)
`focusChanges`	int	Trocas de foco da janela
`lastClickedTag`	string	Tag HTML do ultimo clique
`pageVisibility`	string	Estado da aba (visible/hidden)

Response 200 OK:

{
  "has_model": true,
  "probability": 0.23,
  "should_trigger": true,
  "modal_html": "<div class='modal'><h2>Espere!</h2></div>",
  "cached": false
}

Campo	Tipo	Descricao
`has_model`	bool	Se existe modelo treinado para o datasource
`probability`	float	Probabilidade de conversao (0.0 a 1.0)
`should_trigger`	bool	Se o modal deve ser exibido
`modal_html`	string	HTML do modal (se `should_trigger = true`)
`cached`	bool	Se o resultado veio do cache

Logica de trigger

should_trigger = true quando:

Existe modelo treinado (has_model = true)
probability < percentageExit / 100 (configurado na Action)
sessionTime >= secondsExit (tempo minimo)
Sessao ainda nao recebeu modal (idempotente)

Response 200 OK (sem modelo):

{
  "has_model": false,
  "probability": null,
  "should_trigger": false,
  "modal_html": null,
  "cached": false
}

Marcar Sessao como Triggered¶

POST /api/v1/predict/mark-triggered/{session_id}

Marca que o modal foi exibido para a sessao. Impede re-exibicao.

Parametro	Tipo	Descricao
`session_id`	string (path)	ID da sessao

Response 200 OK:

{
  "status": "marked",
  "session_id": "abc123"
}

Health da Predicao¶

GET /api/v1/predict/health

Verifica se o servico de predicao esta funcionando.

Limpar Cache de Modelos¶

POST /api/v1/predict/clear-cache

Limpa o cache in-memory dos modelos carregados. Util apos promover nova versao.

Response 200 OK:

{
  "status": "cache_cleared"
}

Estatisticas de Predicao¶

GET /api/v1/predict/stats

Retorna estatisticas de predicoes realizadas.

Response 200 OK:

{
  "total_predictions": 15420,
  "total_triggers": 4626,
  "trigger_rate": 0.30,
  "avg_probability": 0.45,
  "cache_hit_rate": 0.12
}

Gerenciamento de Modelos¶

Listar Modelos¶

GET /api/v1/models

Retorna todos os modelos cadastrados.

Response 200 OK:

[
  {
    "id": "990e8400-e29b-41d4-a716-446655440000",
    "datasource_id": "660e8400-e29b-41d4-a716-446655440000",
    "name": "XGBClassifier_20250115",
    "algorithm": "XGBClassifier",
    "trained": true,
    "need_train": false,
    "last_train": "2025-01-15T02:00:00Z",
    "last_session_count": 15420,
    "created_at": "2025-01-10T10:00:00Z"
  }
]

Criar Modelo¶

POST /api/v1/models

Cria um novo modelo vinculado a um datasource.

Request Body:

{
  "datasource_id": "660e8400-e29b-41d4-a716-446655440000",
  "created_by": "admin"
}

Buscar Modelo¶

GET /api/v1/models/{model_id}

Parametro	Tipo	Descricao
`model_id`	UUID (path)	ID do modelo

Debug de Pre-requisitos¶

GET /api/v1/models/{model_id}/debug

Retorna informacoes de debug sobre os pre-requisitos para treinamento.

Response 200 OK:

{
  "model_id": "990e8400...",
  "datasource_id": "660e8400...",
  "session_count": 8500,
  "initial_checkpoint": 10000,
  "ready_to_train": false,
  "missing_sessions": 1500,
  "has_success_events": true,
  "has_actions": true
}

Treinar Modelo Manualmente¶

POST /api/v1/models/{model_id}/train

Dispara o treinamento manual do modelo.

Parametro	Tipo	Descricao
`model_id`	UUID (path)	ID do modelo

Operacao longa

O treinamento pode levar varios minutos dependendo do volume de dados. O endpoint retorna imediatamente e o treinamento ocorre em background.

Response 202 Accepted:

{
  "status": "training_started",
  "model_id": "990e8400..."
}

Listar Versoes do Modelo¶

GET /api/v1/models/{model_id}/versions

Retorna todas as versoes treinadas do modelo.

Response 200 OK:

[
  {
    "id": "aa0e8400-e29b-41d4-a716-446655440000",
    "model_id": "990e8400...",
    "status": "READY",
    "trained_at": "2025-01-15T02:15:00Z",
    "metrics": {
      "accuracy": 0.82,
      "precision": 0.78,
      "recall": 0.85,
      "f1_score": 0.81,
      "auc": 0.89
    },
    "artifact_path": "660e8400.../990e8400_XGBClassifier_20250115_020000.pkl"
  }
]

Status possiveis da versao:

Status	Descricao
`TRAINING`	Treinamento em andamento
`READY`	Pronto para uso
`DEPRECATED`	Versao antiga substituida
`FAILED`	Treinamento falhou

Versao Ativa do Modelo¶

GET /api/v1/models/{model_id}/active-version

Retorna a versao atualmente em producao.

Promover Versao¶

POST /api/v1/models/{model_id}/versions/{version_id}/promote

Promove uma versao especifica para producao.

Parametro	Tipo	Descricao
`model_id`	UUID (path)	ID do modelo
`version_id`	UUID (path)	ID da versao a promover

Response 200 OK:

{
  "status": "promoted",
  "version_id": "aa0e8400...",
  "previous_version": "bb0e8400..."
}

Rollback de Versao¶

POST /api/v1/models/{model_id}/rollback

Reverte para a versao anterior do modelo.

Parametro	Tipo	Descricao
`model_id`	UUID (path)	ID do modelo

Response 200 OK:

{
  "status": "rolled_back",
  "active_version": "bb0e8400...",
  "previous_version": "aa0e8400..."
}

Setup (Temporario)¶

Criar Action via Setup¶

POST /api/v1/setup/action

Cria uma Action para um datasource. Endpoint auxiliar para setup inicial.

Request Body:

{
  "datasource_id": "660e8400-e29b-41d4-a716-446655440000",
  "seconds_exit": 5,
  "percentage_exit": 30,
  "action": "MODAL",
  "action_value": "<div class='modal'>...</div>"
}

Health & Metricas¶

Root¶

GET /

Retorna informacoes basicas da aplicacao.

{
  "app": "oraculo-models-api",
  "version": "1.0.0",
  "status": "running"
}

Health Check¶

GET /health

Response 200 OK:

{
  "status": "healthy",
  "database": "up",
  "mongodb": "up",
  "scheduler": "running",
  "uptime": "2d 14h 32m"
}

Metricas Prometheus¶

GET /metrics

Retorna metricas no formato Prometheus.