> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strattum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# NER Review

> Fila de revisão de entidades detectadas automaticamente em fontes não-estruturadas. Controle sobre o que entra no Knowledge Graph.

O **NER Review** é a interface de curadoria das entidades identificadas pelo motor de Named Entity Recognition (NER) da Memory. Quando o pipeline processa fontes como Slack, Confluence, e-mail ou transcrições de reunião, as entidades detectadas — empresas, pessoas, produtos — passam por um fluxo de confiança antes de ser adicionadas ao Knowledge Graph.

Abaixo do threshold de confirmação automática, essas entidades aparecem na fila de revisão para que o time decida o que aceita, rejeita ou mescla.

> [!NOTE]
>
> A página de NER Review é acessível pelo botão **NER Review** no header da página Memory, dentro do Console.

***

## Fluxo de confiança

Cada fonte tem dois thresholds configuráveis que determinam o destino de cada entidade detectada:

```
Score da entidade
      │
      ▼
┌─────────────────────────────────────────────────────────┐
│  ≥ Auto-confirm threshold  →  Aceita automaticamente    │
│  ≥ Review threshold        →  Entra na fila de revisão  │
│  < Review threshold        →  Rejeitada silenciosamente │
└─────────────────────────────────────────────────────────┘
```

* **Auto-confirm threshold**: entidades com score igual ou acima deste valor são adicionadas diretamente ao Knowledge Graph, sem intervenção manual.
* **Review threshold**: entidades com score entre este valor e o auto-confirm entram na fila para revisão manual.
* **Abaixo do review threshold**: descartadas silenciosamente — não aparecem na fila.

### Thresholds padrão por fonte

| Fonte | Auto-confirmar | Revisar |
| - | - | - |
| Slack | 85% | 50% |
| Confluence | 85% | 50% |
| Google Drive | 85% | 50% |
| Meeting Transcript | 80% | 50% |
| E-mail | 90% | 70% |
| Notion | 85% | 50% |

> [!TIP]
>
> E-mail tem threshold de revisão mais alto (70%) porque a variação de nomes e contexto em mensagens de e-mail tende a gerar mais falsos positivos do que fontes estruturadas como Confluence.

Os thresholds são configuráveis por fonte via API — consulte a seção [Gerenciar thresholds](#gerenciar-thresholds) abaixo.

***

## A fila de revisão

Cada item na fila exibe as informações necessárias para uma decisão informada:

| Campo | Descrição |
| - | - |
| **Texto detectado** | O trecho exato identificado como entidade |
| **Tipo de entidade** | Empresa, pessoa ou produto |
| **Fonte** | Origem do documento (Slack, Confluence, Google Drive, etc.) |
| **Score de confiança** | Percentual de confiança do modelo NER |
| **Documento de origem** | Referência ao documento de onde a entidade foi extraída |
| **Status** | `pendente`, `confirmado` ou `rejeitado` |

***

## Ações disponíveis

### Por item

> **Confirmar**
>
> Aceita a entidade e a adiciona ao Knowledge Graph. Use quando o texto detectado corresponde corretamente a uma entidade real.

> **Rejeitar**
>
> Descarta a entidade. Use quando o texto não representa uma entidade válida ou é um falso positivo.

> **Remapear**
>
> Redireciona a entidade para outra entidade já existente no grafo. Útil para deduplicação — por exemplo, "M. Silva" remapeada para "Maria Silva".

### Em bulk

Selecione múltiplos itens com status `pendente` e confirme todos de uma vez. Útil para processar lotes de entidades de alta confiança que ficaram abaixo do threshold de confirmação automática por configuração conservadora.

***

## Gerenciar thresholds

Os thresholds de cada fonte são configuráveis diretamente pela API. Ajustes têm efeito imediato sobre novos itens processados — itens já na fila não são reclassificados retroativamente.

### Listar thresholds atuais

```bash theme={null}
GET /v1/memory/ner-review/thresholds
```

**Resposta de exemplo:**

```json theme={null}
[
  {
    "source_type": "slack",
    "auto_confirm_threshold": 0.85,
    "review_threshold": 0.50
  },
  {
    "source_type": "email",
    "auto_confirm_threshold": 0.90,
    "review_threshold": 0.70
  }
]
```

### Atualizar threshold de uma fonte

```bash theme={null}
PUT /v1/memory/ner-review/thresholds/{source_type}
```

**Body:**

```json theme={null}
{
  "auto_confirm_threshold": 0.90,
  "review_threshold": 0.60
}
```

> [!WARNING]
>
> Reduzir o `review_threshold` aumenta o volume de itens na fila. Reduzir o `auto_confirm_threshold` aumenta o volume de itens que precisam de revisão manual antes de entrar no grafo. Ajuste gradualmente e monitore o impacto via Observability.

***

## API Reference

### Listar itens da fila

```bash theme={null}
GET /v1/memory/ner-review
```

Suporta paginação e filtros por `status` e `source_type`.

**Parâmetros de query:**

| Parâmetro | Tipo | Descrição |
| - | - | - |
| `status` | `string` | Filtra por `pending`, `confirmed` ou `rejected` |
| `source_type` | `string` | Filtra por fonte: `slack`, `confluence`, `google_drive`, `meeting_transcript`, `email`, `notion` |
| `page` | `integer` | Número da página (default: 1) |
| `page_size` | `integer` | Itens por página (default: 50, máx: 200) |

**Exemplo:**

```bash theme={null}
GET /v1/memory/ner-review?status=pending&source_type=slack&page=1&page_size=50
```

***

### Atualizar um item

```bash theme={null}
PATCH /v1/memory/ner-review/{item_id}
```

**Body para confirmar:**

```json theme={null}
{
  "action": "confirm"
}
```

**Body para rejeitar:**

```json theme={null}
{
  "action": "reject"
}
```

**Body para remapear:**

```json theme={null}
{
  "action": "remap",
  "target_entity_id": "ent_abc123"
}
```

***

### Confirmar em bulk

```bash theme={null}
POST /v1/memory/ner-review/bulk
```

**Body:**

```json theme={null}
{
  "item_ids": ["item_001", "item_002", "item_003"],
  "action": "confirm"
}
```

***

### Listar e atualizar thresholds

```bash theme={null}
GET  /v1/memory/ner-review/thresholds
PUT  /v1/memory/ner-review/thresholds/{source_type}
```

Detalhes e exemplos na seção [Gerenciar thresholds](#gerenciar-thresholds) acima.

***

## Boas práticas

> **Comece com thresholds conservadores**
>
> Nas primeiras semanas, mantenha o `auto_confirm_threshold` alto (90%+) para revisar manualmente um volume maior e entender a qualidade do NER nas suas fontes específicas. Após calibrar, eleve os thresholds gradualmente para reduzir trabalho manual.

> **Use o remapeamento para deduplicação progressiva**
>
> O remapeamento é a ferramenta mais poderosa para manter o grafo limpo. Quando a mesma entidade aparece com grafias diferentes ("TechCorp", "Tech Corp Ltda", "TechCorp Brasil"), use o remapeamento para consolidar todas as referências em um único nó canônico.

> **Processe a fila regularmente**
>
> Itens pendentes na fila representam conhecimento que ainda não está disponível para os agentes. Estabeleça uma rotina de revisão — idealmente diária para fontes de alta frequência como Slack — para garantir que o contexto está sempre atualizado.

> **Monitore via Observability**
>
> O produto Observability registra a taxa de NER ambíguo e a cobertura de fontes. Use essas métricas para identificar quais fontes geram mais revisões manuais e avaliar se ajustes de threshold fazem sentido.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.