CAIO Agent - Documentação Completa

📋 Visão Geral

O CAIO Agent (Chief AI Officer) é um agente executivo do CSuite que governa uso de IA e modelos ML. Ele monitora performance de modelos, detecta drift, gerencia testes A/B e avalia governança de IA.

Status: ✅ Implementado (v1.0.0) - Pronto para uso

🎯 Propósito

O CAIO Agent existe para:

Monitorar Performance: Acompanhar accuracy, precision, recall de modelos ML
Detectar Drift: Identificar data drift e concept drift em modelos
Gerenciar A/B Testing: Monitorar testes A/B e promover modelos de staging
Governar IA: Avaliar políticas, compliance e ética de uso de IA
Proteger Qualidade: Garantir que modelos ML mantenham qualidade em produção

🏗️ Arquitetura

Fluxo de Execução

1. Recebe Payload
   ↓
2. Build Context
   ├─ Model Performance (accuracy, precision, recall)
   ├─ Drift Detection (data drift, concept drift)
   ├─ A/B Testing Status (staging models, active tests)
   ├─ AI Governance (policies, compliance, ethics)
   └─ Memory Query (precedentes de IA)
   ↓
3. Determine Decision Type
   ├─ CAIO.ALERT_DRIFT (alerta de drift)
   ├─ CAIO.PAUSE_MODEL (pausar modelo degradado)
   ├─ CAIO.PROMOTE_MODEL (promover modelo de staging)
   └─ CAIO.REQUIRE_RETRAIN (exigir retreinamento)
   ↓
4. Calculate Confidence
   ↓
5. Propose Actions
   ├─ ALERT_DRIFT
   ├─ PAUSE_MODEL
   ├─ PROMOTE_MODEL
   └─ REQUIRE_RETRAIN
   ↓
6. Policy Validation
   ↓
7. Policy Engine Integration
   ↓
8. Execute Actions
   ↓
9. Record Outcome

Componentes

YAML Config: agents/caio/caio_agent.yaml - Configuração canônica
Script Python: workflows/scripts/caio_agent_daily_brief.py - Execução diária
Cron Setup: workflows/scripts/setup_cron_caio.sh - Configuração de cron

🔌 Integrações

1. Model Registry

Base URL: https://csuite.internut.com.br/model-registry

Endpoint	Descrição	Uso
`GET /models`	Listar modelos	Performance de modelos
`GET /models/{model_name}/versions`	Versões de modelo	A/B testing
`POST /models/{model_name}/versions/{version}/activate`	Ativar versão	Promoção de modelo

2. Policy Engine

Base URL: https://csuite.internut.com.br/executive

Endpoint	Descrição	Uso
`POST /v1/policy/evaluate`	Avaliar decisão	Validação de políticas de IA
`GET /v1/governance/policies/radar`	Policy Radar	Políticas de IA

3. Executive API

Base URL: https://csuite.internut.com.br/executive

Endpoint	Descrição	Uso
`POST /v1/memory/query`	Consultar memória	Precedentes de governança de IA

4. 4C (Modelos ML)

Base URL: https://csuite.internut.com.br/4c

Endpoint	Descrição	Uso
`GET /api/health`	Health check	Status dos modelos
`GET /api/scoring`	Scoring	Performance em produção

5. Feature Store (Opcional)

Base URL: https://csuite.internut.com.br/feature-store

Endpoint	Descrição	Uso
`GET /api/features`	Listar features	Feature drift
`GET /api/features/drift`	Drift de features	Detecção de drift

📥 Payload de Entrada

Formato Padrão

{
  "org_id": 0,
  "as_of_date": "2025-01-04",
  "time_window_days": 7,
  "focus": {
    "themes": ["model_performance", "drift_detection", "ab_testing", "ai_governance"],
    "constraints": []
  },
  "attention": {
    "max_recommendations": 3,
    "max_output_tokens": 1200
  }
}

Campos

Campo	Tipo	Obrigatório	Descrição
`org_id`	integer	✅	ID da organização
`as_of_date`	string	✅	Data de referência (YYYY-MM-DD)
`time_window_days`	integer	❌	Janela de análise (padrão: 7)
`focus.themes`	array	❌	Temas de foco
`attention.max_recommendations`	integer	❌	Máximo de recomendações (padrão: 3)

