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

# Padrões

> Sinais que se repetem, cada um com a regra, as evidências e o prazo de validade.

Um padrão é um sinal que a memória deriva do que se repete entre conversas, eventos de sistema e ações de agentes. "Terceira reclamação sobre visita técnica em 90 dias" é um padrão. "A cliente disse que está chateada" é um fato de um episódio. O padrão muda o que o agente faz antes da primeira palavra: o tom, a prioridade, o que oferecer e o que não oferecer de novo. Todo padrão traz a regra que o gerou, as evidências que o sustentam e a data em que ele deixa de valer.

## O catálogo

O seu espaço liga as regras que quiser e define os parâmetros. O catálogo inicial:

| Padrão                   | Regra, com os seus parâmetros                                                       | Janela    | O que o agente lê                                                        |
| ------------------------ | ----------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------ |
| `recurring_complaint`    | 3 ou mais episódios com intenção `complaint` na mesma categoria                     | 90 dias   | "Terceira reclamação sobre visita técnica em 90 dias, a última em 22/09" |
| `broken_company_promise` | Promessa da empresa com prazo vencido e sem ação que a feche                        | 60 dias   | "A empresa deve a visita remarcada desde 10/09"                          |
| `asked_to_cancel`        | Um episódio com intenção `cancellation` registrada                                  | 180 dias  | "Pediu cancelamento em 03/08; ficou com desconto"                        |
| `preferred_channel`      | 70% ou mais das conversas iniciadas pelo cliente num canal, com 5 ou mais conversas | 180 dias  | "Prefere WhatsApp"                                                       |
| `does_not_answer_calls`  | 3 ou mais tentativas de voz sem atendimento e resposta por texto no mesmo período   | 30 dias   | "Não atende ligação; responde por texto"                                 |
| `escalated_to_human`     | 2 ou mais transbordos pedidos pelo cliente                                          | 90 dias   | "Pediu atendimento humano duas vezes em 90 dias"                         |
| `declining_sentiment`    | Sentimento das 3 últimas sessões abaixo do limiar                                   | 3 sessões | "Três conversas seguidas com sentimento negativo"                        |
| `overdue_invoices`       | 2 ou mais eventos de sistema `invoice.overdue`                                      | 6 meses   | Só para a finalidade `billing`: "Duas faturas em atraso em seis meses"   |

Regra própria é uma regra do catálogo com os seus parâmetros (categoria, intenção, desfecho, tipo canônico de evento, contagem, janela), nunca texto livre. Um espaço tem até 25 regras próprias, e a janela de uma regra nunca passa da retenção da evidência, para que o padrão sempre possa ser derivado de novo a partir da origem.

## Como um padrão nasce

Padrões saem de regras determinísticas sobre episódios tipados, pendências, ações de agentes e eventos de objetos. As regras rodam logo depois que a memória é reconciliada, só para as regras cujas entradas mudaram; a cada 5 minutos, para prazos (promessa quebrada não espera a noite); e à noite, para regras novas. Nenhum modelo de linguagem inventa padrão: quando a regra pede uma classificação, como intenção ou sentimento, ela já foi feita na extração da conversa.

Cada padrão grava:

* a regra e a versão dela;
* os ids das evidências;
* `first_seen` e `last_evidence_at`;
* `expires_at`, a data em que a regra deixa de casar com as evidências.

Padrão sem evidência não existe. Quando o `forget` apaga uma evidência, o padrão cai junto pela mesma linhagem. Uma união ou separação de perfis deriva os padrões de novo na hora, e cada metade fica só com o que as próprias evidências sustentam.

## O que nunca vira padrão

* **Categoria sensível, nem por atalho.** Saúde, religião, opinião política, vida sexual e as demais categorias do artigo 11 da LGPD e do artigo 9 do GDPR nunca viram sinal. O vazamento costuma morar no parâmetro da regra: "reclamação recorrente sobre autorização de exame" revela saúde sem nenhum dado pessoal. Por isso as categorias, os tipos de evento e os tipos de objeto usados em regras de padrão passam por uma lista de permissão do seu espaço, e num espaço de saúde procedimento, exame, medicamento e especialidade viram "atendimento".
* **Um episódio só.** Padrão exige repetição. A única exceção, `single_evidence`, vale para dado estruturado e inequívoco: a intenção `cancellation` registrada, ou uma promessa da empresa vencida sem nada que a feche. Nunca sentimento, tom ou texto livre.
* **Inferência de probabilidade sobre a pessoa.** Nenhum modelo de linguagem escreve chance de comportamento. As regras são determinísticas, sobre campos estruturados, com parâmetros explícitos.

