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.

22.6 KB
Raw Blame
"""`/execute` dispatches by orchestration_mode through the OrchestratorRegistry (full synchronous output).

Pins the dispatch + output-mapping independent of any real backend, with a stub orchestrator: the
runner resolves the deployment's orchestration_mode, dispatches the locally-built PipeJob through the
orchestrator the registry holds for it with `DeliveryMode.BLOCKING`, and rehydrates the orchestrator's
JSON-safe output back into the full PipeOutput the `/execute` response wraps — exercising the real
serialize -> rehydrate round-trip (`serialize_completed_output` -> `hydrate_working_memory`), including
the `graph_spec` and `pipe_io_artifacts` `strict=False` re-validation branches. Also pins the policy-gated per-request override
(symmetric with `/start`), the no-orchestrator case (`MissingOrchestratorError`), and the request id reaching the job the
orchestrator is handed, which is the payload a Temporal worker deserializes and binds its log context from. The boot slot is
never used — every mode dispatches through the per-call registry. (Delivery is endpoint-set, never
requestable, so `/execute` has no fire-and-forget refusal — that axis is `/start`'s.)
"""

from datetime import UTC, datetime
from typing import Any

import pytest
from fastapi import FastAPI
from fastapi.testclient import TestClient
from mthds.protocol.input_form import PipeInputFormDescriptor, TextField
from mthds.protocol.output_form import PipeOutputFormDescriptor
from mthds.protocol.pipe_io_contracts import (
    IOMultiplicity,
    PipeInputContract,
    PipeIOContract,
    PipeOutputContract,
    PresenceMarker,
)
from pipelex.core.memory.working_memory import MAIN_STUFF_NAME
from pipelex.core.pipes.pipe_io_artifacts import PipeIOArtifacts
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.errors.problem import ProblemView
from pipelex.errors.unsupported_reasons import METHOD_FILES_UNSUPPORTED_REASON
from pipelex.graph.graphspec import GraphSpec
from pipelex.pipe_run.delivery_assignment import DeliveryAssignment
from pipelex.pipe_run.pipe_job import PipeJob
from pipelex.pipeline.request_exceptions import PipelexRequestError
from pipelex.plugins.orchestrator_registry import OrchestratorRegistry
from pipelex.runtime_bridge.exceptions import MissingOrchestratorError
from pipelex.runtime_bridge.payloads import PipelexPipeDispatchAck, PipelexPipeRunOutput
from pipelex.runtime_bridge.serialization import serialize_completed_output
from pytest_mock import MockerFixture

from pipelex_api.api_config import ApiConfig
from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.middleware import REQUEST_ID_HEADER, RequestIdMiddleware
from pipelex_api.routes import router as api_router
from pipelex_api.routes.pipelex.pipeline import ApiRunner
from tests.unit._constants import VALID_MTHDS
from tests.unit._problems import assert_problem

_PIPELINE_NS = "pipelex_api.routes.pipelex.pipeline"


def _assert_the_files_map_refusal(*, error: PipelexRequestError) -> None:
    """The refusal of a `files` map handed to the runner object: on the field `files`, with the local runtime's reason."""
    assert error.field == "files"
    params = error.to_problem(view=ProblemView.CALLER).model_dump(mode="json")["params"]
    assert params == {"field": "files", "reason": METHOD_FILES_UNSUPPORTED_REASON}


