# AgentDB Simulation Wizard Guide

**Reading Time**: 10 minutes
**Prerequisites**: AgentDB CLI installed
**Target Audience**: Users preferring interactive interfaces

Learn to use the AgentDB simulation wizard - an interactive, step-by-step interface for creating and running vector database simulations. Perfect for beginners and those who prefer guided workflows.

---

## 🧙 What is the Wizard?

The AgentDB simulation wizard is an **interactive CLI tool** that guides you through:
1. Choosing a simulation scenario or building custom configurations
2. Selecting optimal parameters based on your use case
3. Running simulations with visual progress feedback
4. Understanding results with inline explanations

**Launch the wizard**:
```bash
agentdb simulate --wizard
```

---

## 🎯 Wizard Flow Overview

```
┌─────────────────────────────────────┐
│  🧙 AgentDB Simulation Wizard      │
└─────────────────────────────────────┘
            ↓
┌─────────────────────────────────────┐
│  Step 1: Choose Mode                │
│  • Run validated scenario           │
│  • Build custom simulation          │
│  • View past reports                │
└─────────────────────────────────────┘
            ↓
    ┌───────┴───────┐
    ↓               ↓
┌─────────┐   ┌─────────────┐
│Scenario │   │   Custom    │
│ Wizard  │   │   Builder   │
└─────────┘   └─────────────┘
    ↓               ↓
    └───────┬───────┘
            ↓
┌─────────────────────────────────────┐
│  Step 2: Configure Parameters       │
│  • Dataset size (nodes, dimensions) │
│  • Iteration count                  │
│  • Output preferences               │
└─────────────────────────────────────┘
            ↓
┌─────────────────────────────────────┐
│  Step 3: Confirm & Execute          │
│  • Review configuration             │
│  • Start simulation                 │
│  • Monitor progress                 │
└─────────────────────────────────────┘
            ↓
┌─────────────────────────────────────┐
│  Step 4: View Results               │
│  • Performance summary              │
│  • Report location                  │
│  • Next steps                       │
└─────────────────────────────────────┘
```

---

## 🚀 Scenario Wizard Walkthrough

### Step 1: Launch & Mode Selection

```bash
$ agentdb simulate --wizard
```

**You'll see**:
```
🧙 AgentDB Simulation Wizard

? What would you like to do?
  ❯ 🎯 Run validated scenario (recommended)
    🔧 Build custom simulation
    📊 View past reports
```

**Keyboard Navigation**:
- **↑/↓**: Move selection
- **Enter**: Confirm choice
- **Ctrl+C**: Exit wizard

**Choose**: **Run validated scenario** for this walkthrough.

---

### Step 2: Scenario Selection

**You'll see**:
```
? Choose a simulation scenario:
  ❯ ⚡ HNSW Exploration (8.2x speedup)
    🧠 Attention Analysis (12.4% improvement)
    🎯 Traversal Optimization (96.8% recall)
    🔄 Self-Organizing (97.9% uptime)
    🚀 Neural Augmentation (29.4% improvement)
    🌐 Clustering Analysis (Q=0.758 modularity)
    🔗 Hypergraph Exploration (73% compression)
    ⚛️  Quantum-Hybrid (Theoretical)
```

**Scenario Descriptions** (press `i` for info):

#### ⚡ HNSW Exploration
**What it tests**: Core graph topology and small-world properties
**Duration**: ~4.5 seconds (3 iterations)
**Best for**: Understanding baseline performance
**Validates**: 8.2x speedup, σ=2.84 small-world index

#### 🧠 Attention Analysis
**What it tests**: Multi-head GNN attention mechanisms
**Duration**: ~6.2 seconds (includes training)
**Best for**: Learning query enhancement
**Validates**: +12.4% recall, 3.8ms forward pass

#### 🎯 Traversal Optimization
**What it tests**: Search strategy comparison (greedy, beam, A*)
**Duration**: ~5.8 seconds
**Best for**: Finding optimal search parameters
**Validates**: Beam-5 = 96.8% recall, Dynamic-k = -18.4% latency

#### 🔄 Self-Organizing
**What it tests**: 30-day performance stability simulation
**Duration**: ~12.4 seconds (compressed time simulation)
**Best for**: Long-term deployment planning
**Validates**: MPC = 97.9% degradation prevention

