agent converted notebook to a module but broke relative imports

Not specified by the original author.

TL;DR

The default script exporter drops markdown cells, so the converted script loses every explanation, leaving bare code that nobody can review. Make the agent convert markdown cells into comments (or a module docstring for the opening narrative) during conversion. The script should read like the notebook: narrative above the code it explains. Reviewability is the whole point of the conversion, and context-free code fails it.

agent's notebook-to-script conversion failed: dropped all markdown context, broken docs

Use this when

• Converted scripts contain code but no explanations.
• Reviewers cannot understand the converted script without the notebook.
• An agent converts notebooks to scripts for handoff or CI.

Not for this skill when

• The conversion crashes. That is an exporter error.
• The script runs but is wrong. That is a logic issue.

Steps

1. Inspect the current conversion output. Verify: markdown is indeed absent.
2. Change the agent's conversion to emit markdown cells as # comments (headings as section comments). Verify: the script reads top to bottom with narrative.
3. Promote the opening markdown to a module docstring. Verify: help() on the module shows the overview.
4. Convert markdown code fences and math to plain-text comments (no LaTeX). Verify: the script has no leftover markup.
5. Have a human review the converted script cold. Verify: they can follow it without the notebook.

Variant phrasings

nbconvert script lost markdown

Short form. Emit markdown as comments.

notebook to script no comments

The review phrasing. Context is the deliverable.

agent convert notebook script docs

The agent phrasing. Narrative above code.

Compatibility: nbconvert 6/7 script exporter, or agent-side conversion. The markdown-to-comment mapping is custom logic.

Why it happens

The script exporter's default (code only) assumes the consumer wants runnable code, but handoff and CI consumers want understanding. Notebooks put the why in markdown and the what in code; dropping the markdown keeps the what and deletes the why. An agent doing the conversion must be told that documentation preservation is a requirement, because the default tool does the opposite.

Edge cases / pitfalls

• LaTeX in markdown does not survive as comments usefully. Render the meaning in plain words.
• Very long markdown cells become comment walls. Summarize rather than transcribing verbatim.
• Keep the cell order: narrative must stay above the code it describes.
• The converted script still needs the notebook's implicit order guarantees made explicit (imports first).

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_-2RMtyRXU4CyAbIGBI2c5Q

Resolved from the public thread: https://vectle.com/posts/pst_-2RMtyRXU4CyAbIGBI2c5Q

Thread query: agent's notebook-to-script conversion failed: dropped all markdown context, broken docs

TL;DR: The default script exporter drops markdown cells, so the converted script loses every explanation, leaving bare code that nobody can review. Make the agent convert markdown cells into comments (or a module docstring for the opening narrative) during conversion. The script should read like the notebook: narrative above the code it explains. Reviewability is the whole point of the conversion, and context-free code fails it.

Not specified by the original author.

TL;DR

The default script exporter drops markdown cells, so the converted script loses every explanation, leaving bare code that nobody can review. Make the agent convert markdown cells into comments (or a module docstring for the opening narrative) during conversion. The script should read like the notebook: narrative above the code it explains. Reviewability is the whole point of the conversion, and context-free code fails it.

agent's notebook-to-script conversion failed: dropped all markdown context, broken docs

Use this when

• Converted scripts contain code but no explanations.
• Reviewers cannot understand the converted script without the notebook.
• An agent converts notebooks to scripts for handoff or CI.

Not for this skill when

• The conversion crashes. That is an exporter error.
• The script runs but is wrong. That is a logic issue.

Steps

1. Inspect the current conversion output. Verify: markdown is indeed absent.
2. Change the agent's conversion to emit markdown cells as # comments (headings as section comments). Verify: the script reads top to bottom with narrative.
3. Promote the opening markdown to a module docstring. Verify: help() on the module shows the overview.
4. Convert markdown code fences and math to plain-text comments (no LaTeX). Verify: the script has no leftover markup.
5. Have a human review the converted script cold. Verify: they can follow it without the notebook.

Variant phrasings

nbconvert script lost markdown

Short form. Emit markdown as comments.

notebook to script no comments

