From 3c98903b2ae53082dcc7d827a26c57d45f0ad048 Mon Sep 17 00:00:00 2001 From: Konstantin Taletskiy Date: Thu, 3 Sep 2026 17:57:22 -0700 Subject: [PATCH 1/6] Document marimo UI and remote media checks --- .../skills/marimo-wandb-notebooks/SKILL.md | 7 ++++- .../references/convert-cleanup.md | 26 ++++++++++++++++++- .../references/marimo-idioms.md | 17 +++++++++++- .../references/wandb-patterns.md | 13 ++++++++++ 4 files changed, 60 insertions(+), 3 deletions(-) diff --git a/.agents/skills/marimo-wandb-notebooks/SKILL.md b/.agents/skills/marimo-wandb-notebooks/SKILL.md index c006e8ae..cd67e7af 100644 --- a/.agents/skills/marimo-wandb-notebooks/SKILL.md +++ b/.agents/skills/marimo-wandb-notebooks/SKILL.md @@ -99,7 +99,12 @@ Give a concrete fix for each issue. Do not modify files unless asked. Before considering a conversion complete: -- `uvx marimo check ` passes. +- `uvx marimo check ` passes after the final notebook edit; do + not rely on a saved conversion log or an earlier successful check. +- A fresh sandboxed local session or molab session opens without cell errors. + Every intended widget, form, and embedded player visibly renders, and each + orchestration cell reads a documented reactive value. Keep remote-write + controls unsubmitted, or use an offline/test backend, during this smoke test. - Notebook structure follows [`references/marimo-idioms.md`](references/marimo-idioms.md), including the separation of teaching code, marimo orchestration, and reusable helpers. diff --git a/.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md b/.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md index c40cb488..185d80b6 100644 --- a/.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md +++ b/.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md @@ -44,6 +44,23 @@ marimo notebook from a Jupyter `.ipynb`. The converter writes diagnostics to multiple cells. Keep cell-local imports private with an underscore alias such as `from torch.utils.data import DataLoader as _DataLoader`. +## Molab and Remote Assets + +- Do not assume molab's **Mirror from GitHub** action provides a checkout of the + whole repository. A notebook and its dependency metadata can be present + while sibling data files are not. +- For public, read-only repository assets, prefer a named filesystem such as + `repo_fs = fsspec.filesystem("github", org="wandb", repo="examples")` and + stream files from it. A public name also makes the source discoverable in + marimo's Remote Storage panel. +- Declare `fsspec[http]`, not only `fsspec`, when the notebook reads Git-LFS + files or GitHub files larger than 1 MB. +- Pass file-like objects directly when the consumer supports them. Otherwise, + adapt in memory with `io.BytesIO` or `io.StringIO`, or materialize only the + specific file an API requires. +- Clone a repository only when the tutorial needs Git history, repository + semantics, or a local directory tree rather than a few read-only assets. + ## Widget Cleanup - Replace ipywidgets with native `mo.ui` components when there is a direct @@ -61,8 +78,15 @@ marimo notebook from a Jupyter `.ipynb`. The converter writes diagnostics to ## Final Check -Run: +After the final notebook edit, run: ```bash uvx marimo check marimo/convert//.py ``` + +Then open the notebook in a fresh molab session or a local sandbox. Confirm +that intended controls and embeds render, change each safe control at least +once, and inspect cell errors. Static checking cannot detect a nonexistent +runtime attribute such as `.clicked` or a widget that was constructed but +never returned for display. Keep remote-write controls unsubmitted, or use an +offline/test backend, during this smoke test. diff --git a/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md b/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md index 87ebb5b7..8b2716c6 100644 --- a/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md +++ b/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md @@ -41,6 +41,11 @@ function clean and put its gate or UI wiring in separate cells. - Let the dependency graph determine execution. A cell runs when its inputs are ready. +- `mo.stop()`, `if`, `for`, and `with` control runtime execution; they do not + create a static scope. Imports, assignment targets, loop targets, and context + manager targets anywhere in a cell still define names in marimo's graph. + Give each shared name one owning cell, prefix cell-local temporaries with + `_`, or move procedural work into a function. - Do not rely on cross-cell mutation for reactivity; marimo does not track object mutations or attribute assignments. Prefer creating a new value, or mutate an object only in the cell that defines it. @@ -107,10 +112,20 @@ helpers. Do not repeat the same gate in downstream cells. named helpers. - Prefer native components such as `mo.ui.table`, `mo.callout`, `mo.vstack`, and `mo.hstack` over formatting complex UI as markdown. +- Use `mo.video` for a direct video URL, file, or bytes. For a hosted player + such as YouTube, use the provider's canonical HTTPS embed URL in a trusted + `mo.Html` iframe with a descriptive title and a normal link fallback. +- When official brand artwork has light- and dark-theme variants, select the + appropriate variant and visually verify both marimo themes. ## UI -- Show widgets directly and read their `.value` in orchestration cells. +- Constructing or assigning a widget does not display it. End the definition + cell with the widget or a layout containing it; returning it only wires the + reactive dependency graph. +- Show widgets directly and read documented reactive state such as `.value` in + orchestration cells. Do not invent callback-style attributes such as + `.clicked`; inspect the live object or official API when uncertain. - Prefer native `mo.ui` components before reaching for `anywidget`. ## Error Handling diff --git a/.agents/skills/marimo-wandb-notebooks/references/wandb-patterns.md b/.agents/skills/marimo-wandb-notebooks/references/wandb-patterns.md index acb86c7a..9c043f0c 100644 --- a/.agents/skills/marimo-wandb-notebooks/references/wandb-patterns.md +++ b/.agents/skills/marimo-wandb-notebooks/references/wandb-patterns.md @@ -69,6 +69,19 @@ marimo orders cells through name dependencies; it cannot observe mutations to - Move non-teaching plumbing into helpers when it improves the teaching surface. +## Media From Remote Filesystems + +- Preserve the real media format when adapting a remote file. For example, + pass MP4 bytes through `io.BytesIO` to `wandb.Video(..., format="mp4")` + instead of relabeling the source as a GIF. +- Decode audio with a library such as `soundfile` and pass the detected sample + rate to `wandb.Audio`; do not guess from the tutorial text or source code. +- For OBJ text read from a remote filesystem, use `io.StringIO` and pass + `file_type="obj"` to `wandb.Object3D`. Some file-like objects expose a + `.name` that an SDK can mistake for a local path. +- When logging HTML content rather than a local path, pass the text explicitly + with `data_is_not_path=True`. + ## Expected Failures - Catch only expected, recoverable W&B failures where the notebook can provide From 4a6a80b9245057d0cd735040a0ba30ce2f18b868 Mon Sep 17 00:00:00 2001 From: Konstantin Taletskiy Date: Thu, 3 Sep 2026 18:10:47 -0700 Subject: [PATCH 2/6] Avoid anonymous GitHub API filesystems --- .../references/convert-cleanup.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md b/.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md index 185d80b6..6e7606ed 100644 --- a/.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md +++ b/.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md @@ -49,12 +49,17 @@ marimo notebook from a Jupyter `.ipynb`. The converter writes diagnostics to - Do not assume molab's **Mirror from GitHub** action provides a checkout of the whole repository. A notebook and its dependency metadata can be present while sibling data files are not. -- For public, read-only repository assets, prefer a named filesystem such as - `repo_fs = fsspec.filesystem("github", org="wandb", repo="examples")` and - stream files from it. A public name also makes the source discoverable in - marimo's Remote Storage panel. -- Declare `fsspec[http]`, not only `fsspec`, when the notebook reads Git-LFS - files or GitHub files larger than 1 MB. +- For public, read-only repository assets, prefer a named HTTP filesystem and + raw content URLs, for example `repo_fs = fsspec.filesystem("https")` with a + `raw.githubusercontent.com` base URL. A public filesystem name also makes the + source discoverable in marimo's Remote Storage panel. +- Avoid an anonymous `fsspec.filesystem("github", ...)` in hosted notebooks. + Its repository lookup uses the rate-limited GitHub API, and users can share + one unauthenticated IP quota. Use it only when repository listing semantics + are required and an optional GitHub token comes from the runtime's secrets or + environment; never hardcode the token. +- Declare `fsspec[http]`, not only `fsspec`, for HTTP files, Git-LFS content, + and GitHub files larger than 1 MB. - Pass file-like objects directly when the consumer supports them. Otherwise, adapt in memory with `io.BytesIO` or `io.StringIO`, or materialize only the specific file an API requires. From d1055b1dfd33fabc9c5e3b109829579e27fe5200 Mon Sep 17 00:00:00 2001 From: Konstantin Taletskiy Date: Thu, 3 Sep 2026 23:30:01 -0700 Subject: [PATCH 3/6] Refine notebook preservation guidance --- .../skills/marimo-wandb-notebooks/SKILL.md | 19 +++++++++++-- .../references/convert-cleanup.md | 28 +++++++++++-------- .../references/marimo-idioms.md | 26 +++++++++++------ .../tutorial-notebook-objectives.md | 14 ++++++---- 4 files changed, 60 insertions(+), 27 deletions(-) diff --git a/.agents/skills/marimo-wandb-notebooks/SKILL.md b/.agents/skills/marimo-wandb-notebooks/SKILL.md index cd67e7af..f19bf8ea 100644 --- a/.agents/skills/marimo-wandb-notebooks/SKILL.md +++ b/.agents/skills/marimo-wandb-notebooks/SKILL.md @@ -51,12 +51,23 @@ Also read: - Use the original `.ipynb` for tutorial intent, narrative, and featured W&B behavior. - Treat the current `.py` as the current conversion state. +- When the user designates a live marimo or molab notebook, or an artifact + exported from it, as authoritative, it overrides the repository `.py` as the + current implementation state. The original `.ipynb` remains a reference for + intent, not a reason to rewrite the designated artifact. Do not edit the live + notebook or update a branch unless requested. When syncing is requested, + export or download after the final approved live edit and preserve cell order, + boundaries, setup status, identifiers, working integrations, and configuration + such as `hide_code` and `disabled` unless the request requires changing them. - Treat `.logs/` as historical diagnostic evidence. - Use a fresh `marimo check` for current static validity. - Use `examples/marimo/mnist-registry/mnist_registry.py` as the structural exemplar when the references do not specify a choice, especially its separation of marimo orchestration cells from reusable `@app.function` helpers. Do not copy tutorial-specific details from the exemplar. +- Notebook review or repair does not authorize submitting live credentials or + remote-write controls, committing, pushing, or changing a pull request. + Perform those actions only when the user explicitly requests them. ## Conversion priorities @@ -120,6 +131,8 @@ Before considering a conversion complete: closes prior runs and avoids duplicate stateful updates where practical. - Cross-cell consumers of W&B state use explicit result or completion values, and producers synchronize server-visible state before downstream reads. -- A fresh molab session can authenticate without credentials from the local - computer, and no credential appears in notebook output, run configuration, - logs, or the diff. +- A fresh molab session presents an authentication path that does not assume + credentials from the local computer. Inspect the inputs and gate without + submitting real credentials; test live authentication only when explicitly + requested or with a designated test backend. No credential appears in + notebook output, run configuration, logs, or the diff. diff --git a/.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md b/.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md index 6e7606ed..a6658d02 100644 --- a/.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md +++ b/.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md @@ -29,8 +29,10 @@ marimo notebook from a Jupyter `.ipynb`. The converter writes diagnostics to unnecessary `display()` calls. - Make the intended output the final expression of each display cell. Indented or conditional expressions will not render as cell output. -- Replace notebook-global scratch variables with local variables inside helper - functions when they are only used in one step. +- When cleanup is requested and it improves clarity, replace notebook-global + scratch variables with locals inside helper functions. Do not do this during + an exact synchronization or when it would rename or obscure teaching code + without resolving a demonstrated graph problem. - Prefer explicit markdown cells for prose. Do not leave tutorial text inside code comments or string literals in logic cells. @@ -49,15 +51,19 @@ marimo notebook from a Jupyter `.ipynb`. The converter writes diagnostics to - Do not assume molab's **Mirror from GitHub** action provides a checkout of the whole repository. A notebook and its dependency metadata can be present while sibling data files are not. -- For public, read-only repository assets, prefer a named HTTP filesystem and - raw content URLs, for example `repo_fs = fsspec.filesystem("https")` with a - `raw.githubusercontent.com` base URL. A public filesystem name also makes the - source discoverable in marimo's Remote Storage panel. -- Avoid an anonymous `fsspec.filesystem("github", ...)` in hosted notebooks. - Its repository lookup uses the rate-limited GitHub API, and users can share - one unauthenticated IP quota. Use it only when repository listing semantics - are required and an optional GitHub token comes from the runtime's secrets or - environment; never hardcode the token. +- Preserve a working asset-loading backend. Do not replace it solely because a + different backend might avoid a hypothetical hosted-environment limit. +- Use `fsspec.filesystem("github", org=..., repo=...)` with repository-relative + paths when repository listing or marimo's Remote Storage browser is useful. + Anonymous hosted sessions can share GitHub's API quota; respond to a + demonstrated rate-limit failure with an optional token from runtime secrets + or environment, or use raw HTTPS for the affected known files. Never hardcode + a token. +- A named HTTP filesystem with `raw.githubusercontent.com` URLs avoids GitHub's + repository API when only known public files are required. A bare + `HTTPFileSystem` can open concrete URLs but has no listable root, so do not + select it solely to expose a browsable source in marimo's Remote Storage + panel. - Declare `fsspec[http]`, not only `fsspec`, for HTTP files, Git-LFS content, and GitHub files larger than 1 MB. - Pass file-like objects directly when the consumer supports them. Otherwise, diff --git a/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md b/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md index 8b2716c6..9e0226fb 100644 --- a/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md +++ b/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md @@ -33,9 +33,14 @@ Do not add marimo orchestration, generated dependency plumbing, or underscore-prefixed scratch variables to teaching code merely to satisfy the reactive graph. -Use underscore-prefixed temporaries in orchestration or presentation cells when -useful. When teaching code is naturally expressed as a function, keep the -function clean and put its gate or UI wiring in separate cells. +Preserve original identifiers in teaching code. Do not mechanically prefix a +unique name with `_` merely because no later cell reads it. First inspect actual +definitions and references across cells. Use private names to resolve a real +cross-cell redefinition or for newly introduced implementation-only plumbing, +such as file handles, context-manager targets, or UI internals. + +When teaching code is naturally expressed as a function, keep the function +clean and put its gate or UI wiring in separate cells. ## Reactivity @@ -43,9 +48,10 @@ function clean and put its gate or UI wiring in separate cells. ready. - `mo.stop()`, `if`, `for`, and `with` control runtime execution; they do not create a static scope. Imports, assignment targets, loop targets, and context - manager targets anywhere in a cell still define names in marimo's graph. - Give each shared name one owning cell, prefix cell-local temporaries with - `_`, or move procedural work into a function. + manager targets anywhere in a cell still define names in marimo's graph. Give + each shared name one owning cell. Keep unique teaching names public even when + they have no downstream consumer; use `_` for genuinely private plumbing or + repeated scratch names, or move procedural work into a function. - Do not rely on cross-cell mutation for reactivity; marimo does not track object mutations or attribute assignments. Prefer creating a new value, or mutate an object only in the cell that defines it. @@ -115,8 +121,12 @@ helpers. Do not repeat the same gate in downstream cells. - Use `mo.video` for a direct video URL, file, or bytes. For a hosted player such as YouTube, use the provider's canonical HTTPS embed URL in a trusted `mo.Html` iframe with a descriptive title and a normal link fallback. -- When official brand artwork has light- and dark-theme variants, select the - appropriate variant and visually verify both marimo themes. +- For the W&B header pattern used by the media tutorial, use + `https://raw.githubusercontent.com/wandb/docs/main/icons/Endorsed_primary_blackwhite.svg` + in the light theme and + `https://raw.githubusercontent.com/wandb/docs/main/icons/Endorsed_primary_goldwhite.svg` + in the dark theme. Render both and switch them with marimo's `body.dark` + class; visually verify both themes. ## UI diff --git a/.agents/skills/marimo-wandb-notebooks/references/tutorial-notebook-objectives.md b/.agents/skills/marimo-wandb-notebooks/references/tutorial-notebook-objectives.md index 5e26f50d..dd3f5bc0 100644 --- a/.agents/skills/marimo-wandb-notebooks/references/tutorial-notebook-objectives.md +++ b/.agents/skills/marimo-wandb-notebooks/references/tutorial-notebook-objectives.md @@ -32,9 +32,13 @@ Use this when creating, reviewing, or polishing W&B example notebooks. ## Reader Verification -- End with a clear "Verify and next steps" section. -- Tell the reader exactly what to inspect in the W&B UI, including relevant - charts, tabs, panels, Artifacts, Registry collections, or run summary fields. +- Preserve the source notebook's ending. Add or adapt concise verification and + next-step guidance only when readers otherwise lack a clear way to confirm + the tutorial result; do not append generic boilerplate during a repair or + exact synchronization. +- When verification guidance is needed, tell the reader exactly what to inspect + in the W&B UI, including relevant charts, tabs, panels, Artifacts, Registry + collections, or run summary fields. - Apply a fresh-eyes test: a reader following the documented prerequisites - should be able to complete the tutorial and verify the result from the final - section alone. \ No newline at end of file + should be able to complete the tutorial and verify the result from the + notebook's guidance. From eb4443da4e64ad86d62617d2e87515763ca61c49 Mon Sep 17 00:00:00 2001 From: Konstantin Taletskiy Date: Wed, 9 Sep 2026 10:41:53 -0700 Subject: [PATCH 4/6] Document standardized auth and subprocess runs --- .../skills/marimo-wandb-notebooks/SKILL.md | 6 +++-- .../references/convert-cleanup.md | 7 ++++++ .../references/marimo-idioms.md | 4 +++- .../references/wandb-patterns.md | 24 +++++++++++++++++++ 4 files changed, 38 insertions(+), 3 deletions(-) diff --git a/.agents/skills/marimo-wandb-notebooks/SKILL.md b/.agents/skills/marimo-wandb-notebooks/SKILL.md index f19bf8ea..aeb37193 100644 --- a/.agents/skills/marimo-wandb-notebooks/SKILL.md +++ b/.agents/skills/marimo-wandb-notebooks/SKILL.md @@ -57,8 +57,10 @@ Also read: intent, not a reason to rewrite the designated artifact. Do not edit the live notebook or update a branch unless requested. When syncing is requested, export or download after the final approved live edit and preserve cell order, - boundaries, setup status, identifiers, working integrations, and configuration - such as `hide_code` and `disabled` unless the request requires changing them. + boundaries, setup status, identifiers, dependency metadata, working + integrations, and configuration such as `hide_code` and `disabled` unless the + request requires changing them or a demonstrated runtime issue requires a + dependency correction. - Treat `.logs/` as historical diagnostic evidence. - Use a fresh `marimo check` for current static validity. - Use `examples/marimo/mnist-registry/mnist_registry.py` as the structural diff --git a/.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md b/.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md index a6658d02..0b6247c4 100644 --- a/.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md +++ b/.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md @@ -25,8 +25,15 @@ marimo notebook from a Jupyter `.ipynb`. The converter writes diagnostics to when deciding which instructional cells and W&B API examples to preserve. - Ensure the PEP 723 script metadata lists every runtime package the notebook imports. The converter may miss dependencies. +- Move `%pip` and `!pip install` requirements into PEP 723 metadata, then remove + the obsolete install command, generated install commentary, and any empty + cell it leaves behind. Do not replace package installation with a subprocess. - Remove Jupyter-only artifacts such as `%magic` commands, shell escapes, and unnecessary `display()` calls. +- Translate remaining shell escapes by purpose instead of mechanically wrapping + every command in `subprocess`. Use `fsspec` when file-like or filesystem + access is useful, and reserve `subprocess` for programs that genuinely need a + separate process. - Make the intended output the final expression of each display cell. Indented or conditional expressions will not render as cell output. - When cleanup is requested and it improves clarity, replace notebook-global diff --git a/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md b/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md index 9e0226fb..7b778775 100644 --- a/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md +++ b/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md @@ -126,7 +126,9 @@ helpers. Do not repeat the same gate in downstream cells. in the light theme and `https://raw.githubusercontent.com/wandb/docs/main/icons/Endorsed_primary_goldwhite.svg` in the dark theme. Render both and switch them with marimo's `body.dark` - class; visually verify both themes. + class; visually verify both themes. For the verified marimo `mo.callout` + pattern, select the theme with `:host-context(body.dark)` so the rule crosses + the component boundary. ## UI diff --git a/.agents/skills/marimo-wandb-notebooks/references/wandb-patterns.md b/.agents/skills/marimo-wandb-notebooks/references/wandb-patterns.md index 9c043f0c..2718962f 100644 --- a/.agents/skills/marimo-wandb-notebooks/references/wandb-patterns.md +++ b/.agents/skills/marimo-wandb-notebooks/references/wandb-patterns.md @@ -4,6 +4,10 @@ Use these patterns when a marimo example uses the W&B Python SDK. ## Authentication +- Keep exactly one reader-facing Authentication section. Consolidate signup, + API-key, entity, and login guidance and controls there. Remove duplicate + standalone Colab-era signup and API-key prompts once their essential guidance + is represented in this section; preserve unique tutorial-specific context. - Offer a `mo.ui.text(kind="password")` API-key field. - Call `wandb.login()` only after the reader explicitly submits the form or clicks the run button. @@ -37,6 +41,26 @@ active across cells, finish any prior active run before starting another one. idempotent when practical, such as skipping an alias or Registry link that is already present. +### Runs Created By Child Processes + +When readers need a dashboard link before a blocking command-line program +finishes, preassign the W&B run identity before launching the process: + +- Resolve concrete project, entity, and run ID values, then derive the run URL + from those same values with `wandb.Settings(...).run_url`. +- Start with `os.environ.copy()` and add `WANDB_PROJECT`, `WANDB_ENTITY`, and + `WANDB_RUN_ID`. Pass that mapping as `env` and use `check=True` with + `subprocess.run`; never display the environment because it can contain + secrets. +- Keep preparation, process execution, and URL presentation in separate cells. + Make the process and URL cells depend on the prepared values, not on each + other, so the dashboard link can render while the command is still running. +- Do not assume authentication enables a framework's W&B integration. Pass its + explicit integration option when required—for Hugging Face Trainer commands, + use `--report_to wandb`—and verify that the expected run is created. +- Pass actual values in the argument list. List-form `subprocess.run` does not + expand shell variables such as `$WANDB_PROJECT`. + ## Ordering Remote Effects marimo orders cells through name dependencies; it cannot observe mutations to From a6db6aec0b35bec4922ea502e67c7caa7f04df54 Mon Sep 17 00:00:00 2001 From: Konstantin Taletskiy Date: Thu, 10 Sep 2026 12:01:08 -0700 Subject: [PATCH 5/6] Refine marimo notebook authoring guidance --- .../skills/marimo-wandb-notebooks/SKILL.md | 2 ++ .../references/marimo-idioms.md | 18 ++++++++++++++---- .../tutorial-notebook-objectives.md | 12 ++++++++++-- .../references/wandb-patterns.md | 19 +++++++++++++++++-- 4 files changed, 43 insertions(+), 8 deletions(-) diff --git a/.agents/skills/marimo-wandb-notebooks/SKILL.md b/.agents/skills/marimo-wandb-notebooks/SKILL.md index aeb37193..d1b25c74 100644 --- a/.agents/skills/marimo-wandb-notebooks/SKILL.md +++ b/.agents/skills/marimo-wandb-notebooks/SKILL.md @@ -123,6 +123,8 @@ Before considering a conversion complete: separation of teaching code, marimo orchestration, and reusable helpers. - Tutorial quality follows [`references/tutorial-notebook-objectives.md`](references/tutorial-notebook-objectives.md). +- The Markdown outline has exactly one level-one heading for the notebook title; + major sections use level two, and nested sections do not skip heading levels. - Featured W&B SDK usage follows [`references/wandb-patterns.md`](references/wandb-patterns.md). - No unintended generated or runtime files were introduced, and the notebook diff --git a/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md b/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md index 7b778775..19821556 100644 --- a/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md +++ b/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md @@ -35,9 +35,12 @@ reactive graph. Preserve original identifiers in teaching code. Do not mechanically prefix a unique name with `_` merely because no later cell reads it. First inspect actual -definitions and references across cells. Use private names to resolve a real -cross-cell redefinition or for newly introduced implementation-only plumbing, -such as file handles, context-manager targets, or UI internals. +definitions and references across cells. For reader-facing definitions, resolve +a real cross-cell redefinition by moving procedural work into a function or +choosing unique descriptive names. Reserve private names for newly introduced +implementation-only plumbing, such as file handles, context-manager targets, or +UI internals. For W&B run objects, follow +[`Naming Run Objects in marimo`](wandb-patterns.md#naming-run-objects-in-marimo). When teaching code is naturally expressed as a function, keep the function clean and put its gate or UI wiring in separate cells. @@ -51,7 +54,8 @@ clean and put its gate or UI wiring in separate cells. manager targets anywhere in a cell still define names in marimo's graph. Give each shared name one owning cell. Keep unique teaching names public even when they have no downstream consumer; use `_` for genuinely private plumbing or - repeated scratch names, or move procedural work into a function. + repeated scratch names that are not reader-facing, or move procedural work + into a function. - Do not rely on cross-cell mutation for reactivity; marimo does not track object mutations or attribute assignments. Prefer creating a new value, or mutate an object only in the cell that defines it. @@ -116,6 +120,12 @@ helpers. Do not repeat the same gate in downstream cells. - Use markdown cells for prose and view cells for rendering. - Keep view cells focused on presentation; move non-teaching heavy logic into named helpers. +- Preserve deliberate `hide_code` choices. Prefer `hide_code=True` for + implementation-only cells whose rendered output is the reader-facing + surface, such as authentication form construction, W&B connection or status + gates, and boilerplate HTML embeds such as YouTube iframes. Keep teaching + code, featured W&B SDK usage, and helper implementations readers are expected + to adapt visible. - Prefer native components such as `mo.ui.table`, `mo.callout`, `mo.vstack`, and `mo.hstack` over formatting complex UI as markdown. - Use `mo.video` for a direct video URL, file, or bytes. For a hosted player diff --git a/.agents/skills/marimo-wandb-notebooks/references/tutorial-notebook-objectives.md b/.agents/skills/marimo-wandb-notebooks/references/tutorial-notebook-objectives.md index dd3f5bc0..3589e2ed 100644 --- a/.agents/skills/marimo-wandb-notebooks/references/tutorial-notebook-objectives.md +++ b/.agents/skills/marimo-wandb-notebooks/references/tutorial-notebook-objectives.md @@ -21,8 +21,16 @@ Use this when creating, reviewing, or polishing W&B example notebooks. - Keep the notebook readable from top to bottom. - Preserve useful authorial explanations from the source notebook when they still fit the marimo version. -- Start with a clear title and any prerequisites or setup notes the reader - needs before running the notebook. +- Use exactly one Markdown level-one heading (`#`) for the notebook title. Use + level-two headings (`##`) for major sections and level-three or deeper + headings for their subsections without skipping levels. Correct heading + markers even during an otherwise content-preserving conversion, but do not + rewrite the heading text or surrounding prose solely to repair the hierarchy. +- For readability, omit decorative emojis from headings, labels, callout + titles, and prose. Remove them during cleanup without otherwise rewriting the + surrounding text. +- Start with any prerequisites or setup notes the reader needs before running + the notebook. - Interleave pipeline code with markdown sections that explain what the reader is about to run and why it matters. - Keep code cells purposeful: show a result, teach a core step, or define a diff --git a/.agents/skills/marimo-wandb-notebooks/references/wandb-patterns.md b/.agents/skills/marimo-wandb-notebooks/references/wandb-patterns.md index 2718962f..effc9e8a 100644 --- a/.agents/skills/marimo-wandb-notebooks/references/wandb-patterns.md +++ b/.agents/skills/marimo-wandb-notebooks/references/wandb-patterns.md @@ -30,8 +30,23 @@ Use these patterns when a marimo example uses the W&B Python SDK. run.log({"loss": 0.1}) ``` -Otherwise, explicitly finish the run with `run.finish()`. If a run must stay -active across cells, finish any prior active run before starting another one. +### Naming Run Objects in marimo + +marimo requires each notebook-global name to have one defining cell. If a +notebook creates W&B runs in multiple cells, do not repeat a top-level +`run = wandb.init(...)` or `with wandb.init() as run:` binding across them. + +- Prefer putting each complete run lifecycle in a function or `@app.function`; + `run` is then an ordinary local name and can be reused naturally. +- When a run remains notebook-global, give each instance a unique, descriptive + name for its role, such as `training_run`, `evaluation_run`, or + `artifact_link_run`, and use that name consistently. +- `_run` is a valid cell-local fallback for private plumbing, but do not use + repeated `_run` bindings as the default in reader-visible teaching code. + +When a run cannot use a context manager, explicitly call `.finish()` on the +corresponding run object. If a run must stay active across cells, finish any +prior active run before starting another one. - Prefer methods on the active run, such as `run.log()`, `run.log_artifact()`, and `run.summary`, unless the tutorial intentionally teaches another W&B API From 90a3964f6dd98159cc649f545a094f41cfdef778 Mon Sep 17 00:00:00 2001 From: Konstantin Taletskiy Date: Thu, 10 Sep 2026 15:07:45 -0700 Subject: [PATCH 6/6] Clarify setup and helper visibility guidance --- .agents/skills/marimo-wandb-notebooks/SKILL.md | 3 +++ .../marimo-wandb-notebooks/references/marimo-idioms.md | 7 +++++-- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/.agents/skills/marimo-wandb-notebooks/SKILL.md b/.agents/skills/marimo-wandb-notebooks/SKILL.md index d1b25c74..fef596b0 100644 --- a/.agents/skills/marimo-wandb-notebooks/SKILL.md +++ b/.agents/skills/marimo-wandb-notebooks/SKILL.md @@ -121,6 +121,9 @@ Before considering a conversion complete: - Notebook structure follows [`references/marimo-idioms.md`](references/marimo-idioms.md), including the separation of teaching code, marimo orchestration, and reusable helpers. +- The setup cell remains visible while implementation-only authentication, + status, and embed cells are hidden where their rendered output is the + reader-facing surface. - Tutorial quality follows [`references/tutorial-notebook-objectives.md`](references/tutorial-notebook-objectives.md). - The Markdown outline has exactly one level-one heading for the notebook title; diff --git a/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md b/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md index 19821556..9f4ee19b 100644 --- a/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md +++ b/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md @@ -14,6 +14,9 @@ this repo. as `"marimo>=0.9"` and `"wandb>=0.18"`. - Use one setup/import cell for shared imports, true constants, and environment detection. +- Keep the setup cell's code visible. It is the reader-facing inventory of + shared imports, dependencies, and notebook-wide constants; do not apply + `hide_code=True` to it. - Keep reactive notebook globals scarce. ## Separate Teaching, Orchestration, and Helpers @@ -124,8 +127,8 @@ helpers. Do not repeat the same gate in downstream cells. implementation-only cells whose rendered output is the reader-facing surface, such as authentication form construction, W&B connection or status gates, and boilerplate HTML embeds such as YouTube iframes. Keep teaching - code, featured W&B SDK usage, and helper implementations readers are expected - to adapt visible. + code, featured W&B SDK usage, the setup cell, and helper implementations + readers are expected to adapt visible. - Prefer native components such as `mo.ui.table`, `mo.callout`, `mo.vstack`, and `mo.hstack` over formatting complex UI as markdown. - Use `mo.video` for a direct video URL, file, or bytes. For a hosted player