Intelligence (Cérebro/Observatório)

Status: 🟢 Estável (Sprints 1.A → 2.A deployadas) Code: backend/app/modules/intelligence UI: frontend/src/app/(admin)/[slug]/admin/intelligence Última revisão deste doc: 2026-05-13 por Felipe + Claude Dependências fortes: whatsapp + crm + email + business + diary (lê dados crus L0); council + agents (consomem L1/L3/L5); tenant_router (multi-tenant)

1. Identidade

O que faz (uma frase)

Observatório do negócio: agrega dados crus dos módulos (whatsapp, crm, email, business, diary), calcula atributos por contato (L1), descobre padrões persistentes (L3), registra observações de IA (L5), e expõe tudo via tools que Conselho e Agentes consomem para tomar decisões com evidência.

Por que existe (negócio)

Sem Intelligence, cada decisão de IA seria stateless e estatisticamente cega:

• Conselheiro responderia "como vai a saúde do cliente?" sem ter um score calculado.
• Agente Hari não saberia que o lead já desistiu 3x antes de responder a 4ª.
• Felipe não veria padrões tipo "no-show de yoga sempre na segunda manhã" sem ter alguém olhando.

A camada Intelligence resolve isso operando como observatório passivo + analítico ativo:

• Atributos por contato (L1): churn_risk_score, engagement_score, ltv, tags comportamentais — tudo calculado e cacheado.
• Padrões (L3): "campanhas com vídeo convertem 3x mais que com imagem" — discovered via causality sub-agent.
• Insights pontuais (L2): anomalias, sumários, crisis detection.
• Observações de IA (L5): log do que o Conselho/Agente viu antes de cada decisão (auditabilidade).

Por que existe (técnico)

Intelligence é o agregador-único entre módulos. Sem ele:

• CRM teria que importar whatsapp.message, email.send, billing.invoice (acoplamento).
• Conselho/Agentes refariam queries pesadas em cada turn (sem cache).
• Sem padrão pra "explicabilidade" — cada módulo inventaria seu jeito.

Como módulo dedicado:

• Refresh determinístico com formula_version + inputs_hash (skip se nada mudou).
• Provenance nativo — confidence, churn_explanation, health_explanation, at_risk_reason em cada atributo.
• Catálogo de behavior tags universal: dormant, new_lead, objection_open, no_show_chronic, at_risk_customer, repeat_buyer, etc.
• Append-only history (contact_attribute_history) pra reconstruir trajetória.
• Tools cross-módulo que Conselho usa direto sem precisar entender 7 schemas diferentes.

Status atual

• Sprint 1.A deployada (2026-05-13) — atribuição (campaign + touchpoint + crm_contact.attribution_*, mig 0094). emit_event em council/diary/whatsapp delivered/read/reaction.
• Sprint 1.B + 1.C deployadas (2026-05-13) — alembic 0095+0096. L1 contact_attribute (3758 rows mais-consciente), L3 intelligence_pattern, L5 brain_observation, sub-agent causality, 13 tools novas no Council. Telas /admin/intelligence/{contact-attributes,patterns,observations}.
• Sprint 2.A "Contact OS" deployada (2026-05-13) — alembic 0101 + commit c8ca39e2. L1 ganhou provenance (formula_version, inputs_hash, confidence), explainability nativa, 4 tags novas, refresh v2 cruzando objections+price_inquiry+appointment, skip-on-no-change, contact_attribute_history append-only, tool Council read_contact_attribute_history, endpoint /health do catálogo, UI estendida. Validado em 3758 contatos mais_consciente.

Próxima mudança planejada: L4 (truth) implementação completa (regras derivadas em runtime); embeddings para knowledge_entry busca semântica.

2. Cases de uso reais

Case 1: Conselho responde "como está minha taxa de churn?"

Situação: Felipe pergunta no Conselho.

Fluxo:

1. CEO chama tool read_intelligence_insights(severity=warning, sub_agent=churn_detection).
2. Tool roda cross_module.list_intelligence_insights → retorna últimos N insights de churn.
3. Brain monta resposta narrativa: "X contatos em risco crítico, top 3 razões: dormant, objection_open, low_engagement..."
4. Mostra contatos específicos via read_contact_attributes(behavior_tag='at_risk_customer', limit=10).

Impacto: Felipe entende health do negócio sem abrir 5 telas de CRM.

Case 2: Agente Hari evita oferecer produto a contato com objection_open

Situação: Lead tem objeção registrada ("preço alto") em product X, agora pergunta sobre product Y.

Fluxo:

