Skip to content

docs(release-audit): 0.8.0-rc.1 artifact cleanup - #311

Merged
RyanTheRobothead merged 3 commits into
unstablefrom
release-audit/0.8.0-cleanup
May 5, 2026
Merged

docs(release-audit): 0.8.0-rc.1 artifact cleanup#311
RyanTheRobothead merged 3 commits into
unstablefrom
release-audit/0.8.0-cleanup

Conversation

@RyanTheRobothead

@RyanTheRobothead RyanTheRobothead commented May 5, 2026

Copy link
Copy Markdown
Member

Summary

Three-commit cleanup from the 0.8.0-rc.1 release artifact audit.

docs(release-audit): fill CHANGELOG gaps and remove dead example-lab config

docs(tutorials): rewrite 04-first-workcell and 05-full-lab against real client APIs
The audit found both tutorials referenced fabricated APIs that don't exist in the codebase. Both files were rewritten so every snippet actually runs:

  • WorkcellClient(base_url=) -> positional URL or workcell_server_url=; start_workflow(workflow_path=, parameters=) -> start_workflow(workflow_definition=, json_inputs=) (which already awaits by default); wait_for_workflow/list_workflow_runs/result.outputs replaced with real APIs (get_active_workflows/get_archived_workflows, walking workflow.steps[i].result.json_result).
  • EventClient(base_url=) -> EventClient(event_server_url=); query_events(limit=20) -> get_events(number=20); event field accessors corrected to event_timestamp/log_level/event_type/event_data.
  • Workflow YAML: switched from the silently-discarded dict-of-params format to the simplified [{name, type, default}] list, removed the fabricated outputs: block, and used the canonical parameters: { args: ... } form for parameter injection. The fabricated Jinja-templated condition: and parallel: blocks in "Workflow Features" were replaced with structured conditions: [{condition_type: resource_present, ...}] and the canonical feed_forward parameter pattern.
  • Tutorial 05 Steps 5-8: replaced fabricated ResourceTemplate/ResourceInstance, client.create_template/create_resource, LocationClient.create_location(name=, location_type=, capacity=), DataClient.create_collection/store_data, and the entire fabricated FullLabExperiment class with real APIs (Container + init_template + create_resource_from_template; get_location_by_name/create_location_from_template/get_locations; submit_datapoint(ValueDataPoint(...)) + query_datapoints({...}); the canonical ExperimentScript pattern with inherited clients and Cls.main(lab_server_url=...)).

docs(release-audit): apply review fixes to tutorials and CHANGELOG (review pass)

  • Tutorial 04: added key: measure to the measure_temperature step so callers can pull its datapoint by step key.
  • Tutorial 04: replaced fabricated --json-input k=v CLI flag with the real --parameters '{...}' JSON flag from madsci workflow submit.
  • Tutorial 05: replaced contextlib.suppress(Exception) around pop() with an explicit deck_resource.quantity > 0 check, so the example doesn't model the broad-except anti-pattern this PR's new pre-commit checker is designed to catch. Dropped the now-unused contextlib and WorkflowDefinition imports.
  • Tutorial 05: changed step_key="measurement" to step_key="measure" to match the key now set in the tutorial 04 YAML, and guarded workflow.get_datapoint(...) with a KeyError handler since it raises rather than returning None.
  • CHANGELOG: flattened the #### Sub-heading groupings under ### Added to bullet form to match the rest of the 0.8.0+ section style.

Test plan

  • All from madsci.* imports in tutorial snippets resolve (python -c-checked each one).
  • Container(...), ValueDataPoint(...), ExperimentDesign(...), the ExperimentScript subclasses, and the WorkflowDefinition.model_validate(...) calls all parse against the current Pydantic models.
  • All four workflow YAML snippets (the main sample_collection workflow, the parameters: { args: ... } substitution, the conditions: [{condition_type: resource_present}] example, and the feed_forward data-passing example) validate against WorkflowDefinition.
  • Updated sample_collection YAML re-validates against WorkflowDefinition; measure_temperature step now has key="measure".
  • Every Python snippet in both tutorials passes ast.parse(...) after the review-fix edits (5 blocks in tutorial 04, 4 in tutorial 05).
  • LocationManagerSettings() loads against the trimmed examples/example_lab/settings.yaml and resolves lab_config_file=locations.yaml correctly.
  • Bundled template tests: 311/311 pass (pytest src/madsci_common/tests/test_templates/test_template_engine.py -q).
  • Manual run of the example lab against the trimmed settings.yaml to confirm location reconciliation works end-to-end (recommended before merge).

🤖 Generated with Claude Code

RyanTheRobothead and others added 2 commits May 4, 2026 14:47
…config

The 0.8.0-rc.1 release audit found several artifacts out of sync with the code.

