Foundation models

Each model has two names. The model_id identifies a specific build, and it is the id that sim_ids are minted from. The production_name is the stable product name, built as {model}-{market}-{version}-{size}: for example flow-hkex-1-100M or flow-lse-1-100M, where 100M is the parameter count. Anywhere a model_id is accepted (run() and available_data()) you can pass either name. The match ignores case, spaces, underscores and dashes, so "Flow HKEX 1 100M" finds the same model. A name that matches more than one model is a 400, and one that matches none is a 404.

model_args differ by model family — a diffusion model exposes guidance and num_steps where an autoregressive one exposes temperature. Read the ids and the knobs off this call rather than hard-coding either, and expect min_prompt_rows to differ between models too.

Returns

dict

A models list, one entry per model.

Examples

models = client.fm.models()["models"]

for m in models:
    markets = {(d["provider"], d["exchange"]) for d in m["supported_data"]}
    print(f"{m['model_id']} v{m['version']}")
    print(f"  markets: {markets or 'any'}")
    print(f"  prompt rows: {m['min_prompt_rows']}")
    print(f"  args: {sorted(m['model_args'])}")

flob-adaln-rf-1s-lse v1.0.6
  markets: {('bmll', 'lse')}
  prompt rows: 2048
  args: ['guidance', 'historical_conditions', 'impact_coefficient', 'impact_model', 'impact_seconds', 'method', 'num_steps']
flob-adaln-rf-1s v1.0.14
  markets: {('bmll', 'hkex_securities')}
  prompt rows: 2048
  args: ['guidance', 'historical_conditions', 'impact_coefficient', 'impact_model', 'impact_seconds', 'method', 'num_steps']

A foundation model is prompted with real market data rather than calibrated parameters, so this reads the raw vendor registry rather than the calibrated catalog that calibrated_data() serves.

Parameters

model_id : str, optional

Restrict to the markets this model accepts. Takes the model_id or the production_name, matched the same way as in models(). An ambiguous name is a 400 and an unknown one a 404.

symbol : str, optional

Exact symbol, e.g. "700".

q : str, optional

Case-insensitive substring match over the symbol.

provider : str, optional

Data provider, e.g. "bmll".

exchange : str, optional

Exchange protocol, e.g. "lse" or "hkex_securities".

date : str, optional

Trading date "YYYY-MM-DD". Keeps only symbols with data on it, and narrows each entry's dates to it.

limit : int, default None

Maximum symbols to return, 1–200. None uses the server default of 50.

offset : int, default None

Symbols to skip, for paging alongside limit. None uses the server default of 0.

Returns

dict

Notes

Examples

# Pick a model, then a market it will accept
models = client.fm.models()["models"]
model = models[0]

data = client.data.available_data(model_id=model["model_id"], limit=5)
print(f"{data['total']} symbol-days behind this filter")
for entry in data["symbols"]:
    print(f"  {entry['symbol']} @ {entry['provider']}/{entry['exchange']}")
    print(f"    {entry['dates'][:3]}")

{
  "total": 27306,
  "limit": 2,
  "offset": 0,
  "symbols": [
    {
      "symbol": "700",
      "provider": "bmll",
      "exchange": "hkex_securities",
      "dates": ["2025-09-01", "2025-09-02", "2025-09-03"]
    }
  ]
}

You name a market, not a prompt — the platform builds the prompt itself by slicing min_prompt_rows of real data for that symbol and date.

Parameters

model_id : str

A model from models(): its model_id or its production_name, e.g. "flow-hkex-1-100M".

symbol : str, optional

Instrument to prompt from, e.g. "700".

cal_date : str, optional

Trading day "YYYY-MM-DD" whose opening rows become the prompt.

provider : str, optional

Data provider. Must be a market the model's supported_data allows.

exchange : str, optional

Exchange protocol, e.g. "hkex_securities".

duration_minutes : float, optional