1. Brain de Hari chama read_contact_objections(contact_id, unresolved_only=True).
2. Detecta objeção aberta.
3. Brain ajusta resposta: cita product Y mas aborda objeção de preço primeiro ("entendo que valor era preocupação...").

Impacto: Conversão não morre por agente "robô" ignorando histórico.

Case 3: Padrão descoberto pelo causality sub-agent

Situação: Causality roda diariamente, snapshot de cohorts × outcomes.

Fluxo:

1. causality.discover_patterns(tenant_id) coleta:
   • Campaign cohorts → conversão
   • Channel analysis → engagement
   • Product affinity → cross-sell
   • Objection distribution
   • Appointment patterns (no-show por weekday/hour)
   • Churn signals
2. Manda JSONs estruturados (não dados crus de pessoa) pro Claude.
3. Claude retorna padrões com evidência: {kind, scope_kind, title, evidence: {metric, comparison, base}, confidence, sample_size, severity}.
4. Persiste em intelligence_pattern com status=provisional, discovered_by=causality.
5. Felipe revê em /admin/intelligence/patterns, marca confirmed ou invalidated.

Exemplo real: "Yoga no-show 60% segunda 9h vs 12% terça 19h" (n=42, confidence=0.85).

Impacto: Felipe descobre padrões que jamais identificaria manualmente; ajusta horários, comunicação, oferta.

Case 4: Refresh L1 hora a hora — provenance + skip-on-no-change

Situação: Beat refresh_contact_attributes (30min).

Fluxo:

1. Pega N contatos do tenant (limit 5000 default).
2. Pra cada contato: ~16 queries determinísticas (engagement_30d, ltv, quote_count, purchase_count, objections, price_inquiries, appointments, last_touch).
3. Calcula scores: churn_risk_score, relationship_health_score, engagement_score_*.
4. Calcula inputs_hash = sha256(snapshot_estável).
5. Compara com inputs_hash anterior:
   • Igual → atualiza só refreshed_at (skip materializar).
   • Diferente → recalcula tudo + grava novos atributos + insere em contact_attribute_history (mudanças materiais).
6. confidence proporcional a volume de sinais.
7. churn_explanation + health_explanation: lista de fatores ponderados.

Impacto: 3758 contatos refreshados em 2-5s; ~70% skip materializar; histórico append-only permite reconstruir trajetória.

3. Oportunidades de negócio

• Vender Intelligence como camada standalone: "Mandir Insights" (subset com L1+L3+L5) para empresas que já têm CRM/WhatsApp próprios mas querem atribuição + patterns + churn risk como API.
• Causality como produto premium: descoberta automática de padrões via Claude — "pague por padrão confirmado". Diferencial sobre BIs tradicionais (Looker, Metabase) que só mostram, não descobrem.
• Compliance LGPD: explainability nativa (churn_explanation, etc.) é argumento legal. "Por que você está em risco?" → resposta auditável.
• Marketplace de patterns por vertical: padrões descobertos em e-commerce funcionam pra outros e-commerces. Anonimização + share + adapt.
• Predição como serviço: ChurnAttribute → predição de churn em 90d com confidence. API pricing por inferência.
• Brain Observatory cross-tenant (L5): insights agregados (anonimizados) ajudam o Mandir a melhorar produto. Telemetria opt-in.

Riscos comerciais:

• Custo LLM em escala (causality + crisis_detection rodam por tenant).
• Privacy: refresh de L1 lê dados sensíveis — LGPD exige consentimento + auditoria.
• Padrões "óbvios" que Claude vai inventar sem cuidado (mitigação: confidence ≤ 0.3 se sample_size < 10).

4. Arquitetura interna

Camadas L0-L5 (Brain Observatory)

L0 — Cru (vive em outros módulos)
   whatsapp_message, crm_deal, email_send, contact_touchpoint,
   product_objection, price_inquiry, appointment, campaign

   ↓ refresh_contact_attributes (Beat 30min)

L1 — Atributos por contato (contact_attribute)
   scores, tags, provenance, recência, explanations

   ↓ scoring/threshold rules

L2 — Insights pontuais (intelligence_insight)
   summary, anomaly, crisis_detection, churn_detection

   ↓ causality sub-agent (LLM)

L3 — Padrões persistentes (intelligence_pattern)
   cohort_behavior, cross_channel_correlation, no_show_pattern, ...

   ↓ regras derivadas em runtime

L4 — Verdade (não persistida — TBD)
   "se churn_risk ≥ 70 then contato em risco"

   ↓ logged when consulted

L5 — Observações de IA (brain_observation)
   "advisor X consultou Y antes de decidir Z"

Arquivos do módulo

Tasks Celery (Beat schedule)

