Configuration

SafeLens pipelines are configured with YAML. A minimal config has four sections:

model:
  source: dummy
  name: dummy
  dtype: float32

pipeline:
  risk_threshold: 0.5
  probes:
    - name: dummy_probe
      config:
        layers: [0]
  monitors: []
  attributors: []

dataset:
  - id: sample-1
    text: "Explain safety monitoring."

output:
  report_path: "./safety_scan.json"

Validate a config without loading a real model:

safelens validate --config examples/config.yaml

Generate the JSON Schema used by editors and CI:

safelens schema --output schemas/pipeline-config.schema.json

Inspect model adapter support and cache behavior without downloading weights:

safelens models list-supported
safelens inspect-model --model Qwen/Qwen3-8B

Model Sources

model.source controls how the model is loaded.

Dummy

Use dummy for tests, CI, and architecture demos:

model:
  source: dummy
  name: dummy

This path does not download any model.

HuggingFace

Use huggingface to load directly through Transformers:

model:
  source: huggingface
  name: Qwen/Qwen2.5-0.5B-Instruct
  dtype: float16
  device: cpu
  trust_remote_code: true
  cache_dir: ./.cache/huggingface

Install dependencies with:

python -m pip install -e ".[models]"

If cache_dir is omitted, SafeLens resolves a default provider cache under .cache/safelens/models/huggingface.

Qwen3 Dense

Use qwen3_dense for Qwen3 dense decoder-only models up to 35B parameters:

model:
  source: qwen3_dense
  name: Qwen/Qwen3-8B
  dtype: bfloat16
  device: cuda
  trust_remote_code: true

The wrapper exposes component hooks for resid_pre, resid_mid, resid_post, attn_out, mlp_out, q, k, v, and z, plus attention pattern caching through run_with_cache. Supported dense sizes by name are 0.6B, 1.7B, 4B, 8B, 14B, and 32B; MoE variants such as Qwen3-30B-A3B are rejected.

Install dependencies with:

python -m pip install -e ".[models]"

TransformerLens

Use transformer_lens when you want SafeLens to target model families mirrored from TransformerLens' public support table while keeping runtime loading inside SafeLens. This adapter uses Transformers auto classes and does not install, import, or delegate to transformer-lens:

model:
  source: transformer_lens
  name: gpt2
  dtype: float32
  device: cpu

Install dependencies with:

python -m pip install -e ".[models]"

Useful inspection commands:

safelens models list-transformerlens
safelens inspect-model --model gpt2 --json

If cache_dir is omitted, SafeLens resolves a default provider cache under .cache/safelens/models/transformer_lens_compatible. Attention pattern and raw score hooks use eager softmax instrumentation; flash or SDPA attention paths may need an eager attention implementation. Other component hooks are resolved through SafeLens architecture adapters for GPT-2, GPT-J, GPT-Neo, GPT-NeoX/Pythia, BLOOM/Falcon, MPT, Phi, OPT, BERT/RoBERTa, DistilBERT, T5, Wav2Vec2/Hubert, and LLaMA-like decoder families.

safelens models list-architectures

ModelScope

Use modelscope to download with ModelScope first, then load the local snapshot with Transformers:

model:
  source: modelscope
  name: Qwen/Qwen2.5-0.5B-Instruct
  dtype: float16
  device: cpu
  trust_remote_code: true
  cache_dir: ./.cache/modelscope
  local_dir: ./models/qwen2.5-0.5b

Install dependencies with:

python -m pip install -e ".[modelscope]"

Additional ModelScope arguments can be passed through modelscope_kwargs:

model:
  source: modelscope
  name: Qwen/Qwen2.5-0.5B-Instruct
  modelscope_kwargs:
    allow_file_pattern: "*.json"

If cache_dir is omitted, SafeLens resolves a default provider cache under .cache/safelens/models/modelscope.

Local

Use local for a local Transformers-compatible model directory:

model:
  source: local
  name: ./models/local-causal-lm
  local_dir: ./models/local-causal-lm
  dtype: float16
  device: cpu

Keep model directories outside git. The default .gitignore excludes models/ and common weight files.

Method Lists

Each method is loaded from a registry by name:

pipeline:
  probes:
    - name: dummy_probe
      config:
        layers: [0]
        risk_terms: ["jailbreak", "attack"]
  monitors:
    - name: dummy_monitor
      config:
        threshold: 0.5
  attributors:
    - name: dummy_attributor
      config:
        risk_terms: ["jailbreak", "attack"]

Example Configs

File	Purpose
examples/config.yaml	Dependency-free dummy pipeline for CI and demos.
examples/huggingface_config.yaml	Direct Transformers/HuggingFace loading.
examples/modelscope_config.yaml	ModelScope snapshot download plus Transformers loading.
examples/qwen3_dense_config.yaml	Qwen3 Dense component hook examples.
examples/local_model_config.yaml	Local model directory loading.