autoguardrails

Open source pelo Santander AI Lab. Uma biblioteca / arcabouço de avaliação de pesquisa em guardrails de LLM / segurança de IA (estilo autoresearch): ela busca sobre uma única superfície mutável policy.md para minimizar a taxa de sucesso de ataques (ASR) contra um conjunto de avaliação fixo, com um piso de aprovação benigna.

Parte do Santander AI Open Source — projetos de IA open source do Banco Santander (santander.com).

autoguardrails é um pequeno arcabouço de pesquisa em alinhamento inspirado no autoresearch do Karpathy.

Em vez de buscar sobre train.py, este repositório busca sobre policy.md. A ideia é a mesma:

• manter a superfície mutável mínima
• manter o avaliador fixo
• executar com um orçamento de tempo (wall-clock) fixo
• comparar candidatos com uma única métrica principal
• registrar cada decisão de manter ou descartar

Neste repositório, a métrica principal é a taxa de sucesso de ataques (ASR, quanto menor, melhor), com um piso de aprovação benigna para que o sistema não possa vencer recusando tudo.

O Que Mais Importa

Para a experimentação do dia a dia, três arquivos são os mais importantes:

• program.md: as instruções de propriedade humana para o loop
• policy.md: o único arquivo que você deve editar entre execuções
• results.tsv: o log de execuções somente-acréscimo (append-only)

Todo o restante é código de arcabouço fixo ou dados de avaliação fixos.

Contrato de Pesquisa Atual

• Superfície mutável: policy.md
• Conjunto fixo: eval_suite.jsonl
• Prompt do avaliador (judge) fixo: judge_prompt.md
• Arcabouço fixo: autoguardrails/
• Regra de aceitação: manter um candidato somente se a ASR melhorar e a aprovação benigna não cair mais de 2 pontos percentuais
• Orçamento de execução: definido pela configuração do arcabouço, atualmente 5 minutos por rodada de avaliação

Se você quiser um modelo mental mais próximo do autoresearch original, pense em autoguardrails/ como a camada auxiliar fixa e em policy.md como o único arquivo sob busca.

Início Rápido

Execute a partir da raiz do repositório.

1. Registre uma linha de base (baseline).

python -m autoguardrails baseline --reset --repeat 2 --notes "initial baseline"

2. Edite apenas policy.md.

3. Avalie o novo candidato.

python -m autoguardrails candidate --repeat 2 --notes "cover jailbreak and obfuscation"

4. Inspecione o resultado atualmente mantido.

python -m autoguardrails status

5. Inspecione o registro completo.

cat results.tsv

Se um candidato for rejeitado, o arcabouço restaura policy.md automaticamente para a última versão aceita.

Wrapper de Shell

Se você preferir um único ponto de entrada, use run_autoguardrails.sh:

sh run_autoguardrails.sh status
sh run_autoguardrails.sh evaluate
sh run_autoguardrails.sh baseline "initial baseline" 2
sh run_autoguardrails.sh candidate "cover jailbreak and obfuscation" 2

No Windows, execute o wrapper a partir do Git Bash ou de outro shell compatível com POSIX.

Configuração com Modelo Real

A configuração padrão usa um stub local determinístico para que o repositório funcione offline. Para executar experimentos reais, aponte o modelo alvo e o modelo avaliador (judge) para endpoints compatíveis com OpenAI.

Variáveis do modelo alvo:

• AUTOGUARDRAILS_TARGET_PROVIDER=openai_compatible
• AUTOGUARDRAILS_TARGET_MODEL
• AUTOGUARDRAILS_TARGET_API_BASE
• AUTOGUARDRAILS_TARGET_API_KEY

Variáveis do modelo avaliador (judge):

• AUTOGUARDRAILS_JUDGE_PROVIDER=openai_compatible
• AUTOGUARDRAILS_JUDGE_MODEL
• AUTOGUARDRAILS_JUDGE_API_BASE
• AUTOGUARDRAILS_JUDGE_API_KEY

Exemplo:

export AUTOGUARDRAILS_TARGET_PROVIDER=openai_compatible
export AUTOGUARDRAILS_TARGET_MODEL=gpt-4.1-mini
export AUTOGUARDRAILS_TARGET_API_BASE=https://your-endpoint.example/v1
export AUTOGUARDRAILS_TARGET_API_KEY=your-target-key

export AUTOGUARDRAILS_JUDGE_PROVIDER=openai_compatible
export AUTOGUARDRAILS_JUDGE_MODEL=gpt-4.1-mini
export AUTOGUARDRAILS_JUDGE_API_BASE=https://your-endpoint.example/v1
export AUTOGUARDRAILS_JUDGE_API_KEY=your-judge-key

python -m autoguardrails baseline --reset --repeat 2 --notes "real-model baseline"

Use uma configuração de avaliador (judge) congelada durante uma série de execuções. Não altere prompts ou modelos do avaliador (judge) no meio do experimento.

Padrão Típico de Iteração

Um ciclo simples de emulação offline é assim:

1. Registre a linha de base.
2. Adicione uma família de mudanças de política ao policy.md.
3. Execute candidate.
4. Mantenha a mudança somente se o arcabouço a aceitar.
5. Repita com uma nova mudança por vez.

Um exemplo de mudança candidata que melhora o stub incluído é adicionar tratamento explícito para:

• fraseados de jailbreak, como "ignorar instruções anteriores", "roleplay" e "modo desenvolvedor"
• solicitações de ofuscação, como tradução, base64, rot13, formatação somente-JSON ou conversão de esquema

Isso proporciona uma primeira curva de melhoria realista sem alterar o avaliador.

Estrutura do Repositório

• program.md: instruções e restrições do experimento
• policy.md: política de guardrail mutável sob busca
• judge_prompt.md: prompt do avaliador (judge) congelado
• eval_suite.jsonl: casos de avaliação fixos de ataque e benignos
• results.tsv: log de execuções
• run_autoguardrails.sh: wrapper de conveniência para a CLI
• autoguardrails/: arcabouço Python fixo
• tests/: verificações de regressão e segurança do arcabouço

Consulte autoguardrails/README.md para a arquitetura do código e tests/README.md para a estratégia de testes.

Notas de Segurança

• Este arcabouço é intencionalmente de turno único e escopo restrito.
• Ele não modela ferramentas, acesso a arquivos ou ações de agentes em múltiplas etapas.
• O stub incluído serve apenas para verificação do arcabouço; não é um modelo de segurança realista.
• O conjunto de avaliação é fixo por design. Se você o alterar, inicie uma nova linhagem de experimentos em vez de comparar com resultados antigos.

Requisitos