O contrato de resposta

Uma simulação devolve achados prontos. Quando você quer uma resposta a uma pergunta sua, a pergunta vai no pedido, antes de rodar: é o contrato de resposta. O job devolve uma resposta por pergunta, com o número e uma frase em português, calculados por código a partir das tabelas que a simulação publicou, nunca a partir de uma pessoa sintética e nunca escritos por um modelo de linguagem.

No chat, o assistente escreve o contrato a partir do que você pergunta, lista as perguntas para você confirmar, e o botão roda o job com elas. Pela API e pelo MCP, o contrato vai no cenário.

As perguntas

O contrato fica em contrato_de_resposta, no cenário:

{
  "contrato_de_resposta": {
    "versao": 1,
    "perguntas": [
      {
        "id": "mulheres-semana-2",
        "forma": "quantos",
        "medida": "alcance",
        "publico": { "sexo": [1], "grupo_idade": [2, 3] },
        "territorio": { "municipios": ["2601201"] },
        "momento": { "semana": 2 }
      },
      {
        "id": "oito-em-dez",
        "forma": "quando",
        "medida": "absorve",
        "territorio": { "municipios": ["2601201"] },
        "momento": { "parte": 0.8 }
      },
      {
        "id": "setores-mais-fracos",
        "forma": "onde",
        "medida": "absorve",
        "territorio": { "ponto": [-37.055, -8.418], "raio_m": 1500 },
        "momento": { "semana": 4 },
        "ordem": "menor"
      },
      {
        "id": "sem-radio",
        "forma": "comparar",
        "variantes": ["base", "sem:radio"],
        "pergunta": {
          "id": "alcance-semana-4",
          "forma": "quantos",
          "medida": "alcance",
          "territorio": { "municipios": ["2601201"] },
          "momento": { "semana": 4 }
        }
      }
    ]
  },
  "saida_por_setor": true
}

forma:
- quantos: a contagem acumulada da medida para o público no território, no fim da semana;
- quando: a primeira semana em que essa contagem alcança uma parte (momento.parte, de 0 a 1) do público publicado no território. A parte é do público, não de quem vai aderir: “quando metade da cidade terá comprado” é um quando com parte 0,5; “quando metade dos que vão comprar terá comprado” não é uma pergunta do contrato, e a resposta dela é o dia_50 da tabela saturacao dos achados, o primeiro dia em que a curva chega à metade do próprio total no horizonte;
- onde: as unidades do território (municípios ou setores) ordenadas pela contagem na semana, as dez primeiras, por posição, nunca por um corte;
- comparar: uma das três acima respondida em duas variantes do plano (base, intensidade_x0.9:<canal> e, com mais de um canal, sem:<canal>), lado a lado, com a diferença.
medida: na adoção, adotantes; na recepção, alcance (a soma das primeiras exposições, pelo boca a boca e pela mídia), ignora, absorve, repassa ou rejeita.
publico: os eixos da grade publicada, por índice (grupo_idade de 0 a 6, das faixas de 0–9 a 60 ou mais; sexo 0 masculino e 1 feminino; renda de 0 a 4; escolaridade de 0 a 4; raca). Um eixo ausente quer dizer todos. Num público em faixas de 5 anos, aberto hoje em todas as UFs menos o Piauí, a grade é a etária: faixa_etaria_5 e sexo.
territorio: exatamente um de municipios (códigos de 7 dígitos), setores (códigos de 15 dígitos) ou ponto ([longitude, latitude]) com raio_m (de 50 a 50.000 metros: os setores cujo centro fica dentro do raio). As duas formas por setor pedem saida_por_setor: true no cenário e não levam publico: a tabela por setor não cruza o setor com as células do público.
momento: semana (blocos de 7 dias a partir do dia 1) em quantos e onde; parte em quando.
Limites: até 20 perguntas, cada uma com um id próprio. O contrato entra na identidade do pedido: o mesmo cenário com perguntas diferentes é outro job. O preço não muda com o contrato.

Um contrato que não cabe no formato é recusado na cotação, com o código e o campo da pergunta (códigos).

As respostas

GET /v1/jobs/{id}/respostas (e get_answers no MCP) devolve o contrato como o job o leu e uma resposta por pergunta:

{
  "id": "mulheres-semana-2",
  "forma": "quantos",
  "medida": "alcance",
  "retido": false,
  "numero": 3120,
  "unidade": "pessoas",
  "base": { "unidades": 1, "retidas": 4, "replicas": 1 },
  "frase": "Na semana 2, 3.120 mulheres de 20 a 39 anos em Arcoverde tinham sido alcançadas (4 células retidas pela regra dos 5)."
}

numero é a média das réplicas (com o mínimo e o máximo ao lado); quando dá a semana, e onde, as unidades com o número de cada uma.
O que a regra dos 5 reteve é contado e dito: contagens de 1 a 4 pessoas não são publicadas, então a resposta erra para baixo onde elas faltam, e base diz quantas faltaram.
Sem número: retido: true com o motivo, por exemplo nao_alcancado_no_horizonte (a parte não foi alcançada no horizonte) ou tudo_retido (todas as células do público ali foram retidas). A frase diz o motivo.
Respostas por setor e o corte do diagnóstico: uma resposta por setor (uma lista de setores, ou um ponto com raio_m) lista em base.setores os setores em que foi calculada, os de um ponto inclusive. Ela sai sem número, com retido: true e o motivo do corte (erro_acima_do_corte, erro_nao_medido ou sem_populacao_sintetica), quando algum desses setores não passa no corte de erro do diagnóstico, como na tabela por setor. Uma comparação sobre essa pergunta sai sem número dos dois lados. Uma resposta por ponto de um job que rodou antes de as respostas listarem os setores sai sem número, com setores_do_ponto_nao_listados: sem a lista, o corte não pode ser conferido.
Antes de o job concluir, o pedido é recusado com 409 result_not_ready. Um job sem contrato devolve a lista vazia.

Os eventos por setor e o replay

Com saida_por_setor: true, a simulação publica também os eventos de cada setor censitário por semana, com a regra dos 5 dentro do setor-semana. GET /v1/jobs/{id}/setores?municipio=<código>&semana=<n> traz, para um município e uma semana, a contagem de cada setor ou o motivo de ela faltar:

menor_que_k e complementar: a regra dos 5;
erro_acima_do_corte, erro_nao_medido e sem_populacao_sintetica: o setor onde a população sintética erra acima do corte do diagnóstico não recebe número.

A contagem de cada setor é a média das réplicas, arredondada. Em cada réplica, a regra dos 5 só publica zero ou ao menos 5, mas a média pode ficar entre 1 e 4: zero numa réplica e 5 na outra dão 2. Um número assim é uma média, não uma contagem de pessoas.

Como os achados, a tabela por setor e as respostas por setor deixam de fora as pessoas das células retidas pela regra dos 5: a diferença entre a tabela por setor e os achados não as revela.

No app, o Replay do console da cidade anima essas contagens semana a semana e mostra as respostas do contrato no painel de números.