Repository navigation
refactor: make Colab setup compact across projects #327
Description
Make Colab setup unobtrusive across projects
Type: refactor
Target: PyAutoHands
Difficulty: medium
Consequence: judge
Primary: @PyAutoHands. Consumers: @autolens_workspace, @autogalaxy_workspace,
@autofit_workspace, @HowToFit, @howtogalaxy, @HowToLens, @autolens_assistant.
Shared implementation: @PyAutoNerves (preserve runtime behavior).
Original request (verbatim)
- This takes up too much space and brain capacity of a user, and should be a single line or the most brief possible
thign which doesnt require them to think about whats actually going on. This should not be the first thing a user
has to think about:
try:
import google.colab
except ImportError:
from autolens import setup_colab as _setup_colab
else:
import importlib
import subprocess
import sys
subprocess.check_call(
[sys.executable, "-m", "pip", "install", "autonerves", "--no-deps"]
)
_setup_colab = importlib.import_module("autonerves.setup_colab")
_setup_colab.for_autolens(
raise_error_if_not_gpu=False # Switch to False for CPU Google Colab
)
Sort this across all projects, it function is important and works as expected but its confusing and a lot of code.
Approved plan
- Present Colab setup as one short run cell labelled "Set up Google Colab", with implementation hidden by default.
- Centralize bootstrap generation and shorten source-script setup to an import and call.
- Apply the presentation consistently to existing handwritten setup and all six generated notebook project families.
- Preserve installation, workspace/config setup, CPU/GPU choices and local execution; validate fresh-session and regeneration behavior.
- Tier: judge — merge mode: human /prm.
Detailed implementation plan
- PyAutoHands
autohands/build_util.py: reviseinject_colab_setup,COLAB_SETUP_CODEandCOLAB_SETUP_MARKDOWN. Use compact notebook presentation (Colab form title and hidden source metadata, Jupyter collapsed-source metadata where supported). Remove the long introductory explainer. Keep fresh-Colab bootstrap self-contained: importing the scientific library before installation is not sufficient. - Recognize supported handwritten
setup_colabcells and normalize them, preserving project and keyword options; avoid duplicate setup and retain surrounding science code. Do not blindly replace arbitrary cells containing the string. Make regeneration idempotent. - Replace duplicated bootstrap blocks in Lens/Galaxy
start_here.pyandscripts/**/start_here.pywith the established short import/call form; shorten adjacent setup prose. Inventory all project sources, including the assistant'sdocs/colab/cosmos_web_ring_colab.py. Generated markdown/notebooks follow their canonical generator, not manual parallel edits. - Cover all
COLAB_PROJECTSkeys: autofit, autogalaxy, autolens, howtofit, howtogalaxy, howtolens. Inventory CTI/Reduce too; do not introduce Colab support where none exists. Preserveautonerves/setup_colab.pybehavior and wrapper API; only change it if investigation establishes necessity within this scope. - Extend
PyAutoHands/tests/test_inject_colab_setup.py: generated and handwritten inputs, preserved options, repeated generation, mixed cells, prose-only notebooks, all projects. Exercise fresh Colab with package imports absent, local no-install behavior, CPU and GPU settings. Use existing Nerves tests and Heart Colab gate contract as behavior references; do not claim hosted Colab testing without running it. - Generate representative artifacts for review, then ship generator changes before consumer changes through the required development workflows. No release or merge authorized.
Evidence and next action
Heart entry gate GREEN (2026-10-28). No matching active/planned Colab task found.
Memory consultation identified prior local-CLI silence and faithful fresh-Colab bootstrap validation; preserve both.
Branch proposal: feature/compact-colab-setup.
Next: user plan approval, branch/claim survey, create_issue registration, isolated worktree setup, implementation and validation.
Approved copy and scope clarification
User approved the plan and these two prose tiers, with the correction “locally or in HTML”.
Introductory: “Run this cell to install PyAutoLens and download the files needed for this notebook on Google Colab. If you’re running locally or in HTML, it leaves your installation unchanged.”
Advanced: “Set up Google Colab as in [the introductory notebook].”
Substitute each project’s name and actual introductory link. Cell title: “Set up Google Colab”. HTML support itself is future work, not part of this change.
Branch survey: PyAutoHands, autolens_workspace, autogalaxy_workspace, autofit_workspace, HowToFit, HowToGalaxy, HowToLens, autolens_assistant all on main, clean; no conflicting active claims. Proposed branch feature/compact-colab-setup.
Activity
Jammy2211 commentedon Oct 28, 2026
Development-only Heart RED override for compact-colab-setup (#327)
User authorization: “I authorize you to continue despite RED”.
Exact current reasons:
Prior validation: 581 PyAutoHands tests passed; six notebook-family previews generated; 15 changed source scripts preserve science AST; real local Lens/Galaxy setup calls pass. Final rollout tests and review are in progress and must pass before shipping.
Authorizes continued implementation, commit, push and opening this task’s PRs. No merge, release, failed-test override or CI bypass.
Jammy2211 commentedon Oct 28, 2026
Library PR Created
Shared generator: #328 (77bbc1e), 584 tests passed. Independent Markdown-preservation finding resolved and rechecked.
Workspace migration is underway: PyAutoLabs/autofit_workspace#178 (79a996a), 32 regenerated notebooks; 8 scripts and 2 notebook smokes passed. All six families regenerated (633 notebooks, 632 compact setup cells); science code and idempotency checked. Remaining consumer smoke suites and assistant pinned-runtime validation are in progress.
The task-specific RED development override is recorded above. No merge or release requested.
Jammy2211 commentedon Oct 28, 2026
Implemented the compact Colab setup rollout. Introductory notebooks use the approved two-sentence explanation (including “locally or in HTML”); advanced examples link back. Installation behavior and CPU/GPU options are preserved. HTML support itself remains future work.
Pull requests
Merge PyAutoHands first, then consumers; the Galaxy assistant guide also follows the Galaxy workspace. No merges or releases performed.
Validation
Heart development override
User: “I authorize you to continue despite RED”. Exact reasons retained:
This authorizes development shipping only; no readiness promotion, merge, release or CI bypass. The initial Hands CI failure was the tenant firewall; fixed in a405d14, local full suite and firewall pass. Fresh CI remains subject to review before merge.
Jammy2211 commentedon Oct 28, 2026
Partial merge — human /prm
Every run/job for each current head was checked. Five fully green PRs merged in dependency order. Four remain open because their
smoke / smokejob was skipped by the shared workflow change filter for generated-notebook-only changes; skipped is not a passing test result. Their local smoke suites passed during development. No failed jobs. Issue and Mind task remain open; worktree and claims retained. No release.Jammy2211 commentedon Oct 29, 2026
Shipped — Colab setup rollout merged
All nine rollout PRs are confirmed merged. The final four merged on 2026-10-29:
Previously merged and re-confirmed: PyAutoHands#328, autogalaxy_workspace#265, autolens_workspace#604, autolens_assistant#167, autogalaxy_assistant#41.
Human authorization in this session: “ok merge them and finish this task”, followed by “yes I do” when explicitly asked to accept the recorded local smoke results as an exception for these four generated-notebook-only PRs. This exception applies only to their skipped
smoke / smokejobs. All other enumerated workflow jobs succeeded; all four heads were unchanged, mergeable/clean, and had no review requests for changes or unresolved review threads. Merged with exact-head guards, without bypassing GitHub protection. Skipped smoke jobs are not reported as passing. Hosted Colab remains untested; no release performed.Repository rollout is complete. Local administrative close-out remains outstanding: Mind lifecycle completion record/active-row release, dashboard regeneration, and worktree cleanup. The local command hook rejects even
pwdbecause/home/jammy/Code/PyAutoLabs/.codex/hooks/validate_pyauto_code.pyis missing. No hook bypass attempted, and no local cleanup claimed. Resume the standard prm close-out for compact-colab-setup once local command access is repaired.