Hyperfold AI

Agent Simulation

Test agent behavior with simulated buyer interactions.

Overview

The hyperfold sim commands let you test agent behavior without real buyers or payments. Simulate negotiations, test edge cases, and validate pricing logic before deploying to production.

Chat Simulation

Have an interactive conversation with your agent:

# Start interactive chat simulation
$ hyperfold sim chat

> [Sim] Starting simulation environment...
> [Agent] Connecting to sales-bot-01...

Welcome to Hyperfold Simulation
Type your messages as a buyer agent. Type /help for commands.

You: I'm looking for waterproof running shoes
Agent: I'd be happy to help you find waterproof running shoes! Based on
       your search, I recommend the AeroRun X2 - it's our top-rated
       marathon shoe with Gore-Tex waterproofing. It's priced at $180.

You: That's a bit expensive. Can you do $120?
Agent: I understand you're looking for value. For $120, I can't quite
       reach that price, but I can offer you $162 - that's a 10% discount.
       This still beats Amazon's price of $165 for the same shoe.

You: Deal. I'll take it.
Agent: Excellent! I'll process your order for the AeroRun X2 at $162.
       [Processing payment via test SPT...]
       Your order #HF-12345 is confirmed! Expect delivery in 2-3 days.

SESSION COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Duration:      45 seconds
  Turns:         3
  Outcome:       conversion
  Final Price:   $162.00 (10% discount)
  Margin:        48%

Buyer Personas

Simulate different buyer types with predefined personas:

# Use a predefined buyer persona
$ hyperfold sim chat --persona="premium_buyer"

> [Persona] Premium Buyer: High budget, values quality, expects discounts
> [Context] Loyalty: Gold tier, 12 previous orders, $2,450 lifetime

# Available built-in personas
$ hyperfold sim personas list

BUYER PERSONAS

NAME              DESCRIPTION                       BUDGET    BEHAVIOR
premium_buyer     Gold tier, expects discounts      High      Negotiates firmly
budget_buyer      Price-sensitive, compares         Low       Walks away easily
impulse_buyer     Quick decisions, less haggling    Medium    Accepts early
enterprise        B2B buyer, bulk orders            Very High Volume discounts
comparison        Mentions competitors often        Medium    Uses leverage
loyal_customer    Long history, expects perks       High      Relationship-focused

# Create custom persona
$ cat > my-persona.yaml << 'EOF'
name: aggressive_haggler
description: "Pushes hard for lowest price"

attributes:
  budget: medium
  patience: high
  loyalty_tier: silver
  previous_orders: 3

behavior:
  opening_offer_discount: 0.40  # Start at 40% below list
  counter_increment: 0.05       # Increase 5% each round
  max_rounds: 5                 # Give up after 5 rounds
  walkaway_threshold: 0.15      # Accept if within 15% of target
  mentions_competitors: true

dialogue_style:
  tone: assertive
  uses_silence: true
  asks_for_manager: sometimes
EOF

$ hyperfold sim chat --persona=./my-persona.yaml

Test Scenarios

Run scripted scenarios to test specific behaviors:

# Run predefined test scenarios
$ hyperfold sim scenario --name="price_negotiation"

> [Scenario] Testing price negotiation flow
> [Steps] 5 conversation turns planned

SCENARIO: price_negotiation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Turn 1: Search for product
  Buyer: "I need running shoes"
  Agent: ✓ Returned relevant products

Turn 2: Request quote
  Buyer: "How much for the AeroRun X2?"
  Agent: ✓ Provided price ($180)

Turn 3: Make offer below floor
  Buyer: "I'll pay $80"
  Agent: ✓ Rejected (below floor of $92)

Turn 4: Make reasonable offer
  Buyer: "What about $140?"
  Agent: ✓ Counter-offered at $162

Turn 5: Accept counter
  Buyer: "OK, I'll take it"
  Agent: ✓ Processed order

RESULT: PASSED ✓
  All assertions met
  Agent respected floor price
  Final margin: 48%

# Available test scenarios
$ hyperfold sim scenarios list

SCENARIOS

NAME                    TESTS                          ASSERTIONS
price_negotiation       Negotiation flow               Floor respected, conversion
reject_lowball          Below-floor handling           Rejection with explanation
bundle_suggestion       Cross-sell behavior            Bundle offered, discount applied
out_of_stock            Inventory handling             Alternative suggested
payment_failure         Failed payment recovery        Retry offered, graceful handling
competitor_mention      Competitive response           Value proposition, not defensive

# Run all scenarios
$ hyperfold sim scenario --all

> [Run] Executing 6 scenarios...

RESULTS SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ price_negotiation      PASSED
  ✓ reject_lowball         PASSED
  ✓ bundle_suggestion      PASSED
  ✓ out_of_stock           PASSED
  ✗ payment_failure        FAILED (no retry offered)
  ✓ competitor_mention     PASSED

5/6 scenarios passed

Batch Testing

Run many simulations for statistical analysis:

# Run batch simulations for statistics
$ hyperfold sim batch --count=100 --persona="premium_buyer"

> [Batch] Running 100 simulations...
> [Progress] ████████████████████ 100/100

BATCH RESULTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

OUTCOMES:
  Conversions:    67 (67%)
  Rejections:     18 (18%)
  Abandoned:      15 (15%)

PRICING:
  Avg Final Price:      $158.40
  Avg Discount:         12.0%
  Avg Margin:           46.2%
  Floor Violations:     0

PERFORMANCE:
  Avg Response Time:    1.2s
  Avg Turns:            3.4
  Avg Duration:         42s

# Batch with varied personas
$ hyperfold sim batch --count=500 --personas="all"

> [Batch] Running 500 simulations across 6 personas...

RESULTS BY PERSONA
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PERSONA             COUNT   CONV%   AVG DISCOUNT   AVG MARGIN
premium_buyer       83      72%     14.2%          44.8%
budget_buyer        84      45%     18.5%          38.2%
impulse_buyer       83      89%     8.1%           52.3%
enterprise          83      78%     22.0%          35.5%
comparison          84      52%     16.8%          41.2%
loyal_customer      83      81%     12.5%          46.8%

# Export batch results
$ hyperfold sim batch --count=100 --output=results.json

Result Analysis

Analyze simulation results and compare versions:

# Analyze simulation results
$ hyperfold sim analyze ./results.json

SIMULATION ANALYSIS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

CONVERSION FUNNEL:
  Sessions Started:     100
  Product Found:        98 (98%)
  Quote Requested:      92 (94%)
  Negotiation Started:  85 (92%)
  Converted:            67 (79%)

DROP-OFF ANALYSIS:
  No relevant products:     2 sessions
  Price too high initially: 6 sessions
  Negotiation failed:       18 sessions
  Payment issues:           7 sessions

PRICING INSIGHTS:
  Most common final discount: 10% (Gold tier)
  Highest accepted discount:  25%
  Lowest accepted price:      $95.00 (near floor)

RECOMMENDATIONS:
  1. Consider raising floor price - 12 sales at <$100
  2. Bundle suggestion timing could improve - only 23% uptake
  3. Competitor mention handling is strong - 89% retention

# Compare two simulation runs
$ hyperfold sim compare ./results-v1.json ./results-v2.json

COMPARISON: v1 vs v2
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

METRIC              V1          V2          CHANGE
Conversion Rate     67%         72%         +5% ↑
Avg Discount        12.0%       11.2%       -0.8% ↓ (better)
Avg Margin          46.2%       47.8%       +1.6% ↑
Avg Response        1.2s        1.1s        -0.1s ↓ (better)

VERDICT: V2 shows improvement across all metrics