Configuration Guide
====================

Configuration Overview
----------------------

Agent-Tunix uses YAML-based configuration organized in the ``conf/`` directory. All settings can be overridden from the command line without code changes.

Configuration Structure
-----------------------

The configuration is organized into groups::

    conf/
    ├── config.yaml              # Main config with defaults list
    ├── model/                   # Model architectures
    ├── optimizer/               # Optimizer settings
    ├── scheduler/               # Learning rate schedulers
    ├── grpo/                    # GRPO algorithm parameters
    ├── generation/              # Text generation settings
    ├── training/                # Training hyperparameters
    ├── evaluation/              # Evaluation settings
    └── experiment/              # Experiment presets

Main Configuration
------------------

The ``conf/config.yaml`` file specifies which configs to load::

    defaults:
      - model: gemma3_270m
      - optimizer: adamw
      - scheduler: warmup_cosine
      - grpo: default
      - generation: default
      - training: default
      - _self_

The ``_self_`` entry controls merge order (configs loaded after override earlier ones).

Configuration Groups
--------------------

**Model Configuration**

Located in ``conf/model/``. Available models:

- ``gemma3_270m.yaml`` - 270M parameter model
- ``gemma3_1b.yaml`` - 1B parameter model

Override::

    python run_training.py model=gemma3_1b

**Optimizer Configuration**

Located in ``conf/optimizer/``. Current options:

- ``adamw.yaml`` - AdamW with warmup cosine decay

Key parameters::

    learning_rate: 3e-6
    warmup_ratio: 0.1
    max_grad_norm: 0.1

Override::

    python run_training.py optimizer.learning_rate=1e-5

**GRPO Configuration**

Located in ``conf/grpo/``. Algorithm parameters::

    num_generations: 4      # Responses per prompt
    num_iterations: 1       # Iterations per batch
    beta: 0.08              # KL divergence penalty
    epsilon: 0.2            # PPO clipping

**Training Configuration**

Located in ``conf/training/``. Key settings::

    micro_batch_size: 4
    num_batches: 3738
    num_epochs: 1
    checkpoint_dir: ./checkpoints/ckpts/

**Generation Configuration**

Located in ``conf/generation/``. Text generation settings::

    max_prompt_length: 256
    max_generation_steps: 512
    temperature: 0.9
    top_p: 1.0
    top_k: 50

Command-Line Overrides
----------------------

Use dot notation to override nested values::

    # Single override
    python run_training.py optimizer.learning_rate=5e-6

    # Multiple overrides
    python run_training.py model=gemma3_1b optimizer.learning_rate=1e-5 training.num_batches=50

    # Add new value (+ prefix)
    python run_training.py +optimizer.schedule_type=linear

    # Force override (++ prefix)
    python run_training.py ++optimizer.warmup_steps=100

    # Delete value (~ prefix)
    python run_training.py ~training.gradient_clip

    # List values
    python run_training.py 'generation.eos_tokens=[1,106,107]'

    # Dictionary values
    python run_training.py '+model.custom_params={hidden_size:512,num_layers:8}'

Experiment Presets
------------------

Experiment files in ``conf/experiment/`` combine multiple settings::

    # Quick testing (10 steps, reduced config)
    python run_training.py +experiment=quick_test

    # Full production training
    python run_training.py +experiment=full_training

Create custom experiments by adding YAML files to ``conf/experiment/``.

Configuration Inspection
------------------------

View resolved configuration::

    # Show resolved configuration
    python run_training.py --cfg job

    # Show with interpolations resolved
    python run_training.py --cfg job --resolve

    # Show defaults composition tree
    python run_training.py --info defaults-tree

    # List all available configuration groups
    python run_training.py --info config-groups

    # Dry run (test config without training)
    python run_training.py --dry-run

Advanced: Creating Custom Configurations
-----------------------------------------

Create a new model configuration in ``conf/model/custom.yaml``::

    model_family: gemma3
    model_size: 4b
    lora_rank: 16
    lora_alpha: 16.0
    lora_module_path: ".*q_einsum|.*kv_einsum|.*gate_proj|.*down_proj|.*up_proj|.*attn_vec_einsum"
    mesh_shape: [[1, 4], ["fsdp", "tp"]]

Use it::

    python run_training.py model=custom

Create an experiment preset in ``conf/experiment/ablation.yaml``::

    # @package _global_

    defaults:
      - override /model: gemma3_1b
      - override /optimizer: adamw

    training:
      num_batches: 100
      micro_batch_size: 2

    optimizer:
      learning_rate: 1e-5

    experiment_name: ablation_study
    tags: [ablation, learning_rate]

Use it::

    python run_training.py +experiment=ablation

Configuration Best Practices
-----------------------------

1. **Check before running**: Always view config with ``--cfg job``
2. **Use experiments**: Create presets for common configurations
3. **Semantic naming**: Use descriptive names for custom configs
4. **Document changes**: Add comments in custom YAML files
5. **Version control**: Keep ``conf/`` in version control
6. **Avoid magic numbers**: Use configuration groups instead

Memory Requirements by Model
-----------------------------

Configuration recommendations for different GPUs:

**RTX 2080 Ti (11GB)**

- Model: gemma3_270m
- Batch size: 1
- LoRA rank: 8-16

::

    python run_training.py model=gemma3_270m training.micro_batch_size=1

**RTX A6000 (48GB)**

- Model: gemma3_1b
- Batch size: 4
- LoRA rank: 32

::

    python run_training.py model=gemma3_1b training.micro_batch_size=4

**Multiple GPUs**

Modify ``mesh_shape`` in model config::

    python run_training.py model.mesh_shape=[[1,4],["fsdp","tp"]]

Next Steps
----------

- :doc:`Training Guide </guide/training>`
- :doc:`Hyperparameter Tuning </guide/hyperparameter_tuning>`
- :doc:`API Reference </api/train>`