# How It Works (/scripting-v2/notebook/how-it-works)



## The `mlab` object [#the-mlab-object]

Market Lab does not publish or install a Python package for notebook support.

When `mlab notebook` starts, the CLI:

1. Creates a temporary Jupyter kernel definition for the selected Python interpreter.
2. Loads a private IPython extension when that kernel starts.
3. Places a ready-to-use `mlab` object in the notebook namespace.
4. Opens a permission-restricted local socket between the kernel and the running CLI.

Calls such as `mlab.history(...)`, `history.source(...)`, and `mlab.study.sma(...)` cross that local bridge. Rust fetches and normalizes historical data and runs native studies. The notebook receives ordinary Python dictionaries and lists.

## Session lifecycle [#session-lifecycle]

The bridge uses a random token and exists only while the `mlab notebook` command is running. Market Lab removes the temporary kernel, extension, token, and socket files when the session closes.

The bridge does not expose a network or daemon port. Jupyter itself continues to manage browser access to the notebook server.

Stop JupyterLab or press `Ctrl+C` in the terminal that started it to close the complete research session.

## Lazy source cache [#lazy-source-cache]

`mlab.history(start=..., end=...)` creates a historical context but does not fetch data.

The first `history.source(selector)` call asks Rust to load the exact selector for that range. The normalized records are returned in chunks and cached in the Python kernel. Repeated calls return the cached records until `history.clear(...)` is used.

The cache belongs to that history object and is not persisted to disk.

## No `ctx` in research mode [#no-ctx-in-research-mode]

Notebook mode intentionally has no `ctx` object. `ctx` belongs to plain Python strategy files, where Market Lab owns a sequential event clock, simulator or live execution, positions, PnL, and artifacts.

A notebook receives the complete historical range it requests. This is useful for exploration and feature engineering, but it does not prevent look-ahead bias.

Notebook research currently does not provide:

* `ctx.trade`, `ctx.order`, or live execution
* positions or PnL state
* callbacks such as `on_data`
* simulator-backed notebook backtests
* remote notebook sessions over SSH transport

Use [Plain Python Files](/scripting-v2/getting-started) and `mlab script backtest` when logic must be evaluated one event at a time. Use `mlab script run` when that strategy is ready for live deployment.