# SessionValidator - Quick Reference

## One-Liner Validation

```python
validate_session_production(bpm=95, key="Am", num_scenes=13)
```

## Validation Categories

| Category | Checks | Tolerance | Score Formula |
|----------|--------|-----------|---------------|
| **BPM Coherence** | Sample BPM vs project tempo | ±5 BPM | valid/total |
| **Key Harmony** | MIDI notes vs key scale | Exact match | valid/total |
| **Sample Rotation** | Consecutive scene repetition | No repeats | valid/total |
| **Energy Matching** | Sample RMS vs scene energy | Range-based | valid/total |

## Energy Levels by Scene Type

| Scene Type | Energy Level | RMS Range |
|------------|--------------|-----------|
| Intro | Soft | 0.0 - 0.3 |
| Verse | Medium | 0.3 - 0.7 |
| Pre-Chorus | Medium | 0.3 - 0.7 |
| Chorus | Hard | 0.7 - 1.0 |
| Bridge | Medium | 0.3 - 0.7 |
| Outro | Soft | 0.0 - 0.3 |

## Pass/Fail Threshold

- **≥ 0.85**: PASSED (professional grade)
- **< 0.85**: FAILED (needs improvement)

## Common Commands

### Validate After Production
```python
build_session_production(genre="reggaeton", tempo=95, key="Am", num_scenes=13)
validate_session_production(bpm=95, key="Am", num_scenes=13)
```

### Validate Before Export
```python
results = validate_session_production(95, "Am", 13)
if results['passed']:
    render_full_mix("final.wav")
```

### Get Detailed Report
```python
validator = SessionValidator(song, metadata_store)
results = validator.validate_production(95, "Am", 13)
print(validator.get_detailed_report(results))
```

## Interpreting Results

### Excellent (0.90-1.00)
✓ Professional grade, ready for release

### Good (0.85-0.89)
✓ Meets standards, minor issues acceptable

### Fair (0.75-0.84)
⚠ Needs improvement before release

### Poor (<0.75)
✗ Significant issues, requires fixing

## Quick Fixes

### Low BPM Score
- Warp clips to project tempo
- Select BPM-coherent samples
- Use `select_bpm_coherent_pool(target_bpm=95)`

### Low Key Score
- Transpose out-of-key notes
- Use scale-constrained MIDI
- Enable key filtering

### Low Rotation Score
- Use different samples in consecutive scenes
- Implement A-B-A pattern (not A-A)
- Use sample rotation system

### Low Energy Score
- Select samples with appropriate dynamics
- Use gain staging
- Apply compression/limiting

## MCP Tool Syntax

```python
validate_session_production(
    bpm=95,        # Project tempo
    key="Am",      # Musical key
    num_scenes=13  # Number of scenes
)
```

## Python API

```python
from AbletonMCP_AI.mcp_server.engines import (
    SessionValidator,
    validate_session_production,
    init_metadata_store
)

# Initialize
song = get_song()
ms = init_metadata_store()
validator = SessionValidator(song, ms)

# Validate
results = validator.validate_production(95, "Am", 13)

# Check
if results['passed']:
    print("✓ PASSED")
else:
    print("✗ FAILED")
    print(f"Score: {results['overall_score']:.2f}")
```

## Supported Keys

**Minor:** Am, Cm, Dm, Gm, Em, Fm, Bm  
**Major:** C, D, G, E, F, A

## Files

- **Implementation:** `mcp_server/engines/session_validator.py`
- **Documentation:** `docs/session_validator.md`
- **Sprint Doc:** `docs/sprint_session_validator.md`

## Related Tools

- `build_session_production` - Create Session View productions
- `analyze_library` - Analyze samples for metadata
- `select_coherent_kit` - Select compatible samples
- `full_quality_check` - Comprehensive QA
