Overview
The assistant generates scripts in the PyAutoLens narrative-docstring style (title docstring + __Contents__, per-section """__Section__""" docstrings — #6), adopted precisely because conversion to notebooks is mechanical: each top-level docstring block becomes a markdown cell, the code between becomes code cells. Add a converter + a wrapping skill so a user can say "turn this into a notebook". Notebook-form projects are also friendlier artifacts for the shareable/open-source-paper story (#45).
Reference implementation found (per the prompt's reuse-first rule): PyAutoBuild autobuild/build_util.py::py_to_notebook + autobuild/add_notebook_quotes.py (docstring→# %% markers, then external ipynb-py-convert). Adapt, don't import: assistant users have neither PyAutoBuild nor a guaranteed ipynb-py-convert install, and the semantics are ~70 stdlib lines — so ship a self-contained module citing the PyAutoBuild converter as reference.
Plan
autoassistant/to_notebook.py — stdlib-only converter (json output, nbformat-v4 schema): top-level """/''' docstring blocks → markdown cells; code between → code cells; CLI python -m autoassistant.to_notebook <script.py> [out.ipynb].skills/al_to_notebook.md — user-invocable skill wrapping it (Orient/Ask/Branch/Combine per _style.md), registered in skills/README.md + .claude/skills/ symlink per _bootstrap_skill.md.- End-to-end verification on a real narrative-docstring script; sanity-compare cell split against the PyAutoBuild pipeline output on the same input.
Detailed implementation plan
Affected Repositories
- autolens_assistant (primary, only)
Branch Survey
| Repository |
Current Branch |
Dirty? |
| ./autolens_assistant |
main (post-#50) |
clean (untracked personal james.bib, untouched) |
Suggested branch: feature/script-to-notebook (in-place, no worktree)
Implementation Steps
autoassistant/to_notebook.py: line-scanner mirroring add_notebook_quotes semantics (a line starting with triple quotes toggles docstring mode — matching the generated-script style contract); accumulate markdown/code cells; strip trailing blank lines per cell; emit nbformat v4 JSON (nbformat: 4, nbformat_minor: 5, python3 kernelspec); module docstring cites PyAutoBuild:autobuild/build_util.py + add_notebook_quotes.py as the adapted reference.- Unit-light check in
autoassistant/tests/ if the existing test layout invites it (inspect first); otherwise CLI verification only.
skills/al_to_notebook.md: triggers ("turn this into a notebook", "convert to ipynb", "make a Colab/Jupyter version"); Branch = run the CLI, report the output path, offer to open; note it expects the workspace narrative-docstring style and that notebooks are never hand-edited afterwards (regenerate from the script).- Register in
skills/README.md (complete recipes section) + .claude/skills/al_to_notebook.md symlink.
Validation
- Convert a real generated-style script (e.g.
autolens_workspace start_here.py or an assistant scripts/ example): valid JSON, loads via nbformat.read in the PyAuto venv, cell-type sequence matches the docstring/code alternation.
- Cross-check cell count/types against PyAutoBuild's
py_to_notebook output for the same input (dev-venv only).
--check-citations clean.
Key Files
autoassistant/to_notebook.py (new), skills/al_to_notebook.md (new), skills/README.md, .claude/skills/
Original Prompt
Click to expand starting prompt
Now that autolens_assistant generates scripts in the PyAutoLens narrative-docstring style (title + Contents header, per-section """Section""" docstrings — see issue #6), we should add a script -> notebook converter to the assistant. The style was adopted precisely because it makes conversion mechanical: each top-level docstring block becomes a markdown cell; the Python code between docstring blocks becomes a code cell. This mirrors how autolens_workspace converts its start_here.py scripts to the matching start_here.ipynb notebooks. Look at how the workspace already does this before writing anything new — there is very likely an existing converter in autolens_workspace (or its build tooling) we can reuse or adapt rather than re-implement. What I want: a converter (a work/-style tool or a small module) that takes a generated .py in the narrative-docstring style and emits a .ipynb with the cell split above; a skill (e.g. al_to_notebook.md) wrapping it, so a user can say "turn this into a notebook" after the assistant produces a script; end-to-end verification on a real generated script. Cite the workspace converter as the reference if one exists; only build from scratch if it genuinely doesn't.
Overview
The assistant generates scripts in the PyAutoLens narrative-docstring style (title docstring +
__Contents__, per-section"""__Section__"""docstrings — #6), adopted precisely because conversion to notebooks is mechanical: each top-level docstring block becomes a markdown cell, the code between becomes code cells. Add a converter + a wrapping skill so a user can say "turn this into a notebook". Notebook-form projects are also friendlier artifacts for the shareable/open-source-paper story (#45).Reference implementation found (per the prompt's reuse-first rule): PyAutoBuild
autobuild/build_util.py::py_to_notebook+autobuild/add_notebook_quotes.py(docstring→# %%markers, then externalipynb-py-convert). Adapt, don't import: assistant users have neither PyAutoBuild nor a guaranteedipynb-py-convertinstall, and the semantics are ~70 stdlib lines — so ship a self-contained module citing the PyAutoBuild converter as reference.Plan
autoassistant/to_notebook.py— stdlib-only converter (json output, nbformat-v4 schema): top-level"""/'''docstring blocks → markdown cells; code between → code cells; CLIpython -m autoassistant.to_notebook <script.py> [out.ipynb].skills/al_to_notebook.md— user-invocable skill wrapping it (Orient/Ask/Branch/Combine per_style.md), registered inskills/README.md+.claude/skills/symlink per_bootstrap_skill.md.Detailed implementation plan
Affected Repositories
Branch Survey
Suggested branch:
feature/script-to-notebook(in-place, no worktree)Implementation Steps
autoassistant/to_notebook.py: line-scanner mirroringadd_notebook_quotessemantics (a line starting with triple quotes toggles docstring mode — matching the generated-script style contract); accumulate markdown/code cells; strip trailing blank lines per cell; emit nbformat v4 JSON (nbformat: 4, nbformat_minor: 5, python3 kernelspec); module docstring citesPyAutoBuild:autobuild/build_util.py+add_notebook_quotes.pyas the adapted reference.autoassistant/tests/if the existing test layout invites it (inspect first); otherwise CLI verification only.skills/al_to_notebook.md: triggers ("turn this into a notebook", "convert to ipynb", "make a Colab/Jupyter version"); Branch = run the CLI, report the output path, offer to open; note it expects the workspace narrative-docstring style and that notebooks are never hand-edited afterwards (regenerate from the script).skills/README.md(complete recipes section) +.claude/skills/al_to_notebook.mdsymlink.Validation
autolens_workspacestart_here.pyor an assistantscripts/example): valid JSON, loads vianbformat.readin the PyAuto venv, cell-type sequence matches the docstring/code alternation.py_to_notebookoutput for the same input (dev-venv only).--check-citationsclean.Key Files
autoassistant/to_notebook.py(new),skills/al_to_notebook.md(new),skills/README.md,.claude/skills/Original Prompt
Click to expand starting prompt
Now that autolens_assistant generates scripts in the PyAutoLens narrative-docstring style (title + Contents header, per-section """Section""" docstrings — see issue #6), we should add a script -> notebook converter to the assistant. The style was adopted precisely because it makes conversion mechanical: each top-level docstring block becomes a markdown cell; the Python code between docstring blocks becomes a code cell. This mirrors how autolens_workspace converts its start_here.py scripts to the matching start_here.ipynb notebooks. Look at how the workspace already does this before writing anything new — there is very likely an existing converter in autolens_workspace (or its build tooling) we can reuse or adapt rather than re-implement. What I want: a converter (a work/-style tool or a small module) that takes a generated .py in the narrative-docstring style and emits a .ipynb with the cell split above; a skill (e.g. al_to_notebook.md) wrapping it, so a user can say "turn this into a notebook" after the assistant produces a script; end-to-end verification on a real generated script. Cite the workspace converter as the reference if one exists; only build from scratch if it genuinely doesn't.