Gerenciador Multi-Dimensional

O que Gerenciador Multi-Dimensional faz?

Uma skill autocontida que traz ordem ao estado de experimentos computacionais longos e multi-dimensionais. Seu plugin de computação faz a matemática; esta skill gerencia o caos ao redor: iteração, snapshots, auditoria e reversão.

A skill apenas orquestra. Ela nunca computa um resultado por si só – todo número vem do seu plugin.

Quando usar

• Um fluxo de trabalho executa muitas rodadas sobre um espaço de parâmetros (uma grade cartesiana de dimensões) e precisa que o estado de cada rodada seja registrado.
• Snapshots por rodada dos arquivos críticos declarados são necessários antes e depois de cada rodada.
• Uma trilha de auditoria completa (parâmetros, hashes, timestamps, status) deve existir para cada rodada.
• O usuário deve poder reverter para qualquer rodada anterior, de forma não-destrutiva.
• Formatos típicos: estudos longitudinais, varreduras de parâmetros ou sweepings simbólicos/numéricos chamando resolvedores externos (Mathematica, GAP, SymPy, scripts personalizados).

FLUXO DE TRABALHO OBRIGATÓRIO

Bootstrap de dependências (executar no primeiro uso)

Antes da primeira execução, verifique as dependências de tempo de execução para esta skill:

• Núcleo: apenas biblioteca padrão — nenhuma instalação necessária.
• Opcional: PyYAML (apenas quando a configuração for .yaml; configurações JSON funcionam apenas com a biblioteca padrão).

Se o PyYAML estiver faltando e a configuração do usuário for YAML, informe-o e pergunte se deseja pip install pyyaml; instale somente após confirmação explícita. Nunca instale no ambiente global sem consentimento explícito.

Siga estas etapas na ordem sempre que o usuário solicitar executar, inspecionar ou recuperar um experimento multi-dimensional.

1. Carregar a configuração. Leia o experimento config (config.example.yaml é o modelo). Confirme se param_space.dimensions, critical_paths e o plugin.command estão presentes. Se for usado YAML, o PyYAML deve estar instalado; caso contrário, use JSON.
2. Expandir o espaço. Enumere o produto cartesiano de todas as dimensões. Reporte o número total de rodadas ao usuário antes de executar.
3. Preferir dry run. Execute python scripts/run.py dryrun --config <cfg> para que o usuário veja o plano completo (cada combinação de parâmetros) sem nenhum efeito colateral. Prossiga para a execução somente após confirmação.
4. Executar a varredura. Execute python scripts/run.py run --config <cfg>. Para cada rodada, em ordem: snapshot dos caminhos críticos declarados antes, invoque o plugin, snapshot depois e anexe um registro de auditoria.
5. Reagir corretamente a falhas. Se o plugin de uma rodada sair com código diferente de zero, registre seu status (failed/error). Quando auto_rollback estiver ativado, recupere o estado pós-rodada da última rodada bem-sucedida no diretório de trabalho para que as rodadas seguintes comecem limpas; essa recuperação também é auditada. Não pare toda a varredura em uma única combinação ruim.
6. Resumir. Após a varredura, a skill escreve results_summary.csv, results_summary.md, report_draft.md e run_metadata.json sob o diretório de saída. Aponte o usuário para esses arquivos.
7. Recuperar sob solicitação. Para restaurar uma rodada passada, execute python scripts/run.py rollback --config <cfg> --round <N>. Por padrão, restaura em um NOVO diretório; adicione --force apenas quando o usuário quiser explicitamente sobrescrever o diretório de trabalho ativo.

Restrições rígidas

• Nunca compute o resultado você mesmo. Toda matemática de domínio pertence ao plugin do usuário. A skill apenas o chama e registra o resultado do contrato.
• Snapshot apenas dos caminhos críticos declarados. Nunca é feita uma cópia completa do diretório de trabalho; o conteúdo é armazenado endereçado por hash, portanto arquivos inalterados não custam nada extra.
• Reversão é não-destrutiva por padrão. Sem --force, o diretório de trabalho ativo nunca é modificado; o estado restaurado vai para um novo diretório. Toda reversão (manual ou automática) é registrada no log de auditoria.
• Determinismo é promessa do usuário. A skill garante que a orquestração é reproduzível (mesmos parâmetros -> mesmo plano registrado, mesmos hashes). Ela não pode tornar um plugin não-determinístico determinístico; veja Limitações.

Exemplos de uso

# Imprime o plano completo de rodadas sem nenhum efeito colateral (sempre faça isso primeiro).
python scripts/run.py dryrun --config config.example.yaml

# Executa a varredura.
python scripts/run.py run --config config.example.yaml

# Restaura uma rodada passada (em um NOVO diretório, a menos que --force).
python scripts/run.py rollback --config config.example.yaml --round 7

# Regenera os resumos, ou verifica o resultado de uma rodada.
python scripts/run.py summary --config config.example.yaml
python scripts/run.py verify --config config.example.yaml --round 7

Contrato do plugin

O gerenciador lança exatamente um comando shell por rodada:

python your_plugin.py --params {PARAMS} --out {OUT}

• {PARAMS} - caminho para um arquivo JSON com a combinação de parâmetros desta rodada.
• {OUT} - caminho para o qual o plugin DEVE escrever seu JSON de resultado.
• Códigos de saída: 0 sucesso, 1 falha na asserção/verificação, 2 erro ou ignorado.

Qualquer resolvedor externo (Mathematica, GAP, um script Python LMM) é encapsulado para honrar este contrato: ele lê o arquivo de parâmetros e escreve um arquivo de resultado. A skill não se importa com o que é computado.

Tratamento de falhas

• Uma rodada cujo plugin sai com 1 é marcada como failed; saída 2 é error. Ambos são mantidos no log de auditoria; a varredura continua.
• Erros de config (espaço faltando, YAML inválido, {OUT} faltando) abortam antes de qualquer efeito colateral e imprimem uma mensagem clara (código de saída 2).
• rollback para uma rodada que nunca foi registrada, ou que não tem pós-snapshot, falha com um erro claro em vez de corromper o estado.

Limitações

• Determinismo é apenas na camada de orquestração. O gerenciador registra hashes e reproduz o mesmo plano para os mesmos parâmetros, mas não pode forçar que o plugin seja determinístico. Se o plugin acessa a rede, usa sementes aleatórias ou lê o relógio de parede, as mesmas entradas podem produzir saídas diferentes. Declare esse não-determinismo no próprio plugin.
• Caminhos críticos devem ser declarados antecipadamente. Arquivos não listados em critical_paths nunca são capturados em snapshot e, portanto, não podem ser revertidos.
• Verificação de saída dourada é v0.2. O verificador atual apenas verifica o contrato do plugin (saída 0 + arquivo de resultado presente). A comparação com uma saída esperada conhecida está planejada, mas ainda não implementada.
• Configurações YAML precisam de PyYAML. Configurações JSON funcionam apenas com a biblioteca padrão.