#### 🚀 Neural Augmentation
**What it tests**: Full neural pipeline (GNN + RL + Joint Opt)
**Duration**: ~8.7 seconds
**Best for**: Maximum performance configuration
**Validates**: +29.4% overall improvement

#### 🌐 Clustering Analysis
**What it tests**: Community detection algorithms
**Duration**: ~4.2 seconds
**Best for**: Understanding data organization
**Validates**: Louvain Q=0.758 modularity

#### 🔗 Hypergraph Exploration
**What it tests**: Multi-agent collaboration patterns
**Duration**: ~3.8 seconds
**Best for**: Multi-entity relationships
**Validates**: 73% edge reduction, 96.2% task coverage

#### ⚛️ Quantum-Hybrid
**What it tests**: Theoretical quantum computing integration
**Duration**: ~2.1 seconds (simulation only)
**Best for**: Research roadmap
**Validates**: 2040+ viability timeline

**Select**: **HNSW Exploration** for this walkthrough.

---

### Step 3: Configuration Parameters

**You'll see**:
```
? Number of nodes: (100000)
```

**What it means**: How many vectors to test with
**Defaults**: 100,000 (optimal for benchmarking)
**Range**: 1,000 - 10,000,000
**Recommendation**: Use default for first run

**Press Enter** to accept default.

---

```
? Vector dimensions: (384)
```

**What it means**: Size of each vector (embedding size)
**Defaults**: 384 (common for BERT embeddings)
**Range**: 64 - 4096
**Common values**:
- 128: Lightweight embeddings
- 384: BERT-base, sentence transformers
- 768: BERT-large, OpenAI ada-002
- 1536: OpenAI text-embedding-3

**Press Enter** to accept default.

---

```
? Number of runs (for coherence): (3)
```

**What it means**: How many times to repeat the simulation
**Defaults**: 3 (validates consistency)
**Range**: 1 - 100
**Recommendation**:
- **1**: Quick test
- **3**: Standard validation (recommended)
- **10+**: High-confidence benchmarking

**Press Enter** to accept default.

---

```
? Use optimal validated configuration? (Y/n)
```

**What it means**: Apply discovered optimal parameters
**Defaults**: Yes
**Details**:
- **Yes**: Uses M=32, ef=200 (validated optimal)
- **No**: Prompts for manual parameter tuning

**For HNSW, optimal config includes**:
- M=32 (connection parameter)
- efConstruction=200 (build quality)
- efSearch=100 (query quality)
- Dynamic-k enabled (5-20 range)

**Press Enter** to accept (Yes).

---

### Step 4: Configuration Review

**You'll see**:
```
📋 Simulation Configuration:
   Scenario: HNSW Graph Topology Exploration
   Nodes: 100,000
   Dimensions: 384
   Iterations: 3
   ✅ Using optimal validated parameters (M=32, ef=200)

   Expected Performance:
   • Latency: ~61μs (8.2x vs baseline)
   • Recall@10: ~96.8%
   • Memory: ~151 MB
   • Duration: ~4.5 seconds
```

---

```
? Start simulation? (Y/n)
```

**Press Enter** to start.

---

### Step 5: Execution & Progress

**You'll see real-time progress**:

```
🚀 AgentDB Latent Space Simulation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 Scenario: HNSW Graph Topology Exploration
⚙️  Configuration: M=32, efConstruction=200, efSearch=100

🔄 Iteration 1/3
  ├─ Building graph...      [████████████] 100% (2.3s)
  ├─ Running queries...     [████████████] 100% (1.8s)
  ├─ Analyzing topology...  [████████████] 100% (0.4s)
  └─ ✅ Complete
     Latency: 61.2μs | Recall: 96.8% | QPS: 16,340

🔄 Iteration 2/3
  └─ ✅ Complete
     Latency: 60.8μs | Recall: 96.9% | QPS: 16,447

🔄 Iteration 3/3
  └─ ✅ Complete
     Latency: 61.4μs | Recall: 96.7% | QPS: 16,286

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Simulation Complete!
```

**Progress Indicators**:
- **[████████████] 100%**: Current operation progress
- **(2.3s)**: Time taken for operation
- **✅**: Operation successfully completed
- **⚠️**: Warning (non-critical)
- **❌**: Error (check logs)