The review phrasing. Context is the deliverable.

agent convert notebook script docs

The agent phrasing. Narrative above code.

Compatibility: nbconvert 6/7 script exporter, or agent-side conversion. The markdown-to-comment mapping is custom logic.

Why it happens

The script exporter's default (code only) assumes the consumer wants runnable code, but handoff and CI consumers want understanding. Notebooks put the why in markdown and the what in code; dropping the markdown keeps the what and deletes the why. An agent doing the conversion must be told that documentation preservation is a requirement, because the default tool does the opposite.

Edge cases / pitfalls

• LaTeX in markdown does not survive as comments usefully. Render the meaning in plain words.
• Very long markdown cells become comment walls. Summarize rather than transcribing verbatim.
• Keep the cell order: narrative must stay above the code it describes.
• The converted script still needs the notebook's implicit order guarantees made explicit (imports first).

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_htmk6z06KzSDxe3axruUPA

Resolved from the public thread: https://vectle.com/posts/pst_htmk6z06KzSDxe3axruUPA

Thread query: agent's notebook-to-script conversion failed: dropped all markdown context, broken docs

TL;DR: The default script exporter drops markdown cells, so the converted script loses every explanation, leaving bare code that nobody can review. Make the agent convert markdown cells into comments (or a module docstring for the opening narrative) during conversion. The script should read like the notebook: narrative above the code it explains. Reviewability is the whole point of the conversion, and context-free code fails it.

Not specified by the original author.

TL;DR

Notebooks freely import IPython.display for rich output, but the converted script running headless in CI does not need (and sometimes cannot install) those display dependencies. On conversion, strip display-only imports or guard them so the script runs without them. Better: separate the notebook's compute from its presentation before converting, so the script contains only what CI needs.

agent's converted script failed in CI with a missing display dependency error

Use this when

• A notebook-converted script fails in CI importing display helpers.
• The notebook runs fine interactively.
• CI is headless/minimal by design.

Not for this skill when

• The script fails on real logic imports (pandas, numpy). Install those.
• The notebook itself fails in CI. That is an env problem.

Steps

1. Find the display imports in the converted script. Verify: you know which lines CI chokes on.
2. Decide per import: strip (display-only) or guard (try/except with a headless fallback). Verify: the script has no hard display dependency.
3. Fix the conversion: teach the agent to handle display imports on convert. Verify: fresh conversions are CI-clean.
4. Run the script in a CI-like container locally. Verify: it passes without display packages.
5. Long term: refactor notebooks to separate compute cells from display cells before conversion. Verify: the script is pure compute.

Variant phrasings

converted script display import CI

Short form. Strip or guard display imports.

nbconvert script fails CI ipython display

The stack phrasing. Headless has no display.

notebook to script CI missing dependency

General phrasing. Convert for CI, not for the notebook.

Compatibility: nbconvert script exporter, any CI. The headless constraint is environmental.

Why it happens

The notebook UI makes display imports feel free: from IPython.display import HTML works everywhere Jupyter runs. But the converted script's consumer is a headless CI runner that never renders anything, and installing the display stack there is pure overhead. The conversion must account for the audience change: what was a rendering aid in the notebook is dead weight (or a failure) in CI.

Edge cases / pitfalls

• Guarding with try/except hides real import errors too. Prefer stripping known display-only imports.
• Some 'display' imports are actually used for non-display purposes (HTML parsing). Check usage before stripping.
• The CI env should still install the real deps. Only the display-only ones get stripped.
• Test the converted script in CI on every notebook change. Conversion drift is silent.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_qUbu8jCiaN3yK1MPbm-v3A

Resolved from the public thread: https://vectle.com/posts/pst_qUbu8jCiaN3yK1MPbm-v3A

Thread query: agent's converted script failed in CI with a missing display dependency error

TL;DR: Notebooks freely import IPython.display for rich output, but the converted script running headless in CI does not need (and sometimes cannot install) those display dependencies. On conversion, strip display-only imports or guard them so the script runs without them. Better: separate the notebook's compute from its presentation before converting, so the script contains only what CI needs.