# Seed Testing and BASE_STRATEGY Management Guide

This guide covers the new seed testing and BASE_STRATEGY management features for the HARVEST trading bot.

## Overview

Two new capabilities have been added:

1. **Seed Testing**: Test whitelisted seeds to validate performance
2. **BASE_STRATEGY Overwrite**: Replace default BASE_STRATEGY with proven seeds

## Commands

### 1. Test All Whitelisted Seeds

Test ALL whitelisted seeds for a specific timeframe to find the best performer.

```bash
# Generate test list
python ml/seed_tester.py test-all 15m

# Execute tests
python backtest_90_complete.py --test-seeds-file ml/test_whitelist_15m.json
```

**What it does:**
- Loads all whitelisted seeds for the timeframe
- Creates a test configuration file
- Backtests each seed against 90 days of data
- Ranks results by win rate
- Saves results with timestamps

### 2. Quick Test (Top 10)

Test only the top 10 seeds by recorded win rate for rapid validation.

```bash
# Generate test list
python ml/seed_tester.py test-top10 1h

# Execute tests
python backtest_90_complete.py --test-seeds-file ml/test_top10_1h.json
```

**What it does:**
- Selects top 10 seeds by historical win rate
- Runs abbreviated backtest
- Identifies best performer quickly

### 3. Overwrite BASE_STRATEGY

Replace BASE_STRATEGY configuration with a proven seed's parameters.

```bash
# Overwrite with best seed (auto-select)
python ml/seed_tester.py overwrite 15m --use-best

# Overwrite with specific seed
python ml/seed_tester.py overwrite 1h --seed 60507652
```

**What it does:**
- Backs up original BASE_STRATEGY (if not already backed up)
- Extracts parameters from selected seed
- Updates BASE_STRATEGY configuration
- Saves override to `ml/base_strategy_overrides.json`
- Requires 'yes' confirmation before applying

**Example:**
```
================================================================================
OVERWRITE BASE_STRATEGY - 15m
================================================================================

🔍 Finding best seed...
✅ Best seed: 15542880 (76.3% WR)

📋 Current BASE_STRATEGY for 15m:
   min_confidence: 0.75
   min_trend: 0.60
   min_adx: 25
   ...

📋 New configuration from Seed 15542880:
   min_confidence: 0.78
   min_trend: 0.65
   min_adx: 28
   ...

⚠️  This will OVERWRITE BASE_STRATEGY['15m']
   Original is backed up in ml/base_strategy_backup.json

   Continue? (yes/no): yes

✅ BASE_STRATEGY['15m'] updated to Seed 15542880
   Backup saved to ml/base_strategy_backup.json
💾 Override saved to ml/base_strategy_overrides.json
```

### 4. Reset BASE_STRATEGY

Restore original BASE_STRATEGY configuration.

```bash
# Reset all timeframes
python ml/seed_tester.py reset

# Reset specific timeframe
python ml/seed_tester.py reset --timeframe 15m
```

**What it does:**
- Loads original backup
- Restores BASE_STRATEGY to defaults
- Clears override file

### 5. Check Status

View current BASE_STRATEGY status and overrides.

```bash
python ml/seed_tester.py status
```

**Example output:**
```
================================================================================
BASE_STRATEGY STATUS
================================================================================

📊 15m:
   Status: ⚠️  OVERRIDDEN
   Seed: 15542880
   Updated: 2024-12-17T10:30:00
   Current config:
      min_confidence: 0.78
      min_trend: 0.65
      min_adx: 28

📊 1h:
   Status: ✅ Original BASE_STRATEGY
   Current config:
      min_confidence: 0.75
      min_trend: 0.60
      min_adx: 25

📊 4h:
   Status: ✅ Original BASE_STRATEGY
   Current config:
      min_confidence: 0.63
      min_trend: 0.55
      min_adx: 22
```

## Dashboard Integration

