# Transfer Learning Base Configuration Feature

## Overview
This feature implements automatic loading of base configurations when "Train on COCO" transfer learning is selected. Base parameters are loaded from `backend/data/` based on the selected YOLOX model, and these protected fields are displayed as greyed out and non-editable in the frontend.

## Components Modified/Created

### Backend

#### 1. Base Configuration Files (`backend/data/`)
- **`yolox_s.py`** - Base config for YOLOX-Small (depth=0.33, width=0.50)
- **`yolox_m.py`** - Base config for YOLOX-Medium (depth=0.67, width=0.75)
- **`yolox_l.py`** - Base config for YOLOX-Large (depth=1.0, width=1.0)
- **`yolox_x.py`** - Base config for YOLOX-XLarge (depth=1.33, width=1.25)

Each file contains a `BaseExp` class with protected parameters:
- Model architecture (depth, width, activation)
- Training hyperparameters (max_epoch, warmup_epochs, scheduler, etc.)
- Optimizer settings (momentum, weight_decay)
- Augmentation probabilities (mosaic_prob, mixup_prob, etc.)
- Input/output sizes

#### 2. Services (`backend/services/generate_yolox_exp.py`)
**New functions:**
- `load_base_config(selected_model)` - Dynamically loads base config using importlib
- Modified `generate_yolox_inference_exp()` to support `use_base_config` parameter
- Base config merging logic: base → user overrides → defaults

**Behavior:**
- `transfer_learning='coco'` → loads base config + applies user overrides
- `transfer_learning='sketch'` → uses only user-defined values
- Protected parameters from base config are preserved unless explicitly overridden

#### 3. API Routes (`backend/routes/api.py`)
**New endpoint:**
```python
@api_bp.route('/base-config/<model_name>', methods=['GET'])
def get_base_config(model_name):
```
Returns the base configuration JSON for a specific YOLOX model.

### Frontend

#### 1. HTML (`edit-training.html`)
**Added:**
- Info banner to indicate when base config is active
- CSS styles for disabled input fields (grey background, not-allowed cursor)
- Visual feedback showing which model's base config is loaded

**Banner HTML:**
```html
<div id="base-config-info" style="display:none; ...">
    🔒 Base Configuration Active
    Protected parameters are loaded from [model] base config
</div>
```

**CSS for disabled fields:**
```css
.setting-row input[type="number"]:disabled,
.setting-row input[type="text"]:disabled,
.setting-row input[type="checkbox"]:disabled {
    background: #d3d3d3 !important;
    color: #666 !important;
    cursor: not-allowed !important;
    border: 1px solid #999 !important;
}
```

#### 2. JavaScript (`js/start-training.js`)
**New functionality:**

1. **Base Config Loading:**
   ```javascript
   function loadBaseConfig(modelName)
   ```
   Fetches base config from `/api/base-config/<model>`

2. **Apply Base Config:**
   ```javascript
   function applyBaseConfig(config, isCocoMode)
   ```
   - Applies config values to form fields
   - Disables and greys out protected fields
   - Shows/hides info banner
   - Adds tooltips to disabled fields

3. **Update Transfer Learning Mode:**
   ```javascript
   function updateTransferLearningMode()
   ```
   - Monitors changes to "Transfer Learning" dropdown
   - Monitors changes to "Select Model" dropdown
   - Loads appropriate base config when COCO mode is selected
   - Clears base config when sketch mode is selected

4. **Form Submission Enhancement:**
   - Temporarily enables disabled fields before submission
   - Ensures protected parameters are included in form data
   - Re-disables fields after collection

**Protected Fields List:**
```javascript
const protectedFields = [
    'depth', 'width', 'act', 'max_epoch', 'warmup_epochs', 'warmup_lr',
    'scheduler', 'no_aug_epochs', 'min_lr_ratio', 'ema', 'weight_decay',
    'momentum', 'input_size', 'mosaic_scale', 'test_size', 'enable_mixup',
    'mosaic_prob', 'mixup_prob', 'hsv_prob', 'flip_prob', 'degrees',
    'translate', 'shear', 'mixup_scale', 'print_interval', 'eval_interval'
];
```

