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.
chore: bump the mthds floor to 0.11.0 and adapt to the input-form item split (#1156)
Louis Choquel3427164df9b9
diff --git a/.badges/tests.json b/.badges/tests.jsonindex a6be550d4..c84151c8b 100644--- a/.badges/tests.json+++ b/.badges/tests.json@@ -1,7 +1,7 @@{"schemaVersion": 1,"label": "tests",- "message": "10952",+ "message": "10983","color": "blue","cacheSeconds": 300}diff --git a/.claude/skills/bump-mthds/SKILL.md b/.claude/skills/bump-mthds/SKILL.mdnew file mode 100644index 000000000..8455a961f--- /dev/null+++ b/.claude/skills/bump-mthds/SKILL.md@@ -0,0 +1,371 @@+---+name: bump-mthds+description: >+ Move this repo's `mthds` dependency floor to the latest release on PyPI (or a+ version you name), re-lock, adapt the engine source to whatever the new+ release broke, run the checks, and write the CHANGELOG entry — stopping before+ the commit. Use whenever the user says "bump mthds", "update mthds", "upgrade+ mthds", "move to mthds 0.10.0", "get us on the latest mthds", "is our mthds+ floor stale", "what's the latest mthds", or asks to build against a newly+ published `mthds` release. Also use when a failure looks like an mthds+ version mismatch — a pyright `reportAttributeAccessIssue` on something under+ `mthds.protocol`, an ImportError for a name that used to be there, a pydantic+ `Extra inputs are not permitted` from a protocol model, or a `uv lock` saying+ mthds is unsatisfiable. This is the **`mthds` PyPI package** (the MTHDS+ standard's Python client, from the sibling `mthds-python` repo) — not the+ MTHDS standard's spec pages, and not releasing pipelex itself, which is the+ `release` skill.+---++# Bump the `mthds` dependency++`mthds` is the MTHDS standard's Python client: the protocol wire models, the+runner abstracts, the package-manifest schema. This engine is built on it+directly — it subclasses its abstracts (`StuffAbstract`, `ConceptAbstract`,+`WorkingMemoryAbstract`, `MTHDSProtocol`) and **re-exports its wire models as+part of pipelex's own public surface** (`pipelex/pipeline/input_form.py` and+`pipelex/pipeline/pipe_io_contracts.py` list them in `__all__`).++That last part is what makes this bump different from bumping an ordinary+dependency: an upstream rename is not an internal detail this repo absorbs, it+is a **breaking change to pipelex's own API**, and it has to reach the changelog+as one.++The job is to land the new floor in a state a human can read and commit: floor+moved, lock regenerated, source adapted, checks green, changelog written, ledger+squared. **Stop before committing** — the user stages and commits.++## What the bump touches++| File | Why it moves |+|---|---|+| `pyproject.toml` | The floor itself, one line in `[project].dependencies` — `mthds>=X.Y.Z` |+| `uv.lock` | Regenerated by `make li` |+| `pipelex/**` | Wherever the new release renamed, split, or tightened something this engine imports |+| `tests/**` | Same, plus any test asserting on a shape that moved |+| `CHANGELOG.md` | An entry under `## [Unreleased]` — always at least the floor line |+| `.badges/tests.json`, `.test_durations` | Only if the adaptation added, removed or renamed tests |++Do **not** touch `[project].version`. That is this package's own version and it+moves only at release time, via the `release` skill.++## The floor is a floor, and it always tracks latest++The pin is `mthds>=X.Y.Z`, not `==`. pipelex is a published library, so the floor+is a statement to *its* consumers about the minimum they must have.++**The standing policy is to raise the floor to the latest release, every time**,+even when the new release carries nothing this engine uses. Keeping the floor in+lockstep with the lock means the version this repo tests against is the version+it demands, with no gap for a consumer to fall into. The cost is real and worth+naming when you report: everyone downstream — `pipelex-sdk-python`,+`pipelex-server`, every user install — is forced onto that `mthds` too. Say so+in the changelog when the bump is otherwise uneventful, because for a consumer+"pipelex now requires mthds 0.10.0" *is* the change.++## Three numbers, none of which is the others++This is the single most common way to get confused here, and two of the three+are visible in the same sentence of an upstream changelog.++| Number | Where it lives | What it means |+|---|---|---|+| The **`mthds` package version** | `mthds-python/pyproject.toml`, PyPI | The Python client's own release number. **This is what you are bumping.** |+| The **MTHDS standard version** | `MTHDS_STANDARD_VERSION` in `mthds/package/manifest/schema.py` | The version of the *standard* that client implements. Currently `1.0.0`. |+| The **spec site's release number** | the `mthds/` repo's own CHANGELOG | The documentation site's release, e.g. `v0.9.0`. Coincidentally close to the package number; unrelated to it. |++So "mthds 0.9.0 ships the artifacts the standard owns since MTHDS v0.9.0, which+is standard version 1.0.0" is a coherent sentence. Read every version reference+in the upstream notes against this table before repeating it in ours.++## Workflow++### 1. Orient++Read the floor **from `pyproject.toml`**, not from the virtualenv:++```bash+grep -n '"mthds' pyproject.toml+.venv/bin/python -c "import importlib.metadata as m; print(m.version('mthds'))"+```++They disagree more often than you would think, and each disagreement means+something different. The venv ahead of the floor is normal — the floor is a+minimum. The venv *behind* the floor means someone edited `pyproject.toml`+without re-running `make li`.++Check `git status` and note what was already dirty **before** you start.+Concurrent work in this worktree is normal, and at the end you need to separate+your changes from theirs and never stage something that isn't yours.++Then ask the ledger what it already knows. `mthds-python` files items here when+it lands something this engine will have to absorb, and those items usually+carry the exact diff — file, line, and the shape of the fix — which is faster+and more reliable than rediscovering it from a pyright error:++```bash+ledger inbound+ledger list --origin mthds-python --status open+```++The second query is the targeted one — every item `mthds-python` filed, wherever+it landed — and it is worth reading past the rows owned by this repo, because a+row owned by `pipelex-sdk-python` or by `mthds` is a piece of the same cascade+you will be filing into at step 10.++An item that describes the adaptation you are about to do should be claimed+(`ledger claim <id>`) before you start.++### 2. Resolve the target version++If the user named a version, use it. Otherwise ask PyPI:++```bash+curl -s https://pypi.org/pypi/mthds/json \+ | python3 -c "import json,sys; print(json.load(sys.stdin)['info']['version'])"+```++`info.version` is the latest non-prerelease, which is what "latest" means for a+floor other people inherit.++**Ask PyPI, never the sibling checkout.** `mthds-python/pyproject.toml` is a+working tree and is frequently *ahead* of what has been published — a version+sitting there under `## [Unreleased]` is not installable, and a floor naming it+makes `uv lock` fail. If you notice the sibling is ahead, that is worth+mentioning in your report (it is a preview of the next bump) but it does not+change the target.++If the resolved version equals the current floor, say so and stop: there is+nothing to do, and manufacturing lock churn is worse than reporting "already+current". If the venv disagrees, mention that — `make li` is the real fix there.++### 3. Digest the upstream changes — *before* editing anything++For most dependencies you bump first and read the notes later. Not this one.+Because this engine builds on mthds' types rather than merely calling them, the+release notes are a work list, and reading them first is what turns a pyright+cascade into a set of expected edits:++```bash+.venv/bin/python .claude/skills/bump-mthds/scripts/upstream_notes.py 0.9.0 0.10.0+```++The helper reads `../mthds-python/CHANGELOG.md` and prints the released sections+strictly after the old floor up to and including the new one. It skips+`## [Unreleased]` — that section describes work that is *not* in the version you+are adopting, and this repo's changelog is read by people deciding whether an+upgrade will break them. If the checkout predates the target release the script+says so; fall back to:++```bash+gh release view v0.10.0 --repo mthds-ai/mthds-python+```++Read the notes for three things specifically: renamed or split types this repo+imports, parse-time tightening (mthds models are `extra="forbid"`, so a shape+this engine constructs can start failing at construction), and any move of+`MTHDS_STANDARD_VERSION`.++### 4. Move the floor++One line in `pyproject.toml`. Make it a substring edit — replace `>=0.9.0` with+`>=0.10.0` on that line and leave every other character alone. Use your editor+rather than a shell one-liner: `sed -i` takes a separate empty argument on macOS+and an attached suffix on GNU/Linux, so no single invocation is portable, and+the `release` skill edits this same file the same way.++Confirm with `grep -n '"mthds' pyproject.toml` before moving on.++### 5. Re-lock and install++```bash+make li+```++That is `make lock` (`uv lock`) plus `make install` (`uv sync --all-extras`), so+it rewrites `uv.lock` *and* puts the new mthds in `.venv`, which everything+downstream of here depends on.++**Do not reach for `make update`.** That is `uv lock --upgrade` and it moves+every dependency in the tree at once, which turns a reviewable one-package bump+into a diff nobody can reason about. Raising the floor is already enough to make+plain `uv lock` re-resolve mthds upward.++Check the lock actually moved — a floor edit that didn't take is silent:++```bash+grep -A1 '^name = "mthds"' uv.lock+```++If `uv lock` reports the requirement is unsatisfiable, the version is almost+certainly not on PyPI yet. Re-run the query from step 2. If it genuinely isn't+published, stop and tell the user rather than inventing a git or path source:+adding one is a deliberate decision with a real cost (in uv, a *source* outranks+a version specifier, so the floor you wrote becomes decorative), not a+workaround to apply quietly.++### 6. Check whether `MTHDS_STANDARD_VERSION` moved++```bash+.venv/bin/python -c "from mthds.package.manifest.schema import MTHDS_STANDARD_VERSION as v; print(v)"+```++Do this explicitly, because **nothing in this repo pins it and the suite cannot+see it move.** Every test compares the crate stamp against the imported constant+(`assert crate.mthds_version == MTHDS_STANDARD_VERSION`), and the one test that+hardcodes `"1.0.0"` mocks it. So the constant can change under a green suite.++Two things follow it, and one thing deliberately does not:++- The `mthds_version` **stamp** on every normalized crate this engine emits+ (`normalize_crate(crate, mthds_version=MTHDS_STANDARD_VERSION)`) — a visible+ wire field that changes for real users.+- The **manifest constraint warning** in `LibraryManager._warn_if_mthds_version_unsatisfied`+ — a `METHODS.toml` declaring `mthds_version = "^1.0.0"` starts or stops+ warning depending on this constant.+- **Crate fingerprints do not move.** `mthds_version` is excluded from the+ hashed payload by design (see the docstring on+ `compute_normalized_fingerprint` in `pipelex/libraries/library_crate.py`), so+ a standard-version move does not invalidate anyone's fingerprint.++If it moved, that belongs in the changelog as a user-visible change even though+no pipelex line changed to cause it.++### 7. Adapt the source++Run the type checker first — it is the fastest and most complete reader of a+protocol break, and it costs seconds where the suite costs minutes:++```bash+make pyright+```++Work from the step-3 notes and any ledger item, not from guesswork. The+adaptations that recur, in rough order of how often they bite:++- **A renamed or split type this repo imports.** Fix the import, the `__all__`+ re-export, and every `isinstance` narrowing. Grep is the tool: a name that+ appears in `__all__` appears in at least three places.+- **A shape this engine *constructs* that got tighter.** mthds' protocol models+ are `extra="forbid"`, so a member that used to be tolerated now raises at+ construction. Watch for `model_copy(update={...})` in particular — it does not+ validate, so it will happily leave a model in a state the class forbids, and+ the type checker is the only thing that notices. Rebuild the node as the right+ model rather than patching a field onto the wrong one.+- **A new abstract method** on something this repo subclasses. Implement it;+ don't `raise NotImplementedError` to get green.++Failures here are the breaking change announcing itself, not incidental+breakage. Adopt the new API. A bump whose failures were papered over is worse+than no bump.++### 8. Run the checks++```bash+make agent-check+make agent-test+```++`agent-check` includes `drift-check`, which reads the **git index**, not the+working tree — so `git add` your changes before you trust its verdict. If it+reports an open contract, resolve it properly with the `drift-review` skill+rather than acking it blind.++If the adaptation added, removed or renamed tests, two committed artifacts go+stale and neither is caught by a local aggregate:++```bash+make store-test-durations # .test_durations — keeps the CI shards balanced+make check-test-badge # .badges/tests.json — runs only in CI, so check it here+```++A `MTHDS standard conformance` red is a different animal: that workflow holds+this repo's pinned natives against the standard's own `native-concepts.md` from+an unpinned checkout of the `mthds` **spec** repo. A red there means the+*standard* moved and wants a dedicated catch-up change — bumping the *package*+neither causes nor fixes it. Say so rather than chasing it inside the bump.++### 9. Write the changelog entry++Add to `CHANGELOG.md` under `## [Unreleased]`, creating that heading right after+`# Changelog` if it isn't there. Work in progress accumulates there until a+release cuts it into a version heading — do not add a `## [vX.Y.Z]` heading+yourself, and do not bump `[project].version`.++Every bump gets at least the floor line. Follow the house form, which names the+release *by what it carries*:++```markdown+- **Minimum `mthds` version**: The floor moves to `mthds>=0.10.0`, <the release+ that carries / the release fixing …>.+```++Anything that reached pipelex's own surface gets its own entry under+`### Changed`, marked breaking, written for an importer deciding whether this+upgrade will cost them work. Name the old symbol and the new one — a reader+hitting an ImportError searches for the name they had. Where a change is+breaking, write "breaking", not "pre-1.0 breaking".++If the bump is genuinely uneventful, say that in one sentence and stop. Padding+a quiet bump with upstream detail that doesn't affect this repo makes the loud+ones harder to spot.++### 10. Square the ledger++- **Close what you actually landed**, with evidence — the file and line you+ changed, and the check that went green. `Closes <id>` goes in the PR body when+ the user opens one.+- **File the cascade.** A breaking bump here does not stay here.+ `pipelex-sdk-python` declares its own `mthds` floor, and `pipelex-server` pins+ `pipelex` exactly at several sites. Neither is yours to edit from this repo:+ file it (`ledger new --owner <repo> …`) with the symbol that moved and the+ version that moved it. The `ledger` skill has the full gesture.+- **File the reverse direction if you moved the wire.** `mthds-python` commits+ protocol parity fixtures captured *from this engine*, so a change here that+ alters emitted output means those fixtures need recapturing — an item owned by+ `mthds-python`, naming the SHA to capture from.+- `ledger validate`, then `ledger commit`. Nothing else pushes the ledger.++### 11. Report and stop++Show the user:++- The floor move, old → new, and whether `uv.lock` actually followed.+- Whether `MTHDS_STANDARD_VERSION` moved, and what that changes for users.+- Every file you changed, separated from what was already dirty when you started.+- The check results, honestly — if `agent-test` failed, say so with the output+ rather than reporting a bump as done.+- Whether the bump is **breaking for pipelex's own importers**, since that is+ what decides how the next release is written and who has to move after it.+- Anything left for a human: an upstream change whose adaptation is a judgment+ call, or a version the sibling checkout has that PyPI doesn't yet.++Then stop. Do not commit, branch, or push unless the user asks.++If they do ask, **stage the files explicitly by path** — never `git add -A`. A+working branch here is `chore/<Topic>` (spelled out, from the closed prefix set)+and PRs target `dev`.++## Traps worth remembering++- **The floor is not the lock.** Because `>=` already admits newer releases, a+ fresh resolve can pull a new mthds into someone's environment with nobody+ bumping anything. That is exactly why this bump is done deliberately, and why+ step 5 verifies the lock actually moved.+- **The sibling checkout is routinely ahead of PyPI.** Read `mthds-python`'s+ changelog for *understanding*, PyPI for *the target version*. A floor naming+ an unpublished version fails `uv lock`.+- **`## [Unreleased]` upstream is not in the version you adopted.** Never quote+ it as part of the release. The helper script skips it for you.+- **`MTHDS_STANDARD_VERSION` moves silently.** Nothing pins it; the suite+ follows it. Print it (step 6).+- **`model_copy(update=…)` does not validate.** It is how a model ends up+ holding a value its class forbids, green at runtime, wrong on the type.+- **`make update` is not `make li`.** The former upgrades the whole tree.+- **`drift-check` reads the git index.** Unstaged changes give a false green.+- **`check-test-badge` runs in no local aggregate.** Green here, red in CI, on+ any commit that changes the test count.+- **A `MTHDS standard conformance` red is about the spec repo, not this+ package.** Different repo, different remedy.+- **`[project].version` is pipelex's own version.** Bumping it is the `release`+ skill's job, not this one's.diff --git a/.claude/skills/bump-mthds/scripts/upstream_notes.py b/.claude/skills/bump-mthds/scripts/upstream_notes.pynew file mode 100755index 000000000..f7895e515--- /dev/null+++ b/.claude/skills/bump-mthds/scripts/upstream_notes.py@@ -0,0 +1,132 @@+#!/usr/bin/env python3+"""Extract `mthds` release notes for the versions a bump crosses.++Reads the sibling `mthds-python` checkout's CHANGELOG.md and prints every+released section strictly after ``old_version`` up to and including+``new_version``.++Three boundaries this exists to get right:++- ``## [Unreleased]`` is never printed. It describes work that is *not* in the+ version being pinned. Quoting it in this repo's changelog is a plain factual+ error about what the upgrade contains -- and in this pairing it is a live+ hazard rather than a theoretical one, because `mthds-python`'s working tree is+ routinely ahead of PyPI.+- The old floor's own section is excluded (it was already in effect) while the+ new one's is included.+- A checkout that predates the target release cannot answer, and says so instead+ of printing a plausible-looking short range.++Exits non-zero with an explanation when the checkout cannot answer. Fall back to+``gh release view v<new> --repo mthds-ai/mthds-python`` in that case.+"""++from __future__ import annotations++import argparse+import re+import sys+from pathlib import Path++from packaging.version import InvalidVersion, Version++# .../pipelex/.claude/skills/bump-mthds/scripts/upstream_notes.py+# parents[4] is the pipelex repo root; its parent is the workspace root.+DEFAULT_CHANGELOG = Path(__file__).resolve().parents[4].parent / "mthds-python" / "CHANGELOG.md"+HEADING = re.compile(r"^## \[v?(?P<version>\d+\.\d+\.\d+[^\]]*)\]")+UNRELEASED = re.compile(r"^## \[Unreleased\]", re.IGNORECASE)+FALLBACK = "gh release view v{version} --repo mthds-ai/mthds-python"+++def parse_version(raw: str) -> Version:+ """Parse a version string into a PEP 440 version.++ Ordering has to hold among prereleases as well as between a prerelease and+ the release it leads to, and equality here is normalization-aware, so a+ section is matched by the version it denotes rather than by how it was+ spelled in the heading.+ """+ try:+ return Version(raw.strip())+ except InvalidVersion as exc:+ msg = f"Not a version this script can compare: {raw!r}"+ raise SystemExit(msg) from exc+++def split_sections(text: str) -> list[tuple[str, str]]:+ """Return [(version, body)] for released sections, in file order."""+ sections: list[tuple[str, str]] = []+ current_version: str | None = None+ buffer: list[str] = []++ for line in text.splitlines():+ if UNRELEASED.match(line):+ if current_version is not None:+ sections.append((current_version, "\n".join(buffer).strip()))+ current_version, buffer = None, []+ continue+ match = HEADING.match(line)+ if match:+ if current_version is not None:+ sections.append((current_version, "\n".join(buffer).strip()))+ current_version, buffer = match.group("version"), [line]+ continue+ if current_version is not None:+ buffer.append(line)++ if current_version is not None:+ sections.append((current_version, "\n".join(buffer).strip()))+ return sections+++def main() -> int:+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)+ parser.add_argument("old_version", help="the floor currently declared, excluded from the output")+ parser.add_argument("new_version", help="the version being adopted, included in the output")+ parser.add_argument(+ "--changelog",+ type=Path,+ default=DEFAULT_CHANGELOG,+ help=f"path to mthds-python's CHANGELOG.md (default: {DEFAULT_CHANGELOG})",+ )+ args = parser.parse_args()++ if not args.changelog.is_file():+ print(+ f"No mthds-python changelog at {args.changelog}.\nFall back to: {FALLBACK.format(version=args.new_version)}",+ file=sys.stderr,+ )+ return 2++ low = parse_version(args.old_version)+ high = parse_version(args.new_version)+ if low >= high:+ print(f"{args.new_version} is not newer than {args.old_version} -- nothing to digest.", file=sys.stderr)+ return 2++ sections = split_sections(args.changelog.read_text(encoding="utf-8"))+ known = {parse_version(version) for version, _ in sections}+ if high not in known:+ print(+ f"The checkout at {args.changelog} has no section for {args.new_version} -- it likely predates that release.\n"+ f"Fall back to: {FALLBACK.format(version=args.new_version)}",+ file=sys.stderr,+ )+ return 3++ wanted = [(version, body) for version, body in sections if low < parse_version(version) <= high]+ if not wanted:+ print(f"No released sections between {args.old_version} (exclusive) and {args.new_version}.", file=sys.stderr)+ return 3++ print("\n\n".join(body for _, body in wanted))+ if low not in known:+ print(+ f"\nNote: no section for the old floor {args.old_version} in this checkout, so the range may start earlier than the true gap.",+ file=sys.stderr,+ )+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/.test_durations b/.test_durationsindex be7ed461c..4aa7de521 100644--- a/.test_durations+++ b/.test_durations@@ -7964,6 +7964,8 @@"tests/unit/pipelex/pipeline/test_hint_warnings.py::TestHintLintSilence::test_applicable_hints_produce_no_warning": 0.0006,"tests/unit/pipelex/pipeline/test_hint_warnings.py::TestHintLintSilence::test_hint_free_crate_produces_no_warning": 0.0004,"tests/unit/pipelex/pipeline/test_hint_warnings.py::TestHintLintSilence::test_warned_content_stays_in_the_crate": 0.0007,+ "tests/unit/pipelex/pipeline/test_input_form_list_items.py::TestDerivedListItemsAreNameless::test_a_concept_item_is_the_nameless_model_and_keeps_its_payload": 0.4948,+ "tests/unit/pipelex/pipeline/test_input_form_list_items.py::TestDerivedListItemsAreNameless::test_a_scalar_item_is_the_nameless_model": 0.4989,"tests/unit/pipelex/pipeline/test_input_form_deriver.py::TestInputFormDeriverEscapeHatches::test_chain_ending_at_a_base_absent_from_the_crate_is_unknown": 0.2013,"tests/unit/pipelex/pipeline/test_input_form_deriver.py::TestInputFormDeriverEscapeHatches::test_concept_absent_from_the_crate_is_unknown_without_a_class": 0.0187,"tests/unit/pipelex/pipeline/test_input_form_deriver.py::TestInputFormDeriverEscapeHatches::test_cycle_guard_emits_unknown_on_revisit": 0.1974,diff --git a/AGENTS.md b/AGENTS.mdindex c21ef4f3a..ecee6cb0b 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -219,7 +219,7 @@ The deciding question is **does this value ever get serialized** — sent across- **frozen `BaseModel`** (`model_config = ConfigDict(frozen=True)`) — immutable value objects that need the full model API (`model_dump`, validators, discriminated unions), must sit in a uniformly-`BaseModel` layer, or must stay type-distinct from a `tuple` in a union.- **mutable `BaseModel`** — objects genuinely mutated in place that also want the model API or layer consistency.-Never reach for `TypeAdapter` — needing it means the shape was chosen wrong. And don't convert an existing serialized `BaseModel` to a dataclass just because dataclasses are serialization-safe too: a model that relies on discriminated unions or validators must stay a `BaseModel`. When a serialized dataclass/model field references a type from an optional dependency, alias it to `Any` at runtime so it validates as `Any` without importing the extra (e.g. `if TYPE_CHECKING: from temporalio.common import RetryPolicy` / `else: RetryPolicy = Any`) — a bare forward ref instead raises `PydanticUserError` on construction.+Don't reach for `TypeAdapter` on a shape you designed — needing it there means the top-level shape was chosen wrong: wrap it in a named `BaseModel`, which brings `model_validate` and the rest for free. Its one legitimate use is validating into a top-level type that is not a model class and not yours to wrap — a discriminated union or container owned by an external contract (a standard's wire model, a log stream of one-of-many event types); build that adapter once at module level and reuse it, and never use a `TypeAdapter` as a runtime substitute for `cast` on a value that is already typed. And don't convert an existing serialized `BaseModel` to a dataclass just because dataclasses are serialization-safe too: a model that relies on discriminated unions or validators must stay a `BaseModel`. When a serialized dataclass/model field references a type from an optional dependency, alias it to `Any` at runtime so it validates as `Any` without importing the extra (e.g. `if TYPE_CHECKING: from temporalio.common import RetryPolicy` / `else: RetryPolicy = Any`) — a bare forward ref instead raises `PydanticUserError` on construction.Once you've landed on a `BaseModel` (the default for anything that serializes), respect Pydantic v2 standards:diff --git a/CHANGELOG.md b/CHANGELOG.mdindex a5e891288..99f6649d8 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -13,7 +13,9 @@- **Input-form descriptor conformance fixes (Breaking for descriptor consumers)**: A description-only concept's `refines` now carries the authored chain alone (absent when nothing was authored) instead of a fabricated `native.Text` link the spec forbids reconstructing — text-valuedness still reaches the wire as `kind: "prose"`. And a list's `item` node no longer carries a `name` member: the spec states an item has no authored name, and the index labels entries.- **The input-form descriptor and the pipe I/O contracts are typed by the standard now (Breaking for importers)**: The wire models of both artifacts are declared once, by the MTHDS standard's Python client, and Pipelex imports them instead of restating them. `pipelex/pipeline/pipe_io_contracts.py` re-exports `PipeInputContract`, `PipeOutputContract`, `PipeIOContract` and `IOMultiplicity` from `mthds.protocol.pipe_io_contracts`; `pipelex/pipeline/input_form.py` re-exports `FieldKind`, `PipeInputFormDescriptor` and the field models from `mthds.protocol.input_form`; and `pipelex/core/pipes/variable_multiplicity.py` re-exports `PresenceMarker` from the contracts module, since the marker is part of the contract's wire vocabulary. **The wire is unchanged** — every field name, every value, and every absent-versus-null rule is the one the engine already emitted, and the derivation is the same derivation. What moved is which package declares the shape. Importers are affected in three ways: a field descriptor is now one model per kind (`TextField`, `ProseField`, `DateField`, `NumberField`, `BooleanField`, `EnumField`, `DocumentField`, `ImageField`, `ObjectField`, `ListField`, `UnknownField`) under an `InputFormField` union discriminated on `kind`, so a node is narrowed with `isinstance` or a `match` on its class rather than read off a flat model; `FieldKind.is_list` and `FieldKind.is_object` are gone with that narrowing; and the `date` kind's Python attribute is now `datetime`, the name it always had on the wire, rather than `datetime_flag`. Because the engine constructs the standard's own closed shapes, a drift between what it emits and what the standard defines now fails at derivation instead of silently on the wire. See [Input-form descriptor](under-the-hood/input-form-descriptor.md) and [Pipe I/O contracts](under-the-hood/pipe-io-contracts.md).- **`PresenceMarker`'s symbol grammar moved off the enum (Breaking)**: The marker enum is the standard's, so the three helpers that are this engine's `.mthds` suffix grammar rather than wire vocabulary became module-level functions in `pipelex/core/pipes/variable_multiplicity.py`: `PresenceMarker.from_symbol(...)` is `presence_from_symbol(symbol=...)`, `marker.symbol` is `presence_symbol(presence=marker)`, and `marker.is_force` is `is_force_presence(presence=marker)`, all keyword-only per this repo's convention. `is_optional` and `is_plain` stay properties on the enum, which the standard declares.-- **Minimum `mthds` version**: The floor moves to `mthds>=0.9.0`, the release that carries `mthds/protocol/pipe_io_contracts.py` and `mthds/protocol/input_form.py`.+- **The input-form descriptor's item layer is a type of its own (Breaking for importers)**: The standard now splits the field union in two instead of carrying `name` as an optional slot on one shared base, and `pipelex/pipeline/input_form.py` re-exports both layers. `InputFormField` stays the named union, whose per-kind models (`TextField`, `ObjectField`, …) now require `name: str` rather than admitting `None`; the new `InputFormItem` union is their nameless counterpart (`TextItem`, `ObjectItem`, …), which is what a list's `item` holds and the only shape that position accepts. Two re-exported base classes were renamed with it: `InputFormFieldBase` is now `InputFormItemBase`, and `TextValuedFieldBase` is now `TextValuedItemBase`. **The wire is unchanged** — this engine already stopped emitting `name` on an item; what moved is that the rule is now the shape rather than a convention, so an item built with a name fails at construction and a consumer reading `field.name` gets a `str` with nothing to narrow.+- **Agent-rule refinement on `TypeAdapter`** (`pipelex/kit/agent_rules/python_standards.md`): the flat ban becomes a scoped one — don't design shapes that need a `TypeAdapter`, but validating into a top-level union or container owned by an external contract (a standard's wire model, a log stream of one-of-many event types) is its sanctioned use, as a module-level singleton. The input-form deriver's list-item conversion is exactly that case and keeps its adapter.+- **Minimum `mthds` version**: The floor moves to `mthds>=0.11.0`, the releases carrying that split and the descriptor's coherence rules — a top-level field whose `required` contradicts its presence marker, one pairing `gating: true` with an optional marker, and a wire node spelling absence as an explicit `null` are now rejected at the parse, which gates this engine's emission at derivation time rather than on the wire. Everyone downstream of Pipelex inherits that floor.## [v0.53.0] - 2026-08-25diff --git a/docs/under-the-hood/input-form-descriptor.md b/docs/under-the-hood/input-form-descriptor.mdindex 37857c23f..85afcefe1 100644--- a/docs/under-the-hood/input-form-descriptor.md+++ b/docs/under-the-hood/input-form-descriptor.md@@ -6,7 +6,7 @@ The descriptor exists because the emitted `json_schema` is a *payload* contract,## Where it lives-- `mthds.protocol.input_form` — **the wire models**, declared by the MTHDS standard's Python client and mirroring its `input-form-descriptor` page: `FieldKind`, one model per kind (`TextField`, `ProseField`, `DateField`, `NumberField`, `BooleanField`, `EnumField`, `DocumentField`, `ImageField`, `ObjectField`, `ListField`, `UnknownField`), their `InputFormField` union discriminated on `kind`, and `PipeInputFormDescriptor`. Pipelex does not declare a second copy of them.+- `mthds.protocol.input_form` — **the wire models**, declared by the MTHDS standard's Python client and mirroring its `input-form-descriptor` page: `FieldKind`, one model per kind (`TextField`, `ProseField`, `DateField`, `NumberField`, `BooleanField`, `EnumField`, `DocumentField`, `ImageField`, `ObjectField`, `ListField`, `UnknownField`), their `InputFormField` union discriminated on `kind`, the nameless counterpart of each (`TextItem` … `UnknownItem`) under the `InputFormItem` union a list's `item` holds, and `PipeInputFormDescriptor`. Which union applies is decided by position, never by content: a named position holds an `InputFormField`, whose `name` is a required `str`, and a list's `item` holds an `InputFormItem`, which declares no `name` at all. Pipelex does not declare a second copy of them.- `pipelex/pipeline/input_form.py` — the one public derivation `build_input_form(pipes)` and the `InputFormDeriver` behind it, which import and re-export those models. A node's kind IS its model, so the deriver constructs the per-kind model and a consumer narrows a node with `isinstance` or a `match` on its class.- `PipelexValidationReport.input_form` (`pipelex/pipeline/validation_report.py`) — a **required** field, keyed exactly like `pipe_io_contracts`. `build_validation_report` requires it as a keyword: the shared-assembly rule says a report field is populated on every backend or none, so a backend that forgets it fails loudly instead of shipping an empty view.- `pipelex/pipeline/validate_in_process.py` — the in-process assembly derives it inside the validation library's window, right beside `build_pipe_io_contracts`.diff --git a/pipelex/kit/agent_rules/python_standards.md b/pipelex/kit/agent_rules/python_standards.mdindex 5c26b9697..a173c81c6 100644--- a/pipelex/kit/agent_rules/python_standards.md+++ b/pipelex/kit/agent_rules/python_standards.md@@ -104,7 +104,7 @@ The deciding question is **does this value ever get serialized** — sent across- **frozen `BaseModel`** (`model_config = ConfigDict(frozen=True)`) — immutable value objects that need the full model API (`model_dump`, validators, discriminated unions), must sit in a uniformly-`BaseModel` layer, or must stay type-distinct from a `tuple` in a union.- **mutable `BaseModel`** — objects genuinely mutated in place that also want the model API or layer consistency.-Never reach for `TypeAdapter` — needing it means the shape was chosen wrong. And don't convert an existing serialized `BaseModel` to a dataclass just because dataclasses are serialization-safe too: a model that relies on discriminated unions or validators must stay a `BaseModel`. When a serialized dataclass/model field references a type from an optional dependency, alias it to `Any` at runtime so it validates as `Any` without importing the extra (e.g. `if TYPE_CHECKING: from temporalio.common import RetryPolicy` / `else: RetryPolicy = Any`) — a bare forward ref instead raises `PydanticUserError` on construction.+Don't reach for `TypeAdapter` on a shape you designed — needing it there means the top-level shape was chosen wrong: wrap it in a named `BaseModel`, which brings `model_validate` and the rest for free. Its one legitimate use is validating into a top-level type that is not a model class and not yours to wrap — a discriminated union or container owned by an external contract (a standard's wire model, a log stream of one-of-many event types); build that adapter once at module level and reuse it, and never use a `TypeAdapter` as a runtime substitute for `cast` on a value that is already typed. And don't convert an existing serialized `BaseModel` to a dataclass just because dataclasses are serialization-safe too: a model that relies on discriminated unions or validators must stay a `BaseModel`. When a serialized dataclass/model field references a type from an optional dependency, alias it to `Any` at runtime so it validates as `Any` without importing the extra (e.g. `if TYPE_CHECKING: from temporalio.common import RetryPolicy` / `else: RetryPolicy = Any`) — a bare forward ref instead raises `PydanticUserError` on construction.Once you've landed on a `BaseModel` (the default for anything that serializes), respect Pydantic v2 standards:diff --git a/pipelex/pipeline/input_form.py b/pipelex/pipeline/input_form.pyindex 2b48ecd39..fcd925688 100644--- a/pipelex/pipeline/input_form.py+++ b/pipelex/pipeline/input_form.py@@ -8,11 +8,13 @@ concept tables, and no description matching. It is keyed by the same namespacedconstruction.**The wire shapes belong to the standard, not to this engine.** `FieldKind`, the per-kind field-models, their `InputFormField` union and `PipeInputFormDescriptor` are the models of+models, their two unions and `PipeInputFormDescriptor` are the models of`mthds.protocol.input_form`, mirroring the standard's `input-form-descriptor` page; they areimported and re-exported here so this module keeps its callers, and this engine holds no second-declaration of them. What stays here is the derivation: how an authored library becomes a-descriptor. Because a node's kind IS its model, the deriver constructs the per-kind model rather+declaration of them. The union a node belongs to is decided by its position, not by its content:+every named position holds an `InputFormField`, while a `list`'s `item` holds the nameless+`InputFormItem`, whose per-kind models declare no `name` at all. What stays here is the+derivation: how an authored library becomes a descriptor. Because a node's kind IS its model, the deriver constructs the per-kind model ratherthan passing a `kind`, and the models' own parse-time invariants — the closed shapes, the rulethat `presence` and `gating` are stated on every top-level field and nowhere below it, the rulethat a fixed `item_count` is at least two — gate this emission at derivation time rather than on@@ -43,24 +45,36 @@ from typing import Anyfrom annotated_types import Ge, Gt, Le, Lt, MaxLen, MinLenfrom mthds.protocol.input_form import (BooleanField,+ BooleanItem,DateField,+ DateItem,DocumentField,+ DocumentItem,EnumField,+ EnumItem,FieldKind,ImageField,+ ImageItem,InputForm,InputFormField,- InputFormFieldBase,+ InputFormItem,+ InputFormItemBase,ListField,+ ListItem,NumberField,+ NumberItem,ObjectField,+ ObjectItem,PipeInputFormDescriptor,ProseField,+ ProseItem,TextField,- TextValuedFieldBase,+ TextItem,+ TextValuedItemBase,UnknownField,+ UnknownItem,)-from pydantic import BaseModel+from pydantic import BaseModel, TypeAdapterfrom pydantic.fields import FieldInfofrom pydantic_core import PydanticUndefined@@ -81,23 +95,35 @@ from pipelex.system.registries.class_registry_access import get_class_registry__all__ = ["BooleanField",+ "BooleanItem","DateField",+ "DateItem","DocumentField",+ "DocumentItem","EnumField",+ "EnumItem","FieldKind","ImageField",+ "ImageItem","InputForm","InputFormDeriver","InputFormField",- "InputFormFieldBase",+ "InputFormItem",+ "InputFormItemBase","ListField",+ "ListItem","NumberField",+ "NumberItem","ObjectField",+ "ObjectItem","PipeInputFormDescriptor","ProseField",+ "ProseItem","TextField",- "TextValuedFieldBase",+ "TextItem",+ "TextValuedItemBase","UnknownField",+ "UnknownItem","build_input_form","qualify_current_library_crate",]@@ -481,14 +507,25 @@ class InputFormDeriver:return _scalar_field(field_type=item_type, name=name, required=True)-def _as_list_item(*, node: InputFormField) -> InputFormField:+_LIST_ITEM_ADAPTER: TypeAdapter[InputFormItem] = TypeAdapter(InputFormItem)+"""Parses a node's slots into its nameless counterpart, picked by the union's own `kind` discriminator.++Going through the union rather than a kind-to-model table here keeps the standard's kind list in+one place: a kind added upstream lands in `InputFormItem` and needs no entry on this side.+"""+++def _as_list_item(*, node: InputFormField) -> InputFormItem:"""A node in `item` position: a list's `item` has no authored name and carries no `name` member.The spec states the absence outright (the index labels items, and a sentinel would be a value- two producers could pick differently), so the element node built from the list's own facts- drops the name it was derived under.+ two producers could pick differently), and the standard makes it structural — the two layers+ are separate unions, and none of the item models declares `name`. So the element node derived+ under the list's own name is rebuilt one layer down from the same slots, rather than having its+ name blanked: `model_copy(update=...)` does not validate, and blanking would leave a required+ `str` slot holding `None` — right on the wire, wrong on the type, and unnoticed at runtime."""- return node.model_copy(update={"name": None})+ return _LIST_ITEM_ADAPTER.validate_python({slot: value for slot, value in node if slot != "name"})def _with_effective_hints(*, node: InputFormField, hints: dict[str, str] | None) -> InputFormField:@@ -519,7 +556,7 @@ def _recast_text_kind(*, node: InputFormField, hints: dict[str, str], to_prose:and `label` apply nowhere else — so the source is always a `text` or `prose` node and its ownextra slots are the shared text constraints, which carry over unchanged."""- if not isinstance(node, TextValuedFieldBase):+ if not isinstance(node, TextValuedItemBase):# Unreachable while `_node_site_kind` reports text-valued for the text kinds alone; stated# rather than asserted, so a future kind that reports text-valued degrades to a hint stamp.return node.model_copy(update={"hints": hints})diff --git a/pipelex/pipeline/vacuous_presence_warnings.py b/pipelex/pipeline/vacuous_presence_warnings.pyindex d5fc28425..f01ad9ee8 100644--- a/pipelex/pipeline/vacuous_presence_warnings.py+++ b/pipelex/pipeline/vacuous_presence_warnings.py@@ -77,10 +77,6 @@ def _warning_for_slot(*, pipe_ref: str, slot: InputFormField) -> ValidationError# No concept to name, hence no honest message to state: the lint's whole claim is about# what a named concept declares.return None- if slot.name is None:- # A top-level field always states its name — only a list's item omits one — but the wire- # model keeps the slot optional, and a finding with nothing to point at would not be one.- return None# Split on the LAST dot: a domain is a dotted path ('legal.contracts'), so a leading-dot split# would hand the locator a truncated domain and a pipe code carrying the rest of it.locator = QualifiedRef.parse(pipe_ref)diff --git a/pyproject.toml b/pyproject.tomlindex 36f965c03..ba8ea58ae 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -31,7 +31,7 @@ dependencies = ["json2html>=1.3.0","kajson==0.7.0","markdown>=3.6",- "mthds>=0.9.0",+ "mthds>=0.11.0","networkx>=3.4.2","openai>=2.0.0","opentelemetry-api",diff --git a/tests/helpers/input_form.py b/tests/helpers/input_form.pyindex 5d21962cb..efa788a1d 100644--- a/tests/helpers/input_form.py+++ b/tests/helpers/input_form.py@@ -12,9 +12,9 @@ from __future__ import annotationsfrom typing import TypeVar-from pipelex.pipeline.input_form import InputFormField, InputFormFieldBase, ListField, ObjectField+from pipelex.pipeline.input_form import InputFormField, InputFormItemBase, ListField, ObjectField-FieldModelType = TypeVar("FieldModelType", bound=InputFormFieldBase)+FieldModelType = TypeVar("FieldModelType", bound=InputFormItemBase)def as_kind(node: InputFormField, kind_model: type[FieldModelType]) -> FieldModelType:@@ -35,4 +35,4 @@ def as_list(node: InputFormField) -> ListField:def fields_by_name(node: InputFormField) -> dict[str, InputFormField]:"""An object node's payload fields keyed by their authored name."""- return {field.name: field for field in as_object(node).fields if field.name is not None}+ return {field.name: field for field in as_object(node).fields}diff --git a/tests/integration/pipelex/pipeline/test_input_form.py b/tests/integration/pipelex/pipeline/test_input_form.pyindex c779f8add..4308754cc 100644--- a/tests/integration/pipelex/pipeline/test_input_form.py+++ b/tests/integration/pipelex/pipeline/test_input_form.py@@ -105,7 +105,7 @@ prompt = "Write a haiku."def _field_by_name(descriptor: PipeInputFormDescriptor, name: str) -> InputFormField:- by_name = {field.name: field for field in descriptor.fields if field.name is not None}+ by_name = {field.name: field for field in descriptor.fields}assert name in by_name, f"Expected a field named {name!r}, got {sorted(by_name)}"return by_name[name]diff --git a/tests/unit/pipelex/pipeline/test_input_form_list_items.py b/tests/unit/pipelex/pipeline/test_input_form_list_items.pynew file mode 100644index 000000000..e94595c7c--- /dev/null+++ b/tests/unit/pipelex/pipeline/test_input_form_list_items.py@@ -0,0 +1,62 @@+"""Unit-pin that a list's `item` lands on the standard's nameless layer, not the named one."""++from __future__ import annotations++from pipelex.core.concepts.concept_blueprint import ConceptBlueprint+from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprint, ConceptStructureBlueprintFieldType+from pipelex.pipeline.input_form import InputFormDeriver, ObjectItem, TextItem+from tests.helpers.input_form import as_list, as_object+++class TestDerivedListItemsAreNameless:+ """A list's `item` lands on the standard's nameless layer, not on the named one wearing a blank name.++ Worth pinning explicitly, because every cheaper guard is blind to the difference. The wire is+ identical either way — the `item` slot is declared as the nameless model, so the serializer+ never writes a `name` whatever the object actually is — and a named model passes a static check+ against that slot too, since each `*Field` subclasses its `*Item`. So a node built one layer up+ and handed over unchanged (or one whose name was blanked with `model_copy`, which does not+ validate) would serialize correctly, type-check, and still be the wrong object. Only asking the+ derived item what it IS catches that.+ """++ def test_a_scalar_item_is_the_nameless_model(self) -> None:+ concepts: dict[str, ConceptBlueprint | str] = {+ "demo.Post": ConceptBlueprint(+ description="A post",+ structure={+ "tags": ConceptStructureBlueprint(+ description="Its tags", type=ConceptStructureBlueprintFieldType.LIST, item_type=ConceptStructureBlueprintFieldType.TEXT+ )+ },+ ),+ }+ post = InputFormDeriver(concepts=concepts).derive_concept(name="post", concept_ref="demo.Post")++ item = as_list(as_object(post).fields[0]).item+ assert isinstance(item, TextItem), f"Expected the nameless text model, got '{type(item).__name__}'"+ assert not hasattr(item, "name"), "An item carries no `name` member at all — not even one holding None"++ def test_a_concept_item_is_the_nameless_model_and_keeps_its_payload(self) -> None:+ """The rebuild drops the name and nothing else: the element concept's own fields survive it."""+ concepts: dict[str, ConceptBlueprint | str] = {+ "demo.Gadget": ConceptBlueprint(description="A gadget", structure={"trinket": "Its trinket"}),+ "demo.Box": ConceptBlueprint(+ description="A box",+ structure={+ "gadgets": ConceptStructureBlueprint(+ description="Its gadgets",+ type=ConceptStructureBlueprintFieldType.LIST,+ item_type=ConceptStructureBlueprintFieldType.CONCEPT,+ item_concept_ref="demo.Gadget",+ )+ },+ ),+ }+ box = InputFormDeriver(concepts=concepts).derive_concept(name="box", concept_ref="demo.Box")++ item = as_list(as_object(box).fields[0]).item+ assert isinstance(item, ObjectItem), f"Expected the nameless object model, got '{type(item).__name__}'"+ assert not hasattr(item, "name")+ assert item.concept_ref == "demo.Gadget"+ assert [field.name for field in item.fields or []] == ["trinket"], "The element concept's payload rides through the rebuild"diff --git a/tests/unit/pipelex/pipeline/test_input_form_models.py b/tests/unit/pipelex/pipeline/test_input_form_models.pyindex b8cf0e083..f746d26ff 100644--- a/tests/unit/pipelex/pipeline/test_input_form_models.py+++ b/tests/unit/pipelex/pipeline/test_input_form_models.py@@ -18,7 +18,7 @@ from pipelex.pipeline.input_form import (InputFormField,ListField,NumberField,- ObjectField,+ ObjectItem,PipeInputFormDescriptor,ProseField,TextField,@@ -77,7 +77,7 @@ class TestInputFormSerialization:presence=PresenceMarker.PLAIN,gating=True,item_count=2,- item=ObjectField(+ item=ObjectItem(concept_ref="demo.Gadget",required=True,fields=[TextField(name="label", required=True)],diff --git a/uv.lock b/uv.lockindex 40a24bedd..c884cddde 100644--- a/uv.lock+++ b/uv.lock@@ -2552,7 +2552,7 @@ wheels = [[[package]]name = "mthds"-version = "0.9.0"+version = "0.11.0"source = { registry = "https://pypi.org/simple" }dependencies = [{ name = "httpx" },@@ -2561,9 +2561,9 @@ dependencies = [{ name = "tomlkit" },{ name = "typing-extensions" },]-sdist = { url = "https://files.pythonhosted.org/packages/52/f3/e585dd38f4be879347702d2792c01b571fac607fdc5c520d8ed4d4592b90/mthds-0.9.0.tar.gz", hash = "sha256:2386f52d4bf40e13dbe793cbc9d45ab16981d3de8f846b42ad49f4a7412ea55a", size = 159117, upload-time = "2026-08-26T22:40:50.699Z" }+sdist = { url = "https://files.pythonhosted.org/packages/77/56/56b183589d379effac8af3e319a54907b767e8bd0f2114adacade72a8fde/mthds-0.11.0.tar.gz", hash = "sha256:26bc0fbac97e2ac2b92d7dbde4ef22fc952f3b7f0526987094a8c334b951855e", size = 165653, upload-time = "2026-08-27T12:01:42.887Z" }wheels = [- { url = "https://files.pythonhosted.org/packages/ec/17/6163b570259974bca8dacf8e0b4f0e83649eebae1f5dbbe16603a5e5d749/mthds-0.9.0-py3-none-any.whl", hash = "sha256:226410499aef67847519d994e4cf0fb1ac9b9621b96e34bc17bfa719dd856013", size = 68740, upload-time = "2026-08-26T22:40:49.33Z" },+ { url = "https://files.pythonhosted.org/packages/c1/39/df15725a1b461814d92467ec86b702e1211036782561e2bbd7f6e1b45a74/mthds-0.11.0-py3-none-any.whl", hash = "sha256:78897422a4da0b767cd0a0218fb44eba9fb325839085a4227588b52e1214431e", size = 71591, upload-time = "2026-08-27T12:01:41.686Z" },][[package]]@@ -3472,7 +3472,7 @@ requires-dist = [{ name = "mkdocs-meta-manager", marker = "extra == 'docs'", specifier = ">=1.1.0" },{ name = "mkdocs-redirects", marker = "extra == 'docs'", specifier = "==1.2.2" },{ name = "moto", extras = ["dynamodb", "s3"], marker = "extra == 'dev'", specifier = ">=5.0.0" },- { name = "mthds", specifier = ">=0.9.0" },+ { name = "mthds", specifier = ">=0.11.0" },{ name = "mypy", marker = "extra == 'dev'", specifier = "==1.19.1" },{ name = "networkx", specifier = ">=3.4.2" },{ name = "openai", specifier = ">=2.0.0" },