Export ML Notebook
Source of truth stays the # %% .py. This skill only writes
derived .ipynb (and optional .nb.html). Do not rewrite the
.py from the notebook. cells run is not a substitute.
Human-facing prose
Details: setup-workspace references/human_facing_prose.md.
Tell the user the written .ipynb (and HTML viewer) paths. Do
not quote notebook convert, --html, or site build as
something they should run.
While policy.notebooks is true, explore-ml-data fills the
analysis file it wrote. model-ml-pipeline and
evaluate-ml-pipeline fill the experiment script and, when it
exists, audit/<stem>.py, with empty outputs.
audit-ml-pipeline fills audit/<stem>.py only on a direct
close. This skill owns on-demand fills, other sources, and
turning the flag on when it is null or false. A data-analysis,
experiment, or audit source uses notebook fill, not
notebook convert.
Workflow checkpoint execution
Stage owners read policy before executing a human # %% source.
Only policy.notebooks true enables automatic notebook
materialization; null and false keep the stage's non-notebook
execution and do not change policy.
When true, exploratory analysis uses materialize.py as its
one run, then notebook fill writes the .ipynb with empty
outputs. Add --html only when policy.site is also true. An
experiment or audit file is the same: notebook fill writes the
.ipynb with empty outputs, and materialize.py is the run that
writes the digest and the HTML viewers. Do not notebook convert
those files and do not cells run them. Kernel notebook convert
stays only for a source that is itself the execution (the unfitted
experiment snapshot). A generated notebook records its source
fingerprint; loop notebooks fills or converts again only when
the source or required HTML changed.
Lookup
Run status and read policy.notebooks. Take the first row that
matches. Fill leaves code-cell outputs empty. Do not stop after
reading the table.
policy.notebooks |
Request |
Then |
null |
any |
step 2, then match this table again. Do not take the convert row only because it is listed first. |
false |
any |
step 3. Do not fill until the policy is true. |
true |
the user asked for HTML, a site viewer, or the notebook on the site |
step 4 notebook fill --html, then step 5. data_analysis/, experiments/<stem>.py, and audit/<stem>.py stay notebook fill, not notebook convert. |
true |
the source is itself the execution (unfitted experiment snapshot, before skore.evaluate) and the user did not ask for HTML or a site viewer |
kernel notebook convert, not notebook fill |
true |
notebook, ipynb, or convert, with no HTML and no site viewer |
step 4 notebook fill only. No --html. No site build. |
Sequence
python -m skore_skills status. Read policy.notebooks and
skills.
If policy.notebooks is null: persist
python -m skore_skills policy set notebooks true. Do not
AskUserQuestion. Then load add-python-package for jupytext
and nbformat (agent) and continue.
If policy.notebooks is false: say notebooks are off; offer
to turn them on. Do not fill until the policy is true.
Fill the requested percent file (default data_analysis/data_analysis.py when
the user did not name one):
python -m skore_skills notebook fill data_analysis/data_analysis.py
Fill does not execute the file and leaves code-cell outputs
empty. It needs jupytext and nbformat, not nbclient,
ipywidgets, or IPython. Do not start EDA, an evaluation, or
an audit from this skill to produce those outputs.
experiments/<stem>.py and audit/<stem>.py are filled the
same way. Missing jupytext / nbformat / nbconvert stays
a one-line skip.
If the user wants the notebook on the site, load
add-python-package for nbconvert (agent) and pass --html
(writes a self-contained <stem>.nb.html next to the .py).
The site links that file from the associated exploratory data
analysis or design report. It opens as a page of its own.
Optional --out path.ipynb. Keep *.ipynb gitignored unless
the user asks setup-git to track them.
Fill-only requests (notebook / ipynb / convert, no HTML or
site viewer): run only that notebook fill line, with no
--html. Tell the user the written .ipynb path. Do not
mention --html or site build as an optional aside.
Kernel notebook convert is only for a source that is itself
the execution: the unfitted experiment snapshot, before
skore.evaluate exists. Convert injects %matplotlib inline
for that kernel run so seaborn / matplotlib last expressions
emit image/png, then strips that setup cell from the written
notebook. Do not put %matplotlib inline in the .py
(style / ruff would reject it). If that convert fails
because ipywidgets is missing, load add-python-package
for it (agent) and convert again.
After --html, if policy.site is true, export-ml-site
is installed, run python -m skore_skills site build --if-stale so the
viewer is packaged. Run --html and site build only
when the user asked for HTML or a site viewer. Fill
without --html does not rebuild the site. Skip in one line
otherwise. If site build errors with mkdocs-material is required, load add-python-package for mkdocs-material
(agent) and build once more. Do not pixi add / uv add.
If that skill is missing, or the retry still fails, name the
error in one line. Name a build error; do not fail the
fill, and do not claim the website was updated. When the
build ran, say the website has been updated and paste the
file:// line from that output verbatim. Do not name the
markdown file
or the HTML viewer path. Do not quote the CLI.
Stop conditions
- Do not
git commit or git end-turn.
- Do not run
cells run as a substitute for fill.
- Do not
pixi add / uv add; load add-python-package.
- Missing skill or missing source → one-line skip.
- Do not name
--html or python -m skore_skills site build
unless the user asked for HTML or a site viewer. Tell the user
paths, not the CLI.
1---2name: export-ml-notebook3description: >4 Write a jupytext percent file out as a notebook with empty outputs.5 `data_analysis/`, `experiments/`, and `audit/` are filled with empty6 outputs. Pass `--html` when that notebook should also become a viewer on the7 site. Kernel `notebook convert` stays for a source that is itself the8 execution. Trigger on notebook, ipynb, HTML, or executed-report requests, or9 when export-ml-project dispatches notebooks.10metadata:11 source: https://skillmd.com/skills/probabl-ai/export-ml-notebook12 modelTier: small13---1415# Export ML Notebook1617Source of truth stays the `# %%` `.py`. This skill only writes18derived `.ipynb` (and optional `.nb.html`). Do not rewrite the19`.py` from the notebook. `cells run` is not a substitute.2021## Human-facing prose2223Details: `setup-workspace` `references/human_facing_prose.md`.24Tell the user the written `.ipynb` (and HTML viewer) paths. Do25not quote `notebook convert`, `--html`, or `site build` as26something they should run.2728While `policy.notebooks` is true, `explore-ml-data` fills the29analysis file it wrote. `model-ml-pipeline` and30`evaluate-ml-pipeline` fill the experiment script and, when it31exists, `audit/<stem>.py`, with empty outputs.32`audit-ml-pipeline` fills `audit/<stem>.py` only on a direct33close. This skill owns on-demand fills, other sources, and34turning the flag on when it is `null` or false. A data-analysis,35experiment, or audit source uses `notebook fill`, not36`notebook convert`.3738## Workflow checkpoint execution3940Stage owners read policy before executing a human `# %%` source.41Only `policy.notebooks` `true` enables automatic notebook42materialization; `null` and `false` keep the stage's non-notebook43execution and do not change policy.4445When true, exploratory analysis uses `materialize.py` as its46**one run**, then `notebook fill` writes the `.ipynb` with empty47outputs. Add `--html` only when `policy.site` is also true. An48experiment or audit file is the same: `notebook fill` writes the49`.ipynb` with empty outputs, and `materialize.py` is the run that50writes the digest and the HTML viewers. Do not `notebook convert`51those files and do not `cells run` them. Kernel `notebook convert`52stays only for a source that is itself the execution (the unfitted53experiment snapshot). A generated notebook records its source54fingerprint; `loop notebooks` fills or converts again only when55the source or required HTML changed.5657## Lookup5859Run `status` and read `policy.notebooks`. Take the first row that60matches. Fill leaves code-cell outputs empty. Do not stop after61reading the table.6263| `policy.notebooks` | Request | Then |64|---|---|---|65| `null` | any | step 2, then match this table again. Do not take the convert row only because it is listed first. |66| `false` | any | step 3. Do not fill until the policy is `true`. |67| `true` | the user asked for HTML, a site viewer, or the notebook on the site | step 4 `notebook fill --html`, then step 5. `data_analysis/`, `experiments/<stem>.py`, and `audit/<stem>.py` stay `notebook fill`, not `notebook convert`. |68| `true` | the source is itself the execution (unfitted experiment snapshot, before `skore.evaluate`) and the user did not ask for HTML or a site viewer | kernel `notebook convert`, not `notebook fill` |69| `true` | notebook, ipynb, or convert, with no HTML and no site viewer | step 4 `notebook fill` only. No `--html`. No `site build`. |7071## Sequence72731. `python -m skore_skills status`. Read `policy.notebooks` and74 `skills`.752. If `policy.notebooks` is `null`: persist76 `python -m skore_skills policy set notebooks true`. Do not77 AskUserQuestion. Then load `add-python-package` for `jupytext`78 and `nbformat` (agent) and continue.793. If `policy.notebooks` is false: say notebooks are off; offer80 to turn them on. Do not fill until the policy is true.814. Fill the requested percent file (default `data_analysis/data_analysis.py` when82 the user did not name one):8384 ```bash85 python -m skore_skills notebook fill data_analysis/data_analysis.py86 ```8788 Fill does not execute the file and leaves code-cell outputs89 empty. It needs jupytext and nbformat, not nbclient,90 ipywidgets, or IPython. Do not start EDA, an evaluation, or91 an audit from this skill to produce those outputs.92 `experiments/<stem>.py` and `audit/<stem>.py` are filled the93 same way. Missing `jupytext` / `nbformat` / `nbconvert` stays94 a one-line skip.9596 If the user wants the notebook on the site, load97 `add-python-package` for `nbconvert` (agent) and pass `--html`98 (writes a self-contained `<stem>.nb.html` next to the `.py`).99 The site links that file from the associated exploratory data100 analysis or design report. It opens as a page of its own.101102 Optional `--out path.ipynb`. Keep `*.ipynb` gitignored unless103 the user asks `setup-git` to track them.104105 Fill-only requests (notebook / ipynb / convert, no HTML or106 site viewer): run **only** that `notebook fill` line, with no107 `--html`. Tell the user the written `.ipynb` path. Do not108 mention `--html` or `site build` as an optional aside.109110 Kernel `notebook convert` is only for a source that is itself111 the execution: the unfitted experiment snapshot, before112 `skore.evaluate` exists. Convert injects `%matplotlib inline`113 for that kernel run so seaborn / matplotlib last expressions114 emit `image/png`, then strips that setup cell from the written115 notebook. Do not put `%matplotlib inline` in the `.py`116 (`style` / ruff would reject it). If that convert fails117 because `ipywidgets` is missing, load `add-python-package`118 for it (agent) and convert again.1195. After `--html`, if `policy.site` is true, `export-ml-site`120 is installed, run `python -m skore_skills site build --if-stale` so the121 viewer is packaged. Run `--html` and `site build` **only**122 when the user asked for HTML or a site viewer. Fill123 without `--html` does not rebuild the site. Skip in one line124 otherwise. If `site build` errors with `mkdocs-material is125 required`, load `add-python-package` for `mkdocs-material`126 (agent) and build once more. Do not `pixi add` / `uv add`.127 If that skill is missing, or the retry still fails, name the128 error in one line. Name a build error; do not fail the129 fill, and do not claim the website was updated. When the130 build ran, say the website has been updated and paste the131 `file://` line from that output verbatim. Do not name the132 markdown file133 or the HTML viewer path. Do not quote the CLI.134135## Stop conditions136137- Do not `git commit` or `git end-turn`.138- Do not run `cells run` as a substitute for fill.139- Do not `pixi add` / `uv add`; load `add-python-package`.140- Missing skill or missing source → one-line skip.141- Do not name `--html` or `python -m skore_skills site build`142 unless the user asked for HTML or a site viewer. Tell the user143 paths, not the CLI.