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

# Análises de risco

> Como o veredito é composto e onde encontrar cada dado

Uma análise (`POST /analyses`) roda o workflow de risco PLD/FT completo para
uma entidade e devolve o veredito na mesma resposta — não há fila nem
necessidade de consultar o status depois.

## Veredito (`POST /analyses` e `GET /analyses/{uuid}`)

A resposta principal é enxuta de propósito — dados mais pesados (grafo,
sinais, eventos) ficam em sub-recursos separados, listados em `links`:

| Campo           | Conteúdo                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------- |
| `uuid`          | Identificador da análise — use nas chamadas seguintes.                                            |
| `subject`       | Dados cadastrais da entidade (nome, documento, tipo, endereço).                                   |
| `risk`          | Score (0-100), banda de risco, composição por pilar, piso dispositivo aplicado.                   |
| `signal_counts` | Quantidade de sinais identificados, total e por pilar.                                            |
| `versions`      | Versões do catálogo de regras/regulatório que produziram o resultado — importante para auditoria. |
| `links`         | URLs dos sub-recursos abaixo.                                                                     |

## Sub-recursos

<CardGroup cols={2}>
  <Card title="Grafo de relacionamentos" icon="diagram-project">
    `GET /analyses/{uuid}/graph` — nós e arestas da rede (sócios, processos,
    sanções, vínculos societários e familiares).
  </Card>

  <Card title="Sinais identificados" icon="triangle-exclamation">
    `GET /analyses/{uuid}/signals` — cada sinal identificado, com evidências
    e o quanto contribuiu para o score.
  </Card>

  <Card title="Eventos relevantes" icon="timeline">
    `GET /analyses/{uuid}/events` — linha do tempo dos fatos que embasaram a
    análise.
  </Card>

  <Card title="Explicação operacional" icon="comment-lines">
    `POST` ou `GET /analyses/{uuid}/explanation` — resumo executivo em
    linguagem natural, gerado sob demanda (não vem pronto no veredito).
  </Card>
</CardGroup>

<Tip>
  A explicação operacional é gerada por LLM e tem custo — por isso é sob
  demanda. Chame `GET` primeiro; se retornar `404` (nunca foi gerada), aí
  sim chame `POST` para gerar.
</Tip>

## Score e banda de risco

`risk.score` é um número de 0 a 100. `risk.risk_level` classifica esse score
em `low`, `medium`, `high` ou `critical`. Quando um sinal específico ou uma
regra de acumulação impõe um **piso** (`band_floors_applied`), o score final
nunca fica abaixo desse piso, mesmo que a soma dos sinais individuais desse
menos.