# Descoberta por IA e Relacionamentos Derivados

**Documento:** `grafo/03-ia-e-derivados.md`  
**Versão:** 1.0.0

---

## 1. Princípio

- **Derived (L2):** regras determinísticas ou semi-determinísticas reproduzíveis; sempre com `rule_id`.
- **AI (L3):** modelo estatístico/LLM; sempre `hypothesised=true`, `model_id`, `confidence`, nunca promovido a L1 automaticamente.
- UI e IntegrityScore só consomem L3 com **política explícita do Tenant**.

---

## 2. Relacionamentos derivados (L2)

Forma canônica: criar aresta **`SHARES_*`** entre dois atores **ou** manter apenas o hub compartilhado (`PHONE`) e tratar co-ocorrência como path de comprimento 2.  

**Recomendação Mud Sentinel:** **ambos** — hub `HAS_*` (L1) + aresta derivada direta `SHARES_PHONE_WITH` (L2) para UX de “mesmo X”, com evidência apontando aos dois `HAS_PHONE`.

### 2.1 Mesmo telefone — `SHARES_PHONE_WITH`

| Campo | Conteúdo |
|-------|----------|
| **Direção** | `ATOR ↔ ATOR` (simétrica) |
| **Cardinalidade** | N:M |
| **Peso** | 0.35–0.55 (telefones de call-center / shared desks reduzem peso) |
| **Evidência** | Mesmo `PHONE` node; ≥2 `HAS_PHONE` |
| **Fonte** | regra `derive.shares_phone.v1` |
| **Confiança** | medium (ruído alto em números genéricos) |
| **Modo** | **derived** (não inferido por LLM) |

**Filtros anti-ruído:** denylist de telefones de URA/órgão; exigir match E.164 completo.

### 2.2 Mesmo endereço — `SHARES_ADDRESS_WITH`

| Campo | Conteúdo |
|-------|----------|
| **Direção** | simétrica entre atores |
| **Peso** | 0.4 endereço comercial coletivo; 0.7 endereço raro/residencial-like |
| **Evidência** | mesmo `ADDRESS.place_key` |
| **Confiança** | medium |
| **Modo** | derived |
| **Notas** | Escritórios virtuais → weight↓ ; suite/sala distinta → keys diferentes |

### 2.3 Mesmo e-mail — `SHARES_EMAIL_WITH`

| Campo | Conteúdo |
|-------|----------|
| **Peso** | 0.7 (sinal forte) |
| **Evidência** | mesmo `EMAIL` |
| **Confiança** | high se inbox não for genérico (`contato@`, `sac@` → weight↓) |
| **Modo** | derived |

### 2.4 Mesmo domínio — `SHARES_DOMAIN_WITH`

| Campo | Conteúdo |
|-------|----------|
| **Peso** | 0.5 |
| **Evidência** | mesmo `DOMAIN` via `HAS_DOMAIN` |
| **Confiança** | medium (holding sites, marketplaces) |
| **Modo** | derived |

### 2.5 Mesmo IP — `SHARES_IP_WITH` *(feature flag)*

| Campo | Conteúdo |
|-------|----------|
| **Peso** | ≤ 0.2 default (CDN/shared hosting) |
| **Evidência** | mesmo `IP_ADDRESS` |
| **Confiança** | low |
| **Modo** | derived |
| **Regra ética** | desligado por default; só fontes autorizadas |

### 2.6 Mesmo contador — `SHARES_ACCOUNTANT_WITH`

| Campo | Conteúdo |
|-------|----------|
| **Direção** | `COMPANY ↔ COMPANY` |
| **Peso** | 0.45 |
| **Evidência** | mesmo `PROFESSIONAL_SERVICE` kind=accountant |
| **Confiança** | medium |
| **Modo** | derived |
| **Notas** | Contadores com carteira enorme → weight↓ por grau do hub |

### 2.7 Mesmo advogado — `SHARES_LAWYER_WITH`

| Campo | Conteúdo |
|-------|----------|
| **Análogo a contador** | kind=lawyer |
| **Peso** | 0.4 |
| **Modo** | derived |

### 2.8 Mesmo representante — `SHARES_REPRESENTATIVE_WITH`

| Campo | Conteúdo |
|-------|----------|
| **Direção** | `COMPANY ↔ COMPANY` |
| **Evidência** | mesmo `PERSON` com papel `legal_representative` / procurador em fontes |
| **Peso** | 0.75 |
| **Confiança** | medium–high |
| **Modo** | derived a partir de `ADMIN_OF` / papel explícito |

### 2.9 Mesmo grupo econômico — `IN_SAME_ECONOMIC_GROUP`

| Campo | Conteúdo |
|-------|----------|
| **Direção** | simétrica / via `ECONOMIC_GROUP` |
| **Evidência** | ownership transitivo ≥ limiar **ou** declaração oficial |
| **Peso** | 0.8–1.0 |
| **Modo** | derived (algoritmo de componente) **ou** observed |

