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

.. code-block:: json

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

.. list-table::
   :header-rows: 1
   :widths: 20 15 15 50

   * - 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
-----------------

.. code-block:: json

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

.. list-table::
   :header-rows: 1
   :widths: 20 15 15 50

   * - 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
------------------------

.. code-block:: json

   {
     "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
       }
     }
   }

.. list-table::
   :header-rows: 1
   :widths: 25 15 15 45

   * - 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
----------------------

.. code-block:: json

   {
     "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
~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 25 15 15 45

   * - 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
~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 25 15 15 45

   * - 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
----------------

.. code-block:: json

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

.. list-table::
   :header-rows: 1
   :widths: 25 15 20 40

   * - 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:

.. code-block:: bash

   # 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"

.. list-table::
   :header-rows: 1
   :widths: 40 60

   * - 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
------------------------------

.. code-block:: json

   {
     "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
     }
   }