Skip to content

Developer maintenance

The public workbench is kept consistent through shared definitions and explicit boundaries. The shared workflow explanation shows their execution order and reproducibility limits.

  • arguments.py owns scientific defaults, units, choices, constraints and reusable argument groups. Generated types and help consume these definitions.
  • ACTION_REGISTRY, the callable scientific catalogue in actions.py, binds methods to those definitions. It remains independent of the web server, persistence and accounts.
  • client.py and contracts.py provide the public calling and result contracts; result_views.py explicitly maps measurements, tables and series with units.
  • run_records.py captures completed-call evidence. Records never supply defaults for a later call, and replay refuses changed inputs or software.
  • figure_definitions.py declares figure content. result_figures.py builds figures from completed results; figure_engine.py resolves display choices from the installed analysis_kit.style house definitions and this figure's options. Plotting must not rerun science or consult prior-plot state.
  • USER_ANALYSES, the reviewed browser catalogue in ui_catalogue.py, selects questions and documentation pages. Web routes adapt requests to the registry; they do not introduce another scientific implementation.
  • Validation manifests declare independent expectations before dispatching the real action. Passing implementation tests alone is not independent validation.

Motion and Auto-Organotypic import the public Workbench interface and select shared argument groups. Do not copy a scientific default or renderer into a consumer. Existing wrappers' explicitly supplied settings remain intentional caller choices; new shared trace entrances use Workbench defaults.

When changing a default, change its central definition, regenerate dependent help/types and test consumers. Treat it as a release change: an old snippet with omitted settings is not guaranteed to produce the same answer after an upgrade. Preserve the recorded version and environment for replay; do not add a historical-default selector or automatically switch implementations.

After changing an action, regenerate the agent reference with python scripts/update_circadian_references.py and run its --check mode. After changing the user catalogue, add or update the matching analysis page and run python scripts/check_docs.py.

The real-browser suite is opt-in through the e2e pytest marker. It uses an isolated data root, starts the actual loopback server, drives Microsoft Edge, captures traces only on failure, and verifies shutdown.

The MkDocs source is docs/site/; the built site is written to src/circadian_workbench/static/docs/ so the same guide is available inside the installed application at /docs/.