---

### Step 6: Results Summary

**You'll see**:
```
📊 Summary:
   Average Latency: 61.1μs (σ=0.25μs, 0.4% variance)
   Recall@10: 96.8% (σ=0.08%, highly consistent)
   QPS: 16,358 (queries per second)
   Memory: 151 MB (100K vectors × 384d)
   Coherence: 98.6% ✅ (excellent reproducibility)

   🏆 Performance vs Baseline:
   • 8.2x faster than hnswlib (498μs)
   • +1.2% better recall
   • -18% memory usage

   🔬 Graph Properties:
   • Small-world index (σ): 2.84 ✅ (optimal 2.5-3.5)
   • Clustering coefficient: 0.39
   • Average path length: 5.1 hops (O(log N))
   • Modularity (Q): 0.758

📄 Full report saved:
   ./reports/hnsw-exploration-2025-11-30-143522.md

? What would you like to do next?
  ❯ View detailed report
    Run another simulation
    Exit wizard
```

---

## 🛠️ Custom Builder Walkthrough

### Step 1: Select Custom Mode

```bash
$ agentdb simulate --wizard
```

```
? What would you like to do?
    🎯 Run validated scenario
  ❯ 🔧 Build custom simulation
    📊 View past reports
```

**Select**: **Build custom simulation**

---

### Step 2: Component Selection (6 Steps)

#### Component 1/6: Vector Backend

```
? 1/6 Choose vector backend:
  ❯ 🚀 RuVector (8.2x speedup) [OPTIMAL]
    📦 hnswlib (baseline)
    🔬 FAISS
```

**Info panel** (auto-displayed):
```
RuVector Performance:
• Latency: 61μs (8.2x faster)
• QPS: 12,182
• Memory: 151 MB (100K vectors)
• Small-world σ: 2.84 (optimal)

Best For:
✓ Production deployments
✓ High-performance requirements
✓ Self-learning systems
```

**Select**: **RuVector** (press Enter)

---

#### Component 2/6: Attention Mechanism

```
? 2/6 Attention mechanism:
  ❯ 🧠 8-head attention (+12.4%) [OPTIMAL]
    4-head attention (memory-constrained)
    16-head attention (max accuracy)
    No attention (baseline)
```

**Info panel**:
```
8-Head GNN Attention:
• Recall: +12.4% improvement
• Latency: +5.5% (3.8ms forward pass)
• Convergence: 35 epochs
• Transfer: 91% to unseen data

Best For:
✓ High-recall requirements (>96%)
✓ Learning user preferences
✓ Semantic search
```

**Select**: **8-head attention** (press Enter)

---

#### Component 3/6: Search Strategy

```
? 3/6 Search strategy:
  ❯ 🎯 Beam-5 + Dynamic-k (96.8% recall) [OPTIMAL]
    Beam-2 + Dynamic-k (speed-critical)
    Beam-8 (accuracy-critical)
    Greedy (baseline)
    A* search (experimental)
```

**Info panel**:
```
Beam-5 + Dynamic-k:
• Latency: 87.3μs
• Recall: 96.8%
• Dynamic-k range: 5-20
• Adapts to query complexity

Improvements:
✓ -18.4% latency vs fixed-k
✓ Pareto optimal (best trade-off)
✓ Tested beam widths: 2, 5, 8, 16
```

**Select**: **Beam-5 + Dynamic-k** (press Enter)

---

#### Component 4/6: Clustering Algorithm

```
? 4/6 Clustering algorithm:
  ❯ 🎯 Louvain (Q=0.758) [OPTIMAL]
    Spectral clustering
    Hierarchical clustering
    No clustering
```

**Info panel**:
```
Louvain Algorithm:
• Modularity (Q): 0.758 (excellent)
• Semantic purity: 87.2%
• Hierarchy levels: 3-4
• Stability: 97% consistent

Best For:
✓ Hierarchical navigation
✓ Category-based search
✓ Natural communities
```

**Select**: **Louvain** (press Enter)

---

#### Component 5/6: Self-Healing

```
? 5/6 Enable self-healing (97.9% uptime)? (Y/n)
```

