Configuration Reference

Complete reference for all SpecAlign configuration options.

Configuration Files

SpecAlign uses two main configuration files:

• config.json - Main configuration for all components

• providers.json - API provider credentials and settings

Configuration Loading Order

Configuration is loaded in the following order (later overrides earlier):

1. Default values (built-in)

2. config.json file

3. Environment variables (SPECALIGN_ prefix)

4. CLI arguments

Global Configuration

{
  "global": {
    "mode": "api",
    "log_level": "INFO",
    "seed": null,
    "output_dir": "output"
  }
}

Option	Type	Default	Description
mode	string	"api"	Execution mode: "api" or "local"
log_level	string	"INFO"	Logging level: DEBUG, INFO, WARNING, ERROR
seed	int/null	null	Random seed for reproducibility
output_dir	string	"output"	Base directory for output files

API Configuration

{
  "api": {
    "provider": "openai",
    "model": "gpt-4o",
    "embedding_model": "text-embedding-3-small",
    "max_concurrent": 10,
    "timeout": 60,
    "max_retries": 3
  }
}

Option	Type	Default	Description
provider	string	"openai"	Default API provider name
model	string	"gpt-4o"	Default model for generation
embedding_model	string	"text-embedding-3-small"	Model for embeddings
max_concurrent	int	10	Maximum concurrent API requests
timeout	int	60	Request timeout in seconds
max_retries	int	3	Maximum retry attempts

Specification Generation

{
  "specgen": {
    "num_specs": 50,
    "rules_per_spec_min": 3,
    "rules_per_spec_max": 5,
    "ensure_stage_coverage": true,
    "instruction_generation": {
      "topics_per_spec": 3,
      "temperature": 0.7
    }
  }
}

Option	Type	Default	Description
num_specs	int	50	Number of specifications to generate
rules_per_spec_min	int	3	Minimum rules per specification
rules_per_spec_max	int	5	Maximum rules per specification
ensure_stage_coverage	bool	true	Ensure all rule stages are covered
instruction_generation.topics_per_spec	int	3	Topics per specification instruction
instruction_generation.temperature	float	0.7	Temperature for instruction generation

Red Team Configuration

{
  "redteam": {
    "max_rounds_per_seed": 5,
    "enable_role_swap": true,
    "early_stop_on_success": false,
    "context_pool": {
      "max_size": 500,
      "similarity_threshold": 0.85,
      "diversity_weight": 0.3
    },
    "planner": {
      "use_context": true,
      "num_examples": 3,
      "temperature": 0.8
    },
    "judges": {
      "safety": {
        "model": "gpt-4o",
        "temperature": 0.0
      },
      "quality": {
        "model": "gpt-4o-mini",
        "temperature": 0.0
      }
    }
  }
}

Red Team Options

Option	Type	Default	Description
max_rounds_per_seed	int	5	Maximum attack rounds per seed
enable_role_swap	bool	true	Enable attacker/defender role swapping
early_stop_on_success	bool	false	Stop after first successful attack

Context Pool Options

Option	Type	Default	Description
max_size	int	500	Maximum examples in pool
similarity_threshold	float	0.85	Deduplication threshold (0-1)
diversity_weight	float	0.3	Weight for diversity scoring

DPO Construction

{
  "redteam": {
    "dpo_construction": {
      "strategy": "two_step_reframe",
      "min_quality_score": 0.7,
      "temperature": 0.7,
      "max_tokens": 1024
    }
  }
}

Option	Type	Default	Description
strategy	string	"two_step_reframe"	DPO pair construction strategy
min_quality_score	float	0.7	Minimum quality for chosen responses
temperature	float	0.7	Temperature for compliant response generation
max_tokens	int	1024	Maximum tokens for responses

Environment Variables

All configuration options can be overridden via environment variables:

# API credentials
export SPECALIGN_OPENAI_API_KEY="sk-..."
export SPECALIGN_OPENAI_BASE_URL="https://api.openai.com/v1"

# Global settings
export SPECALIGN_LOG_LEVEL="DEBUG"
export SPECALIGN_OUTPUT_DIR="my_output"

# Provider settings
export SPECALIGN_DEFAULT_PROVIDER="openai"

Variable	Description
SPECALIGN_OPENAI_API_KEY	OpenAI API key
SPECALIGN_OPENAI_BASE_URL	OpenAI API base URL
SPECALIGN_DEFAULT_PROVIDER	Default provider name
SPECALIGN_OUTPUT_DIR	Output directory path
SPECALIGN_LOG_LEVEL	Logging level

Complete Example Configuration

{
  "global": {
    "mode": "api",
    "log_level": "INFO",
    "seed": 42,
    "output_dir": "output"
  },
  "api": {
    "provider": "openai",
    "model": "gpt-4o",
    "embedding_model": "text-embedding-3-small",
    "max_concurrent": 10,
    "timeout": 60,
    "max_retries": 3
  },
  "specgen": {
    "num_specs": 50,
    "rules_per_spec_min": 3,
    "rules_per_spec_max": 5,
    "ensure_stage_coverage": true,
    "instruction_generation": {
      "topics_per_spec": 3,
      "temperature": 0.7
    }
  },
  "redteam": {
    "max_rounds_per_seed": 5,
    "enable_role_swap": true,
    "early_stop_on_success": false,
    "context_pool": {
      "max_size": 500,
      "similarity_threshold": 0.85,
      "diversity_weight": 0.3
    },
    "planner": {
      "use_context": true,
      "num_examples": 3,
      "temperature": 0.8
    },
    "judges": {
      "safety": {
        "model": "gpt-4o",
        "temperature": 0.0
      },
      "quality": {
        "model": "gpt-4o-mini",
        "temperature": 0.0
      }
    },
    "dpo_construction": {
      "strategy": "two_step_reframe",
      "min_quality_score": 0.7,
      "temperature": 0.7,
      "max_tokens": 1024
    }
  },
  "output": {
    "base_dir": "output",
    "save_episodes": true,
    "save_context_pool": true,
    "save_token_stats": true
  }
}