Strategy Creation and Management Tools

Tools for running the optimizer, tracking jobs, saving strategies, and reviewing optimization history. All require the strategy hub to be opened first (call the strategy hub tool).

Workflow

create_strategy  -->  get_strategy_status  -->  save_strategy
                           |                        |
                           v                        v
                      (poll until complete)   get_saved_strategies
                                                    |
                                                    v
                                             find_iron_condors(saved_strategy_id)
                                                    |
                                                    v
                                             trade(action=propose_entry)
                                                    |
                                                    v
                                             trade(action=confirm)

create_strategy

Run the optimizer to find Pareto-optimal Iron Condor strategy configurations. Returns immediately with a job_id. The optimization runs in the background (1-5 minutes depending on tier and compute budget).

Parameters

Parameter Type Required Default Tier Description
ticker string Yes -- All Underlying symbol (e.g. "SPY", "QQQ", "IWM")
max_capital float Yes -- All Total portfolio budget in USD
effort string No "free" / "medium" All Simulation effort (free tier locked to "free")
dte_min int No preset All Minimum days-to-expiration (1-90)
dte_max int No preset All Maximum days-to-expiration (1-90)
top_k int No 5 All Number of top strategies to return
iv_rank_gate_mode string No "soft" All "soft" (warn) or "hard" (block if IV low)
iv_rank_threshold float No 0.20 All Minimum IV Rank (0.0-1.0)
pop_model string No preset Premium PoP model: lognormal, cornish_fisher, johnson_su, evt
vol_estimator string No preset Premium Vol estimator: yang_zhang, parkinson, realized_kernel, har_rv
vol_surface_model string No preset Premium Vol surface: svi, ssvi, vanna_volga, sabr
option_pricer string No preset Premium Option pricer: crr, quantlib, heston, sabr
garch_model string No preset Premium GARCH variant: gjr, egarch, tgarch, ms, fhs, vg, mjd, tail
entry_scorer string No preset Premium Entry scorer: ev, sharpe, sortino

Free tier: ticker, max_capital, top_k, dte_min, dte_max, iv_rank_gate_mode, iv_rank_threshold, and effort (locked to "free") are accepted. Algorithm parameters are locked to preset values (lognormal PoP, yang_zhang vol, SVI surface, CRR pricing, bootstrap simulation, 3 OOS seeds). Passing premium algorithm overrides returns a TIER_BLOCKED error.

Premium tier: Starts with preset defaults and applies any caller overrides. The effort parameter controls simulation depth (trials, paths, OOS seeds) and GPU compute. Delta floor is data-derived; only short_delta_max is overridable as an assignment risk cap. Additional overridable parameters include pop_model, vol_estimator, vol_surface_model, option_pricer, garch_model, entry_scorer, short_delta_max, long_delta_min, and long_delta_max.

Response: StrategySubmitted

{
  "status": "pending",
  "job_id": "a1b2c3d4-...",
  "tier": "free",
  "message": "Strategy optimization submitted. Call get_strategy_status(job_id='a1b2c3d4-...') to check progress."
}

Quota

Free tier: limited daily calls (check with get_quota_remaining). Premium tier: higher or unlimited daily quota.

get_strategy_status

Check the status of a background optimization job.

Parameters

Parameter Type Required Description
job_id string Yes Job UUID from create_strategy

Response: StrategyStatusResult

When running:

{
  "job_id": "a1b2c3d4-...",
  "status": "running",
  "tier": "free",
  "progress": {
    "latest_stage": "trials_progress",
    "stages_completed": 3,
    "trials": {"completed": 120, "total": 200}
  }
}

When completed:

{
  "job_id": "a1b2c3d4-...",
  "status": "completed",
  "tier": "free",
  "duration_seconds": 142.5,
  "preset": "balanced",
  "n_pareto": 5,
  "result": {
    "summary": "5 Pareto-optimal strategies found using balanced preset",
    "top_strategies": [
      {
        "rank": 1,
        "cagr": 0.22,
        "win_rate": 0.81,
        "avg_pop": 0.78,
        "annualized_pnl": 2200.00,
        "year1_pnl": 1950.00,
        "max_drawdown": 0.09,
        "cvar_drawdown": 0.12,
        "sharpe_ratio": 1.85,
        "sortino_ratio": 3.20,
        "dd_floor": 0.05,
        "p_ruin": 0.02,
        "capital_efficiency": 0.65,
        "n_lanes": 3,
        "entry_freq_days": 7,
        "avg_days_held": 32,
        "total_trades": 156,
        "robustness": {
          "oos_cagr_median": 0.18,
          "oos_cagr_p5": 0.08,
          "overfit_gap": 0.04
        },
        "config": { "..." : "..." }
      }
    ],
    "audit": { "..." : "..." },
    "warnings": ["IV_RANK_LOW: Current IV rank (0.15) is below threshold (0.20)"],
    "next_actions": [
      {"tool": "save_strategy", "description": "Bookmark a strategy you like"},
      {"tool": "find_iron_condors", "description": "Scan for live tradeable candidates"}
    ]
  }
}