All commands are accessible from the dashboard's Backtest Control panel (press `B`).

### Keyboard Commands

When no backtest is running:
- `T` - Test all whitelisted seeds for a timeframe
- `Q` - Quick test (top 10 seeds)
- `O` - Overwrite BASE_STRATEGY with best seed
- `R` - Reset BASE_STRATEGY to original
- `H` - View backtest history

## Files Created

### Test Configuration Files

Generated by `seed_tester.py`:

- `ml/test_whitelist_15m.json` - All whitelisted seeds for 15m
- `ml/test_whitelist_1h.json` - All whitelisted seeds for 1h
- `ml/test_whitelist_4h.json` - All whitelisted seeds for 4h
- `ml/test_top10_15m.json` - Top 10 seeds for 15m
- `ml/test_top10_1h.json` - Top 10 seeds for 1h
- `ml/test_top10_4h.json` - Top 10 seeds for 4h

**Format:**
```json
{
  "timeframe": "15m",
  "test_type": "all_whitelisted",
  "created_at": "2024-12-17T10:00:00",
  "seeds": [
    {
      "seed": 15542880,
      "input_seed": 42,
      "expected_wr": 0.763
    }
  ]
}
```

### Result Files

Generated by `backtest_90_complete.py`:

- `ml/batch_test_results_15m_<timestamp>.json`
- `ml/batch_test_results_1h_<timestamp>.json`
- `ml/batch_test_results_4h_<timestamp>.json`

**Format:**
```json
{
  "timeframe": "15m",
  "test_type": "all_whitelisted",
  "tested_at": "2024-12-17T10:30:00",
  "results": [
    {
      "seed": 15542880,
      "input_seed": 42,
      "expected_wr": 0.763,
      "actual_wr": 0.758,
      "trades": 45,
      "pnl": 12.50,
      "final_balance": 22.50
    }
  ]
}
```

### Configuration Files

- `ml/base_strategy_backup.json` - Original BASE_STRATEGY (auto-created)
- `ml/base_strategy_overrides.json` - Current overrides per timeframe

## Workflow Examples

### Example 1: Find and Deploy Best Seed for 15m

```bash
# Step 1: Test all whitelisted seeds
python ml/seed_tester.py test-all 15m
python backtest_90_complete.py --test-seeds-file ml/test_whitelist_15m.json

# Step 2: Review results (automatically printed)
# Top seed identified: 15542880 with 76.3% WR

# Step 3: Overwrite BASE_STRATEGY with best seed
python ml/seed_tester.py overwrite 15m --use-best

# Step 4: Verify
python ml/seed_tester.py status
```

### Example 2: Quick Validation of Top Performers

```bash
# Test top 10 seeds across all timeframes
python ml/seed_tester.py test-top10 15m
python backtest_90_complete.py --test-seeds-file ml/test_top10_15m.json

python ml/seed_tester.py test-top10 1h
python backtest_90_complete.py --test-seeds-file ml/test_top10_1h.json

python ml/seed_tester.py test-top10 4h
python backtest_90_complete.py --test-seeds-file ml/test_top10_4h.json
```

### Example 3: Rollback After Testing

```bash
# Test a specific seed
python backtest_90_complete.py --seed 15542880

# If results look good, overwrite
python ml/seed_tester.py overwrite 15m --seed 15542880

# If results are bad, reset
python ml/seed_tester.py reset --timeframe 15m
```

## Best Practices

### 1. Always Backup

The system automatically backs up BASE_STRATEGY on first use, but you can manually verify:

```bash
# Check if backup exists
ls -l ml/base_strategy_backup.json
```

### 2. Test Before Overwrite

Always run backtests before overwriting BASE_STRATEGY:

```bash
# Test first
python ml/seed_tester.py test-top10 15m
python backtest_90_complete.py --test-seeds-file ml/test_top10_15m.json

# Then overwrite if results are good
python ml/seed_tester.py overwrite 15m --use-best
```