class _StubOrchestrator:
    """A backend-agnostic stand-in orchestrator: echoes the job's working memory back as completed output.

    Returning via `serialize_completed_output` is the point — it produces the real JSON-safe
    `PipelexPipeRunOutput` (the same shape that crosses the Temporal worker boundary), so the route
    exercises the production serialize -> rehydrate round-trip instead of a hand-built payload. It
    records each dispatch so a test can assert `/execute` drove the blocking `execute` arm, and what the
    dispatched job's `RunMetadata` carries, since that is all a worker ever learns of the request. `start` (the
    fire-and-forget arm) is present only to satisfy the protocol — `/execute` never calls it.
    """

    def __init__(
        self,
        *,
        graph_spec: GraphSpec | None = None,
        pipe_io_artifacts: PipeIOArtifacts | None = None,
        pipe_io_artifacts_error: str | None = None,
        supports_fire_and_forget: bool = False,
    ) -> None:
        self.calls: list[dict[str, Any]] = []
        self._graph_spec = graph_spec
        self._pipe_io_artifacts = pipe_io_artifacts
        self._pipe_io_artifacts_error = pipe_io_artifacts_error
        self.supports_fire_and_forget = supports_fire_and_forget

    async def execute(self, *, pipe_job: PipeJob, delivery_assignment: DeliveryAssignment | None) -> PipelexPipeRunOutput:
        self.calls.append(
            {
                "pipe_code": pipe_job.pipe.code,
                "delivery_assignment": delivery_assignment,
                "request_id": pipe_job.job_metadata.run_metadata.request_id,
                "crate_fingerprint": pipe_job.job_metadata.run_metadata.crate_fingerprint,
            }
        )
        # A completed run always delivers a main stuff (pipelex invariant; enforced by
        # `resolve_main_stuff_root_key` in both `serialize_completed_output` and `from_pipe_output`).
        # This stub is an echo: promote the job's input stuff to the run's main stuff via the
        # `main_stuff` alias, so the serialize -> rehydrate round-trip yields a valid completed memory.
        working_memory = pipe_job.get_working_memory()
        working_memory.set_alias(alias=MAIN_STUFF_NAME, target=next(iter(working_memory.root)))
        return serialize_completed_output(
            pipe_output=PipeOutput(
                working_memory=working_memory,
                pipeline_run_id=pipe_job.job_metadata.run_metadata.pipeline_run_id,
                graph_spec=self._graph_spec,
                pipe_io_artifacts=self._pipe_io_artifacts,
                pipe_io_artifacts_error=self._pipe_io_artifacts_error,
            ),
            workflow_id=None,
        )

    async def start(self, *, pipe_job: PipeJob, delivery_assignment: DeliveryAssignment | None) -> PipelexPipeDispatchAck:
        msg = "/execute drives the blocking `execute` arm; `start` must not be reached."
        raise NotImplementedError(msg)


def _echo_pipe_io_artifacts() -> PipeIOArtifacts:
    """The I/O artifacts a run of the echo bundle would carry, keyed by its `pipe_ref`.

    Minimal but real: each of the carrier's members is the standard's own artifact type, so the
    dump the orchestrator produces is the shape a live run produces, not a stand-in dict.
    """
    return PipeIOArtifacts(
        pipe_io_contracts={
            "echo.echo": PipeIOContract(
                inputs={
                    "text": PipeInputContract(
                        concept_ref="native.Text",
                        presence=PresenceMarker.PLAIN,
                        multiplicity=IOMultiplicity.SINGLE,
                        item_count=None,
                        json_schema={"type": "string"},
                    )
                },
                output=PipeOutputContract(
                    concept_ref="native.Text",
                    multiplicity=IOMultiplicity.SINGLE,
                    item_count=None,
                    optional=False,
                    json_schema={"type": "string"},
                ),
            )
        },
        input_form={
            "echo.echo": PipeInputFormDescriptor(fields=[TextField(name="text", required=True, presence=PresenceMarker.PLAIN, gating=False)])
        },
        output_form={"echo.echo": PipeOutputFormDescriptor(field=TextField(name="result", required=True))},
    )


def _build_client(*, with_request_id_middleware: bool = False) -> TestClient:
    """Wire the real routes; `with_request_id_middleware` wraps the app the way `pipelex_api.main` does."""
    app = FastAPI()
    app.include_router(api_router, prefix="/v1")
    register_exception_handlers(app)
    return TestClient(RequestIdMiddleware(app) if with_request_id_middleware else app)


def _register_stub(mocker: MockerFixture, *, mode: str, stub: _StubOrchestrator) -> None:
    """Patch the orchestrator registry so the route's mode lookup finds `stub` for `mode`."""
    registry = OrchestratorRegistry({mode: stub})
    mocker.patch(f"{_PIPELINE_NS}.get_orchestrator_registry", return_value=registry)


def _force_config(mocker: MockerFixture, *, mode: str, allow_override: bool) -> None:
    """Patch the api config so `resolve_orchestration_mode` sees `mode` as the deployment default + policy."""
    config = ApiConfig(orchestration_mode=mode, allow_request_orchestration_mode_override=allow_override)
    mocker.patch(f"{_PIPELINE_NS}.get_api_config", return_value=config)


