Migration: FundPro → MesoSim v3

This guide outlines the FundPro‑specific changes required to migrate to MesoSim v3, including API payloads, database schema changes, and Merlin usage updates.

For broader behavior and strategy format changes, see the general MesoSim v2→v3 migration guide.

Summary of Changes

• API
  • Create uses StrategyDefinition payload (was v2 Job/TemplateName)
  • Path rename: GET /api/v1/backtest/{id}/strategy-definition (was job-definition)
• Database
  • backtest_results.template_name → strategy_name
  • backtest_results.job_definition → strategy_definition
• Merlin
  • Merlin-v1.5.0 supports MesoSim v3 jobs
  • Library: use run_job/list_backtests/get_backtest_events/get_backtest_navs/get_strategy_definition
  • Portfolio config: StrategyDefinition replaces Job
  • Flags: prefer --data-coll-backtest-id (alias --data-coll-job-id remains)

API Migration

Create Backtest (v3)

Endpoint: PUT /api/v1/backtest/new

Request body after MesoSim v3:

StrategyDefinition top level field representing now the Strategy Definition (was: Job).

{
  "StrategyDefinition": {
    "StrategyName": "ShortPut",
    "Backtest": {
      "Name": "generate",
      "Start": "2022-01-01T00:00:00",
      "End": "2022-12-31T23:59:59",
      "Cash": "125000"
    },
    "Symbol": "SPX",
    "Structure": { /* legs, expirations, selectors */ },
    "Entry": { /* schedule, conditions, vars */ },
    "Adjustment": null,
    "Exit": { /* schedule, conditions, targets */ },
    "Settings": { "Sim": { /* fill, commission */ }, "Core": { /* margin, constraints */ } }
  },
  "Shared": false
}

Request body prior to MesoSim v3:

The top level Job field was representing the Strategy Definition. This is changed to StrategyDefinition in v3.

{
  "Job": {
    "StrategyName": "ShortPut",
    "Backtest": {
      "Name": "generate",
      "Start": "2022-01-01T00:00:00",
      "End": "2022-12-31T23:59:59",
      "Cash": "125000"
    },
    "Symbol": "SPX",
    "Structure": { /* legs, expirations, selectors */ },
    "Entry": { /* schedule, conditions, vars */ },
    "Adjustment": null,
    "Exit": { /* schedule, conditions, targets */ },
    "Settings": { "Sim": { /* fill, commission */ }, "Core": { /* margin, constraints */ } }
  },
  "Shared": false
}

Get Strategy Definition (v3)

Endpoint: GET /api/v1/backtest/{id}/strategy-definition

Returns the StrategyDefinition (previously known as: Job Definition).

Database Migration

The following fields were renamed in the backtest_results table in the results_db:

• template_name → strategy_name
• job_definition → strategy_definition

Update downstream queries and dashboards accordingly. Example update:

select 
    created_at,
    name, 
    strategy_name, 
    strat_sharpe, 
    strat_max_dd, 
    strat_cagr_pct
from backtest_results
order by strat_sharpe desc;

Querying into the Strategy Definition JSON:

with cte as (
    select 
        id, 
        CAST(JSON_EXTRACT(strategy_definition, '$.Structure.Expirations[0].DTE') AS float) AS exp1,
        CAST(JSON_EXTRACT(strategy_definition, '$.Exit.MaxDaysInTrade') AS float) AS MaxDaysInTrade,
        strat_sharpe,
        strat_cagr_pct,
        strat_max_dd
    from backtest_results 
    where strategy_name = 'MyStrategy'
)
select * from cte;

Merlin Updates

Merlin v1.5.0 (or later) fully supports MesoSim v3.0.

Library Usage

from merlin.deltaray_apis.mesosim_api import run_job

strategy_definition = {...}  # v3 StrategyDefinition
backtest_id, analytics = run_job(MESOSIM_INSTANCE, API_KEY, strategy_definition)

CLI Usage

• Store the Strategy Definition files with -strategy.json prefix (was: -job.json).

Example: configs/strategies/boxcar-strategy.json

• Prefer --data-coll-backtest-id= over --data-coll-job-id= (alias remains)

Examples:

merlin discover-predictors configs/strategies/boxcar-strategy.json --add-ivs --add-greeks \
  --feature-selection=cramers_v --feature-grouping=tails --bins-or-tails=0.1

merlin optimize-strategy configs/strategies/boxcar-strategy.json configs/strategies/boxcar-model-cfg.json --include-last-fold

Portfolio Config

Use StrategyDefinition instead of Job in portfolio configs:

{
  "Strategies": {
    "boxcar": {
      "StrategyDefinition": "configs/strategies/boxcar-strategy.json",
      "ModelCfg": "configs/strategies/boxcar-model-cfg.json",
      "DataCollectionJobId": null
    }
  }
}