CHANGELOG `[Unreleased]`: added entries for the transfer-graph detailed
view + dashboard redesign (#290), the bundled-template `_shared/` file
deduplication (#270), the node try/except pre-commit checker (#273), the
object-storage unique-key fix closing #274 (#276), the `madsci new --name`
interactive fix and lab compose image corrections (#292), and the SiLA
connection-error diagnostics enrichment.

Example lab `settings.yaml`: removed the inline `location_locations:` block
(149 lines). `LocationManagerSettings` no longer exposes a `locations` field;
locations are now declared via `locations.yaml` (`LabLocationConfig`) and node
`intrinsic_locations`. The block was silently discarded by Pydantic.

Example lab `README.md`: updated the structural-data table and the lab-config
section to describe the reconcilable `LabLocationConfig` model and where
each piece of configuration now lives.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…al client APIs

The release audit found that the tutorials referenced fabricated APIs that
don't exist in the codebase. Rewrote the affected sections so the snippets
actually run.

`docs/tutorials/04-first-workcell.md`:
- `WorkcellClient(base_url=...)` -> positional `WorkcellClient(url)` with
  `workcell_server_url` keyword form documented in the imports.
- `start_workflow(workflow_path=, parameters=)` -> `start_workflow(
  workflow_definition=, json_inputs=)` (with `await_completion=True` default,
  removing the fabricated `wait_for_workflow`).
- Workflow result accessor: `final_result.outputs[...]` -> walking
  `workflow.steps[i].result.json_result[...]`.
- Workflow YAML: switched from the silently-discarded dict-of-params format
  to the simplified `[{name, type, default}]` list, removed the fabricated
  `outputs:` block, and used `parameters: { args: ... }` for parameter
  injection (canonical use_parameters form).
- "List recent workflow runs" -> `get_active_workflows()` /
  `get_archived_workflows()`.
- `EventClient(base_url=)` -> `EventClient(event_server_url=)`;
  `query_events(limit=20)` -> `get_events(number=20)`; event field accessors
  updated to `event_timestamp`/`log_level`/`event_type`/`event_data`.
- "Workflow Features" section: replaced the Jinja2-templated condition and
  parallel-step examples (neither is supported) with structured `conditions:`
  using `condition_type: resource_present`, and replaced the Jinja-templated
  data-passing example with the canonical `feed_forward` parameter pattern.
- Step 9 `SampleCollectionExperiment` rewritten to inherit `ExperimentScript`
  properly (override `run_experiment`, use the inherited `self.workcell_client`
  / `self.logger`, dispatch via `Cls.main(lab_server_url=...)` classmethod).

`docs/tutorials/05-full-lab.md` Steps 5-8:
- Step 5 (Resources): replaced fabricated `ResourceTemplate`/`ResourceInstance`
  types and `client.create_template`/`create_resource` methods with
  `Container` resource type, `ResourceClient.init_template()` and
  `create_resource_from_template()` (the actual idempotent template API).
- Step 6 (Locations): replaced fabricated `create_location(name=, location_type
  =, capacity=, parent_location=)` with the canonical declarative
  `locations.yaml` (`LabLocationConfig`) approach, plus
  `LocationClient.get_location_by_name()`, `create_location_from_template()`,
  and `get_locations(managed_by=)`.
- Step 7 (Data Capture): replaced fabricated `create_collection`/`store_data`
  with `DataClient.submit_datapoint(ValueDataPoint(...))` and
  `query_datapoints({selector})`. Added a note on `FileDataPoint` for files.
- Step 8 (Full Experiment): rewrote the `FullLabExperiment` class to use the
  real `ExperimentScript` pattern (inherited clients, `run_experiment` hook,
  `Cls.main(lab_server_url=...)` entrypoint), removing fabricated calls to
  `query_resources`, `update_status`, `get_resource_location`,
  `wait_for_workflow`, `result.outputs`, `data.store_data`, and
  `move_resource`.

Verified: all snippet imports resolve, all Pydantic constructions parse, and
the workflow YAML examples validate against `WorkflowDefinition`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@github-actions

github-actions Bot commented May 5, 2026

Copy link
Copy Markdown

Coverage report

This PR does not seem to contain any modification to coverable code.

- Tutorial 04: add `key: measure` to the measure_temperature step so
  callers (tutorial 05) can pull its datapoint by step key.
- Tutorial 04: replace fabricated `--json-input k=v` CLI flag with the
  real `--parameters '{...}'` JSON flag from `madsci workflow submit`.
- Tutorial 05: replace `contextlib.suppress(Exception)` with an
  explicit `deck_resource.quantity > 0` check before popping, so the
  example doesn't model the broad-except anti-pattern this PR's new
  pre-commit checker is designed to catch. Drops the now-unused
  `contextlib` and `WorkflowDefinition` imports.
- Tutorial 05: change `step_key="measurement"` to `step_key="measure"`
  to match the key now set on the workflow YAML in tutorial 04, and
  guard `get_datapoint(...)` with a `KeyError` handler since it raises
  rather than returning None.
- CHANGELOG: flatten the `#### Sub-heading` groupings under
  `### Added` to bullet form to match the rest of the 0.8.0+ section
  style.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@RyanTheRobothead
RyanTheRobothead merged commit 64b9d4c into unstable May 5, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant