aitbc/docs/scenarios/51_simulation_scenarios.md

Simulation Scenarios for hermes Agents

Level: Intermediate
Prerequisites: Basic CLI knowledge, AITBC CLI installed, coordinator-api running
Estimated Time: 30 minutes
Last Updated: 2026-05-27
Version: 1.0

🧭 Navigation Path:

🏠 Documentation Home → 🎭 Agent Scenarios → You are here

breadcrumb: Home → Scenarios → Simulation Scenarios

---

🎯 See Also:

• 📖 Previous Scenario: 49 Resource Management
• 📖 Next Scenario: 52 Edge Advanced Operations
• ⚙️ Simulation Documentation: CLI Simulation Commands

---

📚 Scenario Overview

This scenario demonstrates how hermes agents use simulation commands to model and test various AITBC ecosystem scenarios including blockchain operations, wallet behavior, price movements, network topology, and AI job processing. Simulations enable agents to validate strategies and predict outcomes before executing real transactions.

Use Case

An hermes agent needs to:

• Model blockchain behavior under different conditions
• Simulate wallet creation and balance distribution
• Predict price movements with various volatility patterns
• Test network topology and latency scenarios
• Simulate AI job submission and processing workflows
• Validate strategies before real execution

What You'll Learn

• Run blockchain simulations with custom parameters
• Simulate wallet creation and balance distribution
• Model price movements with trends and volatility
• Test network topology and latency scenarios
• Simulate AI job processing workflows
• Run simulations in async mode
• Monitor simulation status and retrieve results

Features Combined

• Blockchain Simulation: Model block generation and transaction processing
• Wallet Simulation: Create wallets with various balance distributions
• Price Simulation: Model price movements with trends and volatility
• Network Simulation: Test network topology and latency scenarios
• AI Jobs Simulation: Model AI job submission and processing
• Async Execution: Run simulations asynchronously
• Status Tracking: Monitor simulation progress and results

---

📋 Prerequisites

Knowledge Required

• Basic command-line interface usage
• Understanding of blockchain concepts
• AITBC CLI installed and accessible
• coordinator-api running (for API-integrated simulations)

System Requirements

