# Sentinel Intelligence Engine (SIE)

**Produto:** Mud Sentinel  
**Documento:** `docs/sie/Sentinel Intelligence Engine.md`  
**Versão:** 1.0.0  
**Data:** 2026-07-14  
**Responsável:** Chief AI & Intelligence Architect  
**Status:** Vigente — arquitetura conceitual (pré-implementação)

---

## Aviso de escopo

Este documento define a arquitetura de inteligência do **Sentinel Intelligence Engine**.  
**Não** inclui: código, schemas de banco, migrations ou contratos HTTP implementáveis.  
A “Intelligence API” (§11) descreve **serviços internos conceituais** consumidos por outros módulos da plataforma.

Alinha-se a:

- Domínio DDD — `docs/dominio/`
- Knowledge Graph — `docs/grafo/`
- Arquitetura fundacional — `docs/arquitetura/`
- Casos de uso — UC-003 a UC-011, UC-013

---

## Sumário

1. [Visão geral do SIE](#1-visão-geral-do-sie)
2. [Rule Engine](#2-rule-engine)
3. [Risk Engine](#3-risk-engine)
4. [Graph Engine](#4-graph-engine)
5. [Similarity Engine](#5-similarity-engine)
6. [Anomaly Engine](#6-anomaly-engine)
7. [Evidence Engine](#7-evidence-engine)
8. [Explainability Engine](#8-explainability-engine)
9. [Monitoring Engine](#9-monitoring-engine)
10. [Recommendation Engine](#10-recommendation-engine)
11. [Intelligence Pipeline](#11-intelligence-pipeline)
12. [Intelligence API (serviços internos)](#12-intelligence-api-serviços-internos)
13. [Performance](#13-performance)
14. [Escalabilidade](#14-escalabilidade)
15. [Roadmap](#15-roadmap)
16. [Princípios transversais e governança](#16-princípios-transversais-e-governança)

---

## 1. Visão geral do SIE

### 1.1 Missão

O **Sentinel Intelligence Engine** é o motor de inteligência da plataforma. Transforma fatos públicos versionados e o Knowledge Graph em:

- detecção de padrões;
- indicadores de risco **explicáveis**;
- sugestão de conexões e investigações;
- monitoramento contínuo de mudanças;
- recomendações acionáveis para analistas—

sempre com **evidência, fonte, data, confiança, justificativa e rastreabilidade**.

### 1.2 Posicionamento arquitetural

```text
┌─────────────────────────────────────────────────────────────────┐
│                     Produto (Cases, Watch, UI, Reports)         │
└──────────────────────────────┬──────────────────────────────────┘
                               │ Intelligence API (§12)
┌──────────────────────────────▼──────────────────────────────────┐
│                 SENTINEL INTELLIGENCE ENGINE (SIE)              │
│  Rule │ Risk │ Graph │ Similarity │ Anomaly │ Evidence │        │
│  Explainability │ Monitoring │ Recommendation                    │
└───────┬──────────────────┬───────────────────┬──────────────────┘
        │                  │                   │
   Knowledge Graph    Domínio / Fatos      AI Orchestration
   (projeção)         (SoR tipado)         (Completion com citação)
        │                  │
        └──────── ETL / Ingest ────────────┘
```

### 1.3 Invariantes do SIE

1. **Nenhuma conclusão sem Evidence Package** (§7).
2. **Nenhuma resposta do tipo “porque a IA disse”** (§8).
3. **Fato ≠ hipótese ≠ score ≠ caminho estrutural** (linguagem ubíqua).
4. **Camadas do grafo** (observed / derived / ai / tenant) respeitadas.
5. **Multi-tenant:** regras/pesos locais não contaminam o catálogo global; sinais privados ficam no Tenant.
6. **Reprocessável:** mesma entrada + mesma versão de motores ⇒ mesma saída (salvo tempo/fontes novas).
7. **Fail soft:** falha de um motor não derruba a pipeline inteira; degradação anunciada na explicação.

### 1.4 Unidades de trabalho

| Unidade | Descrição |
|---------|-----------|
| **Intelligence Target** | Party, Contract, Bidding, Case, Watchlist item, Municipality… |
| **Signal** | Achado intermediário tipado (`rule_hit`, `anomaly`, `pattern`, `similarity_hit`) |
| **Risk Assessment** | Score + fatores + explanation em um `as_of` |
| **Alert** | Materialização para humano (Monitoring) |
| **Recommendation** | Sugestão acionável (não automática irreversível) |
| **Evidence Package** | Pacote de evidências amarrado a qualquer conclusão |

---

## 2. Rule Engine

### 2.1 Finalidade

Avaliar **condições declarativas** sobre fatos, grafo e séries temporais, produzindo `rule_hit` signals com evidências. É a base determinística e auditável do SIE (antes de ML/LLM).

**Justificativa:** compliance exige regras nomináveis, versionadas e testáveis; ML complementa, não substitui.

### 2.2 Arquitetura conceitual

```text
Rule Catalog (definições versionadas)
        │
        ▼
Rule Compiler  →  Evaluation Plan (ordem, deps, short-circuit)
        │
        ▼
Fact/Graph Query Ports  ←  as_of, tenant policy, entitlements
        │
        ▼
Rule Evaluator  →  RuleHit[] + partial Evidence seeds
        │
        ▼
Conflict Resolver  →  hits normalizados
        │
        ▼
Outbox → Risk / Anomaly / Monitoring / Explainability
```

**Componentes:**

| Componente | Responsabilidade |
|------------|------------------|
| Rule Catalog | Armazenar metadados e corpo das regras |
| Rule Compiler | Validar sintaxe/semântica; resolver dependências |
| Evaluation Context | Target, as_of, tenant weights, feature flags |
| Evaluators | Predicados tipados (existential, aggregate, path, temporal) |
| Conflict Resolver | Prioridades, mutex groups, exclusões |
| Hit Store lógico | Persistir hits para score e auditoria |

### 2.3 Tipos de regras

| Tipo | Descrição | Exemplo |
|------|-----------|---------|
| **Predicate** | Condição booleana sobre atributo/fato | `HAS_ACTIVE_SANCTION` |
| **Threshold** | Agregado vs limiar | valor de aditivos > 25% do contrato |
| **Path** | Existência de caminho no grafo sob constraints | PEP → OWNS → Company → AWARDED_TO ← Body do mandato |
| **Temporal** | Mudança em janela | novo sócio nos últimos 30 dias |
| **Set / Cohort** | Comparação com universo | único licitante em certame |
| **Composite** | AND/OR/NOT / NOT / SEQ de regras filhas | COI = Mandate ∧ Contract ∧ Ownership |
| **Scoring-assist** | Não decide sozinha; só emite fator peso | contribuição para Risk Engine |
| **Guard** | Pré-condição de elegibilidade | só PJ ativas; só esfera municipal |

### 2.4 Categorias

| Categoria | Código | Foco |
|-----------|--------|------|
| Integridade / COI | `integrity.coi.*` | Conflito de interesse |
| Sanções / Impedimentos | `integrity.sanction.*` | Listas |
| Societário | `corporate.*` | QSA, controladores |
| Contratos / Aditivos | `contracts.*` | Valores, prazos |
| Licitações | `procurement.*` | Participação, cartéis-hipótese |
| Transferências / Emendas | `transfers.*` / `parliament.*` | Destinações |
| Contatos compartilhados | `graph.share.*` | Mesmo telefone/endereço |
| Cadastro / Qualidade | `data_quality.*` | Lacunas graves |
| Monitoramento | `watch.trigger.*` | Mudanças |
| Custom Tenant | `tenant.<id>.*` | Regras locais |

### 2.5 Prioridades

Escala **P0–P5** (P0 = crítico operacional / segurança da análise):

| Prioridade | Uso | Avaliação |
|------------|-----|-----------|
| P0 | Guardas de sanidade / segurança (não score) | Sempre primeiro |
| P1 | Sanção ativa linkada high-confidence | Síncrono em ficha |
| P2 | COI paths / PEP supplier | Síncrono ou nearline |
| P3 | Aditivos, single-bid, shares_* | Nearline |
| P4 | Enrichment / features fracas | Batch |
| P5 | Experimental / tenant sandbox | Isolado |

Prioridade **não** é o mesmo que peso de risco — é ordem e urgência de avaliação/alerta.

### 2.6 Versionamento

```text
rule_code (imutable logical name) + semver (MAJOR.MINOR.PATCH)
```

| Mudança | Version bump |
|---------|--------------|
| Novo predicado incompatível | MAJOR |
| Novo parâmetro opcional / peso default | MINOR |
| Tipografia / docs da regra | PATCH |
| Disable → não apaga versão | status na ativação |

**Imutabilidade:** versão publicada não é editada; cria-se nova versão.  
**Pinned evaluation:** Risk Assessment grava `rule_code@version` nos fatores.

### 2.7 Ativação e desativação

| Escopo | Quem controla |
|--------|---------------|
| Global platform | Ops / Integrity product |
| Plano / entitlement | Administration |
| Tenant overlay | Admin Tenant (subset allowed) |
| Feature flag | Release |

Estados: `draft` → `published` → `enabled` / `disabled` → `retired`.

**Regras:**

- Disable não recalcula o passado automaticamente; Assessments históricos permanecem; novo `as_of` ignora regra disabled.
- Disable de regra P1 exige AuditEvent.
- Tenant não pode desligar regras **mandatórias** do plano (se houver compliance pack).

### 2.8 Composição entre regras

Operadores:

- `ALL` (AND), `ANY` (OR), `NONE` (NOT ANY)
- `SEQUENCE` temporal (A antes de B em δ)
- `REF` a hits de outras regras (dependency graph acíclico)
- `FILTER` pós-hit (ex.: só se confidence ≥ X)

Composite rules são regras de primeira classe com próprio `rule_code`.

### 2.9 Conflitos

| Tipo de conflito | Resolução |
|------------------|-----------|
| Mutex group (ex.: “sanção ativa” vs “sanção encerrada”) | Vence maior prioridade; ou validade temporal |
| Hits duplicados mesmo padrão | Dedup por `signature` canônica |
| Tenant weight vs global | Tenant sobrescreve peso **se entitlement**; nunca apaga evidence |
| Path vs ausência de path | Silence ≠ negative proof — caveat na explicação |
| Regra experimental vs prod | Namespaces isolados |

**Conflict policy** versionada (`conflict_policy.v1`) anexada ao Assessment.

---

## 3. Risk Engine

### 3.1 Finalidade

Agregar sinais (regras, anomalias, padrões de grafo, similaridade) em um **Integrity / Risk Score** decomponível, temporal e explicável por alvo.

### 3.2 Cálculo de score (modelo conceitual)

**Entrada:** Target + `as_of` + method_version + policy (global ∪ tenant).  
**Saída:** `RiskAssessment { value, band, factors[], explanation_id, evidence_package_id }`.

Forma geral (ilustrativa, não código):

```text
raw = Σ_i  (contribution_i × weight_i × confidence_i × impact_i × temporal_decay_i)
value = normalize(raw) ∈ [0, 100]   # ou [0,1]
band  = map_thresholds(value, policy)
```

**Normalize:** função monotônica saturante (ex.: escala logística / caps por categoria) para evitar um único fator dominar 100% sem política explícita.

### 3.3 Níveis (bands)

| Band | Faixa sugerida | Significado UX |
|------|----------------|----------------|
| `minimal` | 0–19 | Poucos ou nenhum fator material |
| `low` | 20–39 | Fatores fracos / históricos |
| `moderate` | 40–59 | Atenção; revisar fatores |
| `high` | 60–79 | Risco elevado — diligência reforçada |
| `critical` | 80–100 | Bloqueadores fortes (ex.: sanção ativa high-conf) |

Bands são **policy**; Tenants podem ajustar limiares com caveat.

**Linguagem proibida:** “culpado”, “corrupto”, “prova de crime”. Preferir: “faixa de risco / atenção / fatores presentes”.

### 3.4 Pesos

| Dimensão | Descrição |
|----------|-----------|
| `category_weight` | Peso relativo da categoria (sanção > share phone) |
| `rule_weight` | Peso da regra específica |
| `tenant_multiplier` | Ajuste local permitido |
| `plan_cap` | Limite de influência de categoria experimental |

Pesos versionados em `risk_method.vMAJOR`.

### 3.5 Fatores

Cada fator espelha domínio `IntegrityFactor`:

| Campo lógico | Uso |
|--------------|-----|
| `factor_id` | Identidade |
| `signal_ref` | rule_hit / anomaly / pattern |
| `category` | taxonomia |
| `contribution` | valor parcial pré-norma |
| `confidence` | 0–1 |
| `impact` | severidade contextual |
| `temporal_decay` | multiplicador |
| `evidence_package_id` | obrigatório |
| `explanation_snippet` | 1–2 frases |

### 3.6 Impacto

Impacto contextualiza o alvo:

| Contexto | Efeito |
|----------|--------|
| Valor monetário alto sob análise | impact↑ em contratos/aditivos |
| Órgão sensível / saúde / educação | impact↑ opcional por policy |
| Match de sanção `match_status=uncertain` | impact↓ e band clamp |
| Fator apenas L3 AI | impact=0 até aceite humano (default) |

### 3.7 Decaimento temporal

```text
decay = f(age_days, half_life_category, still_active?)
```

| Classe | half-life típica | Notas |
|--------|------------------|-------|
| Sanção ainda vigente | sem decay (ou decay mínimo) | `still_active` |
| Sanção levantada | half-life curta pós-lift | histórico residual baixo |
| Sócio removido | medium | |
| Share phone histórico | rápida | ruído |
| COI com mandato encerrado | medium-fast | |

### 3.8 Explicabilidade do score

O Risk Engine **delega** narrativa ao Explainability Engine (§8), fornecendo:

- ordered factors (top-N por |contribution|);
- method_version + weights snapshot;
- omissões (regras disabled, evidências insuficientes);
- clamp reasons (ex.: “cap de categoria experimental”).

**Proibido** retornar só um número.

---

## 4. Graph Engine

Camada de orquestração sobre o Knowledge Graph (`docs/grafo/`). Não redefine o modelo de nós — **consome** portas do grafo.

### 4.1 Expansão automática

**Serviço:** `AutoExpand(target, profile)`

| Profile | Comportamento |
|---------|---------------|
| `fiche_default` | depth 1–2; societário + sanção + contratos recentes |
| `diligence` | depth 3; inclui shares_* com weight≥τ |
| `coi_hunt` | allowlist de edges COI + mandatos |
| `watch_delta` | só vizinhos novos desde T0 |

Políticas de fan-out/truncamento: ver `docs/grafo/04-algoritmos.md`.  
Toda expansão gera `GraphExplanation` + seeds de Evidence.

### 4.2 Descoberta de comunidades

Orquestra Leiden/components nos edge sets configuráveis; materializa candidatos `ECONOMIC_GROUP` via Recommendation + Review.

### 4.3 Caminhos mínimos

`FindPaths(A, B, constraints)` → K paths + explanations.  
Constraints: depth, edge types, layers, temporal strictness, forbid nodes.

### 4.4 Centralidade

`CentralitySlice(subgraph_spec)` → scores por medida; usados como **features** para Anomaly/Risk (não como veredito).

### 4.5 Clusters

Coordena Similarity + Graph embeddings batch; distingue comunidade (topologia) vs cluster (feature space).

### 4.6 Influência

Modelo conceitual de influência:

```text
influence(n) ≈ α·weighted_pagerank + β·betweenness_ego + γ·contract_value_flow
```

Normalizado por tipo de nó; órgãos públicos não “vence” automaticamente ranking de empresas.

### 4.7 Relacionamento indireto

Definição oficial:

> Relacionamento **indireto** = path de comprimento ≥ 2 sob allowlist, com interseção temporal válida e min_confidence no gargalo (`min` das arestas).

Produtos:

- `indirect_link` signal;
- narrativa hop-a-hop;
- bridge nodes destacados.

---

## 5. Similarity Engine

### 5.1 Finalidade

Calcular similaridade tipada entre pares/candidatos para: peers, entity resolution assistida, recomendações, anomalias de “quase duplicata”.

### 5.2 Empresas semelhantes

| Grupo de atributos | Exemplos | Peso relativo típico |
|--------------------|----------|----------------------|
| Identidade fraca | razão social normalizada, nome fantasia | alto em blocking |
| Identificadores | partial CNPJ collisions (tratar com cuidado) | muito alto se válido |
| Atividade | CNAE primário/secundários | médio |
| Geografia | município sede, UF | médio |
| Contatos | phone/email/domain hubs | alto se raro |
| Estrutura | overlap de sócios (Jaccard) | alto |
| Comportamento | órgãos contratantes comuns, co-bids | médio |
| Embedding | graph + text | auxiliar |

**Algoritmo misto:** blocking → score híbrido → TopK + explanation features.

### 5.3 Pessoas semelhantes

| Atributos | Notas |
|-----------|-------|
| Nome normalizado / tokens | Homônimos: nunca auto-merge |
| Identifiers | decisivo |
| Geo / vínculos | município, empresas comuns |
| Mandatos / PEP flags | contexto |
| Relacionamentos declarados | só L1 |

### 5.4 Fornecedores semelhantes

Especialização de empresas + features de procurement:

- overlap de BiddingProcess;
- similaridade de objetos (texto);
- tickets médios;
- mesmos representantes/`SHARES_REPRESENTATIVE`;
- taxa de vitórias conjunta (cuidado: padrão, não culpa).

### 5.5 Contratos semelhantes

| Atributos | Comparação |
|-----------|------------|
| Objeto (texto) | similaridade semântica / shingles |
| Valor | banda relativa |
| Órgão contratante | exact/hierarquia |
| Fornecedor | exact / similar companies |
| Vigência | overlap temporal |
| Modalidade / origem licitação | exact |
| Aditivos | perfil de deltas |

Uso: detectar “réplicas”, superfaturamento relativo (hipótese), template recycling.

### 5.6 Municípios semelhantes

| Atributos | Comparação |
|-----------|------------|
| Porte (popproxy / faixa) | banda |
| UF / região | exact |
| Perfil de transferências | vetores de programas |
| Densidade contratual | rates |
| Emendas / autores | overlap parlamentar |
| Setores (educação/saúde) | composição de despesas |

Uso: peer benchmarking de concentração e anomalias.

### 5.7 Saída

```text
SimilarityResult {
  left, right, kind,
  score, band,
  feature_contributions[],
  evidence_package_id,
  explanation_id,
  suggested_action?  # link / merge review / ignore
}
```

---

## 6. Anomaly Engine

### 6.1 Finalidade

Detectar desvios em relação a baselines históricos, peers ou expectativas estruturais — sempre como **anomalia/indício**, com baseline e método explícitos.

### 6.2 Estratégias

#### Comportamentos incomuns

- Desvio de padrão de participação (empresa sem histórico em saúde suddenly wins large health bids).
- Mudança de CNAE + contrato imediato no novo setor.
- **Método:** distance to self-baseline + peer z-score.

#### Crescimento atípico

- Volume contratado/pago em janela vs mediana móvel.
- Número de vitórias / mês.
- **Método:** robust z-score / STL residual; min support de histórico.

#### Concentração

- Herfindahl de fornecedores por órgão/município.
- Share de um Economic Group em uma pasta.
- **Método:** índices de concentração + limiares por porte.

#### Mudanças abruptas

- Troca de Quadro societário massiva em δ dias.
- Spike de aditivos.
- **Método:** event burst detection em Timeline.

#### Padrões repetitivos

- Rodízio de vencedores no mesmo cluster (`P_ROTATING_WINNERS`).
- Mesmos pares co-bidders recorrentes.
- **Método:** motif counts + null model (randomization caveat).

#### Relacionamentos inesperados

- Path improvável (raridade de edge sequences).
- Novo `SHARES_ADDRESS` com empresa sancionada.
- **Método:** path surprise score; edge novelty vs histórico do ego.

### 6.3 Saída

`AnomalySignal` com: tipo, severidade, baseline_ref, observed_value, expected_range, window, evidence, explanation.

**Integração:** pode gerar Rule-compat hits ou fatores diretos no Risk (com category `anomaly.*`).

---

## 7. Evidence Engine

### 7.1 Princípio

> **Toda conclusão do SIE referencia ≥ 1 Evidence Package.**  
> Conclusão sem evidência **não é publicável** a UI/Risk/Alert.

### 7.2 Conteúdo obrigatório de toda conclusão

| Elemento | Descrição |
|----------|-----------|
| **Evidências** | Lista de Evidence Items (fatos, docs, hops, métricas) |
| **Fontes** | SourceSystem / SourceRecord / DocumentVersion |
| **Data** | `observed_at` / `valid` / `collected_at` / `computed_at` |
| **Confiança** | score + banda + método de calibração |
| **Justificativa** | texto curto + structured reason codes |
| **Rastreabilidade** | `trace_id`, versões de motores/regras, inputs hash |

### 7.3 Evidence Package (estrutura lógica)

```text
EvidencePackage {
  package_id
  tenant_id?
  subject_refs[]
  conclusion_ref          # assessment | alert | recommendation | completion_pin
  items[]: {
      item_id
      kind                  # source_record | graph_edge | metric | document | citation
      ref
      caption
      observed_at?
      confidence?
      hash?
  }
  sources_deduped[]
  created_at
  integrity_hash
}
```

### 7.4 Regras do Evidence Engine

1. Itens L1 preferidos; L2 exigem `rule_id`; L3 exigem citation/features + status.
2. Métricas (z-score) incluem definição de baseline como item.
3. Graph hops: um item por aresta material **ou** GraphExplanation embedada.
4. Packages são **imutáveis**; correções criam novo package + supersede link.
5. Exports de Case reutilizam packages (manifesto).

### 7.5 Relação com domínio Evidence

O contexto **Evidence** do produto (dossiê) **pin** packages do SIE para o Case.  
O Evidence Engine do SIE é a fábrica; o Case é o arquivo de trabalho do analista.

---

## 8. Explainability Engine

### 8.1 Mandato absoluto

**Nunca** permitir respostas equivalentes a “porque a IA disse”.

Toda conclusão exibida deve mostrar, no mínimo:

| Bloco UX | Conteúdo |
|----------|----------|
| Regras acionadas | `rule_code@version` + título PT-BR |
| Evidências | chips ligando ao Evidence Package |
| Algoritmos utilizados | nomes canônicos (ExpandEgo, Leiden, ZScore…) + versões |
| Fontes consultadas | SourceSystems / records |
| Confiança | banda + valor + limitações de calibração |
| Limitações | truncamento, dados ausentes, camadas excluídas, falsos positivos possíveis |

### 8.2 Arquitetura

```text
Consumers (Risk, Alert, UI, AI grounding)
        │
        ▼
Explanation Builder
  ├─ collect factors / hits / paths / anomalies
  ├─ attach EvidencePackage
  ├─ attach GraphExplanation (se houver)
  ├─ apply narrative templates (PT-BR)
  └─ attach caveats library
        │
        ▼
Explanation Record (imutável, explanation_id)
```

### 8.3 Templates narrativos (template-first)

Exemplos de códigos:

- `narr.path.coi.v1`
- `narr.score.top_factors.v1`
- `narr.anomaly.growth.v1`
- `narr.similarity.company.v1`

LLM **só** pode reescrever estilo se grounding slots estiverem preenchidos e Citations existirem; a versão canônica para auditoria é a structured + template.

### 8.4 Contrafactuais leves

Para paths e fatores dominantes:

- “Sem a aresta OWNS(e123), o caminho deixa de existir.”
- “Se a sanção tivesse match_status=uncertain, a band seria no máximo high−clamp.”

### 8.5 Limitações padrão (biblioteca)

Sempre que aplicável:

- profundidade/orçamento truncados;
- atraso de ingestão (lag);
- ausência de fonte X;
- score não é julgamento jurídico;
- path é estrutural.

---

## 9. Monitoring Engine

### 9.1 Finalidade

Observar **targets** (Watchlists, Cases, entidades de interesse do plano) e emitir **Alerts** priorizados quando houver mudanças relevantes.

### 9.2 Catálogo de gatilhos (exemplos)

| Gatilho | Evento de domínio / diff | Prioridade default |
|---------|--------------------------|--------------------|
| Empresa alterou sócios | `companies.shareholding.*` | P2 |
| Empresa venceu nova licitação | `procurement.lot.awarded` / path AWARDED | P2 |
| Novo contrato | `contracts.public_contract.published` | P2 |
| Novo pagamento | `transparency.expense.recorded` | P3 |
| Nova sanção (link high) | `sanctions.entry.linked_to_party` | P1 |
| Nova sanção (match incerto) | idem uncertain | P2 (review) |
| Novo processo* | fonte processual futura | P2–P3 |
| Nova notícia* | media connector futuro | P3–P4 |
| Alteração cadastral | `registration_snapshot.created` | P3 |
| Aditivo material | `contracts.amendment.published` | P2 |
| Novo share contact com alvo | L2 edge nova | P3 |
| Score band jump | Risk recomputed Δband≥1 | P2 |
| Path COI novo | PatternMatch hit | P1–P2 |

\*Módulos futuros — previstos no roadmap; mesmo contrato de Alert.

### 9.3 Frequência

| Modo | Quando | Uso |
|------|--------|-----|
| **Event-driven** | Outbox de ingest/domain | Preferencial |
| **Nearline** | segundos–minutos | Recompute leve |
| **Scheduled sweep** | hourly/daily | Diff completo, lag catch-up |
| **On-demand** | analista / Case open | Refresh |

SLA de frescor alinhado a `docs/operacao/04-monitoramento.md` (ingest lag).

### 9.4 Prioridades e dedupe

- Priority = max(trigger_priority, severity_from_risk, tenant boost).
- Dedupe window por `(tenant, target, trigger_code, fingerprint)`.
- Storm control: rate limit por target/watchlist.

### 9.5 Ciclo do alerta

`open → notified → acknowledged → closed|escalated`  
Ack/close geram AuditEvent; podem abrir Case/Recommendation.

---

## 10. Recommendation Engine

### 10.1 Finalidade

Sugerir **próximos passos analíticos** — nunca executar ações irreversíveis sem humano.

### 10.2 Tipos de recomendação

| Tipo | Exemplos |
|------|----------|
| Novas investigações | “Abrir Case focado no grupo econômico G” |
| Novas conexões / relacionamentos | Revisar `SAME_AS` / `SHARES_PHONE` candidatos |
| Novas consultas | Buscar sócios do adjudicatário; path até órgão X |
| Novas fontes | “Fonte Y não ingerida para município Z” (coverage gap) |
| Novas entidades relacionadas | TopK similares; co-bidders; bridge nodes |
| Regras | “Ativar regra tenant de aditivo >15% neste setor” |
| Monitoramento | “Adicionar Company C à Watchlist” |

### 10.3 Ranking

```text
reco_score = relevance × novelty × expected_information_gain × (1 - user_fatigue)
```

Explicação obrigatória: por que sugeriu + evidence anchors.

### 10.4 Feedback loop

Aceitar / dispensar / adiar → Usage + model/regra de ranking (V2+).  
Dispensa com motivo alimenta redução de FP.

---

## 11. Intelligence Pipeline

### 11.1 Fluxo canônico ponta a ponta

```text
Coleta (Crawler/Plugins)
    ↓
Normalização (ETL Transform)
    ↓
Validação (Data Quality)
    ↓
Publicação de fatos (IngestRun → Domínio)
    ↓
Projeção Knowledge Graph (nós/arestas L1 + L2 recompute)
    ↓
Rule Engine (hits)
    ↓
Graph Engine jobs (paths/patterns on targets quentes)
    ↓
Similarity Engine (batch + on-demand)
    ↓
Anomaly Engine
    ↓
Risk Engine (Assessment)
    ↓
Evidence Engine (packages)
    ↓
Explainability Engine (explanations)
    ↓
Monitoring Engine (alerts) ──► Notifications
    ↓
Recommendation Engine
    ↓
Dashboard / Ficha / Case UI
    ↓
AI Orchestration (Completion facts_only | hypothesis)
        ↑ grounding via Evidence + Explanation + RAG
```

### 11.2 Gatilhos de pipeline

| Gatilho | Pipeline parcial |
|---------|------------------|
| `ingest_run.published` | Graph project → Rules (impacted) → Risk hot set → Monitor diff |
| `watch.target.added` | Expand + Rules + Risk + baseline anomaly |
| `case.entity.linked` | Diligence profile expand + recommendations |
| Scheduler diário | Comunidades, similarity embeddings, sweeps |
| Manual “recompute” | Full target chain com Audit |

### 11.3 Garantias

- Idempotência por `run_id` + target + method versions.
- Partial failure → Assessment `degraded=true` + caveats.
- Dead-letter por estágio com replay.

---

## 12. Intelligence API (serviços internos)

Contratos **lógicos** entre módulos (não especificação OpenAPI nesta fase).

### 12.1 Catálogo de serviços

| Serviço | Consumidores | Operações conceituais |
|---------|--------------|------------------------|
| `RuleService` | Risk, Monitor, Graph patterns | `Evaluate(target)`, `ExplainHit`, `ListEnabledRules` |
| `RiskService` | UI ficha, Cases, Monitor | `Assess`, `GetAssessment`, `CompareAsOf` |
| `GraphIntelService` | UI grafo, COI, Reco | `Expand`, `FindPaths`, `Communities`, `Centrality` |
| `SimilarityService` | Search, Reco, Core match | `TopKSimilar`, `ScorePair` |
| `AnomalyService` | Risk, Monitor | `Detect`, `GetBaselines` |
| `EvidenceService` | Todos | `BuildPackage`, `GetPackage`, `PinToCase` |
| `ExplanationService` | UI, Reports, AI | `Build`, `Get` |
| `MonitoringService` | Watch, Notify | `RegisterTarget`, `EvaluateDiff`, `ListAlerts` |
| `RecommendationService` | UI, Case | `Recommend`, `Feedback` |
| `PipelineService` | Workers/Ops | `Enqueue`, `Replay`, `Status` |
| `IntelligenceCatalog` | Admin | Versões de métodos, regras, limiares |

### 12.2 Cross-cutting ports

- `TenantPolicyPort` — pesos, limiares, entitlements  
- `AuditPort` — ações sensíveis  
- `QuotaPort` — expansões, assessments, AI  
- `FeatureFlagPort` — motores/experimental  

### 12.3 Semântica de erros

| Código lógico | Significado |
|---------------|-------------|
| `TARGET_NOT_FOUND` | — |
| `INSUFFICIENT_EVIDENCE` | não publica conclusão |
| `BUDGET_EXCEEDED` | truncado / async suggested |
| `METHOD_DISABLED` | — |
| `DEGRADED_UPSTREAM` | score com caveats |

---

## 13. Performance

### 13.1 Cache

| Cache | Chave conceitual | TTL / invalidação |
|-------|------------------|-------------------|
| Assessment | target + as_of_bucket + method + policy_hash | invalidate on relevant ingest / rule change |
| Expand ego | seed + profile + as_of | curto; invalidate on neighborhood diff |
| Path | A,B,constraints hash | curto |
| Similarity TopK | id + kind + model | batch rebuild diário + invalidate on merge |
| Explanation | explanation_id | imutável (long) |
| Rule compile | rule_set_version | até novo publish |
| Baselines anomaly | target + metric + window | recompute schedule |

**Justificativa:** scores e expands são caros; imutabilidade de explanations permite cache agressivo.

### 13.2 Assíncrono e filas

| Fila lógica | Conteúdo |
|-------------|----------|
| `sie.project.graph` | pós-ingest projeções |
| `sie.rules.evaluate` | alvos impactados |
| `sie.risk.recompute` | assessments |
| `sie.anomaly.batch` | métricas |
| `sie.similarity.batch` | embeddings/clusters |
| `sie.monitor.diff` | watch |
| `sie.pipeline.dlq` | falhas |

Online: Expand depth≤2, Risk cache hit, Path rápido.  
Offline: comunidades, embeddings, full sweeps.

### 13.3 Reprocessamento

- **Target replay:** reexecuta cadeia com versões pinadas ou latest.
- **Rule republish MAJOR:** enfileira recompute dos enabled scopes.
- **Backfill:** janelas por source_system / município.
- Sempre Audit + métricas de lag/coverage.

---

## 14. Escalabilidade

### 14.1 Milhares de regras

- Indexação por **trigger predicates** (só avalia regras relevantes ao evento).
- Shard de avaliação por `rule_category` / prioridade.
- Short-circuit e composições precompiled.
- Tenant rules isoladas em namespace; quotas de regras custom.
- Canary: percentual de targets antes de enable global.

### 14.2 Milhões de entidades

- **Hot set:** watch + recent search + open cases — prioridade na pipeline.
- **Cold set:** batch amostral / on-demand.
- Graph queries em slices (município, CNAE, ego).
- Materialized ego summaries (degree, last_contract_at) para filtros baratos.
- Similarity com **blocking** (nunca N² global).
- Partitionamento lógico por jurisdição / tipo de Party.
- Horizontally scale workers; state cache distribuído.
- Orçamentos hard por request (nós tocados, ms).

### 14.3 Multi-tenant em escala

- Computação de catálogo global **uma vez**; overlay tenant (pesos/alertas) barato.
- Isolamento de packages/alerts por `tenant_id`.
- Evitar fan-out “recompute all tenants” — indexar subscriptions (watch).

---

## 15. Roadmap

### Versão 1 — “Deterministic Core” (MVP inteligência)

- Rule Engine (predicate/threshold/path básico) + versionamento
- Risk Engine method.v1 + factors + bands
- Graph Engine: expand + shortest path + explanations
- Evidence + Explainability mínimos (templates)
- Monitoring event-driven (sócios, contratos, sanções, aditivos)
- Pipeline pós-ingest hot set
- Intelligence API interna essentials
- Cache assessments + expand

### Versão 2 — “Patterns & Peers”

- Similarity Engine completo (companies/people/suppliers)
- Anomaly Engine (growth, concentração, abrupt changes)
- Pattern catalog ampliado + comunidades ownership
- Recommendation Engine v1
- Tenant rule weights + custom rules sandboxed
- K-shortest + centrality slices
- Contratos/municípios similarity

### Versão 3 — “Scale & Depth”

- Milhares de regras com trigger index maduro
- Influência / indirect link produtos de UI
- Anomaly null-models mais fortes
- Monitoring: pagamentos, notícias, processos (conectores)
- Reprocessamento self-serve para ops
- Feedback loop de recomendações
- Performance: ego materializations, aggressive invalidation graph

### Versão Enterprise

- Packs setoriais de regras (financeiro, saúde, governo)
- SSO-era compliance: method freeze por contrato, export legal de explanations
- ABAC sobre sinais
- Residência / particionamento regional de hot data
- SLA de recompute e dashboard de coverage por fonte
- COI packs com review workflow dual-control
- API M2M de Assessment (entitlement) — contrato estável

### Versão AI Native

- AI Candidate edges integrados ao SIE com human gate
- Ranking de recomendações aprendido
- NLG polido com grounding obrigatório
- Graph/ML embeddings (GraphSAGE-like) na Similarity/Anomaly
- Eval harness contínuo (precision sanção match, FP COI)
- Agentes de investigação **assistidos** (tool allowlist) — nunca auto-acusação
- Multi-model routing por custo/qualidade

---

## 16. Princípios transversais e governança

### 16.1 Segregação de deveres

| Função | Pode |
|--------|------|
| Rule author | Draft rules |
| Rule publisher | Publish (review) |
| Tenant admin | Adjust allowed weights / watch |
| Analista | Consome insights; pin evidence |
| Platform admin | Enable global / break-glass |

### 16.2 Testes de inteligência (conceituais)

- Golden targets com assessments esperados
- Rule unit fixtures (fact packs)
- Regression de explanation coverage
- Adversarial FP tests (homônimos, escritórios virtuais)

### 16.3 Observabilidade do SIE

Métricas: hits/s, assessment latency, cache hit ratio, DLQ depth, alert storm, explanation coverage %, quota exhaustions.

### 16.4 Documentos relacionados

| Tema | Documento |
|------|-----------|
| Grafo | `docs/grafo/*` |
| Integridade / fatores | `docs/dominio/entidades/04-analise.md` |
| EDA / outbox | `docs/arquitetura/06-event-driven.md` |
| AI produto | `docs/arquitetura` ADR-0008 + domínio AI |
| Ubiquitous language | `docs/dominio/ubiquitous_language.md` |

---

## Histórico de revisões

| Versão | Data | Autor | Notas |
|--------|------|-------|-------|
| 1.0.0 | 2026-07-14 | Chief AI & Intelligence Architect | Arquitetura fundacional do SIE |

---

*Fim do documento oficial **Sentinel Intelligence Engine.md**.*