docs: scaffold PyAutoLens-Assistant JOSS paper

[Jammy2211]

Overview

Create a current-format JOSS manuscript for PyAutoLens-Assistant in the autolens_assistant repository. The paper will explain how a domain-specific natural-language and agentic interface translates gravitational-lensing science goals into explicit, inspectable, and reproducible PyAutoLens workflows.

Plan

• Add a dedicated paper/ manuscript directory to autolens_assistant.
• Use the exact approved title and author-supplied Summary.
• Follow current JOSS metadata and required-section conventions.
• Scaffold sections around the Assistant's architecture, safety, reproducibility, scientific use, and benchmark evidence.
• Seed a focused bibliography and add drafting/build guidance.
• Validate the manuscript structure and compile it with JOSS tooling where available.

Detailed implementation plan

Affected Repositories

• autolens_assistant (primary)

Branch Survey

Repository	Current Branch	Dirty?
./autolens_assistant	main	1 untracked benchmark-run directory

Suggested branch: feature/pyautolens-assistant-joss-paper

Work Classification: Workspace

Worktree root: ~/Code/PyAutoLabs-wt/pyautolens-assistant-joss-paper/

Current conflict: benchmark-calibration claims autolens_assistant on feature/benchmark-calibration; preserve its untracked benchmark outputs and wait for that task to release the repository.

Implementation Steps

1. Add paper/paper.md with current JOSS YAML, the exact title, the supplied Summary and Statement of need, required sections, and explicit drafting prompts.
2. Scaffold Assistant-specific coverage of natural-language analysis, the instructions/skills/wiki architecture, API and real-data safety gates, reproducible science-project workflows, supported interfaces, and the frozen benchmark protocol.
3. Add paper/paper.bib with verified starter references for PyAutoLens and the software/AI systems cited by the manuscript.
4. Add paper/README.md with a drafting checklist and official Inara build instructions, plus paper/.gitignore for generated PDF output.
5. Validate metadata, section structure, citation keys, and PDF compilation without modifying existing benchmark results or Assistant content.

Key Files

• paper/paper.md — JOSS manuscript template and supplied prose.
• paper/paper.bib — focused starter bibliography.
• paper/README.md — drafting checklist and compilation instructions.
• paper/.gitignore — generated paper output.

Verification

• Confirm all pre-existing autolens_assistant files and benchmark outputs are unchanged.
• Validate YAML front matter, required JOSS sections, and all cited BibTeX keys.
• Compile with the official openjournals/inara image when Docker is available.

Original Prompt

Click to expand starting prompt

Set up the PyAutoLens-Assistant JOSS paper

Type: docs
Target: autolens_assistant
Repos:

• autolens_assistant
  Difficulty: small
  Autonomy: supervised
  Priority: normal
  Status: formalised

Request

Create a current-format JOSS paper template for PyAutoLens-Assistant with the title:

PyAutoLens-Assistant: Using Natural Language and AI to Analyse Gravitational Lenses

Place the manuscript in the autolens_assistant repository so that the JOSS paper is hosted with the software it describes. Preserve all existing assistant content and benchmark outputs.

Summary draft supplied by the author

Summary

Stage IV weak-lensing surveys, such as Euclid and the Vera C. Rubin Observatory, are measuring increasingly large samples of galaxies, while strong-lensing searches are discovering rapidly growing numbers of galaxy-, group-, and cluster-scale lenses. These systems are observed through optical and infrared imaging, radio interferometry, point-source measurements of lensed quasars and supernovae, and weak-lensing shear catalogues, enabling studies of cosmology, dark matter, galaxy formation, and the early Universe. Mature open-source software such as PyAutoLens supports simulations, lensing calculations, and strong- and weak-lensing modelling across these datasets, but constructing a bespoke analysis can still require substantial effort to locate, adapt, and combine the relevant examples using the correct Python API and syntax.

PyAutoLens-Assistant allows scientists to use natural language to describe the gravitational-lens analysis they want to perform. It provides a domain-specific interface to the documented and tested capabilities of PyAutoLens, supporting simulations, ray-tracing calculations, probabilistic modelling, data preparation, result interpretation, and visualization. Researchers can use it through a conversational AI assistant, such as ChatGPT, to ask questions and develop workflows interactively, or through agentic coding tools, such as Claude Code or Codex, which can inspect data, write and execute scripts, diagnose errors, analyse outputs, and iteratively refine an analysis. PyAutoLens-Assistant is grounded in curated, version-controlled documentation, examples, scientific reference material, and task-specific instructions, and produces explicit Python code and inspectable analysis products.

Statement of need draft supplied by the author

Statement of Need

Experienced PyAutoLens users often know exactly which scientific analysis they want to perform, but implementing it still requires substantial time assembling the appropriate Python workflow. An expert can quickly specify: “Perform multi-wavelength lens modelling of the F115W, F150W, F277W, and F444W JWST imaging of the COSMOS-Web Ring using a multi-Gaussian expansion lens-light model, a singular isothermal ellipsoid plus external shear mass model, and a Delaunay pixelized source reconstruction.” Translating this concise scientific specification into executable code requires locating and combining several examples, loading and configuring each dataset, composing the model components with the correct API, and adapting the workflow to the system being analysed. As models incorporate more datasets, cluster-scale mass distributions, or joint strong- and weak-lensing constraints, this implementation burden increases even when the underlying scientific choices are already clear. PyAutoLens-Assistant reduces this overhead by translating natural-language specifications into explicit, executable, and reproducible PyAutoLens workflows.

