Skip to content

Add user onboarding Jupyter notebooks for BuildCompiler#84

Open
Gonza10V wants to merge 2 commits intofull_buildfrom
codex/create-jupyter-notebooks-for-package-usage
Open

Add user onboarding Jupyter notebooks for BuildCompiler#84
Gonza10V wants to merge 2 commits intofull_buildfrom
codex/create-jupyter-notebooks-for-package-usage

Conversation

@Gonza10V
Copy link
Copy Markdown
Contributor

@Gonza10V Gonza10V commented May 6, 2026

Motivation

  • Provide new users with concise, hands-on guides to install, configure, and use the BuildCompiler package.
  • Surface the primary entry points and stage responsibilities (index_collections, domestication, assembly_lvl1, assembly_lvl2, transformation, plating, full_build) so users can run planning-only or full-build workflows with explicit dependencies.
  • Offer a lightweight, safe introduction to configuration and safety controls via BuildOptions to encourage deterministic, auditable runs.

Description

  • Added five new user-facing notebooks under notebooks/: 01_install_and_setup.ipynb, 02_planning_only_quickstart.ipynb, 03_full_build_minimal.ipynb, 04_options_and_safety.ipynb, and 05_stage_by_stage_guide.ipynb that contain explanatory markdown and small example code snippets referencing the public API.
  • Updated notebooks/notebooks.md to index the new guides and describe their purpose for users browsing the folder.
  • Notebooks are provided as JSON notebook files with minimal, non-executing example code to avoid requiring heavy runtime dependencies.

Testing

  • Validated notebook JSON structure for representative files with python -m json.tool notebooks/01_install_and_setup.ipynb, which succeeded.
  • Validated notebook JSON structure for representative files with python -m json.tool notebooks/05_stage_by_stage_guide.ipynb, which succeeded.
  • No runtime execution tests were run for notebook cells to avoid imposing optional runtime dependencies in this PR.

Codex Task

Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b569decffa

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

"execution_count": null,
"metadata": {},
"outputs": [],
"source": "# Option A (recommended): uv\n# !uv sync --all-groups\n\n# Option B: pip\n# !python -m venv .venv\n# !source .venv/bin/activate\n# !python -m pip install -U pip\n# !python -m pip install -e ."
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Use interpreter-targeted pip commands in notebook setup

The Option B setup sequence relies on !source .venv/bin/activate, but in Jupyter each ! invocation runs in its own subshell, so the activation does not persist to the later pip commands. Users who uncomment this cell will often install dependencies into the wrong interpreter (or global env), which can make the subsequent import check fail and undermines reproducibility. Prefer %pip in-notebook, or call !./.venv/bin/python -m pip ... directly.

Useful? React with 👍 / 👎.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant