Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

feat: public load + sweep composers for validation API (#960)

Louis Choqueled4116f937f7
diff --git a/pipelex/cli/commands/validate/_validate_core.py b/pipelex/cli/commands/validate/_validate_core.py
index 63f32a4d9..c87832424 100644
--- a/pipelex/cli/commands/validate/_validate_core.py
+++ b/pipelex/cli/commands/validate/_validate_core.py
@@ -7,7 +7,6 @@ import typer
from posthog import tag
from rich.traceback import Traceback
-from pipelex import log
from pipelex.cli.cli_factory import make_pipelex_for_cli
from pipelex.cli.error_handlers import (
ErrorContext,
@@ -20,6 +19,7 @@ from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
from pipelex.hub import (
get_console,
get_library_manager,
+ get_pipes,
get_required_pipe,
get_telemetry_manager,
resolve_library_dirs,
@@ -32,6 +32,7 @@ from pipelex.pipe_signature.signature_walk import collect_signature_refs
from pipelex.pipelex import Pipelex
from pipelex.pipeline.bundle_validator import BundleValidator
from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.pipeline.execution_seams import load_libraries_and_activate
from pipelex.pipeline.validate_bundle import validate_bundle
from pipelex.system.runtime import IntegrationMode
from pipelex.system.telemetry.events import EventProperty
@@ -65,32 +66,23 @@ def do_validate_all_libraries_and_dry_run(
tag(name=EventProperty.PIPELEX_VERSION, value=get_package_version())
tag(name=EventProperty.CLI_COMMAND, value=f"{COMMAND} all")
- library_manager = get_library_manager()
- library_id, library = library_manager.open_library()
- set_current_library(library_id=library_id)
- effective_dirs, source_label = resolve_library_dirs(library_dirs)
- if effective_dirs:
- library_manager.load_libraries(library_id=library_id, library_dirs=effective_dirs)
- else:
- log.info(f"No library directories to load ({source_label})")
+ # Single public composer for the open/set/load ceremony — leaves the library loaded and
+ # current for the sweep below, owning the standard 3-tier dir resolution and load-failure
+ # teardown. No teardown on success here: the caller (validate_pipe_cmd) owns Pipelex teardown.
+ load_libraries_and_activate(library_dirs)
- all_pipes = library.pipe_library.get_pipes()
- # In strict mode, signatures themselves are skipped (validating them would always fail
- # the signature pre-check). In lenient mode, iterate all pipes — signatures dry-run trivially.
+ # The pipe list is needed only to render the "Validating N" line and the signature-count
+ # suffix; validate_current_library re-derives it (with the same strict-mode signature filter)
+ # from the current library for the sweep itself.
+ all_pipes = get_pipes()
pipes = all_pipes if allow_signatures else [pipe for pipe in all_pipes if not pipe.is_signature]
if library_dirs:
dirs_str = ", ".join(f'"{lib_dir}"' for lib_dir in library_dirs)
typer.echo(f"Validating {len(pipes)} pipe(s) from: {dirs_str}")
- # BundleValidator.validate_pipes owns the static wiring pass, the strict signature pre-pass,
- # and the single PIPE_DRY_RUN telemetry event — sweeping against the library we just loaded.
- asyncio.run(
- BundleValidator().validate_pipes(
- pipes=pipes,
- library_id=library_id,
- allow_signatures=allow_signatures,
- )
- )
+ # validate_current_library owns the static wiring pass, the strict signature pre-pass, and the
+ # single PIPE_DRY_RUN telemetry event — sweeping the library we just loaded, without teardown.
+ asyncio.run(BundleValidator().validate_current_library(allow_signatures=allow_signatures))
signature_count = sum(1 for pipe in pipes if pipe.is_signature)
typer.echo(f"Setup sequence passed OK, config and pipelines are validated.{_format_signatures_summary_suffix(signature_count)}")
except SignaturesNotAllowedError as sig_error:
diff --git a/pipelex/hub.py b/pipelex/hub.py
index d50e85fde..2908a0a22 100644
--- a/pipelex/hub.py
+++ b/pipelex/hub.py
@@ -39,6 +39,7 @@ from pipelex.system.console_target import ConsoleTarget
from pipelex.system.environment import PIPELEXPATH_ENV_KEY, get_pipelexpath_dirs
from pipelex.system.registries.func_registry import FuncRegistry
from pipelex.system.telemetry.telemetry_manager_abstract import TelemetryManagerAbstract
+from pipelex.tools.misc.file_utils import reject_bare_str_or_path
from pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstract
from pipelex.tools.storage.storage_provider_abstract import StorageProviderAbstract
@@ -551,6 +552,7 @@ def resolve_library_dirs(library_dirs: Sequence[str | Path] | None = None) -> tu
- effective_dirs: The resolved list of Path objects
- source_label: A string describing the source for logging (e.g., "per-call")
"""
+ reject_bare_str_or_path(library_dirs, param_name="library_dirs")
if library_dirs is not None:
return [Path(lib_dir) for lib_dir in library_dirs], "per-call"
diff --git a/pipelex/pipeline/bundle_validator.py b/pipelex/pipeline/bundle_validator.py
index 1a947968c..42773ec34 100644
--- a/pipelex/pipeline/bundle_validator.py
+++ b/pipelex/pipeline/bundle_validator.py
@@ -38,6 +38,7 @@ from pipelex.config import get_config
from pipelex.core.pipes.pipe_abstract import PipeAbstract
from pipelex.hub import (
clear_current_library,
+ get_current_library,
get_current_library_id_or_none,
get_library_manager,
get_pipe_library,
@@ -131,11 +132,9 @@ class BundleValidator:
bundle_uris=bundle_uris,
)
try:
- all_pipes = get_pipe_library().get_pipes()
- # In strict mode, signatures themselves are excluded (validating one directly would always
- # trip the pre-check); in lenient mode they stay (they dry-run trivially by minting a mock).
- pipes = all_pipes if allow_signatures else [pipe for pipe in all_pipes if not pipe.is_signature]
- return await self.validate_pipes(pipes, library_id=acquired_id, allow_signatures=allow_signatures)
+ # acquire_library left the freshly-acquired library current, so the inner sweep over the
+ # current library targets exactly acquired_id (it filters signatures in strict mode itself).
+ return await self.validate_current_library(allow_signatures=allow_signatures)
finally:
# Restore the caller's outer current-library FIRST (so the guarantee survives a teardown
# raise), then tear the acquired library down — mirroring validate_bundle / acquire_library.
@@ -147,6 +146,21 @@ class BundleValidator:
clear_current_library()
get_library_manager().teardown(library_id=acquired_id)
+ async def validate_current_library(self, *, allow_signatures: bool = False) -> dict[str, DryRunOutput]:
+ """Sweep every pipe in the already-open **current** library, **without** tearing it down.
+
+ The public inner sweep over the active library (D6): the caller owns the library lifecycle —
+ this borrows the current library, classifies its pipes, and leaves it loaded. In strict mode
+ signatures are excluded (validating one directly would always trip the pre-check); in lenient
+ mode they stay (they dry-run trivially by minting a mock). This is the loaded-library twin of
+ :meth:`acquire_and_validate` (which acquires + tears down) and the shared core both the
+ ``validate --all`` CLI and downstream consumers (e.g. cocode) build on instead of re-deriving
+ ``get_pipes`` + signature filtering + ``validate_pipes`` by hand.
+ """
+ all_pipes = get_pipe_library().get_pipes()
+ pipes = all_pipes if allow_signatures else [pipe for pipe in all_pipes if not pipe.is_signature]
+ return await self.validate_pipes(pipes, library_id=get_current_library(), allow_signatures=allow_signatures)
+
async def validate_pipes(
self,
pipes: list[PipeAbstract],
diff --git a/pipelex/pipeline/execution_seams.py b/pipelex/pipeline/execution_seams.py
index 4b939dad6..ca8ccef40 100644
--- a/pipelex/pipeline/execution_seams.py
+++ b/pipelex/pipeline/execution_seams.py
@@ -18,6 +18,7 @@ Two pure-ish building blocks composed by both the single-run wrapper
library mutation.
"""
+from collections.abc import Sequence
from pathlib import Path
from typing import TYPE_CHECKING
@@ -44,6 +45,7 @@ from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
from pipelex.pipeline.input_normalizer import normalize_data_urls_to_storage
from pipelex.pipeline.job_metadata import JobMetadata, OtelContext
from pipelex.system.configuration.configs import PipelineExecutionConfig
+from pipelex.tools.misc.file_utils import reject_bare_str_or_path
if TYPE_CHECKING:
from pipelex.core.bundles.pipelex_bundle_blueprint import PipelexBundleBlueprint
@@ -130,6 +132,28 @@ def acquire_library(
library_manager.teardown(library_id=library_id)
+def load_libraries_and_activate(library_dirs: Sequence[str | Path] | None = None) -> str:
+ """Open a fresh library, set it current, resolve + load ``library_dirs``, and leave it loaded.
+
+ The single public entry for the open/set/load ceremony that ``Pipelex.make`` deliberately does
+ **not** perform (``make`` only records default dirs). Returns the new ``library_id``; the library
+ stays open and current for the caller to query or sweep (e.g. via
+ :meth:`BundleValidator.validate_current_library`). Delegates to :func:`acquire_library` for the
+ tested open + set-current + load + load-failure teardown, dropping the bundle ``main_pipe`` element
+ that directory-loading callers do not need.
+
+ ``library_dirs`` follows the standard 3-tier resolution (see :func:`resolve_library_dirs`): ``None``
+ falls back to the instance defaults / ``PIPELEXPATH``; an explicit ``[]`` disables loading. A bare
+ ``str``/``Path`` (a single directory) is rejected — wrap it in a list.
+ """
+ reject_bare_str_or_path(library_dirs, param_name="library_dirs")
+ library_id, _ = acquire_library(
+ library_id="",
+ library_dirs=[str(lib_dir) for lib_dir in library_dirs] if library_dirs is not None else None,
+ )
+ return library_id
+
+
async def prepare_pipe_job(
pipe: PipeAbstract,
*,
diff --git a/pipelex/tools/misc/file_utils.py b/pipelex/tools/misc/file_utils.py
index 0d9f47b09..a62376148 100644
--- a/pipelex/tools/misc/file_utils.py
+++ b/pipelex/tools/misc/file_utils.py
@@ -9,6 +9,27 @@ from pydantic import BaseModel, ConfigDict, Field
MAX_FILE_PATH_LENGTH = 4096
+
+def reject_bare_str_or_path(value: object, *, param_name: str) -> None:
+ """Reject a bare ``str``/``Path`` passed where a ``Sequence[str | Path]`` is expected.
+
+ A bare ``str`` satisfies ``Sequence[str | Path]`` (``Sequence`` is covariant), so type checkers
+ silently accept it and it gets iterated character-by-character; a bare ``Path`` is not a
+ ``Sequence`` and dies with a confusing deep error instead. Reject both early with a message that
+ tells the caller to wrap the value in a list. ``None`` and real sequences fall through untouched.
+
+ Args:
+ value: The argument received for a ``Sequence[str | Path]`` parameter.
+ param_name: The parameter's name, used to make the error message actionable.
+
+ Raises:
+ TypeError: If ``value`` is a bare ``str`` or ``Path``.
+ """
+ if isinstance(value, (str, Path)):
+ msg = f"{param_name} must be a sequence of paths, not a single {type(value).__name__}; wrap it as [{value!r}]"
+ raise TypeError(msg)
+
+
########################################################
# Save & Load
########################################################
diff --git a/pipelex/tools/misc/toml_utils.py b/pipelex/tools/misc/toml_utils.py
index e9c40e016..64659ed3d 100644
--- a/pipelex/tools/misc/toml_utils.py
+++ b/pipelex/tools/misc/toml_utils.py
@@ -10,7 +10,7 @@ import tomli
import tomlkit
from pipelex.tools.misc.exceptions import TomlError
-from pipelex.tools.misc.file_utils import path_exists
+from pipelex.tools.misc.file_utils import path_exists, reject_bare_str_or_path
from pipelex.tools.misc.json_utils import deep_update
@@ -82,6 +82,7 @@ def load_toml_from_path_and_merge_with_overrides(paths: Sequence[str | Path]) ->
Returns:
dict[str, Any]: The merged dictionary
"""
+ reject_bare_str_or_path(paths, param_name="paths")
merged_dict: dict[str, Any] = {}
for path in paths:
if one_dict := load_toml_from_path_if_exists(path):
diff --git a/tests/integration/pipelex/pipeline/test_public_validation_api.py b/tests/integration/pipelex/pipeline/test_public_validation_api.py
new file mode 100644
index 000000000..6434e472c
--- /dev/null
+++ b/tests/integration/pipelex/pipeline/test_public_validation_api.py
@@ -0,0 +1,91 @@
+"""Integration tests for the public load + sweep composers consumers build on.
+
+These pin the two surfaces downstream consumers (e.g. cocode) use instead of re-deriving the
+open/set/load ceremony + ``get_pipes`` + ``is_signature`` filter + ``validate_pipes`` by hand:
+
+- :func:`load_libraries_and_activate` opens a fresh library, loads the given dirs, and **leaves it
+ loaded and current** (returns its id) — the loaded-library counterpart to ``acquire_and_validate``'s
+ acquire-and-teardown lifecycle.
+- :meth:`BundleValidator.validate_current_library` sweeps every (non-signature, in strict mode) pipe in
+ the **current** library and **never** tears it down, so the same loaded library stays usable after.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+
+from pipelex.hub import clear_current_library, get_current_library_id_or_none, get_library_manager, get_pipes
+from pipelex.pipeline.bundle_validator import BundleValidator, DryRunStatus
+from pipelex.pipeline.execution_seams import load_libraries_and_activate
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+_PVA_DOMAIN = "pub_validate_api"
+_PVA_MTHDS = f"""domain = "{_PVA_DOMAIN}"
+description = "Bundle for public validation API tests"
+
+[concept.Doc]
+description = "A document"
+
+[pipe.leaf]
+type = "PipeLLM"
+description = "An implemented leaf"
+inputs = {{ doc = "Doc" }}
+output = "Text"
+prompt = "Summarize $doc"
+
+[pipe.standalone_sig]
+type = "PipeSignature"
+description = "A standalone signature reached by nothing"
+inputs = {{ doc = "Doc" }}
+output = "Text"
+"""
+
+
+def library_dir(tmp_path: Path) -> Path:
+ """Write the test bundle into a temp directory and return that directory."""
+ (tmp_path / f"{_PVA_DOMAIN}.mthds").write_text(_PVA_MTHDS, encoding="utf-8")
+ return tmp_path
+
+
[email protected](loop_scope="class")
+class TestPublicValidationApi:
+ async def test_load_activates_and_sweep_leaves_library_loaded(self, library_dir: Path) -> None:
+ library_id = load_libraries_and_activate([library_dir])
+ try:
+ # load_libraries_and_activate leaves the library open and current for the caller (no teardown).
+ assert get_current_library_id_or_none() == library_id
+ loaded_refs = {pipe.pipe_ref for pipe in get_pipes()}
+ assert f"{_PVA_DOMAIN}.leaf" in loaded_refs
+ assert f"{_PVA_DOMAIN}.standalone_sig" in loaded_refs
+
+ # Strict sweep over the current library: the leaf passes; the standalone signature is filtered
+ # out of the swept set entirely (validating one directly would always trip the pre-pass).
+ results = await BundleValidator().validate_current_library()
+ assert results[f"{_PVA_DOMAIN}.leaf"].status == DryRunStatus.SUCCESS
+ assert f"{_PVA_DOMAIN}.standalone_sig" not in results
+
+ # No teardown: the library is still loaded and current, so a second sweep runs identically.
+ assert get_current_library_id_or_none() == library_id
+ assert {pipe.pipe_ref for pipe in get_pipes()} == loaded_refs
+ second = await BundleValidator().validate_current_library()
+ assert second[f"{_PVA_DOMAIN}.leaf"].status == DryRunStatus.SUCCESS
+ finally:
+ clear_current_library()
+ get_library_manager().teardown(library_id=library_id)
+
+ async def test_lenient_mode_includes_signature_in_sweep(self, library_dir: Path) -> None:
+ library_id = load_libraries_and_activate([library_dir])
+ try:
+ # Lenient mode keeps the standalone signature in the swept set — it dry-runs trivially by
+ # minting a mock — so both pipes appear in the result map.
+ results = await BundleValidator().validate_current_library(allow_signatures=True)
+ assert results[f"{_PVA_DOMAIN}.leaf"].status == DryRunStatus.SUCCESS
+ assert f"{_PVA_DOMAIN}.standalone_sig" in results
+ finally:
+ clear_current_library()
+ get_library_manager().teardown(library_id=library_id)
diff --git a/tests/unit/pipelex/pipeline/test_load_libraries_and_activate.py b/tests/unit/pipelex/pipeline/test_load_libraries_and_activate.py
new file mode 100644
index 000000000..c69c25c07
--- /dev/null
+++ b/tests/unit/pipelex/pipeline/test_load_libraries_and_activate.py
@@ -0,0 +1,21 @@
+"""Unit test for ``load_libraries_and_activate`` rejecting a bare path string.
+
+Regression for the public-helper footgun (PR #960): because ``str`` satisfies
+``Sequence[str | Path]`` (``Sequence`` is covariant), a bare path string used to be accepted by
+type checkers and iterated character-by-character — turning ``"/fake/mylib"`` into the directories
+``"/"``, ``"t"``, ``"m"``, ``"p"``, … and scanning the filesystem root. The guard now rejects it
+before any library is opened, so this stays a pure unit test (no scan, no leaked library).
+"""
+
+import pytest
+
+from pipelex.pipeline.execution_seams import load_libraries_and_activate
+
+
+class TestLoadLibrariesAndActivate:
+ def test_rejects_bare_string(self) -> None:
+ """A bare path *string* — statically a valid ``Sequence[str | Path]`` — raises ``TypeError``
+ before any library work, so the char-by-char filesystem-root scan can never happen.
+ """
+ with pytest.raises(TypeError):
+ load_libraries_and_activate("/fake/mylib")
diff --git a/tests/unit/pipelex/tools/misc/test_reject_bare_str_or_path.py b/tests/unit/pipelex/tools/misc/test_reject_bare_str_or_path.py
new file mode 100644
index 000000000..2bfaecbd9
--- /dev/null
+++ b/tests/unit/pipelex/tools/misc/test_reject_bare_str_or_path.py
@@ -0,0 +1,59 @@
+"""Unit tests for ``reject_bare_str_or_path`` — the guard that stops a bare ``str``/``Path`` from
+being passed where a ``Sequence[str | Path]`` is expected (where it would be iterated
+character-by-character) — and for its wiring into the public functions that take such a sequence.
+"""
+
+from collections.abc import Callable
+from pathlib import Path
+
+import pytest
+
+from pipelex.hub import resolve_library_dirs
+from pipelex.tools.misc.file_utils import reject_bare_str_or_path
+from pipelex.tools.misc.toml_utils import load_toml_from_path_and_merge_with_overrides
+
+
+class TestRejectBareStrOrPath:
+ @pytest.mark.parametrize(
+ "bad_value",
+ [
+ "/fake/mylib",
+ Path("/fake/mylib"),
+ ],
+ )
+ def test_rejects_bare_str_or_path(self, bad_value: object) -> None:
+ """A bare ``str`` or ``Path`` is rejected with a ``TypeError`` that names the param and hints the fix."""
+ with pytest.raises(TypeError) as exc_info:
+ reject_bare_str_or_path(bad_value, param_name="library_dirs")
+ message = str(exc_info.value)
+ assert "library_dirs" in message
+ assert "[" in message # the message tells the caller to wrap the value in a list
+
+ @pytest.mark.parametrize(
+ "good_value",
+ [
+ None,
+ [],
+ [Path("/fake/a"), Path("/fake/b")],
+ ("/fake/a", "/fake/b"),
+ ],
+ )
+ def test_passes_through_sequences_and_none(self, good_value: object) -> None:
+ """``None`` and any real sequence of paths fall through untouched (no raise)."""
+ reject_bare_str_or_path(good_value, param_name="library_dirs")
+
+ @pytest.mark.parametrize(
+ "func",
+ [
+ resolve_library_dirs,
+ load_toml_from_path_and_merge_with_overrides,
+ ],
+ )
+ def test_public_sequence_consumers_reject_bare_string(self, func: Callable[[str], object]) -> None:
+ """Each public function taking ``Sequence[str | Path]`` rejects a bare string at its boundary.
+
+ Pins the guard wiring so a future refactor that drops a call is caught. A bare ``str`` is
+ statically a valid ``Sequence[str | Path]`` (the footgun), so no type-ignore is needed here.
+ """
+ with pytest.raises(TypeError):
+ func("/fake/mylib")