APEX

O repositório separa o defensor APEX, a normalização de dados de benchmark, os manifestos de capacidades confiáveis e as integrações de métodos de comparação, para que cada camada possa ser inspecionada de forma independente.

Instalação

python -m venv .venv
source .venv/bin/activate
pip install -e '.[test]'
export PYTHONPATH="$PWD/src:$PWD"

Componentes baseados em modelo leem OPENAI_API_KEY e a variável opcional OPENAI_BASE_URL a partir do ambiente. Copie .env.example apenas como referência; o código não lê arquivos locais de credenciais.

Mapa do repositório

Caminho	Responsabilidade
src/apex/defender/	Contratos de tarefa do APEX, bindings tipados, receipts, verificações de prova, PLANT, WRAP e tratamento de continuação
src/apex/core/	Protocolo compartilhado, tipos de resultado, agregação e fronteira de modelo neutra em relação ao provedor
benchmark/adapter/	Conversão somente leitura de releases de benchmark em uma única interface BenchmarkCase
benchmark/registry/	Registro confiável de capacidades e manifestos específicos de benchmark
baseline/<name>/	Uma implementação ou integração de runtime por método de comparação
tests/	Invariantes do repositório e verificações unitárias rápidas

Consulte STRUCTURE.md para o fluxo de componentes e os pontos de extensão.

Carregando casos de benchmark

Descritores compactos e congelados de casos para todos os seis benchmarks estão incluídos em benchmark/data/. Repositórios upstream completos e sandboxes de runtime não são vendorizados. Passar None seleciona os dados empacotados; um data_root explícito ainda pode substituí-los.

from benchmark.adapter import adapter_for

adapter = adapter_for("scr", None)
attack_cases = list(adapter.cases("attack"))

O adaptador é responsável pelos identificadores de caso, rótulos de divisão, rótulos de suíte, elegibilidade e pelo payload apresentado ao runtime do benchmark. Ele não altera o conteúdo do benchmark nem registra autoridade de ferramentas.

Carregando manifestos confiáveis

from benchmark.registry import module_for

registry = module_for("mcptox")
environment_plan = registry.load("12306-mcp")

Os manifestos de capacidades são mantidos separados dos adaptadores de conjuntos de dados porque o texto de benchmark é uma entrada de episódio não confiável, enquanto um manifesto descreve o limite de execução de propriedade do operador disponível antes do episódio.

Cada benchmark/registry/data/<benchmark>/manifest.json é um artefato de registro final que usa apex-benchmark-registry-v2. Um bundle armazena capability_units desduplicadas, ambientes reutilizáveis e vinculações de casos explícitas. Assim, um benchmark com centenas de casos não duplica um manifesto de Tool idêntico centenas de vezes. Cada unidade mantém o esquema exato de entrada/saída, effect, observation, effect_return, o papel do recibo e anotações tipadas. Cada ambiente registra separadamente as fontes, as Skills e a agent_visible_surface.

As entradas de origem exatas auditadas da implementação do experimento são mantidas em benchmark/registry/source/. A etapa de build normaliza e desduplica esses registros existentes; ela não infere novas semânticas de capacidade a partir dos prompts do benchmark. Regenere todos os artefatos finais com:

pip install -e '.[registry]'
python scripts/build_registry_manifests.py
python scripts/audit_registry_coverage.py

Para atualizar os descritores de casos empacotados a partir dos checkouts locais upstream, execute:

python scripts/import_benchmark_data.py \
  --research-root <research-checkout> \
  --scr-root <SCR_Bench-checkout>

O importador SCR verifica o commit fixado antes de derivar seu índice compacto de exposição de casos/Skills.

Fluxo de execução do APEX

1. TaskContractor compila a solicitação confiável do usuário em um contrato de tarefa.
2. O registro de benchmarks fornece a superfície de capacidade limpa.
3. O motor resolve valores tipados e registra observações como recibos.
4. O PLANT verifica a proveniência em nível de tarefa e a estrutura de compromisso.
5. O WRAP verifica o efeito completo proposto em relação ao contrato e aos recibos.
6. O motor retorna informações de continuação de permitir, negar, reparar ou replanejar.

As verificações determinísticas permanecem independentes do modelo alvo. As funções apoiadas por modelo submetem candidatos tipados que devem passar pela mesma fronteira de validação.

Baselines

baseline/registry.py define os 13 métodos de comparação. Cada método possui uma pasta dedicada com o nome do método e um ponto de entrada implementation.py. Dependências com seu próprio runtime são importadas de forma lazy para que o núcleo do APEX e os adaptadores de dados possam ser testados sem instalar todos os ambientes de benchmark.

Verificação

python -m compileall -q src benchmark baseline tests
pytest

Antes do lançamento, execute também as verificações de anonimato em ANONYMITY.md. Nenhuma credencial, arquivo de resultados, caminho específico da máquina, remote do Git ou metadado de autor deve ser adicionado à submissão.