Referência de configuração

Todo campo de oloproof.yaml e release.yaml, com o seu tipo, o seu padrão, os valores que aceita e um exemplo, extraídos dos modelos que leem os arquivos. Use-a para consultar um campo; leia as páginas do início rápido e de gate para aprender o fluxo de trabalho.

Os dois arquivos são validados antes que qualquer coisa rode. Um campo desconhecido, um campo com erro de grafia ou um valor do tipo errado é um erro de configuração, e o comando sai com 2 sem executar nenhum caso. Os dois arquivos têm JSON Schemas, que um editor capaz de ler JSON Schema pode usar para autocompletar. O pacote instalado os grava, junto com os schemas de resultado, em schemas/v1/ sob o diretório atual: python -m oloproof_core.models.schema_export (os dois são project_config.schema.json e release_policy.schema.json).

Nas tabelas abaixo, "obrigatório" significa que o arquivo é recusado sem o campo; qualquer outro campo mostra o valor usado quando é omitido.

oloproof.yaml em resumo

Um projeto pequeno e completo. Ele roda uma função Python localmente, não precisa de rede nem de chaves, e é a forma que o oloproof init gera.

# oloproof.yaml
version: 1
project: support-bot
dataset: datasets/support.jsonl
system:
  name: support-bot
  callable: app.bot:answer
evaluators:
  - type: exact_match
    criterion: correct_label
    field: label

Campos de nível superior

concurrency

Entradas de pricing

O Oloproof não traz nenhuma tabela de preços. Cada entrada nomeia um modelo exatamente como o model: de um avaliador o nomeia.

# oloproof.yaml
version: 1
project: support-bot
dataset: datasets/support.jsonl
system:
  name: support-bot
  callable: app.bot:answer
evaluators:
  - type: exact_match
    criterion: correct_label
    field: label
pricing:
  - model: my-judge-model
    input_per_mtok: 0.15
    output_per_mtok: 0.6
egress: [raw_outputs]

system

Um sistema precisa de exatamente um entre callable, http ou rag.

system.http

# oloproof.yaml
version: 1
project: support-api
dataset: datasets/support.jsonl
system:
  name: support-api
  version: "2026-10-08"
  http:
    url: http://localhost:8000/answer
    output_path: answer
    artifacts:
      retrieval/v1: debug.retrieval
evaluators:
  - type: hit_rate
    k: 5

O contrato de requisição e resposta, e o que acontece com timeouts e erros HTTP, estão em Resultados e execução.

system.rag

As configurações dadas aqui substituem as que a classe declara. Um sistema em estágios registra os seus próprios artefatos retrieval/v1, context/v1 e citations/v1, então records é recusado ao lado dele. Veja RAG.

evaluators

Toda entrada recebe um type e estes dois campos comuns:

fail só se aplica a avaliadores de aprovação ou reprovação; um avaliador de pontuação com ele é um erro de configuração. on_execution_error é um campo YAML; as classes de avaliadores do SDK não recebem esse argumento, e um caso com erro conta como faltante.

Tipos de avaliador

"Lê" lista aquilo de que o veredicto do avaliador depende, que também é a chave do seu julgamento em cache. "SDK" nomeia a classe em oloproof.evaluators.

Um juiz que chama um modelo hospedado envia o conteúdo dos casos a esse provedor e é cobrado por ele. As chaves são lidas da variável de ambiente nomeada em api_key_env; o Oloproof nunca as armazena nesses arquivos.

Avaliadores determinísticos

Juízes baseados em modelo

rubric_judge, groundedness_judge e citation_support_judge compartilham estes campos. rubric_judge exige exatamente um entre rubric_file e rubric_text; os dois juízes de RAG aceitam no máximo um e, caso contrário, usam uma rubrica embutida. O criterion deles tem como padrão groundedness e citation_support.

probability_judge faz uma pergunta tipada e lê as probabilidades do modelo:

cascade roda primeiro um juiz barato e escala os casos incertos:

Os estágios julgam o próprio criterion da cascata; um estágio que nomeia um diferente é recusado.

model_classifier pontua um texto com um modelo treinado em um servidor compatível com TEI:

Avaliadores de RAG

