Python Notebooks

What Python Notebooks are for

Notebooks gives you a flexible Python workspace beside Arizmic's structured Data, Signal, Strategy, Study, Result, Portfolio, and Live workflows. Use it when you need to inspect a question interactively, build a custom chart or table, compare retained outputs, or calculate something that does not belong in a permanent workstation feature.

A Notebook can help you:

• inspect Dataset and Prepared Data metadata, coverage, and bounded samples;
• examine one Run Output or Study Result in more detail;
• compare parameters, trials, trades, and validation findings;
• create custom charts, tables, controls, and written reports;
• combine several read-only views into one investigation;
• calculate additional statistics with the formula and assumptions visible;
• submit an approved, bounded research Job where the Notebook SDK permits it; and
• preserve a reusable investigation as normal Python source.

Notebooks complement the main workstation. They do not replace Results as the authority for engine-reported values, the libraries as the authority for saved objects, or Live as the authority for trading operations.

Why Arizmic uses Marimo

Arizmic uses Marimo rather than Jupyter as its native Notebook environment. Jupyter remains an important part of the Python ecosystem, but Marimo better matches the way Arizmic needs local investigations to behave.

The source is ordinary Python

Every Marimo Notebook is stored as a .py file. You can read it in a text editor, compare revisions cleanly, run normal source-control reviews, execute it with Python, or open it with standard Marimo tools outside Arizmic.

A Jupyter .ipynb file is a JSON document containing cells, metadata, and potentially rich outputs. That format is portable across Jupyter tools, but it is less direct to review as source. Arizmic's plain-Python project format fits its local, inspectable, operator-controlled model more naturally.

Cells follow their dependencies

Marimo builds a dependency graph from the variables used by each cell. When an input changes, dependent cells rerun or become visibly stale. Deleting a cell also removes the variables it defined from the program state.

This reduces the hidden-state problem in which displayed outputs no longer match the code that appears above them. It is particularly useful when a chart, table, or conclusion depends on a selected Run, parameter, date window, or fidelity setting.

For expensive reads, use a deliberate Run control or lazy execution so a minor presentation change does not repeat a large request.

Interactive controls are part of the program

Marimo controls such as sliders, dropdowns, tables, and date selectors bind directly to Python values. Cells that use those values update through the same dependency graph. This makes it practical to build a focused investigation without adding a separate application layer.

The same file can become a report or small app

A Notebook can be edited interactively, executed as Python, or rendered through supported Marimo modes. Arizmic adds its own project, environment, provenance, and export rules around that file, but the underlying source remains useful outside the workstation.

This choice is not a claim that Marimo is universally better than Jupyter. Arizmic selected it because plain Python, dependency-aware execution, and native interactive controls fit reproducible local investigations especially well.

Bring an existing Jupyter Notebook

V1 does not include an in-app migration engine. To reuse a .ipynb file, review it first and use Marimo's supported conversion command outside Arizmic:

marimo convert existing-notebook.ipynb > converted-notebook.py

Open the converted .py file with standard Marimo, resolve conversion notes, remove embedded secrets and unsupported dependencies, then import or copy the reviewed source into your selected Arizmic Notebook workspace. Treat converted code as imported local code and complete the normal trust acknowledgement before launch.

Work with projects

Open Notebooks from the primary navigation. The intended workspace shows:

• the selected Notebook workspace and environment health;
• a searchable project library;
• each project's source, origin, template version, context, trust state, and last session;
• actions to create a blank project or start from a template;
• open, rename, duplicate, archive, reveal, export, and deletion controls; and
• the foreground Marimo editor with session and diagnostic state.

The workspace root is a folder you choose. Arizmic validates it and keeps every managed project as a relative .py path inside it. It does not infer a root from the application checkout or search the rest of your computer.

Creating a project from a template makes your own copy. Updating a built-in template never overwrites a project you have edited; it offers a new copy or a reviewable comparison.

Understand the environment

