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.
fix/Config-before-validators · L-261010-20e31b (#1407)
Louis Choquel365fa71c9d00
diff --git a/.drift/acks/config-docs.toml b/.drift/acks/config-docs.tomlindex c9a2aed1e..bf24b0109 100644--- a/.drift/acks/config-docs.toml+++ b/.drift/acks/config-docs.toml@@ -1,11 +1,11 @@contract = "config-docs"-digest = "sha256:7121dcd7b9d44de22c6d0e86c2d2bf206d32a8129c2032465da6f49dd1e13054"-reviewed_by = "Louis Choquel"-reviewed_at = "2026-10-10T13:32:12Z"-rationale = "clean-pass: the triggers remove the unread [inference.gateway_test] table from pipelex.toml with its GatewayTestConfig model and the InferenceConfig.gateway_test field in config_cogt.py. The removal is answered in the same change by ledger entry pipelex-config@8, a safe delete_table, with check-ledger and check-migration-schemas green. No page under docs/configuration documented the table (inference-config.md lists llm, img_gen and extract only), configs.py needs nothing, and no validator moved."+digest = "sha256:55894578aae3a9fbcaaaa2276dd54cb643a13f9face3709649e903b0f7dde02e"+reviewed_by = "Claude (Opus 5.5)"+reviewed_at = "2026-10-10T14:00:11Z"+rationale = "clean-pass: after merging origin/dev, the triggers changed since dev's ack are this branch's four files. ScanConfig.excluded_dirs is a lax frozenset[str] with no before-validator, so a string or a number is refused, and library-config.md names the key and the refusal; LogConfig.package_log_levels is dict[str, LaxEnum[LogLevel]], whose entries logging-config.md describes unchanged; DryRunConfig.validate_image_urls keeps its name and its non-empty rule as an after-validator raising ValueError, as dry-run-config.md says and as this contract's list of live sites names it, and dev's removal of gateway_test from config_cogt.py merged beside it untouched; ConfigModel lost its transform helpers and gained LaxEnum, documented in the kit standards rule. check-migration-schemas passes on all three surfaces after the merge, pipelex-config@8 included, so the annotation changes moved no fingerprint; the narrowings refuse only values that never meant what they said, so no ledger entry is owed."[trigger_files]-"pipelex/cogt/config_cogt.py" = "blob:8e6514bfcc38e63c9b159a91cd4352e588a24fc5"+"pipelex/cogt/config_cogt.py" = "blob:293ef22ae123266e6a1886d4ffb07f455e5be9e3""pipelex/cogt/img_gen/img_gen_job_components.py" = "blob:084985080413fd8d6c3b1b9b0747020cb0161858""pipelex/graph/graph_config.py" = "blob:dc0939a6d2730c0a10b88aa1a6e0b2dd583462a6""pipelex/language/mthds_config.py" = "blob:353009ad8c59dc5266bdd9dfa42b1ad18b67dca7"@@ -14,14 +14,14 @@ rationale = "clean-pass: the triggers remove the unread [inference.gateway_test]"pipelex/system/configuration/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc""pipelex/system/configuration/config_check.py" = "blob:2d5de29aba3d2ce205d3d82b4623f37b53108332""pipelex/system/configuration/config_loader.py" = "blob:2850f6b39df6ad2afafefc4d431672cb6ee91ced"-"pipelex/system/configuration/config_model.py" = "blob:83b29dc6e93393c9b98c4353636caf0135c80339"+"pipelex/system/configuration/config_model.py" = "blob:b7d141d559c0302f0d8c56859ae0a8edeb9bfdf0""pipelex/system/configuration/config_root.py" = "blob:c7d43851270912d17413cfc6a511247d3c7cc160""pipelex/system/configuration/config_surface.py" = "blob:49424a8103a5611f5b2885135dd699273bde57c8"-"pipelex/system/configuration/configs.py" = "blob:1754391061f3be47e28088a4f8ea85e60b1cdd2b"+"pipelex/system/configuration/configs.py" = "blob:ff56c3d33aa358c6f9d8036d47a83924d473904f""pipelex/system/configuration/pipe_func_config.py" = "blob:dc8890e914fbcdb611147e42eaa0cd87b32288a5""pipelex/system/telemetry/telemetry_config.py" = "blob:068a785d97a2d52ee43e82e723cd944b8b6601bc""pipelex/tools/aws/aws_config.py" = "blob:0a7c9dbf276e61355b1fa79b9db8caf252450a39"-"pipelex/tools/log/log_config.py" = "blob:97019b2cf36ed04513f547059b72be4e6bfcbf05"+"pipelex/tools/log/log_config.py" = "blob:c7ffacbd2b8fcd85b990fc09755cd3279a23932c""pipelex/tools/log/log_levels.py" = "blob:12b94e4d4793a70156ac547ee20c9d483910ecae""pipelex/tools/network/network_config.py" = "blob:e12d1d0e4a40d04859f10a77addeaf8fe2b00414""pipelex/tools/secrets/secrets_config.py" = "blob:cf30aaec1c76c9cabc0531a5b9fe681e153d7024"diff --git a/.test_durations b/.test_durationsindex 995f67f12..a7f4f9a91 100644--- a/.test_durations+++ b/.test_durations@@ -14329,7 +14329,6 @@"tests/unit/pipelex/test_method_fetch_on_miss_config.py::TestIsMethodFetchOnMissEnabled::test_env_var_enables[true]": 0.0004,"tests/unit/pipelex/test_method_fetch_on_miss_config.py::TestIsMethodFetchOnMissEnabled::test_env_var_enables[yes]": 0.0003,"tests/unit/pipelex/test_method_fetch_on_miss_config.py::TestIsMethodFetchOnMissEnabled::test_unrecognized_env_value_falls_back_to_config": 0.0988,- "tests/unit/pipelex/test_pipelex_error_message_init.py::TestPipelexErrorMessageInit::test_message_set_and_error_report_succeeds[ConfigModelError]": 0.1062,"tests/unit/pipelex/test_pipelex_error_message_init.py::TestPipelexErrorMessageInit::test_message_set_and_error_report_succeeds[ConstructFieldBlueprintValueError]": 0.0005,"tests/unit/pipelex/test_pipelex_error_message_init.py::TestPipelexErrorMessageInit::test_message_set_and_error_report_succeeds[RoutingProfileBlueprintValueError]": 0.0012,"tests/unit/pipelex/test_pipelex_error_message_init.py::TestPipelexErrorMessageInit::test_no_subclass_shadows_message_setting_init": 0.8693,diff --git a/AGENTS.md b/AGENTS.mdindex da8134ede..ef4abf1cf 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -359,6 +359,7 @@ Use one casing per acronym (`LLMError` vs `LlmError` collide when kebab-cased in- The model is defined in `pipelex/system/configuration/configs.py`, some of the submodels being defined in their respective sub-packages- When adding new configs, place them where it makes most sense, ask the user if you need arbitrage- As per our python standards, use StrEnum for multiple-value enums. In that case they must not be strict pydantic fields, i.e. add `= Field(strict=False)`+- `Field(strict=False)` does not reach a container's items, so a container of `StrEnum` is written `list[LaxEnum[MyEnum]]` or `dict[LaxEnum[MyEnum], ...]`, with `LaxEnum` from `pipelex/system/configuration/config_model.py`. A `mode="before"` validator never assumes the raw value's type: it returns a value of an unexpected type untouched so the field's own type refuses it, and raises only `ValueError`, since pydantic turns no other exception into a validation error.- **Important**: NEVER EVER set default values for config attributes in the class definition. All the default values are defined in the main config file `pipelex/pipelex.toml`. The only exception si for Optional values which must be set to `None` in the class definition.- If (and only if) you add some config that will clearly make sense for client projects to override, for instance if it's a case of user preference, then you can also add a copy of the settings to the project override config file `.pipelex/pipelex.toml`. NEVER add them commented out: commented-out TOML is never parsed or validated, so it rots silently when keys are refactored. Instead, write the actual default values (matching `pipelex/pipelex.toml`, even empty ones like `activity_queues = {}`) so the override file stays valid and behaves like setting nothing. Plain prose comments explaining the setting are fine — it's commented-out keys/values that are forbidden.- The different `pipelex.toml` files and the python model `configs.py` must be up to date with each other in terms of structure and attributes, otherwise the loading of teh config fails. To check quickly that you're good, just run `make tb` which tests the boot sequence, which includes the config loading.diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 7a4599a90..1e4860182 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -15,12 +15,18 @@- **The API server's refusals of a caller's credentials log at `DEBUG` (Breaking)**: a request with no bearer token, an expired or invalid token or a wrong API key logs `A caller's credentials were refused` at `DEBUG`, with `auth_mode` and `auth_refusal_reason` (`missing_bearer_token`, `expired_token`, `invalid_token` or `api_key_mismatch`), since the error line the server writes at `WARNING` for every `401` already records the refusal. A token that verifies but whose `user_id` claim is missing, not a path-safe segment or the reserved single-tenant id still logs at `WARNING`, its `user_action` telling the token issuer what to fix, and an unset `JWT_SECRET_KEY` or `API_KEY` logs at `ERROR` with the variable's name in `env_var`. An alert on the old authentication warnings counts the `401` error lines instead.- **Exceptions ride as fields at every level**: a `DEBUG` or `VERBOSE` line about a handled exception, such as a Google client that could not be closed, has a fixed message and carries the exception's class and text as `error.type` and `error.message`, as the lines at `INFO` and above already did, rather than splicing them into its text. The retry line names the class of what the attempt raised under `error.type` rather than `exception_type`.- **`make check-log-calls` holds a message's wording and its exceptions**: the log-call guard also refuses, at every level, a message that starts with a lowercase letter, ends with a period or an ellipsis, holds a backtick or splices a handled exception into its text, through an f-string, a `%`, a `.format()` or a task's `exception()`, and, at `INFO` and above, a message that holds an identifier, a word with an underscore or a call such as `setup()`, or runs past 80 characters. The rules are `lowercase-start`, `trailing-period`, `backtick`, `spliced-exception`, `identifier` and `length`, specified on the log-call guard's page of the contributor documentation, and every call in the tree passes them with an empty baseline.+- **A refused enum value names the valid ones**: a validation error for an unknown enum value, in a configuration file or anywhere else Pipelex formats pydantic's errors, now lists the values the field accepts, `invalid enum value 'inptu', expected 'input', 'input_cached', …`, where it used to name only the refused value.### Fixed- **A Google client's close at teardown is no longer garbage-collected**: when a Google LLM or image-generation worker was torn down inside a running event loop, nothing but the loop referenced the background task closing its async client, and a loop holds its tasks weakly, so the task could be collected before the client was closed, with the `asyncio` error `Task was destroyed but it is pending!`. Each close task is now held until it is done.- **A condition whose outcome may be skipped declares it**: a PipeCondition routing to an outcome pipe that takes plainly an input the condition declares optional must declare its own output optional, and is refused with `optional_not_handled` otherwise, since a run without that input skips the outcome and resolves the condition's output absent; an outcome the condition's expression chooses only with that input present declares it forced (`!`) instead, since validation does not read the expression. Every name such an outcome always stores in its caller's memory counts as maybe-absent too, so a sequence binding one into a plain output is refused where it used to validate and then resolve absent; the outcome is listed in `liftable_pipes` under its condition, and a `!` input on an outcome counts in the `optional_force_redundant` lint.- **A sequence step that may be skipped keeps what its run may store**: a step an absent input may lift, whose pipe stores a name on some runs only, now leaves that name maybe-absent when a run may store an absence there, so a sequence binding it into a plain output is refused with `optional_not_handled` rather than validating and then resolving absent.+- **A configuration value of the wrong type is a validation error (Breaking)**: a model's `costs`, `listed_constraints`, `valued_constraints` or `rules` in a backend file or in a plugin's internal model, a backend's constraints in `backends.toml`, and `package_log_levels` in `pipelex.toml` no longer crash the boot with a bare `AttributeError` or `TypeError` naming nothing when written as a value of the wrong shape, such as `costs = "free"` or a date; the boot fails with a message naming the field, the model, the backend and the file, or the plugin, and an empty `inference.dry_run.image_urls` is reported the same way. A plugin may set an internal model's `costs` to `None`. Some values that used to be accepted are now refused: a table as `listed_constraints`, a string as `interpreter.scan.excluded_dirs`, a price that is `nan` or infinite, and a `max_tokens` setting that is neither an integer nor `"auto"`, which used to fall back to the model's default.++### Removed++- **`ConfigModelError` and `ConfigModel`'s conversion helpers (Breaking)**: `ConfigModel.transform_dict_str_to_enum`, `transform_dict_of_floats_str_to_enum`, `transform_dict_keys_str_to_enum` and `transform_list_of_str_to_enum` are gone, and with them `ConfigModelError`, which only they raised. A configuration model holding enums in a container annotates them with `LaxEnum` from `pipelex.system.configuration.config_model`, `list[LaxEnum[MyEnum]]`, and pydantic converts the strings itself.### Removeddiff --git a/CLAUDE.md b/CLAUDE.mdindex 2693e3c99..1c69078ae 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -26,6 +26,7 @@- The model is defined in `pipelex/system/configuration/configs.py`, some of the submodels being defined in their respective sub-packages- When adding new configs, place them where it makes most sense, ask the user if you need arbitrage- As per our python standards, use StrEnum for multiple-value enums. In that case they must not be strict pydantic fields, i.e. add `= Field(strict=False)`+- `Field(strict=False)` does not reach a container's items, so a container of `StrEnum` is written `list[LaxEnum[MyEnum]]` or `dict[LaxEnum[MyEnum], ...]`, with `LaxEnum` from `pipelex/system/configuration/config_model.py`. A `mode="before"` validator never assumes the raw value's type: it returns a value of an unexpected type untouched so the field's own type refuses it, and raises only `ValueError`, since pydantic turns no other exception into a validation error.- **Important**: NEVER EVER set default values for config attributes in the class definition. All the default values are defined in the main config file `pipelex/pipelex.toml`. The only exception si for Optional values which must be set to `None` in the class definition.- If (and only if) you add some config that will clearly make sense for client projects to override, for instance if it's a case of user preference, then you can also add a copy of the settings to the project override config file `.pipelex/pipelex.toml`. NEVER add them commented out: commented-out TOML is never parsed or validated, so it rots silently when keys are refactored. Instead, write the actual default values (matching `pipelex/pipelex.toml`, even empty ones like `activity_queues = {}`) so the override file stays valid and behaves like setting nothing. Plain prose comments explaining the setting are fine — it's commented-out keys/values that are forbidden.- The different `pipelex.toml` files and the python model `configs.py` must be up to date with each other in terms of structure and attributes, otherwise the loading of teh config fails. To check quickly that you're good, just run `make tb` which tests the boot sequence, which includes the config loading.diff --git a/docs/configuration/config-technical/inference-backend-config.md b/docs/configuration/config-technical/inference-backend-config.mdindex 0b8b50f2a..ba49d1a9d 100644--- a/docs/configuration/config-technical/inference-backend-config.md+++ b/docs/configuration/config-technical/inference-backend-config.md@@ -209,6 +209,8 @@ costs = { input = 0.04, output = 0.0 }The `[defaults]` table applies to every model of the file, and a model table overrides any key of it.+`costs` maps a cost category, such as `input` or `output`, to a price, which must be a finite number no lower than zero; an empty table, or no `costs` at all, declares no price. Every field is checked against its type when the file loads, so a value of the wrong shape, such as `costs = "free"`, a price written as a string, or a table where `listed_constraints` takes an array, fails the boot with a message naming the field, the model, the backend and the file.+#### One handle, several kinds of modelA handle names one model per model type. The same name may be an LLM and a judgment model at once, and each pipe reaches the kind its family asks for: a `PipeLLM` naming `acme-one` gets the LLM, and a `PipeJudge` naming it gets the judgment model. A table's name is its handle, and TOML forbids declaring a table twice, so the second model of a handle gets a table name of its own and says which handle it serves with `handle`:diff --git a/docs/configuration/config-technical/library-config.md b/docs/configuration/config-technical/library-config.mdindex ccf861199..5558835ef 100644--- a/docs/configuration/config-technical/library-config.md+++ b/docs/configuration/config-technical/library-config.md@@ -289,6 +289,8 @@ To improve performance and avoid loading unnecessary files, Pipelex automaticallFiles in these directories will not be scanned, even if they contain `.mthds` files or structure classes.+The list is the `excluded_dirs` array under `[interpreter.scan]` in `pipelex.toml`, each entry naming a directory; a value that is not an array, such as a single string, fails the boot.+## Project Organization**Golden rule:** Put `.mthds` files where they make sense in YOUR project. Pipelex finds them automatically.diff --git a/docs/errors/config-model-error.md b/docs/errors/config-model-error.mddeleted file mode 100644index 04d32122e..000000000--- a/docs/errors/config-model-error.md+++ /dev/null@@ -1,19 +0,0 @@-----title: "Config model"-description: "Reference for the `ConfigModelError` Pipelex error class."------<!-- pipelex:generated -->--# Config model--| Field | Value |-|---|---|-| `error_type` | `ConfigModelError` |-| `title` | Config model |-| `type_uri` | `https://docs.pipelex.com/latest/errors/config-model-error/` |-| `error_domain` | _(inherited from parent)_ |-| Defined in | `pipelex.system.exceptions` |-| Parent class | [`FatalError`](fatal-error.md) |--[Back to Error Reference](index.md)diff --git a/docs/errors/platform-and-tooling.md b/docs/errors/platform-and-tooling.mdindex 7c8ed9500..7ed448331 100644--- a/docs/errors/platform-and-tooling.md+++ b/docs/errors/platform-and-tooling.md@@ -67,7 +67,6 @@ own page. Classes are grouped by subsystem.## System & configuration-- [`ConfigModelError`](config-model-error.md) — Config model- [`ConfigValidationError`](config-validation-error.md) — Config validation- [`CredentialsError`](credentials-error.md) — Missing or invalid credentials- [`EnvVarNotFoundError`](env-var-not-found-error.md) — Environment variable not setdiff --git a/pipelex/cogt/config_cogt.py b/pipelex/cogt/config_cogt.pyindex 8e6514bfc..293ef22ae 100644--- a/pipelex/cogt/config_cogt.py+++ b/pipelex/cogt/config_cogt.py@@ -1,6 +1,5 @@from pydantic import Field, field_validator-from pipelex.base_exceptions import PipelexConfigErrorfrom pipelex.cogt.exceptions import LLMConfigErrorfrom pipelex.cogt.img_gen.img_gen_job_components import ImgGenJobConfig, ImgGenJobParams, ImgGenJobParamsDefaults, Qualityfrom pipelex.cogt.llm.llm_job_components import ReasoningEffort@@ -42,12 +41,12 @@ class DryRunConfig(ConfigModel):image_urls: list[str]allowed_to_fail_pipes: list[str] = Field(default_factory=list)- @field_validator("image_urls", mode="before")+ @field_validator("image_urls")@classmethoddef validate_image_urls(cls, value: list[str]) -> list[str]:if not value:msg = "inference.dry_run.image_urls must be a non-empty list"- raise PipelexConfigError(msg)+ raise ValueError(msg)return valuediff --git a/pipelex/cogt/llm/llm_setting.py b/pipelex/cogt/llm/llm_setting.pyindex 91cc63eb1..c77b7ced6 100644--- a/pipelex/cogt/llm/llm_setting.py+++ b/pipelex/cogt/llm/llm_setting.py@@ -1,4 +1,4 @@-from typing import Annotated, Literal, Self, Union+from typing import Annotated, Any, Self, Unionfrom pydantic import BeforeValidator, Field, WithJsonSchema, field_validator, model_validator@@ -26,11 +26,11 @@ class LLMSetting(ConfigModel):@field_validator("max_tokens", mode="before")@classmethod- def validate_max_tokens(cls, value: int | Literal["auto"] | None) -> int | None:- if value is None or (isinstance(value, str) and value == "auto"):+ def validate_max_tokens(cls, value: Any) -> Any:+ """`"auto"` means the model's default; any other value is left to the field's own type to accept or refuse."""+ if value == "auto":return None- if isinstance(value, int): # pyright: ignore[reportUnnecessaryIsInstance]- return value+ return value@model_validator(mode="after")def validate_reasoning_effort_or_budget(self) -> Self:diff --git a/pipelex/cogt/model_backends/backend_factory.py b/pipelex/cogt/model_backends/backend_factory.pyindex 328b095bd..53ee6d636 100644--- a/pipelex/cogt/model_backends/backend_factory.py+++ b/pipelex/cogt/model_backends/backend_factory.py@@ -1,12 +1,12 @@from typing import Any-from pydantic import Field, field_validator+from pydantic import Fieldfrom pipelex.cogt.model_backends.backend import InferenceBackendfrom pipelex.cogt.model_backends.constraints import ListedConstraint, ValuedConstraintfrom pipelex.cogt.model_backends.credential_resolution import CredentialResolutionfrom pipelex.cogt.model_backends.model_spec_index import ModelSpecIndex-from pipelex.system.configuration.config_model import ConfigModel+from pipelex.system.configuration.config_model import ConfigModel, LaxEnumfrom pipelex.tools.typing.pydantic_utils import empty_dict_factory_of, empty_list_factory_of@@ -14,26 +14,10 @@ class InferenceBackendBlueprint(ConfigModel):enabled: bool = Trueendpoint: str | None = Noneapi_key: str | None = None- listed_constraints: list[ListedConstraint] = Field(default_factory=empty_list_factory_of(ListedConstraint))- valued_constraints: dict[ValuedConstraint, Any] = Field(default_factory=empty_dict_factory_of(ValuedConstraint))+ listed_constraints: list[LaxEnum[ListedConstraint]] = Field(default_factory=empty_list_factory_of(ListedConstraint))+ valued_constraints: dict[LaxEnum[ValuedConstraint], Any] = Field(default_factory=empty_dict_factory_of(ValuedConstraint))extra_config: dict[str, Any] = Field(default_factory=dict)- @field_validator("listed_constraints", mode="before")- @classmethod- def validate_listed_constraints(cls, value: list[str]) -> list[ListedConstraint]:- return ConfigModel.transform_list_of_str_to_enum(- input_list=value,- enum_cls=ListedConstraint,- )-- @field_validator("valued_constraints", mode="before")- @classmethod- def validate_valued_constraints(cls, value: dict[str, Any]) -> dict[ValuedConstraint, Any]:- return ConfigModel.transform_dict_keys_str_to_enum(- input_dict=value,- key_enum_cls=ValuedConstraint,- )-class InferenceBackendFactory:# The fields Vertex AI derives at boot from its extra config: the endpoint from the project anddiff --git a/pipelex/cogt/model_backends/model_spec_factory.py b/pipelex/cogt/model_backends/model_spec_factory.pyindex a00cc012d..835f10227 100644--- a/pipelex/cogt/model_backends/model_spec_factory.py+++ b/pipelex/cogt/model_backends/model_spec_factory.py@@ -1,15 +1,16 @@+import mathfrom typing import Anyfrom pydantic import BaseModel, Field, field_validator-from pipelex.cogt.img_gen.img_gen_model_rules import ImgGenArgTopic, ImgGenModelRules+from pipelex.cogt.img_gen.img_gen_model_rules import ImgGenArgTopicfrom pipelex.cogt.llm.structured_output import StructureMethodfrom pipelex.cogt.llm.thinking_mode import ThinkingModefrom pipelex.cogt.model_backends.constraints import ListedConstraint, ValuedConstraintfrom pipelex.cogt.model_backends.model_spec import InferenceModelSpecfrom pipelex.cogt.model_backends.model_type import DEFAULT_MODEL_TYPE, ModelTypefrom pipelex.cogt.usage.cost_category import CostCategory, CostsByCategoryDict-from pipelex.system.configuration.config_model import ConfigModel+from pipelex.system.configuration.config_model import ConfigModel, LaxEnumfrom pipelex.tools.typing.pydantic_utils import empty_dict_factory_of, empty_list_factory_ofBackendModelSpecs = dict[str, Any]@@ -27,55 +28,29 @@ class InferenceModelSpecBlueprint(ConfigModel):model_id: str | None = Noneinputs: list[str] = Field(default_factory=list)outputs: list[str] = Field(default_factory=list)- costs: CostsByCategoryDict | None = Field(default=None, strict=False)+ costs: dict[LaxEnum[CostCategory], float] | None = Nonestructure_method: StructureMethod | None = Field(default=None, strict=False)thinking_mode: ThinkingMode = Field(default=ThinkingMode.NONE, strict=False)max_tokens: int | None = Nonemax_prompt_images: int | None = None- listed_constraints: list[ListedConstraint] = Field(default_factory=empty_list_factory_of(ListedConstraint))- valued_constraints: dict[ValuedConstraint, Any] = Field(default_factory=empty_dict_factory_of(ValuedConstraint))- rules: ImgGenModelRules | None = None+ listed_constraints: list[LaxEnum[ListedConstraint]] = Field(default_factory=empty_list_factory_of(ListedConstraint))+ valued_constraints: dict[LaxEnum[ValuedConstraint], Any] = Field(default_factory=empty_dict_factory_of(ValuedConstraint))+ # The shared `ImgGenModelRules` stays strict: the code that consumes it holds real enums.+ rules: dict[LaxEnum[ImgGenArgTopic], str] | None = None# Provider-side route for models a worker calls by raw path (no kit backend declares one; an out-of-tree plugin may). Our own# routing metadata, not a request header — which is why it is a declared field and not an `extra_headers` entry.endpoint_path: str | None = None- @field_validator("rules", mode="before")- @staticmethod- def validate_rules(value: dict[str, str] | None) -> ImgGenModelRules | None:+ @field_validator("costs")+ @classmethod+ def validate_costs(cls, value: CostsByCategoryDict | None) -> CostsByCategoryDict | None:if value is None:return None- return ConfigModel.transform_dict_keys_str_to_enum(- input_dict=value,- key_enum_cls=ImgGenArgTopic,- )-- @field_validator("costs", mode="before")- @staticmethod- def validate_costs(value: dict[str, float]) -> CostsByCategoryDict:- negative_costs = {key: val for key, val in value.items() if val < 0}- if negative_costs:- msg = f"Cost values must not be negative, got: {negative_costs}"+ invalid_costs = {str(key): val for key, val in value.items() if not (math.isfinite(val) and val >= 0)}+ if invalid_costs:+ msg = f"Cost values must be finite and not negative, got: {invalid_costs}"raise ValueError(msg)- return ConfigModel.transform_dict_of_floats_str_to_enum(- input_dict=value,- key_enum_cls=CostCategory,- )-- @field_validator("listed_constraints", mode="before")- @staticmethod- def validate_listed_constraints(value: list[str]) -> list[ListedConstraint]:- return ConfigModel.transform_list_of_str_to_enum(- input_list=value,- enum_cls=ListedConstraint,- )-- @field_validator("valued_constraints", mode="before")- @staticmethod- def validate_valued_constraints(value: dict[str, Any]) -> dict[ValuedConstraint, Any]:- return ConfigModel.transform_dict_keys_str_to_enum(- input_dict=value,- key_enum_cls=ValuedConstraint,- )+ return valueclass InferenceModelSpecFactory(BaseModel):diff --git a/pipelex/exceptions.py b/pipelex/exceptions.pyindex 7cb2c92e8..77876940a 100644--- a/pipelex/exceptions.py+++ b/pipelex/exceptions.py@@ -47,7 +47,6 @@ from pipelex.pipeline.exceptions import (PipeStackOverflowError,)from pipelex.system.exceptions import (- ConfigModelError,ConfigValidationError,CredentialsError,FatalError,@@ -119,5 +118,4 @@ __all__ = ["FatalError","MissingDependencyError","ConfigValidationError",- "ConfigModelError",]diff --git a/pipelex/kit/agent_rules/pipelex_standards.md b/pipelex/kit/agent_rules/pipelex_standards.mdindex 424f4d2bc..b7953690c 100644--- a/pipelex/kit/agent_rules/pipelex_standards.md+++ b/pipelex/kit/agent_rules/pipelex_standards.md@@ -10,6 +10,7 @@- The model is defined in `pipelex/system/configuration/configs.py`, some of the submodels being defined in their respective sub-packages- When adding new configs, place them where it makes most sense, ask the user if you need arbitrage- As per our python standards, use StrEnum for multiple-value enums. In that case they must not be strict pydantic fields, i.e. add `= Field(strict=False)`+- `Field(strict=False)` does not reach a container's items, so a container of `StrEnum` is written `list[LaxEnum[MyEnum]]` or `dict[LaxEnum[MyEnum], ...]`, with `LaxEnum` from `pipelex/system/configuration/config_model.py`. A `mode="before"` validator never assumes the raw value's type: it returns a value of an unexpected type untouched so the field's own type refuses it, and raises only `ValueError`, since pydantic turns no other exception into a validation error.- **Important**: NEVER EVER set default values for config attributes in the class definition. All the default values are defined in the main config file `pipelex/pipelex.toml`. The only exception si for Optional values which must be set to `None` in the class definition.- If (and only if) you add some config that will clearly make sense for client projects to override, for instance if it's a case of user preference, then you can also add a copy of the settings to the project override config file `.pipelex/pipelex.toml`. NEVER add them commented out: commented-out TOML is never parsed or validated, so it rots silently when keys are refactored. Instead, write the actual default values (matching `pipelex/pipelex.toml`, even empty ones like `activity_queues = {}`) so the override file stays valid and behaves like setting nothing. Plain prose comments explaining the setting are fine — it's commented-out keys/values that are forbidden.- The different `pipelex.toml` files and the python model `configs.py` must be up to date with each other in terms of structure and attributes, otherwise the loading of teh config fails. To check quickly that you're good, just run `make tb` which tests the boot sequence, which includes the config loading.diff --git a/pipelex/system/configuration/config_model.py b/pipelex/system/configuration/config_model.pyindex 83b29dc6e..b7d141d55 100644--- a/pipelex/system/configuration/config_model.py+++ b/pipelex/system/configuration/config_model.py@@ -1,84 +1,16 @@from enum import StrEnum-from typing import Any, TypeVar+from typing import Annotated, TypeAlias, TypeVar-from pydantic import BaseModel, ConfigDict--from pipelex.system.exceptions import ConfigModelError+from pydantic import BaseModel, ConfigDict, StrictStrEnumType = TypeVar("StrEnumType", bound=StrEnum)+# A `StrEnum` read leniently, so a TOML string converts to its member, inside a container that stays strict.+# `Field(strict=False)` on a field does not reach a container's items: `list[MyEnum] = Field(strict=False)`+# still refuses `["a_member"]`. Write `list[LaxEnum[MyEnum]]` or `dict[LaxEnum[MyEnum], ...]` instead, and+# never convert the items by hand in a `mode="before"` validator, which would see the raw value of any type.+LaxEnum: TypeAlias = Annotated[StrEnumType, Strict(False)]+class ConfigModel(BaseModel):model_config = ConfigDict(extra="forbid", strict=True)-- @staticmethod- def transform_dict_str_to_enum(- input_dict: dict[str, str],- *,- key_enum_cls: type[StrEnumType] | None = None,- value_enum_cls: type[StrEnumType] | None = None,- ) -> dict[str, StrEnumType] | dict[StrEnumType, str] | dict[StrEnumType, StrEnumType]:- """Transforms a dictionary with str values into a dictionary with enum values.-- Args:- input_dict: Dictionary with string values to be transformed.- key_enum_cls: The StrEnum class to convert the keys to (if needed)- value_enum_cls: The StrEnum class to convert the values to (if needed).-- Returns:- A dictionary where the values are converted to the given StrEnum type.-- """- # return {key: value_enum_cls(value) for key, value in input_dict.items()}- if key_enum_cls and value_enum_cls:- return {key_enum_cls(key): value_enum_cls(value) for key, value in input_dict.items()}- if key_enum_cls:- return {key_enum_cls(key): value for key, value in input_dict.items()}- if value_enum_cls:- return {key: value_enum_cls(value) for key, value in input_dict.items()}- msg = "Either key_enum_cls or value_enum_cls must be provided."- raise ConfigModelError(msg)-- @staticmethod- def transform_dict_of_floats_str_to_enum(- input_dict: dict[str, float],- *,- key_enum_cls: type[StrEnumType],- ) -> dict[StrEnumType, float]:- """Transforms a dictionary with str keys and float values into a dictionary with enum keys and float values.-- Args:- input_dict: Dictionary with string values to be transformed.- key_enum_cls: The StrEnum class to convert the keys to-- Returns:- A dictionary where the keys are converted to the given StrEnum type.-- """- return {key_enum_cls(key): value for key, value in input_dict.items()}-- @staticmethod- def transform_dict_keys_str_to_enum(- input_dict: dict[str, Any],- *,- key_enum_cls: type[StrEnumType],- ) -> dict[StrEnumType, Any]:- """Transforms a dictionary with str keys and Any values into a dictionary with enum keys and Any values.-- Args:- input_dict: Dictionary with string keys to be transformed.- key_enum_cls: The StrEnum class to convert the keys to-- Returns:- A dictionary where the keys are converted to the given StrEnum type.-- """- return {key_enum_cls(key): value for key, value in input_dict.items()}-- @staticmethod- def transform_list_of_str_to_enum(- input_list: list[str],- *,- enum_cls: type[StrEnumType],- ) -> list[StrEnumType]:- return [enum_cls(item) for item in input_list]diff --git a/pipelex/system/configuration/configs.py b/pipelex/system/configuration/configs.pyindex 175439106..ff56c3d33 100644--- a/pipelex/system/configuration/configs.py+++ b/pipelex/system/configuration/configs.py@@ -95,14 +95,8 @@ class ObserverConfig(ConfigModel):class ScanConfig(ConfigModel):- excluded_dirs: frozenset[str]-- @field_validator("excluded_dirs", mode="before")- @classmethod- def validate_excluded_dirs(cls, value: list[str] | frozenset[str]) -> frozenset[str]:- if isinstance(value, frozenset):- return value- return frozenset(value)+ # Lax so the TOML array converts to a set; a string or a number is still refused.+ excluded_dirs: frozenset[str] = Field(strict=False)class BuilderConfig(ConfigModel):diff --git a/pipelex/system/exceptions.py b/pipelex/system/exceptions.pyindex a8fddaa58..d913d8bf2 100644--- a/pipelex/system/exceptions.py+++ b/pipelex/system/exceptions.py@@ -66,7 +66,3 @@ class FatalError(TracebackMessageError):class ConfigValidationError(FatalError):pass---class ConfigModelError(FatalError, ValueError):- passdiff --git a/pipelex/tools/log/log_config.py b/pipelex/tools/log/log_config.pyindex 97019b2cf..c7ffacbd2 100644--- a/pipelex/tools/log/log_config.py+++ b/pipelex/tools/log/log_config.py@@ -2,11 +2,10 @@ from __future__ import annotationsimport refrom enum import StrEnum-from typing import castfrom pydantic import Field, field_validator-from pipelex.system.configuration.config_model import ConfigModel+from pipelex.system.configuration.config_model import ConfigModel, LaxEnumfrom pipelex.system.console_target import ConsoleTargetfrom pipelex.tools.log.log_levels import LogLevelfrom pipelex.tools.misc.pretty import PrettyPrintMode@@ -141,7 +140,7 @@ class LogRedactionConfig(ConfigModel):class LogConfig(ConfigModel):default_log_level: LogLevel = Field(strict=False)- package_log_levels: dict[str, LogLevel]+ package_log_levels: dict[str, LaxEnum[LogLevel]]# The registered log-sink token boot selects: an open string, validated at the registry lookup.sink: strpretty_print_mode: PrettyPrintMode = Field(strict=False)@@ -159,11 +158,3 @@ class LogConfig(ConfigModel):rich_log: RichLogConfigotlp: OtlpLogSinkConfiggcp: GcpLogSinkConfig-- @field_validator("package_log_levels", mode="before")- @classmethod- def validate_package_log_levels(cls, value: dict[str, str]) -> dict[str, LogLevel]:- return cast(- "dict[str, LogLevel]",- ConfigModel.transform_dict_str_to_enum(input_dict=value, value_enum_cls=LogLevel),- )diff --git a/pipelex/tools/typing/pydantic_utils.py b/pipelex/tools/typing/pydantic_utils.pyindex 2fead90f7..1d13db247 100644--- a/pipelex/tools/typing/pydantic_utils.py+++ b/pipelex/tools/typing/pydantic_utils.py@@ -87,9 +87,12 @@ def analyze_pydantic_validation_error(exc: ValidationError) -> PydanticValidatioextra_fields = [f"'{'.'.join(map(str, err['loc']))}'" for err in exc.errors() if err["type"] == "extra_forbidden"]type_errors = [f"'{'.'.join(map(str, err['loc']))}': expected {err['type']}" for err in exc.errors() if err["type"] == "type_error"]value_errors = [f"'{'.'.join(map(str, err['loc']))}': {err['msg']}" for err in exc.errors() if err["type"] == "value_error"]- enum_errors = [- f"'{'.'.join(map(str, err['loc']))}': invalid enum value '{err.get('input', 'unknown')}'" for err in exc.errors() if err["type"] == "enum"- ]+ enum_errors: list[str] = []+ for err in exc.errors():+ if err["type"] == "enum":+ field_path = ".".join(map(str, err["loc"]))+ expected = err.get("ctx", {}).get("expected", "unknown")+ enum_errors.append(f"'{field_path}': invalid enum value '{err.get('input', 'unknown')}', expected {expected}")literal_errors: list[str] = []for err in exc.errors():if err["type"] == "literal_error":diff --git a/subject_grants.toml b/subject_grants.tomlindex 1a4b19c26..54d2341dc 100644--- a/subject_grants.toml+++ b/subject_grants.toml@@ -5332,22 +5332,6 @@ rationale = "Verb-object: searches upward from the start dir; single operand."param = "relative_path"rationale = "Verb-object: resolves the relative path; single operand."-["pipelex/system/configuration/config_model.py::ConfigModel.transform_dict_keys_str_to_enum"]-param = "input_dict"-rationale = "Verb-object: transforms the input dict; enum class stays keyword."--["pipelex/system/configuration/config_model.py::ConfigModel.transform_dict_of_floats_str_to_enum"]-param = "input_dict"-rationale = "Verb-object: transforms the input dict; enum class stays keyword."--["pipelex/system/configuration/config_model.py::ConfigModel.transform_dict_str_to_enum"]-param = "input_dict"-rationale = "Verb-object: transforms the input dict; enum class stays keyword."--["pipelex/system/configuration/config_model.py::ConfigModel.transform_list_of_str_to_enum"]-param = "input_list"-rationale = "Verb-object: transforms the input list; enum class stays keyword."-["pipelex/system/environment.py::all_env_vars_are_set"]param = "keys"rationale = "Predicate on the given env-var keys; single operand."diff --git a/tests/data/errors/error_identity.txt b/tests/data/errors/error_identity.txtindex e05bbfe28..b4a0e7941 100644--- a/tests/data/errors/error_identity.txt+++ b/tests/data/errors/error_identity.txt@@ -39,7 +39,6 @@ ConceptRefineError | Concept refine | https://docs.pipelex.com/latest/errors/conConceptStringError | Concept string | https://docs.pipelex.com/latest/errors/concept-string-error/ConceptStructureGeneratorError | Concept structure generator | https://docs.pipelex.com/latest/errors/concept-structure-generator-error/ConceptStructureValidationError | Concept structure validation | https://docs.pipelex.com/latest/errors/concept-structure-validation-error/-ConfigModelError | Config model | https://docs.pipelex.com/latest/errors/config-model-error/ConfigValidationError | Config validation | https://docs.pipelex.com/latest/errors/config-validation-error/ConstructFieldBlueprintTypeError | Construct field blueprint type | https://docs.pipelex.com/latest/errors/construct-field-blueprint-type-error/ConstructFieldBlueprintValueError | Construct field blueprint value | https://docs.pipelex.com/latest/errors/construct-field-blueprint-value-error/diff --git a/tests/unit/pipelex/cogt/model_backends/test_backend_library_member_types.py b/tests/unit/pipelex/cogt/model_backends/test_backend_library_member_types.pynew file mode 100644index 000000000..5c5b78e56--- /dev/null+++ b/tests/unit/pipelex/cogt/model_backends/test_backend_library_member_types.py@@ -0,0 +1,136 @@+"""A model or backend member written as a value of the wrong type is a validation error naming the model, the backend and the file.++Each of these used to crash the load with a bare `AttributeError` or `TypeError` that named nothing, or to+be accepted silently, because the members were converted by hand before pydantic had checked their type.+"""++from pathlib import Path++import pytest++from pipelex.cogt.exceptions import InferenceBackendLibraryError, InferenceBackendLibraryValidationError+from pipelex.cogt.img_gen.img_gen_model_rules import ImgGenArgTopic+from pipelex.cogt.model_backends.constraints import ListedConstraint, ValuedConstraint+from pipelex.cogt.model_backends.credential_resolution import CredentialResolution+from pipelex.cogt.model_backends.model_type import ModelType+from pipelex.cogt.usage.cost_category import CostCategory+from tests.helpers.backend_library_loading import BOTH_MODES, load_library, required_backend+from tests.unit.pipelex.cogt.model_backends.test_data import BackendLibraryTomls+++class TestAMemberOfTheWrongTypeIsRefusedCleanly:+ @pytest.mark.parametrize("credentials", BOTH_MODES)+ @pytest.mark.parametrize(+ ("member_line", "field_name", "expected_fragment"),+ [+ pytest.param('costs = "free"', "costs", "Input should be a valid dictionary", id="costs_as_a_string"),+ pytest.param("costs = 1979-05-27", "costs", "Input should be a valid dictionary", id="costs_as_a_date"),+ pytest.param('costs = { input = "free" }', "costs.input", "Input should be a valid number", id="costs_with_a_string_price"),+ pytest.param("costs = { input = nan }", "costs", "must be finite and not negative", id="costs_with_a_nan_price"),+ pytest.param("costs = { input = inf }", "costs", "must be finite and not negative", id="costs_with_an_infinite_price"),+ pytest.param("costs = { input = -1.5 }", "costs", "must be finite and not negative", id="costs_with_a_negative_price"),+ pytest.param(+ "costs = { inptu = 1.5 }",+ "costs.inptu",+ "invalid enum value 'inptu', expected 'input', 'input_cached',",+ id="costs_with_an_unknown_category",+ ),+ pytest.param("listed_constraints = 1979-05-27", "listed_constraints", "Input should be a valid list", id="listed_constraints_as_a_date"),+ pytest.param('listed_constraints = "abc"', "listed_constraints", "Input should be a valid list", id="listed_constraints_as_a_string"),+ pytest.param(+ "listed_constraints = { temperature_unsupported = true }",+ "listed_constraints",+ "Input should be a valid list",+ id="listed_constraints_as_a_table",+ ),+ pytest.param('valued_constraints = "x"', "valued_constraints", "Input should be a valid dictionary", id="valued_constraints_as_a_string"),+ pytest.param("valued_constraints = []", "valued_constraints", "Input should be a valid dictionary", id="valued_constraints_as_an_array"),+ pytest.param("rules = 1979-05-27", "rules", "Input should be a valid dictionary", id="rules_as_a_date"),+ pytest.param('rules = "x"', "rules", "Input should be a valid dictionary", id="rules_as_a_string"),+ ],+ )+ def test_a_model_member_of_the_wrong_type_is_refused_naming_the_model(+ self, tmp_path: Path, credentials: CredentialResolution, member_line: str, field_name: str, expected_fragment: str+ ) -> None:+ with pytest.raises(InferenceBackendLibraryError) as exc_info:+ load_library(+ tmp_path,+ backends_toml=BackendLibraryTomls.BACKENDS_TOML,+ model_specs_toml=BackendLibraryTomls.model_specs_toml_with_member(member_line=member_line),+ credentials=credentials,+ )++ message = str(exc_info.value)+ assert "Invalid inference model spec 'acme-one' for backend 'acme'" in message+ assert "acme.toml" in message+ assert field_name in message+ assert expected_fragment in message++ def test_members_written_as_the_kit_files_write_them_still_load_as_enums(self, tmp_path: Path) -> None:+ """The control: strings naming enum members are converted to the enums, and a model may leave `costs` out."""+ library = load_library(+ tmp_path,+ backends_toml=BackendLibraryTomls.backends_toml_with_member(member_line="valued_constraints = { min_thinking_budget = 1024 }"),+ model_specs_toml=BackendLibraryTomls.model_specs_toml_with_member(+ member_line=(+ 'listed_constraints = ["temperature_unsupported"]\n'+ "valued_constraints = { fixed_temperature = 1 }\n"+ "costs = { input = 1.5, output = 0 }\n"+ 'rules = { prompt = "positive_only" }'+ )+ ),+ credentials=CredentialResolution.REQUIRE,+ )++ model_spec = required_backend(library).get_model_spec(model_type=ModelType.LLM, handle="acme-one")+ assert model_spec is not None+ assert model_spec.listed_constraints == [ListedConstraint.TEMPERATURE_UNSUPPORTED]+ assert model_spec.valued_constraints == {ValuedConstraint.MIN_THINKING_BUDGET: 1024, ValuedConstraint.FIXED_TEMPERATURE: 1}+ assert model_spec.costs == {CostCategory.INPUT: 1.5, CostCategory.OUTPUT: 0}+ assert model_spec.rules == {ImgGenArgTopic.PROMPT: "positive_only"}+ assert all(type(key) is ValuedConstraint for key in model_spec.valued_constraints)+ assert all(type(key) is CostCategory for key in model_spec.costs)+ assert model_spec.rules is not None+ assert all(type(key) is ImgGenArgTopic for key in model_spec.rules)++ def test_a_model_may_leave_costs_out(self, tmp_path: Path) -> None:+ library = load_library(+ tmp_path,+ backends_toml=BackendLibraryTomls.BACKENDS_TOML,+ model_specs_toml=BackendLibraryTomls.MODEL_SPECS_TOML,+ credentials=CredentialResolution.REQUIRE,+ )++ model_spec = required_backend(library).get_model_spec(model_type=ModelType.LLM, handle="acme-one")+ assert model_spec is not None+ assert model_spec.costs == {}++ @pytest.mark.parametrize("credentials", BOTH_MODES)+ @pytest.mark.parametrize(+ ("member_line", "field_name", "expected_fragment"),+ [+ pytest.param("listed_constraints = 1979-05-27", "listed_constraints", "Input should be a valid list", id="listed_constraints_as_a_date"),+ pytest.param(+ "listed_constraints = { temperature_unsupported = true }",+ "listed_constraints",+ "Input should be a valid list",+ id="listed_constraints_as_a_table",+ ),+ pytest.param('valued_constraints = "x"', "valued_constraints", "Input should be a valid dictionary", id="valued_constraints_as_a_string"),+ ],+ )+ def test_a_backend_member_of_the_wrong_type_is_refused_naming_the_backend(+ self, tmp_path: Path, credentials: CredentialResolution, member_line: str, field_name: str, expected_fragment: str+ ) -> None:+ with pytest.raises(InferenceBackendLibraryValidationError) as exc_info:+ load_library(+ tmp_path,+ backends_toml=BackendLibraryTomls.backends_toml_with_member(member_line=member_line),+ model_specs_toml=BackendLibraryTomls.MODEL_SPECS_TOML,+ credentials=credentials,+ )++ message = str(exc_info.value)+ assert "Invalid inference backend 'acme'" in message+ assert field_name in message+ assert expected_fragment in messagediff --git a/tests/unit/pipelex/cogt/model_backends/test_data.py b/tests/unit/pipelex/cogt/model_backends/test_data.pyindex f4b73c7df..cea8f3fdc 100644--- a/tests/unit/pipelex/cogt/model_backends/test_data.py+++ b/tests/unit/pipelex/cogt/model_backends/test_data.py@@ -217,3 +217,13 @@ sdk = "openai_responses"["acme-one"]model_id = "${secrte:ACME_MODEL}""""++ @classmethod+ def model_specs_toml_with_member(cls, *, member_line: str) -> str:+ """`MODEL_SPECS_TOML` with one more member on its `acme-one` table, which is the file's last."""+ return f"{cls.MODEL_SPECS_TOML}{member_line}\n"++ @classmethod+ def backends_toml_with_member(cls, *, member_line: str) -> str:+ """`BACKENDS_TOML` with one more member on its `acme` table, which is the file's last."""+ return f"{cls.BACKENDS_TOML}{member_line}\n"diff --git a/tests/unit/pipelex/cogt/model_backends/test_model_spec_document.py b/tests/unit/pipelex/cogt/model_backends/test_model_spec_document.pyindex 8fcb36f58..073329b4f 100644--- a/tests/unit/pipelex/cogt/model_backends/test_model_spec_document.py+++ b/tests/unit/pipelex/cogt/model_backends/test_model_spec_document.py@@ -97,3 +97,23 @@ class TestABackendFileIsADocumentNotAModel:)def test_a_root_key_whose_value_is_not_a_table_is_refused(self, document: dict[str, Any]) -> None:assert describe_model_spec_document_rejection(document=document) is not None++ @pytest.mark.parametrize(+ ("field_name", "value"),+ [+ pytest.param("costs", "free", id="costs_as_a_string"),+ pytest.param("costs", {"input": "free"}, id="costs_with_a_string_price"),+ pytest.param("listed_constraints", 5, id="listed_constraints_as_a_number"),+ pytest.param("valued_constraints", [], id="valued_constraints_as_an_array"),+ pytest.param("rules", "x", id="rules_as_a_string"),+ ],+ )+ def test_a_member_of_the_wrong_type_is_a_rejection_not_a_crash(self, field_name: str, value: Any) -> None:+ """The migration gate reports the reason; a bare `AttributeError` or `TypeError` used to escape it instead."""+ document: dict[str, Any] = {"defaults": {"sdk": "openai"}, "gpt-4o": {field_name: value}}++ rejection = describe_model_spec_document_rejection(document=document)++ assert rejection is not None+ assert "gpt-4o" in rejection+ assert field_name in rejectiondiff --git a/tests/unit/pipelex/cogt/models/test_plugin_model_merge.py b/tests/unit/pipelex/cogt/models/test_plugin_model_merge.pyindex 0f43dcff9..714eac2a1 100644--- a/tests/unit/pipelex/cogt/models/test_plugin_model_merge.py+++ b/tests/unit/pipelex/cogt/models/test_plugin_model_merge.py@@ -164,6 +164,36 @@ class TestPluginModelMerge:with pytest.raises(PluginModelDeclarationError, match="Plugin 'doc-gen' declares the internal model 'pipelex-xlsx'"):self._setup(inference_dir=inference_dir, plugin_model_declarations=declarations)+ def test_a_plugin_model_may_set_costs_to_none(self, inference_dir: Path) -> None:+ """A plugin builds its table in Python, where an absent price list is naturally `None`."""+ declarations = _declarations(internal_models={"pipelex-xlsx": {**PIPELEX_XLSX_SPEC, "costs": None}}, doc_gen_defaults={})++ model_deck = self._setup(inference_dir=inference_dir, plugin_model_declarations=declarations).get_model_deck()++ assert model_deck.get_required_inference_model(model_handle="pipelex-xlsx", model_type=ModelType.DOC_GEN).costs == {}++ @pytest.mark.parametrize(+ ("field_name", "value"),+ [+ pytest.param("costs", "free", id="costs_as_a_string"),+ pytest.param("costs", {"input": None}, id="costs_with_a_none_price"),+ pytest.param("listed_constraints", None, id="listed_constraints_as_none"),+ pytest.param("valued_constraints", None, id="valued_constraints_as_none"),+ pytest.param("rules", [], id="rules_as_a_list"),+ ],+ )+ def test_a_plugin_member_of_the_wrong_type_fails_the_boot_naming_the_plugin(self, inference_dir: Path, field_name: str, value: Any) -> None:+ """These used to escape the merge as a bare `AttributeError` or `TypeError` naming no plugin."""+ declarations = _declarations(internal_models={"pipelex-xlsx": {**PIPELEX_XLSX_SPEC, field_name: value}}, doc_gen_defaults={})++ with pytest.raises(PluginModelDeclarationError) as exc_info:+ self._setup(inference_dir=inference_dir, plugin_model_declarations=declarations)++ assert exc_info.value.plugin == "doc-gen"+ message = str(exc_info.value)+ assert "Plugin 'doc-gen' declares the internal model 'pipelex-xlsx'" in message+ assert field_name in message+def test_a_plugin_default_no_step_uses_fails_the_boot_naming_the_plugin(self, inference_dir: Path) -> None:declarations = _declarations(internal_models={}, doc_gen_defaults={(DocGenFormat.PPTX, DocGenSource.LAYOUT): "pipelex-pptx"})diff --git a/tests/unit/pipelex/system/configuration/config_section_utils.py b/tests/unit/pipelex/system/configuration/config_section_utils.pynew file mode 100644index 000000000..a396e3f23--- /dev/null+++ b/tests/unit/pipelex/system/configuration/config_section_utils.py@@ -0,0 +1,14 @@+"""Sections of the package's own `pipelex.toml`, the valid documents the member-type tests each spoil one member of."""++import tomllib+from typing import Any++from pipelex.system.configuration.config_loader import CONFIG_NAME, ConfigLoader+++def base_config_section(*section_path: str) -> dict[str, Any]:+ """A section of the package's own `pipelex.toml`, the valid document each test spoils one member of."""+ section: dict[str, Any] = tomllib.loads((ConfigLoader().pipelex_root_dir / CONFIG_NAME).read_text(encoding="utf-8"))+ for key in section_path:+ section = section[key]+ return sectiondiff --git a/tests/unit/pipelex/system/configuration/test_config_dry_run_image_urls.py b/tests/unit/pipelex/system/configuration/test_config_dry_run_image_urls.pynew file mode 100644index 000000000..1433d81ea--- /dev/null+++ b/tests/unit/pipelex/system/configuration/test_config_dry_run_image_urls.py@@ -0,0 +1,18 @@+"""`inference.dry_run.image_urls` is a non-empty list of URLs, and anything else is refused as a validation error."""++import pytest+from pydantic import ValidationError++from pipelex.cogt.config_cogt import DryRunConfig+from tests.unit.pipelex.system.configuration.config_section_utils import base_config_section+++class TestDryRunConfigImageUrls:+ def test_an_empty_list_is_a_validation_error(self) -> None:+ """It used to raise a bare `PipelexConfigError` from inside the validator, which escaped the config load's wrap."""+ with pytest.raises(ValidationError, match=r"inference\.dry_run\.image_urls must be a non-empty list"):+ DryRunConfig.model_validate({**base_config_section("inference", "dry_run"), "image_urls": []})++ def test_a_string_is_refused(self) -> None:+ with pytest.raises(ValidationError, match="Input should be a valid list"):+ DryRunConfig.model_validate({**base_config_section("inference", "dry_run"), "image_urls": "https://example.com/a.png"})diff --git a/tests/unit/pipelex/system/configuration/test_config_llm_setting_max_tokens.py b/tests/unit/pipelex/system/configuration/test_config_llm_setting_max_tokens.pynew file mode 100644index 000000000..018a71a13--- /dev/null+++ b/tests/unit/pipelex/system/configuration/test_config_llm_setting_max_tokens.py@@ -0,0 +1,27 @@+"""An LLM setting's `max_tokens` is an integer, `"auto"` or absent; any other value is refused.++Any other value used to be turned into the model's default without a word.+"""++from typing import Any++import pytest+from pydantic import ValidationError++from pipelex.cogt.llm.llm_setting import LLMSetting+++class TestLLMSettingMaxTokens:+ @pytest.mark.parametrize(("value", "expected"), [(None, None), ("auto", None), (4096, 4096)])+ def test_none_auto_and_an_integer_are_accepted(self, value: Any, expected: int | None) -> None:+ assert LLMSetting.model_validate({"model": "test-model", "temperature": 0.5, "max_tokens": value}).max_tokens == expected++ @pytest.mark.parametrize(+ "value",+ [pytest.param("foo", id="a_string"), pytest.param(3.5, id="a_float"), pytest.param(True, id="a_boolean")],+ )+ def test_any_other_value_is_refused_rather_than_read_as_the_default(self, value: Any) -> None:+ with pytest.raises(ValidationError) as exc_info:+ LLMSetting.model_validate({"model": "test-model", "temperature": 0.5, "max_tokens": value})++ assert exc_info.value.errors()[0]["loc"][0] == "max_tokens"diff --git a/tests/unit/pipelex/system/configuration/test_config_load_wrong_typed_member.py b/tests/unit/pipelex/system/configuration/test_config_load_wrong_typed_member.pynew file mode 100644index 000000000..ca1bc4e17--- /dev/null+++ b/tests/unit/pipelex/system/configuration/test_config_load_wrong_typed_member.py@@ -0,0 +1,37 @@+"""A `pipelex.toml` member of the wrong type fails the config load with the loader's own error.++The boot catches the loader's `ConfigValidationError`; a bare `AttributeError` raised by a `mode="before"`+validator used to escape it.+"""++from __future__ import annotations++from pathlib import Path+from typing import TYPE_CHECKING++import pytest++from pipelex.system.configuration.config_loader import CONFIG_NAME, ConfigLoader+from pipelex.system.configuration.configs import PipelexConfig+from pipelex.system.exceptions import ConfigValidationError++if TYPE_CHECKING:+ from pytest_mock import MockerFixture++[email protected]("no_pipelex_home")+class TestTheConfigLoadReportsAWrongTypedMember:+ def test_a_project_file_with_a_scalar_package_log_levels_fails_the_load_with_the_loaders_error(+ self, tmp_path: Path, mocker: MockerFixture+ ) -> None:+ fake_home = tmp_path / "home"+ (fake_home / ".pipelex").mkdir(parents=True)+ project_root = tmp_path / "project"+ (project_root / ".git").mkdir(parents=True)+ (project_root / ".pipelex").mkdir()+ (project_root / ".pipelex" / CONFIG_NAME).write_text('[runtime.log]\npackage_log_levels = "x"\n', encoding="utf-8")+ mocker.patch.object(Path, "home", return_value=fake_home)+ mocker.patch.object(Path, "cwd", return_value=project_root)++ with pytest.raises(ConfigValidationError, match="package_log_levels"):+ ConfigLoader().load_config_validated(config_cls=PipelexConfig)diff --git a/tests/unit/pipelex/system/configuration/test_config_package_log_levels.py b/tests/unit/pipelex/system/configuration/test_config_package_log_levels.pynew file mode 100644index 000000000..53a7b17fe--- /dev/null+++ b/tests/unit/pipelex/system/configuration/test_config_package_log_levels.py@@ -0,0 +1,36 @@+"""`runtime.log.package_log_levels` is a table of level names, and any other value is refused as a validation error.++A scalar here used to crash the config load with a bare `AttributeError` from a `mode="before"` validator+that called `.items()` on whatever it was given.+"""++from typing import Any++import pytest+from pydantic import ValidationError++from pipelex.tools.log.log_config import LogConfig+from pipelex.tools.log.log_levels import LogLevel+from tests.unit.pipelex.system.configuration.config_section_utils import base_config_section+++class TestLogConfigPackageLogLevels:+ def test_level_names_are_converted_to_levels(self) -> None:+ log_config = LogConfig.model_validate({**base_config_section("runtime", "log"), "package_log_levels": {"pipelex": "DEBUG", "httpx": "INFO"}})++ assert log_config.package_log_levels == {"pipelex": LogLevel.DEBUG, "httpx": LogLevel.INFO}+ assert all(type(level) is LogLevel for level in log_config.package_log_levels.values())++ @pytest.mark.parametrize(+ ("value", "expected_fragment"),+ [+ pytest.param("x", "Input should be a valid dictionary", id="a_string"),+ pytest.param(["DEBUG"], "Input should be a valid dictionary", id="a_list"),+ pytest.param({"pipelex": "LOUD"}, "Input should be", id="an_unknown_level"),+ ],+ )+ def test_a_value_that_is_not_a_table_of_levels_is_refused(self, value: Any, expected_fragment: str) -> None:+ with pytest.raises(ValidationError, match=expected_fragment) as exc_info:+ LogConfig.model_validate({**base_config_section("runtime", "log"), "package_log_levels": value})++ assert exc_info.value.errors()[0]["loc"][0] == "package_log_levels"diff --git a/tests/unit/pipelex/system/configuration/test_config_scan_excluded_dirs.py b/tests/unit/pipelex/system/configuration/test_config_scan_excluded_dirs.pynew file mode 100644index 000000000..51cbd350b--- /dev/null+++ b/tests/unit/pipelex/system/configuration/test_config_scan_excluded_dirs.py@@ -0,0 +1,22 @@+"""`interpreter.scan.excluded_dirs` is an array of directory names, read as a set; any other value is refused.++A string here used to be read as the set of its letters.+"""++from typing import Any++import pytest+from pydantic import ValidationError++from pipelex.system.configuration.configs import ScanConfig+++class TestScanConfigExcludedDirs:+ @pytest.mark.parametrize("value", [["node_modules", ".venv"], ("node_modules", ".venv"), frozenset({"node_modules", ".venv"})])+ def test_a_list_of_names_is_read_as_a_set(self, value: Any) -> None:+ assert ScanConfig.model_validate({"excluded_dirs": value}).excluded_dirs == frozenset({"node_modules", ".venv"})++ @pytest.mark.parametrize("value", [pytest.param("node_modules", id="a_string"), pytest.param(5, id="an_integer")])+ def test_a_value_that_is_not_a_list_is_refused(self, value: Any) -> None:+ with pytest.raises(ValidationError, match="Input should be a valid frozenset"):+ ScanConfig.model_validate({"excluded_dirs": value})diff --git a/tests/unit/pipelex/test_pipelex_error_message_init.py b/tests/unit/pipelex/test_pipelex_error_message_init.pyindex 51c43c6fa..b2338bd3f 100644--- a/tests/unit/pipelex/test_pipelex_error_message_init.py+++ b/tests/unit/pipelex/test_pipelex_error_message_init.py@@ -14,7 +14,6 @@ from pipelex.base_exceptions import PipelexErrorfrom pipelex.cogt.exceptions import RoutingProfileBlueprintValueErrorfrom pipelex.errors.error_pages_generator import iter_pipelex_error_subclassesfrom pipelex.pipe_operators.compose.exceptions import ConstructFieldBlueprintValueError-from pipelex.system.exceptions import ConfigModelErrorclass TestPipelexErrorMessageInit:@@ -31,7 +30,7 @@ class TestPipelexErrorMessageInit:offenders.append(f"{error_cls.__module__}.{error_cls.__name__} (lists {shadow_cls.__name__} before PipelexError)")assert not offenders, "Exception classes shadow PipelexError.__init__ — `.message` will be unset:\n" + "\n".join(offenders)- @pytest.mark.parametrize("error_cls", [ConstructFieldBlueprintValueError, RoutingProfileBlueprintValueError, ConfigModelError])+ @pytest.mark.parametrize("error_cls", [ConstructFieldBlueprintValueError, RoutingProfileBlueprintValueError])def test_message_set_and_error_report_succeeds(self, error_cls: type[PipelexError]) -> None:"""A reordered ``(PipelexError, ValueError)`` mixin sets ``.message``, keeps its``ValueError`` identity (so Pydantic still wraps validator raises), and renders a report.diff --git a/tests/unit/pipelex/tools/test_log_config.py b/tests/unit/pipelex/tools/test_log_config.pyindex 381ca9681..032e83489 100644--- a/tests/unit/pipelex/tools/test_log_config.py+++ b/tests/unit/pipelex/tools/test_log_config.py@@ -1,7 +1,6 @@import pytest-from pipelex.tools.log.log_config import CallerInfoTemplate, LogConfig-from pipelex.tools.log.log_levels import LogLevel+from pipelex.tools.log.log_config import CallerInfoTemplateclass TestLogConfigUtilities:@@ -19,13 +18,3 @@ class TestLogConfigUtilities:)def test_caller_info_template_mapping(self, template_key: CallerInfoTemplate, expected_template: str) -> None:assert CallerInfoTemplate.for_template_key(template_key) == expected_template-- def test_validate_package_log_levels_converts_strings_to_enum(self) -> None:- package_levels = {"pipelex": "DEBUG", "pipelex.tools": "INFO"}-- validated_levels = LogConfig.validate_package_log_levels(package_levels)-- assert validated_levels == {- "pipelex": LogLevel.DEBUG,- "pipelex.tools": LogLevel.INFO,- }diff --git a/tests/unit/pipelex/tools/typing/test_format_pydantic_validation_error.py b/tests/unit/pipelex/tools/typing/test_format_pydantic_validation_error.pyindex 25a91e25c..aa3fa0258 100644--- a/tests/unit/pipelex/tools/typing/test_format_pydantic_validation_error.py+++ b/tests/unit/pipelex/tools/typing/test_format_pydantic_validation_error.py@@ -1,3 +1,4 @@+from enum import StrEnumfrom typing import Literalimport pytest@@ -24,6 +25,22 @@ class TestFormatPydanticValidationError:assert "Missing required fields: 'b'" in formattedassert "Extra forbidden fields: 'c'" in formatted+ def test_an_enum_error_names_the_valid_members(self) -> None:+ """Without them the reader of a refused value has no way to tell what to write instead."""++ class Color(StrEnum):+ RED = "red"+ GREEN = "green"++ class Painted(BaseModel):+ color: Color++ with pytest.raises(ValidationError) as exc:+ Painted.model_validate({"color": "blue"})++ formatted = format_pydantic_validation_error(exc.value)+ assert "Enum errors: 'color': invalid enum value 'blue', expected 'red' or 'green'" in formatted+def test_multiple_missing_fields(self) -> None:"""Test formatting with multiple missing required fields displayed as comma-separated list."""