Skip to content

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.

feature/Hosted-requirements-refusal-shape · L-261025-61814f — hosted requirements refusal shape (#1486)

Louis Choquel9a415f33af98
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 22b314fe4..0e83b06b8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
# Changelog
+## [Unreleased]
+
+### Changed
+
+- **The API server refuses a method's unmet requirements as an invalid method (Breaking)**: `/v1/execute` and `/v1/start` refuse a method whose `requirements.txt` the PipeFunc sandbox does not meet, or holds a line the standard refuses, with a `422` `method.invalid` whose `errors` hold one `method.dependency_missing` or `method.package_invalid` item per refused line, located at `requirements.txt` and the line, the problem a local run of the method raises and the items `/v1/validate` gives, where they answered a bare `method.dependency_missing` or `method.package_invalid` with no item and no location; a client reads the refused requirement from the item's `params` and `location`.
+
## [v0.91.0] - 2026-10-25
### Added
diff --git a/api/pipelex_api/routes/pipelex/pipeline.py b/api/pipelex_api/routes/pipelex/pipeline.py
index 7060046de..3eae4b51b 100644
--- a/api/pipelex_api/routes/pipelex/pipeline.py
+++ b/api/pipelex_api/routes/pipelex/pipeline.py
@@ -590,9 +590,14 @@ class ApiRunner(PipelexMTHDSProtocol):
and it is made through `tree_listing`, which the caller hands to the request's load, so the load reads the trees
checked here without listing them again.
+ A refusal of the method is the invalid verdict the load of the same directories gives, through the one translation
+ the run path's load uses (`translate_to_validate_bundle_error`): a `method.invalid` problem whose items each keep
+ their own code, a `method.dependency_missing` or a `method.package_invalid` located at `requirements.txt` and at the
+ line refused. A run answers it as a 422, and a validation as its invalid verdict.
+
Raises:
- MethodRequirementsFileError: The method's requirements.txt holds a line the standard refuses.
- MethodRequirementsNotMetError: The PipeFunc environment does not meet the method's requirements.
+ ValidateBundleError: The method's requirements.txt holds a line the standard refuses, or the PipeFunc
+ environment does not meet the method's requirements, or the deployment refuses them with its own reason.
HostLibraryTreeError: A directory of the request could not be listed as a method tree.
PipeFuncPackageSetUnstatedError: The deployment states no package set for its PipeFunc sandbox.
"""
@@ -601,7 +606,9 @@ class ApiRunner(PipelexMTHDSProtocol):
library_dirs = [Path(library_dir) for library_dir in self.library_dirs]
# In the method-load pool, whose cancellation waits for the check to end: the directories it lists are removed
# when the request's scope exits, which a client disconnect can make happen while the check still hashes them.
- await run_method_load(ensure_served_method_requirements_met, library_dirs=library_dirs, tree_listing=tree_listing)
+ # The directories are the caller's (`library_dirs_are_callers`), so their refusal is translated as their load's is.
+ with translate_to_validate_bundle_error():
+ await run_method_load(ensure_served_method_requirements_met, library_dirs=library_dirs, tree_listing=tree_listing)
async def validate_verdict(
self,
@@ -668,11 +675,10 @@ class ApiRunner(PipelexMTHDSProtocol):
# its PipeFunc steps run with, before any dispatch, so a refusal reaches the caller whichever validator runs. A
# worker a method tree's validation is dispatched to never reads these directories: it receives the method's
# trees through its method file store and judges their requirements again as it loads them. A refusal is the
- # method's invalid verdict, as a run of it is refused before its files load.
+ # method's invalid verdict, the same one a run of it is refused with before its files load.
tree_listing = MethodTreeListing()
try:
- with translate_to_validate_bundle_error():
- await self._ensure_served_method_requirements_met(tree_listing=tree_listing)
+ await self._ensure_served_method_requirements_met(tree_listing=tree_listing)
except ValidateBundleError as invalid_method:
return BundleValidationFailure(
problem=invalid_method.to_problem(view=ProblemView.OPERATOR),
diff --git a/api/tests/unit/test_method_requirements_refusal.py b/api/tests/unit/test_method_requirements_refusal.py
index 1838d1792..1e27d7c3d 100644
--- a/api/tests/unit/test_method_requirements_refusal.py
+++ b/api/tests/unit/test_method_requirements_refusal.py
@@ -1,10 +1,11 @@
"""A sandbox-hosted deployment refuses a method whose requirements.txt its PipeFunc sandbox does not meet, naming the packages.
The package set is what the plugin providing the execution mode states; here a stub registered for the neutral
-`sandbox` mode. A run is refused on the runner before the method's files load, before any dispatch, and a validation by
-address is refused on the runner as an invalid verdict, before the validator is reached, since a dispatched validator
-never reads the method's Python. A method of the runner's own library directories whose requirements are not met is
-the deployment's fault, never the caller's.
+`sandbox` mode. A run is refused on the runner before the method's files load, before any dispatch, as a 422
+`method.invalid` whose items locate each refused line of `requirements.txt`, the problem a local load of the same method
+raises, and a validation is refused on the runner as the invalid verdict carrying the same items, before the validator is
+reached, since a dispatched validator never reads the method's Python. A method of the runner's own library directories
+whose requirements are not met is the deployment's fault, never the caller's.
"""
import asyncio
@@ -47,6 +48,9 @@ _SANDBOX_ENVIRONMENT = "the Daytona sandbox snapshot 'pipelex-base-test'"
_ABSENT_PACKAGE = "pipelex-requirements-test-absent"
_UNRESOLVABLE_REQUIREMENT = "pandas<2"
_REFUSAL_REASON = "uv explains: Because pandas<2 conflicts with the base snapshot's pandas==2.2.3, the requirements are unsatisfiable."
+# The conformance fixture's requirements.txt: a comment, then a requirement the sandbox holds at a version it refuses.
+_UNMET_REQUIREMENTS_TEXT = "# The function imports pipelex alone\npydantic>=9999\n"
+_REQUIREMENTS_FILE = "requirements.txt"
_PLAIN_MTHDS = """\
domain = "plain_demo"
@@ -131,7 +135,7 @@ def _stated_offer(request: PipeFuncPackageOfferRequest) -> PipeFuncPackageOffer
return PipeFuncPackageRefusal(environment="the Daytona sandbox", reason=_REFUSAL_REASON)
return PipeFuncPackageOffer(
environment=_SANDBOX_ENVIRONMENT,
- distributions={"pandas": "2.2.3", "openpyxl": "3.1.5"},
+ distributions={"pandas": "2.2.3", "openpyxl": "3.1.5", "pydantic": "2.12.3"},
marker_environment={"python_version": "3.12", "sys_platform": "linux"},
)
@@ -168,25 +172,77 @@ def _build_client(
class TestMethodRequirementsRefusal:
+ @pytest.mark.usefixtures("sandbox_hosted_mode")
+ @pytest.mark.parametrize("route", ["/v1/execute", "/v1/start"])
+ def test_a_run_whose_requirement_the_sandbox_does_not_meet_is_an_invalid_method_located_on_the_line(
+ self, mocker: MockerFixture, route: str
+ ) -> None:
+ """The conformance case's refusal: a 422 `method.invalid` whose one item locates the requirement, as the caller reads it."""
+ orchestrator = _RecordingOrchestrator()
+ client = _build_client(mocker, orchestrator=orchestrator, validator=_UnreachableValidator())
+
+ files = {"main.mthds": _PIPE_FUNC_MTHDS, "funcs/pipe_func.py": _PIPE_FUNC_PY, _REQUIREMENTS_FILE: _UNMET_REQUIREMENTS_TEXT}
+ response = client.post(route, json={"files": files, "inputs": {"data": "1,2,3"}})
+
+ assert response.status_code == 422, response.text
+ assert response.headers["content-type"].startswith("application/problem+json")
+ body = response.json()
+ assert body["type"] == "https://mthds.ai/errors/method.invalid"
+ assert body["code"] == CoreCode.METHOD_INVALID
+ assert body["domain"] == "method"
+ assert body["status"] == 422
+ assert body["next_step"]["kind"] == "change_method"
+ # The refusal of the method is an item, not the problem: the problem itself names no parameter and no location.
+ assert "params" not in body
+ assert "location" not in body
+ assert body["errors"] == [
+ {
+ "code": CoreCode.METHOD_DEPENDENCY_MISSING,
+ "detail": "The method depends on the requirement 'pydantic', which is not available here (reason: no_matching_version).",
+ "params": {
+ "kind": MethodDependencyMissingKind.REQUIREMENT,
+ "name": "pydantic",
+ "reason": MethodDependencyMissingReason.NO_MATCHING_VERSION,
+ },
+ "location": {"file": _REQUIREMENTS_FILE, "line": 2},
+ }
+ ]
+ # The caller's view: the operator's message, which names the sandbox, stays out of it.
+ assert "diagnostics" not in body
+ assert orchestrator.dispatches == []
+
@pytest.mark.usefixtures("sandbox_hosted_mode")
def test_a_run_whose_requirements_the_sandbox_does_not_meet_is_refused_before_dispatch(self, mocker: MockerFixture) -> None:
orchestrator = _RecordingOrchestrator()
client = _build_client(mocker, orchestrator=orchestrator, validator=_UnreachableValidator(), as_operator=True)
- files = {"main.mthds": _PIPE_FUNC_MTHDS, "funcs/pipe_func.py": _PIPE_FUNC_PY, "requirements.txt": "pandas>=2\npandas>=3\npolars\n"}
+ files = {"main.mthds": _PIPE_FUNC_MTHDS, "funcs/pipe_func.py": _PIPE_FUNC_PY, _REQUIREMENTS_FILE: "pandas>=2\npandas>=3\npolars\n"}
response = client.post("/v1/start", json={"files": files, "inputs": {"data": "1,2,3"}})
assert response.status_code == 422, response.text
- assert response.headers["content-type"].startswith("application/problem+json")
body = response.json()
- assert body["code"] == CoreCode.METHOD_DEPENDENCY_MISSING
- assert body["domain"] == "method"
- assert body["diagnostics"]["error_class"] == "MethodRequirementsNotMetError"
- # The refusal names each package and the sandbox, and no directory of the runner.
- message = body["diagnostics"]["message"]
- assert "line 2 'pandas>=3' (pandas 2.2.3 is there); line 3 'polars' (polars is missing)" in message
- assert message.startswith(f"The method needs Python packages that {_SANDBOX_ENVIRONMENT} does not have")
- assert "rooted at" not in message
+ assert body["code"] == CoreCode.METHOD_INVALID
+ # One item per requirement not met, each on its line, naming the distribution that fails it and why.
+ assert [(item["code"], item["params"], item["location"]) for item in body["errors"]] == [
+ (
+ CoreCode.METHOD_DEPENDENCY_MISSING,
+ {"kind": "requirement", "name": "pandas", "reason": "no_matching_version"},
+ {"file": _REQUIREMENTS_FILE, "line": 2},
+ ),
+ (
+ CoreCode.METHOD_DEPENDENCY_MISSING,
+ {"kind": "requirement", "name": "polars", "reason": "not_found"},
+ {"file": _REQUIREMENTS_FILE, "line": 3},
+ ),
+ ]
+ # The operator reads which requirement the sandbox refuses and why, and no directory of the runner.
+ diagnostics = body["diagnostics"]
+ assert diagnostics["error_class"] == "ValidateBundleError"
+ assert diagnostics["causes"] == [{"error_class": "MethodRequirementsNotMetError", "code": CoreCode.METHOD_DEPENDENCY_MISSING}]
+ assert diagnostics["message"] == (
+ f"2 validation errors (first: The requirement 'pandas>=3' is not met by {_SANDBOX_ENVIRONMENT}: pandas 2.2.3 is there.)"
+ )
+ assert "rooted at" not in response.text
assert orchestrator.dispatches == []
@pytest.mark.usefixtures("sandbox_hosted_mode")
@@ -194,18 +250,19 @@ class TestMethodRequirementsRefusal:
orchestrator = _RecordingOrchestrator()
client = _build_client(mocker, orchestrator=orchestrator, validator=_UnreachableValidator(), as_operator=True)
- files = {"main.mthds": _PIPE_FUNC_MTHDS, "funcs/pipe_func.py": _PIPE_FUNC_PY, "requirements.txt": f"{_UNRESOLVABLE_REQUIREMENT}\n"}
+ files = {"main.mthds": _PIPE_FUNC_MTHDS, "funcs/pipe_func.py": _PIPE_FUNC_PY, _REQUIREMENTS_FILE: f"{_UNRESOLVABLE_REQUIREMENT}\n"}
response = client.post("/v1/start", json={"files": files, "inputs": {"data": "1,2,3"}})
assert response.status_code == 422, response.text
body = response.json()
- assert body["code"] == CoreCode.METHOD_DEPENDENCY_MISSING
- assert body["diagnostics"]["error_class"] == "MethodRequirementsNotMetError"
- # The deployment's own reason, and no directory of the runner.
- assert (
- body["diagnostics"]["message"]
- == f"The method needs Python packages that the Daytona sandbox cannot offer, as its requirements.txt declares: {_REFUSAL_REASON}"
- )
+ assert body["code"] == CoreCode.METHOD_INVALID
+ # The deployment's reason is about the requirements together, so its one item is on the file and no line.
+ (item,) = body["errors"]
+ assert item["code"] == CoreCode.METHOD_DEPENDENCY_MISSING
+ assert item["params"] == {"kind": "requirement", "name": "pandas", "reason": "no_matching_version"}
+ assert item["location"] == {"file": _REQUIREMENTS_FILE}
+ # The deployment's own reason reaches the operator, with no directory of the runner.
+ assert body["diagnostics"]["message"] == f"The requirements are refused by the Daytona sandbox: {_REFUSAL_REASON}"
assert orchestrator.dispatches == []
@pytest.mark.usefixtures("sandbox_hosted_mode")
@@ -224,16 +281,49 @@ class TestMethodRequirementsRefusal:
orchestrator = _RecordingOrchestrator()
client = _build_client(mocker, orchestrator=orchestrator, validator=_UnreachableValidator(), as_operator=True)
- files = {"main.mthds": _PIPE_FUNC_MTHDS, "funcs/pipe_func.py": _PIPE_FUNC_PY, "requirements.txt": "-r base.txt\n"}
+ files = {"main.mthds": _PIPE_FUNC_MTHDS, "funcs/pipe_func.py": _PIPE_FUNC_PY, _REQUIREMENTS_FILE: "-r base.txt\n"}
response = client.post("/v1/start", json={"files": files, "inputs": {"data": "1,2,3"}})
assert response.status_code == 422, response.text
body = response.json()
- assert body["code"] == CoreCode.METHOD_PACKAGE_INVALID
- assert body["diagnostics"]["error_class"] == "MethodRequirementsFileError"
+ assert body["code"] == CoreCode.METHOD_INVALID
+ assert body["errors"] == [
+ {
+ "code": CoreCode.METHOD_PACKAGE_INVALID,
+ "detail": "The method's package breaks a package rule (reason: requirements_invalid).",
+ "params": {"reason": "requirements_invalid", "path": _REQUIREMENTS_FILE},
+ "location": {"file": _REQUIREMENTS_FILE, "line": 1},
+ }
+ ]
+ assert body["diagnostics"]["causes"] == [{"error_class": "MethodRequirementsFileError", "code": CoreCode.METHOD_PACKAGE_INVALID}]
assert "line 1 '-r base.txt'" in body["diagnostics"]["message"]
assert orchestrator.dispatches == []
+ @pytest.mark.usefixtures("sandbox_hosted_mode")
+ @pytest.mark.parametrize(
+ "requirements_text",
+ [
+ pytest.param(_UNMET_REQUIREMENTS_TEXT, id="requirement-not-met"),
+ pytest.param("-r base.txt\n", id="line-the-standard-refuses"),
+ pytest.param(f"{_UNRESOLVABLE_REQUIREMENT}\n", id="refused-by-the-deployment"),
+ ],
+ )
+ def test_a_run_is_refused_with_the_items_of_the_validation_verdict(self, mocker: MockerFixture, requirements_text: str) -> None:
+ """The run's refusal and the verdict on the same tree are the one translation of the requirements check: same items."""
+ validator = _UnreachableValidator()
+ client = _build_client(mocker, orchestrator=_RecordingOrchestrator(), validator=validator)
+ files = {"main.mthds": _PIPE_FUNC_MTHDS, "funcs/pipe_func.py": _PIPE_FUNC_PY, _REQUIREMENTS_FILE: requirements_text}
+
+ run_response = client.post("/v1/execute", json={"files": files, "inputs": {"data": "1,2,3"}})
+ validate_response = client.post("/v1/validate", json={"files": files})
+
+ assert run_response.status_code == 422, run_response.text
+ assert validate_response.status_code == 200, validate_response.text
+ verdict = validate_response.json()
+ assert verdict["is_valid"] is False
+ assert run_response.json()["errors"] == verdict["errors"]
+ assert validator.calls == 0
+
@pytest.mark.usefixtures("sandbox_hosted_mode")
def test_a_validation_by_address_is_an_invalid_verdict_located_on_the_requirement(
self, mocker: MockerFixture, install_method_package: Callable[..., Path]
diff --git a/docs/api-server/error-responses.md b/docs/api-server/error-responses.md
index 61129959a..c66ba921a 100644
--- a/docs/api-server/error-responses.md
+++ b/docs/api-server/error-responses.md
@@ -124,7 +124,7 @@ An item writes no member that has no value: an absent member is not `null`.
Every invalid verdict carries a **non-empty** list of items — the structured-info invariant is total. A parse-level failure the runtime cannot attribute to a known pipe, concept or field — an empty blueprint, an elaborator failure — still becomes one residual item carrying the failure as its `finding`, so the list is never empty on an invalid verdict. A TOML syntax error is a `method.syntax` item whose `location` holds the `line` and `column` the parser stopped at, and the `file` when the caller sent one. A failing dry run is one item per failing pipe, located at the innermost pipe that failed. A dry run whose every failure belongs to someone other than the method's author, such as a storage outage, is no verdict about the method: it answers the failure's own code, with every failure riding its `errors`.
-On the run routes, **every refusal of the bundle while it loads is this verdict**, and the load happens before any pipe runs: a misspelled concept, a wiring mismatch, an unknown model, a TOML fault or a refusal raised while a pipe is built all answer the same **422** `method.invalid` carrying the same items validating the bundle gives. None of them reaches a run as a `500`. An entry pipe the bundle does not declare answers `request.pipe_not_found`, and a bare code matching pipes in several domains `request.pipe_ambiguous`.
+On the run routes, **every refusal of the bundle while it loads is this verdict**, and the load happens before any pipe runs: a misspelled concept, a wiring mismatch, an unknown model, a TOML fault, a refusal raised while a pipe is built and a line of the method's `requirements.txt` that the PipeFunc sandbox does not meet or that the standard refuses, which the runner judges before the load opens ([Pipe Run](pipe-run.md#sending-a-method-as-a-tree)), all answer the same **422** `method.invalid` carrying the same items validating the bundle gives. None of them reaches a run as a `500`. An entry pipe the bundle does not declare answers `request.pipe_not_found`, and a bare code matching pipes in several domains `request.pipe_ambiguous`.
## Suggested fixes
diff --git a/docs/api-server/pipe-run.md b/docs/api-server/pipe-run.md
index cbda13d8f..1fbf4c674 100644
--- a/docs/api-server/pipe-run.md
+++ b/docs/api-server/pipe-run.md
@@ -260,7 +260,31 @@ The older `mthds_contents`, which carries only `.mthds` text, and `resources`, w
**No Python structure classes.** A structure class (a `StructuredContent` subclass) can only be used by importing its module into the runner's own process, which a sandbox-hosted deployment never does, so a tree whose Python declares one is refused with a `422` problem, `pipelex.deployment.python_structures_refused`, before anything is loaded; its operator view's message names each file and class. The rule is the same however the method arrives: sent as a tree, or fetched by `method_ref`. Declare the types as MTHDS concepts with inline structures instead; a PipeFunc returns them by importing the classes the sandbox generates from those concepts (`from structures import <domain>__<Concept>`). The `structures` module that `pipelex build structures` writes is accepted as long as it is left as generated, and it is not sent to the sandbox, which generates its own.
-**Requirements are checked against the sandbox.** A `requirements.txt` at the root of the tree declares the packages its Python imports, one PEP 508 requirement per line (see [Method Trees](../building-methods/method-trees.md#python-packages-requirementstxt)). Nothing is installed into a running sandbox: the packages the deployment states its PipeFunc sandbox offers for the method's requirements are the whole offer, a fixed package set or an environment the deployment builds for those requirements, and a method asking for a package the sandbox does not offer, or for a version it does not offer, is refused with a `422` (`MethodRequirementsNotMetError`) naming each requirement and the version offered, before the method loads and before anything is dispatched. A deployment that can build no environment holding the requirements refuses them with the same `422`, carrying its own explanation. The refusal names the file by its tree path, `requirements.txt`, and no path on the server. A line the standard refuses, such as `-r base.txt`, a URL or a comment after a requirement, is a `422` (`MethodRequirementsFileError`) naming the line. A deployment that states no package set for its sandbox refuses every method declaring requirements with a `500` (`PipeFuncPackageSetUnstatedError`), a fault of its configuration, and so does a method of the server's own library directories whose requirements are not met (`HostLibraryRequirementsError`), whose message is withheld from the caller. A `method_ref` package is checked the same way, on a run as on [`/validate`](pipe-validate.md), where the refusal is an `is_valid: false` verdict located on the requirement's line.
+**Requirements are checked against the sandbox.** A `requirements.txt` at the root of the tree declares the packages its Python imports, one PEP 508 requirement per line (see [Method Trees](../building-methods/method-trees.md#python-packages-requirementstxt)). Nothing is installed into a running sandbox: the packages the deployment states its PipeFunc sandbox offers for the method's requirements are the whole offer, a fixed package set or an environment the deployment builds for those requirements, and a method asking for a package the sandbox does not offer, or for a version it does not offer, is refused before the method loads and before anything is dispatched with a `422` `method.invalid`, the problem an invalid bundle is refused with, whose `errors` hold one `method.dependency_missing` item per requirement not met, located at `location.file` `requirements.txt` and the requirement's `location.line`, its `params` naming the distribution that fails it (`name`) and why (`reason`: `not_found`, or `no_matching_version` for a version the requirement refuses). A deployment that can build no environment holding the requirements refuses them with the same `422`, its one `method.dependency_missing` item located on the file alone, and its own explanation in the operator's `diagnostics`. A line the standard refuses, such as `-r base.txt`, a URL or a comment after a requirement, is the same `422` with a `method.package_invalid` item on the line, whose `reason` is `requirements_invalid`. These are the items [`/validate`](pipe-validate.md) gives the same tree, and the ones a local run of the method is refused with. The refusal names the file by its tree path, `requirements.txt`, and no path on the server:
+
+```json
+{
+ "type": "https://mthds.ai/errors/method.invalid",
+ "title": "The method does not validate",
+ "status": 422,
+ "detail": "The method does not validate.",
+ "code": "method.invalid",
+ "domain": "method",
+ "retry": "no",
+ "next_step": {"kind": "change_method", "detail": "Fix each fault the problem's errors list, then validate the method again."},
+ "errors": [
+ {
+ "code": "method.dependency_missing",
+ "detail": "The method depends on the requirement 'pydantic', which is not available here (reason: no_matching_version).",
+ "params": {"kind": "requirement", "name": "pydantic", "reason": "no_matching_version"},
+ "location": {"file": "requirements.txt", "line": 2}
+ }
+ ],
+ "request_id": "9f2c1ab3-…"
+}
+```
+
+A deployment that states no package set for its sandbox refuses every method declaring requirements with a `500` (`PipeFuncPackageSetUnstatedError`), a fault of its configuration, and so does a method of the server's own library directories whose requirements are not met (`HostLibraryRequirementsError`), whose message is withheld from the caller. A `method_ref` package is checked the same way, on a run as on [`/validate`](pipe-validate.md), where the refusal is an `is_valid: false` verdict located on the requirement's line.
### Sending files by hash
diff --git a/docs/under-the-hood/pipe-func-requirements.md b/docs/under-the-hood/pipe-func-requirements.md
index 7c1c2cff9..77a10c782 100644
--- a/docs/under-the-hood/pipe-func-requirements.md
+++ b/docs/under-the-hood/pipe-func-requirements.md
@@ -54,10 +54,10 @@ A server loads its own library directories (`PIPELEXPATH`, the instance defaults
## Where the check runs on a sandbox-hosted deployment
-**On the runner first, and never in the sandbox.** The runner is the process that holds the method's files, and the place a refusal reaches the caller before anything is dispatched. The runner loads the directory it makes for a request's files as one of its own library directories, where a refusal is the host's fault, so it judges the caller's method first, through `ensure_served_method_requirements_met`, run off the event loop since it lists and hashes the method's files. It lists them through a `MethodTreeListing` (`pipelex/libraries/method_tree_listing.py`) it hands to the run or the validation serving the request, which loads the trees from it, so a request lists and hashes the method's files once:
+**On the runner first, and never in the sandbox.** The runner is the process that holds the method's files, and the place a refusal reaches the caller before anything is dispatched. It writes a request's method tree into a directory of its own and judges the caller's method there first, before any library opens or any run is registered, through `ensure_served_method_requirements_met`, run off the event loop since it lists and hashes the method's files. The directory holds the caller's method, so the check runs inside the same translation as the load of that directory, `translate_to_validate_bundle_error` (`pipelex/pipeline/validate_bundle_translation.py`), and its refusal is the problem a local load of the method raises: a `method.invalid` whose `errors` hold one item per refused line, each under its own code and located at `requirements.txt` and the line. It lists the files through a `MethodTreeListing` (`pipelex/libraries/method_tree_listing.py`) it hands to the run or the validation serving the request, which loads the trees from it, so a request lists and hashes the method's files once:
-- **A run** (`/execute`, `/start`) with a `files` or `bundle_b64` bundle, or by `method_ref`, is refused there as a `422` naming each requirement, before the method's files load and before any dispatch.
-- **A validation of a method tree** (`/validate`), sent in `files` or fetched by `method_ref`, is judged there too, whether its validator runs in the runner's process or on a worker it is dispatched to, a Temporal worker for instance: `ApiRunner.validate_verdict` returns a refusal as the invalid verdict, one item per line, before the validator is reached. Inline `mthds_contents` carry no Python and are not checked.
+- **A run** (`/execute`, `/start`) with a `files` or `bundle_b64` bundle, or by `method_ref`, is refused there with a `422` `method.invalid`, before the method's files load and before any dispatch: a requirement the sandbox does not meet is a `method.dependency_missing` item on its line, a line the standard refuses a `method.package_invalid` item on its line, and the deployment's own refusal of the requirements a `method.dependency_missing` item on the file alone.
+- **A validation of a method tree** (`/validate`), sent in `files` or fetched by `method_ref`, is judged there too, whether its validator runs in the runner's process or on a worker it is dispatched to, a Temporal worker for instance: `ApiRunner.validate_verdict` returns the same refusal as the invalid verdict, with the same items a run of the method is refused with, before the validator is reached. Inline `mthds_contents` carry no Python and are not checked.
- **A directory of the request that cannot be listed** stays the host's fault, a `500` `HostLibraryTreeError` carrying `pipelex.config.invalid`, as the load reports it.
- **The worker running a run** loads the library crate the runner built, which names each step's method tree by its digest and carries none of the tree's files, its Python and its `requirements.txt` included, so loading it checks nothing. A `PipeFunc` call's files are read on the worker, through the method file store its host installs (`HubSlot.METHOD_FILE_STORE`), and handed to the sandbox, which loads the same crate and checks nothing either.
- **A worker a method tree's validation is dispatched to** receives the method's trees rather than a crate (`BundleValidatorProtocol`) and loads them, so it judges the requirements again, in its own process and through its own listing, against the package set the plugins of its own process state for the mode. Its deployment therefore registers the same offer as the runner's: a worker stating none refuses every method declaring requirements with `PipeFuncPackageSetUnstatedError`.
@@ -119,4 +119,4 @@ For the hosted API, the Daytona sandbox plugin states the package set of the Day
| `HostLibraryRequirementsError` | `pipelex.config.invalid` | A method of a host's own library directories, loaded beside a caller's bundles, is refused for its requirements. |
| `PipeFuncPackageSetUnstatedError` | `runtime.misconfigured` | A sandbox-hosted deployment states no package set for its execution mode. |
-The first two are `LibraryLoadingError`s carrying one blueprint validation item per line, whose `source` is the file's path in the tree and whose `line` is the line's number, so a validation reports them as an invalid verdict located on the line. They are deliberately not `MethodTreeLoadError`s, which a server reports as its own fault around the library directories it loads.
+The first two are `LibraryLoadingError`s carrying one blueprint validation item per line, whose `source` is the file's path in the tree and whose `line` is the line's number, so a validation reports them as an invalid verdict located on the line, and a run, locally or on the API server, as the `method.invalid` problem carrying the same items, each under the error's code. They are deliberately not `MethodTreeLoadError`s, which a server reports as its own fault around the library directories it loads.
diff --git a/tests/unit/pipelex/libraries/test_method_requirements_check.py b/tests/unit/pipelex/libraries/test_method_requirements_check.py
index cb6430e3f..bf2381644 100644
--- a/tests/unit/pipelex/libraries/test_method_requirements_check.py
+++ b/tests/unit/pipelex/libraries/test_method_requirements_check.py
@@ -348,6 +348,49 @@ class TestMethodRequirementsCheck:
assert item.line == 1
assert f"The requirement '{_ABSENT_PACKAGE}' is not met" in item.message
+ @pytest.mark.parametrize(
+ ("topic", "requirements", "expected_item"),
+ [
+ (
+ "a requirement this interpreter holds at a version it refuses, after a comment",
+ "# The function imports pipelex alone\npydantic>=9999\n",
+ {
+ "code": "method.dependency_missing",
+ "detail": "The method depends on the requirement 'pydantic', which is not available here (reason: no_matching_version).",
+ "params": {"kind": "requirement", "name": "pydantic", "reason": "no_matching_version"},
+ "location": {"file": "requirements.txt", "line": 2},
+ },
+ ),
+ (
+ "a line the standard refuses",
+ "-r base.txt\n",
+ {
+ "code": "method.package_invalid",
+ "detail": "The method's package breaks a package rule (reason: requirements_invalid).",
+ "params": {"reason": "requirements_invalid", "path": "requirements.txt"},
+ "location": {"file": "requirements.txt", "line": 1},
+ },
+ ),
+ ],
+ )
+ def test_a_refusal_is_the_invalid_method_problem_carrying_its_located_item(
+ self, tmp_path: Path, topic: str, requirements: str, expected_item: dict[str, object]
+ ) -> None:
+ """The problem a local load and the runner's check both answer: `method.invalid`, the refused line as its one item."""
+ _method(directory=tmp_path, requirements=requirements)
+
+ with pytest.raises(ValidateBundleError) as exc_info, translate_to_validate_bundle_error():
+ ensure_served_method_requirements_met(library_dirs=[tmp_path])
+
+ problem = exc_info.value.to_problem(view=ProblemView.CALLER).to_wire()
+ assert problem["code"] == CoreCode.METHOD_INVALID, topic
+ assert problem["domain"] == ProblemDomain.METHOD
+ # The fault is the item's: the umbrella names no parameter and no location of its own.
+ assert "params" not in problem
+ assert "location" not in problem
+ assert problem["errors"] == [expected_item]
+ assert "diagnostics" not in problem
+
def test_a_served_method_refused_in_direct_mode_names_no_host_path_to_its_caller(self, tmp_path: Path) -> None:
"""This interpreter, read for real in the direct mode: the caller reads the method's lines, and no path on the host."""
method_dir = _method(directory=tmp_path / "request-files", requirements=f"pydantic>=2\n{_ABSENT_PACKAGE}>=1\n")