class TestExecuteDispatch:
    def test_direct_dispatch_returns_rehydrated_full_output(self, mocker: MockerFixture) -> None:
        """`direct` (the packaged default) dispatches through the registry and returns the full output."""
        stub = _StubOrchestrator()
        _register_stub(mocker, mode="direct", stub=stub)

        client = _build_client()
        response = client.post(
            "/v1/execute",
            json={"pipe_code": "echo", "mthds_contents": [VALID_MTHDS], "inputs": {"text": "hello"}},
        )

        assert response.status_code == 200, response.text
        body = response.json()
        assert body["state"] == "COMPLETED"
        # The full output survived the serialize -> rehydrate round-trip: the echo input is in the
        # rehydrated working memory the /execute response wraps.
        root = body["pipe_output"]["working_memory"]["root"]
        assert root["text"]["content"]["text"] == "hello"
        # The dispatch reached the registered orchestrator's blocking `execute` arm; /execute is
        # synchronous, so no delivery target (never the caller's to choose).
        assert len(stub.calls) == 1
        assert stub.calls[0]["delivery_assignment"] is None

    def test_the_result_reports_the_crate_the_job_was_built_from(self, mocker: MockerFixture) -> None:
        """`crate_fingerprint` is the fingerprint the dispatched job's `RunMetadata` carries, which a host records."""
        stub = _StubOrchestrator()
        _register_stub(mocker, mode="direct", stub=stub)

        response = _build_client().post(
            "/v1/execute",
            json={"pipe_code": "echo", "mthds_contents": [VALID_MTHDS], "inputs": {"text": "hello"}},
        )

        assert response.status_code == 200, response.text
        fingerprint = stub.calls[0]["crate_fingerprint"]
        assert isinstance(fingerprint, str)
        assert fingerprint
        assert response.json()["crate_fingerprint"] == fingerprint

    def test_graph_spec_survives_strict_false_rehydration(self, mocker: MockerFixture) -> None:
        """A non-None graph_spec round-trips through the helper's `strict=False` reverse of `model_dump(mode="json")`.

        Pins the most subtle line of `_pipe_output_from_run_output`: the orchestrator dumps `graph_spec`
        in JSON mode (so `GraphSpec.created_at`, a `strict=True` datetime, becomes an ISO string), and the
        helper must re-validate it with `strict=False` to restore the typed `GraphSpec`. Without the
        graph_spec branch exercised, a regression there (strict default, wrong key) would stay green.
        """
        graph_spec = GraphSpec(graph_id="g-1", created_at=datetime(2026, 1, 2, 3, 4, 5, tzinfo=UTC))
        stub = _StubOrchestrator(graph_spec=graph_spec)
        _register_stub(mocker, mode="direct", stub=stub)

        client = _build_client()
        response = client.post(
            "/v1/execute",
            json={"pipe_code": "echo", "mthds_contents": [VALID_MTHDS], "inputs": {"text": "hello"}},
        )

        assert response.status_code == 200, response.text
        # The graph_spec survived the dump -> strict=False re-validation: it is present in the response.
        assert response.json()["pipe_output"]["graph_spec"]["graph_id"] == "g-1"

    def test_pipe_io_artifacts_survive_strict_false_rehydration(self, mocker: MockerFixture) -> None:
        """A non-None `pipe_io_artifacts` reaches the `/execute` response beside `graph_spec`.

        The rule the design ratified is "wherever the graph travels, its description travels with
        it": the runtime fills `pipe_io_artifacts_dump` on the SPI payload exactly as it fills
        `graph_spec_dump`, and this repo is the only reader that puts it back on the public wire.
        Pins the carrier under its own key, so a dropped or misnamed key cannot stay green while
        the OpenAPI artifact still advertises the field. The error slot is `null` here only
        because the build succeeded; what pins *that* key is the failed-build test below, since a
        `null` assertion alone is also satisfied by the field's own default.
        """
        stub = _StubOrchestrator(pipe_io_artifacts=_echo_pipe_io_artifacts())
        _register_stub(mocker, mode="direct", stub=stub)

        client = _build_client()
        response = client.post(
            "/v1/execute",
            json={"pipe_code": "echo", "mthds_contents": [VALID_MTHDS], "inputs": {"text": "hello"}},
        )

        assert response.status_code == 200, response.text
        pipe_output = response.json()["pipe_output"]
        artifacts = pipe_output["pipe_io_artifacts"]
        # All three members survived the dump -> strict=False re-validation, under the standard's names.
        assert artifacts["pipe_io_contracts"]["echo.echo"]["output"]["concept_ref"] == "native.Text"
        assert artifacts["input_form"]["echo.echo"]["fields"][0]["name"] == "text"
        assert artifacts["output_form"]["echo.echo"]["field"]["name"] == "result"
        # The error slot rides along, null when the build succeeded (a host must tell that apart
        # from "the build failed", exactly as it does for the graph).
        assert pipe_output["pipe_io_artifacts_error"] is None

    def test_pipe_io_artifacts_error_reaches_the_wire(self, mocker: MockerFixture) -> None:
        """A failed artifact build is reported on the wire, and does not cost the run its result.

        Upstream builds the artifacts best-effort in a `finally` ahead of delivery and swallows
        whatever the builders raise onto `pipe_io_artifacts_error`, so the only way a caller can
        tell "the build failed" from "no artifacts were requested" is that field arriving non-null
        beside a `null` carrier. This is what actually pins the key through the SPI round-trip:
        asserting it is `null` on a successful run would pass just as well if the route stopped
        mapping it altogether.
        """
        message = "Failed to build the I/O artifacts for pipeline_run_id=run-1: contract will not render"
        stub = _StubOrchestrator(pipe_io_artifacts_error=message)
        _register_stub(mocker, mode="direct", stub=stub)

        client = _build_client()
        response = client.post(
            "/v1/execute",
            json={"pipe_code": "echo", "mthds_contents": [VALID_MTHDS], "inputs": {"text": "hello"}},
        )

        assert response.status_code == 200, response.text
        pipe_output = response.json()["pipe_output"]
        assert pipe_output["pipe_io_artifacts_error"] == message
        # A failed description never invalidates the run: the carrier is null and the result stands.
        assert pipe_output["pipe_io_artifacts"] is None
        assert response.json()["state"] == "COMPLETED"

    def test_pipe_io_artifacts_absent_when_the_run_carried_none(self, mocker: MockerFixture) -> None:
        """A run that built no artifacts yields a null carrier, not a missing key or a fabricated empty one."""
        stub = _StubOrchestrator()
        _register_stub(mocker, mode="direct", stub=stub)

        client = _build_client()
        response = client.post(
            "/v1/execute",
            json={"pipe_code": "echo", "mthds_contents": [VALID_MTHDS], "inputs": {"text": "hello"}},
        )

        assert response.status_code == 200, response.text
        pipe_output = response.json()["pipe_output"]
        assert pipe_output["pipe_io_artifacts"] is None
        assert pipe_output["pipe_io_artifacts_error"] is None

    def test_per_request_override_honored_when_policy_allows(self, mocker: MockerFixture) -> None:
        """With override ON, a per-request orchestration_mode is resolved and dispatched (symmetric with /start)."""
        _force_config(mocker, mode="direct", allow_override=True)
        stub = _StubOrchestrator()
        _register_stub(mocker, mode="temporal", stub=stub)

        client = _build_client()
        response = client.post(
            "/v1/execute",
            json={
                "pipe_code": "echo",
                "mthds_contents": [VALID_MTHDS],
                "inputs": {"text": "hello"},
                "orchestration_mode": "temporal",
            },
        )

        assert response.status_code == 200, response.text
        # The requested (non-default) backend was honored: dispatch reached the temporal-keyed stub.
        assert len(stub.calls) == 1

    def test_forbidden_orchestration_mode_override_is_a_403(self) -> None:
        """The route threads orchestration_mode into the same override policy /start uses: a forbidden override is a 403."""
        client = _build_client()
        # Packaged default is `direct` with override OFF; forcing a different backend is refused before dispatch.
        response = client.post(
            "/v1/execute",
            json={
                "pipe_code": "echo",
                "mthds_contents": [VALID_MTHDS],
                "inputs": {"text": "hello"},
                "orchestration_mode": "temporal",
            },
        )

        problem = assert_problem(response, status=422, code="pipelex.deployment.orchestration_override_forbidden")
        assert problem["params"] == {"requested_mode": "temporal"}

    def test_inbound_request_id_reaches_the_dispatched_job(self, mocker: MockerFixture) -> None:
        """On a `temporal` deployment, the inbound `X-Request-ID` rides the job the orchestrator is handed.

        A worker never sees the request: it binds its log context from the deserialized job's
        `RunMetadata.request_id`, and the middleware's in-process binding does not cross to it. So
        the proof is the payload, not the runner call — a route that passed the id to a runner which
        dropped it would still leave every worker line of the run without one.
        """
        _force_config(mocker, mode="temporal", allow_override=False)
        stub = _StubOrchestrator()
        _register_stub(mocker, mode="temporal", stub=stub)
        inbound_request_id = "01HNJZ4XR7K3Q9D8MWAQ7FY2E5"

        client = _build_client(with_request_id_middleware=True)
        response = client.post(
            "/v1/execute",
            json={"pipe_code": "echo", "mthds_contents": [VALID_MTHDS], "inputs": {"text": "hello"}},
            headers={REQUEST_ID_HEADER: inbound_request_id},
        )

        assert response.status_code == 200, response.text
        assert response.headers[REQUEST_ID_HEADER] == inbound_request_id
        assert len(stub.calls) == 1
        assert stub.calls[0]["request_id"] == inbound_request_id

    def test_minted_request_id_reaches_the_dispatched_job(self, mocker: MockerFixture) -> None:
        """Without an inbound header, the job carries the id the middleware minted, which the response echoes."""
        stub = _StubOrchestrator()
        _register_stub(mocker, mode="direct", stub=stub)

        client = _build_client(with_request_id_middleware=True)
        response = client.post(
            "/v1/execute",
            json={"pipe_code": "echo", "mthds_contents": [VALID_MTHDS], "inputs": {"text": "hello"}},
        )

        assert response.status_code == 200, response.text
        minted_request_id = response.headers[REQUEST_ID_HEADER]
        assert minted_request_id
        assert len(stub.calls) == 1
        assert stub.calls[0]["request_id"] == minted_request_id

    @pytest.mark.asyncio
    async def test_missing_orchestrator_for_resolved_mode_raises(self, mocker: MockerFixture) -> None:
        """A resolved mode with no registered orchestrator fails loud with MissingOrchestratorError."""
        mocker.patch(f"{_PIPELINE_NS}.get_orchestrator_registry", return_value=OrchestratorRegistry({}))

        with pytest.raises(MissingOrchestratorError) as exc_info:
            await ApiRunner().execute(
                pipe_code="echo",
                mthds_contents=[VALID_MTHDS],
                inputs={"text": "hello"},
            )
        # The packaged default is `direct`; the empty registry holds no orchestrator for it.
        assert exc_info.value.mode == "direct"
        # The deployment's own default has no orchestrator: the operator installs its plugin.
        assert exc_info.value.resolve_error_code() == "pipelex.plugin.not_found"

    @pytest.mark.asyncio
    async def test_missing_orchestrator_for_the_callers_override_is_unsupported(self, mocker: MockerFixture) -> None:
        """An override the caller named and the policy allows, which no installed plugin serves, is the caller's to change."""
        _force_config(mocker, mode="direct", allow_override=True)
        mocker.patch(f"{_PIPELINE_NS}.get_orchestrator_registry", return_value=OrchestratorRegistry({}))

        with pytest.raises(MissingOrchestratorError) as exc_info:
            await ApiRunner().execute(
                pipe_code="echo",
                mthds_contents=[VALID_MTHDS],
                inputs={"text": "hello"},
                requested_orchestration_mode="temporal",
            )
        assert exc_info.value.mode == "temporal"
        assert exc_info.value.resolve_error_code() == "runtime.unsupported"

    @pytest.mark.asyncio
    async def test_execute_refuses_a_method_given_as_the_protocol_s_files_map_before_any_dispatch(self, mocker: MockerFixture) -> None:
        """The runner's routes resolve a request's `files` into a tree themselves: the runner object takes `mthds_contents`."""
        registry = mocker.patch(f"{_PIPELINE_NS}.get_orchestrator_registry")

        with pytest.raises(PipelexRequestError) as exc_info:
            await ApiRunner().execute(pipe_code="echo", files={"main.mthds": VALID_MTHDS}, inputs={"text": "hello"})

        _assert_the_files_map_refusal(error=exc_info.value)
        registry.assert_not_called()

    @pytest.mark.asyncio
    async def test_start_refuses_a_method_given_as_the_protocol_s_files_map_before_any_dispatch(self, mocker: MockerFixture) -> None:
        registry = mocker.patch(f"{_PIPELINE_NS}.get_orchestrator_registry")

        with pytest.raises(PipelexRequestError) as exc_info:
            await ApiRunner().start(pipe_code="echo", files={"main.mthds": VALID_MTHDS}, inputs={"text": "hello"})

        _assert_the_files_map_refusal(error=exc_info.value)
        registry.assert_not_called()