Marc Rejohn Castillano 5cb6561924 added ruflo

2026-04-09 19:01:53 +08:00

20 KiB

Raw Blame History

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:

Choosing a simulation scenario or building custom configurations
Selecting optimal parameters based on your use case
Running simulations with visual progress feedback
Understanding results with inline explanations

Launch the wizard:

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

$ 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

$ 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:

agentdb simulate --config my-optimal-config

List saved configs:

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:

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:

# macOS
brew install --cask iterm2

# Linux
sudo apt install gnome-terminal

Wizard Crashes Mid-Simulation

Error:

Unhandled promise rejection

Solution:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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 - All command options
Custom Simulations - Component details
Quick Start - Command-line usage

Dive Deeper

Optimization Strategy - Performance tuning
Simulation Architecture - Technical details

Ready to build? Launch the wizard:

agentdb simulate --wizard

20 KiB Raw Blame History Unescape Escape

AgentDB Simulation Wizard Guide

🧙 What is the Wizard?

🎯 Wizard Flow Overview

🚀 Scenario Wizard Walkthrough

Step 1: Launch & Mode Selection

Step 2: Scenario Selection

⚡ HNSW Exploration

🧠 Attention Analysis

🎯 Traversal Optimization

🔄 Self-Organizing

🚀 Neural Augmentation

🌐 Clustering Analysis

🔗 Hypergraph Exploration

⚛️ Quantum-Hybrid

Step 3: Configuration Parameters

Step 4: Configuration Review

Step 5: Execution & Progress

Step 6: Results Summary

🛠️ Custom Builder Walkthrough

Step 1: Select Custom Mode

Step 2: Component Selection (6 Steps)

Component 1/6: Vector Backend

Component 2/6: Attention Mechanism

Component 3/6: Search Strategy

Component 4/6: Clustering Algorithm

Component 5/6: Self-Healing

Component 6/6: Neural Features

Step 3: Configuration Summary

🎨 Wizard Features

Inline Help

Keyboard Shortcuts

Save & Resume Configurations

📊 View Past Reports Mode

Step 1: Select Report Viewer

Step 2: Report Selection

Step 3: Report Actions

🚨 Troubleshooting Wizard Issues

Wizard Won't Start

Keyboard Input Not Working

Wizard Crashes Mid-Simulation

Can't See Progress Bars

💡 Tips & Best Practices

1. Start Simple

2. Use Optimal Defaults

3. Save Your Configs

4. Compare Before Deploying

5. Iterate on Iterations

🎓 Advanced Wizard Usage

Environment Variables

Templating

CI/CD Integration

📚 Next Steps

Learn More

Dive Deeper

20 KiB

Raw Blame History