**Info panel**:
```
MPC Self-Healing:
• 30-day degradation: +4.5% (vs +95% static)
• Prevention rate: 97.9%
• Adaptation: <100ms
• Cost savings: $9,600/year

How it works:
✓ Predictive modeling
✓ Real-time topology adjustment
✓ Autonomous parameter tuning

Recommended: YES for production
```

**Press Enter** to accept (Yes).

---

#### Component 6/6: Neural Features

```
? 6/6 Neural augmentation features:
  ❯ ◉ GNN edge selection (-18% memory)
    ◉ RL navigation (-26% hops)
    ◉ Joint optimization (+9.1%)
    ◯ Attention routing (42.8% skip)
```

**Keyboard**:
- **Space**: Toggle selection
- **a**: Select all
- **i**: Invert selection
- **Enter**: Confirm

**Info panel**:
```
Neural Features Impact:
┌────────────────┬─────────┬────────┬─────────┐
│ Feature        │ Latency │ Recall │ Memory  │
├────────────────┼─────────┼────────┼─────────┤
│ GNN Edges      │ -2.3%   │ +0.9%  │ -18% ✅ │
│ RL Navigation  │ -13.6%  │ +4.2%  │ 0%      │
│ Joint Opt      │ -8.2%   │ +1.1%  │ -6.8%   │
│ Attention Rout │ -12.4%  │ 0%     │ +2%     │
└────────────────┴─────────┴────────┴─────────┘

Recommendation: GNN Edges + RL Nav (best ROI)
```

**Select**: **GNN edges**, **RL navigation**, **Joint optimization** (press Enter)

---

### Step 3: Configuration Summary

**You'll see**:
```
📋 Custom Simulation Configuration:

Components:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Backend:        🚀 RuVector
Attention:      🧠 8-head GNN
Search:         🎯 Beam-5 + Dynamic-k
Clustering:     🎯 Louvain
Self-Healing:   ✅ MPC (97.9% uptime)
Neural:         ✅ GNN edges, RL navigation, Joint optimization

Expected Performance:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Latency:        ~71.2μs (11.6x vs baseline)
Recall@10:      ~94.1%
Memory:         ~151 MB (-18%)
30-day stable:  +2.1% degradation only

Cost/Complexity: Medium (good ROI)

? Start custom simulation? (Y/n)
```

**Press Enter** to start.

---

## 🎨 Wizard Features

### Inline Help

Press `?` at any prompt for context-sensitive help:

```
? 2/6 Attention mechanism: ?

HELP: Attention Mechanisms
━━━━━━━━━━━━━━━━━━━━━━━━━━
Neural attention learns which graph connections
are most important for your queries.

Options:
• 8-head: Optimal (validated +12.4% recall)
• 4-head: Memory-constrained systems
• 16-head: Maximum accuracy (research)
• None: Baseline (simplest)

Performance Impact:
✓ Better recall (+1.6% to +13.1%)
✗ Slight latency cost (+3-9%)
✓ Learns over time (91% transfer)

Recommendation: 8-head for production
━━━━━━━━━━━━━━━━━━━━━━━━━━

Press Enter to continue...
```

---

### Keyboard Shortcuts

| Key | Action |
|-----|--------|
| **↑/↓** | Navigate options |
| **Enter** | Confirm selection |
| **Space** | Toggle (checkboxes) |
| **?** | Show help for current prompt |
| **i** | Show info panel (scenarios) |
| **a** | Select all (checkboxes) |
| **Ctrl+C** | Exit wizard |
| **Esc** | Go back one step |

---

### Save & Resume Configurations

After building a custom config, you can save it:

```
? Save this configuration? (Y/n)
```

```
? Configuration name: my-optimal-config
```

**Reuse saved config**:
```bash
agentdb simulate --config my-optimal-config
```

**List saved configs**:
```bash
agentdb simulate --list-configs
```

---

## 📊 View Past Reports Mode

### Step 1: Select Report Viewer

```
? What would you like to do?
    🎯 Run validated scenario
    🔧 Build custom simulation
  ❯ 📊 View past reports
```

**Select**: **View past reports**

---

### Step 2: Report Selection

```
? Select a report to view:
  ❯ hnsw-exploration-2025-11-30-143522.md (4.5s ago) ⭐ Latest
    neural-augmentation-2025-11-30-142134.md (15m ago)
    custom-config-optimal-2025-11-30-135842.md (48m ago)
    traversal-optimization-2025-11-29-182341.md (Yesterday)
    [Load more...]
```