New users face a complementary challenge: they may not yet know which modelling approach, software abstractions, or examples are appropriate for the task they are learning. PyAutoLens has grown from galaxy-scale imaging analyses to support point-source lenses, group- and cluster-scale systems, weak lensing, interferometry, simulations, and joint analyses, accompanied by well over one hundred worked examples across the autolens_workspace. Navigating this material while simultaneously learning gravitational-lensing science, Bayesian inference, and the PyAutoLens API can be overwhelming. PyAutoLens-Assistant enables users to describe their immediate goal in natural language and receive targeted explanations, example code, and pointers to the relevant documentation. Its teaching mode also explains the underlying science and numerical methods, encourages follow-up questions, and supports learning rather than simply returning code.

Original request verbatim

ok, the second paper is PyAutoLens-Assistant and its title is PyAutoLens-Assistant: Using Natural Language and AI to Analyse Gravitational Lenses, make another JOSS paper and template

[Jammy2211]

Merge status — blocked by active repository claim

The companion PyAutoLens-JAX paper has shipped, but this paper cannot yet be promoted from its planned state because autolens_assistant is still claimed by the active benchmark-calibration task (#59).

Current evidence (2026-07-14):

• claimed branch: feature/benchmark-calibration
• branch state: 2 commits ahead of and 12 commits behind origin/main
• main checkout contains untracked benchmarks/runs/assistant-easy-cosmos-web-ring/ results

No Assistant-paper source files were written and no benchmark state was changed. Once #59 is shipped, parked, or its repo claim is explicitly released, the approved JOSS draft can be assembled and shipped from its own feature/pyautolens-assistant-joss-paper worktree.

[Jammy2211]

Shipped — 2026-07-15

PRs

• docs: JOSS paper for PyAutoLens-Assistant #71

Summary

Scaffolded paper/ with the JOSS manuscript for PyAutoLens-Assistant: Using Natural Language and AI to Analyse Gravitational Lenses, mirroring the PyAutoLens-JAX sibling in PyAutoLens/paper_jax/. The four sections drafted by the author previously existed only inside the PyAutoMind prompt file; they are now a real manuscript (paper.md, 1309 words — inside the JOSS 750–1750 target) alongside paper.bib, a README.md drafting checklist, and a .gitignore for the local PDF build.

This issue was previously blocked by the autolens_assistant repo claim held by the benchmark-calibration task (#59). That issue is now closed and the claim released, so the paper was assembled from its own feature/pyautolens-assistant-joss-paper worktree as planned.

Session Notes

Decisions

• Benchmarks reframed as "three representative examples" rather than adding a fourth paragraph. The repo ships four prompts; hard_group_multi.md is deliberately not described. This resolves the drafting note in the prompt (author's call), and the README records the framing so prose and prompt set can't silently diverge.
• Author block mirrors the JAX paper (sole corresponding author, ORCID 0000-0002-8987-7401). "Confirm full author list" is on the drafting checklist.
• SLACS0946+1006 → SDSSJ0946+1006 — the name used by both cited papers (Vegetti2010, Minor2021) and by the literature wiki. Worth a look if the SLACS form was deliberate.

Bibliography provenance
All 6 entries were extracted verbatim from wiki/literature/bibliography/autolens_literature.bib rather than written from memory — fabricated or mistyped citations are the one failure mode a paper cannot absorb. Vegetti2010 (original substructure detection) and Minor2021 (the high-concentration claim the medium benchmark actually tests) were the two worth getting exactly right.

Gotchas / open items

• Benchmark results remain unclaimed. benchmarks/RESULTS.md records zero runs for all four benchmarks, so the Benchmark Examples section stays future-tense. Notably research: first benchmark calibration campaign — cross-model runs + rubric verdict #59 (the first benchmark calibration campaign) is closed, yet no runs are recorded — worth confirming whether results exist elsewhere and simply weren't ingested.
• State of the field and Research impact statement are commented stubs. JOSS requires both; neither can be drafted without author judgement, and the repo cannot currently evidence the impact section.
• The Inara PDF build was not run — Docker is not installed in this environment. Build locally before submission (command in paper/README.md).
• No pending-release label — it doesn't exist on this repo, isn't covered by ensure_workspace_labels.sh, and recent merged PRs (docs: science projects use dataset/ not data/ (workspace convention) #70, fix: re-stamp content_sha256 for analysis_objects wiki page (unblock wiki-currency) #68, docs: fix dead iterations_per_update in wiki (use quick/full_update) #66) carry none. The label guards the library-first merge gate, which doesn't apply to a docs-only PR.

Validation
make validate-literature-citations passes; audit_skill_apis.py passes (58 files, 120 symbols, 0 missing/broken); all 6 citation keys resolve 1:1 against the bib with no unused entries; YAML front-matter parses with all required JOSS keys. Heart was YELLOW (score 55, no RED) at ship time, acknowledged by the author; both reasons pre-date this branch and are unrelated to a docs-only change.