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/Entrypoint-function-raised · L-261019-65d73a (#1480)

Louis Choquel0ed7c271ba22
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 553a9f568..41b64c91d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,7 @@
- **OpenRouter model research**: `pipelex-dev openrouter list-models` looks up the public catalog across modalities, filters and sorts models, and emits Markdown or clean JSON. `--save` writes disabled draft backend TOML with output-token limits and known token prices for review, independently of remote-config tooling.
- **The validation report names the files each step reads**: `PipelexValidationReport`, and so the valid verdict of `/v1/validate`, carries `tree_files_read`, mapping each validated pipe's `pipe_ref` to the files of the method's tree it reads, each a `TreeFileRead` with its `tree_path` and its `use` (`template` for a `PipeDocGen` step's `template_file`, `template_asset` for a file its HTML template names by a literal relative URL, `python_module` for the module holding a `PipeFunc` step's function), an empty list for a pipe reading none, and `tree_file_readers`, mapping each of those files to the pipes that read it. `pipelex-agent validate bundle` and `validate method` carry both in their envelope, and the Markdown of a valid verdict lists them in a "Files the steps read" section.
+- **A sandboxed PipeFunc reports its function's own failure**: when the function a `PipeFunc` call runs raises inside a sandbox, `python -m pipelex.pipe_operators.func.pipe_func_transported_entrypoint` writes a `PipeFuncRaisedReport` to its result file before it exits non-zero, holding the operator's view of the `pipe.function_raised` problem, which names the function and the step and the class of what the function raised, never its text, while a sandbox failing any other way, such as a timeout inside it, still writes nothing there. An out-of-process executor reads the result file of a call that exited non-zero with `read_pipe_func_raised_report` (`pipelex.pipe_operators.func.pipe_func_execution_transport`), which answers the problem, rendered again from the registry and with only the diagnostics a sandbox writes, or `None` for no report or a report of any other code, and raises a Pipelex error carrying it, so the step reads `pipe.function_raised` as it does in process.
- **A fetched package is checked against the calling method's `methods.lock`**: when a method carries a `methods.lock` at the root of its tree, a package it calls by address that the runtime fetched itself, for this load or by an earlier fetch whose installed copy records its provenance, must have the tree digest the lock records for its address, whatever version the lock names, else the load is refused with the core code `security.integrity_mismatch` (domain `method`, a `422` with its security event on the API server), whose message names the locked and fetched versions and digests and says to pin the reference to the locked version or to lock the method again, or, when an installed copy answered a reference pinning another tag, says so and to remove that copy. A lock not naming the address, or no lock, checks nothing, and packages shipped with the method or installed by another tool are not checked. The lock is read only when a dependency resolves to such a copy, and one the runtime cannot read, one recording a `hash` from before tree digests included, then refuses the load with `method.package_invalid` and the new reason `lock_invalid`.
### Changed
diff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.md
index fa0e24061..7618319f0 100644
--- a/docs/under-the-hood/error-model.md
+++ b/docs/under-the-hood/error-model.md
@@ -139,7 +139,7 @@ A parameter the code does not declare, or one of the wrong type, is dropped when
| `runtime_version` | The version of the Pipelex runtime that built the problem |
| `trace_id`, `span_id` | The OpenTelemetry span the failure happened in, when one was recording |
-Every text a raise site, a provider or a caller wrote is bounded in a problem: `diagnostics.message`, the provider's message and every text parameter are cut to `MAX_PROBLEM_TEXT_LENGTH` characters by `cap_problem_text()`, which keeps the head of the text and appends ` […]`. The full text is left to the logs, so a provider's answer quoting a whole prompt cannot inflate a webhook, a stored run or a graph.
+Every text a raise site, a provider or a caller wrote is bounded in a problem: `diagnostics.message`, the provider's message, every text parameter and every text of the diagnostics a sandboxed `PipeFunc` call's report carries (see [A PipeFunc Call in a Sandbox](#a-pipefunc-call-in-a-sandbox)) are cut to `MAX_PROBLEM_TEXT_LENGTH` characters by `cap_problem_text()`, which keeps the head of the text and appends ` […]`. The full text is left to the logs, so a provider's answer quoting a whole prompt cannot inflate a webhook, a stored run or a graph.
### The identity, and why renaming an error class or changing its code is a wire break
@@ -172,7 +172,7 @@ class PipeRunInputsError(PipeRunError):
raise PipeRunInputsError(msg).with_error_code(CoreCode.INPUT_MISSING)
```
-`PipelexError.resolve_error_code()` walks the `__cause__` chain: it stops at the first error that carries a code by itself, the code its raise site chose or its class's, descends through every error that takes its cause's code, and stops at a cause that is not a Pipelex error. When no error on the way carries one, the error reports the code the deepest error implies (`implied_error_code`, which an inference error built with a category alone names, see below), else the fallback of the deepest wrapper, and `runtime.unexpected`, whose step is `report`, when none names one. It is one walk, guarded against a cyclic chain, and no error's code starts a walk of its own. So a wrapper that adds the fact deciding the code keeps its own over a coded cause, as `pipe.function_raised` does over any coded error raised inside the method's function (the in-process executor raises what the function raised as `PipeFuncRaisedError`, so a failure of the executor itself keeps its own code; an out-of-process executor must mark the function's failure the same way, with a Pipelex error carrying `pipe.function_raised`, since an exception that is not a Pipelex error, such as a transport failure, proves nothing about the function and reads `runtime.unexpected`), and a wrapper that adds nothing passes its cause's code through.
+`PipelexError.resolve_error_code()` walks the `__cause__` chain: it stops at the first error that carries a code by itself, the code its raise site chose or its class's, descends through every error that takes its cause's code, and stops at a cause that is not a Pipelex error. When no error on the way carries one, the error reports the code the deepest error implies (`implied_error_code`, which an inference error built with a category alone names, see below), else the fallback of the deepest wrapper, and `runtime.unexpected`, whose step is `report`, when none names one. It is one walk, guarded against a cyclic chain, and no error's code starts a walk of its own. So a wrapper that adds the fact deciding the code keeps its own over a coded cause, as `pipe.function_raised` does over any coded error raised inside the method's function (the in-process executor raises what the function raised as `PipeFuncRaisedError`, so a failure of the executor itself keeps its own code; an out-of-process executor must mark the function's failure the same way, with a Pipelex error carrying `pipe.function_raised`, which the sandbox reports in its result file (see [A PipeFunc Call in a Sandbox](#a-pipefunc-call-in-a-sandbox)), since an exception that is not a Pipelex error, such as a transport failure, proves nothing about the function and reads `runtime.unexpected`), and a wrapper that adds nothing passes its cause's code through.
`make_problem()` builds every problem from its code: the title, the documentation page, the domain, the retry verdict, the steps, the sentences' templates, the parameters model and the HTTP status are the code's, read from the registries' generated tables (`error_code_spec()` in `pipelex/errors/error_codes.py`), so building a problem is a pure lookup with no file read, safe inside a Temporal workflow's sandbox.
@@ -459,6 +459,16 @@ The runtime itself stays transport-agnostic: the machinery that carries an error
See [Runtime Bridge & Transport](./runtime-bridge-and-transport.md) for the boundary these converters span; the per-backend converters themselves live in the host-runtime plugins.
+### A PipeFunc Call in a Sandbox
+
+A sandbox-hosted deployment runs a `PipeFunc` call in an isolated sandbox, which runs one command, `python -m pipelex.pipe_operators.func.pipe_func_transported_entrypoint <request_json> <result_json> <tree_root>`: it reads the `PipeFuncExecutionRequest`, runs the call with the `direct` executor's transported path from the call's files unpacked at `<tree_root>`, and leaves its outcome in the result file and its exit code. The executor that dispatched the call reads them on the other side, and the contract between the two is three outcomes:
+
+- **The function returned.** The result file holds the `PipeFuncExecutionResponse`, and the process exits zero.
+- **The function raised.** The `direct` executor marks it as the function's own, `PipeFuncRaisedError`, whose parameters name the function and the step. The entrypoint writes a `PipeFuncRaisedReport` to the result file, whose `problem` is that error's problem in the operator's view, `pipe.function_raised`, its message naming the class of what the function raised and never its text (`pipe_func_raised_report()`), then exits non-zero with the traceback on stderr.
+- **The sandbox failed another way**, such as the function running past its timeout, the call's files that cannot be read back as a tree, or a step the crate does not hold. The process exits non-zero and writes nothing to the result file.
+
+So an executor reads the result file of a call that exited non-zero with `read_pipe_func_raised_report()` (`pipelex/pipe_operators/func/pipe_func_execution_transport.py`). A problem means the function raised: the executor raises a Pipelex error carrying it, whose `recovered_problem()` returns it, and the step reports `pipe.function_raised`, located at the pipe, as a run in this process does. `None` means the sandbox failed, and the executor raises an error of its own whose code says what failed, never `pipe.function_raised`. The report is written where the function ran, and the function can write the file itself, so the reader keeps only what `pipe.function_raised` lets a sandbox say: a report of any other code reads as no report, the sentences, the domain, the verdict and the step are rendered again from the registry with the parameters the code declares, the location is left to the run that locates the failure, and the diagnostics keep the error's class, its message and the classes and codes of its first `MAX_REPORTED_CAUSES` causes, each of these texts capped at `MAX_PROBLEM_TEXT_LENGTH` characters as a raise site's message is, so neither a long text nor a long list the function wrote travels whole into a stored run report, and the runtime's version only when it is a public version number, normalized and without a local label, since it also rides the metadata view, which holds nothing a user wrote. The success shape is unchanged, so a sandbox and an executor at different Pipelex versions still agree on a call that returns; an executor that does not read the report reads the function's failure as the sandbox's.
+
---
## Security Refusals and the Security Event
@@ -659,6 +669,7 @@ InferenceErrorCategory.TRANSIENT.is_retryable # True — only TRANSIENT
| `pipelex/errors/registry/pipelex-error-registry.yaml` | The Pipelex error registry, the single source of the `pipelex.` codes; its snapshot, its typed codes (`pipelex_codes.py`) and its pages are generated from it |
| `pipelex/errors/registry/registry_document.py` | The typed model of an MTHDS error registry, and `load_pipelex_error_registry()` |
| `pipelex/pipe_run/located_failure.py` | `find_root_fault()`, `located_root_fault()`, `failure_location_of()`, `make_unexpected_failure()` |
+| `pipelex/pipe_operators/func/pipe_func_execution_transport.py` | `pipe_func_raised_report()` and `read_pipe_func_raised_report()`: the report a sandboxed `PipeFunc` call writes when its function raises, and its reading back |
| `pipelex/graph/node_problem.py` | `make_node_problem()`: the caller-view problem a failed node of the execution graph records |
| `pipelex/pipeline/validation_errors.py` | `build_validation_error_items()` — shared CLI/API structured bundle-validation builder — and `problem_item_of()` |
| `pipelex/validation_error_types.py` | The closed `error_type` registry — `VALIDATION_ERROR_TYPES`, `PipeValidationErrorType`, `PipeFactoryErrorType`, `ValidationResidualErrorType`, `HintLintErrorType` |
@@ -711,6 +722,7 @@ InferenceErrorCategory.TRANSIENT.is_retryable # True — only TRANSIENT
| A pipe raises a non-Pipelex exception | Located as a `PipelexUnexpectedError` whose message names the original class; `runtime.unexpected`, its message the operator's alone |
| Failure on a distributed worker | The problem recovered from the transport's serialized details — the same as local |
| Worker exception with no packed problem | A fallback problem — `runtime.unexpected` |
+| A `PipeFunc`'s function raises inside a sandbox | The sandbox writes the operator's view of `pipe.function_raised` to its result file and exits non-zero; its executor reads it back and the step reports `pipe.function_raised`. A sandbox failing any other way writes no report and keeps a code of its own |
---
diff --git a/pipelex/pipe_operators/func/direct_pipe_func_executor.py b/pipelex/pipe_operators/func/direct_pipe_func_executor.py
index 22fee5f2c..9ed60b41b 100644
--- a/pipelex/pipe_operators/func/direct_pipe_func_executor.py
+++ b/pipelex/pipe_operators/func/direct_pipe_func_executor.py
@@ -136,6 +136,7 @@ class DirectPipeFuncExecutor(PipeFuncExecutorProtocol):
Raises:
PipeFuncExecutionError: The call's files cannot be read back as a tree, or the function runs past its timeout.
+ PipeFuncRaisedError: The function raised; its parameters name the function and the step.
"""
self._write_generated_structures(crate=request.crate, tree_root=tree_root)
try:
@@ -225,6 +226,11 @@ class DirectPipeFuncExecutor(PipeFuncExecutorProtocol):
.with_error_code(CoreCode.PIPE_FUNCTION_TIMED_OUT)
.with_params(function=request.function_name, timeout=request.timeout_seconds)
) from exc
+ except PipeFuncRaisedError as exc:
+ # The function's own failure names its step here: no router locates it in the process that runs the call, and
+ # the problem a sandbox reports for it (`pipe_func_raised_report`) is taken as it is where the call was made.
+ exc.with_params(pipe=pipe_func.code)
+ raise
# Wrap the output in a memory so it round-trips with its concept (and thus its class identity).
pipe = get_library_manager().get_library(library_id=TRANSPORTED_LIBRARY_ID).pipe_library.get_required_pipe(pipe_code=request.pipe_code)
diff --git a/pipelex/pipe_operators/func/pipe_func_execution_dtos.py b/pipelex/pipe_operators/func/pipe_func_execution_dtos.py
index c21b639d5..42c8c4136 100644
--- a/pipelex/pipe_operators/func/pipe_func_execution_dtos.py
+++ b/pipelex/pipe_operators/func/pipe_func_execution_dtos.py
@@ -72,3 +72,19 @@ class PipeFuncExecutionResponse(BaseModel):
output_memory_raw: dict[str, Any]
function_module: str | None = None
function_qualname: str | None = None
+
+
+class PipeFuncRaisedReport(BaseModel):
+ """What a transported call writes to its result file, in place of a response, when the function it calls raised.
+
+ The out-of-process twin of ``PipeFuncRaisedError``: the sandbox entrypoint writes it before it exits non-zero, so the
+ executor that dispatched the call tells the function's own failure, ``pipe.function_raised``, from a failure of the
+ sandbox itself (a timeout inside it, a boot that failed), which exits non-zero and writes nothing. ``problem`` is the
+ operator's view of that error's problem as ``PipelexProblem.to_wire()`` writes it: its message names the class of
+ what the function raised and never its text, which can quote the run's inputs. The file is written where the
+ function ran, so its reader trusts nothing but its shape (``read_pipe_func_raised_report``).
+ """
+
+ model_config = ConfigDict(extra="forbid")
+
+ problem: dict[str, Any]
diff --git a/pipelex/pipe_operators/func/pipe_func_execution_transport.py b/pipelex/pipe_operators/func/pipe_func_execution_transport.py
index 6728766fc..f27027945 100644
--- a/pipelex/pipe_operators/func/pipe_func_execution_transport.py
+++ b/pipelex/pipe_operators/func/pipe_func_execution_transport.py
@@ -1,10 +1,16 @@
+from mthds.protocol.problem.registry import CoreCode
+from packaging.version import InvalidVersion, Version
+from pydantic import ValidationError
+
from pipelex.core.memory.working_memory import WorkingMemory
+from pipelex.errors.problem import DiagnosticCause, PipelexProblem, ProblemDiagnostics, ProblemView, cap_problem_text, make_problem
from pipelex.interpreter_hub import get_current_library, get_library_manager
-from pipelex.pipe_operators.func.exceptions import PipeFuncTransportError
+from pipelex.pipe_operators.func.exceptions import PipeFuncRaisedError, PipeFuncTransportError
from pipelex.pipe_operators.func.pipe_func_execution_dtos import (
DEFAULT_PIPE_FUNC_TIMEOUT_SECONDS,
PipeFuncExecutionRequest,
PipeFuncExecutionResponse,
+ PipeFuncRaisedReport,
)
from pipelex.pipe_operators.func.pipe_func_executor_protocol import PipeFuncExecutionResult
from pipelex.pipe_run.pipe_run_params import PipeRunParams
@@ -16,6 +22,15 @@ from pipelex.system.job_metadata import JobMetadata
# they are re-exported here (and genuinely used by the builders below), so existing
# ``from ...pipe_func_execution_transport import PipeFuncExecutionRequest`` imports keep working.
+MAX_REPORTED_CAUSES = 10
+"""The most causes the diagnostics of a function's report keep: the first ones, nearest the error the function raised.
+
+A report's causes are the cause chain of what the function raised, which Python built and which is a handful of errors
+deep in practice, but the report is a file the function can write itself, with any number of causes in it, and none of
+them may travel whole into a stored run report. The first cause is the class of what the function raised, which the
+problem's message names too.
+"""
+
def build_pipe_func_execution_request(
*,
@@ -76,3 +91,79 @@ def pipe_func_execution_result_from_response(response: PipeFuncExecutionResponse
function_module=response.function_module,
function_qualname=response.function_qualname,
)
+
+
+def pipe_func_raised_report(*, error: PipeFuncRaisedError) -> PipeFuncRaisedReport:
+ """The report a transported call writes to its result file when the function it calls raised `error`.
+
+ The problem is `error`'s in the operator's view, built where the function ran: its code is `pipe.function_raised`,
+ its parameters name the function and the step, and its diagnostics name the class of what the function raised and
+ never its text, which can quote the run's inputs.
+ """
+ return PipeFuncRaisedReport(problem=error.to_problem(view=ProblemView.OPERATOR).to_wire())
+
+
+def read_pipe_func_raised_report(*, result_json: str | bytes) -> PipelexProblem | None:
+ """The problem of a function that raised in a transported call, read from the call's result file; `None` when it holds none.
+
+ An out-of-process executor reads the result file of a call whose sandbox exited non-zero with it: a report means the
+ function itself raised, and the executor raises a Pipelex error carrying the problem, which the step then reports
+ as `pipe.function_raised`; no report means the sandbox failed another way, and the failure keeps a code of its own.
+
+ The file was written where the function ran, and the function can write it too, so only what `pipe.function_raised`
+ lets it say is kept: a report of another code is no report, the sentences, the domain, the verdict and the step
+ are rendered again from the registry with the parameters the code declares, and the diagnostics keep the class of
+ the error, its message, the classes and codes of its first :data:`MAX_REPORTED_CAUSES` causes, every one of these
+ texts capped at :data:`~pipelex.errors.problem.MAX_PROBLEM_TEXT_LENGTH` characters, and the runtime's version when
+ it is a public version number (:func:`_reported_runtime_version`).
+
+ Args:
+ result_json: The content of the result file.
+
+ Returns:
+ The problem in the operator's view, or `None` when the file holds no report of the function's failure.
+ """
+ try:
+ report = PipeFuncRaisedReport.model_validate_json(result_json)
+ written = PipelexProblem.model_validate(report.problem)
+ except ValidationError:
+ return None
+ if written.code != CoreCode.PIPE_FUNCTION_RAISED:
+ return None
+ diagnostics: ProblemDiagnostics | None = None
+ if written.diagnostics is not None:
+ causes: list[DiagnosticCause] = []
+ for cause in (written.diagnostics.causes or [])[:MAX_REPORTED_CAUSES]:
+ code = cap_problem_text(text=cause.code) if cause.code is not None else None
+ causes.append(DiagnosticCause(error_class=cap_problem_text(text=cause.error_class), code=code))
+ diagnostics = ProblemDiagnostics(
+ error_class=cap_problem_text(text=written.diagnostics.error_class),
+ message=cap_problem_text(text=written.diagnostics.message),
+ causes=causes or None,
+ runtime_version=_reported_runtime_version(written=written.diagnostics.runtime_version),
+ )
+ return make_problem(
+ code=CoreCode.PIPE_FUNCTION_RAISED,
+ view=ProblemView.OPERATOR,
+ params=written.params.as_wire() if written.params is not None else None,
+ diagnostics=diagnostics,
+ )
+
+
+def _reported_runtime_version(*, written: str | None) -> str | None:
+ """The runtime version a function's report names, kept only when it is a public version number; `None` otherwise.
+
+ The version rides the metadata view of the problem too (`problem_metadata`), which holds no sentence and no name a
+ user wrote, while a report is a file the function can write itself. A version number, normalized and with no local
+ label, is digits and a release marker at most, so it says nothing else; a text that is no such number, or that the
+ cap at `MAX_PROBLEM_TEXT_LENGTH` characters cuts, is dropped rather than kept.
+ """
+ if written is None:
+ return None
+ try:
+ version = Version(cap_problem_text(text=written))
+ except InvalidVersion:
+ return None
+ if version.local is not None:
+ return None
+ return str(version)
diff --git a/pipelex/pipe_operators/func/pipe_func_transported_entrypoint.py b/pipelex/pipe_operators/func/pipe_func_transported_entrypoint.py
index 70fce9de0..8429cb3fa 100644
--- a/pipelex/pipe_operators/func/pipe_func_transported_entrypoint.py
+++ b/pipelex/pipe_operators/func/pipe_func_transported_entrypoint.py
@@ -15,8 +15,12 @@ the sandbox *client* (box provisioning, upload/download, teardown) is a worker-s
in the out-of-tree plugin. This is the module a sandbox client runs as
``python -m pipelex.pipe_operators.func.pipe_func_transported_entrypoint <request_json> <result_json> <tree_root>``.
-On any failure the process exits non-zero with a diagnostic on stderr, which the calling sandbox client
-turns into a sandbox error.
+On success the result file holds the ``PipeFuncExecutionResponse`` and the process exits zero. On any failure the
+process exits non-zero with a diagnostic on stderr. When the failure is the function's own, the ``direct`` executor's
+``PipeFuncRaisedError``, it first writes a ``PipeFuncRaisedReport`` to the result file, the operator's view of the
+``pipe.function_raised`` problem, which the calling sandbox client reads back (``read_pipe_func_raised_report``) and
+raises as the function's failure; on any other failure, such as the function running past its timeout or the call's
+files failing to load, it writes nothing there, and the client turns the exit into a sandbox error of its own.
"""
import asyncio
@@ -24,7 +28,9 @@ import sys
from pathlib import Path
from pipelex.pipe_operators.func.direct_pipe_func_executor import DirectPipeFuncExecutor
+from pipelex.pipe_operators.func.exceptions import PipeFuncRaisedError
from pipelex.pipe_operators.func.pipe_func_execution_dtos import PipeFuncExecutionRequest
+from pipelex.pipe_operators.func.pipe_func_execution_transport import pipe_func_raised_report
def main() -> None:
@@ -43,6 +49,11 @@ def main() -> None:
executor = DirectPipeFuncExecutor()
try:
result = asyncio.run(executor.run_pipe_func_transported_at(request=request, tree_root=tree_root))
+ except PipeFuncRaisedError as exc:
+ # The function's own failure is reported before the process exits non-zero, while Pipelex is still up to build
+ # its problem; the error still propagates, so the exit and the diagnostic on stderr are any failure's.
+ result_path.write_text(pipe_func_raised_report(error=exc).model_dump_json(), encoding="utf-8")
+ raise
finally:
Pipelex.teardown_if_needed()
result_path.write_text(result.model_dump_json(), encoding="utf-8")
diff --git a/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_transported_entrypoint.py b/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_transported_entrypoint.py
new file mode 100644
index 000000000..b7f1f1fb1
--- /dev/null
+++ b/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_transported_entrypoint.py
@@ -0,0 +1,264 @@
+import asyncio
+import sys
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+import pytest
+from mthds.protocol.problem.registry import CoreCode, ProblemDomain
+from pydantic import ValidationError
+from pytest_mock import MockerFixture
+
+from pipelex.base_exceptions import PipelexError
+from pipelex.config import get_config
+from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
+from pipelex.core.method_trees.tree_files import write_call_files
+from pipelex.errors.problem import MAX_PROBLEM_TEXT_LENGTH, ProblemDiagnostics, ProblemView, make_problem, problem_metadata
+from pipelex.interpreter_hub import get_library_manager, scoped_current_library
+from pipelex.libraries.pipe_func_call_files import read_pipe_func_call_files
+from pipelex.pipe_operators.func import pipe_func_transported_entrypoint
+from pipelex.pipe_operators.func.direct_pipe_func_executor import TRANSPORTED_LIBRARY_ID, DirectPipeFuncExecutor
+from pipelex.pipe_operators.func.exceptions import PipeFuncRaisedError
+from pipelex.pipe_operators.func.pipe_func_execution_dtos import PipeFuncExecutionRequest, PipeFuncExecutionResponse, PipeFuncRaisedReport
+from pipelex.pipe_operators.func.pipe_func_execution_transport import (
+ MAX_REPORTED_CAUSES,
+ build_pipe_func_execution_request,
+ pipe_func_raised_report,
+ read_pipe_func_raised_report,
+)
+from pipelex.pipe_run.pipe_run_params import PipeRunParams
+from pipelex.pipelex import Pipelex
+from pipelex.system.job_metadata import JobMetadata, RunMetadata
+from pipelex.system.pipe_run_mode import PipeRunMode
+
+#: What the function's own text quotes: the run's input, which no report may carry.
+_FUNCTION_TEXT = "cannot file the note 'confidential-patient-diagnosis'"
+
+_FUNCTION_NAME = "note_funcs.filing.file_note"
+
+_NOTE_MTHDS = """\
+domain = "note_demo"
+description = "A step whose function raises"
+
+[pipe.file_note]
+type = "PipeFunc"
+description = "File the note through customer code"
+output = "Text"
+function_name = "note_funcs.filing.file_note"
+"""
+
+_NOTE_FUNC = f"""\
+from pipelex.core.memory.working_memory import WorkingMemory
+from pipelex.core.stuffs.text_content import TextContent
+from pipelex.system.registries.func_registry import pipe_func
+
+
+@pipe_func()
+async def file_note(working_memory: WorkingMemory) -> TextContent:
+ raise KeyError("{_FUNCTION_TEXT}")
+"""
+
+
+@contextmanager
+def _note_request(*, tmp_path: Path) -> Generator[PipeFuncExecutionRequest, None, None]:
+ """The request a sandbox-hosted deployment builds for the step whose function raises, its library open while the call runs."""
+ method_dir = tmp_path / "note_method"
+ (method_dir / "note_funcs").mkdir(parents=True)
+ (method_dir / "note.mthds").write_text(_NOTE_MTHDS, encoding="utf-8")
+ (method_dir / "note_funcs" / "filing.py").write_text(_NOTE_FUNC, encoding="utf-8")
+
+ pipe_func_config = get_config().interpreter.pipe_func
+ previous_mode = pipe_func_config.execution_mode
+ pipe_func_config.execution_mode = "local_sandbox"
+ library_manager = get_library_manager()
+ try:
+ build_library_id, _ = library_manager.open_library()
+ try:
+ # Scoped, so a later test in the same worker never inherits the id of a library this helper tore down.
+ with scoped_current_library(library_id=build_library_id):
+ library_manager.load_libraries(library_id=build_library_id, library_dirs=[method_dir])
+ yield build_pipe_func_execution_request(
+ job_metadata=JobMetadata(
+ run_metadata=RunMetadata(storage_scope="test/scope", read_scope=None, user_id="user", pipeline_run_id="run")
+ ),
+ pipe_code="note_demo.file_note",
+ function_name=_FUNCTION_NAME,
+ working_memory=WorkingMemoryFactory.make_empty(),
+ pipe_run_params=PipeRunParams(run_mode=PipeRunMode.LIVE, pipe_stack_limit=10, batch_max_concurrency=None),
+ )
+ finally:
+ library_manager.teardown(library_id=build_library_id)
+ finally:
+ pipe_func_config.execution_mode = previous_mode
+
+
+def _run_entrypoint(*, mocker: MockerFixture, request: PipeFuncExecutionRequest, work_dir: Path) -> Path:
+ """Run the entrypoint as a sandbox runs it, its arguments the request, the result file and the unpacked call files.
+
+ The test session's Pipelex stands in for the one the entrypoint boots in a sandbox. Returns the result file's path.
+ """
+ request_path = work_dir / "request.json"
+ result_path = work_dir / "result.json"
+ tree_root = work_dir / "tree"
+ tree_root.mkdir()
+ request_path.write_text(request.model_dump_json(), encoding="utf-8")
+ assert request.tree_digest is not None
+ call_files = asyncio.run(read_pipe_func_call_files(tree_digest=request.tree_digest, read_scope=None))
+ write_call_files(files=call_files, destination=tree_root)
+ mocker.patch.object(sys, "argv", ["pipe_func_transported_entrypoint", str(request_path), str(result_path), str(tree_root)])
+ mocker.patch.object(Pipelex, "make")
+ mocker.patch.object(Pipelex, "teardown_if_needed")
+ with scoped_current_library(library_id=TRANSPORTED_LIBRARY_ID):
+ try:
+ pipe_func_transported_entrypoint.main()
+ finally:
+ get_library_manager().teardown(library_id=TRANSPORTED_LIBRARY_ID)
+ return result_path
+
+
+def _genuine_report_problem() -> dict[str, Any]:
+ """The problem a sandbox reports for a function that raised a `KeyError`, as it writes it."""
+ error = PipeFuncRaisedError("The function raised KeyError").with_params(function=_FUNCTION_NAME, pipe="file_note")
+ error.__cause__ = KeyError(_FUNCTION_TEXT)
+ return pipe_func_raised_report(error=error).problem
+
+
+class TestPipeFuncTransportedEntrypoint:
+ def test_a_function_that_raises_writes_its_coded_report(self, tmp_path: Path, mocker: MockerFixture) -> None:
+ """The function's own failure leaves `pipe.function_raised` in the result file, naming the function, the step and the class it raised."""
+ with _note_request(tmp_path=tmp_path) as request, pytest.raises(PipeFuncRaisedError):
+ _run_entrypoint(mocker=mocker, request=request, work_dir=tmp_path)
+
+ result_json = (tmp_path / "result.json").read_text(encoding="utf-8")
+ problem = read_pipe_func_raised_report(result_json=result_json)
+ assert problem is not None
+ assert problem.code == CoreCode.PIPE_FUNCTION_RAISED
+ assert problem.params is not None
+ assert problem.params.as_wire() == {"function": _FUNCTION_NAME, "pipe": "file_note"}
+ assert problem.diagnostics is not None
+ assert problem.diagnostics.error_class == "PipeFuncRaisedError"
+ assert problem.diagnostics.message == "The function raised KeyError"
+ assert [cause.error_class for cause in problem.diagnostics.causes or []] == ["KeyError"]
+ # What the function raised can quote the run's inputs: its class names it, and its text never reaches the file.
+ assert _FUNCTION_TEXT not in result_json
+ # A reader of the response alone refuses the report rather than misread it.
+ with pytest.raises(ValidationError, match="output_memory_raw"):
+ PipeFuncExecutionResponse.model_validate_json(result_json)
+
+ @pytest.mark.parametrize(
+ ("request_update", "times_out"),
+ [
+ ({}, True),
+ ({"pipe_code": "note_demo.missing_step"}, False),
+ ],
+ ids=["timed_out", "pipe_not_in_crate"],
+ )
+ def test_a_sandbox_that_fails_another_way_writes_no_report(
+ self, tmp_path: Path, mocker: MockerFixture, request_update: dict[str, Any], times_out: bool
+ ) -> None:
+ """A failure that is not the function's own exits non-zero with no result file, so its executor gives it a code of its own."""
+ if times_out:
+ mocker.patch.object(DirectPipeFuncExecutor, "run_pipe_func", side_effect=TimeoutError)
+
+ with _note_request(tmp_path=tmp_path) as request, pytest.raises(PipelexError) as raised:
+ _run_entrypoint(mocker=mocker, request=request.model_copy(update=request_update), work_dir=tmp_path)
+
+ assert not isinstance(raised.value, PipeFuncRaisedError)
+ assert not (tmp_path / "result.json").exists()
+
+ @pytest.mark.parametrize(
+ "result_json",
+ [
+ PipeFuncExecutionResponse(output_memory_raw={}).model_dump_json(),
+ "",
+ "{not json",
+ PipeFuncRaisedReport(problem={"code": "pipe.function_raised"}).model_dump_json(),
+ ],
+ ids=["response", "empty", "not_json", "not_a_problem"],
+ )
+ def test_a_file_holding_no_report_reads_as_none(self, result_json: str) -> None:
+ assert read_pipe_func_raised_report(result_json=result_json) is None
+
+ def test_a_report_of_another_code_is_no_report(self) -> None:
+ """The function can write the file itself, so a report is only ever of its own failure."""
+ problem = make_problem(
+ code=CoreCode.RUNTIME_UNEXPECTED,
+ view=ProblemView.OPERATOR,
+ diagnostics=ProblemDiagnostics(error_class="PipelexUnexpectedError", message="The worker ran out of memory"),
+ )
+ result_json = PipeFuncRaisedReport(problem=problem.to_wire()).model_dump_json()
+
+ assert read_pipe_func_raised_report(result_json=result_json) is None
+
+ def test_what_the_code_does_not_let_the_sandbox_say_is_rendered_again(self) -> None:
+ """The sentences, the domain and the step are the registry's, and the diagnostics keep only what the entrypoint writes."""
+ genuine = _genuine_report_problem()
+ forged = {
+ **genuine,
+ "detail": "Your account is suspended: write to us at the address below.",
+ "domain": ProblemDomain.OPERATOR,
+ "location": {"pipe": "elsewhere", "file": "/etc/passwd"},
+ "diagnostics": {**genuine["diagnostics"], "message": "x" * (MAX_PROBLEM_TEXT_LENGTH * 2), "provider": {"name": "forged"}},
+ }
+
+ genuine_problem = read_pipe_func_raised_report(result_json=PipeFuncRaisedReport(problem=genuine).model_dump_json())
+ forged_problem = read_pipe_func_raised_report(result_json=PipeFuncRaisedReport(problem=forged).model_dump_json())
+
+ assert genuine_problem is not None
+ assert forged_problem is not None
+ assert forged_problem.detail == "The function 'note_funcs.filing.file_note' of pipe 'file_note' raised an error."
+ genuine_wire = genuine_problem.to_wire()
+ forged_wire = forged_problem.to_wire()
+ assert genuine_wire.pop("diagnostics") == genuine["diagnostics"]
+ forged_diagnostics = forged_wire.pop("diagnostics")
+ assert forged_wire == genuine_wire
+ assert set(forged_diagnostics) == {"error_class", "message", "causes", "runtime_version"}
+ assert len(forged_diagnostics["message"]) == MAX_PROBLEM_TEXT_LENGTH
+
+ def test_every_diagnostics_text_of_a_report_is_capped_and_its_causes_bounded(self) -> None:
+ """The function can write any text and any number of causes into the file, and none of it travels whole."""
+ genuine = _genuine_report_problem()
+ oversized = "x" * (MAX_PROBLEM_TEXT_LENGTH * 2)
+ forged_causes = [{"error_class": oversized, "code": oversized}] + [{"error_class": "KeyError"}] * (MAX_REPORTED_CAUSES * 2)
+ forged = {
+ **genuine,
+ "diagnostics": {**genuine["diagnostics"], "error_class": oversized, "causes": forged_causes, "runtime_version": oversized},
+ }
+
+ problem = read_pipe_func_raised_report(result_json=PipeFuncRaisedReport(problem=forged).model_dump_json())
+
+ assert problem is not None
+ assert problem.diagnostics is not None
+ assert len(problem.diagnostics.error_class) == MAX_PROBLEM_TEXT_LENGTH
+ causes = problem.diagnostics.causes or []
+ assert len(causes) == MAX_REPORTED_CAUSES
+ assert len(causes[0].error_class) == MAX_PROBLEM_TEXT_LENGTH
+ assert causes[0].code is not None
+ assert len(causes[0].code) == MAX_PROBLEM_TEXT_LENGTH
+ assert [cause.error_class for cause in causes[1:]] == ["KeyError"] * (MAX_REPORTED_CAUSES - 1)
+ assert problem.diagnostics.runtime_version is None
+
+ @pytest.mark.parametrize(
+ ("written", "kept"),
+ [
+ ("0.90.0", "0.90.0"),
+ ("1.2.0rc1", "1.2.0rc1"),
+ ("v1.2.0-RC1", "1.2.0rc1"),
+ ("1.2.0+confidential.patient.diagnosis", None),
+ ("cannot file the note 'confidential-patient-diagnosis'", None),
+ ("1." + ".".join(["0"] * MAX_PROBLEM_TEXT_LENGTH), None),
+ ],
+ ids=["release", "pre_release", "normalized", "local_label", "sentence", "past_the_cap"],
+ )
+ def test_a_report_keeps_a_runtime_version_only_when_it_is_a_public_version_number(self, written: str, kept: str | None) -> None:
+ """The version reaches the metadata view, which holds nothing a user wrote, so only a version number is kept."""
+ genuine = _genuine_report_problem()
+ forged = {**genuine, "diagnostics": {**genuine["diagnostics"], "runtime_version": written}}
+
+ problem = read_pipe_func_raised_report(result_json=PipeFuncRaisedReport(problem=forged).model_dump_json())
+
+ assert problem is not None
+ assert problem.diagnostics is not None
+ assert problem.diagnostics.runtime_version == kept
+ assert problem_metadata(problem=problem).runtime_version == kept