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.
feat(protocol)!: PipelexRunner → PipelexMTHDSProtocol — implement the MTHDS Protocol locally (#985)
Thomas Hebrard9a64896a33ca
diff --git a/.claude/skills/temporal-e2e-validate/scripts/repro_runner_registry_bug.py b/.claude/skills/temporal-e2e-validate/scripts/repro_runner_registry_bug.pyindex afaaaaac7..142b6d0da 100644--- a/.claude/skills/temporal-e2e-validate/scripts/repro_runner_registry_bug.py+++ b/.claude/skills/temporal-e2e-validate/scripts/repro_runner_registry_bug.py@@ -27,7 +27,7 @@ from pipelex.cli.error_handlers import ErrorContextfrom pipelex.pipe_run.delivery_assignment import DeliveryAssignment, StorageTargetfrom pipelex.pipe_run.pipe_run_mode import PipeRunModefrom pipelex.pipelex import Pipelex-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolDEFAULT_BUNDLE = "tests/integration/pipelex/temporal/library_crate/dynamic_concept_sequence.mthds"DEFAULT_PIPE = "dynamic_greeting_sequence"@@ -35,7 +35,7 @@ DEFAULT_PIPE = "dynamic_greeting_sequence"async def submit(bundle: str, pipe_code: str) -> None:bundle_content = Path(bundle).read_text(encoding="utf-8")- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(bundle_uris=[bundle],pipe_run_mode=PipeRunMode.DRY,execution_config=None,@@ -43,13 +43,13 @@ async def submit(bundle: str, pipe_code: str) -> None:)delivery = DeliveryAssignment(storage=StorageTarget())print(f"Submitting pipe='{pipe_code}' with delivery_assignment={delivery!r}")- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code=pipe_code,mthds_contents=[bundle_content],inputs=None,delivery_assignment=delivery,)- print(f"OK: pipeline_run_id={response.pipeline_run_id} state={response.pipeline_state}")+ print(f"OK: pipeline_run_id={response.pipeline_run_id} state={response.state}")def main() -> None:diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f84b134da..dd2b6ddc1 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,11 +1,16 @@# Changelog-## [Unreleased]+## [v0.33.0] - 2026-06-11++### Breaking Changes++- **`PipelexRunner` → `PipelexMTHDSProtocol`** — the runner class now implements the MTHDS Protocol (`mthds.protocol.protocol.MTHDSProtocol`, mthds 0.4.0). Method renames: `execute_pipeline` → `execute`, `start_pipeline` → `start` (still `NotImplementedError` locally). `execute`/`start` carry the protocol's basic args plus a generic `extra` passthrough — server-specific args (a client-supplied run id, callbacks, a stored `method_id`) ride `extra`, never named params. Response classes: `PipelexPipelineExecuteResponse` → `PipelexRunResultExecute` (subclasses `RunResultExecute` — `pipeline_run_id` + `pipe_output`), `PipelexPipelineStartResponse` → `PipelexRunResultStart` (subclasses `RunResultStart` — `pipeline_run_id` only). `state` / `created_at` / `finished_at` / `main_stuff_name` / `workflow_id` are pipelex extension fields on the protocol's base responses; the run identifier keeps the name `pipeline_run_id` everywhere.+- **`mthds` pin → 0.4.0** — the restructured SDK (`mthds.protocol` + `mthds.runners.api`). The agent CLI's API run path uses `MthdsAPIClient` (`mthds.runners.api.client`) directly; domain shapes import from `mthds.protocol.*`, Dict wire models from `mthds.runners.api.models`.### Changed- **`--dry-run` now honors the configured backend — the mock moved from the operators to the cogt leaf.** `run_mode` rides a new `CogtRunParams` carrier (derived from `PipeRunParams.run_mode`, stamped on every cogt assignment, serialized across the Temporal wire), so a DRY run on a Temporal backend dispatches the REAL `act_llm_gen_*` / extract / img-gen / search / render activities and the leaf mocks **inside** the activity — testing dispatch, scheduling, serialization, routing, and cross-worker propagation at zero AI cost, with no API keys and no storage IO (the img/extract DRY branches sit above the store step). `ContentGeneratorDry` is deleted: operators no longer swap generators (the base operator's dry path simply reuses the live path), and the in-process validation scopes pass an inline `ContentGenerator`. Object mocks are now schema-built on every backend — identical mock on direct and Temporal; classes with exotic format constraints should declare `examples`/`mock_format` (a re-validation failure surfaces as a typed `DryRunObjectFidelityError`, and a deterministic mock-build failure as the new non-retryable `DryRunMockBuildError`). The acceptance gate is Tier 17 of the `temporal-e2e-validate` skill (GREEN on all leaf families + keyless worker, RED-proven) plus a Mode-1 pytest.-- **Unified dry run — `--mock-inference` removed (breaking).** There is now exactly one non-live run mode: `--dry-run`. The mock-inference mode is retired; its capability — non-zero synthetic usage so the cost report renders, used to validate cross-worker cost-report assembly cheaply — survives as an **internal** `is_mock_usage` sub-flag of DRY on `CogtRunParams` (replacing `is_mock_inference`; setting it on a LIVE run is a validation error). It is exposed on the Python surface (`PipelexRunner` / `execute_pipeline` / `prepare_pipe_job` via `is_mock_usage=...`) and as a hidden test-only CLI trigger, deliberately undocumented. Dry-run leaf coverage was already uniform across every operator, so `MockInferenceUnsupportedError` and its img-gen/extract/search guards are deleted; `MockInferenceObjectFidelityError` is renamed `DryRunObjectFidelityError` (mock-built objects are DRY-only now); the `mock_inference` usage sentinel is renamed `mock_usage`.+- **Unified dry run — `--mock-inference` removed (breaking).** There is now exactly one non-live run mode: `--dry-run`. The mock-inference mode is retired; its capability — non-zero synthetic usage so the cost report renders, used to validate cross-worker cost-report assembly cheaply — survives as an **internal** `is_mock_usage` sub-flag of DRY on `CogtRunParams` (replacing `is_mock_inference`; setting it on a LIVE run is a validation error). It is exposed on the Python surface (`PipelexMTHDSProtocol` / `execute` / `prepare_pipe_job` via `is_mock_usage=...`) and as a hidden test-only CLI trigger, deliberately undocumented. Dry-run leaf coverage was already uniform across every operator, so `MockInferenceUnsupportedError` and its img-gen/extract/search guards are deleted; `MockInferenceObjectFidelityError` is renamed `DryRunObjectFidelityError` (mock-built objects are DRY-only now); the `mock_inference` usage sentinel is renamed `mock_usage`.- **Keyless boot (`needs_inference=False`) now forces every run to DRY instead of installing a mock generator.** Generator selection is purely backend-keyed (a keyless Temporal submitter still dispatches and mocks inside activities); the forced-DRY flag is consumed at `PipeRunParamsFactory.make_run_params` — the single writer of `run_mode` — so every execution entry point is covered, including the runtime bridge.- **Temporal runs without graph events skip the guaranteed-empty trace-flush activity.** Post-fix, the workflow's in-memory trace buffer is populated only by inline (workflow-thread) emissions — and with the unified dry run mocking inside the leaf activities, the only inline source left is graph events when graph tracing is on. Every usage emission (LIVE, DRY, or mock-usage) happens activity-side through the per-process event log, so scheduling `act_flush_trace_events` with an empty payload was a wasted activity round-trip per workflow in the fan-out (history events, task-queue dispatch, worker slot — including every child workflow spawned by controllers). The schedule is now gated payload-purely on `emit_graph_events`, so the decision replays identically and the command stream stays a pure function of the payload.- **The "runner-side usage emission engaged" log is now INFO and states the actual contract.** Since activity-side usage emissions always go through the per-process activity event log (by design, co-located or split deployment alike), the old per-process WARNING — which claimed the fallback was specific to split deployments — fired on every standard deployment with a false explanation. Renamed to `log_once_runner_fallback_engaged`, logged once per process at INFO with the writer id.@@ -16,7 +21,7 @@### Fixed-- **Resubmitting a `pipeline_run_id` after its run finished no longer fails permanently.** `PipelineManager` was the one per-run registry with no per-run removal: every run permanently stranded its key, so a second submission of the same `pipeline_run_id` against a long-lived server process raised `PipelineManagerAlreadyExistsError` — surfacing as an unrecoverable 500 from the hosted runner API until process restart. The registry entry is now freed on every exit path: `execute_pipeline`'s `finally` removes it after each run (success or failure), and `pipeline_run_setup` removes its own registration when setup fails after registering (the caller never learns the id on that path, so setup must self-clean). Serial resubmission of a completed/failed run id now succeeds; only genuinely concurrent same-id runs still collide — deliberately, because the collision raise fires before `open_tracer` and shields the live direct-mode tracer (keyed by the caller-suppliable `pipeline_run_id`) from `open_tracer`'s stale-key pop-and-replace healing. The hosted API maps the remaining concurrent-duplicate case to 409 Conflict (pipelex-api change).+- **Resubmitting a `pipeline_run_id` after its run finished no longer fails permanently.** `PipelineManager` was the one per-run registry with no per-run removal: every run permanently stranded its key, so a second submission of the same `pipeline_run_id` against a long-lived server process raised `PipelineManagerAlreadyExistsError` — surfacing as an unrecoverable 500 from the hosted runner API until process restart. The registry entry is now freed on every exit path: `execute`'s `finally` removes it after each run (success or failure), and `pipeline_run_setup` removes its own registration when setup fails after registering (the caller never learns the id on that path, so setup must self-clean). Serial resubmission of a completed/failed run id now succeeds; only genuinely concurrent same-id runs still collide — deliberately, because the collision raise fires before `open_tracer` and shields the live direct-mode tracer (keyed by the caller-suppliable `pipeline_run_id`) from `open_tracer`'s stale-key pop-and-replace healing. The hosted API maps the remaining concurrent-duplicate case to 409 Conflict (pipelex-api change).- **The temporalio extra is no longer imported on every pipelex boot.** `reporting_manager.py` (imported by `pipelex.pipelex` on every `Pipelex.make()` / CLI invocation) eagerly imported `temporalio.activity` at module level to detect in-activity usage emissions — putting the entire temporalio import (Rust bridge, protobuf, ~130ms measured) on every boot's critical path wherever `pipelex[temporal]` is installed, including processes that never touch Temporal, and silently breaking the runtime bridge's documented lazy-import contract. The gate now sniffs `sys.modules` instead: a process that never imported `temporalio.activity` cannot be inside a Temporal activity (the activity context is set by temporalio's own machinery, which requires the module). Worker processes are unaffected. A subprocess boot-cost guard pins the lazy-import contract.- **Per-run Temporal worker-local state is keyed by run id, not workflow id.** The per-workflow library (`wf_{run_id}`), the graph tracer key, and the report-delegate event-log context key now use `workflow.info().run_id` — replay-stable but unique per run — instead of the workflow id. Workflow ids are reused across workflow-level `retry_policy` attempts, Temporal reset, and resubmission of the same `pipeline_run_id` (workflow ids derive deterministically from it), so workflow-id keying let a closed predecessor run's late eviction cleanup tear down a live successor run's library, tracer, and usage context on the same worker — failing the successor inline. With run-id keying such cross-run collisions are structurally impossible; `open_fresh_library` remains the same-run self-heal. `LibraryManager.teardown` also now forgets a library entry even if the library's own teardown raises (pop-first + `finally`), so a raising teardown can never turn into permanent worker-local poison, and the stale-entry healing path is tolerant of concurrent teardown.@@ -29,6 +34,8 @@### Added+- **Protocol `validate` / `models` / `version` on `PipelexMTHDSProtocol`** — `validate` wraps `validate_bundle` (blueprints + per-pipe structures into the protocol `ValidationReport`); `models` wraps the builder's `list_models` into a `ModelDeck`; `version` reports `protocol_version` 0.1.0 with the installed pipelex version.+- **Temporal test hang diagnostics (CI).** Setting `PIPELEX_HANG_DUMP_DIR` arms a per-test watchdog in the temporal integration suite that dumps every thread's stack to a file before pytest-timeout's thread-method kill destroys the process, and mirrors temporalio's failure logs (which carry the workflow-task traceback) to the same directory. The tests workflow prints these dumps when a job fails — pytest-xdist swallows worker stderr on a crash, so this is the only post-mortem signal for a hung test on a remote runner.- **`act_dry_validate` — the whole `/validate` job as ONE in-process Temporal activity.** New activity (+ one-step wrapper workflow `wf_dry_validate` and submitter helper `dispatch_dry_validate`) that runs the validation sweep **and** the graph-producing dry-run in one round-trip: the library is loaded once, the sweep borrows it, the graph dry-run traces into an in-memory event log against the same library, and the result carries `{per-pipe status map, GraphSpec | None}`. Zero nested Temporal dispatch, no NDJSON/DynamoDB tracing I/O, no usage/cost reporting. The graph is best-effort (an expected dry-run failure returns `graph_spec=None` with validation still successful); the sweep half is `validate_bundle` itself, so validation failures cross the activity boundary as structured `ErrorReport`s carrying the same categorized `ValidateBundleError` identity the direct path surfaces (a strict-mode signature refusal keeps its offending-pipe and signature refs in the caller-facing message). Registered in the `pipe` task pack; verified end-to-end in a real 3-process deployment (Tier 2d of the `temporal-e2e-validate` skill).@@ -36,6 +43,10 @@- **`dry_run_pipe_in_process` — graph-producing dry-run that never dispatches.** New entry in `pipelex/pipe_run/dry_run_pipeline.py`: dry-runs a pipe against an already-open library fully in-process and returns its `GraphSpec`, even under a Temporal-enabled hub. Three ContextVar scopes pin the whole run in-process: `scoped_event_log` (in-memory trace transport), `scoped_pipe_router` (nested controller sub-pipes resolve a local router instead of the `TemporalPipeRouter`), and the new `pipelex.hub.scoped_content_generator` (inference leaves resolve an inline dry generator instead of `ContentGeneratorInWorkflow` — holds regardless of whether the DRY mock lives at the pipe level or the leaf). This is the graph half of running `/validate` as one in-process Temporal activity.- **`scoped_event_log` — a shared, scope-pinned trace-event transport.** New `pipelex.hub.scoped_event_log(event_log)` context manager (with `get_event_log_override()` accessor, mirroring `scoped_pipe_router`): both the write side (tracer emission in `pipeline_run_setup`) and the read side (`assemble_tracing`) now prefer the scoped instance over building their own backend via `make_event_log`, so a run can trace into ONE shared `InMemoryEventLog` — no NDJSON file, no DynamoDB round-trip — and still assemble its `GraphSpec` from it. A set override implies tracing-enabled (honored even when `tracing_config.is_enabled` is off); the scoped instance's `close()` must be idempotent or a no-op (the write-side tracer closes its transport at teardown — `InMemoryEventLog`'s is a no-op). ContextVar-scoped, so concurrent runs with separate scopes stay isolated. This is the foundation for running the `/validate` graph dry-run fully in-process and in-memory inside a Temporal activity.+### Coordination++- **pipelex-worker lockstep** — the Temporal payload models cross into `pipelex-worker` via the `pipelex` pin; the worker must ship the same `pipelex` version as `pipelex-api` when the MTHDS Protocol unification deploys.+## [v0.32.1] - 2026-06-09diff --git a/docs/building-methods/libraries.md b/docs/building-methods/libraries.mdindex 62d3348a3..b44588a3f 100644--- a/docs/building-methods/libraries.md+++ b/docs/building-methods/libraries.md@@ -18,7 +18,7 @@ These three components together form what we call a **Pipelex Bundle** (the cont## Understanding Library Scope-When you execute pipelines using `execute_pipeline` or `start_pipeline`, a library is created to hold all the necessary definitions. This library:+When you execute pipelines using `execute` or `start`, a library is created to hold all the necessary definitions. This library:- Contains the pipes and concepts available for execution- Provides isolation between different pipeline runs when using different library IDs@@ -44,17 +44,18 @@ Libraries enforce specific uniqueness constraints to maintain consistency:Currently, all libraries are **local**, meaning they are loaded from:-- Directories on your filesystem (using `library_dirs` parameter)-- MTHDS content strings (using `mthds_content` parameter)+- Directories on your filesystem (using the `library_dirs` constructor parameter)+- MTHDS content strings (using the `mthds_contents` parameter)- The current working directory (default behavior)```python# Loading from local directories-pipe_output = await execute_pipeline(+runner = PipelexMTHDSProtocol(library_dirs=["./pipelines", "./shared_pipes"])+response = await runner.execute(pipe_code="generate_tagline",- library_dirs=["./pipelines", "./shared_pipes"],inputs={...},)+pipe_output = response.pipe_output```### Remote Libraries (Coming Soon)@@ -69,20 +70,20 @@ In the future, you'll be able to import and use remote libraries, enabling:### 1. Library Creation-When you call `execute_pipeline` or `start_pipeline`, a library is created with a unique `library_id`:+When the runner executes a method, a library is created with a unique `library_id`. Pipelex-specific configuration (library id, directories) is provided on the `PipelexMTHDSProtocol` constructor:```python# Explicit library ID-pipe_output = await execute_pipeline(+runner = PipelexMTHDSProtocol(library_id="my_custom_library")+response = await runner.execute(pipe_code="my_pipe",- library_id="my_custom_library", # Custom IDinputs={...},)# Automatic library ID (defaults to pipeline_run_id)-pipe_output = await execute_pipeline(+runner = PipelexMTHDSProtocol()+response = await runner.execute(pipe_code="my_pipe",- # library_id not specified - uses pipeline_run_idinputs={...},)```@@ -95,9 +96,9 @@ The library is populated based on the parameters you provide:```python# Loads all .mthds files from specified directories-pipe_output = await execute_pipeline(+runner = PipelexMTHDSProtocol(library_dirs=["./pipelines"])+response = await runner.execute(pipe_code="my_pipe",- library_dirs=["./pipelines"],inputs={...},)```@@ -119,8 +120,9 @@ output = "Tagline"prompt = "Generate a tagline for: @desc""""-pipe_output = await execute_pipeline(- mthds_content=mthds_content,+runner = PipelexMTHDSProtocol()+response = await runner.execute(+ mthds_contents=[mthds_content],pipe_code="my_pipe",inputs={...},)@@ -140,18 +142,16 @@ You can manage multiple libraries simultaneously by using different `library_id````python# Library for marketing pipelines-marketing_output = await execute_pipeline(+marketing_runner = PipelexMTHDSProtocol(library_id="marketing_lib", library_dirs=["./marketing_pipes"])+marketing_response = await marketing_runner.execute(pipe_code="generate_tagline",- library_id="marketing_lib",- library_dirs=["./marketing_pipes"],inputs={...},)# Library for analytics pipelines-analytics_output = await execute_pipeline(+analytics_runner = PipelexMTHDSProtocol(library_id="analytics_lib", library_dirs=["./analytics_pipes"])+analytics_response = await analytics_runner.execute(pipe_code="analyze_data",- library_id="analytics_lib",- library_dirs=["./analytics_pipes"],inputs={...},)```@@ -162,23 +162,24 @@ analytics_output = await execute_pipeline(```python# Good: Explicit ID for maintaining state-pipe_output = await execute_pipeline(+runner = PipelexMTHDSProtocol(library_id="app_library")+response = await runner.execute(pipe_code="my_pipe",- library_id="app_library",inputs={...},)```### 2. Use MTHDS Content for Dynamic Pipelines-When generating or modifying pipelines dynamically, use `mthds_content`:+When generating or modifying pipelines dynamically, use `mthds_contents`:```python# Generate MTHDS content dynamicallymthds_content = generate_custom_pipeline(user_requirements)-pipe_output = await execute_pipeline(- mthds_content=mthds_content,+runner = PipelexMTHDSProtocol()+response = await runner.execute(+ mthds_contents=[mthds_content],inputs={...},)```@@ -190,21 +191,17 @@ A temporary library will be created holding the Pipelex bundle, and the library_If multiple pipeline runs should share the same library context:```python-library_id = "shared_context"+runner = PipelexMTHDSProtocol(library_id="shared_context", library_dirs=["./pipes"])# First execution-output1 = await execute_pipeline(+response1 = await runner.execute(pipe_code="pipe1",- library_id=library_id,- library_dirs=["./pipes"],inputs={...},)# Second execution with same library-output2 = await execute_pipeline(+response2 = await runner.execute(pipe_code="pipe2",- library_id=library_id,- library_dirs=["./pipes"],inputs={...},)```diff --git a/docs/building-methods/pipes/executing-pipelines.md b/docs/building-methods/pipes/executing-pipelines.mdindex a7b0163ac..3c4ad4e76 100644--- a/docs/building-methods/pipes/executing-pipelines.md+++ b/docs/building-methods/pipes/executing-pipelines.md@@ -30,15 +30,15 @@ pipelex run bundle path/to/my_bundle.mthds --inputs inputs.json```pythonfrom pipelex.pipelex import Pipelex-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolPipelex.make()# Run the bundle's main_pipe-runner = PipelexRunner(+runner = PipelexMTHDSProtocol(bundle_uri="path/to/my_bundle.mthds",)-response = await runner.execute_pipeline(+response = await runner.execute(inputs={"my_input": {"concept": "Text",@@ -49,10 +49,10 @@ response = await runner.execute_pipeline(pipe_output = response.pipe_output# Or run a specific pipe from the bundle-runner = PipelexRunner(+runner = PipelexMTHDSProtocol(bundle_uri="path/to/my_bundle.mthds",)-response = await runner.execute_pipeline(+response = await runner.execute(pipe_code="my_specific_pipe",inputs={...},)@@ -82,13 +82,13 @@ When executing pipelines programmatically, Pipelex can load pipe **libraries** -#### Library Parameters-When using `PipelexRunner`, you can control library behavior with these parameters:+When using `PipelexMTHDSProtocol`, you can control library behavior with these parameters:- **`library_id`**: A unique identifier for the library instance. If not specified, it defaults to the `pipeline_run_id` (a unique ID generated for each pipeline execution).- **`library_dirs`**: A list of directory paths to load pipe definitions from. **These directories must contain both your `.mthds` files AND any Python files defining `StructuredContent` classes** (e.g., `*_struct.py` files). If not specified, Pipelex falls back to the `PIPELEXPATH` environment variable, then to the current working directory.-- **`mthds_content`**: When provided to `PipelexRunner.execute_pipeline()`, Pipelex will load only this content into the library, bypassing directory scanning. This is useful for dynamic pipeline execution without file-based definitions.+- **`mthds_contents`**: When provided to `PipelexMTHDSProtocol.execute()`, Pipelex will load only this content into the library, bypassing directory scanning. This is useful for dynamic pipeline execution without file-based definitions.!!! info "Python Structure Classes"If your concepts use Python `StructuredContent` classes instead of inline structures, those Python files must be in the directories specified by `library_dirs`. Pipelex auto-discovers and registers these classes during library loading. Learn more about [Python StructuredContent Classes](../concepts/python-classes.md).@@ -107,14 +107,14 @@ This approach loads pipe definitions from directories and executes a specific pi```pythonfrom pipelex.pipelex import Pipelex-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocol# First, initialize Pipelex (this loads all pipeline definitions)Pipelex.make()# Execute the pipeline and wait for the result-runner = PipelexRunner()-response = await runner.execute_pipeline(+runner = PipelexMTHDSProtocol()+response = await runner.execute(pipe_code="description_to_tagline",inputs={"description": {@@ -130,10 +130,10 @@ pipe_output = response.pipe_output```python# Load pipes from specific directories-runner = PipelexRunner(+runner = PipelexMTHDSProtocol(library_dirs=["./pipelines", "./shared_pipes"],)-response = await runner.execute_pipeline(+response = await runner.execute(pipe_code="description_to_tagline",inputs={"description": {@@ -149,11 +149,11 @@ pipe_output = response.pipe_output```python# Use a custom library ID for managing multiple library instances-runner = PipelexRunner(+runner = PipelexMTHDSProtocol(library_id="my_marketing_library",library_dirs=["./marketing_pipes"],)-response = await runner.execute_pipeline(+response = await runner.execute(pipe_code="description_to_tagline",inputs={"description": {@@ -170,11 +170,11 @@ pipe_output = response.pipe_output### Using MTHDS Content Directly-You can directly pass MTHDS content as a string to `PipelexRunner.execute_pipeline()`, useful for dynamic pipeline execution without file-based definitions.+You can directly pass MTHDS content as a string to `PipelexMTHDSProtocol.execute()`, useful for dynamic pipeline execution without file-based definitions.```pythonfrom pipelex.pipelex import Pipelex-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolmy_pipe_content = """domain = "marketing"@@ -199,9 +199,9 @@ Generate a catchy tagline based on the above description. The tagline should bePipelex.make()-runner = PipelexRunner()-response = await runner.execute_pipeline(- mthds_content=my_pipe_content,+runner = PipelexMTHDSProtocol()+response = await runner.execute(+ mthds_contents=[my_pipe_content],inputs={"description": {"concept": "ProductDescription",@@ -229,9 +229,9 @@ Pipelex has a REST API for executing pipelines. See more about it [here](https:/## Background Execution-<!-- start_pipeline exists on PipelexRunner as a protocol stub (raises NotImplementedError).- The public entry point is execute_pipeline(). Keep this note so reviewers don't flag the stub as contradictory. -->-The public Python entry point is `PipelexRunner.execute_pipeline()`. The older standalone `start_pipeline` function is no longer a documented entry point.+<!-- start exists on PipelexMTHDSProtocol as a protocol stub (raises NotImplementedError).+ The public entry point is execute(). Keep this note so reviewers don't flag the stub as contradictory. -->+The public Python entry point is `PipelexMTHDSProtocol.execute()`. The older standalone `start` function is no longer a documented entry point.---diff --git a/docs/building-methods/pipes/pipe-output.md b/docs/building-methods/pipes/pipe-output.mdindex 84e08b930..9c196d5c2 100644--- a/docs/building-methods/pipes/pipe-output.md+++ b/docs/building-methods/pipes/pipe-output.md@@ -24,10 +24,12 @@ The **main_stuff** is the final output produced by the last pipe in your pipelinWhen you execute a pipeline, you receive a `PipeOutput` object:```python-pipe_output = await execute_pipeline(+runner = PipelexMTHDSProtocol()+response = await runner.execute(pipe_code="process_invoice",- inputs={...}+ inputs={...},)+pipe_output = response.pipe_output```The `PipeOutput` object provides methods to extract and work with the main output.@@ -43,10 +45,12 @@ If the output concept was defined as a Python class (inheriting from `Structured```pythonfrom my_project.finance.finance_struct import Invoice-pipe_output = await execute_pipeline(+runner = PipelexMTHDSProtocol()+response = await runner.execute(pipe_code="extract_invoice",- inputs={...}+ inputs={...},)+pipe_output = response.pipe_output# Extract with type safetyinvoice = pipe_output.main_stuff_as(content_type=Invoice)@@ -58,10 +62,12 @@ invoice = pipe_output.main_stuff_as(content_type=Invoice)If the output concept was defined with [inline structures](../concepts/inline-structures.md) directly in the `.mthds` file, the generated class is not importable. Use the `PipeOutput` accessor methods instead:```python-pipe_output = await execute_pipeline(+runner = PipelexMTHDSProtocol()+response = await runner.execute(pipe_code="extract_invoice",- inputs={...}+ inputs={...},)+pipe_output = response.pipe_output# Access as dictionary-like structuremain_stuff = pipe_output.main_stuffdiff --git a/docs/building-methods/pipes/provide-inputs.md b/docs/building-methods/pipes/provide-inputs.mdindex 6b6f554d8..db19acde0 100644--- a/docs/building-methods/pipes/provide-inputs.md+++ b/docs/building-methods/pipes/provide-inputs.md@@ -383,7 +383,7 @@ from pipelex.core.stuffs.stuff import DictStuffclient = PipelexClient(api_token="YOUR_API_KEY")# Using DictStuff instance with dict content-response = await client.execute_pipeline(+response = await client.execute(pipe_code="process_invoice",inputs={"invoice": DictStuff(@@ -398,7 +398,7 @@ response = await client.execute_pipeline()# Using DictStuff instance with list of dicts-response = await client.execute_pipeline(+response = await client.execute(pipe_code="process_invoices",inputs={"invoices": DictStuff(diff --git a/docs/building-methods/pipes/understanding-multiplicity.md b/docs/building-methods/pipes/understanding-multiplicity.mdindex aea679112..4f717ec9f 100644--- a/docs/building-methods/pipes/understanding-multiplicity.md+++ b/docs/building-methods/pipes/understanding-multiplicity.md@@ -379,11 +379,11 @@ Use fixed input multiplicity when:When a pipe produces multiple outputs, Pipelex automatically wraps them in a `ListContent` container. This container maintains the type information:```python-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocol# Execute a pipe with multiple outputs-runner = PipelexRunner()-response = await runner.execute_pipeline(+runner = PipelexMTHDSProtocol()+response = await runner.execute(pipe_code="extract_line_items",inputs={"invoice_text": "Your invoice text here..."})@@ -401,11 +401,11 @@ line_items_container = pipe_output.main_stuff_as_list(item_type=LineItem)Similarly, when providing multiple inputs, you can use lists:```python-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.core.stuffs.text_content import TextContent-runner = PipelexRunner()-response = await runner.execute_pipeline(+runner = PipelexMTHDSProtocol()+response = await runner.execute(pipe_code="summarize_all_documents",inputs={"documents": [diff --git a/docs/configuration/config-technical/library-config.md b/docs/configuration/config-technical/library-config.mdindex 9936a8fdd..75e455c2a 100644--- a/docs/configuration/config-technical/library-config.md+++ b/docs/configuration/config-technical/library-config.md@@ -26,22 +26,22 @@ pipelex run bundle path/to/my_bundle.mthds --pipe my_pipe``````python-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocol# Python: run the bundle's main_pipe-runner = PipelexRunner(+runner = PipelexMTHDSProtocol(bundle_uri="path/to/my_bundle.mthds",)-response = await runner.execute_pipeline(+response = await runner.execute(inputs={...},)pipe_output = response.pipe_output# Python: run a specific pipe from the bundle-runner = PipelexRunner(+runner = PipelexMTHDSProtocol(bundle_uri="path/to/my_bundle.mthds",)-response = await runner.execute_pipeline(+response = await runner.execute(pipe_code="my_pipe",inputs={...},)@@ -145,33 +145,33 @@ pipelex which my_pipe -L /path/to/pipelines/dir### Setting Instance Defaults with `Pipelex.make()`-For Python applications, you can set a default library directory when initializing Pipelex. This default will be used for all subsequent `PipelexRunner.execute_pipeline()` calls unless overridden.+For Python applications, you can set a default library directory when initializing Pipelex. This default will be used for all subsequent `PipelexMTHDSProtocol.execute()` calls unless overridden.```pythonfrom pipelex.pipelex import Pipelex-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocol# Set instance-level defaults at initializationPipelex.make(library_dirs=["/path/to/shared_pipes", "/path/to/project_pipes"])-# All PipelexRunner.execute_pipeline() calls will use these directories by default-runner = PipelexRunner()-response = await runner.execute_pipeline(+# All PipelexMTHDSProtocol.execute() calls will use these directories by default+runner = PipelexMTHDSProtocol()+response = await runner.execute(pipe_code="my_pipe",inputs={"input": "value"},)pipe_output = response.pipe_output```-### Per-Runner Override with `PipelexRunner`+### Per-Runner Override with `PipelexMTHDSProtocol`-For maximum flexibility, you can override library directories on each `PipelexRunner` instance:+For maximum flexibility, you can override library directories on each `PipelexMTHDSProtocol` instance:```pythonfrom pipelex.pipelex import Pipelex-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocol# Initialize with default directoriesPipelex.make(@@ -179,28 +179,28 @@ Pipelex.make()# Use the default directories-runner1 = PipelexRunner()-response1 = await runner1.execute_pipeline(+runner1 = PipelexMTHDSProtocol()+response1 = await runner1.execute(pipe_code="default_pipe",inputs={"input": "value"},)pipe_output1 = response1.pipe_output# Override for a specific execution-runner2 = PipelexRunner(+runner2 = PipelexMTHDSProtocol(library_dirs=["/path/to/special_pipes"], # Overrides instance default)-response2 = await runner2.execute_pipeline(+response2 = await runner2.execute(pipe_code="special_pipe",inputs={"input": "value"},)pipe_output2 = response2.pipe_output# Disable directory loading (use only mthds_content)-runner3 = PipelexRunner(+runner3 = PipelexMTHDSProtocol(library_dirs=[], # Empty list disables directory-based loading)-response3 = await runner3.execute_pipeline(+response3 = await runner3.execute(mthds_content=my_mthds_string,inputs={"input": "value"},)@@ -217,14 +217,14 @@ export PIPELEXPATH="/shared/pipes"``````python-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocol# Python: No library_dirs specified anywherePipelex.make() # No library_dirs# Uses PIPELEXPATH: /shared/pipes-runner = PipelexRunner()-response = await runner.execute_pipeline(pipe_code="my_pipe", inputs={...})+runner = PipelexMTHDSProtocol()+response = await runner.execute(pipe_code="my_pipe", inputs={...})pipe_output = response.pipe_output```@@ -236,29 +236,29 @@ export PIPELEXPATH="/shared/pipes"``````python-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocol# Python: Instance default setPipelex.make(library_dirs=["/project/pipes"])# Uses instance default: /project/pipes (PIPELEXPATH ignored)-runner = PipelexRunner()-response = await runner.execute_pipeline(pipe_code="my_pipe", inputs={...})+runner = PipelexMTHDSProtocol()+response = await runner.execute(pipe_code="my_pipe", inputs={...})pipe_output = response.pipe_output```**Example 3: Per-call override takes highest priority**```python-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolPipelex.make(library_dirs=["/default/pipes"])# Uses per-runner value: /special/pipes-runner = PipelexRunner(+runner = PipelexMTHDSProtocol(library_dirs=["/special/pipes"], # Highest priority)-response = await runner.execute_pipeline(+response = await runner.execute(pipe_code="my_pipe",inputs={...},)diff --git a/docs/errors/execution-and-runtime.md b/docs/errors/execution-and-runtime.mdindex 2b181ca49..d8a3e24db 100644--- a/docs/errors/execution-and-runtime.md+++ b/docs/errors/execution-and-runtime.md@@ -30,6 +30,7 @@ own page. Classes are grouped by subsystem.- [`PipeExecutionError`](pipe-execution-error.md) — Pipe execution- [`PipeStackOverflowError`](pipe-stack-overflow-error.md) — Pipe stack overflow- [`PipelineExecutionError`](pipeline-execution-error.md) — Pipeline execution+- [`PipelineInputContentError`](pipeline-input-content-error.md) — Pipeline input content- [`PipelineManagerAlreadyExistsError`](pipeline-manager-already-exists-error.md) — Pipeline manager already exists- [`PipelineManagerNotFoundError`](pipeline-manager-not-found-error.md) — Pipeline manager not found- [`ValidateBundleError`](validate-bundle-error.md) — Validate bundlediff --git a/docs/errors/pipeline-input-content-error.md b/docs/errors/pipeline-input-content-error.mdnew file mode 100644index 000000000..4402145cd--- /dev/null+++ b/docs/errors/pipeline-input-content-error.md@@ -0,0 +1,22 @@+---+title: "Pipeline input content"+description: "Reference for the `PipelineInputContentError` Pipelex error class."+---++<!-- pipelex:generated -->++# Pipeline input content++A pipeline input's content reference (url) is unusable.++| Field | Value |+|---|---|+| `error_type` | `PipelineInputContentError` |+| `title` | Pipeline input content |+| `type_uri` | `https://docs.pipelex.com/latest/errors/pipeline-input-content-error/` |+| `error_domain` | `input` |+| Defined in | `pipelex.pipeline.exceptions` |+| Parent class | [`PipelexError`](pipelex-error.md) |+| `user_action` | `change_input` — Provide a valid url on every Image/Document input (https://, data:, pipelex-storage://, or an existing local file when running locally). |++[Back to Error Reference](index.md)diff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.mdindex 7dca3b5fb..cab402d02 100644--- a/docs/under-the-hood/error-model.md+++ b/docs/under-the-hood/error-model.md@@ -34,7 +34,7 @@ An error rises through a series of layers. Each layer has exactly one job.|-------|------|--------------------------|| **5 — CLI entry points** | `pipelex` / `pipelex-agent` commands | Catch, format for human (Rich) / agent (JSON·MD) / HTTP || **4 — CLI factories** | `cli_factory.py`, `agent_cli_factory.py` | Catch setup errors, route to handlers |-| **3 — Pipeline runner** | `PipelexRunner.execute_pipeline()` | Catch + wrap as `PipelineExecutionError` |+| **3 — Pipeline runner** | `PipelexMTHDSProtocol.execute()` | Catch + wrap as `PipelineExecutionError` || **2 — Pipe router / operators** | `PipeRouter`, pipe operators | Catch + wrap with pipe context (`pipe_code`, `pipe_stack`) || **1 — Workers / SDK calls** | `pipelex/plugins/*/` | **Catch the SDK exception → classify → raise `CogtError`** || **0 — Third-party SDKs** | OpenAI, Anthropic, Google, … | Raise raw, untyped provider exceptions |diff --git a/docs/under-the-hood/execution-graph-tracing.md b/docs/under-the-hood/execution-graph-tracing.mdindex 9f849a260..e277c8095 100644--- a/docs/under-the-hood/execution-graph-tracing.md+++ b/docs/under-the-hood/execution-graph-tracing.md@@ -30,10 +30,10 @@ Pipe Execution → GraphTracer → GraphSpec → Renderers → HTML/Mermaid| Scenario | CLI | API | Result ||----------|-----|-----|--------|-| Generate execution graph | `pipelex run pipe my_pipe --graph` | `PipelexRunner(execution_config=...).execute_pipeline(...)` | GraphSpec JSON + HTML viewers |+| Generate execution graph | `pipelex run pipe my_pipe --graph` | `PipelexMTHDSProtocol(execution_config=...).execute(...)` | GraphSpec JSON + HTML viewers || Force include full data | `--graph --graph-full-data` | `data_inclusion.stuff_json_content=True` | Data embedded in IOSpec || Force exclude data | `--graph --graph-no-data` | All `data_inclusion.*=False` | Previews only |-| Dry run with graph | `--dry-run --graph` | `PipelexRunner(pipe_run_mode=PipeRunMode.DRY, execution_config=...)` | Graph of mock execution |+| Dry run with graph | `--dry-run --graph` | `PipelexMTHDSProtocol(pipe_run_mode=PipeRunMode.DRY, execution_config=...)` | Graph of mock execution |!!! info "Full Data Included by Default"The default configuration includes full data in graphs (`stuff_json_content`, `stuff_text_content`, `stuff_html_content`, and `error_stack_traces` are all `true`). Use `--graph-full-data` or `--graph-no-data` only to override project-specific settings.@@ -61,24 +61,24 @@ pipelex run pipe my_pipe --dry-run --graph --mock-inputs### API```python-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode# Execute with graph tracing via config-runner = PipelexRunner(+runner = PipelexMTHDSProtocol(execution_config=config.with_execution_overrides(generate_graph=True),)-response = await runner.execute_pipeline(+response = await runner.execute(pipe_code="my_pipe",)pipe_output = response.pipe_output# Dry run with graph: the same runner in DRY mode with mock inputs — no separate code path.-dry_runner = PipelexRunner(+dry_runner = PipelexMTHDSProtocol(pipe_run_mode=PipeRunMode.DRY,execution_config=config.with_execution_overrides(generate_graph=True, mock_inputs=True),)-response = await dry_runner.execute_pipeline(pipe_code="my_pipe")+response = await dry_runner.execute(pipe_code="my_pipe")graph_spec = response.pipe_output.graph_spec```diff --git a/pipelex/builder/runner_code.py b/pipelex/builder/runner_code.pyindex 54c03f21f..4309fbc30 100644--- a/pipelex/builder/runner_code.py+++ b/pipelex/builder/runner_code.py@@ -232,7 +232,7 @@ def generate_runner_code(pipe: PipeAbstract, output_multiplicity: bool = False,["","from pipelex.pipelex import Pipelex",- "from pipelex.pipeline.runner import PipelexRunner",+ "from pipelex.pipeline.runner import PipelexMTHDSProtocol",])@@ -268,8 +268,8 @@ def generate_runner_code(pipe: PipeAbstract, output_multiplicity: bool = False,"","",f"async def run_{pipe.code}() -> {return_type}:",- " runner = PipelexRunner()",- " response = await runner.execute_pipeline(",+ " runner = PipelexMTHDSProtocol()",+ " response = await runner.execute(",f' pipe_code="{pipe.code}",',]diff --git a/pipelex/cli/agent_cli/commands/agent_cli_factory.py b/pipelex/cli/agent_cli/commands/agent_cli_factory.pyindex a21855101..632f836d6 100644--- a/pipelex/cli/agent_cli/commands/agent_cli_factory.py+++ b/pipelex/cli/agent_cli/commands/agent_cli_factory.py@@ -69,7 +69,7 @@ from pipelex.tools.misc.pretty import PrettyPrinter, PrettyPrintMode# Why silence everything? The agent CLI is machine-consumed. Its contract is:# stdout = structured success envelope (JSON or markdown), stderr = structured error# envelope. ANY log line on stderr — DEBUG, INFO, WARNING, anything — corrupts the-# error-envelope channel for downstream parsers (e.g. mthds-js's ``PipelexRunner``+# error-envelope channel for downstream parsers (e.g. mthds-js's ``PipelexMTHDSProtocol``# doing ``JSON.parse(stderr)``). This is not a verbosity setting; it's the design.# There is no ``--log-level`` escape hatch on ``pipelex-agent``: when debugging is# needed, use the human ``pipelex`` CLI instead.diff --git a/pipelex/cli/agent_cli/commands/run/_run_core.py b/pipelex/cli/agent_cli/commands/run/_run_core.pyindex 3f629bfc4..8124a434d 100644--- a/pipelex/cli/agent_cli/commands/run/_run_core.py+++ b/pipelex/cli/agent_cli/commands/run/_run_core.py@@ -14,7 +14,7 @@ from pipelex.cogt.usage.cost_registry import CostRegistryfrom pipelex.config import get_configfrom pipelex.graph.graph_factory import generate_graph_outputs, save_graph_outputs_to_dirfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.tools.misc.json_utils import clean_json_dumps@@ -59,13 +59,13 @@ async def run_pipeline_core(mock_inputs=mock_inputs or None,)- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(bundle_uris=bundle_uris,pipe_run_mode=pipe_run_mode,execution_config=execution_config,library_dirs=library_dirs,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code=pipe_code,mthds_contents=mthds_contents,inputs=inputs,diff --git a/pipelex/cli/agent_cli/commands/run/_run_core_api.py b/pipelex/cli/agent_cli/commands/run/_run_core_api.pyindex 6ed931c56..041b7f18a 100644--- a/pipelex/cli/agent_cli/commands/run/_run_core_api.py+++ b/pipelex/cli/agent_cli/commands/run/_run_core_api.py@@ -8,8 +8,8 @@ from __future__ import annotationsfrom typing import Any, cast-from mthds.client.pipeline import MAIN_STUFF_NAME-from mthds.runners.api_runner import ApiRunner+from mthds.runners.api.client import MthdsAPIClient+from mthds.runners.api.models import MAIN_STUFF_NAMEfrom pipelex.cli.agent_cli.commands.run._output_helpers import build_run_output@@ -36,17 +36,24 @@ async def run_pipeline_core_api(ClientAuthenticationError: If API credentials are invalid or missing.PipelineRequestError: If the pipeline request is malformed."""- runner = ApiRunner()- response = await runner.execute_pipeline(- pipe_code=pipe_code,- mthds_contents=mthds_contents,- inputs=inputs,- )+ async with MthdsAPIClient() as runner:+ response = await runner.execute(+ pipe_code=pipe_code,+ mthds_contents=mthds_contents,+ inputs=inputs,+ )++ pipe_output = response.pipe_output++ # `main_stuff_name` and `state` are pipelex extension fields on the protocol's+ # extension-open RunResult — they ride model_extra, never named by the SDK.+ extensions: dict[str, Any] = response.model_extra or {}# Extract main stuff content from the working memorymain_stuff_json: dict[str, Any] = {}- main_stuff_name = response.main_stuff_name or MAIN_STUFF_NAME- main_stuff = response.pipe_output.working_memory.root.get(main_stuff_name)+ raw_main_stuff_name = extensions.get("main_stuff_name")+ main_stuff_name = raw_main_stuff_name if isinstance(raw_main_stuff_name, str) else MAIN_STUFF_NAME+ main_stuff = pipe_output.working_memory.root.get(main_stuff_name)if main_stuff is not None:main_stuff_json = {"json": main_stuff.content,@@ -62,10 +69,10 @@ async def run_pipeline_core_api(return build_run_output(with_memory=with_memory,main_stuff_json=main_stuff_json,- working_memory_dump=response.pipe_output.working_memory.model_dump(),+ working_memory_dump=pipe_output.working_memory.model_dump(),compact_result=compact_result,extra_metadata={"pipeline_run_id": response.pipeline_run_id,- "pipeline_state": response.pipeline_state,+ "pipeline_state": extensions.get("state"),},)diff --git a/pipelex/cli/agent_cli/commands/run/bundle_cmd.py b/pipelex/cli/agent_cli/commands/run/bundle_cmd.pyindex c4ccabb7e..efd71117f 100644--- a/pipelex/cli/agent_cli/commands/run/bundle_cmd.py+++ b/pipelex/cli/agent_cli/commands/run/bundle_cmd.py@@ -167,7 +167,8 @@ def run_bundle_cmd(if mock_inputs:agent_error("--mock-inputs is not supported with --runner api", "ArgumentError")- from mthds.client.exceptions import ClientAuthenticationError, PipelineRequestError # noqa: PLC0415+ from mthds.protocol.exceptions import PipelineRequestError # noqa: PLC0415+ from mthds.runners.api.exceptions import ClientAuthenticationError # noqa: PLC0415try:result = asyncio.run(diff --git a/pipelex/cli/agent_cli/commands/run/method_cmd.py b/pipelex/cli/agent_cli/commands/run/method_cmd.pyindex 4d664a2ef..dbc9e7fcb 100644--- a/pipelex/cli/agent_cli/commands/run/method_cmd.py+++ b/pipelex/cli/agent_cli/commands/run/method_cmd.py@@ -124,7 +124,8 @@ def run_method_cmd(if mock_inputs:agent_error("--mock-inputs is not supported with --runner api", "ArgumentError")- from mthds.client.exceptions import ClientAuthenticationError, PipelineRequestError # noqa: PLC0415+ from mthds.protocol.exceptions import PipelineRequestError # noqa: PLC0415+ from mthds.runners.api.exceptions import ClientAuthenticationError # noqa: PLC0415try:result = asyncio.run(diff --git a/pipelex/cli/agent_cli/commands/run/pipe_cmd.py b/pipelex/cli/agent_cli/commands/run/pipe_cmd.pyindex 80b56720c..b4e0d6e2e 100644--- a/pipelex/cli/agent_cli/commands/run/pipe_cmd.py+++ b/pipelex/cli/agent_cli/commands/run/pipe_cmd.py@@ -122,7 +122,8 @@ def run_pipe_cmd(if mock_inputs:agent_error("--mock-inputs is not supported with --runner api", "ArgumentError")- from mthds.client.exceptions import ClientAuthenticationError, PipelineRequestError # noqa: PLC0415+ from mthds.protocol.exceptions import PipelineRequestError # noqa: PLC0415+ from mthds.runners.api.exceptions import ClientAuthenticationError # noqa: PLC0415try:result = asyncio.run(diff --git a/pipelex/cli/commands/run/_run_core.py b/pipelex/cli/commands/run/_run_core.pyindex af6fe1af5..6791a6b44 100644--- a/pipelex/cli/commands/run/_run_core.py+++ b/pipelex/cli/commands/run/_run_core.py@@ -31,7 +31,7 @@ from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityErrorfrom pipelex.pipe_run.pipe_run_mode import PipeRunModefrom pipelex.pipelex import Pipelexfrom pipelex.pipeline.exceptions import PipelineExecutionError-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.reporting.cost_report_renderer import render_cost_report_for_outputfrom pipelex.system.runtime import IntegrationModefrom pipelex.system.telemetry.events import EventProperty@@ -113,7 +113,7 @@ async def _execute_run(try:mthds_content = Path(bundle_path).read_text(encoding="utf-8")# Use lightweight parsing to extract main_pipe without full validation- # Full validation happens later during execute_pipeline+ # Full validation happens later during executeif not pipe_code:bundle_blueprint = PipelexInterpreter.make_pipelex_bundle_blueprint(mthds_content=mthds_content)main_pipe_code = bundle_blueprint.main_pipe@@ -175,14 +175,14 @@ async def _execute_run()try:- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(bundle_uris=[bundle_path] if bundle_path else None,pipe_run_mode=pipe_run_mode,is_mock_usage=mock_usage,execution_config=execution_config,library_dirs=library_dir,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code=pipe_code,mthds_contents=[mthds_content] if mthds_content else None,inputs=pipeline_inputs,diff --git a/pipelex/core/concepts/concept.py b/pipelex/core/concepts/concept.pyindex 19ff104fe..c91b9f031 100644--- a/pipelex/core/concepts/concept.py+++ b/pipelex/core/concepts/concept.py@@ -1,7 +1,7 @@from typing import Any, Callablefrom kajson.class_registry_abstract import ClassRegistryAbstract-from mthds.models.concept import ConceptAbstract+from mthds.protocol.concept import ConceptAbstractfrom pydantic import field_validatorfrom pipelex import logdiff --git a/pipelex/core/memory/working_memory.py b/pipelex/core/memory/working_memory.pyindex eceb3b819..2a8fedb60 100644--- a/pipelex/core/memory/working_memory.py+++ b/pipelex/core/memory/working_memory.py@@ -1,7 +1,7 @@from operator import attrgetterfrom typing import Any, cast-from mthds.models.working_memory import WorkingMemoryAbstract+from mthds.protocol.working_memory import WorkingMemoryAbstractfrom pydantic import Field, model_validatorfrom typing_extensions import overridediff --git a/pipelex/core/memory/working_memory_factory.py b/pipelex/core/memory/working_memory_factory.pyindex cbccf09f8..0df4978b6 100644--- a/pipelex/core/memory/working_memory_factory.py+++ b/pipelex/core/memory/working_memory_factory.py@@ -1,5 +1,5 @@import shortuuid-from mthds.models.pipeline_inputs import PipelineInputs+from mthds.protocol.pipeline_inputs import PipelineInputsfrom polyfactory.exceptions import FactoryExceptionfrom pydantic import BaseModel, ValidationErrordiff --git a/pipelex/core/pipes/pipe_output.py b/pipelex/core/pipes/pipe_output.pyindex a68248f51..5c329617f 100644--- a/pipelex/core/pipes/pipe_output.py+++ b/pipelex/core/pipes/pipe_output.py@@ -1,6 +1,6 @@from typing import Any, TypeVar-from mthds.models.pipe_output import PipeOutputAbstract+from mthds.protocol.pipe_output import PipeOutputAbstractfrom pydantic import Fieldfrom pipelex.core.memory.working_memory import WorkingMemorydiff --git a/pipelex/core/stuffs/stuff.py b/pipelex/core/stuffs/stuff.pyindex 5856fbad6..7691c17ae 100644--- a/pipelex/core/stuffs/stuff.py+++ b/pipelex/core/stuffs/stuff.py@@ -2,7 +2,8 @@from typing import Any, cast, get_args, get_originfrom kajson import kajson-from mthds.models.stuff import DictStuffAbstract, StuffAbstract+from mthds.protocol.stuff import StuffAbstract+from mthds.runners.api.models import DictStuffAbstractfrom pydantic import ValidationErrorfrom typing_extensions import overridediff --git a/pipelex/core/stuffs/stuff_content.py b/pipelex/core/stuffs/stuff_content.pyindex 56b670f07..7640fe0dd 100644--- a/pipelex/core/stuffs/stuff_content.py+++ b/pipelex/core/stuffs/stuff_content.py@@ -1,7 +1,7 @@from typing import Any, TypeVar, finalfrom kajson import kajson-from mthds.models.stuff import StuffContentAbstract+from mthds.protocol.stuff import StuffContentAbstractfrom rich.json import JSONfrom typing_extensions import overridediff --git a/pipelex/core/stuffs/stuff_factory.py b/pipelex/core/stuffs/stuff_factory.pyindex 61802d82c..bd5b19fdf 100644--- a/pipelex/core/stuffs/stuff_factory.py+++ b/pipelex/core/stuffs/stuff_factory.py@@ -3,7 +3,7 @@ from typing import Any, castfrom urllib.parse import urlsplit, urlunsplitimport shortuuid-from mthds.models.pipeline_inputs import StuffContentOrData+from mthds.protocol.pipeline_inputs import StuffContentOrDatafrom pydantic import BaseModel, ValidationError, field_validatorfrom pipelex.core.concepts.concept import Conceptdiff --git a/pipelex/graph/graph_rendering.py b/pipelex/graph/graph_rendering.pyindex c971aabfe..e796a4bb1 100644--- a/pipelex/graph/graph_rendering.py+++ b/pipelex/graph/graph_rendering.py@@ -119,7 +119,7 @@ async def _dry_run_bundle(mthds_content = bundle_path.read_text(encoding="utf-8")# Ensure the bundle's parent directory is included in library_dirs- # so PipelexRunner can resolve sibling dependencies+ # so PipelexMTHDSProtocol can resolve sibling dependenciesbundle_parent_dir = str(bundle_path.parent.resolve())effective_library_dirs: list[str]if library_dirs:diff --git a/pipelex/pipe_run/delivery_assignment.py b/pipelex/pipe_run/delivery_assignment.pyindex 44ebfd1b2..ce41b1f00 100644--- a/pipelex/pipe_run/delivery_assignment.py+++ b/pipelex/pipe_run/delivery_assignment.py@@ -17,7 +17,7 @@ class DeliveryStatus(StrEnum):# (see ``DeliveryExecutor._notify_webhook``). A caller's static ``payload``# must not declare any of them — otherwise the value would shift silently# with delivery status. Enforced at construction by ``_reject_reserved_keys``.-_RESERVED_WEBHOOK_PAYLOAD_KEYS: frozenset[str] = frozenset({"pipeline_run_id", "status", "result_url", "error"})+_RESERVED_WEBHOOK_PAYLOAD_KEYS: frozenset[str] = frozenset({"state", "pipeline_run_id", "status", "result_url", "error"})class WebhookTarget(BaseModel):@@ -33,7 +33,8 @@ class WebhookTarget(BaseModel):"""Reject caller payload keys that Pipelex assigns per delivery.``DeliveryExecutor._notify_webhook`` writes ``pipeline_run_id`` /- ``status`` / ``result_url`` / ``error`` onto the outgoing body. A static+ ``state`` (protocol spellings) plus the transitional ``status`` alias,+ ``result_url`` and ``error`` onto the outgoing body. A staticpayload that declares any of them would have its meaning shift withdelivery status — fail loudly at construction instead of silently atdelivery time.diff --git a/pipelex/pipe_run/delivery_executor.py b/pipelex/pipe_run/delivery_executor.pyindex b8f5a7673..f5e6f3112 100644--- a/pipelex/pipe_run/delivery_executor.py+++ b/pipelex/pipe_run/delivery_executor.py@@ -270,7 +270,13 @@ class DeliveryExecutor:"""try:payload: dict[str, Any] = dict(webhook.payload)+ # Wire fields follow the MTHDS Protocol: `pipeline_run_id` (unchanged)+ # + `state` (master D1 as revised). The legacy `status` spelling rides+ # along for one release so receivers can migrate without a+ # deploy-window gap (the hosted run-completion Lambda accepts both+ # during the Phase C skew).payload["pipeline_run_id"] = pipeline_run_id+ payload["state"] = statuspayload["status"] = statusif result_url is not None:payload["result_url"] = result_urldiff --git a/pipelex/pipe_run/dry_run_pipeline.py b/pipelex/pipe_run/dry_run_pipeline.pyindex f6e7e5b70..b58623e49 100644--- a/pipelex/pipe_run/dry_run_pipeline.py+++ b/pipelex/pipe_run/dry_run_pipeline.py@@ -20,7 +20,7 @@ from pipelex.pipe_run.pipe_run import PipeRunfrom pipelex.pipe_run.pipe_run_mode import PipeRunModefrom pipelex.pipeline.execution_seams import prepare_pipe_jobfrom pipelex.pipeline.pipeline_factory import PipelineFactory-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.system.telemetry.otel_constants import OTelConstantsfrom pipelex.tracing.in_memory_event_log import InMemoryEventLog@@ -78,7 +78,7 @@ async def dry_run_pipeline(mock_inputs=True,)- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(bundle_uris=bundle_uris,pipe_run_mode=PipeRunMode.DRY,execution_config=execution_config,@@ -90,7 +90,7 @@ async def dry_run_pipeline(# disabled (e.g. pipelex-api's /validate in direct mode) still gets its graph, and a host# with a configured backend doesn't get trace files written as a side effect of validation.with scoped_event_log(InMemoryEventLog()):- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code=pipe_code,mthds_contents=mthds_contents,)diff --git a/pipelex/pipelex.py b/pipelex/pipelex.pyindex e38360e18..d5fe41f6b 100644--- a/pipelex/pipelex.py+++ b/pipelex/pipelex.py@@ -564,7 +564,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.observers: Custom observers for pipeline eventslibrary_dirs: Default library directories for pipeline execution. If provided, thesedirectories will be used instead of the PIPELEXPATH environment variable.- Per-call library_dirs in execute_pipeline/start_pipeline will override this default.+ Per-call library_dirs in execute/start will override this default.config_overrides: Optional dict deep-merged on top of all TOML config layersas the highest-priority override. Useful for tests that need specificconfig without editing TOML files.diff --git a/pipelex/pipeline/bundle_validator.py b/pipelex/pipeline/bundle_validator.pyindex 91160f6e7..137dc10d6 100644--- a/pipelex/pipeline/bundle_validator.py+++ b/pipelex/pipeline/bundle_validator.py@@ -6,7 +6,7 @@ A validation sweep is **not** a run: it is a batch *policy* that *uses* runs. So``SUCCESS / FAILURE / SKIPPED`` aggregation, ``allowed_to_fail`` policy) and**composes** the shared execution seams (``acquire_library`` /``prepare_pipe_job``) plus a direct, in-process ``PipeRun`` — the same execution-core ``PipelexRunner`` reaches for a single run. It never forks the runner and+core ``PipelexMTHDSProtocol`` reaches for a single run. It never forks the runner andnever threads validation-only flags through it.Two lifecycles (D6):diff --git a/pipelex/pipeline/exceptions.py b/pipelex/pipeline/exceptions.pyindex b1c50a44c..cbea02dac 100644--- a/pipelex/pipeline/exceptions.py+++ b/pipelex/pipeline/exceptions.py@@ -125,3 +125,22 @@ class ValidateBundleError(PipelexError):"""# TODO: refactor so we don't need this anymore?return self.pipe_validation_errors + self.pipe_concept_instantiation_errors+++class PipelineInputContentError(PipelexError):+ """A pipeline input's content reference (url) is unusable.++ Raised by the input normalizer when an Image/Document input carries a+ blank url, or a local path that cannot be read. The caller supplied the+ value — INPUT domain, so API servers answer 422, never a sanitized 500+ (a blank url used to surface as IsADirectoryError('.') → 500).+ """++ error_domain = ErrorDomain.INPUT+ user_action = UserAction(+ kind=UserActionKind.CHANGE_INPUT,+ detail=(+ "Provide a valid url on every Image/Document input (https://, data:, pipelex-storage://, or an existing local file when running locally)."+ ),+ )+ caller_facing_message = Truediff --git a/pipelex/pipeline/execution_seams.py b/pipelex/pipeline/execution_seams.pyindex 724ad3a62..190d3ef1f 100644--- a/pipelex/pipeline/execution_seams.py+++ b/pipelex/pipeline/execution_seams.py@@ -22,7 +22,7 @@ from collections.abc import Sequencefrom pathlib import Pathfrom typing import TYPE_CHECKING-from mthds.models.pipeline_inputs import PipelineInputs+from mthds.protocol.pipeline_inputs import PipelineInputsfrom pipelex import logfrom pipelex.core.interpreter.interpreter import PipelexInterpreterdiff --git a/pipelex/pipeline/input_normalizer.py b/pipelex/pipeline/input_normalizer.pyindex cd10e0cf6..48ef3fa68 100644--- a/pipelex/pipeline/input_normalizer.py+++ b/pipelex/pipeline/input_normalizer.py@@ -11,7 +11,6 @@ from typing import Any, castimport shortuuid-from pipelex.base_exceptions import PipelexErrorfrom pipelex.config import get_configfrom pipelex.core.memory.working_memory import WorkingMemoryfrom pipelex.core.stuffs.document_content import DocumentContent@@ -19,6 +18,7 @@ from pipelex.core.stuffs.image_content import ImageContentfrom pipelex.core.stuffs.list_content import ListContentfrom pipelex.core.stuffs.structured_content import StructuredContentfrom pipelex.hub import get_storage_provider+from pipelex.pipeline.exceptions import PipelineInputContentErrorfrom pipelex.tools.misc.file_utils import load_binary_asyncfrom pipelex.tools.misc.filetype_utils import detect_file_type_from_bytesfrom pipelex.tools.storage.storage_provider_abstract import StorageProviderAbstract@@ -194,6 +194,10 @@ async def _normalize_url_content(The original content if no normalization needed, or a new instancewith the normalized URL."""+ if not content.url.strip():+ msg = f"{type(content).__name__} input has a blank url — provide https://, data:, pipelex-storage://, or a local file path."+ raise PipelineInputContentError(msg)+resolved_uri = resolve_uri(content.url)if isinstance(resolved_uri, ResolvedBase64DataUrl):@@ -217,12 +221,15 @@ async def _normalize_url_content(if not get_config().pipelex.storage_config.is_upload_local_content_enabled:return content- # Read local file, detect type, upload to storage+ # Read local file, detect type, upload to storage. OSError covers+ # the whole caller-controllable failure surface (FileNotFoundError,+ # IsADirectoryError, PermissionError, name-too-long, ...) — all of+ # them mean the supplied path is unusable, an INPUT fault.try:raw_bytes = await load_binary_async(Path(resolved_uri.path))- except FileNotFoundError as exc:- msg = f"Input file not found: '{resolved_uri.path}'"- raise PipelexError(msg) from exc+ except OSError as exc:+ msg = f"Input file cannot be read: '{resolved_uri.path}' ({type(exc).__name__})"+ raise PipelineInputContentError(msg) from excfile_type = detect_file_type_from_bytes(raw_bytes)key = f"normalized/{shortuuid.uuid()}.{file_type.extension}"storage_uri = await storage.store(data=raw_bytes, key=key, content_type=file_type.mime)diff --git a/pipelex/pipeline/pipeline_response.py b/pipelex/pipeline/pipeline_response.pyindex ca7311c45..e6bb3d2b3 100644--- a/pipelex/pipeline/pipeline_response.py+++ b/pipelex/pipeline/pipeline_response.py@@ -1,29 +1,64 @@from __future__ import annotations-from mthds.client.pipeline import MAIN_STUFF_NAME, PipelineExecuteResponse, PipelineStartResponse, PipelineState+from mthds.protocol.models import RunResultExecute, RunResultStart+from pipelex.core.memory.working_memory import MAIN_STUFF_NAMEfrom pipelex.core.pipes.pipe_output import PipeOutput+from pipelex.types import StrEnum-class PipelexPipelineExecuteResponse(PipelineExecuteResponse[PipeOutput]):+class RunState(StrEnum):+ """Run lifecycle state — a pipelex extension field on run responses (the protocol defines none)."""++ STARTED = "STARTED"+ RUNNING = "RUNNING"+ COMPLETED = "COMPLETED"+ FAILED = "FAILED"+ CANCELLED = "CANCELLED"+ ERROR = "ERROR"+++class PipelexRunResultExecute(RunResultExecute[PipeOutput]):+ """Pipelex's `/execute` response — the completed run.++ The protocol's `RunResultExecute` carries `pipeline_run_id` + `pipe_output`+ (both always present); `state`, `created_at`, `finished_at`, and+ `main_stuff_name` are pipelex extension fields, documented by this+ implementation's own API schema.+ """++ created_at: str+ state: RunState+ finished_at: str | None = None+ main_stuff_name: str | None = None+@classmethoddef from_pipe_output(cls,pipe_output: PipeOutput,pipeline_run_id: str = "",created_at: str = "",- pipeline_state: PipelineState = PipelineState.COMPLETED,+ state: RunState = RunState.COMPLETED,finished_at: str | None = None,- ) -> PipelexPipelineExecuteResponse:+ ) -> PipelexRunResultExecute:return cls(pipeline_run_id=pipeline_run_id,created_at=created_at,- pipeline_state=pipeline_state,+ state=state,finished_at=finished_at,pipe_output=pipe_output,main_stuff_name=pipe_output.working_memory.aliases.get(MAIN_STUFF_NAME, MAIN_STUFF_NAME),)-class PipelexPipelineStartResponse(PipelineStartResponse[PipeOutput]):+class PipelexRunResultStart(RunResultStart):+ """Pipelex's `/start` response — just the authoritative `pipeline_run_id`.++ The protocol's `RunResultStart` carries `pipeline_run_id` only; `state`,+ `created_at`, `finished_at`, and `workflow_id` are pipelex extension fields.+ """++ created_at: str+ state: RunState+ finished_at: str | None = Noneworkflow_id: str | None = Nonediff --git a/pipelex/pipeline/pipeline_run_setup.py b/pipelex/pipeline/pipeline_run_setup.pyindex ebf2d9c5e..4942d408c 100644--- a/pipelex/pipeline/pipeline_run_setup.py+++ b/pipelex/pipeline/pipeline_run_setup.py@@ -1,6 +1,6 @@from typing import TYPE_CHECKING-from mthds.models.pipeline_inputs import PipelineInputs+from mthds.protocol.pipeline_inputs import PipelineInputsfrom pipelex import logfrom pipelex.config import get_config@@ -60,8 +60,8 @@ async def pipeline_run_setup() -> tuple[PipeJob, str, str]:"""Set up a pipeline for execution.- This function handles all the common setup logic for both ``execute_pipeline``- and ``start_pipeline``, including library setup, pipe loading, working memory+ This function handles all the common setup logic for both ``execute``+ and ``start``, including library setup, pipe loading, working memoryinitialization, and pipe job creation.Parametersdiff --git a/pipelex/pipeline/runner.py b/pipelex/pipeline/runner.pyindex 2176f3775..093b5441e 100644--- a/pipelex/pipeline/runner.py+++ b/pipelex/pipeline/runner.py@@ -1,14 +1,21 @@from __future__ import annotationsfrom datetime import datetime, timezone+from importlib import metadata+from pathlib import Pathfrom typing import TYPE_CHECKING, Any, cast-from mthds.client.pipeline import PipelineState-from mthds.client.protocol import RunnerProtocol-from pydantic import ValidationError+from mthds.protocol.exceptions import PipelineRequestError+from mthds.protocol.models import ModelCategory as MthdsModelCategory+from mthds.protocol.models import ModelDeck as MthdsModelDeck+from mthds.protocol.models import ModelInfo as MthdsModelInfo+from mthds.protocol.models import ValidationReport, VersionInfo+from mthds.protocol.protocol import MTHDSProtocol+from pydantic import Field, ValidationErrorfrom typing_extensions import overridefrom pipelex.base_exceptions import PipelexError+from pipelex.builder.operations.models_ops import ModelCategory, list_modelsfrom pipelex.config import get_configfrom pipelex.graph.graph_tracer_manager import GraphTracerManagerfrom pipelex.hub import (@@ -23,18 +30,18 @@ from pipelex.hub import ()from pipelex.pipe_run.exceptions import PipeRouterErrorfrom pipelex.pipeline.exceptions import PipeExecutionError, PipelineExecutionError-from pipelex.pipeline.pipeline_response import PipelexPipelineExecuteResponse+from pipelex.pipeline.pipeline_response import PipelexRunResultExecute, PipelexRunResultStart, RunStatefrom pipelex.pipeline.pipeline_run_setup import pipeline_run_setup+from pipelex.pipeline.validate_bundle import validate_bundlefrom pipelex.system.telemetry.events import EventName, EventProperty, Outcomefrom pipelex.tools.typing.pydantic_utils import format_pydantic_validation_errorif TYPE_CHECKING:import asyncio- from mthds.client.pipeline import PipelineStartResponse- from mthds.models.pipe_output import VariableMultiplicity- from mthds.models.pipeline_inputs import PipelineInputs- from mthds.models.working_memory import WorkingMemoryAbstract+ from mthds.protocol.pipe_output import VariableMultiplicity+ from mthds.protocol.pipeline_inputs import PipelineInputs+ from mthds.protocol.working_memory import WorkingMemoryAbstractfrom pipelex.core.memory.working_memory import WorkingMemoryfrom pipelex.core.pipes.pipe_output import PipeOutput@@ -44,9 +51,41 @@ if TYPE_CHECKING:from pipelex.pipe_run.pipe_run_protocol import PipeRunProtocolfrom pipelex.system.configuration.configs import PipelineExecutionConfig+# The MTHDS Protocol version this runtime implements (mthds-protocol.openapi.yaml).+MTHDS_PROTOCOL_VERSION = "0.1.0"-class PipelexRunner(RunnerProtocol["PipeOutput"]):- """Pipelex implementation of the mthds RunnerProtocol.++class PipelexValidationReport(ValidationReport):+ """Pipelex's validation artifacts — this implementation's extensions on the+ protocol's `ValidationReport` (which declares no body fields).+ """++ blueprint: Any = None+ graph_spec: Any = None+ pipe_structures: Any = None+++class PipelexModelDeck(MthdsModelDeck):+ """Pipelex's model deck — the protocol base plus this implementation's+ routing metadata (aliases, waterfalls).+ """++ aliases: dict[str, str] = Field(default_factory=dict)+ waterfalls: dict[str, list[str]] = Field(default_factory=dict)+++class PipelexVersionInfo(VersionInfo):+ """Pipelex's version handshake — the protocol base plus this+ implementation's identification.+ """++ implementation: str+ implementation_version: str+ runtime_version: str | None = None+++class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):+ """Pipelex implementation of the mthds MTHDSProtocol.Adapts pipelex pipeline execution to the mthds protocol interface.Pipelex-specific configuration (library directories, run mode, etc.)@@ -78,7 +117,7 @@ class PipelexRunner(RunnerProtocol["PipeOutput"]):self._running_tasks: dict[str, asyncio.Task[PipeOutput]] = {}@override- async def execute_pipeline(+ async def execute(self,pipe_code: str | None = None,mthds_contents: list[str] | None = None,@@ -86,15 +125,16 @@ class PipelexRunner(RunnerProtocol["PipeOutput"]):output_name: str | None = None,output_multiplicity: VariableMultiplicity | None = None,dynamic_output_concept_ref: str | None = None,+ extra: dict[str, Any] | None = None,delivery_assignment: DeliveryAssignment | None = None,- ) -> PipelexPipelineExecuteResponse:+ ) -> PipelexRunResultExecute:"""Execute a pipeline and wait for its completion.- This method executes a pipe and returns its output. Unlike ``start_pipeline``,+ This method executes a pipe and returns its output. Unlike ``start``,this method waits for the pipe execution to complete before returning.Pipelex-specific configuration (library directories, run mode, etc.) is provided- at construction time via the ``PipelexRunner`` constructor.+ at construction time via the ``PipelexMTHDSProtocol`` constructor.Parameters----------@@ -116,16 +156,26 @@ class PipelexRunner(RunnerProtocol["PipeOutput"]):Output multiplicity specification.dynamic_output_concept_ref:Override the dynamic output concept ref.+ extra:+ Rejected — the local runtime defines no extension args. Extension+ args are server-specific; pass them to the server that defines them.+ delivery_assignment:+ Internal delivery hook used by the API layer (in-process, not a+ wire extension).Returns:-------- PipelexPipelineExecuteResponse+ PipelexRunResultExecuteThe pipeline execution response wrapping the pipe output, includingpipeline run ID, timestamps, and pipeline state. If ``generate_graph``was True, the execution graph is available in the pipe output's``graph_spec``."""+ if extra:+ msg = f"The local runtime defines no extension args; got {sorted(extra)}."+ raise PipelineRequestError(msg)+created_at = datetime.now(timezone.utc).isoformat()# Use provided config or get default@@ -251,16 +301,16 @@ class PipelexRunner(RunnerProtocol["PipeOutput"]):get_telemetry_manager().track_event(event_name=EventName.PIPELINE_COMPLETE, properties=properties)finished_at = datetime.now(timezone.utc).isoformat()- return PipelexPipelineExecuteResponse.from_pipe_output(+ return PipelexRunResultExecute.from_pipe_output(pipe_output=pipe_output,pipeline_run_id=pipe_output.pipeline_run_id,created_at=created_at,- pipeline_state=PipelineState.COMPLETED,+ state=RunState.COMPLETED,finished_at=finished_at,)@override- async def start_pipeline(+ async def start(self,pipe_code: str | None = None,mthds_contents: list[str] | None = None,@@ -268,5 +318,128 @@ class PipelexRunner(RunnerProtocol["PipeOutput"]):output_name: str | None = None,output_multiplicity: VariableMultiplicity | None = None,dynamic_output_concept_ref: str | None = None,- ) -> PipelineStartResponse[PipeOutput]:- raise NotImplementedError+ extra: dict[str, Any] | None = None,+ ) -> PipelexRunResultStart:+ """Start a method asynchronously — not implemented by the local runtime.++ Asynchronous execution is owned by the API layer (pipelex-api overrides+ this with Temporal dispatch) and the hosted platform; locally, use+ `execute`.+ """+ _ = (+ pipe_code,+ mthds_contents,+ inputs,+ output_name,+ output_multiplicity,+ dynamic_output_concept_ref,+ extra,+ )+ msg = "start is not implemented by the local runtime. Use execute, or run against an MTHDS API runner."+ raise NotImplementedError(msg)++ @override+ async def validate(+ self,+ mthds_contents: list[str],+ allow_signatures: bool = False,+ ) -> ValidationReport:+ """Parse, validate, and dry-run MTHDS bundles — protocol `validate`.++ Wraps `validate_bundle` and maps its result onto the protocol's+ `ValidationReport`: the parsed blueprint(s) and per-pipe structures are+ reported; `graph_spec` stays None (the dry run validates the graph+ without materializing a spec artifact).++ Args:+ mthds_contents: MTHDS contents to load (always a list, even for one file).+ allow_signatures: Tolerate unimplemented pipe signatures (strict by default).++ Returns:+ ValidationReport with the structural artifacts of a valid bundle.++ Raises:+ PipelexError: When the bundle is invalid (parse, static validation, or dry-run failure).+ """+ library_dirs = [Path(library_dir) for library_dir in self.library_dirs] if self.library_dirs else None+ # `validate_bundle` deliberately leaves its validation library OPEN and+ # current on success (the CLI surfaces consume it before process exit).+ # This protocol wrapper is a long-lived entry point, so restore the+ # caller's current-library and tear the validation library down on the+ # way out — on failure `validate_bundle` already did both, making the+ # cleanup below a no-op.+ prev_library_id = get_current_library_id_or_none()+ try:+ result = await validate_bundle(+ mthds_contents=mthds_contents,+ library_dirs=library_dirs,+ allow_signatures=allow_signatures,+ )+ finally:+ validation_library_id = get_current_library_id_or_none()+ if validation_library_id is not None and validation_library_id != prev_library_id:+ if prev_library_id is not None:+ set_current_library(library_id=prev_library_id)+ else:+ clear_current_library()+ get_library_manager().teardown(library_id=validation_library_id)+ blueprints_dump: list[dict[str, Any]] = [blueprint.model_dump(mode="json") for blueprint in result.blueprints]+ pipe_structures: dict[str, Any] = {pipe.code: pipe.model_dump(mode="json") for pipe in result.pipes}+ return PipelexValidationReport(+ blueprint=blueprints_dump[0] if len(blueprints_dump) == 1 else blueprints_dump,+ graph_spec=None,+ pipe_structures=pipe_structures,+ )++ @override+ async def models(self, category: MthdsModelCategory | None = None) -> MthdsModelDeck:+ """The model deck this runtime can route to — protocol `models`.++ Wraps the builder's `list_models` and shapes its per-category payload+ into the protocol `ModelDeck`.++ Args:+ category: Optional deck filter (`llm`, `extract`, `img_gen`, `search`).++ Returns:+ ModelDeck with presets, aliases, and routing waterfalls.+ """+ categories = [ModelCategory(category)] if category is not None else None+ deck_raw = list_models(categories=categories)+ models: list[MthdsModelInfo] = []+ aliases: dict[str, str] = {}+ waterfalls: dict[str, list[str]] = {}+ presets_by_category: dict[str, list[dict[str, Any]]] = deck_raw["presets"]+ aliases_by_category: dict[str, dict[str, str]] = deck_raw["aliases"]+ waterfalls_by_category: dict[str, dict[str, list[str]]] = deck_raw["waterfalls"]+ for category_key, category_presets in presets_by_category.items():+ for preset in category_presets:+ models.append(MthdsModelInfo(name=preset["name"], type=MthdsModelCategory(category_key)))+ for category_aliases in aliases_by_category.values():+ aliases.update(category_aliases)+ for category_waterfalls in waterfalls_by_category.values():+ waterfalls.update(category_waterfalls)+ return PipelexModelDeck(models=models, aliases=aliases, waterfalls=waterfalls)++ @override+ async def version(self) -> VersionInfo:+ """Protocol + runner versions — protocol `version`.++ Returns:+ VersionInfo with the installed pipelex version as the runner+ version, plus pipelex's identification extensions.+ """+ pipelex_version: str+ try:+ pipelex_version = metadata.version("pipelex")+ except metadata.PackageNotFoundError:+ # Source checkout on PYTHONPATH without an installed distribution —+ # the runtime still works, so version() must not fail.+ pipelex_version = "unknown"+ return PipelexVersionInfo(+ protocol_version=MTHDS_PROTOCOL_VERSION,+ runner_version=pipelex_version,+ implementation="pipelex",+ implementation_version=pipelex_version,+ runtime_version=pipelex_version,+ )diff --git a/pyproject.toml b/pyproject.tomlindex 3df4962d3..a8af7628a 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -1,6 +1,6 @@[project]name = "pipelex"-version = "0.32.1"+version = "0.33.0"description = "Execute composable AI methods declared in the MTHDS open standard"authors = [{ name = "Evotis S.A.S.", email = "[email protected]" }]maintainers = [{ name = "Pipelex staff", email = "[email protected]" }]@@ -30,7 +30,7 @@ dependencies = ["json2html>=1.3.0","kajson==0.7.0","markdown>=3.6",- "mthds>=0.3.0",+ "mthds>=0.4.0","networkx>=3.4.2","openai>=2.0.0","opentelemetry-api",@@ -457,6 +457,9 @@ convention = "google""BLE001", # Broad `except Exception` is acceptable in tests (asserting failure modes, defensive fixtures)]+[tool.uv.sources]+mthds = { git = "https://github.com/mthds-ai/mthds-python.git", rev = "33fcdf0681d894d09d57eab699894552360d954c" }+[tool.uv]required-version = ">=0.7.2"diff --git a/tests/e2e/agent_cli/test_stdout_is_clean_json.py b/tests/e2e/agent_cli/test_stdout_is_clean_json.pyindex c6905d22d..d7cb736a6 100644--- a/tests/e2e/agent_cli/test_stdout_is_clean_json.py+++ b/tests/e2e/agent_cli/test_stdout_is_clean_json.py@@ -1,6 +1,6 @@"""E2E test that the agent CLI's stdout stays clean for JSON-emitting commands.-Downstream tooling (e.g. ``mthds-js``'s ``PipelexRunner``) calls ``JSON.parse(stdout)``+Downstream tooling (e.g. ``mthds-js``'s ``PipelexMTHDSProtocol``) calls ``JSON.parse(stdout)``on commands like ``pipelex-agent models --format json``. The package-default``console_log_target`` / ``console_print_target`` must therefore route logs and richprints to stderr — otherwise a single log line on a setup code path will break everydiff --git a/tests/e2e/pipelex/concepts/nested_concepts/test_nested_concepts_pipe.py b/tests/e2e/pipelex/concepts/nested_concepts/test_nested_concepts_pipe.pyindex 8259496bc..c03097337 100644--- a/tests/e2e/pipelex/concepts/nested_concepts/test_nested_concepts_pipe.py+++ b/tests/e2e/pipelex/concepts/nested_concepts/test_nested_concepts_pipe.py@@ -14,7 +14,7 @@ import pytestfrom pipelex import pretty_printfrom pipelex.core.stuffs.text_content import TextContentfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom tests.e2e.pipelex.concepts.nested_concepts.generated_models.nested_concepts_test__customer import Customerfrom tests.e2e.pipelex.concepts.nested_concepts.generated_models.nested_concepts_test__invoice import Invoicefrom tests.e2e.pipelex.concepts.nested_concepts.generated_models.nested_concepts_test__line_item import LineItem@@ -36,11 +36,11 @@ class TestNestedConceptsPipe:3. The LLM generates structured output with proper nested types4. The output can be accessed via working_memory.get_stuff_as() with typed models"""- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=["tests/e2e/pipelex/concepts/nested_concepts"],pipe_run_mode=pipe_run_mode,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="generate_invoice",inputs={"description_text": TextContent(diff --git a/tests/e2e/pipelex/cv_batch_screening/test_cv_batch_screening.py b/tests/e2e/pipelex/cv_batch_screening/test_cv_batch_screening.pyindex a48771e4f..f51a65441 100644--- a/tests/e2e/pipelex/cv_batch_screening/test_cv_batch_screening.py+++ b/tests/e2e/pipelex/cv_batch_screening/test_cv_batch_screening.py@@ -1,6 +1,6 @@"""Direct-mode e2e test for the CV batch screening pipeline.-Runs the pipelex-demos example 21 pipeline through ``PipelexRunner`` without any+Runs the pipelex-demos example 21 pipeline through ``PipelexMTHDSProtocol`` without anyTemporal layer. The same bundle is also exercised by the temporal in-process test(``tests/integration/pipelex/temporal/library_crate/test_wf_cv_batch_screening.py``)and by the ``/temporal-e2e-validate`` skill (distributed 3-process validation).@@ -15,7 +15,7 @@ from pipelex import logfrom pipelex.core.stuffs.document_content import DocumentContentfrom pipelex.core.stuffs.list_content import ListContentfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom tests.cases.documents import DocumentTestCasesfrom tests.integration.pipelex.temporal.test_data import CvBatchScreeningTemporalTestData@@ -35,8 +35,8 @@ class TestCvBatchScreening:"""mthds_content = Path(CvBatchScreeningTemporalTestData.BUNDLE_FILE).read_text(encoding="utf-8")- runner = PipelexRunner(pipe_run_mode=pipe_run_mode)- response = await runner.execute_pipeline(+ runner = PipelexMTHDSProtocol(pipe_run_mode=pipe_run_mode)+ response = await runner.execute(pipe_code=CvBatchScreeningTemporalTestData.PIPE_CODE,mthds_contents=[mthds_content],inputs={diff --git a/tests/e2e/pipelex/graph/test_graph_with_full_data.py b/tests/e2e/pipelex/graph/test_graph_with_full_data.pyindex 5d490b28f..59fec47d0 100644--- a/tests/e2e/pipelex/graph/test_graph_with_full_data.py+++ b/tests/e2e/pipelex/graph/test_graph_with_full_data.py@@ -20,7 +20,7 @@ from pipelex.graph.mermaidflow.mermaid_html import (from pipelex.graph.mermaidflow.mermaidflow_factory import MermaidflowFactoryfrom pipelex.graph.reactflow.reactflow_html import generate_reactflow_html_asyncfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.tools.misc.chart_utils import FlowchartDirectionfrom pipelex.tools.misc.file_utils import get_incremental_directory_path, save_text_to_pathfrom tests.cases import DocumentTestCases@@ -112,12 +112,12 @@ class TestGraphWithFullData:)# Run pipeline with graph tracing and full data capture- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=["tests/e2e/pipelex/pipes/pipe_operators/pipe_compose"],pipe_run_mode=pipe_run_mode,execution_config=exec_config,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="cv_job_matcher",inputs={"cv_pdf": DocumentContent(url=DocumentTestCases.PDF_FILE_PATH_CV),diff --git a/tests/e2e/pipelex/pipes/pipe_controller/pipe_batch/test_pipe_batch_graph.py b/tests/e2e/pipelex/pipes/pipe_controller/pipe_batch/test_pipe_batch_graph.pyindex 12b663fca..b91291a6f 100644--- a/tests/e2e/pipelex/pipes/pipe_controller/pipe_batch/test_pipe_batch_graph.py+++ b/tests/e2e/pipelex/pipes/pipe_controller/pipe_batch/test_pipe_batch_graph.py@@ -11,7 +11,7 @@ from pipelex.core.stuffs.document_content import DocumentContentfrom pipelex.graph.graph_factory import generate_graph_outputsfrom pipelex.graph.graphspec import EdgeKind, GraphSpec, NodeSpecfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.tools.misc.file_utils import get_incremental_directory_path, save_text_to_pathfrom tests.cases import DocumentTestCasesfrom tests.conftest import TEST_OUTPUTS_DIR@@ -49,12 +49,12 @@ class TestPipeBatchGraph:)# Run PipeBatch pipeline with graph tracing- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=["tests/e2e/pipelex/pipes/pipe_controller/pipe_batch"],pipe_run_mode=pipe_run_mode,execution_config=exec_config,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="batch_analyze_cvs_for_job_offer",inputs={"cvs": [@@ -186,12 +186,12 @@ class TestPipeBatchGraph:exec_config = exec_config.model_copy(update={"graph_config": graph_config})# Run joke batch pipeline- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=["tests/e2e/pipelex/pipes/pipe_controller/pipe_batch"],pipe_run_mode=pipe_run_mode,execution_config=exec_config,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="generate_jokes_from_topics",)pipe_output = response.pipe_output@@ -309,11 +309,11 @@ class TestPipeBatchGraph:attribute of the SearchResult stuff, validating the dotted-path resolutionimplemented in SubPipe.run_pipe()."""- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=["tests/e2e/pipelex/pipes/pipe_controller/pipe_batch"],pipe_run_mode=pipe_run_mode,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="article_briefing",inputs={"topic": "artificial intelligence"},)diff --git a/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/test_pipe_parallel_graph.py b/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/test_pipe_parallel_graph.pyindex 695fa6036..639c13bbf 100644--- a/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/test_pipe_parallel_graph.py+++ b/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/test_pipe_parallel_graph.py@@ -11,7 +11,7 @@ from pipelex.core.stuffs.text_content import TextContentfrom pipelex.graph.graph_factory import generate_graph_outputsfrom pipelex.graph.graphspec import GraphSpec, NodeSpecfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.tools.misc.file_utils import get_incremental_directory_path, save_text_to_pathfrom tests.conftest import TEST_OUTPUTS_DIRfrom tests.e2e.pipelex.pipes.pipe_controller.pipe_parallel.test_data import (@@ -64,12 +64,12 @@ class TestPipeParallelGraph:exec_config = exec_config.model_copy(update={"graph_config": graph_config})# Run pipeline with input text- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=["tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel"],pipe_run_mode=pipe_run_mode,execution_config=exec_config,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="parallel_then_consume",inputs={"input_text": TextContent(text="The quick brown fox jumps over the lazy dog. This is a sample text for testing parallel processing."),@@ -203,12 +203,12 @@ class TestPipeParallelGraph:exec_config = exec_config.model_copy(update={"graph_config": graph_config})# Run pipeline- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=["tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel"],pipe_run_mode=pipe_run_mode,execution_config=exec_config,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code=pipe_code,inputs={"input_text": TextContent(text="Hello world, this is a test document for parallel analysis.")},)diff --git a/tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/test_pipe_sequence_batching.py b/tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/test_pipe_sequence_batching.pyindex eb407ea9c..b0a5afd8a 100644--- a/tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/test_pipe_sequence_batching.py+++ b/tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/test_pipe_sequence_batching.py@@ -14,7 +14,7 @@ from pipelex.hub import get_required_pipefrom pipelex.pipe_run.pipe_run_mode import PipeRunModefrom pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactoryfrom pipelex.pipeline.job_metadata import JobMetadata-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom tests.integration.pipelex.pipes.controller.pipe_sequence.pipe_sequence import Document, ProductRating@@ -67,8 +67,8 @@ async def test_review_analysis_sequence_with_batching()working_memory = WorkingMemoryFactory.make_from_single_stuff(document_stuff)# Execute the pipeline- runner = PipelexRunner()- response = await runner.execute_pipeline(+ runner = PipelexMTHDSProtocol()+ response = await runner.execute(pipe_code="analyze_reviews_sequence",inputs=working_memory,)diff --git a/tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/test_pipe_sequence_multiplicity.py b/tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/test_pipe_sequence_multiplicity.pyindex 478c3c4c6..b4a18f2bf 100644--- a/tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/test_pipe_sequence_multiplicity.py+++ b/tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/test_pipe_sequence_multiplicity.py@@ -7,7 +7,7 @@ from pipelex.core.memory.working_memory_factory import WorkingMemoryFactoryfrom pipelex.core.stuffs.stuff_factory import StuffFactoryfrom pipelex.core.stuffs.text_content import TextContentfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocol@pytest.mark.dry_runnable@@ -31,11 +31,11 @@ class TestPipeSequenceMultiplicity:working_memory = WorkingMemoryFactory.make_from_multiple_stuffs([topic_stuff])# Execute the pipeline- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=["tests/integration/pipelex/pipes/controller/pipe_sequence/"],pipe_run_mode=pipe_run_mode,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="creative_ideation_sequence",inputs=working_memory,)diff --git a/tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/test_pipe_sequence_with_input_memory.py b/tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/test_pipe_sequence_with_input_memory.pyindex f943d07b9..9314fe4f9 100644--- a/tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/test_pipe_sequence_with_input_memory.py+++ b/tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/test_pipe_sequence_with_input_memory.py@@ -4,7 +4,7 @@ import pytestfrom pipelex import pretty_printfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom tests.e2e.pipelex.pipes.pipe_controller.pipe_sequence.test_tweet import OptimizedTweetSAMPLE_DRAFT_TWEET = """@@ -94,11 +94,11 @@ class TestPipeSequenceWithInputMemory:async def test_optimize_tweet_sequence_with_input_memory(self, pipe_run_mode: PipeRunMode):"""Test the optimize_tweet_sequence pipeline using inputs parameter."""# Execute the pipeline using inputs- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=["tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/"],pipe_run_mode=pipe_run_mode,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="optimize_tweet_sequence",inputs={"draft_tweet": {diff --git a/tests/e2e/pipelex/pipes/pipe_operators/pipe_compose/test_pipe_compose_after_inference.py b/tests/e2e/pipelex/pipes/pipe_operators/pipe_compose/test_pipe_compose_after_inference.pyindex 75771d5b2..99df9692d 100644--- a/tests/e2e/pipelex/pipes/pipe_operators/pipe_compose/test_pipe_compose_after_inference.py+++ b/tests/e2e/pipelex/pipes/pipe_operators/pipe_compose/test_pipe_compose_after_inference.py@@ -5,7 +5,7 @@ import pytestfrom pipelex import pretty_printfrom pipelex.core.stuffs.document_content import DocumentContentfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom tests.cases import DocumentTestCasesfrom tests.e2e.pipelex.pipes.pipe_operators.pipe_compose.cv_job_matching_itvw_sheet import InterviewSheet@@ -20,11 +20,11 @@ class TestPipeComposeAfterInference:async def test_pipe_compose_after_inference(self, pipe_run_mode: PipeRunMode):"""Test a pipe which uses inference to analyze stuff and then uses PipeCompose to compose a structured content."""- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=["tests/e2e/pipelex/pipes/pipe_operators/pipe_compose"],pipe_run_mode=pipe_run_mode,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="cv_job_matcher",inputs={"cv_pdf": DocumentContent(url=DocumentTestCases.PDF_FILE_PATH_CV),diff --git a/tests/e2e/pipelex/pipes/pipe_operators/pipe_extract/test_pipe_extract.py b/tests/e2e/pipelex/pipes/pipe_operators/pipe_extract/test_pipe_extract.pyindex bec00b235..c71b98a0c 100644--- a/tests/e2e/pipelex/pipes/pipe_operators/pipe_extract/test_pipe_extract.py+++ b/tests/e2e/pipelex/pipes/pipe_operators/pipe_extract/test_pipe_extract.py@@ -6,7 +6,7 @@ from pipelex import pretty_printfrom pipelex.core.stuffs.document_content import DocumentContentfrom pipelex.core.stuffs.page_content import PageContentfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom tests.e2e.pipelex.pipes.pipe_operators.pipe_extract.test_data import PipeExtractTestCasesLIBRARY_DIRS = ["tests/e2e/pipelex/pipes/pipe_operators/pipe_extract"]@@ -32,11 +32,11 @@ class TestPipeExtract:bot-block HEAD requests with 403, and the pre-flight check must NOT abortthe pipeline — the downstream extractor is the source of truth."""- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=LIBRARY_DIRS,pipe_run_mode=pipe_run_mode,)- pipeline_response = await runner.execute_pipeline(+ pipeline_response = await runner.execute(pipe_code="extract_web_page_e2e",inputs={"document": DocumentContent(url=url),diff --git a/tests/e2e/pipelex/pipes/pipe_operators/pipe_img_gen/test_pipe_img_gen.py b/tests/e2e/pipelex/pipes/pipe_operators/pipe_img_gen/test_pipe_img_gen.pyindex 51186ad89..f202a181a 100644--- a/tests/e2e/pipelex/pipes/pipe_operators/pipe_img_gen/test_pipe_img_gen.py+++ b/tests/e2e/pipelex/pipes/pipe_operators/pipe_img_gen/test_pipe_img_gen.py@@ -5,7 +5,7 @@ import pytestfrom pipelex import pretty_printfrom pipelex.core.stuffs.image_content import ImageContentfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom tests.cases import ImageTestCasesLIBRARY_DIRS = ["tests/e2e/pipelex/pipes/pipe_operators/pipe_img_gen"]@@ -20,11 +20,11 @@ class TestPipeImgGen:async def test_generate_image_basic(self, pipe_run_mode: PipeRunMode):"""Test basic text-to-image generation with a simple prompt."""- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=LIBRARY_DIRS,pipe_run_mode=pipe_run_mode,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="generate_image_basic_e2e",)pipe_output = response.pipe_output@@ -41,11 +41,11 @@ class TestPipeImgGen:@pytest.mark.xfail(reason="Negative prompt is not supported by most models and when it is, it doesn't work well", strict=False)async def test_generate_image_with_negative_prompt(self, pipe_run_mode: PipeRunMode):"""Test text-to-image generation with negative prompt."""- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=LIBRARY_DIRS,pipe_run_mode=pipe_run_mode,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="generate_image_with_negative_e2e",)pipe_output = response.pipe_output@@ -61,11 +61,11 @@ class TestPipeImgGen:async def test_generate_image_from_text(self, pipe_run_mode: PipeRunMode):"""Test image generation with dynamic prompt from input."""- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=LIBRARY_DIRS,pipe_run_mode=pipe_run_mode,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="generate_image_from_input_e2e",inputs={"image_prompt": "A serene Japanese garden with cherry blossoms"},)@@ -94,11 +94,11 @@ class TestPipeImgGen:image_uri: str,):"""Test img2img with a single input image."""- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=LIBRARY_DIRS,pipe_run_mode=pipe_run_mode,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="img2img_single_input_e2e",inputs={"source_image": ImageContent(url=image_uri)},)@@ -127,11 +127,11 @@ class TestPipeImgGen:image_uri: str,):"""Test img2img style transfer transformation."""- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=LIBRARY_DIRS,pipe_run_mode=pipe_run_mode,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="img2img_style_transfer_e2e",inputs={"source_image": ImageContent(url=image_uri)},)@@ -162,11 +162,11 @@ class TestPipeImgGen:subject_image_uri: str,):"""Test blending two images: style from one and subject from the other."""- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=LIBRARY_DIRS,pipe_run_mode=pipe_run_mode,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="img2img_blend_two_images_e2e",inputs={"style_image": ImageContent(url=style_image_uri),diff --git a/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_document_inputs.py b/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_document_inputs.pyindex 0b9fd5c3f..fa48b1dcb 100644--- a/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_document_inputs.py+++ b/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_document_inputs.py@@ -1,4 +1,4 @@-"""E2E tests for document inputs in PipeLLM using execute_pipeline()."""+"""E2E tests for document inputs in PipeLLM using execute()."""import pytest@@ -7,7 +7,7 @@ from pipelex.core.stuffs.document_content import DocumentContentfrom pipelex.core.stuffs.image_content import ImageContentfrom pipelex.core.stuffs.list_content import ListContentfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom tests.cases.documents import DocumentTestCasesfrom tests.e2e.pipelex.pipes.pipe_operators.pipe_llm.pipe_llm_document_inputs import (DocumentListAnalysisE2E,@@ -24,11 +24,11 @@ LIBRARY_DIRS = ["tests/e2e/pipelex/pipes/pipe_operators"]@pytest.mark.dry_runnable@pytest.mark.asyncioclass TestDocumentInputsE2E:- """E2E tests for document input handling using execute_pipeline()."""+ """E2E tests for document input handling using execute()."""async def test_direct_single_document(self, pipe_run_mode: PipeRunMode) -> None:"""Test single direct document input with local PDF file."""- pipeline_response = await PipelexRunner(library_dirs=LIBRARY_DIRS, pipe_run_mode=pipe_run_mode).execute_pipeline(+ pipeline_response = await PipelexMTHDSProtocol(library_dirs=LIBRARY_DIRS, pipe_run_mode=pipe_run_mode).execute(pipe_code="summarize_single_document_e2e",inputs={"document": DocumentContent(url=DocumentTestCases.PDF_FILE_PATH_2),@@ -44,7 +44,7 @@ class TestDocumentInputsE2E:async def test_direct_single_document_by_url(self, pipe_run_mode: PipeRunMode) -> None:"""Test single direct document input with remote URL."""- pipeline_response = await PipelexRunner(library_dirs=LIBRARY_DIRS, pipe_run_mode=pipe_run_mode).execute_pipeline(+ pipeline_response = await PipelexMTHDSProtocol(library_dirs=LIBRARY_DIRS, pipe_run_mode=pipe_run_mode).execute(pipe_code="summarize_single_document_e2e",inputs={"document": DocumentContent(url=DocumentTestCases.PDF_FILE_URL_1),@@ -66,7 +66,7 @@ class TestDocumentInputsE2E:])- pipeline_response = await PipelexRunner(library_dirs=LIBRARY_DIRS, pipe_run_mode=pipe_run_mode).execute_pipeline(+ pipeline_response = await PipelexMTHDSProtocol(library_dirs=LIBRARY_DIRS, pipe_run_mode=pipe_run_mode).execute(pipe_code="analyze_document_list_e2e",inputs={"documents": documents},)@@ -82,7 +82,7 @@ class TestDocumentInputsE2E:collection_a = ListContent[DocumentContent](items=[DocumentContent(url=DocumentTestCases.PDF_FILE_PATH_2)])collection_b = ListContent[DocumentContent](items=[DocumentContent(url=DocumentTestCases.PDF_FILE_PATH_3)])- pipeline_response = await PipelexRunner(library_dirs=LIBRARY_DIRS, pipe_run_mode=pipe_run_mode).execute_pipeline(+ pipeline_response = await PipelexMTHDSProtocol(library_dirs=LIBRARY_DIRS, pipe_run_mode=pipe_run_mode).execute(pipe_code="compare_document_lists_e2e",inputs={"collection_a": collection_a,@@ -99,7 +99,7 @@ class TestDocumentInputsE2E:async def test_mixed_document_and_image_inputs(self, pipe_run_mode: PipeRunMode) -> None:"""Test combining document with image input."""- pipeline_response = await PipelexRunner(library_dirs=LIBRARY_DIRS, pipe_run_mode=pipe_run_mode).execute_pipeline(+ pipeline_response = await PipelexMTHDSProtocol(library_dirs=LIBRARY_DIRS, pipe_run_mode=pipe_run_mode).execute(pipe_code="mixed_document_image_inputs_e2e",inputs={"document": DocumentContent(url=DocumentTestCases.PDF_FILE_PATH_2),diff --git a/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_filename_html.py b/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_filename_html.pyindex b7f81f620..514d389c2 100644--- a/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_filename_html.py+++ b/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_filename_html.py@@ -5,7 +5,7 @@ import pytestfrom pipelex.core.stuffs.document_content import DocumentContentfrom pipelex.core.stuffs.image_content import ImageContentfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.urls import URLsfrom tests.cases.documents import DocumentTestCasesfrom tests.cases.images import ImageTestCases@@ -33,11 +33,11 @@ class TestFilenameHtmlE2E:assert ImageContent(url=URLs.png_example_1).filename is Noneassert DocumentContent(url=URLs.pdf_example_1).filename is None- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=LIBRARY_DIRS,pipe_run_mode=pipe_run_mode,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="describe_with_filenames_e2e",inputs={"image": image_content,diff --git a/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_image_inputs.py b/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_image_inputs.pyindex 7eb6ff6b0..a17d1c30d 100644--- a/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_image_inputs.py+++ b/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_image_inputs.py@@ -1,4 +1,4 @@-"""E2E tests for image inputs in PipeLLM using execute_pipeline()."""+"""E2E tests for image inputs in PipeLLM using execute()."""import pytest@@ -9,7 +9,7 @@ from pipelex.core.stuffs.page_content import PageContentfrom pipelex.core.stuffs.text_and_images_content import TextAndImagesContentfrom pipelex.core.stuffs.text_content import TextContentfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom tests.cases import ImageTestCasesfrom tests.e2e.pipelex.pipes.pipe_operators.pipe_llm.pipe_llm_image_inputs import (ImageDescriptionE2E,@@ -26,15 +26,15 @@ LIBRARY_DIRS = ["tests/e2e/pipelex/pipes/pipe_operators"]@pytest.mark.dry_runnable@pytest.mark.asyncioclass TestImageInputsE2E:- """E2E tests for image input handling using execute_pipeline()."""+ """E2E tests for image input handling using execute()."""async def test_direct_single_image(self, pipe_run_mode: PipeRunMode) -> None:"""Test single direct image input."""- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=LIBRARY_DIRS,pipe_run_mode=pipe_run_mode,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="describe_single_image_e2e",inputs={"image": ImageContent(url=LLMVisionTestCases.URL_CLOUDFRONT_ALAN_TURING_JPG),@@ -57,11 +57,11 @@ class TestImageInputsE2E:])- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=LIBRARY_DIRS,pipe_run_mode=pipe_run_mode,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="analyze_image_list_e2e",inputs={"images": images},)@@ -78,11 +78,11 @@ class TestImageInputsE2E:collection_a = ListContent[ImageContent](items=[ImageContent(url=LLMVisionTestCases.URL_CLOUDFRONT_ALAN_TURING_JPG)])collection_b = ListContent[ImageContent](items=[ImageContent(url=ImageTestCases.LOGO_TINY_PNG_DATA_URL)])- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=LIBRARY_DIRS,pipe_run_mode=pipe_run_mode,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="compare_image_lists_e2e",inputs={"collection_a": collection_a,@@ -109,11 +109,11 @@ class TestImageInputsE2E:page_view=ImageContent(url=ImageTestCases.LOGO_TINY_PNG_DATA_URL),)- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=LIBRARY_DIRS,pipe_run_mode=pipe_run_mode,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="describe_page_with_images_e2e",inputs={"page": page_content},)@@ -138,11 +138,11 @@ class TestImageInputsE2E:page_view=ImageContent(url=ImageTestCases.LOGO_TINY_PNG_DATA_URL),)- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=LIBRARY_DIRS,pipe_run_mode=pipe_run_mode,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="describe_page_text_only_e2e",inputs={"page": page_content},)@@ -165,11 +165,11 @@ class TestImageInputsE2E:page_view=ImageContent(url=ImageTestCases.LOGO_TINY_PNG_DATA_URL),)- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=LIBRARY_DIRS,pipe_run_mode=pipe_run_mode,)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="mixed_image_inputs_e2e",inputs={"direct_image": ImageContent(url=LLMVisionTestCases.URL_CLOUDFRONT_ALAN_TURING_JPG),diff --git a/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_json_concept.py b/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_json_concept.pyindex f9b15dc3e..69f5322be 100644--- a/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_json_concept.py+++ b/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_json_concept.py@@ -14,7 +14,7 @@ from pipelex import pretty_printfrom pipelex.core.stuffs.json_content import JSONContentfrom pipelex.core.stuffs.text_content import TextContentfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocol@pytest.mark.llm@@ -26,9 +26,7 @@ class TestPipeLLMJsonConcept:"""A PipeLLM outputting a bare `refines = "JSON"` concept must build andrebuild its structured-output model without raising."""- pipeline_response = await PipelexRunner(- library_dirs=["tests/e2e/pipelex/pipes/pipe_operators"], pipe_run_mode=pipe_run_mode- ).execute_pipeline(+ pipeline_response = await PipelexMTHDSProtocol(library_dirs=["tests/e2e/pipelex/pipes/pipe_operators"], pipe_run_mode=pipe_run_mode).execute(pipe_code="build_index",inputs={"text": TextContent(diff --git a/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_object_list.py b/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_object_list.pyindex 1f36ca0f1..a12c28db5 100644--- a/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_object_list.py+++ b/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_object_list.py@@ -5,7 +5,7 @@ import pytestfrom pipelex import pretty_printfrom pipelex.core.stuffs.text_content import TextContentfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocol@pytest.mark.llm@@ -15,9 +15,7 @@ from pipelex.pipeline.runner import PipelexRunnerclass TestPipeLLMObjectList:async def test_craft_prompts(self, pipe_run_mode: PipeRunMode) -> None:"""Test a PipeLLM pipe that generates a list of structured MoodboardPrompt objects."""- pipeline_response = await PipelexRunner(- library_dirs=["tests/e2e/pipelex/pipes/pipe_operators"], pipe_run_mode=pipe_run_mode- ).execute_pipeline(+ pipeline_response = await PipelexMTHDSProtocol(library_dirs=["tests/e2e/pipelex/pipes/pipe_operators"], pipe_run_mode=pipe_run_mode).execute(pipe_code="craft_prompts",inputs={"inspiration": TextContent(text="1970s bohemian chic with earthy tones and flowing fabrics"),diff --git a/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_text_simple.py b/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_text_simple.pyindex a1d40b693..4af14f23d 100644--- a/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_text_simple.py+++ b/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_text_simple.py@@ -5,7 +5,7 @@ import pytestfrom pipelex import pretty_printfrom pipelex.core.stuffs.text_content import TextContentfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocol@pytest.mark.llm@@ -22,9 +22,7 @@ class TestPipeLLMTextSimple:)async def test_write_haiku(self, pipe_run_mode: PipeRunMode, variant: str, pipe_code: str) -> None:"""Test a simple text-to-text PipeLLM pipe that writes a haiku."""- pipeline_response = await PipelexRunner(- library_dirs=["tests/e2e/pipelex/pipes/pipe_operators"], pipe_run_mode=pipe_run_mode- ).execute_pipeline(+ pipeline_response = await PipelexMTHDSProtocol(library_dirs=["tests/e2e/pipelex/pipes/pipe_operators"], pipe_run_mode=pipe_run_mode).execute(pipe_code=pipe_code,inputs={"topic": TextContent(text="hello world"),diff --git a/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_vision.py b/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_vision.pyindex b3dd8e0e7..3fe3178e7 100644--- a/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_vision.py+++ b/tests/e2e/pipelex/pipes/pipe_operators/pipe_llm/test_pipe_llm_vision.py@@ -5,7 +5,7 @@ import pytestfrom pipelex import pretty_print, pretty_print_mdfrom pipelex.core.stuffs.image_content import ImageContentfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom tests.e2e.pipelex.pipes.pipe_operators.pipe_llm.pipe_llm_vision import VisionAnalysisE2Efrom tests.integration.pipelex.cogt.test_data import LLMVisionTestCasesfrom tests.integration.pipelex.test_data import PipeTestCases@@ -18,9 +18,7 @@ from tests.integration.pipelex.test_data import PipeTestCasesclass TestPipeLLMVision:async def test_describe_image_single(self, pipe_run_mode: PipeRunMode):# Execute the pipeline with an image- pipeline_response = await PipelexRunner(- library_dirs=["tests/e2e/pipelex/pipes/pipe_operators"], pipe_run_mode=pipe_run_mode- ).execute_pipeline(+ pipeline_response = await PipelexMTHDSProtocol(library_dirs=["tests/e2e/pipelex/pipes/pipe_operators"], pipe_run_mode=pipe_run_mode).execute(pipe_code="describe_image_e2e",inputs={"image": ImageContent(url=LLMVisionTestCases.URL_CLOUDFRONT_ALAN_TURING_JPG),@@ -53,9 +51,7 @@ class TestPipeLLMVision:async def test_describe_images_multiple(self, pipe_run_mode: PipeRunMode, pipe_code: str):"""Test the describe_image pipeline with multiple images to discriminate."""# Execute the pipeline with an image- pipeline_response = await PipelexRunner(- library_dirs=["tests/e2e/pipelex/pipes/pipe_operators"], pipe_run_mode=pipe_run_mode- ).execute_pipeline(+ pipeline_response = await PipelexMTHDSProtocol(library_dirs=["tests/e2e/pipelex/pipes/pipe_operators"], pipe_run_mode=pipe_run_mode).execute(pipe_code=pipe_code,inputs={"image_a": ImageContent(url=LLMVisionTestCases.URL_CLOUDFRONT_ALAN_TURING_JPG),@@ -69,9 +65,7 @@ class TestPipeLLMVision:async def test_structured_analysis_of_image_with_gantt_chart(self, pipe_run_mode: PipeRunMode):"""Test vision with a more complex image (Gantt chart)."""# Execute the pipeline with a complex image- pipeline_response = await PipelexRunner(- library_dirs=["tests/e2e/pipelex/pipes/pipe_operators"], pipe_run_mode=pipe_run_mode- ).execute_pipeline(+ pipeline_response = await PipelexMTHDSProtocol(library_dirs=["tests/e2e/pipelex/pipes/pipe_operators"], pipe_run_mode=pipe_run_mode).execute(pipe_code="vision_analysis_e2e",inputs={"image": ImageContent(url=PipeTestCases.URL_IMG_GANTT_PNG),diff --git a/tests/e2e/pipelex/pipes/pipe_operators/pipe_search/test_pipe_search.py b/tests/e2e/pipelex/pipes/pipe_operators/pipe_search/test_pipe_search.pyindex 857fee64d..52c9da044 100644--- a/tests/e2e/pipelex/pipes/pipe_operators/pipe_search/test_pipe_search.py+++ b/tests/e2e/pipelex/pipes/pipe_operators/pipe_search/test_pipe_search.py@@ -6,7 +6,7 @@ from pipelex import pretty_printfrom pipelex.core.stuffs.search_result_content import SearchResultContentfrom pipelex.core.stuffs.text_content import TextContentfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom tests.e2e.pipelex.pipes.pipe_operators.pipe_search.test_data import PipeSearchTestCasesLIBRARY_DIRS = ["tests/e2e/pipelex/pipes/pipe_operators/pipe_search"]@@ -32,11 +32,11 @@ class TestPipeSearch:input_value: str,) -> None:"""Test a sourced web search that returns an answer with sources."""- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=LIBRARY_DIRS,pipe_run_mode=pipe_run_mode,)- pipeline_response = await runner.execute_pipeline(+ pipeline_response = await runner.execute(pipe_code=pipe_code,inputs={input_name: TextContent(text=input_value),diff --git a/tests/e2e/test_signature_validation_mthds.py b/tests/e2e/test_signature_validation_mthds.pyindex 891dcf5af..61c8e6c9c 100644--- a/tests/e2e/test_signature_validation_mthds.py+++ b/tests/e2e/test_signature_validation_mthds.py@@ -9,7 +9,7 @@ from pipelex.pipe_run.pipe_run_mode import PipeRunModefrom pipelex.pipe_signature.exceptions import PipeSignatureNotExecutableError, SignaturesNotAllowedErrorfrom pipelex.pipeline.bundle_validator import DryRunStatusfrom pipelex.pipeline.exceptions import PipelineExecutionError-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.pipeline.validate_bundle import ValidateBundleError, validate_bundle_FIXTURE_DIR = Path(__file__).parent / "fixtures" / "signature_bundles"@@ -76,12 +76,12 @@ class TestSignatureValidationE2E:assert sig_pipe.output.concept.structure_class_name != "TextContent"async def test_live_run_signature_pipeline_fails(self) -> None:- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_dirs=[str(_FIXTURE_DIR)],pipe_run_mode=PipeRunMode.LIVE,)with pytest.raises(PipelineExecutionError) as exc_info:- await runner.execute_pipeline(+ await runner.execute(pipe_code="summarize_doc",inputs={"doc": TextContent(text="A document to summarize.")},)diff --git a/tests/integration/pipelex/cli/agent_cli/test_run_cost_report.py b/tests/integration/pipelex/cli/agent_cli/test_run_cost_report.pyindex 9fe8f2815..74d652158 100644--- a/tests/integration/pipelex/cli/agent_cli/test_run_cost_report.py+++ b/tests/integration/pipelex/cli/agent_cli/test_run_cost_report.py@@ -58,8 +58,8 @@ class TestAgentRunCostReport:response = mocker.MagicMock()response.pipe_output = pipe_outputrunner = mocker.MagicMock()- runner.execute_pipeline = mocker.AsyncMock(return_value=response)- mocker.patch(f"{_RUN_CORE_MODULE}.PipelexRunner", return_value=runner)+ runner.execute = mocker.AsyncMock(return_value=response)+ mocker.patch(f"{_RUN_CORE_MODULE}.PipelexMTHDSProtocol", return_value=runner)async def test_cost_report_in_with_memory_json(self, mocker: MockerFixture, job_metadata: JobMetadata, tmp_path: Path) -> None:pipe_output = PipeOutput(diff --git a/tests/integration/pipelex/core/memory/test_working_memory_factory.py b/tests/integration/pipelex/core/memory/test_working_memory_factory.pyindex ccc524a9b..f39fade81 100644--- a/tests/integration/pipelex/core/memory/test_working_memory_factory.py+++ b/tests/integration/pipelex/core/memory/test_working_memory_factory.py@@ -9,7 +9,7 @@ from pipelex.core.stuffs.text_content import TextContentfrom tests.cases.images import ImageTestCasesif TYPE_CHECKING:- from mthds.models.pipeline_inputs import PipelineInputs+ from mthds.protocol.pipeline_inputs import PipelineInputsclass TestWorkingMemoryFactory:diff --git a/tests/integration/pipelex/csv/test_csv_input_detection.py b/tests/integration/pipelex/csv/test_csv_input_detection.pyindex e4ba97690..d693929d9 100644--- a/tests/integration/pipelex/csv/test_csv_input_detection.py+++ b/tests/integration/pipelex/csv/test_csv_input_detection.py@@ -24,7 +24,7 @@ from pipelex.core.stuffs.list_content import ListContentfrom pipelex.tools.tabular.exceptions import CsvErrorif TYPE_CHECKING:- from mthds.models.pipeline_inputs import PipelineInputs+ from mthds.protocol.pipeline_inputs import PipelineInputsfrom pipelex.core.stuffs.stuff_content import StuffContentdiff --git a/tests/integration/pipelex/csv/test_csv_roundtrip.py b/tests/integration/pipelex/csv/test_csv_roundtrip.pyindex 152888d49..1e965e51c 100644--- a/tests/integration/pipelex/csv/test_csv_roundtrip.py+++ b/tests/integration/pipelex/csv/test_csv_roundtrip.py@@ -21,13 +21,13 @@ from pathlib import Pathfrom typing import TYPE_CHECKING, castimport pytest-from mthds.models.pipeline_inputs import PipelineInputs+from mthds.protocol.pipeline_inputs import PipelineInputsfrom pipelex.core.memory.working_memory_factory import WorkingMemoryFactoryfrom pipelex.core.stuffs.list_content import ListContentfrom pipelex.hub import get_library_managerfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.tools.tabular.csv_codec import csv_from_list_contentif TYPE_CHECKING:@@ -100,8 +100,8 @@ class TestCsvRoundtrip:@pytest.mark.inference@pytest.mark.asyncioasync def test_full_pipeline_round_trip(self, pipe_run_mode: PipeRunMode) -> None:- runner = PipelexRunner(library_dirs=[str(BUNDLE_DIR)], pipe_run_mode=pipe_run_mode)- response = await runner.execute_pipeline(pipe_code="summarize_people", inputs=people_inputs())+ runner = PipelexMTHDSProtocol(library_dirs=[str(BUNDLE_DIR)], pipe_run_mode=pipe_run_mode)+ response = await runner.execute(pipe_code="summarize_people", inputs=people_inputs())content = response.pipe_output.main_stuff.contentassert isinstance(content, ListContent)diff --git a/tests/integration/pipelex/pipeline/test_cost_report_rendering.py b/tests/integration/pipelex/pipeline/test_cost_report_rendering.pyindex f191ce4ca..6f51e06cc 100644--- a/tests/integration/pipelex/pipeline/test_cost_report_rendering.py+++ b/tests/integration/pipelex/pipeline/test_cost_report_rendering.py@@ -24,7 +24,7 @@ from pipelex.config import get_configfrom pipelex.core.pipes.pipe_output import PipeOutputfrom pipelex.pipe_run.pipe_run_mode import PipeRunModefrom pipelex.pipeline.job_metadata import JobMetadata-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.reporting.cost_report_renderer import render_run_cost_reportfrom pipelex.system.configuration.configs import NdjsonTracingConfig, PipelineExecutionConfig, TracingBackend@@ -90,8 +90,8 @@ class TestCostReportRendering:)async def _run(self, execution_config: PipelineExecutionConfig) -> PipeOutput:- runner = PipelexRunner(pipe_run_mode=PipeRunMode.DRY, execution_config=execution_config)- response = await runner.execute_pipeline(pipe_code="echo_topic", mthds_contents=[_MTHDS])+ runner = PipelexMTHDSProtocol(pipe_run_mode=PipeRunMode.DRY, execution_config=execution_config)+ response = await runner.execute(pipe_code="echo_topic", mthds_contents=[_MTHDS])return response.pipe_outputasync def test_renders_correct_non_zero_totals(self, mocker: MockerFixture, job_metadata: JobMetadata) -> None:diff --git a/tests/integration/pipelex/pipeline/test_direct_tracing_assembly.py b/tests/integration/pipelex/pipeline/test_direct_tracing_assembly.pyindex a524a177d..2f4f8ef39 100644--- a/tests/integration/pipelex/pipeline/test_direct_tracing_assembly.py+++ b/tests/integration/pipelex/pipeline/test_direct_tracing_assembly.py@@ -1,6 +1,6 @@"""Integration tests for the Phase-2 DIRECT tracing assembly onto PipeOutput.-A real (dry, no-spend) run through :meth:`PipelexRunner.execute_pipeline` must ride the assembled+A real (dry, no-spend) run through :meth:`PipelexMTHDSProtocol.execute` must ride the assembledartifacts back on ``pipe_output``:- **costs on:** ``pipe_output.tokens_usages`` is populated from the run's emitted usage events.@@ -20,7 +20,7 @@ from pipelex.config import get_configfrom pipelex.core.pipes.pipe_output import PipeOutputfrom pipelex.core.stuffs.stuff_content import StuffContentfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.system.configuration.configs import NdjsonTracingConfig, PipelineExecutionConfig, TracingBackend_DIRECT_DOMAIN = "direct_tracing_assembly"@@ -61,8 +61,8 @@ class TestDirectTracingAssembly:mocker.patch.object(cfg, "ndjson", NdjsonTracingConfig(traces_dir=traces_dir))async def _run(self, execution_config: PipelineExecutionConfig) -> PipeOutput:- runner = PipelexRunner(pipe_run_mode=PipeRunMode.DRY, execution_config=execution_config)- response = await runner.execute_pipeline(pipe_code="echo_topic", mthds_contents=[_DIRECT_MTHDS])+ runner = PipelexMTHDSProtocol(pipe_run_mode=PipeRunMode.DRY, execution_config=execution_config)+ response = await runner.execute(pipe_code="echo_topic", mthds_contents=[_DIRECT_MTHDS])return response.pipe_outputasync def test_costs_on_populates_tokens_usages(self, tmp_path_factory: pytest.TempPathFactory, mocker: MockerFixture) -> None:diff --git a/tests/integration/pipelex/pipeline/test_execution_seams.py b/tests/integration/pipelex/pipeline/test_execution_seams.pyindex 88a65143b..caf7c823f 100644--- a/tests/integration/pipelex/pipeline/test_execution_seams.py+++ b/tests/integration/pipelex/pipeline/test_execution_seams.py@@ -7,7 +7,7 @@ equivalent :class:`PipeJob` against an already-open library."""import pytest-from mthds.models.pipeline_inputs import PipelineInputs+from mthds.protocol.pipeline_inputs import PipelineInputsfrom pytest_mock import MockerFixturefrom pipelex.config import get_configdiff --git a/tests/integration/pipelex/pipeline/test_mock_usage_direct.py b/tests/integration/pipelex/pipeline/test_mock_usage_direct.pyindex 50e2477fc..de540fca2 100644--- a/tests/integration/pipelex/pipeline/test_mock_usage_direct.py+++ b/tests/integration/pipelex/pipeline/test_mock_usage_direct.py@@ -23,7 +23,7 @@ from pipelex.cogt.usage.cost_registry import CostRegistryfrom pipelex.config import get_configfrom pipelex.core.pipes.pipe_output import PipeOutputfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.reporting.cost_report_renderer import render_run_cost_reportfrom pipelex.system.configuration.configs import NdjsonTracingConfig, PipelineExecutionConfig, TracingBackend@@ -76,8 +76,8 @@ class TestMockUsageDirect:async def _run_mock_usage(self, pipe_code: str) -> PipeOutput:# A DRY run; is_mock_usage switches the leaf reporting to non-zero synthetic usage.- runner = PipelexRunner(pipe_run_mode=PipeRunMode.DRY, is_mock_usage=True, execution_config=self._config())- response = await runner.execute_pipeline(pipe_code=pipe_code, mthds_contents=[_MTHDS])+ runner = PipelexMTHDSProtocol(pipe_run_mode=PipeRunMode.DRY, is_mock_usage=True, execution_config=self._config())+ response = await runner.execute(pipe_code=pipe_code, mthds_contents=[_MTHDS])return response.pipe_outputasync def test_text_pipe_mocks_leaf_and_assembles_reportable_usage(self, tmp_path_factory: pytest.TempPathFactory, mocker: MockerFixture) -> None:diff --git a/tests/integration/pipelex/pipeline/test_pipeline_run_id_resubmission.py b/tests/integration/pipelex/pipeline/test_pipeline_run_id_resubmission.pyindex 3002f85b1..0394522ba 100644--- a/tests/integration/pipelex/pipeline/test_pipeline_run_id_resubmission.py+++ b/tests/integration/pipelex/pipeline/test_pipeline_run_id_resubmission.py@@ -5,8 +5,8 @@ so a later run can resubmit the same explicit ``pipeline_run_id`` (the hosted ruclient-supplied id into ``pipeline_run_setup``; before this fix the entry was process-permanentand every resubmission raised ``PipelineManagerAlreadyExistsError``):-- ``execute_pipeline`` success: the runner's ``finally`` removes the entry.-- ``execute_pipeline`` failure (pipe-run raises after setup succeeded): same ``finally`` removes it.+- ``execute`` success: the runner's ``finally`` removes the entry.+- ``execute`` failure (pipe-run raises after setup succeeded): same ``finally`` removes it.- ``pipeline_run_setup`` failure after registration (pipe missing from the bundle): setup removesits OWN registration — the runner never learns the id on this path, so setup must self-clean —and a resubmission of the same explicit id then succeeds.@@ -40,7 +40,7 @@ from pipelex.pipe_run.pipe_run_protocol import PipeRunProtocolfrom pipelex.pipeline.exceptions import PipelineExecutionErrorfrom pipelex.pipeline.pipeline_factory import PipelineFactoryfrom pipelex.pipeline.pipeline_run_setup import pipeline_run_setup-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolif TYPE_CHECKING:from pytest_mock import MockerFixture@@ -78,7 +78,7 @@ def _dry_mock_config() -> PipelineExecutionConfig:class _FailingPipeRun(PipeRunProtocol):- """A PipeRun whose ``run`` always raises, so the failure lands in ``execute_pipeline``'s+ """A PipeRun whose ``run`` always raises, so the failure lands in ``execute``'sfinally AFTER setup has succeeded and registered the run — exercising the runner-side removal."""@@ -97,11 +97,11 @@ class _FailingPipeRun(PipeRunProtocol):@pytest.mark.asyncio(loop_scope="class")class TestPipelineRunIdResubmission:async def test_success_clears_registry_entry(self) -> None:- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(pipe_run_mode=PipeRunMode.DRY,execution_config=_dry_mock_config(),)- response = await runner.execute_pipeline(+ response = await runner.execute(pipe_code="echo_topic",mthds_contents=[_RESUBMISSION_MTHDS],)@@ -113,13 +113,13 @@ class TestPipelineRunIdResubmission:# rejects spy attribute injection).manager = get_pipeline_manager()mint_spy = mocker.spy(PipelineFactory, "make_pipeline")- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(pipe_run_mode=PipeRunMode.DRY,execution_config=_dry_mock_config(),pipe_run=_FailingPipeRun(),)with pytest.raises(PipelineExecutionError):- await runner.execute_pipeline(+ await runner.execute(pipe_code="echo_topic",mthds_contents=[_RESUBMISSION_MTHDS],)@@ -157,7 +157,7 @@ class TestPipelineRunIdResubmission:assert get_pipeline_manager().get_optional_pipeline(pipeline_run_id=explicit_run_id) is not Nonefinally:# Caller-side teardown (pipeline_run_setup leaves the library open and the run- # registered on success — execute_pipeline's finally owns this in production).+ # registered on success — execute's finally owns this in production).get_pipeline_manager().remove_pipeline(pipeline_run_id=explicit_run_id)get_library_manager().teardown(library_id=library_id)clear_current_library()diff --git a/tests/integration/pipelex/pipeline/test_pipeline_run_setup_characterization.py b/tests/integration/pipelex/pipeline/test_pipeline_run_setup_characterization.pyindex 14dcdc9b6..26790714f 100644--- a/tests/integration/pipelex/pipeline/test_pipeline_run_setup_characterization.py+++ b/tests/integration/pipelex/pipeline/test_pipeline_run_setup_characterization.py@@ -10,7 +10,7 @@ What is pinned here:- **Success path (DRY + mock inputs):** the returned ``PipeJob`` resolves therequested pipe with ``run_mode = DRY`` and mock working memory for the pipe'sneeded inputs; the library is left **open and current** (``pipeline_run_setup``- does *not* tear down on success — the caller, ``execute_pipeline``, owns+ does *not* tear down on success — the caller, ``execute``, ownsteardown); exactly one ``PIPELINE_EXECUTE`` telemetry event is emitted; and thepipeline is registered in the pipeline manager.- **``search_domain_codes`` in-place mutation (trap at the domain-insert block):**@@ -30,12 +30,12 @@ What is pinned here:current-library before propagating. This is an **intentional fix**introduced by the seam extraction: previously the open/load/resolve ran*outside* ``pipeline_run_setup``'s ``try`` so this exact failure leaked the- library (``execute_pipeline``'s ``finally`` only tore down when setup returned+ library (``execute``'s ``finally`` only tore down when setup returneda ``library_id``, which it never did). ``acquire_library`` now owns load-timeteardown and the recomposed ``try``/``finally`` owns the post-acquire window,matching the already-hardened ``validate_bundle``.- **Success path leaves no per-run reporting state (Phase 4 — leak fixed by removal):** a- successful run through ``execute_pipeline`` leaves the ``ReportingManager`` with no accumulated+ successful run through ``execute`` leaves the ``ReportingManager`` with no accumulatedper-run state — the per-run event-log context is cleared on the way out, and the live usageregistry has been removed entirely, so the success-path leak it used to suffer (a per-runregistry opened in setup and never closed) is structurally impossible.@@ -48,7 +48,7 @@ What is pinned here:from collections.abc import Callableimport pytest-from mthds.models.pipeline_inputs import PipelineInputs+from mthds.protocol.pipeline_inputs import PipelineInputsfrom pytest_mock import MockerFixturefrom pipelex.config import get_config@@ -64,7 +64,7 @@ from pipelex.hub import (from pipelex.libraries.pipe.exceptions import PipeNotFoundErrorfrom pipelex.pipe_run.pipe_run_mode import PipeRunModefrom pipelex.pipeline.pipeline_run_setup import pipeline_run_setup-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.reporting.reporting_manager import ReportingManagerfrom pipelex.system.configuration.configs import NdjsonTracingConfig, PipelineExecutionConfig, TracingBackendfrom pipelex.system.telemetry.events import EventName@@ -213,7 +213,7 @@ class TestPipelineRunSetupCharacterization:async def test_success_path_leaves_no_per_run_reporting_state(self, tmp_path_factory: pytest.TempPathFactory, mocker: MockerFixture) -> None:# Phase 4: the live usage registry is removed entirely, so the success-path leak (a per-run# registry opened in pipeline_run_setup and never closed) is structurally impossible. Run a real- # DRY pipeline through execute_pipeline with tracing + costs on (so a usage event-log context IS+ # DRY pipeline through execute with tracing + costs on (so a usage event-log context IS# registered during the run), then assert the ReportingManager carries NO per-run state afterward:# the registry concept no longer exists, and the event-log context was cleared on the success path.traces_dir = str(tmp_path_factory.mktemp("char_no_leak"))@@ -231,8 +231,8 @@ class TestPipelineRunSetupCharacterization:generate_usage=True,mock_inputs=True,)- runner = PipelexRunner(pipe_run_mode=PipeRunMode.DRY, execution_config=execution_config)- response = await runner.execute_pipeline(pipe_code="echo_topic", mthds_contents=[_CHAR_MTHDS])+ runner = PipelexMTHDSProtocol(pipe_run_mode=PipeRunMode.DRY, execution_config=execution_config)+ response = await runner.execute(pipe_code="echo_topic", mthds_contents=[_CHAR_MTHDS])assert not hasattr(delegate, "_usage_registries")# This run registered a usage event-log context (tracing + costs on); the success path must havediff --git a/tests/integration/pipelex/pipeline/test_pipeline_run_setup_emit_gates.py b/tests/integration/pipelex/pipeline/test_pipeline_run_setup_emit_gates.pyindex d44695bab..66399653f 100644--- a/tests/integration/pipelex/pipeline/test_pipeline_run_setup_emit_gates.py+++ b/tests/integration/pipelex/pipeline/test_pipeline_run_setup_emit_gates.py@@ -54,7 +54,7 @@ def _config(*, generate_graph: bool, generate_usage: bool) -> PipelineExecutionCdef _cleanup(pipeline_run_id: str, library_id: str) -> None:"""Tear down the per-run state pipeline_run_setup leaves open on the success path.- The success path intentionally does NOT close the tracer / event-log context; execute_pipeline+ The success path intentionally does NOT close the tracer / event-log context; executenormally owns this teardown. Since this test calls pipeline_run_setup directly, it cleans up itself."""get_report_delegate().clear_event_log(context_key=pipeline_run_id)diff --git a/tests/integration/pipelex/pipeline/test_runner_library_lifecycle.py b/tests/integration/pipelex/pipeline/test_runner_library_lifecycle.pyindex 1bd6490b5..db8007e1f 100644--- a/tests/integration/pipelex/pipeline/test_runner_library_lifecycle.py+++ b/tests/integration/pipelex/pipeline/test_runner_library_lifecycle.py@@ -1,11 +1,11 @@-"""Library-lifecycle guarantee for :meth:`PipelexRunner.execute_pipeline`.+"""Library-lifecycle guarantee for :meth:`PipelexMTHDSProtocol.execute`.Pins that a *successful* run RESTORES the caller's outer current-library instead ofclobbering it to ``None``.``pipeline_run_setup`` leaves the run library open and current on success (teardown isthe caller's job — pinned by ``test_pipeline_run_setup_characterization.py``).-``execute_pipeline``'s ``finally`` then tears the run library down, and must restore the+``execute``'s ``finally`` then tears the run library down, and must restore theouter binding the caller held before the run — mirroring ``pipeline_run_setup``'s ownerror-path restore. Without that, a run started inside an outer-library context leaves thenext operation with "No current library set" (or silently falling back to the global class@@ -32,7 +32,7 @@ from pipelex.pipe_run.exceptions import PipeRouterErrorfrom pipelex.pipe_run.pipe_run_mode import PipeRunModefrom pipelex.pipe_run.pipe_run_protocol import PipeRunProtocolfrom pipelex.pipeline.exceptions import PipelineExecutionError-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolif TYPE_CHECKING:from collections.abc import Callable@@ -70,7 +70,7 @@ def _dry_mock_config() -> PipelineExecutionConfig:class _FailingPipeRun(PipeRunProtocol):- """A PipeRun whose ``run`` always raises, so the failure lands in ``execute_pipeline``'s finally+ """A PipeRun whose ``run`` always raises, so the failure lands in ``execute``'s finallyAFTER setup has succeeded and resolved the run library — exercising the runner's own teardown guard."""@@ -91,15 +91,15 @@ class TestRunnerLibraryLifecycle:async def test_success_restores_outer_current_library(self, load_empty_library: Callable[[], str]) -> None:# A run started inside an outer-library context must leave that outer library current after a# SUCCESSFUL run. We pass no library_id, so the run uses its own auto-generated library id;- # execute_pipeline's finally tears that run library down and must RESTORE the outer binding+ # execute's finally tears that run library down and must RESTORE the outer binding# rather than clear it to None.outer_library_id = load_empty_library()try:- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(pipe_run_mode=PipeRunMode.DRY,execution_config=_dry_mock_config(),)- await runner.execute_pipeline(+ await runner.execute(pipe_code="echo_topic",mthds_contents=[_RUNNER_LIFECYCLE_MTHDS],)@@ -113,18 +113,18 @@ class TestRunnerLibraryLifecycle:# branch still clears (set_current_library cannot take None). Clearing first makes this# deterministic under xdist's per-worker shared current-library state.clear_current_library()- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(pipe_run_mode=PipeRunMode.DRY,execution_config=_dry_mock_config(),)- await runner.execute_pipeline(+ await runner.execute(pipe_code="echo_topic",mthds_contents=[_RUNNER_LIFECYCLE_MTHDS],)assert get_current_library_id_or_none() is Noneasync def test_failure_when_outer_is_run_library_clears_instead_of_dangling(self) -> None:- # execute_pipeline's OWN finally guard, mirroring pipeline_run_setup's edge: when the runner's+ # execute's OWN finally guard, mirroring pipeline_run_setup's edge: when the runner's# library_id equals the outer current-library, prev == library_id_resolved. Restoring then# tearing down the same id would leave current-library pointing at a torn-down library; the guard# clears instead. Setup succeeds (echo_topic resolves), then the injected pipe_run raises so the@@ -133,14 +133,14 @@ class TestRunnerLibraryLifecycle:collide_library_id, _ = library_manager.open_library()set_current_library(library_id=collide_library_id)try:- runner = PipelexRunner(+ runner = PipelexMTHDSProtocol(library_id=collide_library_id,pipe_run_mode=PipeRunMode.DRY,execution_config=_dry_mock_config(),pipe_run=_FailingPipeRun(),)with pytest.raises(PipelineExecutionError):- await runner.execute_pipeline(+ await runner.execute(pipe_code="echo_topic",mthds_contents=[_RUNNER_LIFECYCLE_MTHDS],)diff --git a/tests/integration/pipelex/pipeline/test_scoped_in_memory_tracing.py b/tests/integration/pipelex/pipeline/test_scoped_in_memory_tracing.pyindex 0047dd1db..46d90acc4 100644--- a/tests/integration/pipelex/pipeline/test_scoped_in_memory_tracing.py+++ b/tests/integration/pipelex/pipeline/test_scoped_in_memory_tracing.py@@ -21,7 +21,7 @@ from pipelex.config import get_configfrom pipelex.core.pipes.pipe_output import PipeOutputfrom pipelex.hub import scoped_event_logfrom pipelex.pipe_run.pipe_run_mode import PipeRunMode-from pipelex.pipeline.runner import PipelexRunner+from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.system.configuration.configs import NdjsonTracingConfig, TracingBackendfrom pipelex.tracing.in_memory_event_log import InMemoryEventLog@@ -58,8 +58,8 @@ class TestScopedInMemoryTracing:generate_graph=True,mock_inputs=True,)- runner = PipelexRunner(pipe_run_mode=PipeRunMode.DRY, execution_config=execution_config)- response = await runner.execute_pipeline(pipe_code="echo_topic", mthds_contents=[_SCOPED_MTHDS])+ runner = PipelexMTHDSProtocol(pipe_run_mode=PipeRunMode.DRY, execution_config=execution_config)+ response = await runner.execute(pipe_code="echo_topic", mthds_contents=[_SCOPED_MTHDS])return response.pipe_outputasync def test_in_memory_graph_same_instance_no_backend(self, tmp_path: Path, mocker: MockerFixture) -> None:diff --git a/tests/unit/pipelex/builder/test_runner_generator.py b/tests/unit/pipelex/builder/test_runner_generator.pyindex a0c69103e..7c0a936c3 100644--- a/tests/unit/pipelex/builder/test_runner_generator.py+++ b/tests/unit/pipelex/builder/test_runner_generator.py@@ -225,7 +225,7 @@ class TestGenerateRunnerCode:runner_code = generate_runner_code(mock_pipe_single_output)assert "import asyncio" in runner_codeassert "from pipelex.pipelex import Pipelex" in runner_code- assert "from pipelex.pipeline.runner import PipelexRunner" in runner_code+ assert "from pipelex.pipeline.runner import PipelexMTHDSProtocol" in runner_codedef test_runner_code_includes_structure_imports(self, mock_pipe_single_output: MagicMock) -> None:"""Test that generated runner code includes structure class imports."""diff --git a/tests/unit/pipelex/cli/test_traceback_flag_run_core.py b/tests/unit/pipelex/cli/test_traceback_flag_run_core.pyindex a3a5bc29a..9c8ce44a3 100644--- a/tests/unit/pipelex/cli/test_traceback_flag_run_core.py+++ b/tests/unit/pipelex/cli/test_traceback_flag_run_core.py@@ -52,10 +52,10 @@ class TestTracebackFlagInExecuteRunInnerExcepts:)mocker.patch("pipelex.cli.commands.run._run_core.get_console", return_value=mock_console)- mock_runner_cls = mocker.patch("pipelex.cli.commands.run._run_core.PipelexRunner")+ mock_runner_cls = mocker.patch("pipelex.cli.commands.run._run_core.PipelexMTHDSProtocol")mock_runner = mocker.MagicMock()- mock_runner.execute_pipeline = mocker.MagicMock(side_effect=exc)+ mock_runner.execute = mocker.MagicMock(side_effect=exc)mock_runner_cls.return_value = mock_runner# Patch get_config to provide a minimal execution configdiff --git a/tests/unit/pipelex/core/stuffs/data.py b/tests/unit/pipelex/core/stuffs/data.pyindex f71fd3492..fbde471ca 100644--- a/tests/unit/pipelex/core/stuffs/data.py+++ b/tests/unit/pipelex/core/stuffs/data.py@@ -1,7 +1,7 @@from typing import ClassVarfrom markupsafe import escape-from mthds.models.pipeline_inputs import StuffContentOrData+from mthds.protocol.pipeline_inputs import StuffContentOrDatafrom pydantic import Fieldfrom pipelex.core.concepts.concept_factory import ConceptFactory@@ -36,7 +36,7 @@ class AnotherConcept(StructuredContent):value: int = Field(description="Value field")-TEST_CASES: list[tuple[str, StuffContentOrData, str | None, str, Stuff]] = [+TEST_CASES: list[tuple[str, StuffContentOrData | DictStuff, str | None, str, Stuff]] = [# Case 1.1: Content is a string("case-1.1-string",@@ -481,7 +481,7 @@ TEST_CASES: list[tuple[str, StuffContentOrData, str | None, str, Stuff]] = [# Test cases with search_domains - format: (test_name, stuff_content_or_data, stuff_name, stuff_code, search_domains, expected_stuff)-SEARCH_DOMAIN_TEST_CASES: list[tuple[str, StuffContentOrData, str | None, str, list[str], Stuff]] = [+SEARCH_DOMAIN_TEST_CASES: list[tuple[str, StuffContentOrData | DictStuff, str | None, str, list[str], Stuff]] = [# Case with search_domains: StuffContent object("search-domain-stuff-content",@@ -583,7 +583,7 @@ SEARCH_DOMAIN_TEST_CASES: list[tuple[str, StuffContentOrData, str | None, str, l# Error test cases - these should raise exceptions-ERROR_TEST_CASES: list[tuple[str, StuffContentOrData, str | None, str, list[str] | None, type[Exception], str]] = [+ERROR_TEST_CASES: list[tuple[str, StuffContentOrData | DictStuff, str | None, str, list[str] | None, type[Exception], str]] = [# Format: (test_name, stuff_content_or_data, stuff_name, stuff_code, search_domains, expected_exception, error_match)# Empty list - should fail(diff --git a/tests/unit/pipelex/core/stuffs/test_stuff_factory_implicit_memory.py b/tests/unit/pipelex/core/stuffs/test_stuff_factory_implicit_memory.pyindex 555fadbe4..e25d6e628 100644--- a/tests/unit/pipelex/core/stuffs/test_stuff_factory_implicit_memory.py+++ b/tests/unit/pipelex/core/stuffs/test_stuff_factory_implicit_memory.py@@ -2,7 +2,7 @@ from pathlib import Pathfrom typing import Any, Callableimport pytest-from mthds.models.pipeline_inputs import StuffContentOrData+from mthds.protocol.pipeline_inputs import StuffContentOrDatafrom pipelex import log, pretty_printfrom pipelex.core.concepts.concept_factory import ConceptFactorydiff --git a/tests/unit/pipelex/pipe_run/test_delivery_executor.py b/tests/unit/pipelex/pipe_run/test_delivery_executor.pyindex 894602585..4f6129032 100644--- a/tests/unit/pipelex/pipe_run/test_delivery_executor.py+++ b/tests/unit/pipelex/pipe_run/test_delivery_executor.py@@ -72,6 +72,8 @@ class TestDeliveryExecutor:call_kwargs = mock_client.post.call_argspayload = call_kwargs.kwargs["json"]assert payload["pipeline_run_id"] == "plr-456"+ assert payload["state"] == "COMPLETED"+ # Transitional legacy spelling rides along for one release (master D1/D7).assert payload["status"] == "COMPLETED"assert "result_url" not in payloaddiff --git a/tests/unit/pipelex/pipeline/test_input_normalizer.py b/tests/unit/pipelex/pipeline/test_input_normalizer.pynew file mode 100644index 000000000..fc8f6489f--- /dev/null+++ b/tests/unit/pipelex/pipeline/test_input_normalizer.py@@ -0,0 +1,68 @@+"""Unit tests for input_normalizer URL handling.++Regression coverage for the hosted-runner 500 (2026-06-11): a DocumentContent+with a blank url resolved as local path '', `Path('')` became `'.'`, and the+uncaught `IsADirectoryError` escaped as an InternalServerError. Both the blank+url and any unreadable local path must surface as the INPUT-domain+`PipelineInputContentError` (→ 422 at the API layer), never a sanitized 500.+"""++from pathlib import Path++import pytest+from pytest_mock import MockerFixture++from pipelex.core.concepts.concept_factory import ConceptFactory+from pipelex.core.concepts.native.concept_native import NativeConceptCode+from pipelex.core.memory.working_memory import WorkingMemory+from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory+from pipelex.core.stuffs.document_content import DocumentContent+from pipelex.core.stuffs.stuff_factory import StuffFactory+from pipelex.pipeline.exceptions import PipelineInputContentError+from pipelex.pipeline.input_normalizer import normalize_data_urls_to_storage+from pipelex.tools.storage.storage_provider_abstract import StorageProviderAbstract+++def _memory_with_document(url: str) -> WorkingMemory:+ stuff = StuffFactory.make_stuff(+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.DOCUMENT),+ content=DocumentContent(url=url),+ name="document",+ )+ return WorkingMemoryFactory.make_from_single_stuff(stuff)+++def _patch_storage_and_config(mocker: MockerFixture) -> None:+ mocker.patch(+ "pipelex.pipeline.input_normalizer.get_storage_provider",+ return_value=mocker.Mock(spec=StorageProviderAbstract),+ )+ mocker.patch(+ "pipelex.pipeline.input_normalizer.get_config",+ return_value=mocker.Mock(pipelex=mocker.Mock(storage_config=mocker.Mock(is_upload_local_content_enabled=True))),+ )++[email protected](loop_scope="class")+class TestInputNormalizerUrlGuards:+ @pytest.mark.parametrize("blank_url", ["", " "])+ async def test_blank_url_raises_input_error(self, mocker: MockerFixture, blank_url: str) -> None:+ _patch_storage_and_config(mocker)++ with pytest.raises(PipelineInputContentError, match="blank url"):+ await normalize_data_urls_to_storage(_memory_with_document(blank_url))++ async def test_directory_path_raises_input_error(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """A local path that IS a directory must be an input error, not an+ escaped IsADirectoryError (the '.'-as-url production failure mode).+ """+ _patch_storage_and_config(mocker)++ with pytest.raises(PipelineInputContentError, match="cannot be read"):+ await normalize_data_urls_to_storage(_memory_with_document(str(tmp_path)))++ async def test_missing_file_raises_input_error(self, mocker: MockerFixture, tmp_path: Path) -> None:+ _patch_storage_and_config(mocker)++ with pytest.raises(PipelineInputContentError, match="cannot be read"):+ await normalize_data_urls_to_storage(_memory_with_document(str(tmp_path / "nope.pdf")))diff --git a/uv.lock b/uv.lockindex 1840507ba..dc165d76e 100644--- a/uv.lock+++ b/uv.lock@@ -2664,8 +2664,8 @@ wheels = [[[package]]name = "mthds"-version = "0.3.0"-source = { registry = "https://pypi.org/simple" }+version = "0.4.0"+source = { git = "https://github.com/mthds-ai/mthds-python.git?rev=33fcdf0681d894d09d57eab699894552360d954c#33fcdf0681d894d09d57eab699894552360d954c" }dependencies = [{ name = "backports-strenum", marker = "python_full_version < '3.11'" },{ name = "httpx" },@@ -2675,10 +2675,6 @@ dependencies = [{ name = "tomlkit" },{ name = "typing-extensions" },]-sdist = { url = "https://files.pythonhosted.org/packages/5b/3c/eea615b49c011657246ff61371ca4a95ab3baa94d4b79541bd4b0f816ae5/mthds-0.3.0.tar.gz", hash = "sha256:de479f977b2ec3614b23bdb53ed3e28e2332a2f1653ee92e118c530fe3d5d820", size = 112693, upload-time = "2026-04-29T12:50:11.426Z" }-wheels = [- { url = "https://files.pythonhosted.org/packages/f3/86/1184f31583d3089baea9316853b329720cb786d8e01f38f303a17f1e3f4c/mthds-0.3.0-py3-none-any.whl", hash = "sha256:3f9822c23beb82607ec4bafcff99717fb6531eed8d19b86086dc9deb7825b06b", size = 49356, upload-time = "2026-04-29T12:50:09.734Z" },-][[package]]name = "multidict"@@ -3693,7 +3689,7 @@ wheels = [[[package]]name = "pipelex"-version = "0.32.1"+version = "0.33.0"source = { editable = "." }dependencies = [{ name = "aiofiles" },@@ -3864,7 +3860,7 @@ requires-dist = [{ name = "mkdocs-meta-manager", marker = "extra == 'docs'", specifier = ">=1.1.0" },{ name = "mkdocs-redirects", marker = "extra == 'docs'", specifier = "==1.2.2" },{ name = "moto", extras = ["dynamodb", "s3"], marker = "extra == 'dev'", specifier = ">=5.0.0" },- { name = "mthds", specifier = ">=0.3.0" },+ { name = "mthds", git = "https://github.com/mthds-ai/mthds-python.git?rev=33fcdf0681d894d09d57eab699894552360d954c" },{ name = "mypy", marker = "extra == 'dev'", specifier = "==1.19.1" },{ name = "networkx", specifier = ">=3.4.2" },{ name = "openai", specifier = ">=2.0.0" },