Market time to generate, as wall-clock minutes from the first context row. Preferred over horizon: a duration is measured in market time, so an illiquid symbol simply produces fewer frames for the same request, where a raw frame count means something different on every instrument. The frame count that resulted is reported in the output rather than requested up front.

horizon : int, optional

Raw frame count to generate. The older form — applies only when duration_minutes is unset.

n_runs : int, default None

Monte Carlo runs, 1–8. None uses the server default of 1 for a foundation-model run. Per-run seeds derive from seed exactly as the ABM derives them. The cap is 8 because an FM job's worst case must fit on one GPU.

seed : int, default 42

Master random seed.

device : {"cpu", "gpu"}, optional

None uses the model's own default.

model_args : dict, optional

Overrides for the model's declared knobs. Unknown or out-of-range keys are a 400, not a silent ignore.

exec_algos : list of dict, optional

Execution algorithms, same config shape as simulation.run(). At most one per job, and it needs a real market day.

Returns

dict

Notes

Examples

job = client.simulation.run(
    engine="fm",
    model_id="flob-adaln-rf-1s",  # or its production name, "flow-hkex-1-100M"
    symbol="700",
    cal_date="2025-09-02",
    provider="bmll",
    exchange="hkex_securities",
    duration_minutes=5,
    n_runs=2,
    seed=42,
    model_args={"num_steps": 20},
)

print(job["job_id"], job["engine"], job["n_runs"])
print(job["sim_ids"])

curl -X POST https://pulse-api.simudyne.com/simulation/run \
  -H "X-API-Key: $SIMUDYNE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "engine": "fm",
    "model_id": "flow-hkex-1-100M",
    "symbol": "700",
    "cal_date": "2025-09-02",
    "provider": "bmll",
    "exchange": "hkex_securities",
    "duration_minutes": 30,
    "n_runs": 4,
    "seed": 42,
    "model_args": {"num_steps": 20}
  }'

Owner-only, and Pro like the rest of the jobs routes — as is simulation.get_job_logs(job_id), which returns the log as a plain str and is what to read when a run fails. This is the same get_job_status() as for an agent-based job, so the response also carries engine ("fm" here), total_simulations, status_summary, is_complete, has_errors and simulations, as documented there. For an FM job, the GPU scheduler's status, message and detail are merged in on top.

Parameters

job_id : str

A job handle from run().

Returns

dict

Notes

Examples

import time

# No market named: the model runs on the test day baked into its image.
job_id = client.simulation.run(
    engine="fm", model_id="flob-adaln-rf-1s", duration_minutes=5,
)["job_id"]

while True:
    status = client.simulation.get_job_status(job_id)
    # status / message / detail are the inference pod's own state, e.g.
    # waiting for a GPU; they are absent until the orchestrator reports.
    print(f"{status.get('status', 'queued')}: {status.get('message', '')}")
    if status.get("detail"):
        print(f"  {status['detail']}")
    if status["is_complete"]:
        break
    time.sleep(30)

if status["has_errors"]:
    print(client.simulation.get_job_logs(job_id))

curl -H "X-API-Key: $SIMUDYNE_API_KEY" \
  https://pulse-api.simudyne.com/simulation/jobs/$JOB_ID/status

curl -H "X-API-Key: $SIMUDYNE_API_KEY" \
  https://pulse-api.simudyne.com/simulation/jobs/$JOB_ID/logs

{
  "job_id": "1f3c9a2e",
  "engine": "fm",
  "total_simulations": 4,
  "status_summary": {"queued": 4},
  "is_complete": false,
  "has_errors": false,
  "simulations": [...],
  "status": "provisioning",
  "message": "Finding GPUs…",
  "detail": "0/29 nodes are available: Insufficient nvidia.com/gpu"
}

Takes the same model and generation fields as run(), but streams frames to a live chart rather than writing output files.

Parameters

model_id : str

A model from models().

horizon : int, optional

Frames to generate before the session ends.

seed : int, default 42

Master random seed.

model_args : dict, optional

Overrides for the model's declared knobs.

Returns

dict