Referência do objeto response — POST /analyze

O endpoint POST /analyze retorna um objeto JSON com o resultado da análise de risco. O objeto é stateless: reflete exclusivamente a análise daquela chamada específica. O vario não armazena o texto enviado nem o resultado — o objeto response é o único produto da chamada.

Tabela de campos

Como interpretar combined_score

combined_score é um número de ponto flutuante no intervalo 0 a 10:

• 0 — nenhum sinal detectado para a conduta analisada.
• 10 — sinal máximo; a comunicação apresenta indicadores muito fortes da conduta.

A escala é ordinal, não linear: a distância entre 7 e 8 não é equivalente à distância entre 3 e 4. Não compare scores de chamadas distintas como se fossem magnitudes absolutas; use-os para priorizar dentro de um corpus.

O campo severity expressa o mesmo resultado em categorias qualitativas, mais úteis para tomar decisões de triagem. O campo should_alert é o indicador binário recomendado para integrar em fluxos automatizados.

Como interpretar severity

severity categoriza o nível de risco da comunicação:

A determinação de severity é responsabilidade do sistema; a decisão de agir sobre ela é sempre responsabilidade do revisor humano.

Como usar reasoning e key_phrases

reasoning é uma explicação narrativa gerada no idioma do texto analisado. Descreve quais elementos da comunicação contribuíram para o resultado. Seu propósito é dar contexto ao revisor humano — não é um parecer jurídico nem uma conclusão definitiva.

key_phrases é um array de fragmentos extraídos do texto que o sistema identificou como relevantes para a conduta analisada. Podem ser usados para localizar rapidamente as partes da mensagem que motivaram o score.

Considerações importantes:

• Tanto reasoning quanto key_phrases são ferramentas de orientação para o revisor, não substitutos da análise jurídica.
• Quando bedrock_available é false, reasoning pode estar vazio ou ser menos detalhado.
• key_phrases pode ser um array vazio ([]) se o sistema não identificou fragmentos específicos com confiança suficiente.

Como usar regulatory_frameworks

regulatory_frameworks lista os marcos regulatórios que o sistema identificou como potencialmente relevantes para a comunicação analisada. Exemplos de valores possíveis: "FCPA", "DL 211", "MAR", "Lei Anticorrupção 12.846/2013", "CADE", "COFECE".

Considerações importantes:

• Esta lista reflete os marcos que o sistema associou ao sinal detectado. Não é uma opinião jurídica.
• Não substitui assessoria jurídica especializada.
• O array pode estar vazio ([]) se o sistema não identificou marcos com confiança suficiente.

Privacidade

O vario não armazena nem retém o texto analisado. O pipeline é completamente stateless: nenhum dado do campo text nem de thread_context persiste no banco de dados do vario.

Degradação: quando bedrock_available é false

Se a análise profunda não esteve disponível no momento da chamada, o endpoint retorna 200 com bedrock_available: false. Nesse caso:

• reasoning pode estar vazio.
• confidence pode ser "low". Para receber um erro explícito em vez de uma resposta parcial, inclua o header Prefer: deep-analysis-required. Nesse caso, o endpoint retorna 503 DEEP_ANALYSIS_UNAVAILABLE quando a análise profunda não está disponível.

Exemplo de resposta completa

Sinal alto de fixação de preços, analisado no modo full:

{
  "combined_score": 8.4,
  "should_alert": true,
  "severity": "critical",
  "reasoning": "El mensaje contiene una indicación explícita de coordinar el precio mínimo de venta con un competidor. La referencia directa a un valor de precio y la expectativa de que otros actores del mercado lo respetarán son indicadores consistentes con coordinación horizontal de precios.",
  "key_phrases": [
    "no bajamos de $450 la unidad",
    "los demás van a hacer lo mismo",
    "acordamos no competir por precio"
  ],
  "regulatory_frameworks": [
    "DL 211 (Chile)",
    "Lei Anticorrupção 12.846/2013 (Brasil)",
    "COFECE — Ley Federal de Competencia Económica"
  ],
  "recommended_action": "legal_review",
  "confidence": "high",
  "mode_used": "full",
  "analyzed_at": "2026-06-02T14:32:00Z",
  "pipeline_version": "1.0",
  "bedrock_available": true
}

Exemplo no modo fast com sinal baixo

{
  "combined_score": 1.2,
  "should_alert": false,
  "severity": "low",
  "reasoning": "No se identificaron indicadores relevantes de la conducta analizada en el texto proporcionado.",
  "key_phrases": [],
  "regulatory_frameworks": [],
  "recommended_action": "no_action",
  "confidence": "high",
  "mode_used": "fast",
  "analyzed_at": "2026-06-02T14:33:10Z",
  "pipeline_version": "1.0",
  "bedrock_available": true
}

Exemplo com degradação (bedrock_available: false)

{
  "combined_score": 3.1,
  "should_alert": false,
  "severity": "medium",
  "reasoning": "",
  "key_phrases": [],
  "regulatory_frameworks": [],
  "recommended_action": "monitoring",
  "confidence": "low",
  "mode_used": "fast",
  "analyzed_at": "2026-06-02T15:01:42Z",
  "pipeline_version": "1.0",
  "bedrock_available": false
}

Resposta no modo screening

Quando mode_used é "screening", o objeto response tem um schema diferente dos modos fast e full. Inclui apenas resultados da camada L1 (keyword + embedding). Os campos combined_score, should_alert, severity, reasoning, key_phrases, regulatory_frameworks, recommended_action, confidence e bedrock_available não estão presentes.

Exemplo de resposta no modo screening:

{
  "mode_used": "screening",
  "l1_score": 0.82,
  "l1_keyword_score": 0.75,
  "l1_embedding_score": 0.82,
  "l1_matched_terms": ["combinamos não mexer no preço", "preço"],
  "l1_embedding_available": true,
  "playbook": "price_fixing",
  "playbook_version": "1.0",
  "pipeline_version": "1.0",
  "analyzed_at": "2026-06-04T10:15:00Z",
  "external_id": "email-msg-00842"
}

Notas finais

• O output de POST /analyze é um sinal de risco, não uma determinação legal. Não substitui a revisão por parte de um advogado nem constitui evidência perante reguladores.
• O vario alerta; o CCO decide. O princípio de revisão humana faz parte do design do sistema.