Skip to content

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

fix/Config-before-validators · L-261010-20e31b (#1407)

Louis Choquel365fa71c9d00
diff --git a/.drift/acks/config-docs.toml b/.drift/acks/config-docs.toml
index 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_durations
index 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.md
index 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.md
index 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.
### Removed
diff --git a/CLAUDE.md b/CLAUDE.md
index 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.md
index 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 model
A 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.md
index 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 automaticall
Files 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.md
deleted file mode 100644
index 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.md
index 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 set
diff --git a/pipelex/cogt/config_cogt.py b/pipelex/cogt/config_cogt.py
index 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 PipelexConfigError
from pipelex.cogt.exceptions import LLMConfigError
from pipelex.cogt.img_gen.img_gen_job_components import ImgGenJobConfig, ImgGenJobParams, ImgGenJobParamsDefaults, Quality
from 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")
@classmethod
def 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 value
diff --git a/pipelex/cogt/llm/llm_setting.py b/pipelex/cogt/llm/llm_setting.py
index 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, Union
from 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.py
index 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 Field
from pipelex.cogt.model_backends.backend import InferenceBackend
from pipelex.cogt.model_backends.constraints import ListedConstraint, ValuedConstraint
from pipelex.cogt.model_backends.credential_resolution import CredentialResolution
from 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, LaxEnum
from pipelex.tools.typing.pydantic_utils import empty_dict_factory_of, empty_list_factory_of
@@ -14,26 +14,10 @@ class InferenceBackendBlueprint(ConfigModel):
enabled: bool = True
endpoint: str | None = None
api_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 and
diff --git a/pipelex/cogt/model_backends/model_spec_factory.py b/pipelex/cogt/model_backends/model_spec_factory.py
index 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 math
from typing import Any
from 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 ImgGenArgTopic
from pipelex.cogt.llm.structured_output import StructureMethod
from pipelex.cogt.llm.thinking_mode import ThinkingMode
from pipelex.cogt.model_backends.constraints import ListedConstraint, ValuedConstraint
from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
from pipelex.cogt.model_backends.model_type import DEFAULT_MODEL_TYPE, ModelType
from pipelex.cogt.usage.cost_category import CostCategory, CostsByCategoryDict
-from pipelex.system.configuration.config_model import ConfigModel
+from pipelex.system.configuration.config_model import ConfigModel, LaxEnum
from pipelex.tools.typing.pydantic_utils import empty_dict_factory_of, empty_list_factory_of
BackendModelSpecs = dict[str, Any]
@@ -27,55 +28,29 @@ class InferenceModelSpecBlueprint(ConfigModel):
model_id: str | None = None
inputs: 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 = None
structure_method: StructureMethod | None = Field(default=None, strict=False)
thinking_mode: ThinkingMode = Field(default=ThinkingMode.NONE, strict=False)
max_tokens: int | None = None
max_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 value
class InferenceModelSpecFactory(BaseModel):
diff --git a/pipelex/exceptions.py b/pipelex/exceptions.py
index 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.md
index 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.py
index 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, Strict
StrEnumType = 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.py
index 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.py
index 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):
- pass
diff --git a/pipelex/tools/log/log_config.py b/pipelex/tools/log/log_config.py
index 97019b2cf..c7ffacbd2 100644
--- a/pipelex/tools/log/log_config.py
+++ b/pipelex/tools/log/log_config.py
@@ -2,11 +2,10 @@ from __future__ import annotations
import re
from enum import StrEnum
-from typing import cast
from pydantic import Field, field_validator
-from pipelex.system.configuration.config_model import ConfigModel
+from pipelex.system.configuration.config_model import ConfigModel, LaxEnum
from pipelex.system.console_target import ConsoleTarget
from pipelex.tools.log.log_levels import LogLevel
from 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: str
pretty_print_mode: PrettyPrintMode = Field(strict=False)
@@ -159,11 +158,3 @@ class LogConfig(ConfigModel):
rich_log: RichLogConfig
otlp: OtlpLogSinkConfig
gcp: 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.py
index 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) -> PydanticValidatio
extra_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.toml
index 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.txt
index 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/con
ConceptStringError | 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.py
new file mode 100644
index 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 message
diff --git a/tests/unit/pipelex/cogt/model_backends/test_data.py b/tests/unit/pipelex/cogt/model_backends/test_data.py
index 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.py
index 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 rejection
diff --git a/tests/unit/pipelex/cogt/models/test_plugin_model_merge.py b/tests/unit/pipelex/cogt/models/test_plugin_model_merge.py
index 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.py
new file mode 100644
index 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 section
diff --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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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 PipelexError
from pipelex.cogt.exceptions import RoutingProfileBlueprintValueError
from pipelex.errors.error_pages_generator import iter_pipelex_error_subclasses
from pipelex.pipe_operators.compose.exceptions import ConstructFieldBlueprintValueError
-from pipelex.system.exceptions import ConfigModelError
class 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.py
index 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 CallerInfoTemplate
class 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.py
index 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 StrEnum
from typing import Literal
import pytest
@@ -24,6 +25,22 @@ class TestFormatPydanticValidationError:
assert "Missing required fields: 'b'" in formatted
assert "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."""