diff --git a/.agents/skills/marimo-wandb-notebooks/SKILL.md b/.agents/skills/marimo-wandb-notebooks/SKILL.md index c006e8ae..aeb37193 100644 --- a/.agents/skills/marimo-wandb-notebooks/SKILL.md +++ b/.agents/skills/marimo-wandb-notebooks/SKILL.md @@ -51,12 +51,25 @@ 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, 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 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 @@ -99,7 +112,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. @@ -115,6 +133,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 c40cb488..0b6247c4 100644 --- a/.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md +++ b/.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md @@ -25,12 +25,21 @@ 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. -- 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. @@ -44,6 +53,32 @@ 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. +- 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, + 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 +96,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..7b778775 100644 --- a/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md +++ b/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md @@ -33,14 +33,25 @@ 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 - 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. 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. @@ -107,10 +118,26 @@ 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. +- 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. For the verified marimo `mo.callout` + pattern, select the theme with `:host-context(body.dark)` so the rule crosses + the component boundary. ## 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/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. diff --git a/.agents/skills/marimo-wandb-notebooks/references/wandb-patterns.md b/.agents/skills/marimo-wandb-notebooks/references/wandb-patterns.md index acb86c7a..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 @@ -69,6 +93,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