Each configured Notebook workspace has an environment separate from the Arizmic application and from other Notebook workspaces. A workspace manifest, requirements, and dependency lock describe what it needs. Shared immutable download caches may avoid duplicate downloads, but installed packages and mutable project state do not merge across workspaces.

Before launching a project, check that the environment is Ready. If it is missing, blocked, or out of date, inspect the proposed dependency changes and use the explicit sync or recreate action. Environment work must not alter the Python environment that runs Arizmic itself.

Notebook code is trusted local operator code. Environment and process isolation protect application ownership and reproducibility; they are not a hostile-code sandbox. Review imported packages and source before running them.

Bind Arizmic context

Create a project from Notebooks or choose Open in Notebook from a supported Data, Prepared Data, Study, or Result surface. A cross-surface action only prefills the project and context choice; it does not create a file, change the environment, or launch code without confirmation.

Context can refer to an exact Dataset, Prepared Data version, Strategy, Portfolio, Study, Study Result, or Run Output. Arizmic revalidates its identity, availability, and supported kind before project creation and again before launch. A missing or retired object remains visibly unresolved instead of being replaced by a similarly named record.

Use the Research SDK

Notebook code uses the read-oriented arizmic.notebooks Python SDK. It provides typed, bounded access to supported workstation objects without asking you to construct private URLs or read Arizmic's storage directly.

The SDK can expose supported views of:

• Dataset and Prepared Data identity, schema, lineage, readiness, and bounded details;
• Strategy and Portfolio metadata and version lineage;
• Study definitions, status, trials, candidates, and supported surfaces;
• Run Output performance, parameters, trades, chart windows, diagnostics, and retained artifact references; and
• a closed list of estimated, cancellable Notebook-safe research Jobs.

Large collections require a page, cursor, limit, or time window. SDK responses identify provenance, truncation, continuation, and value origin. A helper must not silently load every row, event, trade, trial, bar, or artifact.

The SDK cannot read provider or broker credentials, send Live commands, mutate canonical Data, save Signals or Strategies, access arbitrary HTTP endpoints, or bypass the workflow that owns an object.

Separate reported and calculated values

Values read from Results retain the label engine-reported. If you calculate a new statistic inside the Notebook, label it notebook-derived and keep its formula, inputs, assumptions, and sample window visible.

A Notebook calculation can inform your next decision, but it does not silently become an Arizmic Result or upgrade a validation status. If it should become a supported metric, implement and validate it through the owning product workflow.

Build controls, charts, and reports

Organize a practical Notebook into a small number of stages:

1. identify the exact context and versions;
2. choose committed controls such as date range, page, trial, or instrument;
3. make one bounded SDK request;
4. validate the response and display its truncation or missing state;
5. perform clearly labeled local calculations; and
6. render a table, chart, explanation, or report section.

Charts should state the selected object, time window, sampling, units, and value origin. Tables should distinguish server-side paging from local sorting or filtering. Missing data stays missing; it must not be converted to zero or a passing state.

Save, export, and recover

Marimo saves the project source as a .py file. Stopping a Notebook session ends the managed editor process; it does not delete the file. Confirm the file is saved before stopping or changing environments.

Supported exports may include static HTML, a supported session snapshot, and a source-and-provenance bundle. An export records the project, template, context, environment lock, SDK and Marimo versions, truncation, and value origins. It must not include session tokens or credentials, and it does not register a new Result.

After an application restart, an interrupted session is reconciled and can be relaunched with a fresh local token. If launch fails, review the named phase, safe log tail, environment state, port state, and remediation rather than creating duplicate project files or processes.

Important boundaries

• Notebook code can consume bounded research data; it cannot operate Live.
• A local project may execute any Python you approve, so imported code and dependencies require review.
• Engine values remain owned by Results and Studies.
• Derived values remain Notebook calculations until implemented elsewhere.
• Changing pages does not discard a managed project, but unsaved editor state still requires the normal Marimo acknowledgement.
• Remote kernels, cloud sync, collaboration, scheduling, and multi-user code execution are outside V1.

Next

Start with Notebook Templates for the launch library, or use AI in Notebooks to draft and review code through the Arizmic AI permission system.