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.
refactor: use pathlib.Path for filesystem path handling (#948)
Louis Choquel4ba28f52d83d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex d69d7cd3c..53e2196a2 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,8 @@### Changed+- **Filesystem path helpers in `pipelex.tools.misc.file_utils` and `pipelex.tools.misc.json_utils` now take and return `pathlib.Path` instead of `str`.** Helpers such as `save_text_to_path`, `load_text_from_path`, `load_binary` / `load_binary_async`, `load_json_from_path` / `load_json_dict_from_path` / `load_json_list_from_path`, `save_as_json_to_path`, `copy_file`, `remove_file` / `remove_folder`, `ensure_directory_exists` / `ensure_directory_for_file_path`, and `get_incremental_directory_path` / `get_incremental_file_path` now operate on `Path`. Path handling is `Path`-based throughout `pipelex/`, converting to/from `str` only at boundaries (CLI arguments, environment variables, JSON/TOML serialization). Callers passing bare strings must now wrap them with `Path(...)`.+- **`ErrorReport` is now a frozen Pydantic `BaseModel`** (previously a frozen Pydantic dataclass). It is still immutable and still round-trips through `to_dict()` / `from_dict()`, but an attempted mutation now raises `pydantic.ValidationError` instead of `dataclasses.FrozenInstanceError`.- **`recover_error_report()` is now a total function.** It returns an `ErrorReport` rather than `ErrorReport | None`: when a Temporal failure carries no embedded report — or its payload fails to rehydrate — it synthesizes one from the new `UnrecoverableWorkflowFailureError`, surfacing the deepest worker-side cause message. Callers no longer branch on `None`.diff --git a/pipelex/cli/agent_cli/commands/init_cmd.py b/pipelex/cli/agent_cli/commands/init_cmd.pyindex 70b32ec5f..9d036ff13 100644--- a/pipelex/cli/agent_cli/commands/init_cmd.py+++ b/pipelex/cli/agent_cli/commands/init_cmd.py@@ -1,7 +1,6 @@"""Agent CLI init command -- non-interactive Pipelex initialization."""import json-import osimport shutilfrom pathlib import Pathfrom typing import Annotated, Any, cast@@ -29,7 +28,6 @@ from pipelex.system.pipelex_service.pipelex_service_agreement import (update_service_terms_acceptance,)from pipelex.system.telemetry.telemetry_config import TELEMETRY_CONFIG_FILE_NAME, TELEMETRY_PROJECT_TEMPLATE_FILE_NAME-from pipelex.tools.misc.file_utils import path_existsfrom pipelex.tools.misc.toml_utils import load_toml_with_tomlkit, save_toml_to_path@@ -132,17 +130,17 @@ def _copy_inference_templates(target_dir: Path) -> None:template_backends_dir = template_inference_dir / "backends"target_backends_dir = target_inference_dir / "backends"target_backends_dir.mkdir(parents=True, exist_ok=True)- for backend_file in os.listdir(template_backends_dir):- if backend_file.endswith(".toml"):- shutil.copy2(template_backends_dir / backend_file, target_backends_dir / backend_file)+ for backend_file in template_backends_dir.iterdir():+ if backend_file.suffix == ".toml":+ shutil.copy2(backend_file, target_backends_dir / backend_file.name)# Copy deck/*.tomltemplate_deck_dir = template_inference_dir / "deck"target_deck_dir = target_inference_dir / "deck"target_deck_dir.mkdir(parents=True, exist_ok=True)- for deck_file in os.listdir(template_deck_dir):- if deck_file.endswith(".toml"):- shutil.copy2(template_deck_dir / deck_file, target_deck_dir / deck_file)+ for deck_file in template_deck_dir.iterdir():+ if deck_file.suffix == ".toml":+ shutil.copy2(deck_file, target_deck_dir / deck_file.name)write_manifest(target_deck_dir, compute_kit_manifest())@@ -174,8 +172,8 @@ def _copy_telemetry_template(target_dir: Path, for_project: bool) -> None:def _configure_backends(config: dict[str, Any],- backends_toml_path: str,- template_backends_path: str,+ backends_toml_path: Path,+ template_backends_path: Path,) -> list[str]:"""Configure backends in backends.toml based on config input.@@ -187,7 +185,7 @@ def _configure_backends(Returns:List of enabled backend keys."""- if not path_exists(backends_toml_path):+ if not backends_toml_path.exists():agent_error("backends.toml not found after config initialization", "InitConfigError")requested_backends: list[str] | None = config.get("backends")@@ -237,9 +235,9 @@ def _configure_routing(selected_backend_keys: list[str], config: dict[str, Any],Returns:Name of the active routing profile."""- routing_profiles_toml_path = str(target_dir / "inference" / "routing_profiles.toml")+ routing_profiles_toml_path = target_dir / "inference" / "routing_profiles.toml"- if not path_exists(routing_profiles_toml_path):+ if not routing_profiles_toml_path.exists():agent_error("routing_profiles.toml not found after config initialization", "InitConfigError")toml_doc = load_toml_with_tomlkit(routing_profiles_toml_path)@@ -384,7 +382,7 @@ def agent_init_cmd(target_dir = _resolve_target_dir(global_)# Step 1: Copy config files (skips inference/ directory)- config_files_copied = init_config(reset=True, target_dir=str(target_dir))+ config_files_copied = init_config(reset=True, target_dir=target_dir)# Step 1.5: Copy inference templates (init_config skips inference/)_copy_inference_templates(target_dir)@@ -395,8 +393,8 @@ def agent_init_cmd(_copy_telemetry_template(target_dir, for_project=not global_)# Step 2: Configure backends- template_backends_path = str(get_kit_configs_dir() / "inference" / "backends.toml")- backends_toml_path = str(target_dir / "inference" / "backends.toml")+ template_backends_path = Path(str(get_kit_configs_dir() / "inference" / "backends.toml"))+ backends_toml_path = target_dir / "inference" / "backends.toml"backends_enabled = _configure_backends(parsed_config, backends_toml_path, template_backends_path)# Step 3: Configure routingdiff --git a/pipelex/cli/agent_cli/commands/run/stdin_resolver.py b/pipelex/cli/agent_cli/commands/run/stdin_resolver.pyindex c1581e8b4..36664ccbf 100644--- a/pipelex/cli/agent_cli/commands/run/stdin_resolver.py+++ b/pipelex/cli/agent_cli/commands/run/stdin_resolver.py@@ -168,7 +168,7 @@ def _parse_inputs_arg(inputs_arg: str) -> dict[str, Any] | None:agent_error(f"Failed to parse inline JSON inputs: {exc}", "JSONDecodeError", cause=exc)else:try:- loaded = load_json_dict_from_path(inputs_arg)+ loaded = load_json_dict_from_path(Path(inputs_arg))# Resolve relative url paths against the inputs file's parent directorybase_dir = Path(inputs_arg).parent.resolve()return resolve_inputs_paths(loaded, base_dir)diff --git a/pipelex/cli/commands/build/inputs/_inputs_core.py b/pipelex/cli/commands/build/inputs/_inputs_core.pyindex 4de199a05..5abe52805 100644--- a/pipelex/cli/commands/build/inputs/_inputs_core.py+++ b/pipelex/cli/commands/build/inputs/_inputs_core.py@@ -103,8 +103,8 @@ async def _generate_inputs_core(final_output_path = Path("results") / DEFAULT_INPUTS_FILE_NAMEtry:- ensure_directory_for_file_path(file_path=str(final_output_path))- save_text_to_path(text=inputs_json_str, path=str(final_output_path))+ ensure_directory_for_file_path(file_path=final_output_path)+ save_text_to_path(text=inputs_json_str, path=final_output_path)typer.secho(f"Generated input JSON file: {final_output_path}", fg=typer.colors.GREEN)except Exception as exc:# CLI command boundary: any failure writing the file is reported to the user and exits via typer.Exit.diff --git a/pipelex/cli/commands/build/output/_output_core.py b/pipelex/cli/commands/build/output/_output_core.pyindex ad7d7de6e..cd9e67226 100644--- a/pipelex/cli/commands/build/output/_output_core.py+++ b/pipelex/cli/commands/build/output/_output_core.py@@ -117,8 +117,8 @@ async def _generate_output_core(final_output_path = Path("results/output_schema.json")try:- ensure_directory_for_file_path(file_path=str(final_output_path))- save_text_to_path(text=output_str, path=str(final_output_path))+ ensure_directory_for_file_path(file_path=final_output_path)+ save_text_to_path(text=output_str, path=final_output_path)typer.secho(f"Generated output file: {final_output_path}", fg=typer.colors.GREEN)except Exception as exc:# CLI command boundary: any failure writing the file is reported to the user and exits via typer.Exit.diff --git a/pipelex/cli/commands/build/runner/_runner_core.py b/pipelex/cli/commands/build/runner/_runner_core.pyindex c6e13dea3..85996c552 100644--- a/pipelex/cli/commands/build/runner/_runner_core.py+++ b/pipelex/cli/commands/build/runner/_runner_core.py@@ -1,7 +1,6 @@from __future__ import annotationsimport asyncio-from pathlib import Pathfrom typing import TYPE_CHECKINGimport typer@@ -42,6 +41,8 @@ from pipelex.tools.misc.file_utils import ()if TYPE_CHECKING:+ from pathlib import Path+from pipelex.core.bundles.pipelex_bundle_blueprint import PipelexBundleBlueprintCOMMAND = "build"@@ -106,9 +107,9 @@ async def _prepare_runner_core(if output_path:final_output_path = output_pathelse:- bundle_dir = Path(bundle_path).parent+ bundle_dir = bundle_path.parentfinal_output_path = bundle_dir / f"run_{pipe_code}.py"- output_dir = Path(final_output_path).parent+ output_dir = final_output_path.parent# Generate structures folder FIRSTstructures_output_dir = output_dir / "structures"@@ -126,15 +127,15 @@ async def _prepare_runner_core(if structures_output_dir.exists():ClassRegistryUtils.register_classes_in_folder(- folder_path=str(structures_output_dir),+ folder_path=structures_output_dir,base_class=StuffContent,is_recursive=True,)ClassRegistryUtils.register_classes_in_folder(- folder_path=str(output_dir),+ folder_path=output_dir,base_class=StuffContent,is_recursive=True,- force_exclude_dirs=[str(structures_output_dir.resolve())] if structures_output_dir.exists() else None,+ force_exclude_dirs=[structures_output_dir.resolve()] if structures_output_dir.exists() else None,)get_class_registry().register_classes(CoreRegistryModels.get_all_models())@@ -149,7 +150,7 @@ async def _prepare_runner_core(if library_dirs:pipelex_library_dir = str(library_dirs[0].resolve())elif bundle_path:- pipelex_library_dir = str(Path(bundle_path).parent.resolve())+ pipelex_library_dir = str(bundle_path.parent.resolve())else:pipelex_library_dir = None@@ -161,8 +162,8 @@ async def _prepare_runner_core(raise typer.Exit(1) from exctry:- ensure_directory_for_file_path(file_path=str(final_output_path))- save_text_to_path(text=runner_code, path=str(final_output_path))+ ensure_directory_for_file_path(file_path=final_output_path)+ save_text_to_path(text=runner_code, path=final_output_path)typer.secho(f"Generated runner file: {final_output_path}", fg=typer.colors.GREEN)except Exception as exc:# CLI command boundary: any failure writing the file is reported to the user and exits via typer.Exit.diff --git a/pipelex/cli/commands/doctor_cmd.py b/pipelex/cli/commands/doctor_cmd.pyindex a1ce5e14b..087f2b350 100644--- a/pipelex/cli/commands/doctor_cmd.py+++ b/pipelex/cli/commands/doctor_cmd.py@@ -4,7 +4,6 @@ from __future__ import annotationsimport contextlibimport io-import osimport sysfrom pathlib import Pathfrom typing import TYPE_CHECKING, Any@@ -58,7 +57,6 @@ from pipelex.system.telemetry.telemetry_config import TELEMETRY_CONFIG_FILE_NAMEfrom pipelex.tools.log.log_config import LogConfigfrom pipelex.tools.misc.dict_utils import extract_vars_from_strings_recursivefrom pipelex.tools.misc.exceptions import TomlError-from pipelex.tools.misc.file_utils import path_existsfrom pipelex.tools.misc.json_utils import deep_updatefrom pipelex.tools.misc.placeholder import value_is_placeholderfrom pipelex.tools.misc.toml_utils import load_toml_from_path@@ -122,7 +120,7 @@ def check_config_files(config_dir: Path | None = None) -> tuple[bool, int, str]:# Check for missing filestry:- missing_count = init_config(reset=False, dry_run=True, target_dir=str(effective_config_dir))+ missing_count = init_config(reset=False, dry_run=True, target_dir=effective_config_dir)except (PipelexCLIError, OSError) as exc:return False, 0, f"Error checking config files: {exc}"@@ -132,7 +130,7 @@ def check_config_files(config_dir: Path | None = None) -> tuple[bool, int, str]:# - and skips ensure_global_config_exists when --global is set, so this probe# stays a check and never silently materializes ~/.pipelex/ on a fresh machine.pipelex_config_path = config_manager.resolve_config_file("pipelex.toml", config_dir=config_dir)- if path_exists(pipelex_config_path):+ if pipelex_config_path.exists():try:# Suppress stderr and stdout to prevent tracebacks from being printedwith contextlib.redirect_stderr(io.StringIO()), contextlib.redirect_stdout(io.StringIO()):@@ -200,9 +198,9 @@ def check_backend_credentials(config_dir: Path | None = None) -> tuple[bool, dicReturns:Tuple of (is_healthy, backend_reports_dict, summary_message)"""- backends_toml_path = config_manager.resolve_config_file(os.path.join("inference", "backends.toml"), config_dir=config_dir)+ backends_toml_path = config_manager.resolve_config_file("inference/backends.toml", config_dir=config_dir)- if not path_exists(backends_toml_path):+ if not backends_toml_path.exists():return False, {}, "Backend configuration file not found"try:@@ -314,7 +312,7 @@ def replace_backend_file(backend_name: str, dry_run: bool = False, config_dir: P# Determine target pathresolved_config_dir = config_dir or config_manager.pipelex_config_dir- target_dir = Path(resolved_config_dir) / "inference" / "backends"+ target_dir = resolved_config_dir / "inference" / "backends"target_file = target_dir / f"{backend_name}.toml"if dry_run:@@ -342,14 +340,14 @@ def check_backend_files(config_dir: Path | None = None) -> tuple[bool, dict[str,Returns:Tuple of (is_healthy, backend_file_reports_dict, summary_message)"""- backends_dir_path = config_manager.resolve_config_file(os.path.join("inference", "backends"), config_dir=config_dir)+ backends_dir_path = config_manager.resolve_config_file("inference/backends", config_dir=config_dir)- if not path_exists(backends_dir_path):+ if not backends_dir_path.exists():return True, {}, "No backend files to check"# Get list of enabled backends from backends.toml- backends_toml_path = config_manager.resolve_config_file(os.path.join("inference", "backends.toml"), config_dir=config_dir)- if not path_exists(backends_toml_path):+ backends_toml_path = config_manager.resolve_config_file("inference/backends.toml", config_dir=config_dir)+ if not backends_toml_path.exists():return True, {}, "No backends.toml to check"try:@@ -377,9 +375,10 @@ def check_backend_files(config_dir: Path | None = None) -> tuple[bool, dict[str,continue# Check if backend file exists- backend_file_path = str(backends_dir_path / f"{backend_name}.toml")+ backend_file = backends_dir_path / f"{backend_name}.toml"+ backend_file_path = str(backend_file)- if not path_exists(backend_file_path):+ if not backend_file.exists():# No separate file - this is OK, configuration might be inlinecontinuediff --git a/pipelex/cli/commands/graph_cmd.py b/pipelex/cli/commands/graph_cmd.pyindex 8234c3487..bdff1e2bb 100644--- a/pipelex/cli/commands/graph_cmd.py+++ b/pipelex/cli/commands/graph_cmd.py@@ -48,7 +48,7 @@ def _do_graph_render(get_telemetry_manager().track_event(EventName.GRAPH_RENDER)# Load the graphtyper.echo(f"Loading graph from: {input_file}", err=True)- json_str = load_text_from_path(str(input_file))+ json_str = load_text_from_path(input_file)graph_spec = GraphSpec.model_validate_json(json_str)typer.secho(f"✅ Loaded graph with {len(graph_spec.nodes)} nodes", fg=typer.colors.GREEN, err=True)diff --git a/pipelex/cli/commands/init/backends.py b/pipelex/cli/commands/init/backends.pyindex 6190ad790..634ab6746 100644--- a/pipelex/cli/commands/init/backends.py+++ b/pipelex/cli/commands/init/backends.py@@ -25,7 +25,6 @@ from pipelex.hub import get_consolefrom pipelex.kit.paths import get_kit_configs_dirfrom pipelex.system.configuration.config_loader import config_managerfrom pipelex.system.pipelex_service.pipelex_service_agreement import update_service_terms_acceptance-from pipelex.tools.misc.file_utils import path_existsfrom pipelex.tools.misc.toml_utils import load_toml_from_path, load_toml_with_tomlkit, save_toml_to_path@@ -47,7 +46,7 @@ def update_backends_in_toml(toml_doc: Any, selected_indices: list[int], backend_backend_section["enabled"] = backend_key in selected_backend_keys # type: ignore[index]-def get_selected_backend_keys(backends_toml_path: str) -> list[str]:+def get_selected_backend_keys(backends_toml_path: Path) -> list[str]:"""Extract the list of enabled backend keys from backends.toml.Args:@@ -58,7 +57,7 @@ def get_selected_backend_keys(backends_toml_path: str) -> list[str]:"""selected_backends: list[str] = []- if not path_exists(backends_toml_path):+ if not backends_toml_path.exists():return selected_backendstoml_doc = load_toml_from_path(backends_toml_path)@@ -74,13 +73,13 @@ def get_selected_backend_keys(backends_toml_path: str) -> list[str]:return selected_backends-def disable_gateway_backend(backends_toml_path: str) -> None:+def disable_gateway_backend(backends_toml_path: Path) -> None:"""Disable the pipelex_gateway backend in backends.toml.Args:backends_toml_path: Path to the backends.toml file."""- if not path_exists(backends_toml_path):+ if not backends_toml_path.exists():returntoml_doc = load_toml_with_tomlkit(backends_toml_path)@@ -99,16 +98,16 @@ def customize_backends_config(is_first_time_setup: bool = False, target_config_d"""console = get_console()effective_config_dir = target_config_dir or config_manager.pipelex_config_dir- backends_toml_path = str(effective_config_dir / "inference" / "backends.toml")- template_backends_path = str(get_kit_configs_dir() / "inference" / "backends.toml")+ backends_toml_path = effective_config_dir / "inference" / "backends.toml"+ template_backends_path = Path(str(get_kit_configs_dir() / "inference" / "backends.toml"))- if not path_exists(backends_toml_path):+ if not backends_toml_path.exists():console.print("[yellow]⚠ Warning: backends.toml not found, skipping backend customization[/yellow]")returntry:# Get backend options from template and existing config- existing_path = backends_toml_path if path_exists(backends_toml_path) else None+ existing_path = backends_toml_path if backends_toml_path.exists() else Nonebackend_options = get_backend_options_from_toml(template_backends_path, existing_path)# Get currently enabled backends to show user their current selectiondiff --git a/pipelex/cli/commands/init/command.py b/pipelex/cli/commands/init/command.pyindex cf773b043..db95bbc30 100644--- a/pipelex/cli/commands/init/command.py+++ b/pipelex/cli/commands/init/command.py@@ -1,6 +1,5 @@"""Main command orchestration for the init command."""-import osimport shutilfrom pathlib import Path@@ -41,7 +40,6 @@ from pipelex.system.pipelex_service.pipelex_service_config import (from pipelex.system.pipelex_service.remote_config_cache import RemoteConfigCachefrom pipelex.system.pipelex_service.remote_config_fetcher import RemoteConfigFetcherfrom pipelex.system.telemetry.telemetry_config import TELEMETRY_CONFIG_FILE_NAME-from pipelex.tools.misc.file_utils import path_existsclass CachePrimingResult(BaseModel):@@ -143,7 +141,7 @@ def prime_remote_config_cache(console: Console, target_config_dir: Path | None =console.print("[dim]Re-run 'pipelex init' while online to prime the cache for offline dry-runs.[/dim]")-def _check_gateway_terms_if_needed(console: Console, backends_toml_path: str) -> None:+def _check_gateway_terms_if_needed(console: Console, backends_toml_path: Path) -> None:"""Check if gateway is enabled and terms not yet accepted, then prompt for acceptance.This is called after init_config() to ensure users who have gateway enabled@@ -155,7 +153,7 @@ def _check_gateway_terms_if_needed(console: Console, backends_toml_path: str) ->backends_toml_path: Path to backends.toml file."""# Check if backends.toml exists and gateway is enabled- if not path_exists(backends_toml_path):+ if not backends_toml_path.exists():returnselected_backend_keys = get_selected_backend_keys(backends_toml_path)@@ -187,9 +185,9 @@ def determine_needs(check_inference: bool,check_routing: bool,check_telemetry: bool,- backends_toml_path: str,- routing_profiles_toml_path: str,- telemetry_config_path: str,+ backends_toml_path: Path,+ routing_profiles_toml_path: Path,+ telemetry_config_path: Path,target_config_dir: Path | None = None,) -> tuple[bool, bool, bool, bool]:"""Determine what needs to be initialized based on current state.@@ -208,13 +206,11 @@ def determine_needs(Returns:Tuple of (needs_config, needs_inference, needs_routing, needs_telemetry) booleans."""- nb_missing_config_files = (- init_config(reset=False, dry_run=True, target_dir=str(target_config_dir) if target_config_dir else None) if check_config else 0- )+ nb_missing_config_files = init_config(reset=False, dry_run=True, target_dir=target_config_dir) if check_config else 0needs_config = check_config and (nb_missing_config_files > 0 or reset)- needs_inference = check_inference and (not path_exists(backends_toml_path) or reset)- needs_routing = check_routing and (not path_exists(routing_profiles_toml_path) or reset)- needs_telemetry = check_telemetry and (not path_exists(telemetry_config_path) or reset)+ needs_inference = check_inference and (not backends_toml_path.exists() or reset)+ needs_routing = check_routing and (not routing_profiles_toml_path.exists() or reset)+ needs_telemetry = check_telemetry and (not telemetry_config_path.exists() or reset)return needs_config, needs_inference, needs_routing, needs_telemetry@@ -277,8 +273,8 @@ def execute_initialization(reset: bool,check_inference: bool,check_routing: bool,- backends_toml_path: str,- telemetry_config_path: str,+ backends_toml_path: Path,+ telemetry_config_path: Path,is_first_time_backends_setup: bool,target_config_dir: Path | None = None,for_project: bool = False,@@ -306,14 +302,14 @@ def execute_initialization(# Step 1: Initialize config if neededif needs_config:# Check if backends.toml exists before copying- backends_existed_before = path_exists(backends_toml_path)+ backends_existed_before = backends_toml_path.exists()console.print()- init_config(reset=reset, target_dir=str(target_config_dir) if target_config_dir else None)+ init_config(reset=reset, target_dir=target_config_dir)# init_config skips the inference/ directory (handled independently by the inference step).# Detect first-time setup: if backends.toml didn't exist before, inference needs to be set up.- backends_exists_now = path_exists(backends_toml_path)+ backends_exists_now = backends_toml_path.exists()if not backends_existed_before or (check_inference and backends_exists_now):needs_inference = True@@ -338,28 +334,26 @@ def execute_initialization(# Reset backends.tomltemplate_backends_path = template_inference_dir / "backends.toml"- Path(backends_toml_path).parent.mkdir(parents=True, exist_ok=True)+ backends_toml_path.parent.mkdir(parents=True, exist_ok=True)shutil.copy2(template_backends_path, backends_toml_path)# Reset all individual backend files in backends/ directorytemplate_backends_dir = template_inference_dir / "backends"target_backends_dir = target_inference_dir / "backends"target_backends_dir.mkdir(parents=True, exist_ok=True)- for backend_file in os.listdir(template_backends_dir):- if backend_file.endswith((".toml", ".md")):- src_path = template_backends_dir / backend_file- dst_path = target_backends_dir / backend_file- shutil.copy2(src_path, dst_path)+ for backend_file in template_backends_dir.iterdir():+ if backend_file.suffix in {".toml", ".md"}:+ dst_path = target_backends_dir / backend_file.name+ shutil.copy2(backend_file, dst_path)# Reset deck/ directory files (model deck configurations)template_deck_dir = template_inference_dir / "deck"target_deck_dir = target_inference_dir / "deck"target_deck_dir.mkdir(parents=True, exist_ok=True)- for deck_file in os.listdir(template_deck_dir):- if deck_file.endswith(".toml"):- src_path = template_deck_dir / deck_file- dst_path = target_deck_dir / deck_file- shutil.copy2(src_path, dst_path)+ for deck_file in template_deck_dir.iterdir():+ if deck_file.suffix == ".toml":+ dst_path = target_deck_dir / deck_file.name+ shutil.copy2(deck_file, dst_path)# Stamp the deck manifest so future updates can detect drift and# `pipelex update` knows the exact kit version this install came from.@@ -393,9 +387,9 @@ def execute_initialization(# If reset is True, copy the template file firstif reset:effective_config_dir_for_routing = target_config_dir or config_manager.pipelex_config_dir- routing_profiles_toml_path = str(effective_config_dir_for_routing / "inference" / "routing_profiles.toml")+ routing_profiles_toml_path = effective_config_dir_for_routing / "inference" / "routing_profiles.toml"template_routing_path = Path(str(get_kit_configs_dir())) / "inference" / "routing_profiles.toml"- Path(routing_profiles_toml_path).parent.mkdir(parents=True, exist_ok=True)+ routing_profiles_toml_path.parent.mkdir(parents=True, exist_ok=True)shutil.copy2(template_routing_path, routing_profiles_toml_path)console.print("✅ Reset routing_profiles.toml from template")@@ -462,8 +456,8 @@ def _init_agreement(console: Console) -> None:display_gateway_declined_message(console)update_service_terms_acceptance(accepted=False, config_dir=config_manager.global_config_dir)# Disable the gateway since terms were declined- backends_toml_path = str(config_manager.pipelex_config_dir / "inference" / "backends.toml")- if path_exists(backends_toml_path):+ backends_toml_path = config_manager.pipelex_config_dir / "inference" / "backends.toml"+ if backends_toml_path.exists():disable_gateway_backend(backends_toml_path)console.print()@@ -493,8 +487,8 @@ def init_cmd(# Handle credentials-only flow separately (no reset needed)if focus == InitFocus.CREDENTIALS:- backends_toml_path = str(config_manager.pipelex_config_dir / "inference" / "backends.toml")- if not path_exists(backends_toml_path):+ backends_toml_path = config_manager.pipelex_config_dir / "inference" / "backends.toml"+ if not backends_toml_path.exists():console.print()console.print("[yellow]No backends.toml found. Please run 'pipelex init' first.[/yellow]")console.print()@@ -520,9 +514,9 @@ def init_cmd(console.print(f"[dim]Target directory: {target_config_dir}[/dim]")pipelex_config_dir = target_config_dir- telemetry_config_path = str(pipelex_config_dir / TELEMETRY_CONFIG_FILE_NAME)- backends_toml_path = str(pipelex_config_dir / "inference" / "backends.toml")- routing_profiles_toml_path = str(pipelex_config_dir / "inference" / "routing_profiles.toml")+ telemetry_config_path = pipelex_config_dir / TELEMETRY_CONFIG_FILE_NAME+ backends_toml_path = pipelex_config_dir / "inference" / "backends.toml"+ routing_profiles_toml_path = pipelex_config_dir / "inference" / "routing_profiles.toml"# Determine what to check based on focus parametercheck_config = focus in {InitFocus.ALL, InitFocus.CONFIG}@@ -532,7 +526,7 @@ def init_cmd(check_telemetry = focus in {InitFocus.ALL, InitFocus.TELEMETRY}# Track if backends.toml existed before we start- is_first_time_backends_setup = not path_exists(backends_toml_path)+ is_first_time_backends_setup = not backends_toml_path.exists()# Check what needs to be initializedneeds_config, needs_inference, needs_routing, needs_telemetry = determine_needs(diff --git a/pipelex/cli/commands/init/config_files.py b/pipelex/cli/commands/init/config_files.pyindex 184e3afa0..9a4b8f339 100644--- a/pipelex/cli/commands/init/config_files.py+++ b/pipelex/cli/commands/init/config_files.py@@ -1,7 +1,7 @@"""Configuration files management for the init command."""-import osimport shutil+from pathlib import Pathfrom pipelex.cli.exceptions import PipelexCLIErrorfrom pipelex.kit.paths import GIT_IGNORED_CONFIG_FILES, get_kit_configs_dir@@ -17,7 +17,7 @@ INIT_SKIP_FILES: frozenset[str] = GIT_IGNORED_CONFIG_FILES | {TELEMETRY_CONFIG_FINIT_SKIP_DIRS: frozenset[str] = frozenset({"inference"})-def init_config(reset: bool = False, dry_run: bool = False, target_dir: str | None = None) -> int:+def init_config(reset: bool = False, dry_run: bool = False, target_dir: Path | None = None) -> int:"""Initialize pipelex configuration in the .pipelex directory. Does not install telemetry, just the main config and inference backends.Args:@@ -28,38 +28,38 @@ def init_config(reset: bool = False, dry_run: bool = False, target_dir: str | NoReturns:The number of files copied."""- config_template_dir = str(get_kit_configs_dir())- target_config_dir = target_dir or str(config_manager.pipelex_config_dir)+ config_template_dir = Path(str(get_kit_configs_dir()))+ target_config_dir = target_dir or config_manager.pipelex_config_dir- os.makedirs(target_config_dir, exist_ok=True)+ target_config_dir.mkdir(parents=True, exist_ok=True)try:copied_files: list[str] = []existing_files: list[str] = []- def copy_directory_structure(src_dir: str, dst_dir: str, relative_path: str = "", dry_run: bool = False) -> None:+ def copy_directory_structure(src_dir: Path, dst_dir: Path, relative_path: Path | None = None, dry_run: bool = False) -> None:"""Recursively copy directory structure, handling existing files."""- for item in os.listdir(src_dir):- src_item = os.path.join(src_dir, item)- dst_item = os.path.join(dst_dir, item)- relative_item = os.path.join(relative_path, item) if relative_path else item+ for src_item in src_dir.iterdir():+ item = src_item.name+ dst_item = dst_dir / item+ relative_item = (relative_path / item) if relative_path is not None else Path(item)# Skip git-ignored files and telemetry.toml (created when user is prompted)if item in INIT_SKIP_FILES:continue- if os.path.isdir(src_item):+ if src_item.is_dir():if item in INIT_SKIP_DIRS:continueif not dry_run:- os.makedirs(dst_item, exist_ok=True)+ dst_item.mkdir(parents=True, exist_ok=True)copy_directory_structure(src_item, dst_item, relative_item, dry_run)- elif os.path.exists(dst_item) and not reset:- existing_files.append(relative_item)+ elif dst_item.exists() and not reset:+ existing_files.append(relative_item.as_posix())else:if not dry_run:shutil.copy2(src_item, dst_item)- copied_files.append(relative_item)+ copied_files.append(relative_item.as_posix())copy_directory_structure(src_dir=config_template_dir, dst_dir=target_config_dir, dry_run=dry_run)diff --git a/pipelex/cli/commands/init/credentials.py b/pipelex/cli/commands/init/credentials.pyindex 5927db81b..33ddd46c6 100644--- a/pipelex/cli/commands/init/credentials.py+++ b/pipelex/cli/commands/init/credentials.py@@ -12,7 +12,6 @@ from rich.prompt import Promptfrom pipelex.system.configuration.config_loader import config_managerfrom pipelex.system.pipelex_service.pipelex_details import PipelexDetailsfrom pipelex.tools.misc.dict_utils import extract_vars_from_strings_recursive-from pipelex.tools.misc.file_utils import path_existsfrom pipelex.tools.misc.toml_utils import load_toml_from_path@@ -70,7 +69,7 @@ def write_env_file(env_path: Path, entries: dict[str, str]) -> None:env_path.chmod(stat.S_IRUSR | stat.S_IWUSR)-def get_required_vars_for_enabled_backends(backends_toml_path: str) -> dict[str, list[str]]:+def get_required_vars_for_enabled_backends(backends_toml_path: Path) -> dict[str, list[str]]:"""Determine which env vars are required by each enabled backend.Args:@@ -79,7 +78,7 @@ def get_required_vars_for_enabled_backends(backends_toml_path: str) -> dict[str,Returns:Dictionary mapping env var names to the list of backend display names that need them."""- if not path_exists(backends_toml_path):+ if not backends_toml_path.exists():return {}toml_data = load_toml_from_path(backends_toml_path)@@ -102,7 +101,7 @@ def get_required_vars_for_enabled_backends(backends_toml_path: str) -> dict[str,return var_to_backends-def prompt_credentials(console: Console, backends_toml_path: str) -> None:+def prompt_credentials(console: Console, backends_toml_path: Path) -> None:"""Prompt the user for missing credentials and persist them to ~/.pipelex/.env.Reads the backends.toml to find which env vars are needed by enabled backends,diff --git a/pipelex/cli/commands/init/routing.py b/pipelex/cli/commands/init/routing.pyindex a486c70fe..bfe377dda 100644--- a/pipelex/cli/commands/init/routing.py+++ b/pipelex/cli/commands/init/routing.py@@ -20,7 +20,6 @@ from pipelex.cogt.model_routing.routing_profile import PipelexRoutingProfilefrom pipelex.hub import get_consolefrom pipelex.kit.paths import get_kit_configs_dirfrom pipelex.system.configuration.config_loader import config_manager-from pipelex.tools.misc.file_utils import path_existsfrom pipelex.tools.misc.toml_utils import load_toml_with_tomlkit, save_toml_to_path@@ -33,11 +32,11 @@ def customize_routing_profile(selected_backend_keys: list[str], target_config_di"""console = get_console()effective_config_dir = target_config_dir or config_manager.pipelex_config_dir- routing_profiles_toml_path = str(effective_config_dir / "inference" / "routing_profiles.toml")- template_routing_path = str(get_kit_configs_dir() / "inference" / "routing_profiles.toml")- backends_toml_path = str(effective_config_dir / "inference" / "backends.toml")+ routing_profiles_toml_path = effective_config_dir / "inference" / "routing_profiles.toml"+ template_routing_path = Path(str(get_kit_configs_dir() / "inference" / "routing_profiles.toml"))+ backends_toml_path = effective_config_dir / "inference" / "backends.toml"- if not path_exists(routing_profiles_toml_path):+ if not routing_profiles_toml_path.exists():console.print("[yellow]⚠ Warning: routing_profiles.toml not found, skipping routing customization[/yellow]")return@@ -49,7 +48,7 @@ def customize_routing_profile(selected_backend_keys: list[str], target_config_ditoml_doc = load_toml_with_tomlkit(routing_profiles_toml_path)# Get backend options for display names- template_backends_path = str(get_kit_configs_dir() / "inference" / "backends.toml")+ template_backends_path = Path(str(get_kit_configs_dir() / "inference" / "backends.toml"))backend_options = get_backend_options_from_toml(template_backends_path, backends_toml_path)# Case 1: pipelex_gateway is enabled - use all_pipelex_gatewaydiff --git a/pipelex/cli/commands/init/telemetry.py b/pipelex/cli/commands/init/telemetry.pyindex 6f0e94e60..716975f55 100644--- a/pipelex/cli/commands/init/telemetry.py+++ b/pipelex/cli/commands/init/telemetry.py@@ -1,7 +1,7 @@"""Telemetry configuration logic for the init command."""-import osimport shutil+from pathlib import Pathfrom rich.console import Console@@ -9,7 +9,7 @@ from pipelex.kit.paths import get_kit_configs_dirfrom pipelex.system.telemetry.telemetry_config import TELEMETRY_CONFIG_FILE_NAME, TELEMETRY_PROJECT_TEMPLATE_FILE_NAME-def setup_telemetry(console: Console, telemetry_config_path: str, for_project: bool) -> None:+def setup_telemetry(console: Console, telemetry_config_path: Path, for_project: bool) -> None:"""Set up telemetry configuration by copying the appropriate kit template.The global template (`telemetry.toml`) carries active defaults and seeds@@ -23,10 +23,10 @@ def setup_telemetry(console: Console, telemetry_config_path: str, for_project: bfor_project: True when targeting a project's `.pipelex/`; False whentargeting the global `~/.pipelex/`."""- os.makedirs(os.path.dirname(telemetry_config_path), exist_ok=True)+ telemetry_config_path.parent.mkdir(parents=True, exist_ok=True)template_name = TELEMETRY_PROJECT_TEMPLATE_FILE_NAME if for_project else TELEMETRY_CONFIG_FILE_NAME- template_path = os.path.join(str(get_kit_configs_dir()), template_name)+ template_path = Path(str(get_kit_configs_dir())) / template_nameshutil.copy(template_path, telemetry_config_path)console.print()diff --git a/pipelex/cli/commands/init/ui/backends_ui.py b/pipelex/cli/commands/init/ui/backends_ui.pyindex cc55b6d66..46803096a 100644--- a/pipelex/cli/commands/init/ui/backends_ui.py+++ b/pipelex/cli/commands/init/ui/backends_ui.py@@ -1,5 +1,7 @@"""UI components for backend configuration in the init command."""+from pathlib import Path+import typerfrom rich.console import Console, Groupfrom rich.panel import Panel@@ -8,12 +10,11 @@ from rich.table import Tablefrom rich.text import Textfrom pipelex.tools.misc.exceptions import TomlError-from pipelex.tools.misc.file_utils import path_existsfrom pipelex.tools.misc.string_utils import snake_to_capitalize_first_letterfrom pipelex.tools.misc.toml_utils import load_toml_from_path-def get_backend_options_from_toml(template_path: str, existing_path: str | None = None) -> list[tuple[str, str]]:+def get_backend_options_from_toml(template_path: Path, existing_path: Path | None = None) -> list[tuple[str, str]]:"""Get backend options dynamically from TOML files.Args:@@ -27,7 +28,7 @@ def get_backend_options_from_toml(template_path: str, existing_path: str | Noneseen_backends: set[str] = set()# Read template backends- if path_exists(template_path):+ if template_path.exists():toml_doc = load_toml_from_path(template_path)for backend_key in toml_doc:if backend_key != "internal": # Skip internal backend@@ -41,7 +42,7 @@ def get_backend_options_from_toml(template_path: str, existing_path: str | Noneseen_backends.add(backend_key)# Add any additional backends from existing config (custom backends user may have added)- if existing_path and path_exists(existing_path):+ if existing_path and existing_path.exists():toml_doc = load_toml_from_path(existing_path)for backend_key in toml_doc:if backend_key != "internal" and backend_key not in seen_backends:@@ -57,7 +58,7 @@ def get_backend_options_from_toml(template_path: str, existing_path: str | Nonereturn backend_options-def get_currently_enabled_backends(backends_toml_path: str, backend_options: list[tuple[str, str]]) -> list[int]:+def get_currently_enabled_backends(backends_toml_path: Path, backend_options: list[tuple[str, str]]) -> list[int]:"""Get list of currently enabled backend indices from existing backends.toml.Args:@@ -69,7 +70,7 @@ def get_currently_enabled_backends(backends_toml_path: str, backend_options: lis"""currently_enabled: list[int] = []- if not path_exists(backends_toml_path):+ if not backends_toml_path.exists():return currently_enabledtry:diff --git a/pipelex/cli/commands/run/_run_core.py b/pipelex/cli/commands/run/_run_core.pyindex d53243dcd..655d38d65 100644--- a/pipelex/cli/commands/run/_run_core.py+++ b/pipelex/cli/commands/run/_run_core.py@@ -97,7 +97,7 @@ async def _execute_run(raise typer.Exit(1) from json_decode_excelse:try:- pipeline_inputs = load_json_dict_from_path(inputs)+ pipeline_inputs = load_json_dict_from_path(Path(inputs))# Resolve relative url paths against the inputs file's parent directorybase_dir = Path(inputs).parent.resolve()pipeline_inputs = resolve_inputs_paths(pipeline_inputs, base_dir)@@ -151,7 +151,7 @@ async def _execute_run(needs_output_path = (graph_spec is not None) or save_main_stuff or save_working_memoryif needs_output_path:- output_path = Path(get_incremental_directory_path(base_path=output_dir, base_name=f"{pipe_code}_output"))+ output_path = get_incremental_directory_path(base_path=Path(output_dir), base_name=f"{pipe_code}_output")output_path.mkdir(parents=True, exist_ok=True)# Save graph outputs if requested@@ -211,7 +211,7 @@ async def _execute_run(else:working_memory_output_path = str(output_path / "working_memory.json")working_memory_dict = pipe_output.working_memory.smart_dump()- save_as_json_to_path(object_to_save=working_memory_dict, path=working_memory_output_path)+ save_as_json_to_path(object_to_save=working_memory_dict, path=Path(working_memory_output_path))log.verbose(f"Working memory saved to: {working_memory_output_path}")reporting_config = get_config().pipelex.reporting_configdiff --git a/pipelex/cli/dev_cli/commands/sync_main_config_cmd.py b/pipelex/cli/dev_cli/commands/sync_main_config_cmd.pyindex 1ac2d2974..0ec259a61 100644--- a/pipelex/cli/dev_cli/commands/sync_main_config_cmd.py+++ b/pipelex/cli/dev_cli/commands/sync_main_config_cmd.py@@ -14,9 +14,9 @@ from pipelex.tools.misc.toml_sync import TomlSyncResult, sync_toml_valuesfrom pipelex.types import StrEnum# Config file paths-MAIN_CONFIG_PATH = "pipelex/pipelex.toml"-KIT_CONFIG_PATH = "pipelex/kit/configs/pipelex.toml"-PROJECT_CONFIG_PATH = ".pipelex/pipelex.toml"+MAIN_CONFIG_PATH = Path("pipelex/pipelex.toml")+KIT_CONFIG_PATH = Path("pipelex/kit/configs/pipelex.toml")+PROJECT_CONFIG_PATH = Path(".pipelex/pipelex.toml")class SyncTarget(StrEnum):@@ -90,8 +90,7 @@ def sync_main_config_cmd(console = get_console()# Check if main config exists- main_path = Path(MAIN_CONFIG_PATH)- if not main_path.exists():+ if not MAIN_CONFIG_PATH.exists():if quiet:console.print(f"[red]Error:[/red] Main config not found: {MAIN_CONFIG_PATH}")else:@@ -111,12 +110,11 @@ def sync_main_config_cmd(console.print(f" Source: [cyan]{MAIN_CONFIG_PATH}[/cyan]")console.print()- results: list[tuple[str, TomlSyncResult | None, str]] = []+ results: list[tuple[str, TomlSyncResult | None, Path]] = []# Sync to kit configif sync_kit:- kit_path = Path(KIT_CONFIG_PATH)- if kit_path.exists():+ if KIT_CONFIG_PATH.exists():try:kit_result = sync_toml_values(MAIN_CONFIG_PATH, KIT_CONFIG_PATH, dry_run=dry_run)results.append(("kit", kit_result, KIT_CONFIG_PATH))@@ -134,8 +132,7 @@ def sync_main_config_cmd(# Sync to project configif sync_project:- project_path = Path(PROJECT_CONFIG_PATH)- if project_path.exists():+ if PROJECT_CONFIG_PATH.exists():try:project_result = sync_toml_values(MAIN_CONFIG_PATH, PROJECT_CONFIG_PATH, dry_run=dry_run)results.append(("project", project_result, PROJECT_CONFIG_PATH))diff --git a/pipelex/cogt/document/prompt_document_utils.py b/pipelex/cogt/document/prompt_document_utils.pyindex e3f118813..4d3911e1c 100644--- a/pipelex/cogt/document/prompt_document_utils.py+++ b/pipelex/cogt/document/prompt_document_utils.py@@ -6,6 +6,7 @@ PreparedFile instances that can be consumed by LLM provider APIs.import asyncioimport base64+from pathlib import Pathfrom pipelex.cogt.document.prompt_document import (PromptDocument,@@ -67,7 +68,7 @@ async def prepare_prompt_document()case ResolvedLocalPath():- raw_bytes = await load_binary_async(prompt_document.resolved.path)+ raw_bytes = await load_binary_async(Path(prompt_document.resolved.path))prepared = PreparedFileBase64(base64_data=base64.b64encode(raw_bytes).decode("ascii"),file_type=detect_file_type_from_bytes(raw_bytes),@@ -144,7 +145,7 @@ async def prepare_prompt_document_as_base64(prompt_document: PromptDocument) ->)case ResolvedLocalPath():- raw_bytes = await load_binary_async(prompt_document.resolved.path)+ raw_bytes = await load_binary_async(Path(prompt_document.resolved.path))return PreparedFileBase64(base64_data=base64.b64encode(raw_bytes).decode("ascii"),file_type=detect_file_type_from_bytes(raw_bytes),diff --git a/pipelex/cogt/file/file_preparation_utils.py b/pipelex/cogt/file/file_preparation_utils.pyindex 88a4cdd7c..fcc2f5345 100644--- a/pipelex/cogt/file/file_preparation_utils.py+++ b/pipelex/cogt/file/file_preparation_utils.py@@ -5,6 +5,7 @@ instances that can be consumed by various APIs."""import base64+from pathlib import Pathfrom pipelex.hub import get_storage_providerfrom pipelex.tools.misc.file_fetch_utils import fetch_file_from_url_httpx@@ -69,7 +70,7 @@ async def prepare_file_from_uri(if keep_local_path:prepared = PreparedFileLocalPath(path=resolved_uri.path)else:- raw_bytes = await load_binary_async(resolved_uri.path)+ raw_bytes = await load_binary_async(Path(resolved_uri.path))prepared = PreparedFileBase64(base64_data=base64.b64encode(raw_bytes).decode("ascii"),file_type=detect_file_type_from_bytes(raw_bytes),diff --git a/pipelex/cogt/image/prompt_image_utils.py b/pipelex/cogt/image/prompt_image_utils.pyindex 2ec2c6bda..9f75304d4 100644--- a/pipelex/cogt/image/prompt_image_utils.py+++ b/pipelex/cogt/image/prompt_image_utils.py@@ -6,6 +6,7 @@ PreparedFile instances that can be consumed by LLM provider APIs.import asyncioimport base64+from pathlib import Pathfrom pipelex.cogt.image.prompt_image import (PromptImage,@@ -67,7 +68,7 @@ async def prepare_prompt_image()case ResolvedLocalPath():- raw_bytes = await load_binary_async(prompt_image.resolved.path)+ raw_bytes = await load_binary_async(Path(prompt_image.resolved.path))prepared = PreparedFileBase64(base64_data=base64.b64encode(raw_bytes).decode("ascii"),file_type=detect_file_type_from_bytes(raw_bytes),@@ -145,7 +146,7 @@ async def prepare_prompt_image_as_base64(prompt_image: PromptImage) -> PreparedF)case ResolvedLocalPath():- raw_bytes = await load_binary_async(prompt_image.resolved.path)+ raw_bytes = await load_binary_async(Path(prompt_image.resolved.path))return PreparedFileBase64(base64_data=base64.b64encode(raw_bytes).decode("ascii"),file_type=detect_file_type_from_bytes(raw_bytes),diff --git a/pipelex/cogt/models/model_manager.py b/pipelex/cogt/models/model_manager.pyindex b94396ac8..e6278c813 100644--- a/pipelex/cogt/models/model_manager.py+++ b/pipelex/cogt/models/model_manager.py@@ -1,3 +1,5 @@+from pathlib import Path+from typing_extensions import overridefrom pipelex.cogt.exceptions import GatewayUnknownModelError, ModelManagerError@@ -44,7 +46,7 @@ class ModelManager(ModelManagerAbstract):model_deck_paths = [str(path)for path in find_files_in_dir(- dir_path=deck_dir_path,+ dir_path=Path(deck_dir_path),pattern="*.toml",is_recursive=True,)diff --git a/pipelex/libraries/library_manager.py b/pipelex/libraries/library_manager.pyindex b71478c33..9d6f67bb9 100644--- a/pipelex/libraries/library_manager.py+++ b/pipelex/libraries/library_manager.py@@ -260,14 +260,14 @@ class LibraryManager(LibraryManagerAbstract):for library_dir in all_dirs:# Only import files that contain StructuredContent subclasses (uses AST pre-check)ClassRegistryUtils.import_modules_in_folder(- folder_path=str(library_dir),+ folder_path=library_dir,base_class_names=[StructuredContent.__name__],- force_include_dirs=[str(Path(builder_pkg.__file__).parent)],+ force_include_dirs=[Path(builder_pkg.__file__).parent],)# Only import files that contain @pipe_func decorated functions (uses AST pre-check)FuncRegistryUtils.register_funcs_in_folder(- folder_path=str(library_dir),- force_include_dirs=[str(Path(builder_pkg.__file__).parent)],+ folder_path=library_dir,+ force_include_dirs=[Path(builder_pkg.__file__).parent],)# Auto-discover and register all StructuredContent classes from sys.modules@@ -336,9 +336,9 @@ class LibraryManager(LibraryManagerAbstract):for library_dir in all_dirs:# Only import files that contain StructuredContent subclasses (uses AST pre-check)ClassRegistryUtils.import_modules_in_folder(- folder_path=str(library_dir),+ folder_path=library_dir,base_class_names=[StructuredContent.__name__],- force_include_dirs=[str(Path(builder_pkg.__file__).parent)],+ force_include_dirs=[Path(builder_pkg.__file__).parent],)# NOTE: We skip FuncRegistryUtils.register_funcs_in_folder() since we're not loading pipesdiff --git a/pipelex/libraries/library_utils.py b/pipelex/libraries/library_utils.pyindex 7b64a845a..14a4fe27b 100644--- a/pipelex/libraries/library_utils.py+++ b/pipelex/libraries/library_utils.py@@ -73,7 +73,7 @@ def get_pipelex_mthds_files_from_dirs(dirs: set[Path]) -> list[Path]:# Find all .mthds files in the directory, excluding problematic directoriesmthds_files = find_files_in_dir(- dir_path=str(dir_path),+ dir_path=dir_path,pattern=f"*{MTHDS_EXTENSION}",excluded_dirs=list(get_config().pipelex.scan_config.excluded_dirs),force_include_dirs=[str(Path(builder_pkg.__file__).parent)],diff --git a/pipelex/observer/local_observer.py b/pipelex/observer/local_observer.pyindex 317235257..0d40f6896 100644--- a/pipelex/observer/local_observer.py+++ b/pipelex/observer/local_observer.py@@ -1,4 +1,4 @@-import os+from pathlib import Pathimport kajsonfrom typing_extensions import override@@ -15,9 +15,9 @@ class LocalObserverEventType(StrEnum):class LocalObserver(ObserverProtocol):- def __init__(self, storage_dir: str | None = None) -> None:- self.storage_dir = storage_dir or get_config().pipelex.observer_config.observer_dir- os.makedirs(self.storage_dir, exist_ok=True)+ def __init__(self, storage_dir: str | Path | None = None) -> None:+ self.storage_dir = Path(storage_dir or get_config().pipelex.observer_config.observer_dir)+ self.storage_dir.mkdir(parents=True, exist_ok=True)def _write_to_jsonl(self, event_type: str, payload: PayloadType) -> None:payload = {@@ -25,7 +25,7 @@ class LocalObserver(ObserverProtocol):**payload,}- file_path = os.path.join(self.storage_dir, f"{event_type}.jsonl")+ file_path = self.storage_dir / f"{event_type}.jsonl"with open(file_path, "a", encoding="utf-8") as file:file.write(kajson.dumps(payload) + "\n")diff --git a/pipelex/pipeline/input_normalizer.py b/pipelex/pipeline/input_normalizer.pyindex 727b57f0f..cd10e0cf6 100644--- a/pipelex/pipeline/input_normalizer.py+++ b/pipelex/pipeline/input_normalizer.py@@ -6,6 +6,7 @@ pipelex-storage:// URIs for more efficient pipeline processing."""import base64+from pathlib import Pathfrom typing import Any, castimport shortuuid@@ -218,7 +219,7 @@ async def _normalize_url_content(# Read local file, detect type, upload to storagetry:- raw_bytes = await load_binary_async(resolved_uri.path)+ 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 excdiff --git a/pipelex/plugins/mistral/mistral_factory.py b/pipelex/plugins/mistral/mistral_factory.pyindex 14719672c..0cc44ed11 100644--- a/pipelex/plugins/mistral/mistral_factory.py+++ b/pipelex/plugins/mistral/mistral_factory.py@@ -1,6 +1,6 @@import asyncioimport base64-import os+from pathlib import Pathfrom typing import TYPE_CHECKINGimport aiofiles@@ -397,7 +397,7 @@ class MistralFactory:case PreparedFileLocalPath():uploaded_file_id = await cls.upload_file_to_mistral_for_ocr(mistral_client=mistral_client,- file_path=prepared.path,+ file_path=Path(prepared.path),)signed_url_response = await mistral_client.files.get_signed_url_async(file_id=uploaded_file_id)document_url = signed_url_response.url@@ -422,7 +422,7 @@ class MistralFactory:async def upload_file_to_mistral_for_ocr(cls,mistral_client: Mistral,- file_path: str,+ file_path: Path,) -> str:"""Upload a local file to Mistral.@@ -438,7 +438,7 @@ class MistralFactory:file_content = await file.read()uploaded_file = await mistral_client.files.upload_async(- file={"file_name": os.path.basename(file_path), "content": file_content},+ file={"file_name": file_path.name, "content": file_content},purpose="ocr",)return uploaded_file.iddiff --git a/pipelex/plugins/openai/vertexai_factory.py b/pipelex/plugins/openai/vertexai_factory.pyindex 43c188fe9..6debe79a6 100644--- a/pipelex/plugins/openai/vertexai_factory.py+++ b/pipelex/plugins/openai/vertexai_factory.py@@ -1,3 +1,4 @@+from pathlib import Pathfrom typing import Anyfrom pipelex.plugins.openai.openai_exceptions import VertexAIConfigError, VertexAICredentialsError@@ -63,7 +64,7 @@ class VertexAIFactory(ConfigModel):raise MissingDependencyError(lib_name, lib_extra_name, msg) from exctry:- credentials_dict: dict[str, Any] = load_json_dict_from_path(path=gcp_credentials_file_path)+ credentials_dict: dict[str, Any] = load_json_dict_from_path(path=Path(gcp_credentials_file_path))except FileNotFoundError as exc:msg = f"Could not get VertexAI credentials from GCP credentials file: File not found: {gcp_credentials_file_path}"raise VertexAICredentialsError(msg) from excdiff --git a/pipelex/reporting/reporting_manager.py b/pipelex/reporting/reporting_manager.pyindex f4756df23..e10765609 100644--- a/pipelex/reporting/reporting_manager.py+++ b/pipelex/reporting/reporting_manager.py@@ -1,7 +1,7 @@from collections.abc import Sequencefrom dataclasses import dataclassfrom datetime import datetime, timezone-from typing import TYPE_CHECKING+from pathlib import Pathfrom pydantic import Field, RootModelfrom typing_extensions import override@@ -33,9 +33,6 @@ try:except ImportError:_BotoClientError = None # type: ignore[assignment, misc]-if TYPE_CHECKING:- from pathlib import Path-@dataclassclass _EventLogContext:@@ -369,7 +366,7 @@ class ReportingManager(ReportingProtocol):def generate_report(self, pipeline_run_id: str | None = None, print_to_console: bool = True):is_csv_enabled = self._reporting_config.is_generate_cost_report_file_enabledif is_csv_enabled:- ensure_path(self._reporting_config.cost_report_dir_path)+ ensure_path(Path(self._reporting_config.cost_report_dir_path))registries_to_process: dict[str, UsageRegistry] = {}if pipeline_run_id:@@ -381,7 +378,7 @@ class ReportingManager(ReportingProtocol):cost_report_file_path: Path | None = Noneif is_csv_enabled:cost_report_file_path = get_incremental_file_path(- base_path=self._reporting_config.cost_report_dir_path,+ base_path=Path(self._reporting_config.cost_report_dir_path),base_name=self._reporting_config.cost_report_base_name,extension=self._reporting_config.cost_report_extension,)diff --git a/pipelex/system/configuration/config_loader.py b/pipelex/system/configuration/config_loader.pyindex c226019dd..51a522a33 100644--- a/pipelex/system/configuration/config_loader.py+++ b/pipelex/system/configuration/config_loader.py@@ -119,22 +119,22 @@ class ConfigLoader:@propertydef backends_file_path(self) -> Path:"""Resolve backends.toml from project dir or global dir."""- return self.resolve_config_file(str(Path(INFERENCE_DIR_NAME) / BACKENDS_FILE_NAME))+ return self.resolve_config_file(f"{INFERENCE_DIR_NAME}/{BACKENDS_FILE_NAME}")@propertydef backends_dir_path(self) -> Path:"""Resolve backends/ directory from project dir or global dir."""- return self.resolve_config_file(str(Path(INFERENCE_DIR_NAME) / BACKENDS_DIR_NAME))+ return self.resolve_config_file(f"{INFERENCE_DIR_NAME}/{BACKENDS_DIR_NAME}")@propertydef routing_profiles_file_path(self) -> Path:"""Resolve routing_profiles.toml from project dir or global dir."""- return self.resolve_config_file(str(Path(INFERENCE_DIR_NAME) / ROUTING_PROFILES_FILE_NAME))+ return self.resolve_config_file(f"{INFERENCE_DIR_NAME}/{ROUTING_PROFILES_FILE_NAME}")@propertydef model_decks_dir_path(self) -> Path:"""Resolve model decks directory from project dir or global dir."""- return self.resolve_config_file(str(Path(INFERENCE_DIR_NAME) / MODEL_DECKS_DIR_NAME))+ return self.resolve_config_file(f"{INFERENCE_DIR_NAME}/{MODEL_DECKS_DIR_NAME}")def ensure_global_config_exists(self) -> None:"""Create the global ~/.pipelex/ directory with kit template files if it doesn't exist."""diff --git a/pipelex/system/registries/class_registry_utils.py b/pipelex/system/registries/class_registry_utils.pyindex 52a375cc3..63bdd74f7 100644--- a/pipelex/system/registries/class_registry_utils.py+++ b/pipelex/system/registries/class_registry_utils.py@@ -1,6 +1,7 @@import inspectimport sysimport warnings+from pathlib import Pathfrom typing import Anyfrom pipelex import log@@ -19,7 +20,7 @@ class ClassRegistryUtils:@classmethoddef register_classes_in_file(cls,- file_path: str,+ file_path: Path,base_class: type[Any] | None,is_include_imported: bool,) -> None:@@ -38,11 +39,11 @@ class ClassRegistryUtils:@classmethoddef register_classes_in_folder(cls,- folder_path: str,+ folder_path: Path,base_class: type[Any] | None = None,is_recursive: bool = True,is_include_imported: bool = False,- force_exclude_dirs: list[str] | None = None,+ force_exclude_dirs: list[Path] | None = None,) -> None:"""Registers all classes in Python files within folders that are subclasses of base_class.If base_class is None, registers all classes.@@ -59,12 +60,13 @@ class ClassRegistryUtils:dir_path=folder_path,pattern="*.py",is_recursive=is_recursive,- excluded_dirs=list(get_config().pipelex.scan_config.excluded_dirs) + (force_exclude_dirs or []),+ excluded_dirs=list(get_config().pipelex.scan_config.excluded_dirs)+ + [str(force_exclude_dir) for force_exclude_dir in (force_exclude_dirs or [])],)for python_file in python_files:cls.register_classes_in_file(- file_path=str(python_file),+ file_path=python_file,base_class=base_class,is_include_imported=is_include_imported,)@@ -72,8 +74,8 @@ class ClassRegistryUtils:@classmethoddef import_modules_in_folder(cls,- folder_path: str,- force_include_dirs: list[str] | None = None,+ folder_path: Path,+ force_include_dirs: list[Path] | None = None,is_recursive: bool = True,base_class_names: list[str] | None = None,) -> None:@@ -100,7 +102,7 @@ class ClassRegistryUtils:pattern="*.py",is_recursive=is_recursive,excluded_dirs=list(get_config().pipelex.scan_config.excluded_dirs),- force_include_dirs=force_include_dirs,+ force_include_dirs=[str(force_include_dir) for force_include_dir in force_include_dirs] if force_include_dirs is not None else None,)for python_file in python_files:@@ -108,12 +110,12 @@ class ClassRegistryUtils:if base_class_names is not None:# Use AST-based import to avoid executing modules without relevant classesimport_module_from_file_if_has_classes(- str(python_file),+ python_file,base_class_names=base_class_names,)else:# Import all modules regardless of content- import_module_from_file(str(python_file))+ import_module_from_file(python_file)except ModuleFileError:# Expected: file validation issues (directories with .py extension, etc.)# log.verbose(f"Skipping file {python_file}: {e}")diff --git a/pipelex/system/registries/func_registry_utils.py b/pipelex/system/registries/func_registry_utils.pyindex d9f52547f..5aee824e1 100644--- a/pipelex/system/registries/func_registry_utils.py+++ b/pipelex/system/registries/func_registry_utils.py@@ -2,6 +2,7 @@ import importlibimport inspectimport pkgutilfrom collections.abc import Callable+from pathlib import Pathfrom typing import Anyfrom pipelex import log@@ -73,8 +74,8 @@ class FuncRegistryUtils:@classmethoddef register_funcs_in_folder(cls,- folder_path: str,- force_include_dirs: list[str] | None = None,+ folder_path: Path,+ force_include_dirs: list[Path] | None = None,is_recursive: bool = True,) -> None:"""Discovers and attempts to register all functions in Python files within a folder.@@ -101,16 +102,16 @@ class FuncRegistryUtils:pattern="*.py",is_recursive=is_recursive,excluded_dirs=list(get_config().pipelex.scan_config.excluded_dirs),- force_include_dirs=force_include_dirs,+ force_include_dirs=[str(force_include_dir) for force_include_dir in force_include_dirs] if force_include_dirs is not None else None,)for python_file in python_files:- cls._register_funcs_in_file(file_path=str(python_file))+ cls._register_funcs_in_file(file_path=python_file)@classmethoddef _register_funcs_in_file(cls,- file_path: str,+ file_path: Path,) -> None:"""Processes a Python file to find and register eligible @pipe_func decorated functions.@@ -155,7 +156,7 @@ class FuncRegistryUtils:func_registry.register_ineligible_function(func=func,reason=eligibility_error,- source_file=file_path,+ source_file=str(file_path),)log.warning(f"Function '{func_name}' in '{file_path}' has @pipe_func() decorator but is not eligible: {eligibility_error}")except ModuleFileError:diff --git a/pipelex/tools/misc/base64_utils.py b/pipelex/tools/misc/base64_utils.pyindex 29e574549..cbb82870d 100644--- a/pipelex/tools/misc/base64_utils.py+++ b/pipelex/tools/misc/base64_utils.py@@ -1,20 +1,18 @@import base64--import aiofiles+from pathlib import Pathfrom pipelex.tools.misc.file_fetch_utils import fetch_file_from_url_httpxfrom pipelex.tools.misc.file_utils import load_binary_asyncfrom pipelex.tools.misc.filetype_utils import FileType, detect_file_type_from_bytes-async def load_binary_as_base64(path: str) -> str:+async def load_binary_as_base64(path: Path) -> str:"""Load a file and return its contents as a base64-encoded string."""- async with aiofiles.open(path, "rb") as fp: # pyright: ignore[reportUnknownMemberType]- data_bytes = await fp.read()- return base64.b64encode(data_bytes).decode("ascii")+ data_bytes = await load_binary_async(path=path)+ return base64.b64encode(data_bytes).decode("ascii")-async def make_base64_url_from_path(path: str) -> str:+async def make_base64_url_from_path(path: Path) -> str:"""Create a data: URL from a local file path."""raw_bytes = await load_binary_async(path=path)base64_data = base64.b64encode(raw_bytes).decode("ascii")diff --git a/pipelex/tools/misc/file_utils.py b/pipelex/tools/misc/file_utils.pyindex b3522f159..0d9f47b09 100644--- a/pipelex/tools/misc/file_utils.py+++ b/pipelex/tools/misc/file_utils.py@@ -14,28 +14,28 @@ MAX_FILE_PATH_LENGTH = 4096########################################################-def save_bytes_to_binary_file(file_path: str, byte_data: bytes, create_directory: bool = False) -> str:+def save_bytes_to_binary_file(file_path: Path, byte_data: bytes, create_directory: bool = False) -> Path:"""Write binary data to a file.Args:- file_path (str): Path where the binary data will be saved+ file_path (Path): Path where the binary data will be savedbyte_data (bytes): Binary data to be writtencreate_directory (bool, optional): Whether to create the directory if it doesn't exist.Defaults to False.Returns:- str: Path to the saved file+ Path: Path to the saved file"""# Ensure the directory existsif create_directory:- ensure_directory_exists(os.path.dirname(file_path))+ ensure_directory_exists(file_path.parent)- Path(file_path).write_bytes(byte_data)+ file_path.write_bytes(byte_data)return file_path-def save_text_to_path(text: str, path: str, create_directory: bool = False):+def save_text_to_path(text: str, path: Path, create_directory: bool = False):"""Writes text content to a file at the specified path.This function opens a file in write mode and writes the provided text to it.@@ -43,7 +43,7 @@ def save_text_to_path(text: str, path: str, create_directory: bool = False):Args:text (str): The text content to write to the file.- path (str): The file path where the content should be saved.+ path (Path): The file path where the content should be saved.create_directory (bool, optional): Whether to create the directory if it doesn't exist.Defaults to False.@@ -52,21 +52,20 @@ def save_text_to_path(text: str, path: str, create_directory: bool = False):"""if create_directory:- directory = os.path.dirname(path)- if directory:- ensure_directory_exists(directory)+ directory = path.parent+ ensure_directory_exists(directory)- Path(path).write_text(text, encoding="utf-8")+ path.write_text(text, encoding="utf-8")-def load_text_from_path(path: str) -> str:+def load_text_from_path(path: Path) -> str:"""Reads and returns the entire contents of a text file.This function opens a file in text mode using UTF-8 encoding and readsits entire contents into a string.Args:- path (str): The file path to read from.+ path (Path): The file path to read from.Returns:str: The complete contents of the file as a string.@@ -75,34 +74,32 @@ def load_text_from_path(path: str) -> str:FileNotFoundError: If the file does not exist."""- with open(path, encoding="utf-8") as file:- return file.read()+ return path.read_text(encoding="utf-8")-def failable_load_text_from_path(path: str) -> str | None:+def failable_load_text_from_path(path: Path) -> str | None:"""Attempts to read a text file, returning None if the file doesn't exist.This function is a safer version of load_text_from_path that handles missing filesgracefully by returning None instead of raising an error.Args:- path (str): The file path to read from.+ path (Path): The file path to read from.Returns:Optional[str]: The complete contents of the file as a string, or None if the file doesn't exist."""- if not path_exists(path):+ if not path.exists():return Nonereturn load_text_from_path(path)-def load_binary(path: str) -> bytes:- with open(path, "rb") as file_pointer:- return file_pointer.read()+def load_binary(path: Path) -> bytes:+ return path.read_bytes()-async def load_binary_async(path: str) -> bytes:+async def load_binary_async(path: Path) -> bytes:async with aiofiles.open(path, "rb") as fp: # pyright: ignore[reportUnknownMemberType]return await fp.read()@@ -112,34 +109,32 @@ async def load_binary_async(path: str) -> bytes:########################################################-def copy_file(source_path: str, target_path: str, overwrite: bool = True) -> None:+def copy_file(source_path: Path, target_path: Path, overwrite: bool = True) -> None:"""Copies a file from the source path to the target path.Creates any necessary parent directories for the target path if they don't exist.Args:- source_path (str): The path to the source file.- target_path (str): The path to the target file.+ source_path (Path): The path to the source file.+ target_path (Path): The path to the target file.overwrite (bool, optional): Whether to overwrite existing files. Defaults to True."""# Ensure the target directory exists- target_dir = os.path.dirname(target_path)- if target_dir:- ensure_directory_exists(target_dir)+ ensure_directory_exists(target_path.parent)- if not os.path.exists(target_path) or overwrite:+ if not target_path.exists() or overwrite:shutil.copy2(source_path, target_path)def copy_file_from_package(package_name: str,file_path_in_package: str,- target_path: str,+ target_path: Path,overwrite: bool = True,) -> None:"""Copies a file from a package to a target directory."""- file_path = str(importlib.resources.files(package_name).joinpath(file_path_in_package))+ file_path = Path(str(importlib.resources.files(package_name).joinpath(file_path_in_package)))copy_file(source_path=file_path,target_path=target_path,@@ -150,7 +145,7 @@ def copy_file_from_package(def copy_folder_from_package(package_name: str,folder_path_in_package: str,- target_dir: str,+ target_dir: Path,overwrite: bool = True,non_overwrite_files: list[str] | None = None,) -> None:@@ -163,71 +158,67 @@ def copy_folder_from_package(Args:package_name (str): The name of the package to copy from.folder_path_in_package (str): The path to the folder in the package to copy.- target_dir (str): The target directory to copy the folder to.+ target_dir (Path): The target directory to copy the folder to.overwrite (bool, optional): Whether to overwrite existing files. Defaults to True.non_overwrite_files (Optional[List[str]], optional): List of files to not overwrite. Defaults to None."""- os.makedirs(target_dir, exist_ok=True)+ target_dir.mkdir(parents=True, exist_ok=True)# Use importlib.resources to get the path to the package resource- data_dir_str = str(importlib.resources.files(package_name).joinpath(folder_path_in_package))+ data_dir = Path(str(importlib.resources.files(package_name).joinpath(folder_path_in_package)))- copied_files: list[str] = []+ copied_files: list[Path] = []++ if non_overwrite_files is None:+ non_overwrite_files = []# Walk through all directories and files recursively- for root, _, files in os.walk(data_dir_str):- # Create the corresponding subdirectory in the target directory- rel_path = os.path.relpath(root, data_dir_str)- target_subdir = os.path.join(target_dir, rel_path) if rel_path != "." else target_dir- os.makedirs(target_subdir, exist_ok=True)-- if non_overwrite_files is None:- non_overwrite_files = []-- # Copy all files in the current directory- for file in files:- src_file = os.path.join(root, file)- dest_file = os.path.join(target_subdir, file)-- # Check if the file exists and respect the overwrite parameter- if not Path(dest_file).exists() or (overwrite and file not in non_overwrite_files):- copy_file(- source_path=src_file,- target_path=dest_file,- overwrite=overwrite,- )- copied_files.append(dest_file)---def remove_file(file_path: str):+ for source_path in data_dir.rglob("*"):+ if not source_path.is_file():+ continue+ relative_path = source_path.relative_to(data_dir)+ dest_file = target_dir / relative_path+ dest_file.parent.mkdir(parents=True, exist_ok=True)++ # Check if the file exists and respect the overwrite parameter+ if not dest_file.exists() or (overwrite and source_path.name not in non_overwrite_files):+ copy_file(+ source_path=source_path,+ target_path=dest_file,+ overwrite=overwrite,+ )+ copied_files.append(dest_file)+++def remove_file(file_path: Path):"""Removes a file if it exists at the specified path.This function checks if a file exists before attempting to remove it,preventing errors from trying to remove non-existent files.Args:- file_path (str): The path to the file to be removed.+ file_path (Path): The path to the file to be removed.Note:This function silently succeeds if the file doesn't exist."""- if path_exists(file_path):- Path(file_path).unlink()+ if file_path.exists():+ file_path.unlink()-def remove_folder(folder_path: str) -> None:+def remove_folder(folder_path: Path) -> None:"""Removes a folder if it exists at the specified path.This function checks if a folder exists before attempting to remove it,preventing errors from trying to remove non-existent folders.Args:- folder_path (str): The path to the folder to be removed.+ folder_path (Path): The path to the folder to be removed."""- if Path(folder_path).exists():+ if folder_path.exists():shutil.rmtree(folder_path)@@ -262,8 +253,8 @@ def _reraise_walk_error(walk_error: OSError) -> None:def mirror_dir(- source_dir: str | Path,- target_dir: str | Path,+ source_dir: Path,+ target_dir: Path,exclude_files: frozenset[str] | None = None,exclude_dirs: frozenset[str] | None = None,dry_run: bool = False,@@ -278,8 +269,8 @@ def mirror_dir(are not specially preserved.Args:- source_dir (str | Path): The reference directory to mirror from. Must exist.- target_dir (str | Path): The directory brought in sync. Created if missing.+ source_dir (Path): The reference directory to mirror from. Must exist.+ target_dir (Path): The directory brought in sync. Created if missing.exclude_files (frozenset[str] | None): File basenames to skip entirely.exclude_dirs (frozenset[str] | None): Directory basenames to skip entirely.dry_run (bool): If True, report changes without touching the filesystem.@@ -332,7 +323,7 @@ def mirror_dir(if dir_to_remove.is_symlink():dir_to_remove.unlink()else:- remove_folder(str(dir_to_remove))+ remove_folder(dir_to_remove)dir_names[:] = kept_dir_namesfor file_name in sorted(file_names):if file_name in excluded_files:@@ -356,7 +347,7 @@ def mirror_dir(if relative_root.parts and not target_subdir.is_dir():created_dirs.append(relative_root.as_posix())if not dry_run:- ensure_directory_exists(str(target_subdir))+ ensure_directory_exists(target_subdir)for file_name in sorted(file_names):if file_name in excluded_files:continue@@ -371,7 +362,7 @@ def mirror_dir(elif target_file.is_file() and filecmp.cmp(str(source_file), str(target_file), shallow=False):continueif not dry_run:- copy_file(source_path=str(source_file), target_path=str(target_file))+ copy_file(source_path=source_file, target_path=target_file)copied_files.append((relative_root / file_name).as_posix())return MirrorDirResult(@@ -388,42 +379,42 @@ def mirror_dir(########################################################-def ensure_directory_exists(directory_path: str) -> None:+def ensure_directory_exists(directory_path: Path) -> None:"""Creates a directory and any necessary parent directories if they don't exist.Args:- directory_path (str): The path to the directory to create.+ directory_path (Path): The path to the directory to create."""- Path(directory_path).mkdir(parents=True, exist_ok=True)+ directory_path.mkdir(parents=True, exist_ok=True)-def ensure_path(path: str) -> bool:+def ensure_path(path: Path) -> bool:"""Ensures a directory exists at the specified path, creating it if necessary.This function checks if a directory exists at the given path. If it doesn't exist,it creates the directory and any necessary parent directories.Args:- path (str): The path where the directory should exist.+ path (Path): The path where the directory should exist.Returns:bool: True if the directory was created, False if it already existed."""- if Path(path).exists():+ if path.exists():return False- Path(path).mkdir(parents=True, exist_ok=True)+ path.mkdir(parents=True, exist_ok=True)return True-def ensure_directory_for_file_path(file_path: str) -> None:+def ensure_directory_for_file_path(file_path: Path) -> None:"""Ensures a directory exists for the specified file path.Args:- file_path (str): The path to the file.+ file_path (Path): The path to the file."""- ensure_directory_exists(os.path.dirname(file_path))+ ensure_directory_exists(file_path.parent)def path_exists(path_str: str | Path) -> bool:@@ -442,7 +433,7 @@ def path_exists(path_str: str | Path) -> bool:return Path(path_str).exists()-def get_incremental_directory_path(base_path: str, base_name: str, start_at: int = 1) -> str:+def get_incremental_directory_path(base_path: Path, base_name: str, start_at: int = 1) -> Path:"""Generates a unique directory path by incrementing a counter until an unused path is found.This function creates a directory path in the format 'base_path/base_name_XX' where XX@@ -450,18 +441,18 @@ def get_incremental_directory_path(base_path: str, base_name: str, start_at: intThe directory is then created at this path.Args:- base_path (str): The parent directory where the new directory will be created.+ base_path (Path): The parent directory where the new directory will be created.base_name (str): The base name for the directory (will be appended with _XX).start_at (int, optional): The number to start counting from. Defaults to 1.Returns:- str: The path to the newly created directory.+ Path: The path to the newly created directory."""counter = start_atwhile True:- tested_path = f"{base_path}/{base_name}_%02d" % counter- if not path_exists(tested_path):+ tested_path = base_path / f"{base_name}_{counter:02d}"+ if not tested_path.exists():breakcounter += 1ensure_path(tested_path)@@ -469,7 +460,7 @@ def get_incremental_directory_path(base_path: str, base_name: str, start_at: intdef get_incremental_file_path(- base_path: str,+ base_path: Path,base_name: str,extension: str,start_at: int = 1,@@ -482,7 +473,7 @@ def get_incremental_file_path(Unlike get_incremental_directory_path, this function only generates the path and does not create the file.Args:- base_path (str): The directory where the file path will be generated.+ base_path (Path): The directory where the file path will be generated.base_name (str): The base name for the file (will be appended with _XX).extension (str): The file extension (without the dot).start_at (int, optional): The number to start counting from. Defaults to 1.@@ -494,18 +485,18 @@ def get_incremental_file_path("""if avoid_suffix_if_possible:# try without adding the suffix- tested_path = f"{base_path}/{base_name}.{extension}"- if not path_exists(tested_path):- return Path(tested_path)+ tested_path = base_path / f"{base_name}.{extension}"+ if not tested_path.exists():+ return tested_path# we must add a number to the base namecounter = start_atwhile True:- tested_path = f"{base_path}/{base_name}_%02d.{extension}" % counter- if not path_exists(tested_path):+ tested_path = base_path / f"{base_name}_{counter:02d}.{extension}"+ if not tested_path.exists():breakcounter += 1- return Path(tested_path)+ return tested_path########################################################@@ -514,7 +505,7 @@ def get_incremental_file_path(def find_files_in_dir(- dir_path: str,+ dir_path: Path,pattern: str,is_recursive: bool = True,excluded_dirs: list[str] | None = None,@@ -534,7 +525,7 @@ def find_files_in_dir(List of matching Path objects"""- path = Path(dir_path)+ path = dir_pathfiles: list[Path] = []filtered_files: list[Path] = []# Sort results for consistent ordering across platforms and Python versions.diff --git a/pipelex/tools/misc/filetype_utils.py b/pipelex/tools/misc/filetype_utils.pyindex 6910aa6ca..7442a73b2 100644--- a/pipelex/tools/misc/filetype_utils.py+++ b/pipelex/tools/misc/filetype_utils.py@@ -35,7 +35,7 @@ class FileType(BaseModel):mime: str-def detect_file_type_from_path(path: str | Path) -> FileType:+def detect_file_type_from_path(path: Path) -> FileType:"""Detect the file type of a file at a given path.Args:diff --git a/pipelex/tools/misc/json_utils.py b/pipelex/tools/misc/json_utils.pyindex 7d8d1a3cb..117faf9a3 100644--- a/pipelex/tools/misc/json_utils.py+++ b/pipelex/tools/misc/json_utils.py@@ -127,7 +127,7 @@ def json_str(some_object: Any, title: str | None = None, is_spaced: bool = Falsedef save_as_json_to_path(object_to_save: Any,- path: str,+ path: Path,indent: int | None = 4,is_warning_enabled: bool = True,create_directory: bool = False,@@ -139,7 +139,7 @@ def save_as_json_to_path(Args:object_to_save (Any): The Python object to be saved as JSON. Can be any JSON-serializable object.- path (str): The file path where the JSON file will be saved.+ path (Path): The file path where the JSON file will be saved.indent (int | None, optional): Number of spaces for JSON formatting indentation. Defaults to 4.is_warning_enabled (bool, optional): Whether to show warnings during JSON purification. Defaults to True.create_directory (bool, optional): Whether to create the directory if it doesn't exist. Defaults to False.@@ -152,14 +152,14 @@ def save_as_json_to_path(save_text_to_path(json_string, path, create_directory=create_directory)-def load_json_from_path(path: str) -> JsonContent:+def load_json_from_path(path: Path) -> JsonContent:"""Loads and parses a JSON file from the specified path.This function reads a JSON file and returns its contents as a Python object.The file is read using UTF-8 encoding.Args:- path (str): The file path to the JSON file to be loaded.+ path (Path): The file path to the JSON file to be loaded.Returns:JsonContent: The parsed JSON content as a Python object (can be a dict, list, string, number, bool, or None).@@ -169,19 +169,18 @@ def load_json_from_path(path: str) -> JsonContent:json.JSONDecodeError: If the file contains invalid JSON."""- with open(path, encoding="utf-8") as file:- json_content: JsonContent = json.load(file)- return json_content+ json_content: JsonContent = json.loads(path.read_text(encoding="utf-8"))+ return json_content-def load_json_dict_from_path(path: str) -> dict[str, Any]:+def load_json_dict_from_path(path: Path) -> dict[str, Any]:"""Loads a JSON file and ensures it contains a dictionary.This function reads a JSON file and verifies that its content is a dictionary.It uses load_json_from_path internally and adds type checking.Args:- path (str): The file path to the JSON file to be loaded.+ path (Path): The file path to the JSON file to be loaded.Returns:Dict[str, Any]: The parsed JSON content as a Python dictionary.@@ -199,14 +198,14 @@ def load_json_dict_from_path(path: str) -> dict[str, Any]:return json_content-def load_json_list_from_path(path: str) -> list[Any]:+def load_json_list_from_path(path: Path) -> list[Any]:"""Loads a JSON file and ensures it contains a list.This function reads a JSON file and verifies that its content is a list.It uses load_json_from_path internally and adds type checking.Args:- path (str): The file path to the JSON file to be loaded.+ path (Path): The file path to the JSON file to be loaded.Returns:List[Any]: The parsed JSON content as a Python list.diff --git a/pipelex/tools/misc/toml_sync.py b/pipelex/tools/misc/toml_sync.pyindex ce9d98efa..98581081c 100644--- a/pipelex/tools/misc/toml_sync.py+++ b/pipelex/tools/misc/toml_sync.py@@ -2,7 +2,7 @@from __future__ import annotations-from typing import Any, cast+from typing import TYPE_CHECKING, Any, castfrom pydantic import BaseModel, Fieldfrom tomlkit import TOMLDocument@@ -11,6 +11,9 @@ from tomlkit.items import Item, Tablefrom pipelex.tools.misc.toml_utils import load_toml_with_tomlkit, save_toml_to_pathfrom pipelex.tools.typing.pydantic_utils import empty_list_factory_of+if TYPE_CHECKING:+ from pathlib import Path+class TomlKeyChange(BaseModel):"""Represents a single key change during TOML sync."""@@ -142,7 +145,7 @@ def collect_leaf_key_paths(doc: TOMLDocument | Table | dict[str, Any], prefix: sreturn paths-def sync_toml_values(source_path: str, target_path: str, dry_run: bool = False) -> TomlSyncResult:+def sync_toml_values(source_path: Path, target_path: Path, dry_run: bool = False) -> TomlSyncResult:"""Sync values from source TOML to target TOML, preserving target's structure and comments.For each leaf key in the target:diff --git a/pipelex/tools/typing/module_inspector.py b/pipelex/tools/typing/module_inspector.pyindex a0ff7ff9c..4f33fd091 100644--- a/pipelex/tools/typing/module_inspector.py+++ b/pipelex/tools/typing/module_inspector.py@@ -1,7 +1,6 @@import astimport importlib.utilimport inspect-import osimport sysfrom pathlib import Pathfrom typing import Any@@ -9,7 +8,7 @@ from typing import Anyfrom pipelex.tools.typing.exceptions import ModuleFileError-def import_module_from_file(file_path: str) -> Any:+def import_module_from_file(file_path: Path) -> Any:"""Imports a module from a file path.Args:@@ -23,13 +22,12 @@ def import_module_from_file(file_path: str) -> Any:"""# Validate that the file is a Python file- if not file_path.endswith(".py"):+ if file_path.suffix != ".py":msg = f"File {file_path} is not a Python file (must end with .py)"raise ModuleFileError(msg)# Validate that the path exists and is a file, not a directory- path = Path(file_path)- if path.exists() and not path.is_file():+ if file_path.exists() and not file_path.is_file():msg = f"Path {file_path} exists but is not a file (it may be a directory)"raise ModuleFileError(msg)@@ -41,7 +39,7 @@ def import_module_from_file(file_path: str) -> Any:return sys.modules[module_name]# Use importlib.util to load the module from file path- spec = importlib.util.spec_from_file_location(module_name, file_path)+ spec = importlib.util.spec_from_file_location(module_name, str(file_path))if spec is None or spec.loader is None:msg = f"Could not load module from {file_path}"raise ModuleFileError(msg)@@ -57,7 +55,7 @@ def import_module_from_file(file_path: str) -> Any:return module-def convert_file_path_to_module_path(file_path: str) -> str:+def convert_file_path_to_module_path(file_path: Path) -> str:"""Convert a file path to a valid module identifier.The module name doesn't need to match the actual package structure since@@ -71,7 +69,7 @@ def convert_file_path_to_module_path(file_path: str) -> str:A unique, valid Python module name derived from the absolute file path"""# Convert to absolute path for uniqueness and consistency- abs_path = os.path.abspath(file_path)+ abs_path = str(file_path.resolve())# Remove .py extensionmodule_path = abs_path.removesuffix(".py")@@ -99,7 +97,7 @@ def convert_file_path_to_module_path(file_path: str) -> str:return result-def find_class_names_in_file(file_path: str, base_class_names: list[str] | None = None) -> list[str]:+def find_class_names_in_file(file_path: Path, base_class_names: list[str] | None = None) -> list[str]:"""Find class names in a Python file without executing it using AST parsing.This is useful when you want to discover classes without running module-level code.@@ -118,20 +116,19 @@ def find_class_names_in_file(file_path: str, base_class_names: list[str] | None"""# Validate that the file is a Python file- if not file_path.endswith(".py"):+ if file_path.suffix != ".py":msg = f"File {file_path} is not a Python file (must end with .py)"raise ModuleFileError(msg)# Validate that the path exists and is a file- path = Path(file_path)- if not path.exists() or not path.is_file():+ if not file_path.exists() or not file_path.is_file():msg = f"Path {file_path} does not exist or is not a file"raise ModuleFileError(msg)try:# Read and parse the file- source = Path(file_path).read_text(encoding="utf-8")- tree = ast.parse(source, filename=file_path)+ source = file_path.read_text(encoding="utf-8")+ tree = ast.parse(source, filename=str(file_path))except (OSError, SyntaxError, ValueError) as exc:msg = f"Failed to parse {file_path}: {exc}"raise ModuleFileError(msg) from exc@@ -162,7 +159,7 @@ def find_class_names_in_file(file_path: str, base_class_names: list[str] | Nonedef find_decorated_function_names_in_file(- file_path: str,+ file_path: Path,decorator_names: list[str],) -> list[str]:"""Find function names decorated with specific decorators without executing the file.@@ -181,20 +178,19 @@ def find_decorated_function_names_in_file("""# Validate that the file is a Python file- if not file_path.endswith(".py"):+ if file_path.suffix != ".py":msg = f"File {file_path} is not a Python file (must end with .py)"raise ModuleFileError(msg)# Validate that the path exists and is a file- path = Path(file_path)- if not path.exists() or not path.is_file():+ if not file_path.exists() or not file_path.is_file():msg = f"Path {file_path} does not exist or is not a file"raise ModuleFileError(msg)try:# Read and parse the file- source = Path(file_path).read_text(encoding="utf-8")- tree = ast.parse(source, filename=file_path)+ source = file_path.read_text(encoding="utf-8")+ tree = ast.parse(source, filename=str(file_path))except (OSError, SyntaxError, ValueError) as exc:msg = f"Failed to parse {file_path}: {exc}"raise ModuleFileError(msg) from exc@@ -227,7 +223,7 @@ def find_decorated_function_names_in_file(def import_module_from_file_if_has_decorated_functions(- file_path: str,+ file_path: Path,decorator_names: list[str],) -> Any | None:"""Import a module only if it contains functions with specific decorators.@@ -259,7 +255,7 @@ def import_module_from_file_if_has_decorated_functions(def import_module_from_file_if_has_classes(- file_path: str,+ file_path: Path,base_class_names: list[str] | None = None,) -> Any | None:"""Import a module only if it contains classes (optionally filtered by base class).diff --git a/pipelex/tools/uri/uri_resolver.py b/pipelex/tools/uri/uri_resolver.pyindex 6dbc64e55..824888a09 100644--- a/pipelex/tools/uri/uri_resolver.py+++ b/pipelex/tools/uri/uri_resolver.py@@ -186,7 +186,7 @@ async def make_base64_url_from_any_uri(case ResolvedHttpUrl():base64_url = await make_base64_url_from_http_url(url=resolved_uri.url)case ResolvedLocalPath():- base64_url = await make_base64_url_from_path(path=resolved_uri.path)+ base64_url = await make_base64_url_from_path(path=Path(resolved_uri.path))case ResolvedPipelexStorage():if storage_provider is None:msg = f"Cannot convert pipelex-storage:// URI to base64 without a storage provider: {uri}"diff --git a/pipelex/tracing/ndjson_event_log.py b/pipelex/tracing/ndjson_event_log.pyindex ba51e3247..025005790 100644--- a/pipelex/tracing/ndjson_event_log.py+++ b/pipelex/tracing/ndjson_event_log.py@@ -5,7 +5,6 @@ One JSON event per line, one file per workflow, organized by pipeline run:"""import json-import osimport shutilimport threadingfrom pathlib import Path@@ -41,8 +40,8 @@ class NdjsonEventLog(EventLogProtocol):DynamoDB backend for fully separated hosts."""- def __init__(self, traces_dir: str, writer_id: str = "primary") -> None:- self._traces_dir = traces_dir+ def __init__(self, traces_dir: str | Path, writer_id: str = "primary") -> None:+ self._traces_dir = Path(traces_dir)self._file_handles: dict[tuple[str, str, str], IO[str]] = {}self._sequence: int = 0self._sequence_lock = threading.Lock()@@ -105,9 +104,9 @@ class NdjsonEventLog(EventLogProtocol):with self._handles_lock:handle = self._file_handles.get(cache_key)if handle is None:- run_dir = os.path.join(self._traces_dir, event.pipeline_run_id)- os.makedirs(run_dir, exist_ok=True)- file_path = os.path.join(run_dir, self._file_name_for(event.workflow_id, event.writer_id))+ run_dir = self._traces_dir / event.pipeline_run_id+ run_dir.mkdir(parents=True, exist_ok=True)+ file_path = run_dir / self._file_name_for(event.workflow_id, event.writer_id)handle = open(file_path, "a", encoding="utf-8") # noqa: SIM115self._file_handles[cache_key] = handle@@ -127,18 +126,17 @@ class NdjsonEventLog(EventLogProtocol):Corrupt lines (truncated JSON from crash-mid-write) are skipped witha warning log."""- run_dir = os.path.join(self._traces_dir, pipeline_run_id)- if not os.path.isdir(run_dir):+ run_dir = self._traces_dir / pipeline_run_id+ if not run_dir.is_dir():return []- ndjson_files = sorted(Path(run_dir).glob("*.ndjson"))+ ndjson_files = sorted(run_dir.glob("*.ndjson"))seen: set[tuple[str, str, str, int]] = set()events: list[TraceEvent] = []for ndjson_path in ndjson_files:- file_path = str(ndjson_path)- with open(file_path, encoding="utf-8") as fhandle:+ with open(ndjson_path, encoding="utf-8") as fhandle:for line_number, raw_line in enumerate(fhandle, start=1):stripped = raw_line.strip()if not stripped:@@ -146,7 +144,7 @@ class NdjsonEventLog(EventLogProtocol):try:event = _any_trace_event_adapter.validate_json(stripped)except (ValidationError, json.JSONDecodeError) as exc:- log.warning(f"Skipping corrupt line in {file_path}:{line_number} — {exc}")+ log.warning(f"Skipping corrupt line in {ndjson_path}:{line_number} — {exc}")continuededup_key = (event.workflow_id, event.writer_id, type(event).__name__, event.sequence)@@ -173,8 +171,8 @@ class NdjsonEventLog(EventLogProtocol):self._file_handles[cache_key].close()del self._file_handles[cache_key]- run_dir = os.path.join(self._traces_dir, pipeline_run_id)- if os.path.isdir(run_dir):+ run_dir = self._traces_dir / pipeline_run_id+ if run_dir.is_dir():shutil.rmtree(run_dir)@overridediff --git a/tests/e2e/pipelex/graph/test_graph_renderers_from_json.py b/tests/e2e/pipelex/graph/test_graph_renderers_from_json.pyindex e10e2dbc0..24271f3f6 100644--- a/tests/e2e/pipelex/graph/test_graph_renderers_from_json.py+++ b/tests/e2e/pipelex/graph/test_graph_renderers_from_json.py@@ -28,8 +28,8 @@ def _get_next_output_folder() -> Path:Creates folders like: temp/test_outputs/graph_renderers/run_01, run_02, etc."""- base_dir = str(Path(TEST_OUTPUTS_DIR) / "graph_renderers")- return Path(get_incremental_directory_path(base_dir, "run"))+ base_dir = Path(TEST_OUTPUTS_DIR) / "graph_renderers"+ return get_incremental_directory_path(base_dir, "run")@pytest.mark.asyncio(loop_scope="class")@@ -66,7 +66,7 @@ class TestGraphRenderersFromJson:json_path = Path(graph_json_path)assert json_path.exists(), f"Graph JSON file not found: {json_path}"- json_str = load_text_from_path(str(json_path))+ json_str = load_text_from_path(json_path)graph_spec = GraphSpec.model_validate_json(json_str)assert graph_spec is not Noneassert len(graph_spec.nodes) > 0diff --git a/tests/e2e/pipelex/graph/test_graph_with_full_data.py b/tests/e2e/pipelex/graph/test_graph_with_full_data.pyindex d37058b77..a17f8d1a2 100644--- a/tests/e2e/pipelex/graph/test_graph_with_full_data.py+++ b/tests/e2e/pipelex/graph/test_graph_with_full_data.py@@ -32,8 +32,8 @@ def _get_next_output_folder() -> Path:Creates folders like: temp/test_outputs/graph_full_data/run_01, run_02, etc."""- base_dir = str(Path(TEST_OUTPUTS_DIR) / "graph_full_data")- return Path(get_incremental_directory_path(base_dir, "run"))+ base_dir = Path(TEST_OUTPUTS_DIR) / "graph_full_data"+ return get_incremental_directory_path(base_dir, "run")async def _save_graph_outputs(graph_spec: GraphSpec, output_dir: Path) -> dict[str, int]:@@ -55,7 +55,7 @@ async def _save_graph_outputs(graph_spec: GraphSpec, output_dir: Path) -> dict[s# Save graph.jsongraph_json_path = output_dir / "graph.json"graph_json = graph_spec.to_json()- save_text_to_path(graph_json, str(graph_json_path))+ save_text_to_path(graph_json, graph_json_path)log.info(f"Saved graph.json to: {graph_json_path}")# Generate and save mermaid filesdiff --git a/tests/e2e/pipelex/graph/test_mermaid_from_json.py b/tests/e2e/pipelex/graph/test_mermaid_from_json.pyindex 0a619d829..fc680ad41 100644--- a/tests/e2e/pipelex/graph/test_mermaid_from_json.py+++ b/tests/e2e/pipelex/graph/test_mermaid_from_json.py@@ -27,8 +27,8 @@ def _get_next_output_folder() -> Path:Creates folders like: temp/test_outputs/mermaid_from_json/run_01, run_02, etc."""- base_dir = str(Path(TEST_OUTPUTS_DIR) / "mermaid_from_json")- return Path(get_incremental_directory_path(base_dir, "run"))+ base_dir = Path(TEST_OUTPUTS_DIR) / "mermaid_from_json"+ return get_incremental_directory_path(base_dir, "run")@pytest.mark.asyncio(loop_scope="class")@@ -60,7 +60,7 @@ class TestMermaidFromJson:json_path = Path(graph_json_path)assert json_path.exists(), f"Graph JSON file not found: {json_path}"- json_str = load_text_from_path(str(json_path))+ json_str = load_text_from_path(json_path)graph_spec = GraphSpec.model_validate_json(json_str)# Verify graph loaded correctly@@ -119,7 +119,7 @@ class TestMermaidFromJson:"""Test that mermaidflow Mermaid combines orchestration and dataflow elements."""_ = topic # Used for test identification- json_str = load_text_from_path(graph_json_path)+ json_str = load_text_from_path(Path(graph_json_path))graph_spec = GraphSpec.model_validate_json(json_str)graph_config = self._get_graph_config_with_data()mermaidflow = MermaidflowFactory.make_from_graphspec(graph_spec, graph_config)diff --git a/tests/e2e/pipelex/graph/test_reactflow_from_json.py b/tests/e2e/pipelex/graph/test_reactflow_from_json.pyindex 6bd710764..e4f3ecb14 100644--- a/tests/e2e/pipelex/graph/test_reactflow_from_json.py+++ b/tests/e2e/pipelex/graph/test_reactflow_from_json.py@@ -22,8 +22,8 @@ def _get_next_output_folder() -> Path:Creates folders like: temp/test_outputs/reactflow_from_json/run_01, run_02, etc."""- base_dir = str(Path(TEST_OUTPUTS_DIR) / "reactflow_from_json")- return Path(get_incremental_directory_path(base_dir, "run"))+ base_dir = Path(TEST_OUTPUTS_DIR) / "reactflow_from_json"+ return get_incremental_directory_path(base_dir, "run")class TestReactFlowFromJson:@@ -47,7 +47,7 @@ class TestReactFlowFromJson:json_path = Path(graph_json_path)assert json_path.exists(), f"Graph JSON file not found: {json_path}"- json_str = load_text_from_path(str(json_path))+ json_str = load_text_from_path(json_path)graph_spec = GraphSpec.model_validate_json(json_str)# Verify graph loaded correctly@@ -93,7 +93,7 @@ class TestReactFlowFromJson:_ = topic # Used for test identification# Load graph from JSON- json_str = load_text_from_path(graph_json_path)+ json_str = load_text_from_path(Path(graph_json_path))graph_spec = GraphSpec.model_validate_json(json_str)# Generate ReactFlow HTMLdiff --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 91330b2ae..02caca6fb 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@@ -20,8 +20,8 @@ from tests.e2e.pipelex.pipes.pipe_controller.pipe_batch.test_data import JokeBatdef _get_next_output_folder() -> Path:"""Get the next numbered output folder for batch graph outputs."""- base_dir = str(Path(TEST_OUTPUTS_DIR) / "pipe_batch_graph")- return Path(get_incremental_directory_path(base_dir, "run"))+ base_dir = Path(TEST_OUTPUTS_DIR) / "pipe_batch_graph"+ return get_incremental_directory_path(base_dir, "run")@pytest.mark.dry_runnable@@ -129,7 +129,7 @@ class TestPipeBatchGraph:output_dir = _get_next_output_folder()graph_json_path = output_dir / "graph.json"graph_json = graph_spec.to_json()- save_text_to_path(graph_json, str(graph_json_path))+ save_text_to_path(graph_json, graph_json_path)log.info(f"Saved graph.json to: {graph_json_path}")# Pretty print the graph summary@@ -212,21 +212,21 @@ class TestPipeBatchGraph:# Save outputs to folderoutput_dir = Path(TEST_OUTPUTS_DIR) / "joke_batch_graph"- output_dir = Path(get_incremental_directory_path(str(output_dir), "run"))+ output_dir = get_incremental_directory_path(output_dir, "run")if graph_outputs.graphspec_json:graph_json_path = output_dir / "graph.json"- save_text_to_path(graph_outputs.graphspec_json, str(graph_json_path))+ save_text_to_path(graph_outputs.graphspec_json, graph_json_path)log.info(f"Saved graph.json to: {graph_json_path}")if graph_outputs.mermaidflow_html:mermaid_path = output_dir / "mermaidflow.html"- save_text_to_path(graph_outputs.mermaidflow_html, str(mermaid_path))+ save_text_to_path(graph_outputs.mermaidflow_html, mermaid_path)log.info(f"Saved mermaidflow.html to: {mermaid_path}")if graph_outputs.reactflow_html:reactflow_path = output_dir / "reactflow.html"- save_text_to_path(graph_outputs.reactflow_html, str(reactflow_path))+ save_text_to_path(graph_outputs.reactflow_html, reactflow_path)log.info(f"Saved reactflow.html to: {reactflow_path}")# Log edge countsdiff --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 bcb485fe8..ca9af5e59 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@@ -24,8 +24,8 @@ from tests.e2e.pipelex.pipes.pipe_controller.pipe_parallel.test_data import (def _get_next_output_folder(subfolder: str) -> Path:"""Get the next numbered output folder for parallel graph outputs."""- base_dir = str(Path(TEST_OUTPUTS_DIR) / f"pipe_parallel_graph_{subfolder}")- return Path(get_incremental_directory_path(base_dir, "run"))+ base_dir = Path(TEST_OUTPUTS_DIR) / f"pipe_parallel_graph_{subfolder}"+ return get_incremental_directory_path(base_dir, "run")@pytest.mark.dry_runnable@@ -146,11 +146,11 @@ class TestPipeParallelGraph:output_dir = _get_next_output_folder("add_each")if graph_outputs.graphspec_json:- save_text_to_path(graph_outputs.graphspec_json, str(output_dir / "graph.json"))+ save_text_to_path(graph_outputs.graphspec_json, output_dir / "graph.json")if graph_outputs.mermaidflow_html:- save_text_to_path(graph_outputs.mermaidflow_html, str(output_dir / "mermaidflow.html"))+ save_text_to_path(graph_outputs.mermaidflow_html, output_dir / "mermaidflow.html")if graph_outputs.reactflow_html:- save_text_to_path(graph_outputs.reactflow_html, str(output_dir / "reactflow.html"))+ save_text_to_path(graph_outputs.reactflow_html, output_dir / "reactflow.html")pretty_print({@@ -271,13 +271,13 @@ class TestPipeParallelGraph:output_dir = _get_next_output_folder(pipe_code)if graph_outputs.graphspec_json:- save_text_to_path(graph_outputs.graphspec_json, str(output_dir / "graph.json"))+ save_text_to_path(graph_outputs.graphspec_json, output_dir / "graph.json")if graph_outputs.mermaidflow_html:- save_text_to_path(graph_outputs.mermaidflow_html, str(output_dir / "mermaidflow.html"))+ save_text_to_path(graph_outputs.mermaidflow_html, output_dir / "mermaidflow.html")if graph_outputs.mermaidflow_mmd:- save_text_to_path(graph_outputs.mermaidflow_mmd, str(output_dir / "mermaidflow.mmd"))+ save_text_to_path(graph_outputs.mermaidflow_mmd, output_dir / "mermaidflow.mmd")if graph_outputs.reactflow_html:- save_text_to_path(graph_outputs.reactflow_html, str(output_dir / "reactflow.html"))+ save_text_to_path(graph_outputs.reactflow_html, output_dir / "reactflow.html")pretty_print({diff --git a/tests/helpers/instructor_test_utils.py b/tests/helpers/instructor_test_utils.pyindex 7ce1acad1..b3c9ec972 100644--- a/tests/helpers/instructor_test_utils.py+++ b/tests/helpers/instructor_test_utils.py@@ -13,6 +13,8 @@ from typing import TYPE_CHECKING, Anyfrom instructor.core import FailedAttempt, InstructorRetryExceptionfrom pydantic import BaseModel+from pipelex.cogt.llm.llm_prompt import LLMPrompt+if TYPE_CHECKING:from pytest_mock import MockerFixture@@ -54,11 +56,17 @@ def make_llm_job(mocker: MockerFixture) -> Any:"""Return a MagicMock ``LLMJob`` skeleton suitable for ``_gen_object`` tests.The returned mock has ``applied_job_params=None`` and a ``job_params`` mock- populated with the fields ``_gen_object`` actually reads. Callers may- override individual fields as needed.+ populated with the fields ``_gen_object`` actually reads. ``llm_prompt`` is a+ real :class:`LLMPrompt` (not a MagicMock) so its ``system_text`` / ``user_text``+ don't leak auto-attributes into provider config/message construction. Callers+ may override individual fields as needed."""job = mocker.MagicMock()job.applied_job_params = None+ job.llm_prompt = LLMPrompt(+ system_text="You are a helpful test assistant.",+ user_text="Generate a structured object.",+ )job.job_params.temperature = 0.5job.job_params.max_tokens = Nonejob.job_params.reasoning_effort = Nonediff --git a/tests/integration/pipelex/cogt/image/test_pipelex_storage_image_flow.py b/tests/integration/pipelex/cogt/image/test_pipelex_storage_image_flow.pyindex 072a39897..f022769a2 100644--- a/tests/integration/pipelex/cogt/image/test_pipelex_storage_image_flow.py+++ b/tests/integration/pipelex/cogt/image/test_pipelex_storage_image_flow.py@@ -9,6 +9,7 @@ These tests verify the complete flow:"""import base64+from pathlib import Pathimport pytestimport pytest_asyncio@@ -33,7 +34,7 @@ async def storage_provider_with_test_image() -> tuple[InMemoryStorageProvider, s"""Create an in-memory storage with a real test image and return (provider, uri)."""provider = InMemoryStorageProvider()# Load a real test image- image_bytes = load_binary(path=TEST_IMAGE_PATH)+ image_bytes = load_binary(path=Path(TEST_IMAGE_PATH))key = "pipeline_run_123/generated_image.png"uri = await provider.store(data=image_bytes, key=key)return provider, uridiff --git a/tests/integration/pipelex/cogt/test_llm_vision.py b/tests/integration/pipelex/cogt/test_llm_vision.pyindex 05ea3dd2b..bf1b4ad7c 100644--- a/tests/integration/pipelex/cogt/test_llm_vision.py+++ b/tests/integration/pipelex/cogt/test_llm_vision.py@@ -1,3 +1,5 @@+from pathlib import Path+import pytestfrom pipelex import log, pretty_print@@ -47,7 +49,7 @@ class TestLLMVision:async def test_gen_text_from_vision_by_bytes(self, job_metadata: JobMetadata, llm_job_params: LLMJobParams, llm_combo: ModelCombo, topic: str, image_path: str):- base64_data = await load_binary_as_base64(path=image_path)+ base64_data = await load_binary_as_base64(path=Path(image_path))prompt_image = PromptImageBase64(base64_data=base64_data)llm_worker = get_llm_worker(llm_handle=llm_combo.handle)llm_job = LLMJobFactory.make_llm_job(diff --git a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_dry_run.py b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_dry_run.pyindex 7d611c0b9..a020ea81f 100644--- a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_dry_run.py+++ b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_dry_run.py@@ -35,7 +35,7 @@ class TestPipeSequenceDryRun:"""Test that the Discord newsletter pipeline creates correct working memory with ListContent for batched inputs."""load_test_library([Path("tests/integration/pipelex/pipes/controller/pipe_sequence")])# Load the discord channel updates data from JSON- discord_channel_updates_data = load_json_list_from_path(path="tests/data/discord_newsletter/discord_sample.json")+ discord_channel_updates_data = load_json_list_from_path(path=Path("tests/data/discord_newsletter/discord_sample.json"))# Create structured DiscordChannelUpdate objectsdiscord_channel_updates = ListContent[DiscordChannelUpdate](diff --git a/tests/integration/pipelex/tools/class_registry/test_class_registry_utils.py b/tests/integration/pipelex/tools/class_registry/test_class_registry_utils.pyindex 5d307e4f8..7af7e302a 100644--- a/tests/integration/pipelex/tools/class_registry/test_class_registry_utils.py+++ b/tests/integration/pipelex/tools/class_registry/test_class_registry_utils.py@@ -16,7 +16,7 @@ class TestClassRegistryUtilsIntegration:"""Integration test for registering StuffContent classes recursively."""class_registry = get_class_registry()ClassRegistryUtils.register_classes_in_folder(- folder_path=ClassRegistryTestCases.MODEL_FOLDER_PATH,+ folder_path=Path(ClassRegistryTestCases.MODEL_FOLDER_PATH),base_class=StuffContent,is_recursive=True,)@@ -30,7 +30,7 @@ class TestClassRegistryUtilsIntegration:"""Integration test for registering StuffContent classes non-recursively."""class_registry = get_class_registry()ClassRegistryUtils.register_classes_in_folder(- folder_path=ClassRegistryTestCases.MODEL_FOLDER_PATH,+ folder_path=Path(ClassRegistryTestCases.MODEL_FOLDER_PATH),base_class=StuffContent,is_recursive=False,)@@ -50,7 +50,7 @@ class TestClassRegistryUtilsIntegration:if class_registry.has_class(class_name):classes_before.add(class_name)- ClassRegistryUtils.register_classes_in_folder(folder_path=ClassRegistryTestCases.MODEL_FOLDER_PATH, base_class=None, is_recursive=True)+ ClassRegistryUtils.register_classes_in_folder(folder_path=Path(ClassRegistryTestCases.MODEL_FOLDER_PATH), base_class=None, is_recursive=True)# Should register all classesfor class_name in ["Class1", "Class2", "Class3", "Class4", "ClassA", "ClassB"]:@@ -64,7 +64,7 @@ class TestClassRegistryUtilsIntegration:empty_dir.mkdir()# This should not raise an error and should not register any classes- ClassRegistryUtils.register_classes_in_folder(folder_path=str(empty_dir), base_class=StuffContent, is_recursive=True)+ ClassRegistryUtils.register_classes_in_folder(folder_path=empty_dir, base_class=StuffContent, is_recursive=True)# Verify no new classes were registered (we can't easily check the exact count,# but the operation should complete without error)diff --git a/tests/integration/pipelex/tools/storage/test_generated_image_storage.py b/tests/integration/pipelex/tools/storage/test_generated_image_storage.pyindex 5dc34298b..a8a112be7 100644--- a/tests/integration/pipelex/tools/storage/test_generated_image_storage.py+++ b/tests/integration/pipelex/tools/storage/test_generated_image_storage.py@@ -7,6 +7,7 @@ compatibility with AI-generated image handling."""import base64+from pathlib import Pathimport pytestfrom pytest_mock import MockerFixture@@ -47,7 +48,7 @@ class TestGeneratedImageStorage:mocker.patch("pipelex.cogt.image.prompt_image_utils.get_storage_provider", return_value=storage_provider)# Load a real test image as bytes- image_bytes = load_binary(path=ImageTestCases.IMAGE_FILE_PATH_LOGO_TINY)+ image_bytes = load_binary(path=Path(ImageTestCases.IMAGE_FILE_PATH_LOGO_TINY))# Create GeneratedImageRawDetails with raw bytesraw_details = GeneratedImageRawDetails(diff --git a/tests/integration/pipelex/tools/storage/test_storage_provider_contract.py b/tests/integration/pipelex/tools/storage/test_storage_provider_contract.pyindex 236cadf95..4a1c5c387 100644--- a/tests/integration/pipelex/tools/storage/test_storage_provider_contract.py+++ b/tests/integration/pipelex/tools/storage/test_storage_provider_contract.py@@ -12,6 +12,8 @@ Storage Provider Contract Requirements:- public_url(uri: str) -> str | None: Must return a human-readable link or None"""+from pathlib import Path+import pytestfrom pipelex.tools.misc.file_utils import load_binary@@ -56,7 +58,7 @@ class TestStorageProviderContract:must be identical to the bytes stored."""# Use real image data for a realistic test- image_bytes = load_binary(path=ImageTestCases.IMAGE_FILE_PATH_LOGO_TINY)+ image_bytes = load_binary(path=Path(ImageTestCases.IMAGE_FILE_PATH_LOGO_TINY))key = "contract/image.png"uri = await storage_provider.store(data=image_bytes, key=key)diff --git a/tests/unit/pipelex/cli/test_init_credentials.py b/tests/unit/pipelex/cli/test_init_credentials.pyindex 72b093b84..5f48ffe4d 100644--- a/tests/unit/pipelex/cli/test_init_credentials.py+++ b/tests/unit/pipelex/cli/test_init_credentials.py@@ -103,20 +103,20 @@ class TestInitCredentials:'[anthropic]\nenabled = false\napi_key = "${ANTHROPIC_API_KEY}"\n\n'"[internal]\nenabled = true\n")- result = get_required_vars_for_enabled_backends(str(backends_toml))+ result = get_required_vars_for_enabled_backends(backends_toml)assert "OPENAI_API_KEY" in resultassert "ANTHROPIC_API_KEY" not in resultdef test_get_required_vars_returns_empty_for_no_file(self, tmp_path: Path) -> None:"""Returns empty dict when file doesn't exist."""- result = get_required_vars_for_enabled_backends(str(tmp_path / "nonexistent.toml"))+ result = get_required_vars_for_enabled_backends(tmp_path / "nonexistent.toml")assert result == {}def test_get_required_vars_maps_to_display_names(self, tmp_path: Path) -> None:"""Vars are mapped to their backend display names."""backends_toml = tmp_path / "backends.toml"backends_toml.write_text('[openai]\ndisplay_name = "OpenAI"\nenabled = true\napi_key = "${OPENAI_API_KEY}"\n\n[internal]\nenabled = true\n')- result = get_required_vars_for_enabled_backends(str(backends_toml))+ result = get_required_vars_for_enabled_backends(backends_toml)assert result["OPENAI_API_KEY"] == ["OpenAI"]def test_prompt_credentials_skips_when_all_set(self, tmp_path: Path, mocker: MockerFixture) -> None:@@ -130,7 +130,7 @@ class TestInitCredentials:)mock_prompt = mocker.patch("pipelex.cli.commands.init.credentials.Prompt.ask")mock_console: MagicMock = mocker.MagicMock()- prompt_credentials(mock_console, str(backends_toml))+ prompt_credentials(mock_console, backends_toml)# Should print "already set" message, no Prompt.ask callsmock_console.print.assert_called()mock_prompt.assert_not_called()@@ -152,7 +152,7 @@ class TestInitCredentials:return_value="sk-test-value",)mock_console: MagicMock = mocker.MagicMock()- prompt_credentials(mock_console, str(backends_toml))+ prompt_credentials(mock_console, backends_toml)# Verify .env was writtenenv_path = tmp_path / ".env"@@ -182,7 +182,7 @@ class TestInitCredentials:return_value="",)mock_console: MagicMock = mocker.MagicMock()- prompt_credentials(mock_console, str(backends_toml))+ prompt_credentials(mock_console, backends_toml)# Verify .env was NOT written (no values entered)env_path = tmp_path / ".env"@@ -207,7 +207,7 @@ class TestInitCredentials:return_value="sk-new",)mock_console: MagicMock = mocker.MagicMock()- prompt_credentials(mock_console, str(backends_toml))+ prompt_credentials(mock_console, backends_toml)result = read_env_file(env_path)assert result["EXISTING_KEY"] == "existing_value"@@ -226,5 +226,5 @@ class TestInitCredentials:)mock_prompt = mocker.patch("pipelex.cli.commands.init.credentials.Prompt.ask")mock_console: MagicMock = mocker.MagicMock()- prompt_credentials(mock_console, str(backends_toml))+ prompt_credentials(mock_console, backends_toml)mock_prompt.assert_not_called()diff --git a/tests/unit/pipelex/cogt/image/test_prompt_image_factory.py b/tests/unit/pipelex/cogt/image/test_prompt_image_factory.pyindex 19f0c41ff..1b5ab25fd 100644--- a/tests/unit/pipelex/cogt/image/test_prompt_image_factory.py+++ b/tests/unit/pipelex/cogt/image/test_prompt_image_factory.py@@ -1,3 +1,5 @@+from pathlib import Path+import pytestfrom pydantic import ValidationError@@ -39,7 +41,7 @@ class TestPromptImageFactoryDataUrl:far exceeding URL_MAX_LENGTH (2048).Before the fix, this would fail with 'URI is too long'."""- data_url = await make_base64_url_from_path(image_path)+ data_url = await make_base64_url_from_path(Path(image_path))result = PromptImageFactory.make_prompt_image(uri=data_url)diff --git a/tests/unit/pipelex/cogt/models/test_model_deck_references.py b/tests/unit/pipelex/cogt/models/test_model_deck_references.pyindex 1defeec71..b51c4f570 100644--- a/tests/unit/pipelex/cogt/models/test_model_deck_references.py+++ b/tests/unit/pipelex/cogt/models/test_model_deck_references.py@@ -93,7 +93,7 @@ class TestModelDeckReferences:known_handles: dict[str, ModelType] = {}backends_dir = config_manager.backends_dir_path- toml_files = find_files_in_dir(str(backends_dir), pattern="*.toml", is_recursive=False)+ toml_files = find_files_in_dir(backends_dir, pattern="*.toml", is_recursive=False)for toml_path in toml_files:backend_data = load_toml_from_path_if_exists(str(toml_path))if backend_data:diff --git a/tests/unit/pipelex/core/concepts/test_concept_find_image_field_paths.py b/tests/unit/pipelex/core/concepts/test_concept_find_image_field_paths.pyindex b93011bdd..169ae4515 100644--- a/tests/unit/pipelex/core/concepts/test_concept_find_image_field_paths.py+++ b/tests/unit/pipelex/core/concepts/test_concept_find_image_field_paths.py@@ -32,7 +32,7 @@ def register_test_concepts(load_test_library: Callable[[list[Path]], None]):# Register the test structure classesClassRegistryUtils.register_classes_in_file(- file_path=data.__file__,+ file_path=Path(data.__file__),base_class=StructuredContent,is_include_imported=False,)diff --git a/tests/unit/pipelex/core/stuffs/test_stuff_factory_combine_stuffs.py b/tests/unit/pipelex/core/stuffs/test_stuff_factory_combine_stuffs.pyindex e79d1f169..0803042e9 100644--- a/tests/unit/pipelex/core/stuffs/test_stuff_factory_combine_stuffs.py+++ b/tests/unit/pipelex/core/stuffs/test_stuff_factory_combine_stuffs.py@@ -1,4 +1,3 @@-import osfrom pathlib import Pathfrom typing import TYPE_CHECKING, Callable@@ -38,7 +37,7 @@ def setup_combine_concepts(load_test_library: Callable[[list[Path]], None]):"""Register structured content classes and create concepts for combine_stuffs tests."""load_test_library([Path(__file__).parent])ClassRegistryUtils.register_classes_in_file(- file_path=os.path.join(os.path.dirname(__file__), "test_stuff_factory_combine_stuffs.py"),+ file_path=Path(__file__).parent / "test_stuff_factory_combine_stuffs.py",base_class=StructuredContent,is_include_imported=False,)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 2c3ff718f..555fadbe4 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@@ -1,4 +1,3 @@-import osfrom pathlib import Pathfrom typing import Any, Callable@@ -20,7 +19,7 @@ def setup_test_concept(load_test_library: Callable[[list[Path]], None]):load_test_library([Path(__file__).parent])# Register the class in the class registryClassRegistryUtils.register_classes_in_file(- file_path=os.path.join(os.path.dirname(__file__), "data.py"),+ file_path=Path(__file__).parent / "data.py",base_class=StructuredContent,is_include_imported=False,)diff --git a/tests/unit/pipelex/graph/test_graphspec_roundtrip.py b/tests/unit/pipelex/graph/test_graphspec_roundtrip.pyindex a41f11ccd..7f8ff01b4 100644--- a/tests/unit/pipelex/graph/test_graphspec_roundtrip.py+++ b/tests/unit/pipelex/graph/test_graphspec_roundtrip.py@@ -218,8 +218,8 @@ class TestGraphSpecRoundtrip:)file_path = tmp_path / "test_graph.json"- save_text_to_path(graph.to_json(), str(file_path))- json_str = load_text_from_path(str(file_path))+ save_text_to_path(graph.to_json(), file_path)+ json_str = load_text_from_path(file_path)restored = GraphSpec.model_validate_json(json_str)assert restored.graph_id == graph.graph_iddiff --git a/tests/unit/pipelex/tools/misc/base64/test_base64_utils.py b/tests/unit/pipelex/tools/misc/base64/test_base64_utils.pyindex 99eba3c83..2dd742a42 100644--- a/tests/unit/pipelex/tools/misc/base64/test_base64_utils.py+++ b/tests/unit/pipelex/tools/misc/base64/test_base64_utils.py@@ -1,4 +1,5 @@import base64+from pathlib import Pathimport pytest@@ -25,7 +26,7 @@ class TestBase64Utils:with open(file_path, "rb") as file_handle:expected = base64.b64encode(file_handle.read()).decode("ascii")- result = await load_binary_as_base64(path=file_path)+ result = await load_binary_as_base64(path=Path(file_path))assert result == expectedassert isinstance(result, str)@@ -71,7 +72,7 @@ class TestBase64Utils:"""Test async creating base64 URL from PNG file path."""file_path = ImageTestCases.IMAGE_FILE_PATH_PNG_1- result = await make_base64_url_from_path(path=file_path)+ result = await make_base64_url_from_path(path=Path(file_path))assert result.startswith("data:image/png;base64,")base64_part = result.split(",", 1)[1]@@ -83,7 +84,7 @@ class TestBase64Utils:"""Test async creating base64 URL from JPEG file path."""file_path = ImageTestCases.IMAGE_FILE_PATH_JPG_1- result = await make_base64_url_from_path(path=file_path)+ result = await make_base64_url_from_path(path=Path(file_path))assert result.startswith("data:image/jpeg;base64,")base64_part = result.split(",", 1)[1]diff --git a/tests/unit/pipelex/tools/misc/test_filetype_utils.py b/tests/unit/pipelex/tools/misc/test_filetype_utils.pyindex b99dd7649..a09cba5f7 100644--- a/tests/unit/pipelex/tools/misc/test_filetype_utils.py+++ b/tests/unit/pipelex/tools/misc/test_filetype_utils.py@@ -36,21 +36,7 @@ class TestFileTypeError:class TestDetectFileTypeFromPath:- def test_detect_file_type_from_path_success_string(self, mocker: MockerFixture):- # Mock the filetype.guess function- mock_kind = mocker.MagicMock()- mock_kind.extension = "jpg"- mock_kind.mime = "image/jpeg"- mock_filetype_guess = mocker.patch("filetype.guess", return_value=mock_kind)-- result = detect_file_type_from_path("/path/to/image.jpg")-- assert isinstance(result, FileType)- assert result.extension == "jpg"- assert result.mime == "image/jpeg"- mock_filetype_guess.assert_called_once_with("/path/to/image.jpg")-- def test_detect_file_type_from_path_success_pathlib(self, mocker: MockerFixture):+ def test_detect_file_type_from_path_success(self, mocker: MockerFixture):# Mock the filetype.guess functionmock_kind = mocker.MagicMock()mock_kind.extension = "png"@@ -69,15 +55,6 @@ class TestDetectFileTypeFromPath:# Mock filetype.guess to return None (unrecognized file type)mock_filetype_guess = mocker.patch("filetype.guess", return_value=None)- with pytest.raises(FileTypeError, match=r"Could not identify file type of '/unknown/file\.xyz'"):- detect_file_type_from_path("/unknown/file.xyz")-- mock_filetype_guess.assert_called_once_with("/unknown/file.xyz")-- def test_detect_file_type_from_path_failure_pathlib(self, mocker: MockerFixture):- # Mock filetype.guess to return None (unrecognized file type)- mock_filetype_guess = mocker.patch("filetype.guess", return_value=None)-path = Path("/unknown/file.xyz")with pytest.raises(FileTypeError, match=r"Could not identify file type of '/unknown/file\.xyz'"):detect_file_type_from_path(path)diff --git a/tests/unit/pipelex/tools/misc/test_find_files_in_dir.py b/tests/unit/pipelex/tools/misc/test_find_files_in_dir.pyindex 65f541114..29215ff02 100644--- a/tests/unit/pipelex/tools/misc/test_find_files_in_dir.py+++ b/tests/unit/pipelex/tools/misc/test_find_files_in_dir.py@@ -19,7 +19,7 @@ class TestFindFilesInDir:(sub_dir / "file4.py").touch()# Find Python files non-recursively- files = find_files_in_dir(temp_dir, "*.py", is_recursive=False)+ files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=False)assert len(files) == 2file_names = [f.name for f in files]@@ -41,7 +41,7 @@ class TestFindFilesInDir:(sub_dir / "file4.py").touch()# Find Python files recursively- files = find_files_in_dir(temp_dir, "*.py", is_recursive=True)+ files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=True)expected_files_length = 3assert len(files) == expected_files_length@@ -53,7 +53,7 @@ class TestFindFilesInDir:def test_find_files_empty_directory(self):"""Test finding files in empty directory."""with tempfile.TemporaryDirectory() as temp_dir:- files = find_files_in_dir(temp_dir, "*.py", is_recursive=False)+ files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=False)assert len(files) == 0def test_find_files_no_matches(self):@@ -62,7 +62,7 @@ class TestFindFilesInDir:(Path(temp_dir) / "file1.txt").touch()(Path(temp_dir) / "file2.md").touch()- files = find_files_in_dir(temp_dir, "*.py", is_recursive=False)+ files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=False)assert len(files) == 0def test_find_files_with_excluded_dirs_single(self):@@ -86,7 +86,7 @@ class TestFindFilesInDir:normal_dir.mkdir()(normal_dir / "normal.py").touch()- files = find_files_in_dir(temp_dir, "*.py", is_recursive=True, excluded_dirs=[".venv"])+ files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=True, excluded_dirs=[".venv"])assert len(files) == 2file_names = [f.name for f in files]@@ -118,7 +118,7 @@ class TestFindFilesInDir:src_dir = Path(temp_dir) / "src"(src_dir / "normal.py").touch()- files = find_files_in_dir(temp_dir, "*.py", is_recursive=True, excluded_dirs=[".venv", "node_modules", "__pycache__"])+ files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=True, excluded_dirs=[".venv", "node_modules", "__pycache__"])assert len(files) == 2file_names = [f.name for f in files]@@ -156,7 +156,7 @@ class TestFindFilesInDir:(other_venv / "other.py").touch()files = find_files_in_dir(- temp_dir,+ Path(temp_dir),"*.py",is_recursive=True,excluded_dirs=[".venv"],@@ -201,7 +201,7 @@ class TestFindFilesInDir:(src_pipelex / "also_important.py").touch()files = find_files_in_dir(- temp_dir,+ Path(temp_dir),"*.py",is_recursive=True,excluded_dirs=[".venv"],@@ -247,7 +247,7 @@ class TestFindFilesInDir:(node_modules / "regular_node.py").touch()files = find_files_in_dir(- temp_dir,+ Path(temp_dir),"*.py",is_recursive=True,excluded_dirs=[".venv", "node_modules"],@@ -291,7 +291,7 @@ class TestFindFilesInDir:(pkg3 / "pkg3_file.py").touch()files = find_files_in_dir(- temp_dir,+ Path(temp_dir),"*.py",is_recursive=True,excluded_dirs=[".venv"],@@ -322,7 +322,7 @@ class TestFindFilesInDir:(Path(temp_dir) / "root.py").touch()files = find_files_in_dir(- temp_dir,+ Path(temp_dir),"*.py",is_recursive=True,excluded_dirs=[".venv"],@@ -346,7 +346,7 @@ class TestFindFilesInDir:venv_dir.mkdir()(venv_dir / "venv_file.py").touch()- files = find_files_in_dir(temp_dir, "*.py", is_recursive=True, excluded_dirs=None)+ files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=True, excluded_dirs=None)# Should find all files when no exclusionsassert len(files) == 2@@ -364,7 +364,7 @@ class TestFindFilesInDir:venv_dir.mkdir()(venv_dir / "venv_file.py").touch()- files = find_files_in_dir(temp_dir, "*.py", is_recursive=True, excluded_dirs=[".venv"], force_include_dirs=None)+ files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=True, excluded_dirs=[".venv"], force_include_dirs=None)# Should exclude all venv files when no includesassert len(files) == 1@@ -385,7 +385,7 @@ class TestFindFilesInDir:# Include directory is in src, not in excluded dirfiles = find_files_in_dir(- temp_dir,+ Path(temp_dir),"*.py",is_recursive=True,excluded_dirs=[".venv"],@@ -410,12 +410,12 @@ class TestFindFilesInDir:(venv_dir / "venv_data.json").touch()# Find only .py files- py_files = find_files_in_dir(temp_dir, "*.py", is_recursive=True, excluded_dirs=[".venv"])+ py_files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=True, excluded_dirs=[".venv"])assert len(py_files) == 1assert py_files[0].name == "script.py"# Find only .json files- json_files = find_files_in_dir(temp_dir, "*.json", is_recursive=True, excluded_dirs=[".venv"])+ json_files = find_files_in_dir(Path(temp_dir), "*.json", is_recursive=True, excluded_dirs=[".venv"])assert len(json_files) == 1assert json_files[0].name == "data.json"@@ -428,7 +428,7 @@ class TestFindFilesInDir:venv_dir.mkdir()(venv_dir / "venv_file.py").touch()- files = find_files_in_dir(temp_dir, "*.py", is_recursive=True, excluded_dirs=[])+ files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=True, excluded_dirs=[])# Empty list should behave like None - no exclusionsassert len(files) == 2@@ -442,7 +442,7 @@ class TestFindFilesInDir:venv_dir.mkdir()(venv_dir / "venv_file.py").touch()- files = find_files_in_dir(temp_dir, "*.py", is_recursive=True, excluded_dirs=[".venv"], force_include_dirs=[])+ files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=True, excluded_dirs=[".venv"], force_include_dirs=[])# Empty include list should exclude all venv filesassert len(files) == 1@@ -466,7 +466,7 @@ class TestFindFilesInDir:# Exclude structures using its absolute pathresult = find_files_in_dir(- str(temp_path),+ temp_path,"*.py",is_recursive=True,excluded_dirs=[str(structures_dir.resolve())],@@ -493,7 +493,7 @@ class TestFindFilesInDir:# Test with trailing slashresult_with_slash = find_files_in_dir(- str(temp_path),+ temp_path,"*.py",is_recursive=True,excluded_dirs=[str(structures_dir.resolve()) + "/"],@@ -501,7 +501,7 @@ class TestFindFilesInDir:# Test without trailing slashresult_without_slash = find_files_in_dir(- str(temp_path),+ temp_path,"*.py",is_recursive=True,excluded_dirs=[str(structures_dir.resolve())],@@ -536,7 +536,7 @@ class TestFindFilesInDir:(src_dir / "code.py").write_text("# code")result = find_files_in_dir(- str(temp_path),+ temp_path,"*.py",is_recursive=True,excluded_dirs=[".venv", str(structures_dir.resolve())],diff --git a/tests/unit/pipelex/tools/test_class_registry_utils.py b/tests/unit/pipelex/tools/test_class_registry_utils.pyindex 67587be92..d4f0c7d25 100644--- a/tests/unit/pipelex/tools/test_class_registry_utils.py+++ b/tests/unit/pipelex/tools/test_class_registry_utils.py@@ -32,10 +32,10 @@ class TestClassRegistryUtilsUnit:return_value=mock_registry,)- ClassRegistryUtils.register_classes_in_file(file_path="/fake/path.py", base_class=None, is_include_imported=False)+ ClassRegistryUtils.register_classes_in_file(file_path=Path("/fake/path.py"), base_class=None, is_include_imported=False)# Verify the mocked functions were called correctly- mock_import.assert_called_once_with("/fake/path.py")+ mock_import.assert_called_once_with(Path("/fake/path.py"))mock_find.assert_called_once_with(module=mock_module, base_class=None, include_imported=False)# Verify classes were registered with the global registry@@ -57,7 +57,7 @@ class TestClassRegistryUtilsUnit:mock_register_file = mocker.patch.object(ClassRegistryUtils, "register_classes_in_file")ClassRegistryUtils.register_classes_in_folder(- folder_path="/fake/folder",+ folder_path=Path("/fake/folder"),base_class=BaseModel,is_recursive=True,is_include_imported=False,@@ -65,7 +65,7 @@ class TestClassRegistryUtilsUnit:# Verify find_files_in_dir was called correctlymock_find_files.assert_called_once_with(- dir_path="/fake/folder",+ dir_path=Path("/fake/folder"),pattern="*.py",is_recursive=True,excluded_dirs=["__pycache__", ".git"],@@ -73,5 +73,5 @@ class TestClassRegistryUtilsUnit:# Verify register_classes_in_file was called for each fileassert mock_register_file.call_count == 2- mock_register_file.assert_any_call(file_path="/fake/file1.py", base_class=BaseModel, is_include_imported=False)- mock_register_file.assert_any_call(file_path="/fake/file2.py", base_class=BaseModel, is_include_imported=False)+ mock_register_file.assert_any_call(file_path=Path("/fake/file1.py"), base_class=BaseModel, is_include_imported=False)+ mock_register_file.assert_any_call(file_path=Path("/fake/file2.py"), base_class=BaseModel, is_include_imported=False)diff --git a/tests/unit/pipelex/tools/test_func_registry_utils.py b/tests/unit/pipelex/tools/test_func_registry_utils.pyindex 20070cc0d..15ab541e5 100644--- a/tests/unit/pipelex/tools/test_func_registry_utils.py+++ b/tests/unit/pipelex/tools/test_func_registry_utils.py@@ -163,7 +163,7 @@ class CodebaseFileContent(StructuredContent):func_registry.teardown()# Test the registration- FuncRegistryUtils.register_funcs_in_folder(folder_path=temp_dir, is_recursive=False)+ FuncRegistryUtils.register_funcs_in_folder(folder_path=Path(temp_dir), is_recursive=False)# Check that expected functions were registeredfor func_name in expected_registered:@@ -213,7 +213,7 @@ async def nested_function(working_memory: WorkingMemory) -> TextContent:func_registry.teardown()# Test recursive search- FuncRegistryUtils.register_funcs_in_folder(folder_path=temp_dir, is_recursive=True)+ FuncRegistryUtils.register_funcs_in_folder(folder_path=Path(temp_dir), is_recursive=True)# Both functions should be registeredassert func_registry.has_function("root_function"), "root_function should be registered"@@ -221,7 +221,7 @@ async def nested_function(working_memory: WorkingMemory) -> TextContent:# Clear and test non-recursive searchfunc_registry.teardown()- FuncRegistryUtils.register_funcs_in_folder(folder_path=temp_dir, is_recursive=False)+ FuncRegistryUtils.register_funcs_in_folder(folder_path=Path(temp_dir), is_recursive=False)# Only root function should be registeredassert func_registry.has_function("root_function"), "root_function should be registered"diff --git a/tests/unit/pipelex/tools/typing/test_convert_file_path_to_module_path.py b/tests/unit/pipelex/tools/typing/test_convert_file_path_to_module_path.pyindex b410187d5..8c3c8e373 100644--- a/tests/unit/pipelex/tools/typing/test_convert_file_path_to_module_path.py+++ b/tests/unit/pipelex/tools/typing/test_convert_file_path_to_module_path.py@@ -9,7 +9,7 @@ from pipelex.tools.typing.module_inspector import (class TestConvertFilePathToModulePath:def test_simple_relative_path(self):"""Test conversion of a simple relative path."""- result = convert_file_path_to_module_path("test_module.py")+ result = convert_file_path_to_module_path(Path("test_module.py"))# Should convert to absolute path and replace separators with underscoresassert result.endswith("test_module")assert ".py" not in result@@ -18,7 +18,7 @@ class TestConvertFilePathToModulePath:def test_absolute_path(self, tmp_path: Path):"""Test conversion of an absolute path."""file_path = str(tmp_path / "test_file.py")- result = convert_file_path_to_module_path(file_path)+ result = convert_file_path_to_module_path(Path(file_path))# Should contain the temp path components with separators replacedassert "test_file" in resultassert ".py" not in result@@ -28,7 +28,7 @@ class TestConvertFilePathToModulePath:def test_nested_path(self, tmp_path: Path):"""Test conversion of a nested path."""file_path = str(tmp_path / "subdir" / "nested" / "module.py")- result = convert_file_path_to_module_path(file_path)+ result = convert_file_path_to_module_path(Path(file_path))assert "module" in resultassert "subdir" in resultassert "nested" in result@@ -38,13 +38,13 @@ class TestConvertFilePathToModulePath:def test_removes_py_extension(self):"""Test that .py extension is removed."""- result = convert_file_path_to_module_path("my_module.py")+ result = convert_file_path_to_module_path(Path("my_module.py"))assert not result.endswith(".py")assert not result.endswith("_py")def test_replaces_special_characters(self):"""Test that special characters are replaced with underscores."""- result = convert_file_path_to_module_path("my-special.module.py")+ result = convert_file_path_to_module_path(Path("my-special.module.py"))# Hyphens and dots should be replaced with underscoresassert "-" not in result# The .py extension is removed, but other dots become underscores@@ -52,14 +52,14 @@ class TestConvertFilePathToModulePath:def test_replaces_spaces(self):"""Test that spaces are replaced with underscores."""- result = convert_file_path_to_module_path("my module.py")+ result = convert_file_path_to_module_path(Path("my module.py"))assert " " not in resultassert "my" in resultassert "module" in resultdef test_path_with_multiple_special_chars(self):"""Test path with various special characters."""- result = convert_file_path_to_module_path("my-file@name#test.py")+ result = convert_file_path_to_module_path(Path("my-file@name#test.py"))# All special characters should be replaced with underscoresassert "@" not in resultassert "#" not in result@@ -70,7 +70,7 @@ class TestConvertFilePathToModulePath:def test_number_at_start_adds_underscore(self):"""Test that a path starting with a number gets underscore prefix."""- result = convert_file_path_to_module_path("123_module.py")+ result = convert_file_path_to_module_path(Path("123_module.py"))# Module names cannot start with numbers in Pythonassert result[0] == "_" or not result[0].isdigit()# If it was prefixed, check that the original number is still there@@ -80,16 +80,16 @@ class TestConvertFilePathToModulePath:def test_consistent_results_for_same_path(self):"""Test that the same path produces the same result."""path = "test/module.py"- result1 = convert_file_path_to_module_path(path)- result2 = convert_file_path_to_module_path(path)+ result1 = convert_file_path_to_module_path(Path(path))+ result2 = convert_file_path_to_module_path(Path(path))assert result1 == result2def test_different_paths_produce_different_results(self, tmp_path: Path):"""Test that different absolute paths produce different results."""path1 = str(tmp_path / "module1.py")path2 = str(tmp_path / "module2.py")- result1 = convert_file_path_to_module_path(path1)- result2 = convert_file_path_to_module_path(path2)+ result1 = convert_file_path_to_module_path(Path(path1))+ result2 = convert_file_path_to_module_path(Path(path2))assert result1 != result2def test_uses_absolute_path(self, tmp_path: Path):@@ -102,7 +102,7 @@ class TestConvertFilePathToModulePath:# Change to test directoryos.chdir(test_dir)# Use relative path- result = convert_file_path_to_module_path("relative_module.py")+ result = convert_file_path_to_module_path(Path("relative_module.py"))# Result should contain the absolute path componentsassert str(test_dir).replace(os.sep, "_") in result or "testdir" in resultfinally:@@ -111,14 +111,14 @@ class TestConvertFilePathToModulePath:def test_path_with_dots_in_directory(self):"""Test path with dots in directory names."""- result = convert_file_path_to_module_path("dir.name/module.py")+ result = convert_file_path_to_module_path(Path("dir.name/module.py"))# Dots should be replaced with underscoresassert "." not in resultassert all(c.isalnum() or c == "_" for c in result)def test_unicode_characters(self):"""Test path with Unicode characters."""- result = convert_file_path_to_module_path("modülé.py")+ result = convert_file_path_to_module_path(Path("modülé.py"))# Unicode alphanumeric should be preservedassert ".py" not in result# Result should only contain valid identifier characters@@ -128,7 +128,7 @@ class TestConvertFilePathToModulePath:"""Test that even minimal paths like '.py' produce valid identifiers."""# Even a path like ".py" will be converted to absolute path first,# so it will include the current directory components- result = convert_file_path_to_module_path(".py")+ result = convert_file_path_to_module_path(Path(".py"))# Should still be a valid identifierassert len(result) > 0assert result[0].isalpha() or result[0] == "_"@@ -145,7 +145,7 @@ class TestConvertFilePathToModulePath:"special@chars#here.py",]for path in test_paths:- result = convert_file_path_to_module_path(path)+ result = convert_file_path_to_module_path(Path(path))# Check it's a valid identifier: starts with letter or underscore,# followed by letters, digits, or underscoresassert result[0].isalpha() or result[0] == "_"@@ -158,7 +158,7 @@ class TestConvertFilePathToModulePath:for i in range(10):long_path /= f"dir{i}"file_path = str(long_path / "module.py")- result = convert_file_path_to_module_path(file_path)+ result = convert_file_path_to_module_path(Path(file_path))# Should contain elements from all directory levelsassert "dir0" in resultassert "dir9" in result@@ -167,7 +167,7 @@ class TestConvertFilePathToModulePath:def test_path_with_multiple_dots(self):"""Test path with multiple dots in filename."""- result = convert_file_path_to_module_path("my.module.test.py")+ result = convert_file_path_to_module_path(Path("my.module.test.py"))# All dots except in .py extension should become underscoresassert ".py" not in resultassert "my" in result@@ -177,7 +177,7 @@ class TestConvertFilePathToModulePath:def test_windows_style_path(self):"""Test Windows-style path with backslashes."""# Use a path that looks like Windows path- result = convert_file_path_to_module_path("C:\\Users\\test\\module.py")+ result = convert_file_path_to_module_path(Path("C:\\Users\\test\\module.py"))# Backslashes should be replacedassert "\\" not in resultassert ":" not in result # Colon from C: should be replaced@@ -187,8 +187,8 @@ class TestConvertFilePathToModulePath:"""Test that different paths with similar names produce unique results."""path1 = str(tmp_path / "dir1" / "module.py")path2 = str(tmp_path / "dir2" / "module.py")- result1 = convert_file_path_to_module_path(path1)- result2 = convert_file_path_to_module_path(path2)+ result1 = convert_file_path_to_module_path(Path(path1))+ result2 = convert_file_path_to_module_path(Path(path2))# Even though they have the same filename, full paths should differassert result1 != result2assert "dir1" in result1diff --git a/tests/unit/pipelex/tools/typing/test_find_class_names_in_file.py b/tests/unit/pipelex/tools/typing/test_find_class_names_in_file.pyindex 5815671c7..4d55ee21a 100644--- a/tests/unit/pipelex/tools/typing/test_find_class_names_in_file.py+++ b/tests/unit/pipelex/tools/typing/test_find_class_names_in_file.py@@ -20,7 +20,7 @@ class ClassB:def some_function():pass""")- class_names = find_class_names_in_file(str(test_file_path))+ class_names = find_class_names_in_file(test_file_path)assert len(class_names) == 2assert "ClassA" in class_namesassert "ClassB" in class_names@@ -45,7 +45,7 @@ class UnrelatedClass:pass""")class_names = find_class_names_in_file(- str(test_file_path),+ test_file_path,base_class_names=["StructuredContent"],)assert len(class_names) == 1@@ -66,7 +66,7 @@ class UnrelatedClass:pass""")class_names = find_class_names_in_file(- str(test_file_path),+ test_file_path,base_class_names=["StructuredContent"],)assert len(class_names) == 1@@ -81,7 +81,7 @@ def some_function():variable = 42""")- class_names = find_class_names_in_file(str(test_file_path))+ class_names = find_class_names_in_file(test_file_path)assert len(class_names) == 0def test_find_class_names_non_python_file_raises_error(self, tmp_path: Path):@@ -89,12 +89,12 @@ variable = 42test_file_path = tmp_path / "test.txt"test_file_path.write_text("Not Python")with pytest.raises(ModuleFileError) as excinfo:- find_class_names_in_file(str(test_file_path))+ find_class_names_in_file(test_file_path)assert "is not a Python file" in str(excinfo.value)def test_find_class_names_nonexistent_file_raises_error(self, tmp_path: Path):"""Test that nonexistent file raises error."""nonexistent_file_path = tmp_path / "nonexistent.py"with pytest.raises(ModuleFileError) as excinfo:- find_class_names_in_file(str(nonexistent_file_path))+ find_class_names_in_file(nonexistent_file_path)assert "does not exist" in str(excinfo.value)diff --git a/tests/unit/pipelex/tools/typing/test_import_module_from_file.py b/tests/unit/pipelex/tools/typing/test_import_module_from_file.pyindex 6e83ed93b..09d93b331 100644--- a/tests/unit/pipelex/tools/typing/test_import_module_from_file.py+++ b/tests/unit/pipelex/tools/typing/test_import_module_from_file.py@@ -27,7 +27,7 @@ def test_function():class TestClass:pass""")- module = import_module_from_file(str(test_file_path))+ module = import_module_from_file(test_file_path)assert hasattr(module, "test_function")assert hasattr(module, "TestClass")assert module.test_function() == "test_value"@@ -37,14 +37,14 @@ class TestClass:test_file_path = tmp_path / "test_file.txt"test_file_path.write_text("This is not Python code")with pytest.raises(ModuleFileError) as excinfo:- import_module_from_file(str(test_file_path))+ import_module_from_file(test_file_path)assert "is not a Python file" in str(excinfo.value)def test_import_nonexistent_file_raises_error(self, tmp_path: Path):"""Test that importing a nonexistent file raises FileNotFoundError."""nonexistent_file_path = tmp_path / "nonexistent.py"with pytest.raises(FileNotFoundError):- import_module_from_file(str(nonexistent_file_path))+ import_module_from_file(nonexistent_file_path)def test_import_file_with_syntax_error_raises_error(self, tmp_path: Path):"""Test that importing a file with syntax errors raises SyntaxError."""@@ -54,7 +54,7 @@ def test_function(return "missing closing parenthesis"""")with pytest.raises(SyntaxError):- import_module_from_file(str(test_file_path))+ import_module_from_file(test_file_path)def test_import_file_with_import_error_raises_error(self, tmp_path: Path):"""Test that importing a file with import errors raises ImportError."""@@ -63,7 +63,7 @@ def test_function(import nonexistent_module""")with pytest.raises(ImportError):- import_module_from_file(str(test_file_path))+ import_module_from_file(test_file_path)def test_module_added_to_sys_modules(self, tmp_path: Path):"""Test that imported module is added to sys.modules."""@@ -72,7 +72,7 @@ import nonexistent_moduledef test_function():return "test_value"""")- module = import_module_from_file(str(test_file_path))+ module = import_module_from_file(test_file_path)# The module name is derived from the full file pathmodule_name = module.__name__assert module_name.endswith("test_module_sys")@@ -88,6 +88,6 @@ def test_function():def test_function():return "test_value"""")- module = import_module_from_file(str(test_file_path))+ module = import_module_from_file(test_file_path)assert hasattr(module, "test_function")assert module.test_function() == "test_value"diff --git a/tests/unit/pipelex/tools/typing/test_import_module_from_file_if_has_classes.py b/tests/unit/pipelex/tools/typing/test_import_module_from_file_if_has_classes.pyindex ec2b13e05..952a04a81 100644--- a/tests/unit/pipelex/tools/typing/test_import_module_from_file_if_has_classes.py+++ b/tests/unit/pipelex/tools/typing/test_import_module_from_file_if_has_classes.py@@ -27,7 +27,7 @@ class MyContent(StructuredContent):value = "imported"""")module = import_module_from_file_if_has_classes(- str(test_file_path),+ test_file_path,base_class_names=["StructuredContent"],)assert module is not None@@ -48,7 +48,7 @@ def some_function():pass""")module = import_module_from_file_if_has_classes(- str(test_file_path),+ test_file_path,base_class_names=["StructuredContent"],)assert module is None@@ -62,7 +62,7 @@ def some_function():class AnyClass:value = "any_class"""")- module = import_module_from_file_if_has_classes(str(test_file_path))+ module = import_module_from_file_if_has_classes(test_file_path)assert module is not Noneassert hasattr(module, "AnyClass")assert module.AnyClass.value == "any_class"@@ -76,5 +76,5 @@ def some_function():variable = 42""")- module = import_module_from_file_if_has_classes(str(test_file_path))+ module = import_module_from_file_if_has_classes(test_file_path)assert module is Nonediff --git a/wip/pathlib-refactor.workflow.js b/wip/pathlib-refactor.workflow.jsnew file mode 100644index 000000000..491743dcc--- /dev/null+++ b/wip/pathlib-refactor.workflow.js@@ -0,0 +1,278 @@+export const meta = {+ name: 'pathlib-refactor',+ description: 'Refactor filesystem path handling to pathlib.Path, converting to/from str only at boundaries (CLI, API, env)',+ whenToUse: 'When you want to modernize path handling across pipelex/: use pathlib.Path internally, str only at boundaries.',+ phases: [+ { title: 'Inventory', detail: 'parallel read-only scan of each subsystem for filesystem-path handling' },+ { title: 'Plan', detail: 'synthesize disjoint, self-contained refactor clusters' },+ { title: 'Implement', detail: 'one agent per cluster applies pathlib idioms' },+ { title: 'Verify', detail: 'make agent-check + targeted path tests, with repair loop' },+ ],+}++// ---------------------------------------------------------------------------+// Shared guidance — every agent must respect these rules.+// ---------------------------------------------------------------------------+const RULES = `+PROJECT: pipelex (Python runtime). CWD is the repo root (a worktree on branch refactor/Paths).+GOAL: modern, pythonic filesystem-path handling.+ - Use \`from pathlib import Path\` and Path objects for ALL filesystem path manipulation internally.+ - Replace os.path.join/dirname/basename/exists/isdir/abspath/relpath, os.makedirs, os.walk, os.listdir,+ string concatenation of paths, and str-typed FS path params with Path equivalents+ (Path / "x", p.parent, p.name, p.exists(), p.is_dir(), p.resolve(), p.relative_to(), p.mkdir(parents=True, exist_ok=True),+ Path.rglob/iterdir/walk, etc.).+ - Convert to/from str ONLY at genuine boundaries: CLI argument parsing (typer/click), API request/response models,+ environment-variable parsing (os.environ, PIPELEXPATH split on os.pathsep), serialization to JSON/TOML,+ and third-party library calls that demand str. At those boundaries, str(path) / Path(raw_str) is correct and expected.+ - Internal utility functions (e.g. in pipelex/tools/misc/) should take and pass Path. Per project policy there is+ NO backward-compat requirement — change signatures directly; do NOT add \`str | Path\` unions just to be safe.+ Exception: a function that is a public exported API surface OR a boundary may keep str. Use judgment and note it.++CRITICAL — DO NOT TOUCH non-filesystem "paths". These look like paths but are NOT files on disk:+ - dotted/attribute paths: variable_path, dotted_path, var_path, from_path (blueprint refs), key_path, json paths,+ "report.pdf"-style template variable references, module import paths (a.b.c), concept/pipe paths.+ - URL paths, route paths, API endpoint paths.+ - module-path<->file-path conversion helpers where the "module path" side is dotted.+ If a *_path symbol is not an actual location on the filesystem, LEAVE IT ALONE and record it as excluded.++Be precise. Prefer correctness over breadth. Read the actual code before judging.+`++const INVENTORY_SCHEMA = {+ type: 'object',+ additionalProperties: false,+ required: ['area', 'files', 'notes'],+ properties: {+ area: { type: 'string' },+ files: {+ type: 'array',+ items: {+ type: 'object',+ additionalProperties: false,+ required: ['path', 'role', 'fs_path_symbols', 'excluded_logical_paths', 'recommended_changes'],+ properties: {+ path: { type: 'string', description: 'repo-relative file path' },+ role: { type: 'string', enum: ['core_util', 'boundary', 'internal', 'test'] },+ fs_path_symbols: {+ type: 'array',+ description: 'Genuine filesystem-path functions/params/attrs that should move to Path',+ items: {+ type: 'object',+ additionalProperties: false,+ required: ['name', 'kind', 'detail'],+ properties: {+ name: { type: 'string' },+ kind: { type: 'string', enum: ['function', 'method', 'param', 'attribute', 'local', 'os_path_call'] },+ detail: { type: 'string', description: 'current signature/usage + line refs + what should change' },+ },+ },+ },+ excluded_logical_paths: {+ type: 'array',+ description: 'Symbols that look like paths but are NOT filesystem paths — must not be changed',+ items: {+ type: 'object',+ additionalProperties: false,+ required: ['name', 'reason'],+ properties: { name: { type: 'string' }, reason: { type: 'string' } },+ },+ },+ recommended_changes: { type: 'string' },+ },+ },+ },+ notes: { type: 'string', description: 'cross-file observations, especially callers of functions whose signatures should change' },+ },+}++const PLAN_SCHEMA = {+ type: 'object',+ additionalProperties: false,+ required: ['clusters', 'excluded', 'summary'],+ properties: {+ clusters: {+ type: 'array',+ items: {+ type: 'object',+ additionalProperties: false,+ required: ['id', 'title', 'rationale', 'files', 'instructions', 'signature_changes'],+ properties: {+ id: { type: 'string', description: 'short kebab id, e.g. core-file-utils' },+ title: { type: 'string' },+ rationale: { type: 'string' },+ files: { type: 'array', items: { type: 'string' }, description: 'ALL files this cluster edits — MUST be disjoint from every other cluster' },+ instructions: { type: 'string', description: 'precise per-cluster refactor instructions' },+ signature_changes: { type: 'array', items: { type: 'string' }, description: 'function signatures changing, so the owning agent updates every caller within this cluster' },+ },+ },+ },+ excluded: { type: 'array', items: { type: 'string' }, description: 'logical/non-fs paths confirmed left untouched' },+ summary: { type: 'string' },+ },+}++const CLUSTER_RESULT_SCHEMA = {+ type: 'object',+ additionalProperties: false,+ required: ['cluster_id', 'files_changed', 'summary', 'follow_ups'],+ properties: {+ cluster_id: { type: 'string' },+ files_changed: { type: 'array', items: { type: 'string' } },+ summary: { type: 'string' },+ follow_ups: { type: 'array', items: { type: 'string' }, description: 'anything left undone or risky for verification to watch' },+ },+}++const VERIFY_SCHEMA = {+ type: 'object',+ additionalProperties: false,+ required: ['passed', 'commands_run', 'failures', 'raw_tail'],+ properties: {+ passed: { type: 'boolean' },+ commands_run: { type: 'array', items: { type: 'string' } },+ failures: {+ type: 'array',+ items: {+ type: 'object',+ additionalProperties: false,+ required: ['tool', 'file', 'message'],+ properties: {+ tool: { type: 'string', description: 'pyright | mypy | ruff | pytest | other' },+ file: { type: 'string' },+ message: { type: 'string' },+ },+ },+ },+ raw_tail: { type: 'string', description: 'last ~60 lines of combined output for context' },+ },+}++const REPAIR_SCHEMA = {+ type: 'object',+ additionalProperties: false,+ required: ['files_changed', 'notes'],+ properties: {+ files_changed: { type: 'array', items: { type: 'string' } },+ notes: { type: 'string' },+ },+}++// ---------------------------------------------------------------------------+// Phase 1 — Inventory (parallel, read-only)+// ---------------------------------------------------------------------------+phase('Inventory')++const AREAS = [+ { area: 'core-utils', scope: 'pipelex/tools/misc/ (file_utils.py, toml_utils.py, json_utils.py, base64_utils.py, filetype_utils.py, diff.py, toml_sync.py) and pipelex/tools/ broadly. This is the HUB — most FS path helpers live here.' },+ { area: 'cli', scope: 'pipelex/cli/ (commands/, agent_cli/, init/). Boundary-heavy: typer/click args are str and convert to Path here.' },+ { area: 'tracing-observer', scope: 'pipelex/tracing/ (ndjson_event_log.py) and pipelex/observer/ (local_observer.py).' },+ { area: 'system-config', scope: 'pipelex/system/ — especially environment.py (PIPELEXPATH / os.pathsep parsing — a boundary) and configuration/.' },+ { area: 'temporal-plugins', scope: 'pipelex/temporal/ (worker_cli.py) and pipelex/plugins/ (mistral_factory.py and others).' },+ { area: 'rest-of-src', scope: 'Everything else under pipelex/ NOT covered above: kit/, graph/, builder/, core/, pipe_operators/, pipe_controllers/, etc. Watch hard for logical/dotted paths here (variable_path, dotted_path, from_path) which must be EXCLUDED.' },+ { area: 'tests', scope: 'tests/ — find call sites of FS path utilities and any direct FS path handling that will need updating when signatures change. Include tests/helpers/paths.py.' },+ { area: 'export-surface', scope: 'Public export surface: pipelex/__init__.py and any re-exports, plus build a caller index. Use grep to list ALL callers across pipelex/ and tests/ of these functions: save_text_to_path, save_bytes_to_binary_file, load_text_from_path, failable_load_text_from_path, load_binary, load_binary_async, copy_file, copy_file_from_package, copy_folder_from_package, remove_file, remove_folder, mirror_dir, ensure_directory_exists, ensure_path, ensure_directory_for_file_path, get_incremental_directory_path, load_toml_from_path, save_toml_to_path. Report which of these are publicly exported (boundary) vs internal, and the full caller list per function.' },+]++const inventories = (await parallel(AREAS.map((a) => () =>+ agent(+ `${RULES}\n\nYou are inventorying area "${a.area}".\nSCOPE: ${a.scope}\n\n` ++ `Search this scope thoroughly (grep for os.path, "import os", os.makedirs/walk/listdir/getcwd, open(, *_path: str, *_dir: str, *_file: str, string path concatenation). ` ++ `For each relevant file, READ the actual usage and classify every path-like symbol as a genuine filesystem path (record in fs_path_symbols) or a logical/non-fs path (record in excluded_logical_paths with the reason). ` ++ `Note callers of any function whose signature should change. Do NOT edit anything — this is read-only.`,+ { agentType: 'Explore', schema: INVENTORY_SCHEMA, label: `inv:${a.area}`, phase: 'Inventory' },+ ),+))).filter(Boolean)++log(`Inventory complete: ${inventories.length} areas, ${inventories.reduce((n, i) => n + (i.files?.length || 0), 0)} files flagged`)++// ---------------------------------------------------------------------------+// Phase 2 — Plan (single synthesizer; barrier — needs the full inventory)+// ---------------------------------------------------------------------------+phase('Plan')++const plan = await agent(+ `${RULES}\n\nYou are the refactor architect. Below is the full filesystem-path inventory of the repo as JSON.\n\n` ++ `${JSON.stringify(inventories, null, 2)}\n\n` ++ `Produce a refactor plan as a set of CLUSTERS with these HARD constraints:\n` ++ `1. Clusters must partition the work into DISJOINT file sets — NO file may appear in two clusters. If a file (e.g. a test or CLI module) calls utilities from what would be two clusters, MERGE those clusters so one agent owns all coupled files.\n` ++ `2. Each cluster must be SELF-CONTAINED: if it changes a function signature, it must include that function's definition AND every caller of it (across pipelex/ and tests/). This is why disjointness matters — it guarantees parallel agents never touch the same file and signatures stay consistent.\n` ++ `3. Group naturally: a "core-file-utils" cluster (file_utils.py + all its callers) will likely be the largest and that is fine — one agent owns it.\n` ++ `4. Confirm the excluded logical/non-fs paths so implementers know what to leave alone.\n` ++ `5. Verify caller completeness yourself with grep before finalizing — do not rely solely on the inventory notes.\n` ++ `Order clusters by importance but assume they are independent (they will run in parallel). Write precise, actionable per-cluster instructions.`,+ { schema: PLAN_SCHEMA, label: 'synthesize-plan', phase: 'Plan' },+)++// Safety net: detect any file that leaked into >1 cluster and warn (synthesis is instructed to avoid this).+const seen = {}+const collisions = new Set()+for (const c of plan.clusters) for (const f of (c.files || [])) { if (seen[f]) collisions.add(f); seen[f] = true }+if (collisions.size) log(`WARNING: ${collisions.size} file(s) appear in multiple clusters: ${[...collisions].join(', ')} — running sequentially-safe is NOT guaranteed; review.`)+log(`Plan: ${plan.clusters.length} clusters covering ${Object.keys(seen).length} files. ${plan.summary}`)++// ---------------------------------------------------------------------------+// Phase 3 — Implement (parallel, one agent per cluster; disjoint file sets)+// ---------------------------------------------------------------------------+phase('Implement')++const results = (await parallel(plan.clusters.map((c) => () =>+ agent(+ `${RULES}\n\nYou OWN this refactor cluster and ONLY these files — do not edit files outside the list:\n` ++ `${JSON.stringify(c.files, null, 2)}\n\n` ++ `Title: ${c.title}\nRationale: ${c.rationale}\nSignature changes you must propagate to every caller in your file list: ${JSON.stringify(c.signature_changes)}\n\n` ++ `Instructions:\n${c.instructions}\n\n` ++ `Apply the edits with the Edit/Write tools. Keep changes idiomatic and minimal — convert genuine FS path handling to pathlib.Path, keep str only at the boundaries described in the rules. ` ++ `Do not run linters or tests (a dedicated verify phase does that). When done, report exactly which files you changed.`,+ { schema: CLUSTER_RESULT_SCHEMA, label: `impl:${c.id}`, phase: 'Implement' },+ ),+))).filter(Boolean)++const changedFiles = [...new Set(results.flatMap((r) => r.files_changed || []))]+log(`Implementation complete: ${results.length} clusters, ${changedFiles.length} files changed.`)++// ---------------------------------------------------------------------------+// Phase 4 — Verify + repair loop (barrier; whole-repo lint/type check)+// ---------------------------------------------------------------------------+phase('Verify')++const VERIFY_CMDS =+ 'Run, from the repo root, IN THIS ORDER and capture output:\n' ++ ' 1. `make agent-check` (ruff fix-unused-imports + format + lint, then pyright, then mypy)\n' ++ ' 2. `.venv/bin/pytest -q -p no:randomly -m "not (inference or pipelex_api or img_gen or gha_disabled or needs_output or llm or ocr)" -k "test_boot or test_toml_utils or test_paths or inputs_path_resolver or convert_file_path_to_module_path" --tb=short` (targeted: boot/config load + path-related unit tests)\n' ++ 'Report passed=true ONLY if make agent-check exits 0 AND the targeted pytest exits 0. ' ++ 'Parse failures into the structured list (tool, file, message). Include the last ~60 lines of combined output in raw_tail.'++let verify = await agent(+ `You are the verification gate for a pathlib refactor. ${VERIFY_CMDS}`,+ { schema: VERIFY_SCHEMA, label: 'verify:1', phase: 'Verify' },+)++let attempt = 0+while (!verify.passed && attempt < 3) {+ attempt+++ log(`Verify failed (attempt ${attempt}): ${verify.failures.length} issue(s). Repairing...`)+ await agent(+ `${RULES}\n\nThe pathlib refactor introduced check/test failures. Fix them at the ROOT cause — keep the pathlib best-practice intent; ` ++ `do NOT revert to os.path just to silence a checker unless the location is a genuine boundary. ` ++ `If a failure reveals a misclassified logical (non-fs) path that should never have been changed, revert that specific change.\n\n` ++ `Failures (JSON):\n${JSON.stringify(verify.failures, null, 2)}\n\nRaw output tail:\n${verify.raw_tail}\n\n` ++ `Edit the offending files to fix every failure. Do not run the full check yourself; the gate will re-run.`,+ { schema: REPAIR_SCHEMA, label: `repair:${attempt}`, phase: 'Verify' },+ )+ verify = await agent(+ `You are the verification gate for a pathlib refactor (re-run after repair attempt ${attempt}). ${VERIFY_CMDS}`,+ { schema: VERIFY_SCHEMA, label: `verify:${attempt + 1}`, phase: 'Verify' },+ )+}++log(verify.passed ? 'Verification PASSED ✅' : `Verification still FAILING after ${attempt} repair attempt(s) ❌`)++return {+ inventory_summary: { areas: inventories.length, files_flagged: inventories.reduce((n, i) => n + (i.files?.length || 0), 0) },+ plan_summary: plan.summary,+ excluded_logical_paths: plan.excluded,+ clusters: plan.clusters.map((c) => ({ id: c.id, title: c.title, files: c.files })),+ files_changed: changedFiles,+ implementation: results,+ verification: verify,+}