**Info panel**:
```
Preview: hnsw-exploration-2025-11-30-143522.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Scenario: HNSW Graph Topology
Latency:  61.1μs (8.2x speedup)
Recall:   96.8%
Memory:   151 MB
Duration: 4.5s
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

**Select**: Any report to view inline or open in editor.

---

### Step 3: Report Actions

```
? What would you like to do with this report?
  ❯ View summary in terminal
    Open full report in editor
    Compare with another report
    Export to PDF
    Share URL (if uploaded)
    Delete report
```

---

## 🚨 Troubleshooting Wizard Issues

### Wizard Won't Start

**Error**:
```
Error: inquirer not found
```

**Solution**:
```bash
npm install -g inquirer chalk ora
agentdb simulate --wizard
```

---

### Keyboard Input Not Working

**Issue**: Arrow keys don't navigate

**Solution**: Use `j/k` for vi-style navigation:
- `j`: Move down
- `k`: Move up
- `Enter`: Confirm

**Or**: Update your terminal:
```bash
# macOS
brew install --cask iterm2

# Linux
sudo apt install gnome-terminal
```

---

### Wizard Crashes Mid-Simulation

**Error**:
```
Unhandled promise rejection
```

**Solution**:
```bash
# Check logs
cat ~/.agentdb/wizard-error.log

# Run with verbose mode
agentdb simulate --wizard --verbose
```

---

### Can't See Progress Bars

**Issue**: Progress bars render as text

**Solution**:
```bash
# Disable fancy UI
agentdb simulate --wizard --no-spinner

# Or use simple mode
agentdb simulate --wizard --simple
```

---

## 💡 Tips & Best Practices

### 1. Start Simple
Run validated scenarios before building custom configs:
```bash
# Good: Learn from validated scenarios first
agentdb simulate --wizard → "Run validated scenario"

# Then: Build custom after understanding components
agentdb simulate --wizard → "Build custom simulation"
```

### 2. Use Optimal Defaults
When prompted "Use optimal validated configuration?", say **Yes** unless you have specific requirements.

### 3. Save Your Configs
After building a custom config you like, save it for reuse:
```
? Save this configuration? Yes
? Configuration name: my-production-config
```

### 4. Compare Before Deploying
Run both baseline and optimized configs to validate improvements:
```bash
# Baseline
agentdb simulate hnsw --output ./reports/baseline/

# Optimized
agentdb simulate --config my-production-config --output ./reports/optimized/
```

### 5. Iterate on Iterations
For critical deployments, run 10+ iterations for high confidence:
```
? Number of runs: 10
```

---

## 🎓 Advanced Wizard Usage

### Environment Variables

Control wizard behavior via environment:

```bash
# Skip confirmation prompts
export AGENTDB_WIZARD_SKIP_CONFIRM=1

# Default to JSON output
export AGENTDB_DEFAULT_FORMAT=json

# Auto-save all configs
export AGENTDB_AUTO_SAVE_CONFIG=1

agentdb simulate --wizard
```

---

### Templating

Create config templates for teams:

```bash
# Create team template
agentdb simulate --wizard --save-template production-team

# Team members use template
agentdb simulate --template production-team
```

---

### CI/CD Integration

Run wizard non-interactively in CI:

```bash
# Use config file
agentdb simulate --config-file ./ci-config.json

# Or environment variables
export AGENTDB_SCENARIO=hnsw
export AGENTDB_ITERATIONS=3
export AGENTDB_OUTPUT=./ci-reports/
agentdb simulate --ci-mode
```

---

## 📚 Next Steps

### Learn More
- **[CLI Reference](CLI-REFERENCE.md)** - All command options
- **[Custom Simulations](CUSTOM-SIMULATIONS.md)** - Component details
- **[Quick Start](QUICK-START.md)** - Command-line usage

### Dive Deeper
- **[Optimization Strategy](../architecture/OPTIMIZATION-STRATEGY.md)** - Performance tuning
- **[Simulation Architecture](../architecture/SIMULATION-ARCHITECTURE.md)** - Technical details

---

**Ready to build?** Launch the wizard:
```bash
agentdb simulate --wizard
```