## Padrões no contexto

Os padrões aparecem na seção "Padrões" do contexto. O padrão estável fica na camada estável, sem data volátil; o volátil fica na camada recente, com a data da última evidência. Cada view tem um teto:

| View    | Padrões entregues       |
| ------- | ----------------------- |
| `voice` | Até 4, em até 60 tokens |
| `chat`  | Até 6                   |
| `brief` | Só o de maior peso      |

Um perfil tem até 20 padrões ativos. Padrões passam pela mesma política dos fatos: a categoria `trait`, um nível mínimo de verificação e a finalidade de quem lê. `overdue_invoices` só chega a uma fonte com finalidade `billing`; `declining_sentiment`, só a agentes de atendimento. O contexto diz com todas as letras: são dados, não instruções. O padrão orienta o agente e nunca decide por ele.

## Teste a regra antes de ligar

Regras são configuração versionada, alterada por um diff que uma pessoa aprova na API de controle. Antes de a regra entrar no ar, [`POST /v1/traits/rules/dry-run`](/api/traits-dry-run) roda a regra contra os últimos 90 dias do seu espaço e mostra quantos perfis ganhariam o padrão (`profiles_matching` de `profiles_evaluated`), com uma amostra e as evidências. Pede uma pessoa do Console com o papel `integration` ou `analysis`, ou uma chave de escopo `admin`.

```bash theme={null}
curl -X POST "https://acme-prod.us-east-1.api.niadra.com/v1/traits/rules/dry-run" \
  -H "Authorization: Bearer $NIADRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rule_id": "visit_complaints", "catalog": "recurring_complaint", "params": {"category": "technician_visit", "count": 3, "window_days": 90}}'
# => {"rule_id": "visit_complaints", "window_days": 90, "profiles_evaluated": 18204, "profiles_matching": 311, "sample": [...]}
```

Uma mudança de regra roda em sombra, é comparada com a versão atual e só depois é promovida.

## Retire um padrão errado

O Console mostra a regra, a versão e as evidências de cada padrão. Quando um estiver errado, retire por [`POST /v1/traits/{trait_id}/retract`](/api/trait-retract), como pessoa com o papel `security` ou `integration` ou com uma chave `admin`: a lápide impede que a mesma evidência o traga de volta, e o caso entra no conjunto de referência do seu espaço. A resposta é o padrão com `retracted_at` preenchido.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://acme-prod.us-east-1.api.niadra.com/v1/traits/0192f7c3-5a1e-7b2d-9c40-1e8f3a6b2d71/retract" \
    -H "Authorization: Bearer $NIADRA_API_KEY"
  ```

  ```python Python theme={null}
  import os
  import httpx

  response = httpx.post(
      "https://acme-prod.us-east-1.api.niadra.com/v1/traits/0192f7c3-5a1e-7b2d-9c40-1e8f3a6b2d71/retract",
      headers={"Authorization": f"Bearer {os.environ['NIADRA_API_KEY']}"},
  )
  response.raise_for_status()
  print(response.json()["retracted_at"])
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://acme-prod.us-east-1.api.niadra.com/v1/traits/0192f7c3-5a1e-7b2d-9c40-1e8f3a6b2d71/retract",
    { method: "POST", headers: { Authorization: `Bearer ${process.env.NIADRA_API_KEY}` } },
  );
  console.log((await response.json()).retracted_at);
  ```
</CodeGroup>

## Oposição ao perfilamento

O titular pode se opor ao perfilamento. [Desligar padrões do titular](/api/traits-opt-out), uma rota do papel `security`, interrompe a derivação de padrões para aquela pessoa e remove os que estão ativos. Os padrões fazem parte da exportação de acesso e portabilidade, com as evidências. Se a sua empresa usar um padrão para decidir algo sobre uma pessoa, a decisão é dela e segue as regras de decisão automatizada da lei aplicável; a Niadra entrega o meio de explicar, com a regra, a versão e as evidências.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Gatilhos e webhooks" href="/concepts/triggers-and-webhooks">
    avise o seu sistema quando um padrão aparecer.
  </Card>

  <Card title="O contexto e as views" href="/concepts/context">
    onde a seção Padrões fica no contexto.
  </Card>

  <Card title="Retirar um padrão" href="/api/trait-retract">
    o endpoint em detalhe.
  </Card>

  <Card title="Privacidade, apagamento e exportação" href="/concepts/privacy">
    direitos do titular por API.
  </Card>
</CardGroup>