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.

Polish PR review fixes: warn on dropped inputs, deduplicate structure helper, consolidate alias tests

Louis Choquel7f7417a0720a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index abbdd74e1..d5de49b80 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,7 +12,7 @@
### Fixed
-- **`concept_cmd` alias bug**: The CLI's `_parse_concept_spec_from_json` incorrectly listed `concept_code` as an alias instead of `the_concept_code`, causing it to miss valid input.
+- **Concept alias bug**: Concept alias handling previously listed `concept_code` as an alias instead of `the_concept_code`, causing valid input to be silently dropped. Fixed by the new shared `parse_concept_spec` helper.
## [v0.23.0] - 2026-03-29
diff --git a/README.md b/README.md
index c0a0e3485..3227c0c43 100644
--- a/README.md
+++ b/README.md
@@ -522,7 +522,7 @@ The package supports the following additional features:
Install all extras:
```bash
-pip install "pipelex[anthropic,google,google-genai,mistralai,bedrock,fal,linkup,docling]"
+uv pip install "pipelex[anthropic,google,google-genai,mistralai,bedrock,fal,linkup,docling]"
```
---
diff --git a/pipelex/builder/operations/pipe_ops.py b/pipelex/builder/operations/pipe_ops.py
index d307cab97..e95c74c67 100644
--- a/pipelex/builder/operations/pipe_ops.py
+++ b/pipelex/builder/operations/pipe_ops.py
@@ -10,6 +10,7 @@ from typing import Any
import tomlkit
from tomlkit.items import Table
+from pipelex import log
from pipelex.builder.pipe.pipe_batch_spec import PipeBatchSpec
from pipelex.builder.pipe.pipe_compose_spec import PipeComposeSpec
from pipelex.builder.pipe.pipe_condition_spec import PipeConditionSpec
@@ -23,15 +24,21 @@ from pipelex.builder.pipe.pipe_sequence_spec import PipeSequenceSpec
from pipelex.builder.pipe.pipe_spec import PipeSpec
from pipelex.builder.pipe.pipe_spec_map import pipe_type_to_spec_class
-# Aliases that agents may use instead of "pipe_code" — checked in order, first match wins.
+# Aliases that agents may use instead of "pipe_code". First found is promoted when canonical key is absent; extras are dropped.
_PIPE_CODE_ALIASES = ("pipe", "the_pipe_code", "code", "name", "pipe_name", "pipe_ref")
def _normalize_sub_pipe_dict(data: dict[str, Any]) -> None:
"""Normalize a step/branch dict: resolve pipe_code aliases and drop extraneous fields."""
_normalize_pipe_code_aliases(data)
- # Agents sometimes add "inputs" to individual steps; silently drop it.
- data.pop("inputs", None)
+ # Agents sometimes add "inputs" to individual steps; drop with a warning.
+ if "inputs" in data:
+ log.warning(
+ f"Dropping unsupported 'inputs' field from step/branch dict "
+ f"(pipe_code={data.get('pipe_code', '?')}). "
+ f"Step-level inputs are not supported; inputs are inherited from the parent pipe."
+ )
+ data.pop("inputs")
def _normalize_pipe_code_aliases(data: dict[str, Any]) -> None:
diff --git a/pipelex/cli/agent_cli/commands/concept_cmd.py b/pipelex/cli/agent_cli/commands/concept_cmd.py
index df24073d1..5e1b20545 100644
--- a/pipelex/cli/agent_cli/commands/concept_cmd.py
+++ b/pipelex/cli/agent_cli/commands/concept_cmd.py
@@ -9,8 +9,8 @@ import tomlkit
import typer
from pydantic import ValidationError
-from pipelex.builder.concept.concept_spec import ConceptSpec, ConceptStructureSpec
-from pipelex.builder.operations.concept_ops import parse_concept_spec
+from pipelex.builder.concept.concept_spec import ConceptSpec
+from pipelex.builder.operations.concept_ops import parse_concept_spec, structure_field_to_dict
from pipelex.cli.agent_cli.commands.agent_output import agent_error
from pipelex.language.toml_string_utils import format_toml_string
from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error_for_agent
@@ -42,7 +42,7 @@ def _concept_spec_to_toml(concept_spec: ConceptSpec) -> str:
if concept_spec.structure:
structure_table = tomlkit.table()
for field_name, field_spec in concept_spec.structure.items():
- field_dict = _structure_field_to_dict(field_spec)
+ field_dict = structure_field_to_dict(field_spec)
# If only description is present, use simple string format
if len(field_dict) == 1 and "description" in field_dict:
structure_table.add(field_name, format_toml_string(field_dict["description"]))
@@ -59,38 +59,6 @@ def _concept_spec_to_toml(concept_spec: ConceptSpec) -> str:
return tomlkit.dumps(doc)
-def _structure_field_to_dict(field_spec: ConceptStructureSpec) -> dict[str, Any]:
- """Convert a ConceptStructureSpec to a dictionary for TOML serialization.
-
- Args:
- field_spec: The field specification to convert.
-
- Returns:
- Dictionary with field properties.
- """
- result: dict[str, Any] = {}
-
- # Type is always needed unless it's just a text description
- if not field_spec.type.is_text or field_spec.required or field_spec.default_value is not None:
- result["type"] = field_spec.type
-
- result["description"] = field_spec.description
-
- if field_spec.required:
- result["required"] = True
-
- if field_spec.default_value is not None:
- result["default"] = field_spec.default_value
-
- if field_spec.concept_ref:
- result["concept_ref"] = field_spec.concept_ref
-
- if field_spec.choices:
- result["choices"] = field_spec.choices
-
- return result
-
-
def concept_cmd(
spec: Annotated[
str | None,
@@ -158,5 +126,8 @@ def concept_cmd(
message, details = format_pydantic_validation_error_for_agent(exc)
agent_error(message, "ValidationError", cause=exc, validation_details=details)
+ except ValueError as exc:
+ agent_error(str(exc), "ValueError", cause=exc)
+
except Exception as exc:
agent_error(str(exc), type(exc).__name__, cause=exc)
diff --git a/pipelex/cogt/img_gen/img_gen_worker_factory.py b/pipelex/cogt/img_gen/img_gen_worker_factory.py
index 201f8ca38..1642e484b 100644
--- a/pipelex/cogt/img_gen/img_gen_worker_factory.py
+++ b/pipelex/cogt/img_gen/img_gen_worker_factory.py
@@ -143,10 +143,7 @@ class ImgGenWorkerFactory:
if importlib.util.find_spec("google.genai") is None:
lib_name = "google-genai"
lib_extra_name = "google"
- msg = (
- "The google-genai SDK is required in order to use Google Gemini Image models. "
- "You can install it with 'pip install google-genai'."
- )
+ msg = "The google-genai SDK is required in order to use Google Gemini Image models."
raise MissingDependencyError(
lib_name,
lib_extra_name,
diff --git a/pipelex/cogt/llm/llm_worker_factory.py b/pipelex/cogt/llm/llm_worker_factory.py
index 1b5a77e42..64308ccb5 100644
--- a/pipelex/cogt/llm/llm_worker_factory.py
+++ b/pipelex/cogt/llm/llm_worker_factory.py
@@ -229,10 +229,7 @@ class LLMWorkerFactory:
if importlib.util.find_spec("google.genai") is None:
lib_name = "google-genai"
lib_extra_name = "google"
- msg = (
- "The google-genai SDK is required in order to use Google Gemini API directly. "
- "You can install it with 'pip install google-genai'."
- )
+ msg = "The google-genai SDK is required in order to use Google Gemini API directly."
raise MissingDependencyError(
lib_name,
lib_extra_name,
diff --git a/tests/unit/pipelex/builder/operations/test_parse_concept_spec.py b/tests/unit/pipelex/builder/operations/test_parse_concept_spec.py
index d38eec3ef..e3f9bbfb2 100644
--- a/tests/unit/pipelex/builder/operations/test_parse_concept_spec.py
+++ b/tests/unit/pipelex/builder/operations/test_parse_concept_spec.py
@@ -5,6 +5,7 @@ from __future__ import annotations
from typing import Any, ClassVar
import pytest
+from pydantic import ValidationError
from pipelex.builder.concept.concept_spec import ConceptStructureSpecFieldType
from pipelex.builder.operations.concept_ops import parse_concept_spec
@@ -42,6 +43,12 @@ class TestParseConceptSpec:
result = parse_concept_spec(spec)
assert result.concept_code == "Invoice"
+ def test_missing_concept_code_raises(self) -> None:
+ """Spec with no concept_code and no alias should raise ValidationError."""
+ spec: dict[str, Any] = {**self._BASE}
+ with pytest.raises(ValidationError):
+ parse_concept_spec(spec)
+
# -- does not mutate caller's dict ------------------------------------
def test_original_dict_unchanged(self) -> None:
diff --git a/tests/unit/pipelex/builder/operations/test_parse_pipe_spec.py b/tests/unit/pipelex/builder/operations/test_parse_pipe_spec.py
index 57509be3d..279fe9bd4 100644
--- a/tests/unit/pipelex/builder/operations/test_parse_pipe_spec.py
+++ b/tests/unit/pipelex/builder/operations/test_parse_pipe_spec.py
@@ -90,22 +90,6 @@ class TestParsePipeSpec:
# -- steps/branches 'pipe' → 'pipe_code' alias -----------------------
- def test_sequence_steps_pipe_alias(self) -> None:
- spec: dict[str, Any] = {
- "pipe_code": "my_seq",
- "description": "A sequence",
- "inputs": {"doc": "Document"},
- "output": "Text",
- "steps": [
- {"pipe": "step_one", "result": "intermediate"},
- {"pipe": "step_two", "result": "final"},
- ],
- }
- result = parse_pipe_spec("PipeSequence", spec)
- assert isinstance(result, PipeSequenceSpec)
- assert result.steps[0].pipe_code == "step_one"
- assert result.steps[1].pipe_code == "step_two"
-
def test_sequence_steps_canonical_pipe_code(self) -> None:
spec: dict[str, Any] = {
"pipe_code": "my_seq",
@@ -118,26 +102,9 @@ class TestParsePipeSpec:
assert isinstance(result, PipeSequenceSpec)
assert result.steps[0].pipe_code == "step_one"
- def test_parallel_branches_pipe_alias(self) -> None:
- spec: dict[str, Any] = {
- "pipe_code": "my_par",
- "description": "Parallel branches",
- "inputs": {"doc": "Document"},
- "output": "Text",
- "add_each_output": True,
- "branches": [
- {"pipe": "branch_a", "result": "result_a"},
- {"pipe": "branch_b", "result": "result_b"},
- ],
- }
- result = parse_pipe_spec("PipeParallel", spec)
- assert isinstance(result, PipeParallelSpec)
- assert result.branches[0].pipe_code == "branch_a"
- assert result.branches[1].pipe_code == "branch_b"
-
- @pytest.mark.parametrize("alias", ["pipe_ref", "the_pipe_code", "code", "name", "pipe_name"])
+ @pytest.mark.parametrize("alias", ["pipe", "pipe_ref", "the_pipe_code", "code", "name", "pipe_name"])
def test_sequence_steps_all_aliases(self, alias: str) -> None:
- """All pipe_code aliases must work inside step dicts, not just 'pipe'."""
+ """All pipe_code aliases must work inside step dicts."""
spec: dict[str, Any] = {
"pipe_code": "my_seq",
"description": "A sequence",
@@ -153,9 +120,9 @@ class TestParsePipeSpec:
assert result.steps[0].pipe_code == "step_one"
assert result.steps[1].pipe_code == "step_two"
- @pytest.mark.parametrize("alias", ["pipe_ref", "the_pipe_code", "code", "name", "pipe_name"])
+ @pytest.mark.parametrize("alias", ["pipe", "pipe_ref", "the_pipe_code", "code", "name", "pipe_name"])
def test_parallel_branches_all_aliases(self, alias: str) -> None:
- """All pipe_code aliases must work inside branch dicts, not just 'pipe'."""
+ """All pipe_code aliases must work inside branch dicts."""
spec: dict[str, Any] = {
"pipe_code": "my_par",
"description": "Parallel branches",