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/llm completion error handling (#383)

Louis Choquelc9577cffef78
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fd5683b92..a5fcdb81e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,23 +1,49 @@
# Changelog
-## Unreleased
+## [Unreleased]
+
+### Highlights - Simplifying pipeline execution and improving developer experience
+
+This release focuses on making Pipelex more accessible and easier to use, with major improvements to the CLI, simplified syntax for multiplicity, and a complete documentation overhaul:
+
+- **New CLI commands**: Run pipelines directly with `pipelex run`, generate Python runners with `pipelex build runner`, and inspect your AI backend configuration with `pipelex show backends`
+- **Simplified pipeline inputs**: The new `inputs` parameter replaces `input_memory` and accepts strings, lists, or content objects directly - no more complex dictionary structures
+- **Getting started faster**: Completely rewritten quick-start guide and new documentation sections help you go from installation to your first pipeline in minutes
### Added
- - **New `pipelex run` Command**: A top-level command to execute pipelines directly from the CLI. It can run a pipe existing in the package or a pipe from any `.plx` bundle file, with options to provide inputs from a JSON file and save the output.
- - **New `pipelex build runner` Command**: A new command that generates a Python script to run a specified pipe. The script includes all necessary imports and placeholder inputs, significantly speeding up the integration of pipes into Python applications.
- - **New `pipelex show backends` Command**: A new command to display all configured inference backends, their status (enabled/disabled), and the active model routing profile and its rules.
- - **Revamped Documentation**: The documentation has been overhauled with a new "Getting Started" guide on the main page, making it easier for new users to install Pipelex, configure API keys, and run their first pipeline. New sections on executing pipelines and input/output multiplicity have also been added.
+
+- CLI command `pipelex run`: Top-level command to execute pipelines directly from the CLI. Can run pipes from the package or from any `.plx` bundle file, with options to provide inputs from a JSON file and save the output
+- CLI command `pipelex build runner`: Generates Python script with imports and example input structures for any pipe
+- CLI command `pipelex show backends`: Displays configured AI providers, their status, and active routing rules
+- Model presets: Added task-oriented presets including `llm_to_write_questions`, `llm_to_code`, `llm_for_basic_vision`, `llm_for_visual_analysis`
+- Documentation: Complete quick-start guide rewrite, new guides for "Understanding Multiplicity", "API Guide", "Executing Pipelines with Inputs", and updated README with video demo
+- Migration guide: Updated guide at `pipelex/kit/migrations/migrate_0.11.0_0.12.x.md`
### Changed
- - **Bundle `main_pipe` Attribute**: Pipelex bundles (`.plx` files) now support a `main_pipe` attribute to designate the primary entry point of the bundle. This is used by the new `pipelex run` and `build build runner` commands to simplify execution.
- - **CLI Reorganization**: The main command-line interface has been restructured for better usability, with improved help texts and a more logical command order.
- - **`PipeExtract` Operator**: The `PipeExtract` operator's output is now consistently validated to be the `Page` concept, simplifying its usage for document processing.
- - **Python Coding Standards**: Updated internal coding standards to recommend declaring variables with a type but no default value to better leverage linters for bug detection.
+
+- **Unified bracket notation for multiplicity**: Single items use `"Concept"`, variable lists use `"Concept[]"`, fixed-count lists use `"Concept[3]"`. Applies to both `inputs` and `output` fields in `.plx` files
+- **Pipeline input format**: `input_memory` parameter renamed to `inputs`; now accepts strings, lists of strings, `StuffContent` objects, or explicit concept dictionaries instead of `CompactMemory`
+- **Bundle `main_pipe` attribute**: Pipelex bundles (`.plx` files) now support a `main_pipe` attribute to designate the primary entry point of the bundle. Used by `pipelex run` and `pipelex build runner` commands to simplify execution
+- **Model preset names**: `llm_to_reason` → `llm_for_complex_reasoning`, `base_ocr_mistral` → `extract_text_from_visuals`, `base_extract_pypdfium2` → `extract_text_from_pdf`, `base_img_gen` → `gen_image_basic`, `fast_img_gen` → `gen_image_fast`, `high_quality_img_gen` → `gen_image_high_quality`
+- **Unified model parameter**: `PipeExtract` and `PipeImgGen` now use `model` parameter for consistency across all operator pipes
+- **`PipeExtract` operator**: Output is now consistently validated to be the `Page` concept, simplifying its usage for document processing
+- **CLI improvements**: `pipelex run` and `pipelex validate` now auto-detect pipe code vs `.plx` bundle files; `pipelex validate` promoted to top-level command with improved error reporting and syntax-highlighted code snippets
+- **CLI reorganization**: Main command-line interface restructured for better usability with improved help texts and more logical command order
+- **Python API**: `Pipelex.make()` now accepts dependency injection arguments directly
+- **Python coding standards**: Updated internal coding standards to recommend declaring variables with a type but no default value to better leverage linters for bug detection
+- **Default configuration**: Azure and AWS inference backends now disabled by default in template configuration
+
+### Fixed
+
+- Structure generation: Special characters (double quotes, backslashes) in concept field descriptions or default values no longer produce invalid Python code
### Removed
- - Removed seldom used `prompt_template_to_structure` and `system_prompt_to_structure` configurations at the pipe and domain level.
- - Removed **Project Name** discovery from Configuration.
- - Removed temporary design document for the new inference backend system, as the feature is now fully implemented and documented.
+
+- Legacy multiplicity syntax: `nb_output`, `multiple_output` parameters, and complex input dictionary syntax with `multiplicity` field
+- Pipe-specific model parameters: `ocr` parameter from `PipeExtract` and `img_gen` parameter from `PipeImgGen`
+- `prompt_template_to_structure` and `system_prompt_to_structure` configurations at the pipe and domain level
+- Project Name discovery from Configuration
+- Temporary design document for the new inference backend system (feature now fully implemented and documented)
## [v0.12.0] - 2025-10-15
diff --git a/pipelex/pipe_operators/llm/pipe_llm.py b/pipelex/pipe_operators/llm/pipe_llm.py
index c9d771730..41f1218de 100644
--- a/pipelex/pipe_operators/llm/pipe_llm.py
+++ b/pipelex/pipe_operators/llm/pipe_llm.py
@@ -6,6 +6,7 @@ from typing_extensions import override
from pipelex import log
from pipelex.cogt.content_generation.content_generator_dry import ContentGeneratorDry
from pipelex.cogt.content_generation.content_generator_protocol import ContentGeneratorProtocol
+from pipelex.cogt.exceptions import LLMCompletionError
from pipelex.cogt.llm.llm_prompt import LLMPrompt
from pipelex.cogt.llm.llm_prompt_factory_abstract import LLMPromptFactoryAbstract
from pipelex.cogt.llm.llm_prompt_template import LLMPromptTemplate
@@ -27,6 +28,7 @@ from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
from pipelex.exceptions import (
+ PipeExecutionError,
StaticValidationError,
StaticValidationErrorType,
)
@@ -252,11 +254,16 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
output_structure_prompt=None,
extra_params=llm_prompt_run_params.params,
)
- generated_text: str = await content_generator.make_llm_text(
- job_metadata=job_metadata,
- llm_prompt_for_text=llm_prompt_1_for_text,
- llm_setting_main=llm_setting_main,
- )
+ try:
+ generated_text: str = await content_generator.make_llm_text(
+ job_metadata=job_metadata,
+ llm_prompt_for_text=llm_prompt_1_for_text,
+ llm_setting_main=llm_setting_main,
+ )
+ except LLMCompletionError as exc:
+ location = self._format_error_location(pipe_run_params=pipe_run_params)
+ msg = f"Error generating text with LLM {location}: {exc}"
+ raise PipeExecutionError(msg) from exc
the_content = TextContent(
text=generated_text,
@@ -300,6 +307,7 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
)
the_content = await self._llm_gen_object_stuff_content(
job_metadata=job_metadata,
+ pipe_run_params=pipe_run_params,
is_multiple_output=is_multiple_output,
fixed_nb_output=fixed_nb_output,
output_class_name=output_concept.structure_class_name,
@@ -329,6 +337,7 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
async def _llm_gen_object_stuff_content(
self,
job_metadata: JobMetadata,
+ pipe_run_params: PipeRunParams,
is_multiple_output: bool,
fixed_nb_output: int | None,
output_class_name: str,
@@ -355,27 +364,36 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
method_desc = "text_then_object"
log.verbose(f"{task_desc} by {method_desc}")
log.verbose(f"llm_prompt_2_factory: {llm_prompt_2_factory}")
-
- generated_objects = await content_generator.make_text_then_object_list(
- job_metadata=job_metadata,
- object_class=content_class,
- llm_prompt_for_text=llm_prompt_1,
- llm_setting_main=llm_setting_main,
- llm_prompt_factory_for_object_list=llm_prompt_2_factory,
- llm_setting_for_object_list=llm_setting_for_object,
- nb_items=fixed_nb_output,
- )
+ try:
+ generated_objects = await content_generator.make_text_then_object_list(
+ job_metadata=job_metadata,
+ object_class=content_class,
+ llm_prompt_for_text=llm_prompt_1,
+ llm_setting_main=llm_setting_main,
+ llm_prompt_factory_for_object_list=llm_prompt_2_factory,
+ llm_setting_for_object_list=llm_setting_for_object,
+ nb_items=fixed_nb_output,
+ )
+ except LLMCompletionError as exc:
+ location = self._format_error_location(pipe_run_params=pipe_run_params)
+ msg = f"Error generating list of objects with text then object {location}: {exc}"
+ raise PipeExecutionError(msg) from exc
else:
# We're generating a list of objects directly
method_desc = "object_direct"
log.verbose(f"{task_desc} by {method_desc}, content_class={content_class.__name__}")
- generated_objects = await content_generator.make_object_list_direct(
- job_metadata=job_metadata,
- object_class=content_class,
- llm_prompt_for_object_list=llm_prompt_1,
- llm_setting_for_object_list=llm_setting_for_object,
- nb_items=fixed_nb_output,
- )
+ try:
+ generated_objects = await content_generator.make_object_list_direct(
+ job_metadata=job_metadata,
+ object_class=content_class,
+ llm_prompt_for_object_list=llm_prompt_1,
+ llm_setting_for_object_list=llm_setting_for_object,
+ nb_items=fixed_nb_output,
+ )
+ except LLMCompletionError as exc:
+ location = self._format_error_location(pipe_run_params=pipe_run_params)
+ msg = f"Error generating list of objects with direct method {location}: {exc}"
+ raise PipeExecutionError(msg) from exc
the_content = ListContent(items=generated_objects)
else:
@@ -387,28 +405,41 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
method_desc = "text_then_object"
log.verbose(f"{task_desc} by {method_desc}")
log.verbose(f"llm_prompt_2_factory: {llm_prompt_2_factory}")
- generated_object = await content_generator.make_text_then_object(
- job_metadata=job_metadata,
- object_class=content_class,
- llm_prompt_for_text=llm_prompt_1,
- llm_setting_main=llm_setting_main,
- llm_prompt_factory_for_object=llm_prompt_2_factory,
- llm_setting_for_object=llm_setting_for_object,
- )
+ try:
+ generated_object = await content_generator.make_text_then_object(
+ job_metadata=job_metadata,
+ object_class=content_class,
+ llm_prompt_for_text=llm_prompt_1,
+ llm_setting_main=llm_setting_main,
+ llm_prompt_factory_for_object=llm_prompt_2_factory,
+ llm_setting_for_object=llm_setting_for_object,
+ )
+ except LLMCompletionError as exc:
+ location = self._format_error_location(pipe_run_params=pipe_run_params)
+ msg = f"Error generating single object with text then object {location}: {exc}"
+ raise PipeExecutionError(msg) from exc
else:
# We're generating a single object directly
method_desc = "object_direct"
log.verbose(f"{task_desc} by {method_desc}, content_class={content_class.__name__}")
- generated_object = await content_generator.make_object_direct(
- job_metadata=job_metadata,
- object_class=content_class,
- llm_prompt_for_object=llm_prompt_1,
- llm_setting_for_object=llm_setting_for_object,
- )
+ try:
+ generated_object = await content_generator.make_object_direct(
+ job_metadata=job_metadata,
+ object_class=content_class,
+ llm_prompt_for_object=llm_prompt_1,
+ llm_setting_for_object=llm_setting_for_object,
+ )
+ except LLMCompletionError as exc:
+ location = self._format_error_location(pipe_run_params=pipe_run_params)
+ msg = f"Error generating single object with direct method {location}: {exc}"
+ raise PipeExecutionError(msg) from exc
the_content = generated_object
return the_content
+ def _format_error_location(self, pipe_run_params: PipeRunParams) -> str:
+ return f"in pipe '{pipe_run_params.pipe_stack_str}'"
+
@override
async def _dry_run_operator_pipe(
self,
diff --git a/pipelex/pipe_run/pipe_run_params.py b/pipelex/pipe_run/pipe_run_params.py
index a5588edbf..039339035 100644
--- a/pipelex/pipe_run/pipe_run_params.py
+++ b/pipelex/pipe_run/pipe_run_params.py
@@ -162,6 +162,10 @@ class PipeRunParams(BaseModel):
pipe_stack: list[str] = Field(default_factory=list)
pipe_layers: list[str] = Field(default_factory=list)
+ @property
+ def pipe_stack_str(self) -> str:
+ return ".".join(self.pipe_stack)
+
@field_validator("params")
@classmethod
def validate_param_keys(cls, value: dict[str, Any]) -> dict[str, Any]: