diff --git a/.agents/skills/marimo-wandb-notebooks/SKILL.md b/.agents/skills/marimo-wandb-notebooks/SKILL.md index c006e8ae..25812d58 100644 --- a/.agents/skills/marimo-wandb-notebooks/SKILL.md +++ b/.agents/skills/marimo-wandb-notebooks/SKILL.md @@ -5,6 +5,18 @@ description: Convert existing Jupyter or Colab .ipynb tutorials in wandb/example # Convert W&B example notebooks to marimo +## Why we are migrating + +**Mission**: Make marimo *the* **standard** computational notebook, supporting +the entire lifecycle of computational science and development. + +These migrations bring established W&B workflows into marimo: learning, +experimentation, training, debugging, inspecting results, and sharing +reproducible work. Preserve the tutorials' teaching value while making those +workflows usable end to end in marimo and molab. A successful migration gives +readers a notebook they can understand, run, adapt, and build on throughout +that lifecycle. + ## Determine the starting state ### `.ipynb` @@ -42,21 +54,36 @@ Before modifying a notebook, read: Also read: - [`references/convert-cleanup.md`](references/convert-cleanup.md) for - generated, pre-converted, or failed conversions. + generated, pre-converted, or failed conversions, molab links, and hosted + runtime failures. - [`references/wandb-patterns.md`](references/wandb-patterns.md) when - reviewing or changing W&B SDK usage. + reviewing or changing W&B SDK usage, including logged media. ## Sources of truth - 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. Work on the artifacts + the user requested: a live repair does not imply a repository sync, while a + request to fix both requires both. When syncing is requested, + export or download after the final 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 @@ -71,14 +98,27 @@ not by itself complete the conversion. ## Repo conventions -- Keep each completed example in `examples/marimo//` with the - notebook named `.py`. +- Follow the parent branch's placement convention. In the conversion workflow, + keep notebooks in `marimo/convert//.py`; do not + move them into `examples/marimo/` merely because cleanup is complete. Preserve + other existing locations unless the user requests relocation. +- Do not add per-notebook READMEs, reports, or other repository artifacts unless + requested. The notebook itself is the teaching surface. - Treat the notebook `.py` as authoritative; never edit its generated `.md` export. - Do not commit runtime-generated files such as `data/`, `wandb/`, `artifacts/`, `__marimo__/`, model weights, or similar outputs. - Use `.logs/` only for diagnosis; final notebooks and docs must not depend on them. +- Preserve source comments, docstrings, lesson order, and model demonstrations; + do not editorialize teaching code during conversion. Follow + [`tutorial-notebook-objectives.md`](references/tutorial-notebook-objectives.md). +- Keep molab launch badges and useful cross-notebook links, targeting converted + files. Remove obsolete Colab self-links and `@wandbcode` HTML markers using + [`convert-cleanup.md`](references/convert-cleanup.md#notebook-links-and-html-markers). +- Treat a request covering all notebooks as a repository-wide marimo scan, + not just the current batch. Do not edit the original `.ipynb` sources or + generated session files unless they are explicitly in scope. ## Review-only tasks @@ -97,24 +137,48 @@ Give a concrete fix for each issue. Do not modify files unless asked. ## Final verification +Scale verification to the change. For a narrow prose, link, or marker cleanup, +check every changed file, verify link targets, and confirm executable code is +unchanged; do not retrain models for a documentation-only edit. Distinguish +pre-existing diagnostics from new regressions. For conversions and runtime +repairs, validate the affected execution path as well as static validity. + 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. +- 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). +- Compare every notebook in the requested scope with its source, including + nested callbacks and small inline comments. Confirm that removed cells were + obsolete or empty, not missing teaching steps. +- 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 and docs do not depend on `.logs/`. +- Each converted notebook has one molab badge pointing to itself. Cross-links + resolve to the intended converted notebook and the requested published ref; + use `main` when explicitly preparing links for after merge. - Opening the notebook and changing unsubmitted controls do not create W&B objects or other remote side effects. - Each submission performs its intended remote writes once; re-submission 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..992f68d5 100644 --- a/.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md +++ b/.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md @@ -25,25 +25,145 @@ 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. -- Prefer explicit markdown cells for prose. Do not leave tutorial text inside - code comments or string literals in logic cells. +- 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. +- Use explicit markdown cells for newly added narrative. Preserve source code + comments and docstrings in place; do not move or rewrite them as prose. ## Common Check Failures - Circular dependencies often come from imports or helper names returned by a later cell and consumed by an earlier helper cell. Fix by moving shared - imports/constants into `app.setup(...)` or into the helper cell that uses - them, and avoid returning imported symbols from downstream logic cells. + imports into setup or the helper that uses them, and avoid returning imported + symbols from downstream logic cells. Pass educational configuration as + arguments instead of hoisting it away from its teaching step. - `multiple-definitions` errors can happen after moving the same import into multiple cells. Keep cell-local imports private with an underscore alias such as `from torch.utils.data import DataLoader as _DataLoader`. +## Notebook Links and HTML Markers + +Classify links before removing them: + +- A Colab badge linking to the source of this same notebook should become one + **Open in molab** badge targeting its converted `.py`, near the top. Remove + duplicate "original Colab tutorial" links rather than keeping both versions. +- A link to a different tutorial in this repository should target that + tutorial's converted notebook when available. Preserve the useful cross-link + and surrounding explanation. Resolve shortened URLs before mapping them; + the label can be stale or the redirect can point back to the current notebook. +- External scientific attribution, upstream project references, and official + documentation are distinct from obsolete self-links. Preserve them unless + the user requests their removal. If a tutorial has no converted counterpart, + report that gap rather than inventing a target. + +Use the existing badge shape: + +```markdown +[![Open in molab](https://marimo.io/molab-shield.svg)](https://molab.marimo.io/github/wandb/examples/blob/REF/marimo/convert/EXAMPLE/NOTEBOOK.py/server) +``` + +Substitute the real repository-relative path and requested Git ref. For testing +from a branch, verify the published remote branch and file; a local branch name +can differ from its upstream. When the user says to assume the PR is merged, +use `main`. Validate that the intended converted file exists and distinguish +links intended for after merge from links verified live today. Do not claim a new +`main` URL works before the file is merged. + +Remove W&B HTML tracking comments such as ``, +including the `` variant. If nothing remains in that +markdown cell, remove the whole cell. If a banner, logo, prose, or other content +remains, keep it. Do not confuse these markers with ordinary Python comments. + +For repository-wide cleanup, inventory all marimo notebooks, not just the +current batch. Check for direct Colab URLs and short links such as +`wandb.me/sweeps-colab`, verify converted targets, and confirm each converted +tutorial has a self-link badge without duplicates. Keep generated `.md`, +`__marimo__` snapshots, and original `.ipynb` sources outside the edit scope +unless explicitly requested. + +## Hosted Runtime and Accelerator Checks + +Local success does not establish molab compatibility. When a hosted notebook +fails, inspect versions and imported module locations in its actual kernel, +including preinstalled packages and the Python version. Dependency-panel labels +or PEP 723 metadata alone do not prove which modules are currently loaded. + +- For a PyTorch-only Transformers tutorial, an installed TensorFlow/Keras stack + can trigger an unrelated optional-backend import failure. When applicable to + the installed Transformers version, set `os.environ["USE_TF"] = "0"` before + any Transformers import. Do not add `tf-keras` to a PyTorch lesson just because + the optional backend's traceback recommends it. A previously imported module + may cache availability; account for that when validating the repair. +- For ordinary PyTorch device selection, prefer CUDA when available, then Apple + MPS, then CPU. MPS keeps the existing PyTorch model and training code; MLX is a + different implementation, not a device switch. Validate the operations used + by the notebook, including export when featured, on the backend being added. +- A pytest fixture error on a helper named `test` can be notebook test discovery, + not a model evaluation failure. Inspect the classification and existing + training result before retraining; see + [`marimo-idioms.md`](marimo-idioms.md#separate-teaching-orchestration-and-helpers). + +### Repairing a running notebook + +When pairing on a live session, use the available `marimo-pair` skill and its +code-mode API for durable edits. Inspect current API help instead of assuming +private kernel attributes are stable. Use the supplied session credentials +without printing them or storing them in notebook code. + +Before changing a helper, inspect its downstream cells and submitted controls. +In autorun mode, even a helper rename can rerun training or create another W&B +run. Prefer temporary lazy execution or another supported means of limiting +execution to the cells under repair, and restore the original execution mode +afterward. Preserve trained models, results, and unrelated user edits. Use +cached data and local capture/offline logging to validate a media or evaluation +repair when another remote run is unnecessary. Do not finish or restart the +user's active run solely to perform a read-only check. + +When the request includes the local copy, apply the verified live fix locally +too and check both artifacts. A full requested sync should preserve exported +cell order and metadata; a narrow repair should not overwrite unrelated local +changes. Do not commit or push unless requested. + +## 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 +181,20 @@ 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 ``` + +For a conversion or runtime repair, 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. + +For a narrow prose, link, or marker edit, verify the affected presentation and +targets and confirm executable code is unchanged. Do not rerun training solely +for that edit; report unrelated existing diagnostics separately. diff --git a/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md b/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md index 87ebb5b7..5071e46b 100644 --- a/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md +++ b/.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md @@ -12,8 +12,12 @@ this repo. - Add PEP 723 metadata with `requires-python` and every runtime package the notebook imports, using repository-approved minimum version constraints such as `"marimo>=0.9"` and `"wandb>=0.18"`. -- Use one setup/import cell for shared imports, true constants, and environment - detection. +- Use one setup/import cell for shared imports and environment detection. Keep + educational parameters beside the lesson steps that use them rather than + collecting them in setup merely because they are constants. +- Keep the setup cell's code visible. It is the reader-facing inventory of + shared imports and runtime setup; do not apply + `hide_code=True` to it. - Keep reactive notebook globals scarce. ## Separate Teaching, Orchestration, and Helpers @@ -33,14 +37,36 @@ 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. 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. + +Preserving an identifier has a runtime exception: marimo's pytest integration +can classify an evaluation helper named `test` as a test and request fixtures +for its parameters. Use `evaluate` for ordinary model evaluation when this +collision occurs, update callers and the corresponding prose, and preserve the +function body and comments. Verify with pytest installed; installing pytest or +inventing fixtures is not a fix for accidental collection. ## 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 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. @@ -105,12 +131,55 @@ 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, 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 + 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. + +### Model inspection + +Preserve an explicit construction/inspection cell near the model definition. +For a supported PyTorch module, the cell can end with: + +```python +model = MNIST_LitModule(n_layer_1=128, n_layer_2=128) +model +``` + +This lets marimo render its native model viewer. If training creates another +notebook-global model, give that result a distinct name such as `trained_model` +instead of deleting the preview to avoid a duplicate definition. Keep downloads +and training gated; an architecture preview need not start a W&B run. + +Check the actual formatter for each framework before replacing `model.summary()` +with `model`. In the tested marimo 0.24.2 runtime, Keras models rendered only an +object representation, so retaining `model.summary()` was appropriate. Recheck +support in the target version; do not add Graphviz/pydot or a custom viewer just +to imitate native PyTorch display unless that extra work is requested. ## 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..c9d99ea6 100644 --- a/.agents/skills/marimo-wandb-notebooks/references/tutorial-notebook-objectives.md +++ b/.agents/skills/marimo-wandb-notebooks/references/tutorial-notebook-objectives.md @@ -6,7 +6,14 @@ Use this when creating, reviewing, or polishing W&B example notebooks. - Treat these notebooks as tutorials, not just runnable apps. - Preserve the original lesson flow, explanatory code, and teaching surface - unless it is broken, duplicative, unsafe, or Jupyter-only. + unless a specific incompatibility or the user's request requires a change. +- Preserve original comments and docstrings verbatim, including short inline + comments and comments inside class methods and callbacks. Do not paraphrase, + shorten, or delete them as a style cleanup. Adapt only comments made inaccurate + by a required code change; remove obsolete installation or Jupyter directives. +- Audit the whole requested batch against the source `.ipynb` cells, not just + top-level functions or files already edited. Record any necessary exceptions + in the work summary rather than adding an unsolicited audit file to the repo. - Keep customer-facing teaching code close to ordinary Python/Colab style. Marimo orchestration should support the lesson without becoming part of the code the reader is expected to learn. @@ -15,26 +22,50 @@ Use this when creating, reviewing, or polishing W&B example notebooks. - Do not collapse the tutorial into opaque helpers. Use named functions when they make the taught workflow clearer, but keep the implementation the reader is meant to learn inspectable. +- Keep educational configuration beside the step it explains. For example, + introduce `MODEL_NAME` near model/tokenizer selection and `BLOCK_SIZE` near + token grouping; uppercase spelling does not make them setup-cell constants. +- Keep model classes, construction, and inspection at their original teaching + position. A preview such as `model = ConvNet(...)` followed by `model` is part + of the lesson, even when training later constructs a fresh instance. ## Narrative Structure - 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. +- Preserve existing heading wording and intentional decorations unless asked + to restyle them; conversion is not an editorial rewrite. +- Preserve the W&B features banner, branding, explanatory diagram, and useful + Docs/Resources sections. Reuse the existing notebook pattern, including theme + support where present; do not replace the banner with a short prose summary. +- Do not put local launch commands such as `uvx marimo edit ... --sandbox`, pip + instructions, or explanations of script metadata into the reader's molab + flow. Remove sections that exist only for local installation. Keep relevant + hardware, download, data, and authentication guidance. Dependency declarations + belong in PEP 723 metadata; maintainer validation commands belong in this skill. - 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 named helper. -- Move reusable plumbing, model classes, and long utilities into named helpers, - preferably under a `## Helper functions` section near the bottom. +- Move implementation-only plumbing into helpers when useful. Do not move model + classes or other featured teaching code to a bottom helper section just to + make the notebook resemble a script. ## 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..a9bfad4c 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. @@ -26,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 @@ -36,6 +55,29 @@ active across cells, finish any prior active run before starting another one. re-submission, clean up any prior active run and make stateful remote updates idempotent when practical, such as skipping an alias or Registry link that is already present. +- Preserve the established authentication, entity, and run-name form patterns + across related notebooks. Respect a blank name when it intentionally lets + W&B generate one; do not replace it with a fixed name during cleanup. + +### 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 @@ -69,6 +111,56 @@ marimo orders cells through name dependencies; it cannot observe mutations to - Move non-teaching plumbing into helpers when it improves the teaching surface. +## Image Values and Media Verification + +Check serialized media, not just whether a logging call succeeds or a file +exists. A completed training run can still contain unusable images. + +- Undo the dataset's normalization for display, then convert explicitly to + 8-bit pixels in `[0, 255]` before passing image arrays/tensors to `wandb.Image` + or `WandbLogger.log_image`. Do not assume the SDK rescales floats in `[0, 1]`; + the observed W&B 0.30 behavior casts them to integers and produces nearly + black pixels. +- For MNIST normalized with mean `0.1307` and standard deviation `0.3081`, the + display conversion is: + + ```python + image = ( + (image.detach().cpu() * 0.3081 + 0.1307) + .clamp(0, 1).mul(255).round().to(torch.uint8) + ) + ``` + + Use the actual dataset's normalization, and modify only the display copy, + not the tensors used for training. +- Share the corrected images between image-panel and Table logging, preserving + captions, labels, and predictions. Validate both paths with real SDK image + serialization and cached examples, without another training run if possible. +- Inspect RGB/grayscale pixels, excluding alpha when measuring range: an opaque + alpha channel of 255 can hide that all color pixels are only 0 or 1. Compare + against the source image where practical and visually inspect a saved sample. +- Explain that a code repair affects future uploads; it does not restore pixel + information already lost in existing remote media. Do not overwrite a run's + history or launch another run merely to make old images look correct. + +When evaluating a saved PyTorch model after its W&B run has finished, remember +that `wandb.watch` hooks may still refer to the finished run. A fresh instance +loaded with the same `state_dict` can validate predictions without those hooks; +do not modify the user's trained object just to run a diagnostic probe. + +## 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