## User Flow

### 1. Normal Custom Training (Train from sketch)
- User selects model: e.g., "YOLOX-s"
- User selects "Train from sketch"
- All fields are editable (white background)
- User can customize all parameters
- Submission uses user-defined values only

### 2. COCO Transfer Learning (Train on COCO)
- User selects model: e.g., "YOLOX-s"
- User selects "Train on coco"
- **Automatic actions:**
  1. Frontend calls `/api/base-config/YOLOX-s`
  2. Base config is loaded and applied
  3. Protected fields become greyed out and disabled
  4. Green info banner appears: "🔒 Base Configuration Active"
  5. Tooltip on hover: "Protected by base config for YOLOX-s. Switch to 'Train from sketch' to customize."
- User can still edit non-protected fields
- On submit: both base config values AND user overrides are sent to backend
- Backend generates exp.py with merged settings

### 3. Switching Models
- User changes from "YOLOX-s" to "YOLOX-l" (while in COCO mode)
- Frontend automatically:
  1. Fetches new base config for YOLOX-l
  2. Updates field values (depth=1.0, width=1.0, etc.)
  3. Updates banner text to show "YOLOX-l"
- Protected parameters update to match new model's architecture

## Testing

### Manual Test Steps:

1. **Test Base Config Loading:**
   ```bash
   cd backend/data
   python test_base_configs.py
   ```
   Should display all parameters for yolox-s, yolox-m, yolox-l, yolox-x

2. **Test API Endpoint:**
   ```bash
   # Start Flask server
   cd backend
   python app.py
   
   # In another terminal:
   curl http://localhost:3000/api/base-config/YOLOX-s
   ```
   Should return JSON with depth, width, activation, etc.

3. **Test Frontend:**
   - Open `edit-training.html?id=<project_id>` in browser
   - Select "YOLOX-s" model
   - Select "Train on coco" → fields should grey out
   - Select "Train from sketch" → fields should become editable
   - Switch to "YOLOX-l" (in COCO mode) → values should update
   - Open browser console and check for: `Applied base config. Protected fields: depth, width, ...`

4. **Test Form Submission:**
   - With COCO mode active (fields greyed out)
   - Click "Save Parameters"
   - Check browser Network tab → POST to `/api/yolox-settings`
   - Verify payload includes protected parameters (depth, width, etc.)
   - Check Flask logs for successful save

### Expected Behaviors:

✅ **COCO mode + YOLOX-s:**
- depth: 0.33 (greyed out)
- width: 0.50 (greyed out)
- activation: silu (greyed out)
- Info banner visible

✅ **COCO mode + YOLOX-l:**
- depth: 1.0 (greyed out)
- width: 1.0 (greyed out)
- activation: silu (greyed out)

✅ **Sketch mode:**
- All fields white/editable
- No info banner
- User can set any values

## Documentation

- **`backend/data/README.md`** - Complete guide on base config system
- **`backend/data/test_base_configs.py`** - Test script for base configs

## Benefits

1. **Proven defaults:** Users start with battle-tested COCO pretraining settings
2. **Prevents mistakes:** Can't accidentally break model architecture by changing depth/width
3. **Easy customization:** Can still override specific parameters if needed
4. **Visual feedback:** Clear indication of which fields are protected
5. **Model-specific:** Each model (s/m/l/x) has appropriate architecture defaults
6. **Flexible:** Can easily add new models by creating new base config files

## Future Enhancements

- Add "Override" button next to protected fields to unlock individual parameters
- Show diff comparison between base config and user overrides
- Add validation warnings if user tries values far from base config ranges
- Export final merged config as preview before training