📤 Payload de Saída

Formato Padrão

{
  "decision": {
    "decision_type": "CAIO.ALERT_DRIFT | CAIO.PAUSE_MODEL | CAIO.PROMOTE_MODEL | CAIO.REQUIRE_RETRAIN",
    "confidence": 0.85,
    "proposed_actions": [
      {
        "action": "ALERT_DRIFT",
        "model_name": "intent",
        "reason": "Drift detectado no modelo intent",
        "severity": "medium"
      }
    ]
  },
  "context": {
    "model_performance": {
      "summary": "Resumo de performance",
      "models_status": [],
      "performance_trends": []
    },
    "drift_analysis": {
      "drift_detected": false,
      "models_affected": [],
      "drift_severity": "none | low | medium | high"
    },
    "ab_testing_status": {
      "active_tests": [],
      "staging_models": [],
      "promotion_candidates": []
    },
    "ai_governance": {
      "compliance_score": 0.95,
      "policies_status": [],
      "risks": []
    }
  },
  "execution": {
    "status": "completed",
    "actions": []
  },
  "opportunities": [
    {
      "type": "ALERT_DRIFT",
      "description": "Drift detectado no modelo intent",
      "impact": "alto | médio | baixo",
      "confidence": 0.85,
      "model_name": "intent"
    }
  ],
  "recommendations": [
    {
      "action": "Pausar modelo intent e exigir retreinamento",
      "reason": "Drift severo detectado",
      "priority": "alta",
      "ai_impact": "alto"
    }
  ],
  "next_steps": [
    "Revisar modelo intent",
    "Executar retreinamento",
    "Validar novo modelo em staging"
  ],
  "generated_at": "2025-01-04T08:40:00",
  "org_id": 0,
  "as_of_date": "2025-01-04"
}

🔄 Decision Types

CAIO.ALERT_DRIFT

Descrição: Alerta de drift detectado em modelo

Condições:
- Drift detectado (data drift ou concept drift)
- Severidade: medium ou high
- Confidence >= 0.8

Ações:
- ALERT_DRIFT: Enviar alerta
- REQUIRE_RETRAIN: Exigir retreinamento (se severidade alta)

CAIO.PAUSE_MODEL

Descrição: Pausar modelo com performance degradada

Condições:
- Performance abaixo do threshold
- Drift severo detectado
- Confidence >= 0.7

Ações:
- PAUSE_MODEL: Pausar modelo em produção
- REQUIRE_RETRAIN: Exigir retreinamento

CAIO.PROMOTE_MODEL

Descrição: Promover modelo de staging para produção

Condições:
- Modelo em staging com performance superior
- A/B testing concluído com sucesso
- Confidence >= 0.9

Ações:
- PROMOTE_MODEL: Ativar versão em produção
- ARCHIVE_OLD_MODEL: Arquivar versão antiga

CAIO.REQUIRE_RETRAIN

Descrição: Exigir retreinamento de modelo

Condições:
- Performance degradada
- Drift severo
- Modelo desatualizado
- Confidence >= 0.7

Ações:
- REQUIRE_RETRAIN: Exigir retreinamento
- PAUSE_MODEL: Pausar modelo (se necessário)

🎛️ Autonomia

Níveis de Autonomia

Nível	Descrição	Condição
L0	Sempre recomendação	`PAUSE_MODEL`, `REQUIRE_RETRAIN`, ou `confidence < 0.7`
L1	Alerta automático	`ALERT_DRIFT` e `confidence >= 0.8`
L2	Promoção automática	`PROMOTE_MODEL` e `confidence >= 0.9`

⚙️ Configuração

Variáveis de Ambiente

# LLM
OPENAI_API_KEY=sk-...
LLM_MODEL=gpt-4o-mini

# CSuite Services
CSUITE_POLICY_ENGINE_URL=https://csuite.internut.com.br/executive
CSUITE_EXECUTIVE_URL=https://csuite.internut.com.br/executive
CSUITE_MODEL_REGISTRY_URL=https://csuite.internut.com.br/model-registry
CSUITE_4C_URL=https://csuite.internut.com.br/4c
CSUITE_MEMORY_URL=https://csuite.internut.com.br/executive
CSUITE_FEATURE_STORE_URL=https://csuite.internut.com.br/feature-store