Todas usam tenant_router.worker_session(tenant_id) (NullPool por task).

5. Tabelas + relacionamentos (7)

intelligence_insight (L2)

Descobertas pontuais por sub-agent.

Índices: (tenant, severity), (tenant, sub_agent), (tenant, subject_type, subject_id).

intelligence_segment + intelligence_segment_member

Segmentos dinâmicos.

intelligence_segment: slug (UQ), name, criteria JSONB, member_count, is_active, refreshed_at. intelligence_segment_member: segment_id, contact_id, added_at — materializado por beat 05:00 UTC.

contact_attribute (L1) ⭐

Atributos agregados por contato.

Índices: (tenant, churn_risk_score DESC), (tenant, relationship_health_score DESC), (tenant, engagement_score_30d DESC), (tenant, last_interaction_at DESC).

contact_attribute_history (append-only)

Mudanças materiais ao longo do tempo.

Quando escreve: Δ ≥ 10 em scores trackeados; tag add/remove; primeira vez (first_value). Índices: (tenant, contact, time), (tenant, attribute, time).

intelligence_pattern (L3)

Padrões persistentes descobertos.

Índices: (tenant, kind), (tenant, status), (tenant, scope_kind, scope_id).

brain_observation (L5)

Log do que IA observou antes de cada decisão.

Relacionamentos cross-módulo

6. API / Endpoints (29+)

Prefixo /api/intelligence.

Insights (L2)

Segments (Dinâmicos)

Contact Attributes (L1)

Patterns (L3)

Observations (L5)

Chat Query (LLM Tool Use)

WhatsApp Intelligence

7. Sub-agentes

8. Contact Attribute (L1) — Refresh Pipeline

Princípios cravados (Sprint 2.A):

1. formula_version: cada linha carrega versão (v2 atual). Bump força reprocessamento com force=true.
2. inputs_hash: sha256 de snapshot estável (eng, ltv, quote_count, purchase_count, appt_count, ns_count, churn_risk, health_score, tags, at_risk_reason, last_int_at, last_pur_at). Idêntico → skip materializar (atualiza apenas refreshed_at).
3. confidence: 0..1 baseado em volume de sinais (wa_in, wa_out, purchases, touches).
4. Explicabilidade: churn_explanation + health_explanation são dicts com fatores ponderados — UI mostra "por que risco?"

Catálogo de behavior tags

Heurísticas de scoring (determinísticas, sem LLM)

• engagement_score = wa_in×3 + wa_out×2 + email_open×1 + email_click×4, capped 100
• churn_risk_score (0-100):
  • eng_30 crítico (+30)
  • eng_90 queda (-20)

  • 60d sem interação (+20)

  • customer sem compra 180d (+15)
  • objeção aberta (+10)
  • no_show_rate ≥ 0.3 (+12)
• relationship_health_score (0-100):
  • Baseline 40
  • eng_30 ≥ 40 (+25)
  • comprou (+15)
  • 3+ compras (+10)
  • objeção aberta (-15)
  • no_show_rate ≥ 0.3 (-10)

  • 30d sem interação (-10)

History (append-only)

• TRACKED_SCORES: engagement_score_30d, churn_risk_score, relationship_health_score → entry quando Δ ≥ 10.
• Tags: entry em cada add/remove.
• delta_kind: first_value, score_jump_up, score_jump_down, tag_added, tag_removed.

Performance (3758 contatos)

• ~16 queries totais por refresh (paralelo-friendly).
• Batch upsert via pg_insert.on_conflict_do_update.
• Skip-on-no-change: ~70% das linhas pulam materialização.
• ~2-5s por 5000 contatos.

9. Patterns (L3) — Causality Sub-Agent

Snapshots coletados:

1. campaign_cohorts — por campanha → n contatos, deals_won, deals_lost, ltv, avg eng/churn/health.
2. channel_analysis — por canal (YouTube, IG, Email, Ads) → similar.
3. product_affinity — produtos comprados juntos.
4. objection_distribution — categorias em deals won vs lost.
5. appointment_patterns — no-show por weekday/hour.
6. churn_signals — contatos com churn_risk alto + engagement queda.

Prompt do Claude (causality.py):

Recebe JSONs estruturados (nunca dados crus de pessoa). Pede "padrões com evidência estatística". Retorna array:

{
  "kind": "cohort_behavior|cross_channel_correlation|temporal|...",
  "scope_kind": "global|cohort|contact|campaign|product|segment|channel",
  "scope_id": "uuid-if-applicable",
  "title": "≤80 chars",
  "description_md": "2-4 linhas pt-BR com números",
  "severity": "info|warning|critical|opportunity",
  "confidence": 0..1,
  "sample_size": int,
  "evidence": {"metric": "...", "comparison": "62% vs 8%", "base": "n=42"}
}