Avaliadores de agentes

Cada tipo de agente tem um criterion padrão, então ele pode ser omitido: o próprio nome do tipo, ou um montado a partir da sua configuração (agent_steps_le_8, agent_tool_lookup_called, agent_handoffs_le_2). Veja Agentes.

Avaliadores preditivos

Um avaliador preditivo que não escreve positive, field ou expected_field o recebe do bloco predictive:; um valor que ele escreve é mantido.

predictive

metrics

Cada critério de avaliador já é uma métrica. Uma entrada de metrics: acrescenta mais uma, distinguida por type.

# oloproof.yaml
version: 1
project: support-bot
dataset: datasets/support.jsonl
system:
  name: support-bot
  callable: app.bot:answer
evaluators:
  - type: exact_match
    criterion: correct_label
    field: label
metrics:
  - id: latency_p95
    type: quantile
    source: latency_ms
    quantile: 0.95

release.yaml

A política de lançamento: quais regras decidem e quais decisões bloqueiam. As configurações omitidas mantêm os seus padrões, então uma política que nomeia apenas as suas regras ainda bloqueia em FAIL, INSUFFICIENT_EVIDENCE e MANUAL_REVIEW.

# release.yaml
version: 1
rules:
  - id: label_accuracy
    metric: correct_label
    min: 0.8

rules

Uma única lista contém os dois tipos. Uma regra de execução recebe exatamente um entre min, max ou max_failures. Uma regra de comparação nomeia o seu kind e decide uma diferença entre duas execuções; veja Regras de comparação.

families

# release.yaml
version: 1
warn_on: [INSUFFICIENT_EVIDENCE]
block_on: [FAIL, MANUAL_REVIEW]
rules:
  - id: label_accuracy
    metric: correct_label
    min: 0.8
    max_missing_fraction: 0.05
  - id: no_regression
    metric: correct_label
    kind: non_inferiority
    margin: 0.02

Tipos de artefato

Um artefato é um registro tipado que um sistema grava ao lado da sua saída, como o que ele recuperou. Um tipo é um nome em minúsculas com uma versão opcional, que corresponde a ^[a-z][a-z0-9_]*(/v[1-9][0-9]*)?$. Os avaliadores que precisam de um artefato o nomeiam, e uma execução cujo sistema não declara um tipo exigido é recusada antes de começar, em vez de contar todos os casos como faltantes.

Um sistema callable declara os tipos que registra em records: (ou @system(records=...)); um sistema HTTP em http.artifacts; um sistema RAG em estágios registra os seus próprios.

Versões, chaves de cache e invalidação

O Oloproof reaproveita o trabalho cujas entradas não mudaram, e decide o que "inalterado" significa a partir de digests do conteúdo. Cada um é calculado pelo engine e registrado com a execução.

O que o Oloproof não consegue ver cabe a você declarar:

• O comportamento de um sistema HTTP fica no servidor. Mude system.version sempre que o que está por trás da URL mudar, senão uma saída antiga em cache vai valer pelo novo sistema.
• Os módulos auxiliares de um callable só entram no hash quando code_paths os inclui. Sem isso, editar um módulo auxiliar não muda a versão.
• Um método ou um objeto callable precisa declarar uma versão, e a versão precisa mudar quando o estado do objeto muda.
• Um índice RAG é identificado por index_version; mude-o quando o índice for reconstruído.
• A identidade de um juiz baseado em modelo são as suas configurações, não os pesos do provedor. Um provedor que atualiza o modelo por trás do mesmo nome não é detectado pelo cache.
• Um @evaluator personalizado faz o hash do arquivo do módulo que o define, e os seus julgamentos só são reaproveitados entre execuções quando ele declara cacheable=True. Os juízes de rubrica embutidos são cacheáveis; os avaliadores determinísticos são recalculados, o que é barato.

O trabalho em cache fica no store local do projeto, .oloproof/store.sqlite ao lado de oloproof.yaml (ou em OLOPROOF_HOME). Apagar o store descarta todo cache e toda execução. Em um espaço de trabalho hospedado o engine não reaproveita execuções, julgamentos ou análises em cache, porque um push pode gravá-los; ele recalcula.