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.pyindex 63f32a4d9..c87832424 100644--- a/pipelex/cli/commands/validate/_validate_core.py+++ b/pipelex/cli/commands/validate/_validate_core.py@@ -7,7 +7,6 @@ import typerfrom posthog import tagfrom rich.traceback import Traceback-from pipelex import logfrom pipelex.cli.cli_factory import make_pipelex_for_clifrom pipelex.cli.error_handlers import (ErrorContext,@@ -20,6 +19,7 @@ from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceErrorfrom 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_refsfrom pipelex.pipelex import Pipelexfrom pipelex.pipeline.bundle_validator import BundleValidatorfrom pipelex.pipeline.exceptions import ValidateBundleError+from pipelex.pipeline.execution_seams import load_libraries_and_activatefrom pipelex.pipeline.validate_bundle import validate_bundlefrom pipelex.system.runtime import IntegrationModefrom 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.pyindex d50e85fde..2908a0a22 100644--- a/pipelex/hub.py+++ b/pipelex/hub.py@@ -39,6 +39,7 @@ from pipelex.system.console_target import ConsoleTargetfrom pipelex.system.environment import PIPELEXPATH_ENV_KEY, get_pipelexpath_dirsfrom pipelex.system.registries.func_registry import FuncRegistryfrom pipelex.system.telemetry.telemetry_manager_abstract import TelemetryManagerAbstract+from pipelex.tools.misc.file_utils import reject_bare_str_or_pathfrom pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstractfrom 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.pyindex 1a947968c..42773ec34 100644--- a/pipelex/pipeline/bundle_validator.py+++ b/pipelex/pipeline/bundle_validator.py@@ -38,6 +38,7 @@ from pipelex.config import get_configfrom pipelex.core.pipes.pipe_abstract import PipeAbstractfrom 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.pyindex 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 wrapperlibrary mutation."""+from collections.abc import Sequencefrom pathlib import Pathfrom typing import TYPE_CHECKING@@ -44,6 +45,7 @@ from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactoryfrom pipelex.pipeline.input_normalizer import normalize_data_urls_to_storagefrom pipelex.pipeline.job_metadata import JobMetadata, OtelContextfrom pipelex.system.configuration.configs import PipelineExecutionConfig+from pipelex.tools.misc.file_utils import reject_bare_str_or_pathif 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.pyindex 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, FieldMAX_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.pyindex e9c40e016..64659ed3d 100644--- a/pipelex/tools/misc/toml_utils.py+++ b/pipelex/tools/misc/toml_utils.py@@ -10,7 +10,7 @@ import tomliimport tomlkitfrom 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_pathfrom 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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")