### 2.10 Mesmo núcleo familiar — `IN_SAME_FAMILY`

| Campo | Conteúdo |
|-------|----------|
| **Evidência** | somente com fonte pública e `legal_basis_tag` |
| **Peso** | 0.6 |
| **Modo** | derived **estrito**; default off |
| **Proibição** | inferir família só por sobrenome |

### 2.11 Mesmo município de destinação + mesmo parlamentar — `CO_BENEFITS_FROM_AMENDMENT_NETWORK` *(opcional)*

Padrão derivado fraco para análises de emendas; weight baixo; sempre explicável.

### 2.12 Co-participação em certames — `CO_BIDDED_WITH`

| Campo | Conteúdo |
|-------|----------|
| **Direção** | `COMPANY ↔ COMPANY` |
| **Evidência** | ≥ K certames comuns em janela T |
| **Peso** | f(K, sincronia de lances) |
| **Modo** | derived |
| **Uso** | hipótese de padrão — **não** acusação |

### 2.13 Sequência contrato↔pagamento — `LIKELY_SETTLES`

| Campo | Conteúdo |
|-------|----------|
| **Direção** | `PAYMENT → CONTRACT` |
| **Evidência** | fuzzy match número/instrumento + partes + janela temporal |
| **Modo** | derived |
| **Confiança** | medium |

---

## 3. Relacionamentos descobertos / sugeridos por IA (L3)

A IA **não grava L1**. Produz **Edge Candidates** revisáveis.

### 3.1 Catálogo de descobertas automáticas por IA

| ID | Relacionamento candidato | Como a IA ajuda | Risco | Gate humano |
|----|--------------------------|-----------------|-------|-------------|
| AI-01 | `SAME_AS` entre Parties | Entity resolution multimodal (nome+addr+contexto) | Homônimos | Sim, abaixo de limiar |
| AI-02 | `APPLIES_TO` sanção↔Party | Match fuzzy de nomes em listas | Falso positivo regulatório | Sim se confidence < high |
| AI-03 | `RELATED_TO` pessoas | Extrair vínculos declarados em texto de diário/PDF | Alucinação | Só com span citado |
| AI-04 | `SIGNED` agente→contrato | NER em PDFs de contratos | Erro OCR/NER | Sample review |
| AI-05 | `HAS_PROFESSIONAL` | Extrair “contador responsável” de texto | Ruído | Validação schema |
| AI-06 | `COI_PATTERN` → `FLAGS` | Sugerir padrões a partir de path features | Bias | Nunca auto-score sem regra |
| AI-07 | `OWNS` oculto / “controle de fato” | Inferir controle além do QSA | **Alto** — especulativo | Sempre speculative; off default |
| AI-08 | Agrupar `ECONOMIC_GROUP` | Clustering supervisionado | Erro de grupo | Aceite analista |
| AI-09 | `FUNDED_BY` emenda→contrato | Ligação narrativa em documentos orçamentários | Erro | Citação obrigatória |
| AI-10 | Classificar `relation_kind` em RELATED_TO | Tipagem semântica | Erro de parentesco | Base legal check |

### 3.2 Pipeline conceitual de promoção

```text
Signal/Doc/Path features
  → AI candidate edge (layer=ai, status=proposed)
  → Scoring + policy (tenant)
  → Human accept / reject / expire
  → Se accept com evidência forte: materializa L2 rule ou L1 observed
  → AuditEvent + Explainable Graph payload
```

### 3.3 O que a IA **não** deve fazer

1. Criar `RELATED_TO` familiar sem trecho de fonte.
2. Escrever sanção “confirmada” sem lista oficial.
3. Inferir crime/colusão como fato.
4. Usar dados de Tenant A para edges do Tenant B.
5. Treinar modelos com PII além da base legal.

---

## 4. Features para modelos (conceitual)

Para AI-01/02/06 tipicamente:

- Similaridade de nomes (Jaro-Winkler, embeddings).
- Co-ocorrência de hubs (phone, address, email).
- Overlap de vizinhos (Jaccard de ego-network).
- Distância temporal de eventos conjuntos.
- Compatibilidade geográfica.
- Confiança prévia das arestas no path.

**Saída:** probabilidade calibrada + **explanation vector** (ver Explainable Graph).

---

## 5. Precedência e conflitos

Quando L1, L2 e L3 discordam:

1. Exibir L1 como fato.
2. Exibir L2 como “mesmo X (regra)”.
3. Exibir L3 como “sugestão”.
4. Em export de dossiê, camadas listadas separadamente no manifesto.

---

## 6. Métricas de qualidade das arestas derivadas/IA

| Métrica | Alvo |
|---------|------|
| Precision@review de AI-02 (sanções) | Alta — priorizar baixos FP |
| Taxa de aceite humano AI-01 | Monitorar drift |
| Average weight de SHARES_PHONE após denylist | Estável |
| % edges L3 sem citation span | → 0 |