From a418e3d3034a21e221689ef382982827bcce71eb Mon Sep 17 00:00:00 2001 From: Jammy2211 Date: Fri, 23 Oct 2026 12:16:19 +0100 Subject: [PATCH] docs: add the PyAutoLabs AI options page for every assistant (#87) One canonical page covering Claude Code, Codex, the free routes (GitHub Copilot CLI and OpenCode), troubleshooting, Colab and chat with a GitHub connector. Linked from the README next to the AI policy. Co-Authored-By: Claude Fable 5.1 --- AI_OPTIONS.md | 221 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 2 + 2 files changed, 223 insertions(+) create mode 100644 AI_OPTIONS.md diff --git a/AI_OPTIONS.md b/AI_OPTIONS.md new file mode 100644 index 0000000..72874f9 --- /dev/null +++ b/AI_OPTIONS.md @@ -0,0 +1,221 @@ +# PyAutoLabs AI Options + +Every PyAutoLabs science assistant runs inside an **AI coding agent**: a tool that reads the assistant +repository, runs Python on your computer and looks at the results. That is what lets the assistant install +the software, plot your data, run fits and check the figures they produce. You do not have to run anything +to use it. Asking questions, planning an analysis and learning in Teacher Mode happen in the same agent. + +This page covers every assistant. Pick an agent below, then go back to your assistant's README for its +starting prompt. + +| Assistant | Repository | Library | +|-----------|------------|---------| +| PyAutoLens Assistant | [autolens_assistant](https://github.com/PyAutoLabs/autolens_assistant) | strong gravitational lensing | +| PyAutoGalaxy Assistant | [autogalaxy_assistant](https://github.com/PyAutoLabs/autogalaxy_assistant) | galaxy morphology and structure | +| PyAutoFit Assistant | [autofit_assistant](https://github.com/PyAutoLabs/autofit_assistant) | probabilistic model fitting | +| PyAutoCTI Assistant | [autocti_assistant](https://github.com/PyAutoLabs/autocti_assistant) | charge transfer inefficiency | + +**The short version.** Claude Code and Codex are recommended and both are paid. GitHub Copilot CLI and +OpenCode are free ways to try an assistant. A browser chat with a GitHub connector is good for reading and +discussion, but it cannot run code. Prices and quotas below are as of October 2026; check the linked +provider pages, because they change often. + +In the commands below, replace `` with the repository name from the table, for example +`autolens_assistant`. + +## Claude Code (recommended, paid) + +Claude Code is Anthropic's coding agent. It runs in the terminal, a desktop app and IDE extensions. It +reads the assistant's `AGENTS.md` instructions and registers the code-gate hook from the project settings +(`.claude/settings.json`). The hook blocks stale library API written from memory before it runs. + +**What you need.** A Claude subscription (Pro or Max, or a Team or Enterprise seat), usage billing through +the Claude Console, or a cloud provider your institution already uses (Amazon Bedrock, Google Cloud, +Microsoft Foundry). See Anthropic's [cost page](https://code.claude.com/docs/en/costs). Sustained science +is heavy use, so budget for it. + +**Install and sign in.** Follow [code.claude.com/docs](https://code.claude.com/docs). Then: + +```bash +git clone https://github.com/PyAutoLabs/.git +cd +claude +``` + +The assistant configures itself on your first prompt and installs its library if it is missing. + +**Start from any directory.** Cloning first is optional. Open Claude Code in any folder, even an empty one, +and paste your assistant's starting prompt. The prompt names the repository, so the agent clones it, reads +`AGENTS.md` and installs the library. Approve the `git clone` and `pip install` requests. Hooks and project +settings only load when Claude Code is launched inside the folder, so in that session the agent checks its +code against the installed library by hand. Relaunch `claude` inside the cloned folder for the full setup. + +**Tested coverage.** Claude Code is the most thoroughly exercised agent. The assistants are developed in it, +and it has run them end to end, from installing the library to fits and HPC workflows. + +## Codex (recommended, paid) + +Codex is OpenAI's coding agent (CLI, IDE extension and cloud). It reads the shared `AGENTS.md` +instructions. Each assistant exposes its `skills/` through generated `.codex/skills/` adapters, and the +tracked `.codex/hooks.json` registers the code gate. + +**What you need.** Codex is included in ChatGPT plans, and the Free plan lists it for quick coding tasks +([pricing](https://learn.chatgpt.com/docs/pricing)). As of October 2026, CLI access on Free is not +confirmed and Free limits are unpublished. For sustained science, plan on Plus or above, or API billing. + +**Install and sign in.** Follow [developers.openai.com/codex](https://developers.openai.com/codex). Then: + +```bash +git clone https://github.com/PyAutoLabs/.git +cd +codex +``` + +After cloning, and after any change to the hooks, run `/hooks` and trust the current hash of +`.codex/hooks.json`. Codex skips project hooks until you do. For local development setup, use +`source activate.sh`. + +**Start from any directory.** Open Codex in any folder and paste your assistant's starting prompt. The +default sandbox blocks network access, and the clone and install need it. Approve the network request when +Codex asks, or start it with network enabled: +`codex --sandbox workspace-write -c sandbox_workspace_write.network_access=true`. +Codex reads `AGENTS.md` and registers hooks only at launch, so relaunch `codex` inside the cloned folder +for the full setup. + +**Tested coverage.** Codex discovery and the safety adapters are checked with an installed Codex CLI, and +guard tests cover the setup. Full science fits still need to be exercised in your own environment. The +[harness smoke record](https://github.com/PyAutoLabs/PyAutoBrain/blob/main/docs/agent_harness_smoke.md) +describes the measured scope. + +## Free options + +Every free route is for trying the assistant, not sustained science: quotas are small and free models +change without notice. Both routes below are supported and documented, but not benchmarked against the +assistants. Neither has a hook system the assistants use, so the code gate is self-enforced: the assistant +should run its `autoassistant/audit_skill_apis.py` check on generated code before executing it. If it +skips this, ask it to. + +### GitHub Copilot CLI + +**What is free.** Every Copilot plan includes Copilot CLI, including Copilot Free +([plans](https://docs.github.com/en/copilot/get-started/plans)). Copilot Free gives an allowance of GitHub +AI Credits (the amount is unpublished) and automatic model selection only. Verified students get the +Copilot Student plan at no cost, also with automatic model selection +([GitHub Education](https://github.com/education/students)). Many researchers already have Copilot access +through GitHub Education or their institution. + +**Install.** See [Installing GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli). +For example `npm install -g @github/copilot`, `brew install --cask copilot-cli`, or +`curl -fsSL https://gh.io/copilot-install | bash`. Then: + +```bash +git clone https://github.com/PyAutoLabs/.git +cd +copilot +``` + +On first launch, run `/login` if prompted. + +**Caveats.** You cannot choose the model on Free or Student, so quality varies from session to session. +Copilot CLI is expected to read `AGENTS.md`; tell it to read `AGENTS.md` in full if it does not. + +### OpenCode + +**What is free.** [OpenCode](https://opencode.ai/docs/) is an open-source (MIT) coding agent. The client +is free and the model is a separate choice. Its hosted provider, [OpenCode Zen](https://opencode.ai/docs/zen/), +listed 13 free models in October 2026 (for example Big Pickle, GLM-5.3-Flash Free and DeepSeek V4.1 Flash +Free). All are described as free for a limited time. Zen's setup asks you to add billing details before +copying your API key, so a card may be requested even for free models. Any other provider key also works, +including a paid Claude or OpenAI key. + +**Install.** + +```bash +curl -fsSL https://opencode.ai/install | bash +git clone https://github.com/PyAutoLabs/.git +cd +opencode +``` + +Run it from the repository root so it reads `AGENTS.md`. + +**Caveats.** Pick a model that supports tool use and image input; check the model card, not the name. +Many free models have no vision input, so the assistant cannot check its own figures, and every fit check +involves looking at a PNG. A quick test: ask it to plot the dataset and describe what it sees. A model +that cannot view the figure will describe the code instead. + +If you try a free route, please open an issue on the assistant's repository with the agent, model, date +and what worked or failed. + +## Troubleshooting + +Known failure modes in any coding agent. If you hit something else, open an issue on the assistant's +repository. + +**It wrote API that no longer exists** (for example `aplt.FitImagingPlotter(...)` or `aplt.MatPlot2D(...)`). +Older library versions dominate model training data. On Claude Code and Codex the code gate blocks this. +Elsewhere, ask it to re-read the relevant skill, rewrite the code, and run +`python autoassistant/audit_skill_apis.py --file