### 3. Monitor Performance

After overwriting, monitor live trading performance:

- Watch win rate in dashboard
- Check if performance matches backtest
- Reset if live performance degrades

### 4. Keep Test History

Result files include timestamps. Keep them for historical analysis:

```bash
# Review past tests
ls -lh ml/batch_test_results_*.json

# Compare two tests
diff ml/batch_test_results_15m_20241217_100000.json \
     ml/batch_test_results_15m_20241217_110000.json
```

## Troubleshooting

### No whitelisted seeds

```
❌ No whitelisted seeds found for 15m
```

**Solution:** Seeds are whitelisted automatically after achieving:
- 70%+ win rate
- Positive P&L
- 15+ trades

Run more backtests to populate the whitelist.

### Seed not found

```
❌ Seed 12345678 not found in registry
```

**Solution:** Check available seeds:
```bash
python ml/seed_tester.py status
python -c "from ml.seed_tracker import SeedTracker; t=SeedTracker(); print(t.whitelist)"
```

### Backup already exists

The system will NOT overwrite existing backups. If you need to reset:

```bash
# Check current backup
cat ml/base_strategy_backup.json

# Remove if you want to create new backup
rm ml/base_strategy_backup.json
```

## Integration with Existing Systems

### Seed Registry

All tested seeds are automatically recorded in:
- `ml/seed_registry.json` - Complete parameter history
- `ml/seed_catalog.json` - Trade-by-trade performance
- `ml/seed_performance_tracker.json` - Win rate tracking

### Dashboard

The dashboard automatically shows:
- Active seed per timeframe
- Override status
- Test history
- Win rate statistics

### Live Trading

When BASE_STRATEGY is overridden:
- New trades use overridden parameters
- Existing positions unaffected
- ML can still adapt if enabled

## Safety Features

1. **Automatic Backup**: Original BASE_STRATEGY backed up before first overwrite
2. **Confirmation Required**: Interactive 'yes/no' prompt before applying changes
3. **Timeframe Isolation**: Each timeframe can be overridden independently
4. **Easy Rollback**: Simple reset command restores originals
5. **Audit Trail**: All changes timestamped in override file

## Performance Expectations

### Test-All Duration

Approximate times (on 90-day dataset):

- 10 seeds: ~5-10 minutes
- 25 seeds: ~15-25 minutes
- 50 seeds: ~30-45 minutes

### Quick Test Duration

Top 10 seeds: ~5-8 minutes

### Memory Usage

Each backtest: ~100-200 MB
Batch testing: Processes serially, so memory is constant

## CLI Reference

```bash
# Seed Testing
python ml/seed_tester.py test-all <timeframe>
python ml/seed_tester.py test-top10 <timeframe>

# BASE_STRATEGY Management
python ml/seed_tester.py overwrite <timeframe> --use-best
python ml/seed_tester.py overwrite <timeframe> --seed <number>
python ml/seed_tester.py reset [--timeframe <timeframe>]
python ml/seed_tester.py status

# Backtest Execution
python backtest_90_complete.py --seed <number>
python backtest_90_complete.py --test-seeds-file <json_file>
python backtest_90_complete.py --test-seeds-file <json_file> --data-file <path>

# Options
--skip-check              Skip pre-flight validation
--non-interactive         Auto-update data without prompts
--data-file <path>        Custom data file (default: data/eth_90days.json)
```

## Summary

These new features provide:

✅ **Validation**: Test seeds before deploying
✅ **Optimization**: Find best performers per timeframe
✅ **Flexibility**: Easy override and rollback
✅ **Safety**: Automatic backups and confirmations
✅ **Efficiency**: Quick-test mode for rapid iteration
✅ **Integration**: Full dashboard and CLI support

The system maintains the existing 4-layer seed tracking while adding practical tools for seed validation and BASE_STRATEGY management.