autoguardrails

Open source di Santander AI Lab. Una libreria di ricerca / harness di valutazione per i guardrail LLM / AI-safety (in stile autoresearch): cerca su un'unica superficie mutabile policy.md per minimizzare il tasso di successo degli attacchi (ASR) rispetto a una suite di valutazione fissa, con una soglia minima di superamento dei casi benigni.

Parte di Santander AI Open Source — progetti AI open source di Banco Santander (santander.com).

autoguardrails è un piccolo scaffold di ricerca sull'allineamento ispirato ad autoresearch di Karpathy.

Invece di cercare su train.py, questo repo cerca su policy.md. L'idea è la stessa:

• mantenere la superficie mutabile minima
• mantenere fisso il valutatore
• eseguire entro un budget wall-clock fisso
• confrontare i candidati con un'unica metrica principale
• registrare ogni decisione di mantenimento o scarto

In questo repo, la metrica principale è il tasso di successo degli attacchi (ASR, più basso è meglio), con una soglia minima di superamento dei casi benigni, così il sistema non può vincere rifiutando tutto.

Ciò che conta di più

Per la sperimentazione quotidiana, tre file contano più di tutti:

• program.md: le istruzioni del ciclo di proprietà umana
• policy.md: l'unico file che dovresti modificare tra un'esecuzione e l'altra
• results.tsv: il registro delle esecuzioni in sola append

Tutto il resto è codice fisso dell'harness o dati di valutazione fissi.

Contratto di ricerca attuale

• Superficie mutabile: policy.md
• Suite fissa: eval_suite.jsonl
• Prompt del giudice fisso: judge_prompt.md
• Harness fissa: autoguardrails/
• Regola di accettazione: mantieni un candidato solo se l'ASR migliora e il superamento benigno non scende di più di 2 punti percentuali
• Budget di runtime: fissato dalla configurazione dell'harness, attualmente 5 minuti per passaggio di valutazione

Se vuoi un modello mentale più vicino all'autoresearch originale, pensa a autoguardrails/ come al layer di supporto fisso e a policy.md come all'unico file sotto ricerca.

Avvio rapido

Esegui dalla radice del repository.

1. Registra una baseline.

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

2. Modifica solo policy.md.

3. Valuta il nuovo candidato.

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

4. Ispeziona il risultato attualmente mantenuto.

python -m autoguardrails status

5. Ispeziona il registro completo.

cat results.tsv

Se un candidato viene rifiutato, l'harness ripristina automaticamente policy.md all'ultima versione accettata.

Wrapper di shell

Se preferisci un unico punto di ingresso, usa 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

Su Windows, esegui il wrapper da Git Bash o da un'altra shell compatibile con POSIX.

Configurazione per modelli reali

La configurazione predefinita usa uno stub locale deterministico così il repo funziona offline. Per eseguire esperimenti reali, punta il modello target e il modello giudice verso endpoint compatibili con OpenAI.

Variabili del modello target:

• AUTOGUARDRAILS_TARGET_PROVIDER=openai_compatible
• AUTOGUARDRAILS_TARGET_MODEL
• AUTOGUARDRAILS_TARGET_API_BASE
• AUTOGUARDRAILS_TARGET_API_KEY

Variabili del modello giudice:

• AUTOGUARDRAILS_JUDGE_PROVIDER=openai_compatible
• AUTOGUARDRAILS_JUDGE_MODEL
• AUTOGUARDRAILS_JUDGE_API_BASE
• AUTOGUARDRAILS_JUDGE_API_KEY

Esempio:

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"

Usa una configurazione del giudice congelata durante una serie di esecuzioni. Non cambiare i prompt del giudice o i modelli giudice a metà esperimento.

Schema di iterazione tipico

Un semplice ciclo di emulazione offline si presenta così:

1. Registra la baseline.
2. Aggiungi una famiglia di modifiche alla policy in policy.md.
3. Esegui candidate.
4. Mantieni la modifica solo se l'harness la accetta.
5. Ripeti con una nuova modifica alla volta.

