Agent Loop - Implementação Completa

✅ Status: Implementado e Funcional

Todos os 4 itens do Agent Loop foram implementados e aplicados ao CSuite.

📊 Componentes Implementados

1️⃣ Job Automático de Detecção

Objetivo: Detectar decisões sem snapshot e monitorar saúde do Agent Loop.

Componentes:
- View: vw_decisions_missing_snapshot - Lista decisões sem snapshot categorizadas por idade
- View: vw_agent_loop_health - Métricas consolidadas de saúde do loop
- Procedure: sp_ctx_detect_missing_snapshots - Detecção parametrizável de gaps
- Script: scripts/agent_loop_detection_job.py - Job Python para execução periódica

Arquivo: sql/14_agent_loop_detection_job.sql

Uso:

python3 scripts/agent_loop_detection_job.py

Cron Job (opcional):

# Executar a cada hora
0 * * * * cd /path/to/c-suite && python3 scripts/agent_loop_detection_job.py

2️⃣ Alimentar csuite_memory usando vw_decision_timeline

Objetivo: Criar precedentes automaticamente a partir de decisões com outcomes observados.

Componentes:
- Procedure: sp_ctx_feed_memory_from_timeline - Processa decisões e cria precedentes

Arquivo: sql/15_agent_loop_memory_feed.sql

Uso:

CALL csuite_memory.sp_ctx_feed_memory_from_timeline(
  0,      -- org_id (0 = todas)
  7,      -- days_back (últimos 7 dias)
  100,    -- limit (máximo 100 decisões)
  'system' -- actor
);

O que faz:
- Busca decisões com outcomes observados na vw_decision_timeline
- Cria itens de precedente em mm_item (layer='PRECEDENTS', type='DECISION_OUTCOME')
- Armazena contexto completo do snapshot JSON
- Vincula precedente à decisão original

Cron Job (opcional):

-- Executar diariamente às 03:00
CREATE EVENT IF NOT EXISTS evt_feed_memory_from_timeline
ON SCHEDULE EVERY 1 DAY STARTS '2024-01-01 03:00:00'
DO
  CALL csuite_memory.sp_ctx_feed_memory_from_timeline(0, 7, 100, 'system');

3️⃣ UI Decision Timeline

Objetivo: Interface visual para explorar o Flight Recorder completo do CSuite.

Componentes:
- Endpoint UI: /executive/decision-timeline
- Endpoint API: /api/executive/decision-timeline
- Template: csuite-gateway/app/templates/decision_timeline.html

Arquivos:
- csuite-context/approot/app/routers/executive_dashboard.py - Endpoints API
- csuite-gateway/app/main.py - Rotas UI e proxy API
- csuite-gateway/app/templates/decision_timeline.html - Template HTML

Funcionalidades:
- Visualização em timeline de todas as decisões
- Filtros por policy, entity_type, entity_ref
- Estatísticas de cobertura (snapshot, outcome)
- Visualização de contexto JSON (snapshot)
- Badges de status (SUCCESS, FAILURE, PENDING)

Acesso:

https://csuite.internut.com.br/executive/decision-timeline

4️⃣ Policy Decay / Tuning Integration

Objetivo: Detectar decay de políticas e auto-tuning baseado em outcomes do Decision Timeline.

Componentes:
- View: vw_policy_decay_from_timeline - Análise de decay por política
- Procedure: sp_ctx_detect_decay_from_timeline - Detecta decay e cria casos
- Procedure: sp_ctx_autotune_from_timeline - Auto-tuning baseado em métricas

Arquivo: sql/16_agent_loop_policy_decay_integration.sql

View - vw_policy_decay_from_timeline:

SELECT * FROM csuite_memory.vw_policy_decay_from_timeline
WHERE org_id = 0
ORDER BY decay_score ASC, success_rate_pct ASC;

Métricas calculadas:
- total_decisions - Total de decisões analisadas
- decisions_with_outcome - Decisões com outcome observado
- success_count / failure_count - Contadores de sucesso/falha
- avg_delta_score - Delta médio (quanto maior, melhor)
- success_rate_pct - Taxa de sucesso (%)
- decay_score - Score de decay (1=crítico, 2=moderado, 5=sem decay)

Procedure - Detectar Decay:

CALL csuite_memory.sp_ctx_detect_decay_from_timeline(
  0,      -- org_id
  2,      -- decay_threshold (1=crítico, 2=moderado)
  'system' -- actor
);

O que faz:
- Analisa políticas usando vw_policy_decay_from_timeline
- Cria casos em pg_case quando decay é detectado
- Tipo de caso: 'ALERT'
- Source rule: 'PG_POLICY_DECAY_DETECTED'

Procedure - Auto-tuning:

-- Dry run (apenas sugere mudanças)
CALL csuite_memory.sp_ctx_autotune_from_timeline(
  0,              -- org_id
  'INV_LOW_TURN', -- policy_code
  1,              -- dry_run (1=sim, 0=aplicar)
  'system'        -- actor
);

-- Aplicar tuning
CALL csuite_memory.sp_ctx_autotune_from_timeline(
  0,              -- org_id
  'INV_LOW_TURN', -- policy_code
  0,              -- dry_run (0=aplicar)
  'system'        -- actor
);

Lógica de tuning:
- Taxa de sucesso < 30%: Aumenta severity (mais restritivo)
- Taxa de sucesso > 80% e delta positivo: Diminui severity (menos restritivo)
- Caso contrário: Mantém severity atual

Cron Job (opcional):

-- Detectar decay semanalmente (Quarta, 06:30)
CREATE EVENT IF NOT EXISTS evt_detect_decay_from_timeline
ON SCHEDULE EVERY 1 WEEK STARTS '2024-01-03 06:30:00'
DO
  CALL csuite_memory.sp_ctx_detect_decay_from_timeline(0, 2, 'system');

-- Auto-tuning semanal (Quinta, 07:00) - dry run primeiro
CREATE EVENT IF NOT EXISTS evt_autotune_from_timeline
ON SCHEDULE EVERY 1 WEEK STARTS '2024-01-04 07:00:00'
DO
  -- Lista políticas e faz dry run
  -- (pode ser expandido para iterar sobre todas as políticas)
  CALL csuite_memory.sp_ctx_autotune_from_timeline(0, 'INV_LOW_TURN', 1, 'system');

🔄 Fluxo Completo do Agent Loop

1. Decisão é tomada (Policy Engine)
   ↓
2. Snapshot de contexto é criado automaticamente
   (sp_ctx_snapshot_decision_context via instrumentation.py)
   ↓
3. Outcome é observado e registrado
   (ctx_policy_outcomes)
   ↓
4. Decision Timeline une tudo
   (vw_decision_timeline)
   ↓
5. Memory Feed cria precedentes
   (sp_ctx_feed_memory_from_timeline)
   ↓
6. Policy Decay é detectado
   (sp_ctx_detect_decay_from_timeline)
   ↓
7. Auto-tuning ajusta políticas
   (sp_ctx_autotune_from_timeline)
   ↓
8. Loop fecha: próxima decisão usa política ajustada

📈 Métricas e Monitoramento

Health Metrics

SELECT * FROM csuite_context.vw_agent_loop_health;

Campos:
- total_decisions - Total de decisões
- decisions_with_snapshot - Com snapshot
- decisions_with_outcome - Com outcome
- snapshot_coverage_pct - % cobertura de snapshot
- outcome_coverage_pct - % cobertura de outcome

Missing Snapshots

SELECT * FROM csuite_context.vw_decisions_missing_snapshot
WHERE age_category = 'RECENT'
ORDER BY hours_since_decision ASC;

Policy Decay

SELECT 
  policy_code,
  decay_score,
  success_rate_pct,
  avg_delta_score,
  total_decisions
FROM csuite_memory.vw_policy_decay_from_timeline
WHERE org_id = 0
  AND decay_score <= 2  -- Crítico ou moderado
ORDER BY decay_score ASC, success_rate_pct ASC;

🎯 Próximos Passos (Opcionais)

1. Backfill de Snapshots Antigos
2. Criar script para gerar snapshots retroativos de decisões antigas

3. Usar dados disponíveis em pg_decision_log e ctx_policy_outcomes

4. Alertas Automáticos

5. Integrar agent_loop_detection_job.py com sistema de alertas

6. Enviar notificações quando cobertura < 95%

7. Dashboard Executivo

8. Adicionar card de "Agent Loop Health" no Policy Radar Executivo

9. Mostrar métricas de cobertura e decay

10. Machine Learning

11. Usar vw_decision_timeline para treinar modelos de predição
12. Prever sucesso/falha de decisões antes de executar

📚 Referências

• Agent Loop Implementation: docs/AGENT_LOOP_IMPLEMENTATION.md
• Agent Loop Integration: docs/AGENT_LOOP_INTEGRATION.md
• Agent Loop Detection Job: docs/AGENT_LOOP_DETECTION_JOB.md
• Decision Timeline View: sql/13_agent_loop_decision_context.sql
• Memory Feed: sql/15_agent_loop_memory_feed.sql
• Policy Decay Integration: sql/16_agent_loop_policy_decay_integration.sql

✅ Checklist de Implementação

• [x] Job automático de detecção
• [x] Alimentação do csuite_memory
• [x] UI Decision Timeline
• [x] Policy decay/tuning integration
• [x] Documentação completa
• [x] SQLs aplicados no banco
• [x] Endpoints API criados
• [x] Template HTML criado

Status: ✅ COMPLETO E FUNCIONAL