# Webhook
CAIO_BRIEF_WEBHOOK_URL=https://hooks.slack.com/services/...

# Configuração
ORG_ID=0
TIME_WINDOW_DAYS=7

Cron Job

O CAIO Agent executa diariamente às 08:40:

cd workflows/scripts
./setup_cron_caio.sh

Cron Entry:

10 8 * * * cd /path/to/workflows/scripts && /usr/bin/python3 caio_agent_daily_brief.py >> logs/caio_agent_cron.log 2>&1

🚀 Uso

Execução Manual

cd workflows/scripts
python3 caio_agent_daily_brief.py

Output

O brief é publicado no Slack e salvo em arquivo JSON:

caio_brief_YYYYMMDD_HHMMSS.json

Formato do Brief no Slack

O brief é formatado com:
- Header com status de drift (🔴 se detectado, 🟢 se não)
- Contexto de governança de IA
- Performance de modelos
- Análise de drift
- Oportunidades identificadas
- Recomendações prioritárias
- Próximos passos

📊 Modelos Monitorados

O CAIO Agent monitora os seguintes modelos do 4C:

intent - Modelo de intenção de compra
offer - Modelo de recomendação de oferta
channel - Modelo de seleção de canal
timing - Modelo de timing de contato

🔍 Métricas Monitoradas

Performance de Modelos

Accuracy: Taxa de acerto geral
Precision: Precisão (TP / (TP + FP))
Recall: Recall (TP / (TP + FN))
F1-Score: Média harmônica de precision e recall
AUC-ROC: Área sob a curva ROC

Drift Detection

PSI (Population Stability Index): Medida de drift de distribuição
KS Statistic: Kolmogorov-Smirnov test
Severity: none, low, medium, high

A/B Testing

Staging Models: Modelos em staging aguardando promoção
Active Tests: Testes A/B ativos
Promotion Candidates: Modelos candidatos a promoção

🛠️ Troubleshooting

Erro: "OPENAI_API_KEY não configurada"

Solução: Configure a variável de ambiente OPENAI_API_KEY ou LLM_API_KEY.

Erro: "Model Registry retornou 404"

Solução: Verifique se o csuite-model-registry está rodando e acessível.

Erro: "Drift detection não disponível"

Solução: Integre com scripts/ml_pipeline/monitor_drift.py para detecção completa de drift.

Brief não publicado no Slack

Solução:
1. Verifique se CAIO_BRIEF_WEBHOOK_URL está configurada
2. Verifique se o webhook do Slack está válido
3. Verifique logs em caio_agent.log

📚 Referências

YAML Config: agents/caio/caio_agent.yaml
Script Python: workflows/scripts/caio_agent_daily_brief.py
README: agents/caio/README.md
Model Registry Guide: docs/guides/GUIA_USO_APIS_MODEL_REGISTRY.md
ML Pipeline: scripts/ml_pipeline/README.md

Última atualização: 2025-01-04

CAIO Agent - Documentação Completa

📋 Visão Geral

🎯 Propósito

🏗️ Arquitetura

Fluxo de Execução

Componentes

🔌 Integrações

1. Model Registry

2. Policy Engine

3. Executive API

4. 4C (Modelos ML)

5. Feature Store (Opcional)

📥 Payload de Entrada

Formato Padrão

Campos

📤 Payload de Saída

Formato Padrão

🔄 Decision Types

CAIO.ALERT_DRIFT

CAIO.PAUSE_MODEL

CAIO.PROMOTE_MODEL

CAIO.REQUIRE_RETRAIN

🎛️ Autonomia

Níveis de Autonomia

⚙️ Configuração

Variáveis de Ambiente

Cron Job

🚀 Uso

Execução Manual

Output

Formato do Brief no Slack

📊 Modelos Monitorados

🔍 Métricas Monitoradas

Performance de Modelos

Drift Detection

A/B Testing

🛠️ Troubleshooting

Erro: "OPENAI_API_KEY não configurada"

Erro: "Model Registry retornou 404"

Erro: "Drift detection não disponível"

Brief não publicado no Slack

📚 Referências

🔊 Text-to-Speech