Strategy metric fields

Field Description
cagr Compound annual growth rate
win_rate Fraction of trades that were profitable
avg_pop Average probability-of-profit across entries
annualized_pnl Annualized P&L in USD
year1_pnl First-year P&L in USD
max_drawdown Median max drawdown across simulation paths
cvar_drawdown Conditional Value-at-Risk (worst-5% drawdown)
sharpe_ratio Risk-adjusted return (excess return / std dev). NSGA-II objective. Clamped to [-10, 10].
sortino_ratio Downside-risk-adjusted return (excess return / downside dev). NSGA-II objective. Clamped to [-10, 10].
dd_floor Theoretical drawdown floor (max single-position loss / capital). Median DD below this is suspicious.
p_ruin Probability of ruin (capital going to zero)
capital_efficiency Diagnostic metric (no longer an NSGA-II objective). Capital utilization ratio.
n_lanes Number of concurrent IC positions
entry_freq_days Days between new entries
avg_days_held Average holding period in days
total_trades Total trades across the simulation
robustness.oos_cagr_median Median CAGR across out-of-sample seeds
robustness.oos_cagr_p5 5th percentile OOS CAGR (worst-case)
robustness.overfit_gap Ratio of in-sample to OOS performance (>1 = overfitting)

Failure response (0 strategies)

When no strategies survive the optimizer filters, the response includes a failure section with structured diagnostics instead of an empty top_strategies array:

{
  "result": {
    "summary": "No IC candidates passed filters for GOOGL...",
    "top_strategies": [],
    "failure": {
      "reason": "no_candidates",
      "message": "No IC candidates passed the min PoP / capital filters...",
      "candidate_stats": {
        "n_candidates": 0,
        "n_expiries": 0,
        "max_lanes": 0
      },
      "rejection_counts": {}
    }
  }
}

Failure reason codes:

Reason Meaning
no_candidates Zero IC chains passed the min PoP / capital filters
insufficient_candidates Too few candidates for reliable optimization
insufficient_expiries Fewer than 4 expiries — can't build multi-lane strategies
all_pruned All evaluated strategies were pruned (Sharpe/Sortino/robustness)
no_viable_strategies Strategies were evaluated but none met quality thresholds

Pipeline stages

Stages progress in order: fetching_data -> data_ready -> trials_progress -> trials_complete -> pareto_extracted -> oos_validating -> oos_complete -> pipeline_complete.

save_strategy

Bookmark a strategy from optimizer results. Creates a saved reference with a saved_strategy_id that can be passed to find_iron_condors and propose_entry for audit trail continuity.

Parameters

Parameter Type Required Default Description
run_id string Yes -- Job ID from create_strategy / get_strategy_status
strategy_rank int Yes -- Rank of the strategy to save (1 = best)
notes string No null Optional reason for saving

Response: SavedStrategyResult

{
  "id": "e5f6g7h8-...",
  "run_id": "a1b2c3d4-...",
  "strategy_rank": 1,
  "notes": "Best risk-adjusted for SPY weekly entries",
  "created_at": "2026-05-12T14:30:00Z"
}

get_saved_strategies

List previously saved strategies with their search parameters and run metadata.

Parameters

Parameter Type Required Default Description
limit int No 20 Max strategies to return (1-50)

Response

[
  {
    "id": "e5f6g7h8-...",
    "run_id": "a1b2c3d4-...",
    "strategy_rank": 1,
    "strategy_json": {
      "cagr": 0.22,
      "win_rate": 0.81,
      "max_drawdown": 0.09,
      "sharpe_ratio": 1.85,
      "sortino_ratio": 3.20,
      "cvar_drawdown": 0.12,
      "config": { "..." : "..." }
    },
    "notes": "Best risk-adjusted for SPY weekly entries",
    "created_at": "2026-05-12T14:30:00Z",
    "run_preset": "balanced",
    "run_ticker": "SPY",
    "run_created_at": "2026-05-12T14:15:00Z"
  }
]

get_optimization_history

Return past optimizer runs for this user (summaries only, not full results).

Parameters

Parameter Type Required Default Description
limit int No 10 Max runs to return (1-50)

Response

[
  {
    "run_id": "a1b2c3d4-...",
    "preset": "balanced",
    "status": "completed",
    "n_pareto": 5,
    "n_trials": 200,
    "duration_seconds": 142.5,
    "created_at": "2026-05-12T14:15:00Z",
    "summary": "5 Pareto-optimal strategies found"
  }
]

To retrieve full results from a past run, call get_strategy_status(job_id=run_id).

The Audit Chain

The saved_strategy_id links every step from optimization through execution:

create_strategy (run_id)
    |
    v
save_strategy (run_id + rank -> saved_strategy_id)
    |
    v
find_iron_condors (saved_strategy_id -> auto-loads search params)
    |
    v
trade(propose_entry, saved_strategy_id -> stored on proposal)
    |
    v
trade(confirm -> order submitted with full provenance)

Every proposal, order, and position can be traced back to the optimizer run that produced the strategy, including all parameters and algorithms used.

Cross-references