# Same-Pack Strict Selection Implementation

## Overview

This implementation enforces strict same-pack selection for `atmos_fx` and `vocal_shot` roles to ensure these samples are well-integrated into the same sonic universe as the main musical elements (drums, bass, music).

## Problem Statement

Previously, these roles could be selected from different packs than the main elements, leading to:
- Poor sonic coherence within tracks
- Jarring transitions between sound sources
- A lack of unified "pack character" in productions

## Solution

### 1. Strict Same-Pack Bonus System

Added `_calculate_same_pack_strict_bonus()` method in `sample_selector.py` that applies different score multipliers based on folder relationships:

| Relationship | Multiplier | Type | Description |
|--------------|------------|------|-------------|
| Exact folder match | 2.0x | same_pack | Sample in same folder as main pack |
| Subfolder of main pack | 1.8x | same_pack | Sample in subfolder of main pack folder |
| Sibling folder | 1.5x | same_parent | Sample in sibling folder (same parent) |
| Same pack root | 1.3x | same_parent | Different structure but same pack name |
| Different pack | 0.4x | fallback | Completely different pack lineage |

### 2. Integration with Sample Scoring

Modified `_calculate_sample_score()` to:
- Detect when selecting for `atmos_fx` or `vocal_shot` roles
- Build list of main pack folders from palette data (drums, bass, music anchors)
- Apply strict bonus/penalty with high weight (0.25)
- Log selection type with clear markers

### 3. Fallback Mechanism

When same-pack samples aren't available:
- Heavy penalty (0.4x) is applied but selection can still proceed
- Logs clearly mark "FALLBACK" selections
- System continues to function even with limited library diversity

### 4. Logging

Three log levels for monitoring:
- `INFO` - "SAME_PACK": Selected from main pack (bonus applied)
- `INFO` - "SAME_PARENT": Selected from related folder (moderate bonus)
- `WARNING` - "FALLBACK": Cross-pack selection (penalty applied)

## Files Modified

1. **`AbletonMCP_AI/AbletonMCP_AI/MCP_Server/sample_selector.py`**
   - Added `_calculate_same_pack_strict_bonus()` method
   - Modified `_calculate_sample_score()` to apply strict same-pack logic
   - Uses existing palette data from `_palette_data` attribute

## How Same-Pack Selection Works

1. **Pack Context Establishment**: 
   - `PackBrain` in `pack_brain.py` establishes the current pack context
   - Main pack folders (drums, bass, music) are identified and stored in palette
   - Palette data is passed to `SampleSelector` via `set_palette_data()`

2. **Sample Evaluation**:
   - When scoring samples for `atmos_fx` or `vocal_shot` roles
   - System checks folder relationships against main pack folders
   - Applies appropriate bonuses or penalties

3. **Selection**:
   - Weighted random selection still applies
   - Same-pack samples have significantly higher probability
   - Cross-pack selections are penalized but possible if no alternatives exist

## Validation Steps

### 1. Compile Check
```powershell
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\sample_selector.py"
```

### 2. Unit Test
```powershell
python "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\test_same_pack_selection.py"
```

Expected output:
```
[PASS] Test 1: Exact folder match gives bonus 2.0x
[PASS] Test 2: Subfolder match gives bonus 1.8x
[PASS] Test 3: Sibling folder gives bonus 1.5x
[PASS] Test 4: Different pack gets penalty 0.4x
[PASS] Test 5: Multiple main pack references work correctly

[OK] All same-pack bonus tests passed!
[SUCCESS] Same-pack strict selection feature is working correctly!
```

### 3. Real Generation Test

1. Generate a track with the system
2. Check logs for same-pack selection markers
3. Inspect the generation manifest for sample paths:
   - `atmos_fx` and `vocal_shot` should come from folders related to main pack
   - Look for log entries starting with "SAME_PACK", "SAME_PARENT", or "FALLBACK"

### 4. Log Inspection

During generation, look for:
```
SAME_PACK [ATMOS_FX]: Selected from main pack - sample.wav (score: 2.0)
SAME_PARENT [VOCAL_SHOT]: Selected from related folder - vocal.wav (score: 1.5, sibling folder to main pack)
FALLBACK [ATMOS_FX]: Cross-pack selection - atmos.wav (penalty: 0.4, different pack lineage)
```

## Configuration

No manual configuration required. The feature automatically:
- Activates for `atmos_fx` and `vocal_shot` roles only
- Uses existing palette data from PackBrain
- Logs all selections for monitoring

## Backward Compatibility

- Fully backward compatible
- Existing tracks without these roles are unaffected
- No changes to other roles or selection logic
- Palette system remains unchanged

## Benefits

1. **Coherence**: Samples from same pack share sonic characteristics
2. **Predictability**: Consistent behavior across generations
3. **Fallback Safety**: System continues to work even with limited libraries
4. **Transparency**: Clear logging shows which samples were selected from where

## Future Enhancements

Potential improvements:
- Add user-configurable strictness level
- Expand to additional roles (e.g., `fx`, `perc_loop`)
- Add same-pack tracking to diversity memory to avoid repetition within pack