Regras firmes:

• confidence ≤ 0.3 se sample_size < 10.
• Nunca inventar números.
• Citar na descrição: base (n=X) e efeito (Y% vs Z%).

10. Brain Observation (L5)

Estrutura (planejado para cross-tenant via mandir-events, hoje só log estruturado):

• advisor_slug — qual agente/conselheiro consultou intelligence.
• conversation_id, message_id, contact_id — contexto.
• trigger_kind — contact_pre_interaction, campaign_launch_eligibility, diary_engagement.
• observed_facts (JSONB) — {contact_engagement: 75, churn_risk: 42, last_interaction_days: 3}.
• patterns_used — IDs de patterns consultados.
• decision_md — raciocínio em markdown.

Exemplos:

• "Luciano cota 7 no vídeo Yoga" — contact_id=luciano, observed_facts={sentiment: "positive", engagement_topic: "yoga"}, trigger_kind="diary_engagement".
• "Yoga no-show segunda-manhã 60%" — padrão global, scope_kind="global", observed_facts={no_show_bucket: "weekday_0_hour_09", rate: 0.60}.

11. Configuração

Env vars

Settings flags (planejados — TODO)

• INTELLIGENCE_LLM_ENABLED (master switch para sub-agentes LLM)
• INTELLIGENCE_REFRESH_ENABLED (pause refresh em deploy)
• INTELLIGENCE_CONTACT_ATTRIBUTE_FORCE_VERSION (bump formula)

12. Operações

Como rodar refresh ad-hoc

# Forçar refresh de tudo (ignora hash)
curl -X POST '/api/intelligence/contact-attributes/refresh?force=true'

# Refresh limit 100
curl -X POST '/api/intelligence/contact-attributes/refresh?limit=100'

Como descobrir patterns

curl -X POST '/api/intelligence/run/causality'
# Verifica /admin/intelligence/patterns
# Marca confirmed/invalidated

Troubleshooting

Sintoma: ContactAttribute desatualizado

Diagnóstico:

SELECT MAX(refreshed_at), COUNT(*) FROM contact_attribute;

Fix: verificar Beat refresh_contact_attributes rodando (docker logs mandir-suite-beat).

Sintoma: Padrão "óbvio" / inventado

Causa: Claude inventando sem evidence forte. Fix: verificar confidence e sample_size. Se baixo, marcar invalidated na UI.

Sintoma: Custo LLM crescendo

Causa: crisis_detection ou causality rodando muito. Fix: ajustar Beat schedule; usar model_tier=fast (Haiku) onde possível.

13. Métricas e observabilidade

Logs estruturados-chave

14. Limitações e débitos técnicos conhecidos

15. Histórico relevante

• 2026-05-13 (alembic 0101, commit c8ca39e2) — Sprint 2.A "Contact OS": provenance (formula_version, inputs_hash, confidence), explainability nativa (churn/health/at_risk), 4 tags novas (dormant, new_lead, objection_open, no_show_chronic), refresh v2 cruzando objections+price_inquiries+appointments, skip-on-no-change, history append-only, tool Council read_contact_attribute_history, endpoint /health, UI estendida. Validado em 3758 contatos.
• 2026-05-13 (alembic 0095+0096) — Sprint 1.B+1.C: L1 contact_attribute, L3 intelligence_pattern, L5 brain_observation, sub-agent causality, módulo business (knowledge+products+quotes+objections+appointments+brain_config), 13 tools novas no Council. Telas /admin/intelligence/{contact-attributes,patterns,observations}.
• 2026-05-13 (alembic 0094, commits 09aada4 + a3729da) — Sprint 1.A: módulo attribution (campaign + touchpoint + crm_contact.attribution_*). Áudio inbound vira contexto do Council. emit_event em council.intervention, diary, whatsapp delivered/read/reaction. UTM resolution on-create.

Apêndices

A. Catálogo completo de behavior tags

B. Glossário

• L0-L5: camadas do Brain Observatory (cru → atributo → insight → padrão → verdade → observação).
• Provenance: rastreabilidade da computação (formula_version + inputs_hash + confidence).
• Skip-on-no-change: se inputs_hash igual ao anterior, atualiza só refreshed_at (não escreve atributos novamente).
• Sub-agent: unidade de processamento dentro de Intelligence (summary, anomaly, causality, etc.).
• Pattern: descoberta persistente (vs Insight, que é pontual).
• Behavior tag: marcador comportamental aplicado ao contact_attribute (universalmente reconhecido por agentes/conselheiros).