Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
Corpus distribution: prove the wheel ships it, and add the image-payload slice (#1133)
Louis Choquel45b9bbe0f0f1
diff --git a/.vscode/launch.json b/.vscode/launch.jsonindex 4ac1e598e..57771a312 100644--- a/.vscode/launch.json+++ b/.vscode/launch.json@@ -113,7 +113,7 @@"args": ["run","bundle",- "tests/integration/pipelex/pipes/pipelines/test_image_out_in.mthds",+ "tests/integration/pipelex/pipes/pipelines/test_image_inputs.mthds","--pipe","describe_image","--inputs",diff --git a/CHANGELOG.md b/CHANGELOG.mdindex afaac96be..d030f41ef 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,8 +6,12 @@- **The MTHDS Test Corpus: one canonical, tagged set of `.mthds` methods, with coverage of the language surface turned into a gate instead of a thing somebody has to remember**: Every repo in the workspace had grown its own pile of `.mthds` fixtures, each shaped by its own consumer, and coverage of the MTHDS language surface — a cross-repo invariant — was asserted locally in each of them against a private pile. The result was exactly what that arrangement predicts: the `Time` native concept had no pipelex fixture at all, while another repo had independently patched the same gap in its own corpus without either side knowing. The corpus lives at `pipelex/test_extras/mthds_corpus/` and ships in the wheel, so a consumer that already depends on `pipelex` reads it through `iter_entries()` / `get_entry()` with no copy and no drift — lockstep by construction via the pinned version. Each entry is a directory holding the method, an optional `inputs.json`, and an `entry.toml` declaring what it exercises: `covers` (the axes, drawn from a closed vocabulary), `tier` (the cheapest conformance tier at which it is meaningful), `granularity`, and `validity` — plus, for a deliberately invalid entry, the exact wire `error_type` it must produce. Metadata lives beside the bundle and never inside it, so a bundle stays a pure language artifact. The `native.*` tag vocabulary is **generated** from `NativeConceptCode` by `make generate-corpus-vocabulary` and committed, so a consumer reads the closed tag set without a registry walk; the generator itself stays unshipped dev tooling. Three gates hold it: regeneration must reproduce the committed vocabulary byte for byte, every non-excluded tag must have a `focused` entry covering it, and every entry must mean what its manifest claims — a valid one validating, an invalid one failing with exactly its declared error, both checked against the local runtime rather than a deployed API that lags it, and both run over every entry regardless of tier so an `inference`-tier entry that broke is caught without spending a token. The exhaustivity gate is the one that closes the hole: the moment a registry grows a code, regeneration adds its tag and the build stays red until an entry covers it. The corpus is seeded with a focused entry for every native concept, and no code needed excluding — each one turned out to support a real entry. Entry subject matter is ordinary-world by rule, never AI and never MTHDS's own vocabulary, because an entry exists so a red gate can be narrated in one sentence and *"the model output the model"* is not one. The cross-repo contract is the workspace spec `docs/specs/mthds-test-corpus.md`; the working guide is `docs/contribute/mthds-test-corpus.md`.+- **The corpus is proven to ship, against a wheel that is actually built**: wheel consumers reach the corpus through `importlib.resources`, so a corpus that stopped being packaged would be invisible in this repo and would break every consumer at once, on the release. A packaging test builds the real wheel and looks inside it, deriving what it expects from the corpus tree rather than from a list somebody has to maintain — a new entry, a new file kind or a new namespace is covered the moment it lands. It pins both halves of the split at once: the generated `vocabulary.toml` and every entry file ship, and the generator that writes them stays out. No packaging configuration change was needed, which is what the test now holds true rather than assumes.+- **Image-payload corpus entries**, so a consumer that needs an `Image` crossing a pipe boundary has one: a sequence that writes a scene and draws it, and a round trip that produces a photograph and reads it back to caption it. Both are `composite`, both sit at the `inference` tier, and — like every other entry — neither names a model. That is a contract property rather than a preference: presets are resolved by the validation engine, so an entry pinning one would fail validation outright on any consumer whose deck does not define it.+### Changed+- **The image round-trip bundle moved into the corpus** and its integration test re-sources from there. An `Image` produced by one pipe and consumed by the next is a language-level shape, so the corpus owns it; the local copy under `tests/integration/pipelex/pipes/pipelines/` is deleted.- **The `Date` and `YesNo` dry-run e2e tests now source their bundles from the corpus** rather than from copies sitting beside them, and those copies are deleted. Nothing in this repo holds a second copy of a language-level `.mthds` method any more.## [v0.47.0] - 2026-08-19diff --git a/docs/contribute/mthds-test-corpus.md b/docs/contribute/mthds-test-corpus.mdindex a61696df9..74ae95086 100644--- a/docs/contribute/mthds-test-corpus.md+++ b/docs/contribute/mthds-test-corpus.md@@ -48,13 +48,15 @@ An entry directory holds either exactly one `.mthds` file, or several with a `bu]```-4. **Validate it locally** — against the local runtime, never the hosted API, which lags it:+4. **Name no model.** Presets and aliases are resolved by the validation engine, not only at run time, so an entry pinning one fails validation outright on any consumer whose deck does not define it — which turns an entry about a language feature into an entry about model selection. Leave the choice to each consumer's deck.++5. **Validate it locally** — against the local runtime, never the hosted API, which lags it:```bash.venv/bin/pipelex validate bundle pipelex/test_extras/mthds_corpus/entries/native_time_departure/```-5. **Run the gates**: `.venv/bin/pytest tests/unit/pipelex/test_extras tests/integration/pipelex/test_extras`.+6. **Run the gates**: `.venv/bin/pytest tests/unit/pipelex/test_extras tests/integration/pipelex/test_extras`.An **invalid** entry additionally declares the exact wire `error_type` it must produce. Read that string off the runtime rather than inferring it from the source:@@ -89,6 +91,7 @@ An **exclusion** marks a registry code that no standalone focused entry could me| Manifest | `tests/unit/pipelex/test_extras/test_mthds_corpus_manifest.py` | The strict `entry.toml` model rejected something. || Layout and filters | `tests/unit/pipelex/test_extras/test_mthds_corpus_loader.py` | An entry's name does not match its directory, its bundle does not resolve, or the loader's filter semantics changed. || Entry validation | `tests/integration/pipelex/test_extras/test_mthds_corpus_entries.py` | A valid entry stopped validating, or an invalid one stopped failing with exactly its declared error. Runs over every entry regardless of tier, so an `inference`-tier entry that broke is caught without spending a token. |+| Packaging | `tests/integration/pipelex/test_extras/test_mthds_corpus_packaging.py` | A corpus file stopped shipping in the wheel, or the generator started shipping. It builds a real wheel and derives what it expects from the corpus tree, so a new entry is covered with no wiring. |## Consuming the corpus from a test@@ -105,6 +108,8 @@ for entry in iter_entries(tier=EntryTier.DRY):`iter_entries()` filters compose conjunctively and each is optional: `tags` (the entry covers **all** of them), `tier` (a ceiling — the entry's tier is that one or cheaper), `validity`, `granularity`. Ordering is entry-name lexicographic and stable, so parametrized test ids do not churn.+The same two calls are how a **consumer outside this repo** reaches the corpus: it ships as package data in the wheel, so anything that already depends on `pipelex` — our own hosted services, most immediately — reads it with no vendored copy and no drift, in lockstep with its pinned version. Paths handed out are real filesystem paths, resolved through `importlib.resources.files`; wheels install unzipped, and a zip-imported distribution is not supported.+The corpus is the single source for language-level `.mthds` methods in this repo: `tests/e2e/pipelex/pipes/date/` and `tests/e2e/pipelex/pipes/yes_no/` already reach for their bundles this way rather than keeping local copies.!!! note "The entries are data, never auto-loaded"diff --git a/pipelex/test_extras/mthds_corpus/entries/image_from_planting_brief/bundle.mthds b/pipelex/test_extras/mthds_corpus/entries/image_from_planting_brief/bundle.mthdsnew file mode 100644index 000000000..1cf63d551--- /dev/null+++ b/pipelex/test_extras/mthds_corpus/entries/image_from_planting_brief/bundle.mthds@@ -0,0 +1,33 @@+domain = "seed_catalog"+description = "Write the planting scene a seed packet should show, then draw it"+main_pipe = "make_packet_illustration"++[concept.PlantingScene]+description = """+A description of the scene a seed packet illustration should show: the plant at maturity, the bed it grows in, the season, and the light.+"""+refines = "Text"++[pipe.write_planting_scene]+type = "PipeLLM"+description = "Write the planting scene the seed packet should show"+output = "PlantingScene"+prompt = """+Describe, in two or three vivid sentences, the scene a seed packet for climbing beans should show: the plant at maturity, the bed it grows in, the season, and the light.+"""++[pipe.draw_packet_illustration]+type = "PipeImgGen"+description = "Draw the seed packet illustration from the planting scene"+inputs = { planting_scene = "PlantingScene" }+output = "Image"+prompt = "$planting_scene"++[pipe.make_packet_illustration]+type = "PipeSequence"+description = "Write the planting scene, then draw the seed packet illustration from it"+output = "Image"+steps = [+ { pipe = "write_planting_scene", result = "planting_scene" },+ { pipe = "draw_packet_illustration", result = "packet_illustration" },+]diff --git a/pipelex/test_extras/mthds_corpus/entries/image_from_planting_brief/entry.toml b/pipelex/test_extras/mthds_corpus/entries/image_from_planting_brief/entry.tomlnew file mode 100644index 000000000..fa9f04773--- /dev/null+++ b/pipelex/test_extras/mthds_corpus/entries/image_from_planting_brief/entry.toml@@ -0,0 +1,10 @@+name = "image_from_planting_brief"+description = "A seed packet illustration drawn from a planting scene the method writes first"++validity = "valid"+tier = "inference"+granularity = "composite"++covers = [+ "native.image",+]diff --git a/pipelex/test_extras/mthds_corpus/entries/image_round_trip_room_photo/bundle.mthds b/pipelex/test_extras/mthds_corpus/entries/image_round_trip_room_photo/bundle.mthdsnew file mode 100644index 000000000..043bdb50c--- /dev/null+++ b/pipelex/test_extras/mthds_corpus/entries/image_round_trip_room_photo/bundle.mthds@@ -0,0 +1,29 @@+domain = "holiday_lettings"+description = "Produce a room photograph for a holiday listing, then read it back to caption it"+main_pipe = "illustrate_and_caption_room"++[pipe.render_room_photo]+type = "PipeImgGen"+description = "Produce the photograph of the room"+output = "Image"+prompt = "A sunlit corner bedroom with a wooden bed frame, linen curtains and a view over rooftops"++[pipe.caption_room_photo]+type = "PipeLLM"+description = "Write the listing caption from the room photograph"+inputs = { room_photo = "Image" }+output = "Text"+prompt = """+Write the caption for this holiday listing photograph in one or two sentences, naming what a guest would notice first.++$room_photo+"""++[pipe.illustrate_and_caption_room]+type = "PipeSequence"+description = "Produce the room photograph and caption it"+output = "Text"+steps = [+ { pipe = "render_room_photo", result = "room_photo" },+ { pipe = "caption_room_photo", result = "caption" },+]diff --git a/pipelex/test_extras/mthds_corpus/entries/image_round_trip_room_photo/entry.toml b/pipelex/test_extras/mthds_corpus/entries/image_round_trip_room_photo/entry.tomlnew file mode 100644index 000000000..f291ecd35--- /dev/null+++ b/pipelex/test_extras/mthds_corpus/entries/image_round_trip_room_photo/entry.toml@@ -0,0 +1,11 @@+name = "image_round_trip_room_photo"+description = "A room photograph produced and then read back to write the listing caption"++validity = "valid"+tier = "inference"+granularity = "composite"++covers = [+ "native.image",+ "native.text",+]diff --git a/tests/integration/pipelex/pipes/pipelines/test_image_inputs.mthds b/tests/integration/pipelex/pipes/pipelines/test_image_inputs.mthdsindex a7f125022..a3474ba22 100644--- a/tests/integration/pipelex/pipes/pipelines/test_image_inputs.mthds+++ b/tests/integration/pipelex/pipes/pipelines/test_image_inputs.mthds@@ -34,3 +34,17 @@ Extract the year and title.Also, add this to the description:$page.text_and_images.text.text"""++# Fed a data-URL image by test_image_inputs_inference.py. It used to borrow `describe_image` from+# the image round-trip bundle that now lives in the corpus; the pipe belongs here, beside the other+# image-input pipes that test drives.+[pipe.describe_image]+type = "PipeLLM"+description = "Describe what is in the image"+inputs = { image = "Image" }+output = "Text"+model = "$vision-cheap"+prompt = """+Describe what you see in this image in 1-2 sentences, be concise.+$image+"""diff --git a/tests/integration/pipelex/pipes/pipelines/test_image_out_in.mthds b/tests/integration/pipelex/pipes/pipelines/test_image_out_in.mthdsdeleted file mode 100644index 97142e80b..000000000--- a/tests/integration/pipelex/pipes/pipelines/test_image_out_in.mthds+++ /dev/null@@ -1,32 +0,0 @@-domain = "test_image_in_out"-description = "Test domain for verifying image output / input support"-main_pipe = "image_out_in"---[pipe]-[pipe.generate_image]-type = "PipeImgGen"-description = "Generate an image from a prompt"-output = "Image"-prompt = "A beautiful landscape"-model = "$gen-image-testing"--[pipe.describe_image]-type = "PipeLLM"-description = "Describe what is in the image"-inputs = { image = "Image" }-output = "Text"-model = "$vision-cheap"-prompt = """-Describe what you see in this image in 1-2 sentences, be concise.-$image-"""--[pipe.image_out_in]-type = "PipeSequence"-description = "Generate an image from a prompt and describe it"-output = "Text"-steps = [- { pipe = "generate_image", result = "image" },- { pipe = "describe_image", result = "visual_description" },-]diff --git a/tests/integration/pipelex/pipes/test_image_out_in.py b/tests/integration/pipelex/pipes/test_image_out_in.pyindex 7725e2dd0..391127c48 100644--- a/tests/integration/pipelex/pipes/test_image_out_in.py+++ b/tests/integration/pipelex/pipes/test_image_out_in.py@@ -8,6 +8,7 @@ from pipelex.pipe_run.pipe_job_factory import PipeJobFactoryfrom pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactoryfrom pipelex.system.job_metadata import JobMetadatafrom pipelex.system.pipe_run_mode import PipeRunMode+from pipelex.test_extras.mthds_corpus.loader import get_entry@pytest.mark.dry_runnable@@ -16,10 +17,12 @@ from pipelex.system.pipe_run_mode import PipeRunMode@pytest.mark.asyncio(loop_scope="class")class TestImageOutIn:async def test_image_out_in(self, job_metadata: JobMetadata, pipe_run_mode: PipeRunMode, load_test_library: Callable[[list[Path]], None]) -> None:- load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])+ # The bundle is a corpus entry: an Image produced by one pipe and consumed by the next is+ # a language-level shape, and the corpus is the single source for those.+ load_test_library([get_entry(name="image_round_trip_room_photo").directory])pipe_output = await get_pipe_router().run(pipe_job=PipeJobFactory.make_pipe_job(- pipe=get_required_entry_pipe(pipe_code="image_out_in"),+ pipe=get_required_entry_pipe(pipe_code="illustrate_and_caption_room"),pipe_run_params=PipeRunParamsFactory.make_run_params(pipe_run_mode=pipe_run_mode),job_metadata=job_metadata,),diff --git a/tests/integration/pipelex/test_extras/test_mthds_corpus_packaging.py b/tests/integration/pipelex/test_extras/test_mthds_corpus_packaging.pynew file mode 100644index 000000000..3508b6d1f--- /dev/null+++ b/tests/integration/pipelex/test_extras/test_mthds_corpus_packaging.py@@ -0,0 +1,70 @@+"""The corpus ships in the wheel — asserted against a wheel that is actually built.++Contract: ``docs/specs/mthds-test-corpus.md`` (workspace root), section "Distribution".++Wheel consumers reach the corpus through ``importlib.resources``, so a corpus that stopped being+packaged would be invisible in this repo and would break every consumer at once, on the release.+Precedent said hatchling would carry the data files — ``pipelex.toml`` and ``kit/**/*.toml``+already ship — but precedent is not a gate, so this builds the real wheel and looks inside it.++The expected set is derived from the corpus tree rather than listed here: a new entry, a new file+kind, or a new namespace is covered the moment it lands, with nothing to remember.++Marked ``codex_disabled``: building a wheel resolves the PEP 517 backend through uv's default+index, which the air-gapped Codex sandbox cannot reach. The alternatives both cost more than the+marker — ``--offline`` would make the gate depend on a warm uv cache in every environment that+*does* run it, and skipping on a build failure would turn the one packaging gate we have into a+silent pass. It runs in GitHub Actions, which is where a packaging regression has to be caught.+"""++import shutil+import subprocess # noqa: S404 — builds the real wheel; inspecting a hand-rolled file list would prove nothing+import zipfile+from pathlib import Path++import pytest++import pipelex+from pipelex.test_extras.mthds_corpus.resources import corpus_root++_REPO_ROOT = Path(pipelex.__file__).resolve().parent.parent+_UNSHIPPED_GENERATOR = "pipelex/cli/dev_cli/commands/generate_corpus_vocabulary_cmd.py"++[email protected]_disabled+class TestMthdsCorpusPackaging:+ def test_the_corpus_ships_and_its_generator_does_not(self, tmp_path: Path) -> None:+ """Both halves of the split, against one built wheel: the generated data ships, the generator stays out."""+ uv_path = shutil.which("uv")+ # Not a skip: uv is how this repo is installed, so its absence is a broken environment, and a+ # packaging gate that quietly passes when it could not build anything is worse than no gate.+ assert uv_path is not None, "uv is not on PATH, so the wheel cannot be built and the packaging gate cannot run"++ build = subprocess.run( # noqa: S603+ [uv_path, "build", "--wheel", "--out-dir", str(tmp_path)],+ cwd=str(_REPO_ROOT),+ capture_output=True,+ text=True,+ check=False,+ timeout=300,+ )+ assert build.returncode == 0, f"uv build failed.\nstdout={build.stdout!r}\nstderr={build.stderr!r}"+ wheels = list(tmp_path.glob("*.whl"))+ assert len(wheels) == 1, f"expected exactly one built wheel, got {[wheel.name for wheel in wheels]}"++ with zipfile.ZipFile(wheels[0]) as wheel:+ packaged = set(wheel.namelist())++ expected: set[str] = set()+ # Resolved on both sides of the relative_to: on a checkout reached through a symlink the two+ # would disagree and this test would die on a path error instead of reporting its verdict.+ for corpus_file in sorted(corpus_root().resolve().rglob("*")):+ if corpus_file.is_file() and "__pycache__" not in corpus_file.parts:+ expected.add(corpus_file.relative_to(_REPO_ROOT).as_posix())+ assert expected, "the corpus tree is empty on disk, so this test would otherwise pass vacuously"++ missing = sorted(expected - packaged)+ assert not missing, f"corpus files absent from the built wheel: {', '.join(missing)}"++ assert (_REPO_ROOT / _UNSHIPPED_GENERATOR).is_file(), "the generator moved; this test is pinning a path that no longer exists"+ assert _UNSHIPPED_GENERATOR not in packaged, "the vocabulary generator must stay unshipped dev tooling"