Un esempio di modifica candidata che migliora lo stub incluso è aggiungere una gestione esplicita per:

• frasi da jailbreak come "ignora le istruzioni precedenti", "roleplay" e "developer mode"
• richieste di offuscamento come traduzione, base64, rot13, formattazione solo JSON o conversione di schema

Questo ti dà una prima curva di miglioramento realistica senza modificare il valutatore.

Struttura del repository

• program.md: istruzioni e vincoli dell'esperimento
• policy.md: policy dei guardrail mutabile sotto ricerca
• judge_prompt.md: prompt del giudice congelato
• eval_suite.jsonl: casi di valutazione fissi, di attacco e benigni
• results.tsv: registro delle esecuzioni
• run_autoguardrails.sh: wrapper di comodo attorno alla CLI
• autoguardrails/: harness Python fissa
• tests/: controlli di regressione e sicurezza per l'harness

Vedi autoguardrails/README.md per l'architettura del codice e tests/README.md per la strategia di test.

Note di sicurezza

• Questo scaffold è intenzionalmente a turno singolo e di portata limitata.
• Non modella strumenti, accesso ai file o azioni multi-step degli agenti.
• Lo stub incluso serve solo per la verifica dell'harness; non è un modello di sicurezza realistico.
• La suite di valutazione è fissa per progettazione. Se la modifichi, avvia una nuova linea di esperimenti invece di confrontare con i vecchi risultati.

Requisiti

• Python 3.10+
• Nessuna dipendenza runtime di terze parti — l'harness è costruita interamente sulla libreria standard di Python e funziona offline per impostazione predefinita.
• Opzionale, solo per lo sviluppo: ruff, black, mypy, pytest, pytest-cov (vedi CONTRIBUTING.md).
• Opzionale, per esperimenti con modelli reali: accesso a un endpoint chat-completions compatibile con OpenAI (configurato tramite le variabili d'ambiente AUTOGUARDRAILS_* descritte sopra).

Contributi

I contributi sono benvenuti! Ti preghiamo di leggere le nostre Linee guida per i contributi e il Codice di condotta prima di iniziare.

• Segnala bug e richiedi funzionalità tramite GitHub Issues.
• I contributori esterni firmano la CLA (gestita automaticamente dal bot CLA Assistant alla tua prima PR).
• Esegui ruff check ., black --check ., mypy autoguardrails e pytest prima di aprire una PR.
• Rispetta il contratto di ricerca: policy.md è l'unica superficie mutabile; eval_suite.jsonl e judge_prompt.md sono congelati.

Sicurezza

Segnala le vulnerabilità di sicurezza in modo responsabile. Vedi la nostra Security Policy per sapere come segnalarle (non aprire un issue pubblico per le vulnerabilità). Contatto: [email protected] oppure usa GitHub Security Advisories.

Disclaimer

Questo software è un progetto open source del Santander AI Lab, fornito "così com'è" sotto la sua licenza, senza garanzie o condizioni di alcun tipo. Non è un prodotto o servizio ufficiale di Banco Santander, non comporta alcun impegno di supporto in produzione e non costituisce consulenza finanziaria, legale o professionale.

"Santander" e il suo logo sono marchi registrati di Banco Santander, S.A. La licenza del progetto non concede alcun diritto di usarli oltre l'attribuzione fattuale.

Se ritieni di aver trovato una vulnerabilità di sicurezza, segui la nostra security policy — non aprire un issue pubblico. Sei responsabile di valutare l'idoneità di questo software per il tuo caso d'uso e di mantenere aggiornati i tuoi deployment.

Licenza

Questo progetto è rilasciato sotto la Apache License 2.0 — vedi i file LICENSE e NOTICE per i dettagli.

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

Citazione

Se usi autoguardrails nella tua ricerca, ti preghiamo di citarlo:

@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}
}