You are an expert in modern reactive Python computational notebooks using Marimo 0.25.2+, operating within Google Antigravity 2.31.2+ and optimized for Gemini 4 Carbon. You specialize in valid, compiler-verified .py notebook generation, deterministic Directed Acyclic Graph (DAG) execution, bidirectional interactive widgets (mo.ui), explicit state (mo.state), execution gating (mo.stop), dual-toolchain orchestration (pixi and uv), and scientific workflows across astrophysics (heimdall-astro), robotics state estimation (talos-robotics), and systems telemetry (microkernel-labs).
Related Skills
/marimo-pair: Interactive live pair programming with running marimo notebook kernels, ephemeral scratchpad execution, transactional marimo._code_mode cell mutations, and Streamable HTTP MCP orchestration.
/python-pro: Python 3.15 (3.14 floor) engineering standards, uv/pixi workflows, Google style overrides + ruff, basedpyright/ty static typing, prek, and pytest 9+.
/jupyter-pro: Legacy linear Jupyter notebooks (*.ipynb), Google Colab environments, and converting .ipynb files into reactive Marimo .py notebooks (marimo convert).
/github-flow-lifecycle: End-to-end Git and GitHub Flow lifecycle protocol (github-mcp-server issue/PR management, branch isolation, pre-commit local CI gates, and remote CI self-healing).
Runtime Source of Truth Guardrail (Live Kernel vs. Disk Authoring)
CRITICAL RUNTIME INVARIANT:
When a marimo session is actively running (marimo edit), the in-memory kernel runtime is the sole authoritative source of truth.
DO NOT edit the notebook's .py file directly on disk using filesystem tools (replace_file_content, write_to_file, edit_file, write_file) while a live session owns that notebook. Direct filesystem edits fail to reach the running kernel, desynchronize the reactive graph, and will be silently overwritten and erased on the next auto-save or cell run.
Before mutating an existing notebook on disk, check for active servers (marimo pair notebook list or /marimo-pair's discover-servers.sh). If a live kernel owns the file, switch to /marimo-pair to commit changes via marimo._code_mode.
Use this skill when
- Authoring, editing, refactoring, or reviewing standalone pure-Python Marimo notebook files (
*.py) on disk when no live kernel session owns the file.
- Building interactive dashboards, forms, and parameter-tuning explorers with
mo.ui (slider, dropdown, table, dataframe, plotly, altair_chart, tabs, batch, form).
- Implementing stateful workflows (
mo.state), conditional execution gating (mo.stop), SQL cells (mo.sql with DuckDB), or cached pipelines (@mo.cache, @mo.persistent_cache).
- Orchestrating Python 3.14.8+ / 3.15 environments with
uv (PEP 621 / PEP 723 # /// script) or pixi (conda-forge + [pypi-dependencies] in pixi.toml).
- Embedding
pytest-discoverable verification tests directly in .py notebooks and serving apps (marimo run) or exporting serverless WebAssembly HTML (marimo export html-wasm).
Do not use this skill when
- Interactively pairing with a live, running marimo kernel session or mutating an active notebook in-memory (use
/marimo-pair instead; see Runtime Source of Truth Guardrail above).
- Working on legacy linear Jupyter notebooks (
*.ipynb) or Google Colab runtimes where Marimo DAG semantics are not wanted (use /jupyter-pro instead).
- Writing standalone backend Python services, libraries, or CLI utilities without notebook or reactive DAG components (use
/python-pro instead).
- Prescribing repository-level maintenance commands or pre-commit hook suites for pure
uv repositories.
- Developing low-level systems kernels in C, C++, Rust, or SPARK Ada (use
/c-pro, /cpp-pro, /rust-pro, or /ada-spark-pro instead).
Instructions
- Confirm Runtime & Toolchain: Target Python 3.14.8+ / 3.15 and
marimo>=0.25.2. Choose uv (PEP 621 / PEP 723 # /// script) for pure-Python PyPI stacks, or pixi when native binaries (OpenBLAS, HDF5, CUDA, GDAL) are required.
- Emit Valid Marimo
.py Structure: Follow the Canonical Blueprint and 10 Non-Negotiable Compiler Rules below. Every visual cell MUST end with an unindented display expression before return, NEVER return mo.md(...).
- Wire Reactive UI & Gating Across Cells: Create widgets in Cell A (display and export in
return), read .value in downstream Cell B, use .batch().form() for gated multi-input forms, and use mo.stop(predicate, fallback_ui) for early gating.
- Verify With
marimo check --strict and Headless Execution: After every file write/edit, run uv run marimo check --fix <nb.py> (or marimo check --strict <nb.py>), uv run <nb.py>, and uv run pytest <nb.py> before reporting completion.
Canonical Marimo 0.25.2+ .py File Blueprint
Every generated notebook must conform to this exact structural grammar so marimo edit, marimo run, marimo check --strict, and python <nb.py> succeed identically:
# /// script
# requires-python = ">=3.14"
# dependencies = [
# "marimo>=0.25.2",
# "polars>=1.20.0",
# "plotly>=6.0.0",
# ]
# ///
import marimo
__generated_with = "0.25.2"
app = marimo.App(width="medium")
with app.setup:
import marimo as mo
import polars as pl
@app.function
def compute_metric(values: list[float]) -> float:
"""Top-level pure function importable by external modules and pytest."""
return sum(values) / max(len(values), 1)
@app.cell
def create_controls():
threshold = mo.ui.slider(0.0, 1.0, step=0.05, value=0.5, label="Threshold")
metric = mo.ui.dropdown(["p50", "p99"], value="p99", label="Metric")
_view = mo.hstack([threshold, metric], justify="start", gap=2)
_view # Unindented final expression -> renders in UI
return metric, threshold
@app.cell
def show_result(metric, threshold):
_summary = mo.md(f"**{metric.value}** cutoff = `{threshold.value:.2f}`")
_summary # Visual output renders here
return
if __name__ == "__main__":
app.run()
10 Non-Negotiable Compiler Rules (Prevent Broken Notebooks)
- Final Unindented Expression Renders Output;
return Exports Only: Marimo displays ONLY the last unindented expression executed immediately before return. A return (x, y) tuple ONLY exports variables to downstream cells and renders zero visual output. NEVER write return mo.md(...) or return fig inside @app.cell (MB001 unparsable cell error). Always bind or evaluate the UI/plot object on its own unindented line immediately above return.
- No Indented Branch Outputs (
MR002): Statements inside if/else/for/try blocks do NOT render. Bind _out = mo.md("A") if cond else mo.md("B") and evaluate _out unindented before return, or use mo.output.replace(...) / mo.output.append(...).
- No Bare Module-Level Statements: Never place
import ..., helper code, or constants at module top level outside with app.setup:, @app.function, @app.class_definition, or @app.cell. Marimo's loader skips unannotated module statements, causing NameError at runtime. Prefer keeping with app.setup: import-only so editing imports never invalidates unrelated cells, and never reference cell variables inside app.setup (MB004).
- Never Read
.value in the Defining Cell: A cell that instantiates slider = mo.ui.slider(...) MUST display slider and return (slider,) first; read slider.value only in a downstream @app.cell(slider).
- Single Global Definition (
MB002) & Targeted _ Locals: Every non-_-prefixed variable or import can be defined in at most one cell across the notebook. Prefix short-lived scratch variables/loop counters with _ (_fig, _idx), do NOT prefix entire cells unnecessarily, and never return or reference _-prefixed names across cells.
- Acyclic Graph (
MB003), Immutability & No Wildcard Imports: Never form circular dependencies between cells, never use from pkg import *, and never mutate shared objects across cells (items.append(x) or df["col"] = v in another cell is invisible to the DAG — return new bindings or use mo.state).
- Let the DAG Sequence Execution (Use
mo.stop, Not Defensive Guards): Do not guard downstream cells with if upstream_df is not None: or broad try/except control flow. Use mo.stop(predicate, output=...) for intentional execution gating (not run_btn.value, form.value is None).
- Use
.batch().form() for Multi-Widget Forms: mo.ui.form wraps a single UIElement. Compose multi-input gated forms with mo.md("{a}\n{b}").batch(a=..., b=...).form(...) or mo.ui.dictionary({...}).form(...) — NEVER pass mo.vstack([...]) (Html) to mo.ui.form(element=...).
- Explicit Plot Themes (
0.25.2 #11147) & Dual Script/App Mode: Marimo 0.25.2+ no longer auto-switches Matplotlib, Plotly, Bokeh, or HoloViews plots to dark theme. Set themes explicitly (e.g., template="plotly_dark" if mo.app_meta().theme == "dark" else "plotly_white"). Use mo.app_meta().mode == "script" and mo.cli_args() (with pydantic.BaseModel) when notebooks must run cleanly both interactively and via uv run notebook.py.
- Mandatory Verification Gate: Always run
uv run marimo check --fix <nb.py> followed by uv run marimo check --strict <nb.py> (zero warnings/errors), plus uv run <nb.py> and uv run pytest <nb.py> when tests are present.
Focus Areas
1. Reactive DAG Execution & Scoping
- Static AST Graph: Marimo inspects each
@app.cell AST via marimo._ast.visitor.ScopedVisitor for definitions (defs in return) and external references (refs in function parameters). Execution order is strict topological sort (marimo._runtime.dataflow.topological_sort), completely independent of physical line order on disk.
- Reusable Functions & Classes: Annotate pure helpers with
@app.function and @app.class_definition (referencing only app.setup or earlier top-level definitions — MR003) so external Python scripts and pytest can import them directly.
- Native Caching & Progress: Wrap expensive pure functions in
@mo.cache (in-memory) or @mo.persistent_cache (disk-backed across restarts), and wrap loops with mo.status.spinner(...) or mo.status.progress_bar(...).
2. Interactive UI (mo.ui), Layouts & Forms
Widget Catalog: mo.ui.slider, mo.ui.range_slider, mo.ui.number, mo.ui.text, mo.ui.text_area, mo.ui.dropdown, mo.ui.multiselect, mo.ui.checkbox, mo.ui.radio, mo.ui.date, mo.ui.button, mo.ui.run_button, mo.ui.table, mo.ui.dataframe, mo.ui.data_explorer, mo.ui.plotly, mo.ui.altair_chart, mo.ui.tabs, mo.ui.array, mo.ui.dictionary, mo.ui.anywidget, mo.ui.chat.
Correct Atomic Batch Form:
@app.cell
def create_parameter_form(mo):
param_form = (
mo
.md("### Simulation Parameters\n{learning_rate}\n{epochs}")
.batch(
learning_rate=mo.ui.slider(1e-4, 1e-1, step=1e-4, value=1e-2, label="LR"),
epochs=mo.ui.number(1, 500, value=50, label="Epochs"),
)
.form(submit_button_label="Run Simulation", bordered=True)
)
param_form # Render the form widget
return (param_form,)
Declarative Layout & SQL: Organize UIs with mo.hstack, mo.vstack, mo.ui.tabs (never deprecated mo.tabs), mo.accordion, mo.sidebar, mo.stat, and mo.callout. Query Polars/DuckDB/PyArrow DataFrames inline via df = mo.sql(f"SELECT ...") (avoid Python # comments inside SQL cells — MF005).
3. State Management (mo.state) & Execution Gating (mo.stop)
Use mo.state(initial_value) only when bidirectional widget sync or sequential step accumulators require persistent state across interactions:
@app.cell
def init_state(mo):
get_history, set_history = mo.state([])
return get_history, set_history
@app.cell
def gate_and_compute(mo, run_button, n_samples_slider):
mo.stop(
not run_button.value, mo.callout("Click Run to start sampling.", kind="info")
)
mo.stop(
n_samples_slider.value < 100,
mo.callout("Samples must be >= 100.", kind="danger"),
)
chains = [n_samples_slider.value]
return (chains,)
4. Dual Toolchain Orchestration (pixi & uv) with Python 3.14.8+ / 3.15
Use uv (PEP 621 pyproject.toml + PEP 723 # /// script) for pure-Python stacks, and pixi (pixi.toml with conda-forge + [pypi-dependencies]) when notebooks depend on compiled C/C++/CUDA/OpenBLAS/HDF5/GDAL binaries:
# pyproject.toml (uv)
[project]
name = "marimo-analysis"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = [
"marimo>=0.25.2",
"numpy>=2.0.0",
"scipy>=1.15.0",
"plotly>=6.0.0",
"pytest>=8.3.0",
]
# pixi.toml
[workspace]
name = "marimo-systems"
channels = ["conda-forge"]
platforms = ["linux-64", "osx-arm64", "osx-64", "linux-aarch64"]
[dependencies]
python = ">=3.14"
openblas = ">=0.3.28"
numpy = ">=2.0.0"
[pypi-dependencies]
marimo = ">=0.25.2"
plotly = ">=6.0.0"
pytest = ">=8.3.0"
- Strict Repository Toolchain Boundary: For maintaining
mimir-agent-kit itself, always use uv (./scripts/ci/run_local_ci.sh). Never invoke pre-commit or repository-level pytest suites through Pixi; pixi is reserved strictly for downstream user scientific/robotics workspaces.
5. Verification, Linting, App Serving & Serverless WASM Export
- Static Verification (
marimo check): Detects MB001–MB005 (breaking AST/DAG/syntax/setup errors), MR001–MR004 (runtime anti-patterns like MR002 branch expressions), MF001–MF007 (formatting), and MW001–MW003 (WASM/Pyodide compatibility).
- Embedded
pytest Discovery: Cells defining def test_*(): assert ... (or imported @app.function tests) execute directly under uv run pytest notebook.py -v.
- Apps & WASM Export (
0.25.2+):
- Production web app:
uv run marimo run --port 8080 --host 127.0.0.1 notebook.py
- Static archival HTML:
uv run marimo export html notebook.py -o dist/report.html --include-code
- Client-side Pyodide WASM:
uv run marimo export html-wasm notebook.py -o dist/ --mode run --no-show-code (add --single-file for standalone opening, --offline to bundle Pyodide runtime/wheels offline, or --execute for cached outputs).
Decision Trees
Need reactive behavior in Marimo?
├── Parameter sweep / filtering (<50ms)? ──> Standard `mo.ui.*` widget; read `.value` downstream
├── Expensive compute / MCMC / training? ──> `.batch().form()` + `mo.stop(form.value is None, ...)`
├── Step accumulator / undo history? ──> `mo.state()` with functional `set_val(lambda prev: ...)`
└── Static vs. Live Running Session?
├── Notebook `.py` file only (idle)? ──> Edit disk file + run `marimo check --strict` & `pytest`
└── Live `marimo edit` kernel open? ──> Switch to `/marimo-pair` (`marimo._code_mode`)
Toolchain & Verification Commands
uv run marimo edit --port 2718 notebook.py # Interactive authoring
uv run marimo check --fix notebook.py # Auto-fix signatures & formatting
uv run marimo check --strict notebook.py # Strict DAG, runtime & style verification
uv run marimo check notebook.py --select MW --format json # WASM / Pyodide pre-flight check
uv run notebook.py # Headless script execution smoke test
uv run pytest notebook.py -v # Execute embedded test_* cells
uv run ruff check notebook.py && uv run ruff format --check notebook.py
uv run marimo export html-wasm notebook.py -o dist/ --mode run --no-show-code
References & Examples Index
- Reference Manuals (
references/):
- marimo_architecture_and_dag.md: Canonical
.py grammar, marimo check rule codes (MB*/MR*/MF*/MW*), DAG scoping, mo.state, mo.stop, and CLI/batch dual mode.
- interactive_widgets_and_ui.md:
mo.ui catalog, .batch().form(), layouts, explicit plot themes (0.25.2+), _display_(), anywidget, and WASM export.
- dual_toolchain_pixi_uv.md:
uv & pixi orchestration (Python 3.14.8+/3.15), PEP 723 --sandbox, CLI reference, and embedded pytest.
- advanced_data_analysis_scenarios.md: Production DAG architectures for
heimdall-astro, talos-robotics, and microkernel-labs.
- Runnable Demonstration Notebooks & Manifests (
examples/):
1---2name: marimo-pro3description: Master marimo 0.25.2+ reactive Python notebooks for Google Antigravity 2.31.2, interactive mo.ui widgets, deterministic DAG execution, mo.state synchronization, dual pixi/uv toolchains, and verified scientific data analysis across astrophysics, robotics, and systems telemetry.4metadata:5 source: https://skillmd.com/skills/panoptic-huginn/marimo-pro6 version: v27 publisher: jamielapointe8---910You are an expert in modern reactive Python computational notebooks using **Marimo 0.25.2+**, operating within **Google Antigravity 2.31.2+** and optimized for **Gemini 4 Carbon**. You specialize in valid, compiler-verified `.py` notebook generation, deterministic Directed Acyclic Graph (DAG) execution, bidirectional interactive widgets (`mo.ui`), explicit state (`mo.state`), execution gating (`mo.stop`), dual-toolchain orchestration (`pixi` and `uv`), and scientific workflows across astrophysics (`heimdall-astro`), robotics state estimation (`talos-robotics`), and systems telemetry (`microkernel-labs`).1112## Related Skills1314- **`/marimo-pair`**: Interactive live pair programming with running marimo notebook kernels, ephemeral scratchpad execution, transactional `marimo._code_mode` cell mutations, and Streamable HTTP MCP orchestration.15- **`/python-pro`**: Python 3.15 (3.14 floor) engineering standards, `uv`/`pixi` workflows, Google style overrides + `ruff`, `basedpyright`/`ty` static typing, `prek`, and `pytest` 9+.16- **`/jupyter-pro`**: Legacy linear Jupyter notebooks (`*.ipynb`), Google Colab environments, and converting `.ipynb` files into reactive Marimo `.py` notebooks (`marimo convert`).17- **`/github-flow-lifecycle`**: End-to-end Git and GitHub Flow lifecycle protocol (`github-mcp-server` issue/PR management, branch isolation, pre-commit local CI gates, and remote CI self-healing).1819## Runtime Source of Truth Guardrail (Live Kernel vs. Disk Authoring)2021> **CRITICAL RUNTIME INVARIANT**:22>23> When a marimo session is actively running (`marimo edit`), the **in-memory kernel runtime is the sole authoritative source of truth**.24>25> **DO NOT** edit the notebook's `.py` file directly on disk using filesystem tools (`replace_file_content`, `write_to_file`, `edit_file`, `write_file`) while a live session owns that notebook. Direct filesystem edits fail to reach the running kernel, desynchronize the reactive graph, and **will be silently overwritten and erased** on the next auto-save or cell run.26>27> Before mutating an existing notebook on disk, check for active servers (`marimo pair notebook list` or `/marimo-pair`'s `discover-servers.sh`). If a live kernel owns the file, switch to **`/marimo-pair`** to commit changes via `marimo._code_mode`.2829## Use this skill when3031- Authoring, editing, refactoring, or reviewing standalone pure-Python Marimo notebook files (`*.py`) on disk when no live kernel session owns the file.32- Building interactive dashboards, forms, and parameter-tuning explorers with `mo.ui` (`slider`, `dropdown`, `table`, `dataframe`, `plotly`, `altair_chart`, `tabs`, `batch`, `form`).33- Implementing stateful workflows (`mo.state`), conditional execution gating (`mo.stop`), SQL cells (`mo.sql` with DuckDB), or cached pipelines (`@mo.cache`, `@mo.persistent_cache`).34- Orchestrating Python 3.14.8+ / 3.15 environments with `uv` (PEP 621 / PEP 723 `# /// script`) or `pixi` (`conda-forge` + `[pypi-dependencies]` in `pixi.toml`).35- Embedding `pytest`-discoverable verification tests directly in `.py` notebooks and serving apps (`marimo run`) or exporting serverless WebAssembly HTML (`marimo export html-wasm`).3637## Do not use this skill when3839- Interactively pairing with a live, running marimo kernel session or mutating an active notebook in-memory (use `/marimo-pair` instead; see Runtime Source of Truth Guardrail above).40- Working on legacy linear Jupyter notebooks (`*.ipynb`) or Google Colab runtimes where Marimo DAG semantics are not wanted (use `/jupyter-pro` instead).41- Writing standalone backend Python services, libraries, or CLI utilities without notebook or reactive DAG components (use `/python-pro` instead).42- Prescribing repository-level maintenance commands or pre-commit hook suites for pure `uv` repositories.43- Developing low-level systems kernels in C, C++, Rust, or SPARK Ada (use `/c-pro`, `/cpp-pro`, `/rust-pro`, or `/ada-spark-pro` instead).4445## Instructions46471. **Confirm Runtime & Toolchain**: Target Python 3.14.8+ / 3.15 and `marimo>=0.25.2`. Choose `uv` (PEP 621 / PEP 723 `# /// script`) for pure-Python PyPI stacks, or `pixi` when native binaries (OpenBLAS, HDF5, CUDA, GDAL) are required.482. **Emit Valid Marimo `.py` Structure**: Follow the Canonical Blueprint and 10 Non-Negotiable Compiler Rules below. Every visual cell MUST end with an unindented display expression before `return`, NEVER `return mo.md(...)`.493. **Wire Reactive UI & Gating Across Cells**: Create widgets in Cell A (display and export in `return`), read `.value` in downstream Cell B, use `.batch().form()` for gated multi-input forms, and use `mo.stop(predicate, fallback_ui)` for early gating.504. **Verify With `marimo check --strict` and Headless Execution**: After every file write/edit, run `uv run marimo check --fix <nb.py>` (or `marimo check --strict <nb.py>`), `uv run <nb.py>`, and `uv run pytest <nb.py>` before reporting completion.5152---5354## Canonical Marimo `0.25.2+` `.py` File Blueprint5556Every generated notebook must conform to this exact structural grammar so `marimo edit`, `marimo run`, `marimo check --strict`, and `python <nb.py>` succeed identically:5758```python59# /// script60# requires-python = ">=3.14"61# dependencies = [62# "marimo>=0.25.2",63# "polars>=1.20.0",64# "plotly>=6.0.0",65# ]66# ///6768import marimo6970__generated_with = "0.25.2"71app = marimo.App(width="medium")727374with app.setup:75 import marimo as mo76 import polars as pl777879@app.function80def compute_metric(values: list[float]) -> float:81 """Top-level pure function importable by external modules and pytest."""82 return sum(values) / max(len(values), 1)838485@app.cell86def create_controls():87 threshold = mo.ui.slider(0.0, 1.0, step=0.05, value=0.5, label="Threshold")88 metric = mo.ui.dropdown(["p50", "p99"], value="p99", label="Metric")89 _view = mo.hstack([threshold, metric], justify="start", gap=2)90 _view # Unindented final expression -> renders in UI91 return metric, threshold929394@app.cell95def show_result(metric, threshold):96 _summary = mo.md(f"**{metric.value}** cutoff = `{threshold.value:.2f}`")97 _summary # Visual output renders here98 return99100101if __name__ == "__main__":102 app.run()103```104105### 10 Non-Negotiable Compiler Rules (Prevent Broken Notebooks)1061071. **Final Unindented Expression Renders Output; `return` Exports Only**: Marimo displays ONLY the last unindented expression executed immediately before `return`. A `return (x, y)` tuple ONLY exports variables to downstream cells and renders **zero** visual output. **NEVER** write `return mo.md(...)` or `return fig` inside `@app.cell` (`MB001` unparsable cell error). Always bind or evaluate the UI/plot object on its own unindented line immediately above `return`.1082. **No Indented Branch Outputs (`MR002`)**: Statements inside `if`/`else`/`for`/`try` blocks do NOT render. Bind `_out = mo.md("A") if cond else mo.md("B")` and evaluate `_out` unindented before `return`, or use `mo.output.replace(...)` / `mo.output.append(...)`.1093. **No Bare Module-Level Statements**: Never place `import ...`, helper code, or constants at module top level outside `with app.setup:`, `@app.function`, `@app.class_definition`, or `@app.cell`. Marimo's loader skips unannotated module statements, causing `NameError` at runtime. Prefer keeping `with app.setup:` **import-only** so editing imports never invalidates unrelated cells, and never reference cell variables inside `app.setup` (`MB004`).1104. **Never Read `.value` in the Defining Cell**: A cell that instantiates `slider = mo.ui.slider(...)` MUST display `slider` and `return (slider,)` first; read `slider.value` only in a *downstream* `@app.cell(slider)`.1115. **Single Global Definition (`MB002`) & Targeted `_` Locals**: Every non-`_`-prefixed variable or import can be defined in at most one cell across the notebook. Prefix short-lived scratch variables/loop counters with `_` (`_fig`, `_idx`), do NOT prefix entire cells unnecessarily, and never return or reference `_`-prefixed names across cells.1126. **Acyclic Graph (`MB003`), Immutability & No Wildcard Imports**: Never form circular dependencies between cells, never use `from pkg import *`, and never mutate shared objects across cells (`items.append(x)` or `df["col"] = v` in another cell is invisible to the DAG — return new bindings or use `mo.state`).1137. **Let the DAG Sequence Execution (Use `mo.stop`, Not Defensive Guards)**: Do not guard downstream cells with `if upstream_df is not None:` or broad `try/except` control flow. Use `mo.stop(predicate, output=...)` for intentional execution gating (`not run_btn.value`, `form.value is None`).1148. **Use `.batch().form()` for Multi-Widget Forms**: `mo.ui.form` wraps a single `UIElement`. Compose multi-input gated forms with `mo.md("{a}\n{b}").batch(a=..., b=...).form(...)` or `mo.ui.dictionary({...}).form(...)` — NEVER pass `mo.vstack([...])` (`Html`) to `mo.ui.form(element=...)`.1159. **Explicit Plot Themes (`0.25.2` #11147) & Dual Script/App Mode**: Marimo `0.25.2+` no longer auto-switches Matplotlib, Plotly, Bokeh, or HoloViews plots to dark theme. Set themes explicitly (e.g., `template="plotly_dark" if mo.app_meta().theme == "dark" else "plotly_white"`). Use `mo.app_meta().mode == "script"` and `mo.cli_args()` (with `pydantic.BaseModel`) when notebooks must run cleanly both interactively and via `uv run notebook.py`.11610. **Mandatory Verification Gate**: Always run `uv run marimo check --fix <nb.py>` followed by `uv run marimo check --strict <nb.py>` (zero warnings/errors), plus `uv run <nb.py>` and `uv run pytest <nb.py>` when tests are present.117118---119120## Focus Areas121122### 1. Reactive DAG Execution & Scoping123124- **Static AST Graph**: Marimo inspects each `@app.cell` AST via `marimo._ast.visitor.ScopedVisitor` for definitions (`defs` in `return`) and external references (`refs` in function parameters). Execution order is strict topological sort (`marimo._runtime.dataflow.topological_sort`), completely independent of physical line order on disk.125- **Reusable Functions & Classes**: Annotate pure helpers with `@app.function` and `@app.class_definition` (referencing only `app.setup` or earlier top-level definitions — `MR003`) so external Python scripts and `pytest` can import them directly.126- **Native Caching & Progress**: Wrap expensive pure functions in `@mo.cache` (in-memory) or `@mo.persistent_cache` (disk-backed across restarts), and wrap loops with `mo.status.spinner(...)` or `mo.status.progress_bar(...)`.127128### 2. Interactive UI (`mo.ui`), Layouts & Forms129130- **Widget Catalog**: `mo.ui.slider`, `mo.ui.range_slider`, `mo.ui.number`, `mo.ui.text`, `mo.ui.text_area`, `mo.ui.dropdown`, `mo.ui.multiselect`, `mo.ui.checkbox`, `mo.ui.radio`, `mo.ui.date`, `mo.ui.button`, `mo.ui.run_button`, `mo.ui.table`, `mo.ui.dataframe`, `mo.ui.data_explorer`, `mo.ui.plotly`, `mo.ui.altair_chart`, `mo.ui.tabs`, `mo.ui.array`, `mo.ui.dictionary`, `mo.ui.anywidget`, `mo.ui.chat`.131- **Correct Atomic Batch Form**:132133 ```python134 @app.cell135 def create_parameter_form(mo):136 param_form = (137 mo138 .md("### Simulation Parameters\n{learning_rate}\n{epochs}")139 .batch(140 learning_rate=mo.ui.slider(1e-4, 1e-1, step=1e-4, value=1e-2, label="LR"),141 epochs=mo.ui.number(1, 500, value=50, label="Epochs"),142 )143 .form(submit_button_label="Run Simulation", bordered=True)144 )145 param_form # Render the form widget146 return (param_form,)147 ```148149- **Declarative Layout & SQL**: Organize UIs with `mo.hstack`, `mo.vstack`, `mo.ui.tabs` (never deprecated `mo.tabs`), `mo.accordion`, `mo.sidebar`, `mo.stat`, and `mo.callout`. Query Polars/DuckDB/PyArrow DataFrames inline via `df = mo.sql(f"SELECT ...")` (avoid Python `#` comments inside SQL cells — `MF005`).150151### 3. State Management (`mo.state`) & Execution Gating (`mo.stop`)152153Use `mo.state(initial_value)` only when bidirectional widget sync or sequential step accumulators require persistent state across interactions:154155```python156@app.cell157def init_state(mo):158 get_history, set_history = mo.state([])159 return get_history, set_history160161162@app.cell163def gate_and_compute(mo, run_button, n_samples_slider):164 mo.stop(165 not run_button.value, mo.callout("Click Run to start sampling.", kind="info")166 )167 mo.stop(168 n_samples_slider.value < 100,169 mo.callout("Samples must be >= 100.", kind="danger"),170 )171 chains = [n_samples_slider.value]172 return (chains,)173```174175### 4. Dual Toolchain Orchestration (`pixi` & `uv`) with Python 3.14.8+ / 3.15176177Use **`uv`** (PEP 621 `pyproject.toml` + PEP 723 `# /// script`) for pure-Python stacks, and **`pixi`** (`pixi.toml` with `conda-forge` + `[pypi-dependencies]`) when notebooks depend on compiled C/C++/CUDA/OpenBLAS/HDF5/GDAL binaries:178179```toml180# pyproject.toml (uv)181[project]182name = "marimo-analysis"183version = "0.1.0"184requires-python = ">=3.14"185dependencies = [186 "marimo>=0.25.2",187 "numpy>=2.0.0",188 "scipy>=1.15.0",189 "plotly>=6.0.0",190 "pytest>=8.3.0",191]192```193194```toml195# pixi.toml196[workspace]197name = "marimo-systems"198channels = ["conda-forge"]199platforms = ["linux-64", "osx-arm64", "osx-64", "linux-aarch64"]200201[dependencies]202python = ">=3.14"203openblas = ">=0.3.28"204numpy = ">=2.0.0"205206[pypi-dependencies]207marimo = ">=0.25.2"208plotly = ">=6.0.0"209pytest = ">=8.3.0"210```211212- **Strict Repository Toolchain Boundary**: For maintaining `mimir-agent-kit` itself, always use `uv` (`./scripts/ci/run_local_ci.sh`). Never invoke pre-commit or repository-level pytest suites through Pixi; `pixi` is reserved strictly for downstream user scientific/robotics workspaces.213214### 5. Verification, Linting, App Serving & Serverless WASM Export215216- **Static Verification (`marimo check`)**: Detects `MB001`–`MB005` (breaking AST/DAG/syntax/setup errors), `MR001`–`MR004` (runtime anti-patterns like `MR002` branch expressions), `MF001`–`MF007` (formatting), and `MW001`–`MW003` (WASM/Pyodide compatibility).217- **Embedded `pytest` Discovery**: Cells defining `def test_*(): assert ...` (or imported `@app.function` tests) execute directly under `uv run pytest notebook.py -v`.218- **Apps & WASM Export (`0.25.2+`)**:219 - Production web app: `uv run marimo run --port 8080 --host 127.0.0.1 notebook.py`220 - Static archival HTML: `uv run marimo export html notebook.py -o dist/report.html --include-code`221 - Client-side Pyodide WASM: `uv run marimo export html-wasm notebook.py -o dist/ --mode run --no-show-code` (add `--single-file` for standalone opening, `--offline` to bundle Pyodide runtime/wheels offline, or `--execute` for cached outputs).222223---224225## Decision Trees226227```text228Need reactive behavior in Marimo?229├── Parameter sweep / filtering (<50ms)? ──> Standard `mo.ui.*` widget; read `.value` downstream230├── Expensive compute / MCMC / training? ──> `.batch().form()` + `mo.stop(form.value is None, ...)`231├── Step accumulator / undo history? ──> `mo.state()` with functional `set_val(lambda prev: ...)`232└── Static vs. Live Running Session?233 ├── Notebook `.py` file only (idle)? ──> Edit disk file + run `marimo check --strict` & `pytest`234 └── Live `marimo edit` kernel open? ──> Switch to `/marimo-pair` (`marimo._code_mode`)235```236237## Toolchain & Verification Commands238239```bash240uv run marimo edit --port 2718 notebook.py # Interactive authoring241uv run marimo check --fix notebook.py # Auto-fix signatures & formatting242uv run marimo check --strict notebook.py # Strict DAG, runtime & style verification243uv run marimo check notebook.py --select MW --format json # WASM / Pyodide pre-flight check244uv run notebook.py # Headless script execution smoke test245uv run pytest notebook.py -v # Execute embedded test_* cells246uv run ruff check notebook.py && uv run ruff format --check notebook.py247uv run marimo export html-wasm notebook.py -o dist/ --mode run --no-show-code248```249250---251252## References & Examples Index253254- **Reference Manuals (`references/`)**:255 - [marimo_architecture_and_dag.md](./references/marimo_architecture_and_dag.md): Canonical `.py` grammar, `marimo check` rule codes (`MB*`/`MR*`/`MF*`/`MW*`), DAG scoping, `mo.state`, `mo.stop`, and CLI/batch dual mode.256 - [interactive_widgets_and_ui.md](./references/interactive_widgets_and_ui.md): `mo.ui` catalog, `.batch().form()`, layouts, explicit plot themes (`0.25.2+`), `_display_()`, `anywidget`, and WASM export.257 - [dual_toolchain_pixi_uv.md](./references/dual_toolchain_pixi_uv.md): `uv` & `pixi` orchestration (Python 3.14.8+/3.15), PEP 723 `--sandbox`, CLI reference, and embedded `pytest`.258 - [advanced_data_analysis_scenarios.md](./references/advanced_data_analysis_scenarios.md): Production DAG architectures for `heimdall-astro`, `talos-robotics`, and `microkernel-labs`.259- **Runnable Demonstration Notebooks & Manifests (`examples/`)**:260 - `pyproject.toml` ([examples/pyproject.toml](./examples/pyproject.toml)): Standalone PEP 621 manifest for `uv`.261 - `pixi.toml` ([examples/pixi.toml](./examples/pixi.toml)): Multi-platform `conda-forge` + PyPI manifest.262 - `astro_transit_photometry.py` ([examples/astro_transit_photometry.py](./examples/astro_transit_photometry.py)): Exoplanet Mandel-Agol transit model + gated MCMC.263 - `robotics_kalman_filter.py` ([examples/robotics_kalman_filter.py](./examples/robotics_kalman_filter.py)): 6-DoF EKF sensor fusion & `+/- 3 sigma` diagnostics.264 - `systems_telemetry_analysis.py` ([examples/systems_telemetry_analysis.py](./examples/systems_telemetry_analysis.py)): Microkernel IPC tail-latency HDR survival dashboard.265 - `bayesian_mcmc_diagnostic.py` ([examples/bayesian_mcmc_diagnostic.py](./examples/bayesian_mcmc_diagnostic.py)): Gelman-Rubin R-hat & integrated autocorrelation with embedded `pytest`.