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

• Python 3.10+
• Sem dependências de runtime de terceiros — o arcabouço é construído inteiramente com a biblioteca padrão do Python e executa offline por padrão.
• Opcional, apenas para desenvolvimento: ruff, black, mypy, pytest, pytest-cov (veja CONTRIBUTING.md).
• Opcional, para experimentos com modelos reais: acesso a um endpoint de chat-completions compatível com OpenAI (configurado por meio das variáveis de ambiente AUTOGUARDRAILS_* descritas acima).

Contribuição

Contribuições são bem-vindas! Por favor, leia nossas Diretrizes de Contribuição e o Código de Conduta antes de começar.

• Reporte bugs e solicite recursos por meio das GitHub Issues.
• Contribuidores externos assinam o CLA (gerenciado automaticamente pelo bot CLA Assistant no seu primeiro PR).
• Execute ruff check ., black --check ., mypy autoguardrails e pytest antes de abrir um PR.
• Respeite o contrato de pesquisa: policy.md é a única superfície mutável; eval_suite.jsonl e judge_prompt.md estão congelados.

Segurança

Por favor, reporte vulnerabilidades de segurança de forma responsável. Consulte nossa Política de Segurança para saber como reportar (não abra uma issue pública para vulnerabilidades). Contato: [email protected] ou use o GitHub Security Advisories.

Aviso Legal

Este software é um projeto open source do Santander AI Lab, fornecido "as is" (no estado em que se encontra) sob sua licença, sem garantias ou condições de qualquer tipo. Não é um produto ou serviço oficial do Banco Santander, não possui compromisso de suporte em produção e não constitui aconselhamento financeiro, jurídico ou profissional.

"Santander" e seu logotipo são marcas registradas do Banco Santander, S.A. A licença do projeto não concede nenhum direito de uso além da atribuição factual.

Se você acredita ter encontrado uma vulnerabilidade de segurança, siga nossa política de segurança — não abra uma issue pública. Você é responsável por avaliar a adequação deste software ao seu caso de uso e por manter suas próprias implantações atualizadas.

Licença

Este projeto é licenciado sob a Apache License 2.0 — consulte os arquivos LICENSE e NOTICE para detalhes.

Copyright (c) 2026 Santander Group
SPDX-License-Identifier: Apache-2.0

Citação

Se você usar autoguardrails em sua pesquisa, por favor cite-o:

@software{autoguardrails2026,
  author  = {{Santander AI Lab}},
  title   = {autoguardrails: an autoresearch-style guardrail policy loop},
  year    = {2026},
  url     = {https://github.com/SantanderAI/autoguardrails},
  license = {Apache-2.0}
}