[Runtime modes]

interpret / compile / auto defaults differ by surface. Library interpret, POST /run auto, pyne run compile-only. PyneTS 0.2.0 has interpret + JS compile.

Runtime modes

Abstract

mode selects how the bar loop executes: interpret (AST walk), compile (transpiled loop), or auto (try compile, fall back to interpret). The default is not the same on every surface. This is the most common footgun when moving a script from the library to the Pro API or between Python and PyneTS.

There is no Runtime.evaluate.

Conceptual model

Interface surface

What each mode means

Mode	Python	PyneTS (this checkout)
`interpret`	AST walker. Full host: `input.`, `request.`, libraries, profiler, alerts	AST walker only (`pynets/src/runtime/interpret.ts`). Result `mode` is always `"interpret"`
`compile`	Numba nopython or object-mode Python loop	Not implemented — no `src/runtime/compile/` in this tree
`auto`	Try compile; on ineligibility / compile error / compiled runtime error → interpret	Not implemented

Defaults by surface

Surface	Default `mode`	Calls `Runtime.run`?
`pynescript.runtime.Runtime.run(..., mode=None)`	`PYNE_RUNTIME_MODE` else `interpret`	yes
Pro API `POST /run` body omits `mode`	schema `auto`	yes (host wrap)
`?mode=` query (legacy)	overrides body	yes
CLI `pyne run`	compile only — not `Runtime.run`	no
`new Runtime()` / `pynets run`	interpret only (no `--mode`; `--bars` default 20)	yes
AXIS engine `server`	whatever you pass; UI default often `auto`	HTTP `/run`
AXIS engine `pyodide`	object-mode in Wasm (no Numba)	in-browser Python

`Runtime.run` (Python, exact)

Runtime(symbol="AAPL").run(
    source_code,
    ohlcv_data,
    data_feed=None,
    data_provider=None,
    mode=None,            # env PYNE_RUNTIME_MODE else "interpret"
    inputs=None,
    profiler=False,
    timeout_seconds=None,
    libraries=None,
    realtime_last_bar=False,
    realtime_ticks=1,
    realtime_bars=0,
    realtime_from_bar=None,
)

Argument	Surfaces	Effect on `mode`
`mode`	library / `POST /run`	See defaults table. `pyne run` has no `--mode`.
`inputs`	library / `POST /run`	Non-empty overrides force interpret (compile does not apply them).
`libraries`	library / `POST /run` / `POST /run/batch` (max 32)	`[{namespace, name, version, source}]` for `import ns/Name/ver`. Compile-ineligible; `auto` keeps the list on interpret fallback. Not on `pyne run`.
`timeout_seconds`	library / `POST /run` / `POST /run/batch`	Interpret wall-clock budget. Exceeded → partial plots + `timed_out`. Omit / `null` / `≤ 0` → no timeout. Not on `pyne run`.
`profiler`	library / `POST /run`	Forces interpret (line timings).
`realtime_*`	library only	Interpret forming-bar window (`realtime_last_bar`, `realtime_ticks`, `realtime_bars`, `realtime_from_bar`).

inputs / profiler / libraries / timeout_seconds / realtime_* force or keep the interpret host (or force interpret after compile miss).

`Runtime.run` (PyneTS)

new Runtime(symbol, { inputs, broker, timeframe })
  .run(source, ohlcv, extra?)

There is no constructor/extra.mode and no libraries option on this host. RuntimeResult.mode is always "interpret".

Internals

Surface	Implementation
Python library	`src/pynescript/runtime/host.py`
Python CLI `run`	`src/pynescript/__main__.py` → `compile_script` + synthetic bars
Pro API	`backend/app.py` `RUN_SCHEMA` default `auto`
PyneTS	`pynets/` v0.2.0 — interpret + JS compile (`mode` `interpret` / `compile` / `auto`). Python remains the oracle
PyneTS CLI	`pynets/src/cli.ts` → `new Runtime("AAPL", { broker }).run`

Invariants & edge cases

Do not document pyne run as mode=auto. It is compile-only smoke (--bars default 50).
Do not document pynets run as Python pyne run. PyneTS Runtime.run defaults to interpret; 0.2.0 also has JS compile / auto. Default --bars is 20 (Python pyne run defaults to 50).
result.mode is what executed. After auto, also read auto_backend and compile_fallback_reason.
Foreign request.security is na on every host. Compile does not invent bars to become "more complete".
AXIS Pyodide compile / auto cannot be Numba (Wasm).

Worked examples

Force interpret everywhere you care about input.* + libraries + alerts:

Runtime(symbol="AAPL").run(src, bars, mode="interpret", inputs={"len": 14})

new Runtime("AAPL", { inputs: { len: 14 } }).run(src, bars);

# Python desk smoke (compile only)
pyne run script.pine --bars 50

# PyneTS desk smoke (Runtime.run; default interpret, --bars 20)
pynets run script.pine --bars 50

Failure modes

Symptom	Cause	Fix
Pro API "misses" an input	`auto` compiled a path that drops overrides	Pass `mode: "interpret"`
`pyne run` ≠ notebook `Runtime.run`	Different host	Use the library or Pro API
Expect PyneTS ≡ Python compile	JS emit is object-mode analog, not Numba	Treat Python Runtime as the oracle
`mode` omitted, two hosts disagree	Different defaults	Set `mode` explicitly