• AITBC CLI installed
• coordinator-api running (http://127.0.0.1:18000)
• Sufficient system resources for simulations

---

🚀 Quick Start

# Blockchain simulation
aitbc simulate blockchain --blocks 10 --transactions 50

# Wallets simulation
aitbc simulate wallets --count 5 --balance 1000

# Price simulation
aitbc simulate price --days 30 --volatility 0.1

# Network simulation
aitbc simulate network --nodes 10 --latency 50

# AI jobs simulation
aitbc simulate ai-jobs --jobs 20 --duration 300

---

📖 Detailed Steps

Step 1: Blockchain Simulation

Simulate blockchain block generation and transaction processing:

aitbc simulate blockchain --blocks 10 --transactions 50

Expected Output:

{
  "simulation_id": "sim_1716789123",
  "blocks": 10,
  "transactions": 50,
  "status": "completed",
  "block_time_avg": "2.5s"
}

What happens:

• Blockchain simulation executed
• Blocks generated with transactions
• Performance metrics collected

Step 2: Blockchain with Custom Parameters

Simulate blockchain with difficulty and custom parameters:

aitbc simulate blockchain --blocks 100 --transactions 500 --difficulty 5

Expected Output:

{
  "simulation_id": "sim_1716789234",
  "blocks": 100,
  "transactions": 500,
  "difficulty": 5,
  "status": "completed"
}

Step 3: Wallets Simulation

Simulate wallet creation with balance distribution:

aitbc simulate wallets --count 5 --balance 1000

Expected Output:

{
  "simulation_id": "sim_1716789345",
  "wallets": 5,
  "balance": 1000,
  "distribution": "uniform",
  "status": "completed"
}

Step 4: Wallets with Exponential Distribution

Simulate wallets with exponential balance distribution:

aitbc simulate wallets --count 10 --distribution exponential

Expected Output:

{
  "simulation_id": "sim_1716789456",
  "wallets": 10,
  "distribution": "exponential",
  "status": "completed"
}

Step 5: Price Simulation

Simulate price movements with volatility:

aitbc simulate price --days 30 --volatility 0.1

Expected Output:

{
  "simulation_id": "sim_1716789567",
  "days": 30,
  "volatility": 0.1,
  "prices": [100.0, 105.2, 98.7, ...],
  "status": "completed"
}

Step 6: Price with Trend

Simulate price movements with bullish trend:

aitbc simulate price --days 90 --trend bullish --volatility 0.15

Expected Output:

{
  "simulation_id": "sim_1716789678",
  "days": 90,
  "trend": "bullish",
  "volatility": 0.15,
  "status": "completed"
}

Step 7: Network Simulation

Simulate network topology and latency:

aitbc simulate network --nodes 10 --latency 50

Expected Output:

{
  "simulation_id": "sim_1716789789",
  "nodes": 10,
  "latency": 50,
  "topology": "random",
  "status": "completed"
}

Step 8: Network with Custom Topology

Simulate network with mesh topology:

aitbc simulate network --nodes 20 --topology mesh --latency 100

Expected Output:

{
  "simulation_id": "sim_1716789890",
  "nodes": 20,
  "topology": "mesh",
  "latency": 100,
  "status": "completed"
}

Step 9: AI Jobs Simulation

Simulate AI job submission and processing:

aitbc simulate ai-jobs --jobs 20 --duration 300

Expected Output:

{
  "simulation_id": "sim_1716790001",
  "jobs": 20,
  "duration": 300,
  "status": "completed"
}

Step 10: AI Jobs with GPU Requirements

Simulate AI jobs with GPU requirements:

aitbc simulate ai-jobs --jobs 30 --gpu-required --duration 600

Expected Output:

{
  "simulation_id": "sim_1716790112",
  "jobs": 30,
  "gpu_required": true,
  "duration": 600,
  "status": "completed"
}

Step 11: Run Simulation

Run a simulation with type and duration:

aitbc simulate run --type blockchain --duration 60

Expected Output:

{
  "simulation_id": "sim_1716790223",
  "type": "blockchain",
  "duration": 60,
  "status": "started"
}

Step 12: Run Async Simulation

Run simulation in async mode:

aitbc simulate run --type network --async --duration 120

Expected Output:

{
  "simulation_id": "sim_1716790334",
  "type": "network",
  "async": true,
  "status": "started"
}

Step 13: Check Simulation Status

Monitor simulation progress:

aitbc simulate status sim_1716790223

Expected Output:

{
  "simulation_id": "sim_1716790223",
  "status": "running",
  "progress": "75%",
  "elapsed_time": "45s"
}

Step 14: Get Simulation Results

Retrieve simulation results:

aitbc simulate result sim_1716790223

Expected Output:

{
  "simulation_id": "sim_1716790223",
  "status": "completed",
  "results": {
    "blocks_generated": 10,
    "transactions_processed": 50,
    "avg_block_time": "2.5s"
  }
}

---

🔧 Advanced Usage

Custom Simulation Scenarios

Create complex simulation scenarios by combining parameters:

# High-volume blockchain simulation
aitbc simulate blockchain --blocks 1000 --transactions 10000 --difficulty 8

# Large-scale wallet simulation
aitbc simulate wallets --count 1000 --distribution power-law --balance 10000

# Long-term price simulation
aitbc simulate price --days 365 --trend bearish --volatility 0.25

# Complex network topology
aitbc simulate network --nodes 50 --topology hierarchical --latency 200

# Complex AI job workflow
aitbc simulate ai-jobs --jobs 100 --gpu-required --multi-gpu --duration 3600

Batch Simulations

Run multiple simulations sequentially:

#!/bin/bash
# run_simulations.sh

sim_types=("blockchain" "wallets" "price" "network" "ai-jobs")

for sim in "${sim_types[@]}"; do
    echo "Running simulation: $sim"
    aitbc simulate run --type "$sim" --duration 60
    
    # Wait for completion
    sleep 5
done

Simulation Comparison

Compare results from different simulations:

# Run simulation A
aitbc simulate blockchain --blocks 100 --transactions 500 --difficulty 3
sim_id_a=$(aitbc simulate run --type blockchain --duration 60 | jq -r '.simulation_id')

# Run simulation B
aitbc simulate blockchain --blocks 100 --transactions 500 --difficulty 7
sim_id_b=$(aitbc simulate run --type blockchain --duration 60 | jq -r '.simulation_id')

# Compare results
aitbc simulate result $sim_id_a > result_a.json
aitbc simulate result $sim_id_b > result_b.json
diff result_a.json result_b.json

---

⚠️ Important Notes

Simulation IDs

• Each simulation gets a unique ID: sim_<timestamp>
• Use simulation IDs for tracking and result retrieval
• IDs are generated automatically

Simulation States

• Started: Simulation initialized
• Running: Simulation in progress
• Completed: Simulation finished successfully
• Failed: Simulation encountered an error

Resource Requirements

• Large simulations may require significant CPU/memory
• Async mode recommended for long-running simulations
• Monitor system resources during simulations

Output Formats

• JSON format for programmatic processing
• Table format for human-readable output
• Use --format json or --format table to specify

---

🐛 Troubleshooting

Simulation not found

Error:

Error: Simulation 'sim_123' not found

Solution:

# Check simulation ID
aitbc simulate status sim_123

# List recent simulations (if available)
aitbc simulate list

Coordinator-api unavailable

Error:

Error: coordinator-api not available

Solution:

# Check coordinator-api status
curl http://127.0.0.1:18000/health

# Start coordinator-api if needed
systemctl start aitbc-coordinator-api

Simulation stuck in running state

Issue: Simulation status shows "Running" but not progressing

Solution:

# Check coordinator-api status
curl http://127.0.0.1:18000/health

# Review simulation logs
# (Location depends on implementation)

# Cancel simulation if needed
aitbc simulate cancel sim_123

Invalid simulation parameters

Error:

Error: Invalid parameter value

Solution:

# Check parameter ranges
aitbc simulate blockchain --help

# Use valid parameter values
aitbc simulate blockchain --blocks 10  # Valid
aitbc simulate blockchain --blocks -5  # Invalid

---

📊 Testing

Run the integration test script to verify simulation operations:

# Run pytest tests
cd /opt/aitbc
pytest tests/cli/test_simulate_integration.py -v

# Run bash integration test
scripts/testing/test_simulate.sh

Expected test output:

tests/cli/test_simulate_integration.py::TestSimulateCommandsIntegration::test_simulate_blockchain PASSED
tests/cli/test_simulate_integration.py::TestSimulateCommandsIntegration::test_simulate_wallets PASSED
tests/cli/test_simulate_integration.py::TestSimulateCommandsIntegration::test_simulate_price PASSED
...

---

🎓 Summary

In this scenario, you learned:

• How to run blockchain simulations with custom parameters
• How to simulate wallet creation and balance distribution
• How to model price movements with trends and volatility
• How to test network topology and latency scenarios
• How to simulate AI job processing workflows
• How to run simulations in async mode
• How to monitor simulation status and retrieve results

Key Takeaways:

• Simulations enable strategy validation before real execution
• Each simulation gets a unique ID for tracking
• Async mode recommended for long-running simulations
• Custom parameters enable realistic scenario modeling
• Status monitoring enables simulation control
• Results retrieval enables analysis and comparison

---

🔄 Related Scenarios

• Scenario 03: Genesis Deployment - Blockchain operations
• Scenario 07: AI Job Submission - AI job operations
• Scenario 09: GPU Listing - GPU marketplace operations
• Scenario 49: Resource Management - Resource allocation