From 95eda58955853c1bba4bdff88ec07cb3df405a35 Mon Sep 17 00:00:00 2001 From: Ian Mayo Date: Fri, 19 Jun 2026 17:20:30 +0100 Subject: [PATCH] docs: add PLAYGROUND.md hands-on guide A step-by-step guide for experimenting with the pipeline in a Codespace: edit the example input, re-run the pipeline, poke the CLI/REPL. Includes a section on switching to the real schema in private/ and the pipeline caveat. Co-Authored-By: Claude Opus 4.8 --- PLAYGROUND.md | 138 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 PLAYGROUND.md diff --git a/PLAYGROUND.md b/PLAYGROUND.md new file mode 100644 index 0000000..f5e581c --- /dev/null +++ b/PLAYGROUND.md @@ -0,0 +1,138 @@ +# Playground — having a play with the Python pipeline + +A hands-on guide to experimenting with the code in a Codespace. The example input +(`examples/calculation_input.xml`) is your sandbox: edit it, re-run the pipeline, and +watch the validated output change. + +> Everything below works through one CLI (`acoustic`, i.e. `python -m acoustic_dataset.cli`). +> The `make` targets are just documented shortcuts over it. + +## Step 0 — Open the Codespace and let it bootstrap + +When you create the Codespace, the devcontainer automatically runs `make bootstrap` +(installs deps + generates models). Wait for the terminal to show `Bootstrap complete.`, +then confirm everything's healthy: + +```bash +make verify # ruff + mypy + pytest — should be all green +``` + +> If you ever recreate the venv by hand, run `make bootstrap` first — the `acoustic` +> command and `make pipeline`/`make verify` only work once the package is installed +> into the environment. In a fresh Codespace this is automatic. + +## Step 1 — Run the pipeline once to see the baseline + +```bash +make pipeline +``` + +This maps `examples/calculation_input.xml` → typed objects → XML → validates → round-trips, +and writes `build/acoustic_dataset.xml`. You'll see something like +`pipeline ok: 10 band(s) -> build/acoustic_dataset.xml`. Open `build/acoustic_dataset.xml` +to see the expanded, validated dataset. + +## Step 2 — Edit the input and re-run (the fun part) + +Open `examples/calculation_input.xml` and change a value — e.g. bump `10` to +`20`, or change `140.0` to `155.0`. Then: + +```bash +make pipeline +``` + +The band count in the output message and the generated XML change accordingly. This is the +tightest feedback loop: input XML in, validated dataset out. + +**Try breaking it on purpose** to see the gates work. Set `` to a negative number, +or put text where a number goes, and re-run — the build/validation gate rejects it, prints the +error, exits non-zero, and does **not** write a stale artifact. + +## Step 3 — Poke the CLI directly + +The Makefile just wraps the `acoustic` command. Call it yourself for full control over +inputs/outputs: + +```bash +acoustic --help # see all subcommands +acoustic pipeline --input examples/calculation_input.xml --out build/mine.xml +acoustic validate --xml build/mine.xml +acoustic compare build/mine.xml examples/reference/trial_known_good.xml +``` + +`compare` tells you whether your output is *canonically identical* to the known-good +reference, not just schema-valid. + +## Step 4 — Explore in a Python REPL + +To play with the actual objects rather than the CLI: + +```bash +python +``` + +```python +from acoustic_dataset import build, serialize +model = build.build_platform_from_file("examples/calculation_input.xml") +model.radiated_noise.band[:3] # inspect the expanded bands +print(serialize.to_xml(model)[:500]) # see the serialized XML +``` + +This drops you into the dataclasses generated from the schema, so you can introspect the +data model interactively. + +## Step 5 — If you change the schema + +If you edit anything in `schema/*.xsd`, regenerate the typed models (otherwise CI's drift +gate will fail): + +```bash +make generate # regenerate models from the XSD +make gen-schema-docs # regenerate the HTML schema reference +``` + +## Quick reference for a play session + +1. Edit `examples/calculation_input.xml` +2. `make pipeline` +3. Look at `build/acoustic_dataset.xml` +4. Repeat — or drop into `python` for the object model + +--- + +## Switching to the real schema + +Everything above runs against the **placeholder** schema committed in `schema/`. The real, +proprietary XSD and corpus live in `private/` — a folder that is **entirely gitignored** and +must never reach git, CI, or the internet. (See `private/README.md`.) + +The key constraint: `src/acoustic_dataset/models/` is **committed** (the placeholder-generated +models that CI drift-checks). Generating from the real schema into that location would +overwrite it with real structure, and an accidental commit would leak it. So real-generated +models go into `private/models/` instead. + +Once the real material is dropped into `private/` (real XSD in `private/schema/`, real inputs +in `private/examples/`, known-good XML in `private/reference/`), point the same CLI at those +paths: + +```bash +# 1. Generate typed models from the real XSD into the gitignored output dir +acoustic generate --schema private/schema/.xsd --out private/models + +# 2. Validate a real XML file against the real schema (structural gate + round-trip) +acoustic validate --xml private/examples/.xml --schema private/schema/.xsd + +# 3. Migration-safety compare: generated vs known-good reference +acoustic compare private/models/.xml private/reference/.xml +``` + +### Caveat: the full `pipeline` command + +`acoustic pipeline` imports `acoustic_dataset.models` — the **committed** package — so it always +uses the placeholder-derived bindings, even when you pass `--schema private/...`. To run the +*full* end-to-end pipeline on real-generated models, that import would need to point at +`private/models/`. **Ask before wiring that up**, since it touches committed code and risks +leaking real structure into the repo. + +In short, with the real schema you can immediately use `generate`, `validate`, and `compare` +against `private/` paths; the end-to-end `pipeline` needs a deliberate (reviewed) change first.