gllm-pipeline-binary 0.4.17__cp312-cp312-win_amd64.whl → 0.4.18__cp312-cp312-win_amd64.whl

gllm_pipeline/pipeline/composer/__init__.pyi

@@ -0,0 +1,8 @@
+from gllm_pipeline.pipeline.composer.composer import Composer as Composer
+from gllm_pipeline.pipeline.composer.guard_composer import GuardComposer as GuardComposer
+from gllm_pipeline.pipeline.composer.if_else_composer import IfElseComposer as IfElseComposer
+from gllm_pipeline.pipeline.composer.parallel_composer import ParallelComposer as ParallelComposer
+from gllm_pipeline.pipeline.composer.switch_composer import SwitchComposer as SwitchComposer
+from gllm_pipeline.pipeline.composer.toggle_composer import ToggleComposer as ToggleComposer
+
+__all__ = ['Composer', 'GuardComposer', 'IfElseComposer', 'ParallelComposer', 'SwitchComposer', 'ToggleComposer']

gllm_pipeline/pipeline/composer/composer.pyi

@@ -0,0 +1,350 @@
+from gllm_core.schema import Component as Component
+from gllm_core.utils.retry import RetryConfig as RetryConfig
+from gllm_datastore.cache.cache import BaseCache as BaseCache
+from gllm_pipeline.alias import InputMapSpec as InputMapSpec
+from gllm_pipeline.pipeline.composer.guard_composer import GuardComposer as GuardComposer
+from gllm_pipeline.pipeline.composer.if_else_composer import IfElseComposer as IfElseComposer
+from gllm_pipeline.pipeline.composer.parallel_composer import ParallelComposer as ParallelComposer
+from gllm_pipeline.pipeline.composer.switch_composer import SwitchComposer as SwitchComposer
+from gllm_pipeline.pipeline.composer.toggle_composer import ToggleComposer as ToggleComposer
+from gllm_pipeline.pipeline.pipeline import Pipeline as Pipeline
+from gllm_pipeline.schema import PipelineSteps as PipelineSteps
+from gllm_pipeline.steps.pipeline_step import BasePipelineStep as BasePipelineStep
+from gllm_pipeline.steps.step_error_handler.step_error_handler import BaseStepErrorHandler as BaseStepErrorHandler
+from typing import Any, Callable, Self, overload
+
+class Composer:
+    """Fluent API for composing a pipeline out of simple steps.
+
+    The composer accumulates steps in order and can build a `Pipeline` with
+    a specified state type, recursion limit, and optional name.
+
+    The Composer uses a manager-style API:
+    1. When initialized with an existing `Pipeline` instance, it manages the pipeline in place.
+    2. If none is provided, a new empty `Pipeline` with the default `RAGState` is created.
+
+    Examples:
+    ```python
+    # With existing pipeline
+    composer = Composer(existing_pipeline).no_op().terminate()
+    pipeline = composer.done()
+    ```
+
+    ```python
+    # With new pipeline
+    composer = Composer().no_op().terminate()
+    pipeline = composer.done()
+    ```
+    """
+    def __init__(self, pipeline: Pipeline | None = None) -> None:
+        """Create a composer that manages a pipeline instance.
+
+        Args:
+            pipeline (Pipeline | None, optional): Pipeline to modify. Defaults to None,
+                in which case a new empty pipeline with the default `RAGState` is created.
+        """
+    def step(self, component: Component, input_map: InputMapSpec, output_state: str | list[str] | None = None, retry_config: RetryConfig | None = None, error_handler: BaseStepErrorHandler | None = None, name: str | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None) -> Self:
+        '''Append a component step.
+
+        Args:
+            component (Component): The component to execute.
+            input_map (InputMapSpec): Unified input mapping for the component.
+            output_state (str | list[str] | None, optional): Key to store the result in the pipeline state.
+                Defaults to None.
+            retry_config (RetryConfig | None, optional): Configuration for retry behavior using
+                GLLM Core\'s RetryConfig. Defaults to None, in which case no retry config is applied.
+            error_handler (BaseStepErrorHandler | None, optional): Error handler to use for this step.
+                Defaults to None, in which case no error handler is used.
+            name (str | None, optional): A unique identifier for this step. If None, a name will be
+                auto-generated with the prefix "step_". Defaults to None.
+            cache_store (BaseCache | None, optional): Cache store to be used for caching.
+                Defaults to None, in which case no cache store is used.
+            cache_config (dict[str, Any] | None, optional): Cache configuration to be used for caching.
+                Defaults to None, in which case no cache configuration is used.
+
+        Returns:
+            Self: The composer instance with this step appended.
+        '''
+    def map_reduce(self, input_map: InputMapSpec, output_state: str, map_func: Component | Callable[[dict[str, Any]], Any], reduce_func: Callable[[list[Any]], Any] = ..., retry_config: RetryConfig | None = None, error_handler: BaseStepErrorHandler | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None, name: str | None = None) -> Self:
+        """Append a map-reduce step.
+
+        Args:
+            input_map (InputMapSpec): Unified input mapping for the map function.
+            output_state (str): Key to store the reduced result in the pipeline state.
+            map_func (Component | Callable[[dict[str, Any]], Any]): Function to apply to each input item.
+            reduce_func (Callable[[list[Any]], Any], optional): Function to reduce mapped results.
+                Defaults to a function that returns the list of results as is.
+            retry_config (RetryConfig | None, optional): Retry behavior configuration.
+                Defaults to None, in which case no retry config is applied.
+            error_handler (BaseStepErrorHandler | None, optional): Error handler to use for this step.
+                Defaults to None, in which case the default error handler is used.
+            cache_store (BaseCache | None, optional): Cache store to be used for caching.
+                Defaults to None, in which case no cache store is used.
+            cache_config (dict[str, Any] | None, optional): Cache configuration to be used for caching.
+                Defaults to None, in which case no cache configuration is used.
+            name (str | None, optional): Optional name for the step. Defaults to None.
+
+        Returns:
+            Self: The composer instance with this step appended.
+        """
+    def subgraph(self, subgraph: Pipeline, input_map: InputMapSpec | None = None, output_state_map: dict[str, str] | None = None, retry_config: RetryConfig | None = None, error_handler: BaseStepErrorHandler | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None, name: str | None = None) -> Self:
+        """Append a subgraph step that executes another pipeline.
+
+        Args:
+            subgraph (Pipeline): The pipeline to be executed as a subgraph.
+            input_map (InputMapSpec | None, optional): Unified input mapping for the subgraph. Defaults to None.
+            output_state_map (dict[str, str] | None, optional): Map parent state keys to subgraph output keys.
+                Defaults to None, in which case all outputs are passed through.
+            retry_config (RetryConfig | None, optional): Retry behavior configuration.
+                Defaults to None, in which case no retry config is applied.
+            error_handler (BaseStepErrorHandler | None, optional): Error handler to use for this step.
+                Defaults to None, in which case the default error handler is used.
+            cache_store (BaseCache | None, optional): Cache store to be used for caching.
+                Defaults to None, in which case no cache store is used.
+            cache_config (dict[str, Any] | None, optional): Cache configuration to be used for caching.
+                Defaults to None, in which case no cache configuration is used.
+            name (str | None, optional): Optional name for the step. Defaults to None.
+
+        Returns:
+            Self: The composer instance with this step appended.
+        """
+    def log(self, message: str, is_template: bool = True, emit_kwargs: dict[str, Any] | None = None, retry_config: RetryConfig | None = None, name: str | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None) -> Self:
+        '''Append a log step.
+
+        Args:
+            message (str): The message to log.
+            is_template (bool, optional): Whether the message is a template. Defaults to True.
+            emit_kwargs (dict[str, Any] | None, optional): Keyword arguments to pass to the emit function.
+                Defaults to None.
+            retry_config (RetryConfig | None, optional): Configuration for retry behavior using
+                GLLM Core\'s RetryConfig. Defaults to None, in which case no retry config is applied.
+            name (str | None, optional): A unique identifier for this step. If None, a name will be
+                auto-generated with the prefix "step_". Defaults to None.
+            cache_store (BaseCache | None, optional): Cache store to be used for caching.
+                Defaults to None, in which case no cache store is used.
+            cache_config (dict[str, Any] | None, optional): Cache configuration to be used for caching.
+                Defaults to None, in which case no cache configuration is used.
+
+        Returns:
+            Self: The composer instance with this step appended.
+        '''
+    def no_op(self, name: str | None = None) -> Self:
+        '''Append a no-op step.
+
+        Args:
+            name (str | None, optional): A unique identifier for this step. If None, a name will be
+                auto-generated with the prefix "no_op_". Defaults to None.
+
+        Returns:
+            Self: The composer instance with this step appended.
+        '''
+    def bundle(self, input_states: list[str] | dict[str, str], output_state: str | list[str], retry_config: RetryConfig | None = None, error_handler: BaseStepErrorHandler | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None, name: str | None = None) -> Self:
+        """Append a bundle step to combine multiple state keys.
+
+        Args:
+            input_states (list[str] | dict[str, str]): List of keys to bundle as-is or mapping of
+                output field names to source state keys.
+            output_state (str | list[str]): State key(s) to store the bundled result.
+            retry_config (RetryConfig | None, optional): Retry configuration for the step. Defaults to None.
+            error_handler (BaseStepErrorHandler | None, optional): Error handler for this step. Defaults to None.
+            cache_store (BaseCache | None, optional): Cache store for this step. Defaults to None.
+            cache_config (dict[str, Any] | None, optional): Cache configuration for this step. Defaults to None.
+            name (str | None, optional): Optional name for the step. Defaults to None.
+
+        Returns:
+            Self: The composer instance with this step appended.
+        """
+    def transform(self, operation: Callable[[dict[str, Any]], Any], input_map: InputMapSpec, output_state: str | list[str], retry_config: RetryConfig | None = None, error_handler: BaseStepErrorHandler | None = None, name: str | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None) -> Self:
+        '''Append a state operator step.
+
+        Args:
+            operation (Callable[[dict[str, Any]], Any]): The operation to apply to the state.
+            input_map (InputMapSpec): Unified input mapping for the operation.
+            output_state (str | list[str]): State key(s) to store the result in.
+            retry_config (RetryConfig | None, optional): Configuration for retry behavior using
+                GLLM Core\'s RetryConfig. Defaults to None, in which case no retry config is applied.
+            error_handler (BaseStepErrorHandler | None, optional): Error handler to use for this step.
+                Defaults to None, in which case no error handler is used.
+            name (str | None, optional): A unique identifier for this step. If None, a name will be
+                auto-generated with the prefix "transform_". Defaults to None.
+            cache_store (BaseCache | None, optional): Cache store to be used for caching.
+                Defaults to None, in which case no cache store is used.
+            cache_config (dict[str, Any] | None, optional): Cache configuration to be used for caching.
+                Defaults to None, in which case no cache configuration is used.
+
+        Returns:
+            Self: The composer instance with this step appended.
+        '''
+    def terminate(self, name: str | None = None, retry_config: RetryConfig | None = None, error_handler: BaseStepErrorHandler | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None) -> Self:
+        '''Append a terminator step.
+
+        Args:
+            name (str | None, optional): A unique identifier for this step. If None, a name will be
+                auto-generated with the prefix "terminator_". Defaults to None.
+            retry_config (RetryConfig | None, optional): Configuration for retry behavior using
+                GLLM Core\'s RetryConfig. Defaults to None, in which case no retry config is applied.
+            error_handler (BaseStepErrorHandler | None, optional): Error handler to use for this step.
+                Defaults to None, in which case no error handler is used.
+            cache_store (BaseCache | None, optional): Cache store to be used for caching.
+                Defaults to None, in which case no cache store is used.
+            cache_config (dict[str, Any] | None, optional): Cache configuration to be used for caching.
+                Defaults to None, in which case no cache configuration is used.
+
+        Returns:
+            Self: The composer instance with this step appended.
+        '''
+    def if_else(self, condition: Component | Callable[[dict[str, Any]], bool], if_branch: BasePipelineStep | list[BasePipelineStep], else_branch: BasePipelineStep | list[BasePipelineStep], input_map: InputMapSpec | None = None, output_state: str | None = None, retry_config: RetryConfig | None = None, error_handler: BaseStepErrorHandler | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None, name: str | None = None) -> Self:
+        """Append a direct if/else conditional step.
+
+        This is the direct-style counterpart to the builder returned by `when(...)`.
+        Use this when you already have both branches available and prefer a single call.
+
+        Args:
+            condition (Component | Callable[[dict[str, Any]], bool]): The condition to evaluate.
+            if_branch (BasePipelineStep | list[BasePipelineStep]): Step(s) to execute if condition is true.
+            else_branch (BasePipelineStep | list[BasePipelineStep]): Step(s) to execute if condition is false.
+            input_map (InputMapSpec | None, optional): Unified input mapping for the condition. Defaults to None.
+            output_state (str | None, optional): Optional state key to store the condition result. Defaults to None.
+            retry_config (RetryConfig | None, optional): Configuration for retry behavior using GLLM Core's
+                `RetryConfig`. Defaults to None.
+            error_handler (BaseStepErrorHandler | None, optional): Strategy to handle errors during execution.
+                Defaults to None.
+            cache_store (BaseCache | None, optional): Cache store to be used for caching. Defaults to None.
+            cache_config (dict[str, Any] | None, optional): Cache configuration to be used for caching.
+                Defaults to None.
+            name (str | None, optional): A unique identifier for the conditional step. If None, a name will be
+                auto-generated. Defaults to None.
+
+        Returns:
+            Self: The composer instance with this step appended.
+        """
+    def when(self, condition: Component | Callable[[dict[str, Any]], bool], input_map: InputMapSpec | None = None, output_state: str | None = None, retry_config: RetryConfig | None = None, error_handler: BaseStepErrorHandler | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None, name: str | None = None) -> IfElseComposer:
+        """Begin an if/else conditional using a fluent builder.
+
+        Returns an `IfElseComposer` bound to this composer. Use `.then(...)` on the returned
+        builder to set the true-branch, `.otherwise(...)` to set the false-branch, and `.end()`
+        to finalize and return to the parent composer.
+
+        Args:
+            condition (Component | Callable[[dict[str, Any]], bool]): The condition to evaluate.
+            input_map (InputMapSpec | None, optional): Unified input mapping for this conditional. Defaults to None.
+            output_state (str | None, optional): Key to store the outcome state. Defaults to None.
+            retry_config (RetryConfig | None, optional): Retry behavior configuration. Defaults to None.
+            error_handler (BaseStepErrorHandler | None, optional): Error handler. Defaults to None.
+            cache_store (BaseCache | None, optional): Cache store to be used for caching. Defaults to None.
+            cache_config (dict[str, Any] | None, optional): Cache configuration. Defaults to None.
+            name (str | None, optional): Optional name for the step. Defaults to None.
+
+        Returns:
+            IfElseComposer: A builder to define the branches and finalize with `.end()`.
+        """
+    @overload
+    def switch(self, condition: Component | Callable[[dict[str, Any]], str], *, input_map: InputMapSpec | None = ..., output_state: str | None = ..., retry_config: RetryConfig | None = ..., error_handler: BaseStepErrorHandler | None = ..., cache_store: BaseCache | None = ..., cache_config: dict[str, Any] | None = ..., name: str | None = ...) -> SwitchComposer: ...
+    @overload
+    def switch(self, condition: Component | Callable[[dict[str, Any]], str], *, branches: dict[str, BasePipelineStep | list['BasePipelineStep']], input_map: InputMapSpec | None = ..., output_state: str | None = ..., default: BasePipelineStep | list['BasePipelineStep'] | None = ..., retry_config: RetryConfig | None = ..., error_handler: BaseStepErrorHandler | None = ..., cache_store: BaseCache | None = ..., cache_config: dict[str, Any] | None = ..., name: str | None = ...) -> Self: ...
+    @overload
+    def parallel(self, *, squash: bool = ..., input_map: InputMapSpec | None = ..., retry_config: RetryConfig | None = ..., error_handler: BaseStepErrorHandler | None = ..., cache_store: BaseCache | None = ..., cache_config: dict[str, Any] | None = ..., name: str | None = ...) -> ParallelComposer: ...
+    @overload
+    def parallel(self, *, branches: list['PipelineSteps'] | dict[str, 'PipelineSteps'], squash: bool = ..., input_map: InputMapSpec | None = ..., retry_config: RetryConfig | None = ..., error_handler: BaseStepErrorHandler | None = ..., cache_store: BaseCache | None = ..., cache_config: dict[str, Any] | None = ..., name: str | None = ...) -> Self: ...
+    def parallel(self, *, branches: list['PipelineSteps'] | dict[str, 'PipelineSteps'] | None = None, squash: bool = True, input_map: InputMapSpec | None = None, retry_config: RetryConfig | None = None, error_handler: BaseStepErrorHandler | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None, name: str | None = None) -> Self | ParallelComposer:
+        '''Create a parallel step (builder-style or direct-style).
+
+        This method supports two usage patterns:
+        1) Builder-style (no `branches` provided):
+            ```python
+            composer.parallel(input_states=["query"], squash=True, name="p")                 .fork(step_a)                 .fork([step_b1, step_b2])                 .end()
+            ```
+
+        2) Direct-style (provide `branches` list or dict):
+            ```python
+            composer.parallel(
+                branches=[step_a, [step_b1, step_b2]],
+                input_states=["query"],
+                squash=True,
+                name="p_direct",
+            )
+            ```
+
+        Args:
+            branches (list[PipelineSteps] | dict[str, PipelineSteps] | None, optional):
+                Branches to execute in parallel. Each branch can be a single step or a list of steps to run
+                sequentially. If omitted (builder-style), a `ParallelComposer` is returned to define forks via
+                `.fork()`; if provided (direct-style), the parallel step is created and appended immediately.
+                Defaults to None.
+            squash (bool, optional): Whether to squash execution into a single node (async gather). If True, the
+                parallel execution is represented by a single node; if False, native graph structures are used.
+                Defaults to True.
+            input_map (InputMapSpec | None, optional): Unified input mapping for all branches. Defaults to None.
+            retry_config (RetryConfig | None, optional): Retry behavior configuration. Defaults to None, in which case
+                no retry config is applied.
+            error_handler (BaseStepErrorHandler | None, optional): Strategy to handle errors during execution.
+                Defaults to None, in which case the default error handler is used.
+            cache_store (BaseCache | None, optional): Cache store to be used for caching. Defaults to None, in which
+                case no cache store is used.
+            cache_config (dict[str, Any] | None, optional): Cache configuration to be used for caching. Defaults to
+                None, in which case no cache configuration is used.
+            name (str | None, optional): A unique identifier for the parallel step. Defaults to None.
+
+        Returns:
+            ParallelComposer | Self: If `branches` is omitted, returns a `ParallelComposer` builder; otherwise,
+            returns the current composer after appending the constructed step.
+        '''
+    @overload
+    def guard(self, condition: Component | Callable[[dict[str, Any]], bool], *, success_branch: BasePipelineStep | list[BasePipelineStep], failure_branch: BasePipelineStep | list[BasePipelineStep] | None = ..., input_map: InputMapSpec | None = ..., output_state: str | None = ..., retry_config: RetryConfig | None = ..., error_handler: BaseStepErrorHandler | None = ..., cache_store: BaseCache | None = ..., cache_config: dict[str, Any] | None = ..., name: str | None = ...) -> Self: ...
+    @overload
+    def guard(self, condition: Component | Callable[[dict[str, Any]], bool], *, success_branch: None = ..., failure_branch: BasePipelineStep | list[BasePipelineStep] | None = ..., input_map: InputMapSpec | None = ..., output_state: str | None = ..., retry_config: RetryConfig | None = ..., error_handler: BaseStepErrorHandler | None = ..., cache_store: BaseCache | None = ..., cache_config: dict[str, Any] | None = ..., name: str | None = ...) -> GuardComposer: ...
+    @overload
+    def toggle(self, condition: Component | Callable[[dict[str, Any]], bool] | str, *, if_branch: BasePipelineStep | list[BasePipelineStep], input_map: InputMapSpec | None = ..., output_state: str | None = ..., retry_config: RetryConfig | None = ..., error_handler: BaseStepErrorHandler | None = ..., cache_store: BaseCache | None = ..., cache_config: dict[str, Any] | None = ..., name: str | None = ...) -> Self: ...
+    @overload
+    def toggle(self, condition: Component | Callable[[dict[str, Any]], bool] | str, *, if_branch: None = ..., input_map: InputMapSpec | None = ..., output_state: str | None = ..., retry_config: RetryConfig | None = ..., error_handler: BaseStepErrorHandler | None = ..., cache_store: BaseCache | None = ..., cache_config: dict[str, Any] | None = ..., name: str | None = ...) -> ToggleComposer: ...
+    def toggle(self, condition: Component | Callable[[dict[str, Any]], bool] | str, *, if_branch: BasePipelineStep | list[BasePipelineStep] | None = None, input_map: InputMapSpec | None = None, output_state: str | None = None, retry_config: RetryConfig | None = None, error_handler: BaseStepErrorHandler | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None, name: str | None = None) -> Self | ToggleComposer:
+        """Create a toggle conditional (builder-style or direct-style).
+
+        This method supports two usage patterns:
+        1) Builder-style (no `if_branch` provided):
+            ```python
+            composer.toggle(condition)                 .then(enabled_steps)                 .end()
+            ```
+
+        2) Direct-style (provide `if_branch`):
+            ```python
+            composer.toggle(
+                condition,
+                if_branch=enabled_steps,
+            )
+            ```
+
+        Args:
+            condition (Component | Callable[[dict[str, Any]], bool] | str): The condition to evaluate.
+                If a `Component`, it must return a boolean value. If a `Callable`, it must return
+                a boolean value. If a `str`, it will be looked up in the merged state data.
+            if_branch (BasePipelineStep | list[BasePipelineStep] | None, optional):
+                Steps to execute if condition is true. If omitted (builder-style), a `ToggleComposer`
+                is returned to define the branch via `.then()`; if provided (direct-style),
+                the toggle step is created and appended immediately. Defaults to None, in which case
+                a `ToggleComposer` is returned.
+            input_map (InputMapSpec | None, optional): Unified input mapping for the condition. Defaults to None.
+            output_state (str | None, optional): Optional state key to store the condition result. Defaults to None.
+            retry_config (RetryConfig | None, optional): Configuration for retry behavior using GLLM Core's
+                `RetryConfig`. Defaults to None.
+            error_handler (BaseStepErrorHandler | None, optional): Strategy to handle errors during execution.
+                Defaults to None.
+            cache_store (BaseCache | None, optional): Cache store to be used for caching. Defaults to None.
+            cache_config (dict[str, Any] | None, optional): Cache configuration to be used for caching.
+                Defaults to None.
+            name (str | None, optional): A unique identifier for the conditional step. If None, a name will be
+                auto-generated. Defaults to None.
+
+        Returns:
+            ToggleComposer | Self: If `if_branch` is omitted, returns a `ToggleComposer` builder; otherwise,
+                returns the current composer after appending the constructed step.
+        """
+    def done(self) -> Pipeline:
+        """Return the composed `Pipeline` instance.
+
+        This does not build the execution graph. The graph is built when
+        `Pipeline.graph` or `Pipeline.build_graph()` is accessed/called.
+
+        Returns:
+            Pipeline: The composed pipeline instance.
+        """

gllm_pipeline/pipeline/composer/guard_composer.pyi

@@ -0,0 +1,58 @@
+from gllm_core.schema import Component as Component
+from gllm_core.utils.retry import RetryConfig as RetryConfig
+from gllm_datastore.cache.cache import BaseCache as BaseCache
+from gllm_pipeline.alias import InputMapSpec as InputMapSpec
+from gllm_pipeline.pipeline.composer.composer import Composer as Composer
+from gllm_pipeline.steps.pipeline_step import BasePipelineStep as BasePipelineStep
+from gllm_pipeline.steps.step_error_handler.step_error_handler import BaseStepErrorHandler as BaseStepErrorHandler
+from typing import Any, Callable, Self
+
+class GuardComposer:
+    """Fluent builder for a guard conditional.
+
+    Usage:
+        composer.guard(condition).on_success(success_branch).on_failure(failure_branch).end()
+        composer.guard(condition).on_success(success_branch).end()  # failure defaults to termination
+
+    After setting the branches, call `.end()` to append the guard step and
+    return back to the parent `Composer`.
+    """
+    def __init__(self, parent: Composer, condition: Component | Callable[[dict[str, Any]], bool], output_state: str | None = None, input_map: InputMapSpec | None = None, retry_config: RetryConfig | None = None, error_handler: BaseStepErrorHandler | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None, name: str | None = None) -> None:
+        '''Initialize the GuardComposer.
+
+        Args:
+            parent (Composer): The parent composer instance.
+            condition (Component | Callable[[dict[str, Any]], bool]): The condition to evaluate.
+            output_state (str | None, optional): Optional state key to store condition result. Defaults to None.
+            input_map (InputMapSpec | None, optional): Unified input mapping for the condition. Defaults to None.
+            retry_config (RetryConfig | None, optional): Retry configuration. Defaults to None.
+            error_handler (BaseStepErrorHandler | None, optional): Error handler. Defaults to None.
+            cache_store (BaseCache | None, optional): Optional cache store. Defaults to None.
+            cache_config (dict[str, Any] | None, optional): Optional cache config. Defaults to None.
+            name (str | None, optional): Optional name for the resulting step. Defaults to None, in which case
+                a name will be auto-generated with the prefix "Guard_".
+        '''
+    def on_success(self, branch: BasePipelineStep | list[BasePipelineStep]) -> Self:
+        """Define the branch to execute when the condition is true (successful).
+
+        Args:
+            branch (BasePipelineStep | list[BasePipelineStep]): The step(s) for the success branch.
+
+        Returns:
+            Self: The builder instance for chaining.
+        """
+    def on_failure(self, branch: BasePipelineStep | list[BasePipelineStep]) -> Self:
+        """Define the branch to execute when the condition is false (failed).
+
+        Args:
+            branch (BasePipelineStep | list[BasePipelineStep]): The step(s) for the failure branch.
+
+        Returns:
+            Self: The builder instance for chaining.
+        """
+    def end(self) -> Composer:
+        """Finalize and append the guard step to the parent composer.
+
+        Returns:
+            Composer: The parent composer for continued chaining.
+        """

gllm_pipeline/pipeline/composer/if_else_composer.pyi

@@ -0,0 +1,57 @@
+from gllm_core.schema import Component as Component
+from gllm_core.utils.retry import RetryConfig as RetryConfig
+from gllm_datastore.cache.cache import BaseCache as BaseCache
+from gllm_pipeline.alias import InputMapSpec as InputMapSpec
+from gllm_pipeline.pipeline.composer.composer import Composer as Composer
+from gllm_pipeline.steps.pipeline_step import BasePipelineStep as BasePipelineStep
+from gllm_pipeline.steps.step_error_handler.step_error_handler import BaseStepErrorHandler as BaseStepErrorHandler
+from typing import Any, Callable, Self
+
+class IfElseComposer:
+    """Fluent builder for an if/else conditional.
+
+    Usage:
+        composer.when(cond).then(if_branch).otherwise(else_branch).end()
+
+    After setting both branches, call `.end()` to append the conditional step and
+    return back to the parent `Composer`.
+    """
+    def __init__(self, parent: Composer, condition: Component | Callable[[dict[str, Any]], bool], output_state: str | None = None, input_map: InputMapSpec | None = None, retry_config: RetryConfig | None = None, error_handler: BaseStepErrorHandler | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None, name: str | None = None) -> None:
+        '''Initialize the IfElseComposer.
+
+        Args:
+            parent (Composer): The parent composer instance.
+            condition (Component | Callable[[dict[str, Any]], bool]): The condition to evaluate.
+            output_state (str | None, optional): Optional state key to store condition result. Defaults to None.
+            input_map (InputMapSpec | None, optional): Unified input mapping for the condition. Defaults to None.
+            retry_config (RetryConfig | None, optional): Retry configuration. Defaults to None.
+            error_handler (BaseStepErrorHandler | None, optional): Error handler. Defaults to None.
+            cache_store (BaseCache | None, optional): Optional cache store. Defaults to None.
+            cache_config (dict[str, Any] | None, optional): Optional cache config. Defaults to None.
+            name (str | None, optional): Optional name for the resulting step. Defaults to None, in which case
+                a name will be auto-generated with the prefix "IfElse_".
+        '''
+    def then(self, branch: BasePipelineStep | list[BasePipelineStep]) -> Self:
+        """Define the branch to execute when the condition is true.
+
+        Args:
+            branch (BasePipelineStep | list[BasePipelineStep]): The step(s) for the true branch.
+
+        Returns:
+            Self: The builder instance for chaining.
+        """
+    def otherwise(self, branch: BasePipelineStep | list[BasePipelineStep]) -> Self:
+        """Define the branch to execute when the condition is false.
+
+        Args:
+            branch (BasePipelineStep | list[BasePipelineStep]): The step(s) for the false branch.
+
+        Returns:
+            Self: The builder instance for chaining.
+        """
+    def end(self) -> Composer:
+        """Finalize and append the conditional step to the parent composer.
+
+        Returns:
+            Composer: The parent composer for continued chaining.
+        """

gllm_pipeline/pipeline/composer/parallel_composer.pyi

@@ -0,0 +1,47 @@
+from gllm_core.utils.retry import RetryConfig as RetryConfig
+from gllm_datastore.cache.cache import BaseCache as BaseCache
+from gllm_pipeline.alias import InputMapSpec as InputMapSpec
+from gllm_pipeline.pipeline.composer.composer import Composer as Composer
+from gllm_pipeline.schema import PipelineSteps as PipelineSteps
+from gllm_pipeline.steps.pipeline_step import BasePipelineStep as BasePipelineStep
+from gllm_pipeline.steps.step_error_handler.step_error_handler import BaseStepErrorHandler as BaseStepErrorHandler
+from typing import Any, Self
+
+class ParallelComposer:
+    '''Fluent builder for a parallel step.
+
+    Usage:
+        composer.parallel(name="p").fork(step_a).fork([step_b1, step_b2]).end()
+
+    The builder collects forks as branches and constructs a `ParallelStep`
+    using the functional helper `_func.parallel(...)`.
+    '''
+    def __init__(self, parent: Composer, *, squash: bool = True, input_map: InputMapSpec | None = None, retry_config: RetryConfig | None = None, error_handler: BaseStepErrorHandler | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None, name: str | None = None) -> None:
+        """Initialize the ParallelComposer.
+
+        Args:
+            parent (Composer): The parent composer instance.
+            squash (bool, optional): Whether to squash execution into a single node (async gather).
+                Defaults to True.
+            input_map (InputMapSpec | None, optional): Unified input mapping for all branches. Defaults to None.
+            retry_config (RetryConfig | None, optional): Retry configuration. Defaults to None.
+            error_handler (BaseStepErrorHandler | None, optional): Error handler. Defaults to None.
+            cache_store (BaseCache | None, optional): Optional cache store. Defaults to None.
+            cache_config (dict[str, Any] | None, optional): Optional cache config. Defaults to None.
+            name (str | None, optional): Optional name for the resulting step. Defaults to None.
+        """
+    def fork(self, branch: BasePipelineStep | list[BasePipelineStep]) -> Self:
+        """Add a fork (branch) to execute in parallel.
+
+        Args:
+            branch (BasePipelineStep | list[BasePipelineStep]): Step(s) for this fork.
+
+        Returns:
+            Self: The builder instance for chaining.
+        """
+    def end(self) -> Composer:
+        """Finalize and append the parallel step to the parent composer.
+
+        Returns:
+            Composer: The parent composer for continued chaining.
+        """

gllm_pipeline/pipeline/composer/switch_composer.pyi

@@ -0,0 +1,57 @@
+from gllm_core.schema import Component as Component
+from gllm_core.utils.retry import RetryConfig as RetryConfig
+from gllm_datastore.cache.cache import BaseCache as BaseCache
+from gllm_pipeline.alias import InputMapSpec as InputMapSpec
+from gllm_pipeline.pipeline.composer.composer import Composer as Composer
+from gllm_pipeline.steps.pipeline_step import BasePipelineStep as BasePipelineStep
+from gllm_pipeline.steps.step_error_handler.step_error_handler import BaseStepErrorHandler as BaseStepErrorHandler
+from typing import Any, Callable, Self
+
+class SwitchComposer:
+    '''Fluent builder for a switch conditional.
+
+    Usage:
+        composer.switch(cond).case("A", step_a).case("B", step_b).end()
+
+    Optionally call `.default(...)` to set a fallback branch.
+    '''
+    def __init__(self, parent: Composer, condition: Component | Callable[[dict[str, Any]], str], output_state: str | None = None, input_map: InputMapSpec | None = None, retry_config: RetryConfig | None = None, error_handler: BaseStepErrorHandler | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None, name: str | None = None) -> None:
+        '''Initialize the SwitchComposer.
+
+        Args:
+            parent (Composer): The parent composer instance.
+            condition (Component | Callable[[dict[str, Any]], str]): The condition to evaluate.
+            output_state (str | None, optional): Optional state key to store condition result. Defaults to None.
+            input_map (InputMapSpec | None, optional): Unified input mapping for the condition. Defaults to None.
+            retry_config (RetryConfig | None, optional): Retry configuration. Defaults to None.
+            error_handler (BaseStepErrorHandler | None, optional): Error handler. Defaults to None.
+            cache_store (BaseCache | None, optional): Optional cache store. Defaults to None.
+            cache_config (dict[str, Any] | None, optional): Optional cache config. Defaults to None.
+            name (str | None, optional): Optional name for the resulting step. Defaults to None, in which case
+                a name will be auto-generated with the prefix "Switch_".
+        '''
+    def case(self, key: str, branch: BasePipelineStep | list[BasePipelineStep]) -> Self:
+        """Add a case branch.
+
+        Args:
+            key (str): Case key to match against condition result.
+            branch (BasePipelineStep | list[BasePipelineStep]): Step(s) to execute for this case.
+
+        Returns:
+            Self: The builder instance for chaining.
+        """
+    def default(self, branch: BasePipelineStep | list[BasePipelineStep]) -> Self:
+        """Set the default branch for unmatched cases.
+
+        Args:
+            branch (BasePipelineStep | list[BasePipelineStep]): Default fallback branch.
+
+        Returns:
+            Self: The builder instance for chaining.
+        """
+    def end(self) -> Composer:
+        """Finalize and append the switch conditional to the parent composer.
+
+        Returns:
+            Composer: The parent composer for continued chaining.
+        """

gllm_pipeline/pipeline/composer/toggle_composer.pyi

@@ -0,0 +1,48 @@
+from gllm_core.schema import Component as Component
+from gllm_core.utils.retry import RetryConfig as RetryConfig
+from gllm_datastore.cache.cache import BaseCache as BaseCache
+from gllm_pipeline.alias import InputMapSpec as InputMapSpec
+from gllm_pipeline.pipeline.composer.composer import Composer as Composer
+from gllm_pipeline.steps.pipeline_step import BasePipelineStep as BasePipelineStep
+from gllm_pipeline.steps.step_error_handler.step_error_handler import BaseStepErrorHandler as BaseStepErrorHandler
+from typing import Any, Callable, Self
+
+class ToggleComposer:
+    """Fluent builder for a toggle conditional.
+
+    Usage:
+        composer.toggle(condition).then(enabled_branch).end()
+
+    After setting the enabled branch, call `.end()` to append the toggle step and
+    return back to the parent `Composer`.
+    """
+    def __init__(self, parent: Composer, condition: Component | Callable[[dict[str, Any]], bool] | str, output_state: str | None = None, input_map: InputMapSpec | None = None, retry_config: RetryConfig | None = None, error_handler: BaseStepErrorHandler | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None, name: str | None = None) -> None:
+        '''Initialize the ToggleComposer.
+
+        Args:
+            parent (Composer): The parent composer instance.
+            condition (Component | Callable[[dict[str, Any]], bool] | str): The condition to evaluate.
+            output_state (str | None, optional): Optional state key to store condition result. Defaults to None.
+            input_map (InputMapSpec | None, optional): Unified input mapping for the condition. Defaults to None.
+            retry_config (RetryConfig | None, optional): Retry configuration. Defaults to None.
+            error_handler (BaseStepErrorHandler | None, optional): Error handler. Defaults to None.
+            cache_store (BaseCache | None, optional): Optional cache store. Defaults to None.
+            cache_config (dict[str, Any] | None, optional): Optional cache config. Defaults to None.
+            name (str | None, optional): Optional name for the resulting step. Defaults to None, in which case
+                a name will be auto-generated with the prefix "Toggle_".
+        '''
+    def then(self, branch: BasePipelineStep | list[BasePipelineStep]) -> Self:
+        """Define the branch to execute when the condition is true.
+
+        Args:
+            branch (BasePipelineStep | list[BasePipelineStep]): The step(s) for the enabled branch.
+
+        Returns:
+            Self: The builder instance for chaining.
+        """
+    def end(self) -> Composer:
+        """Finalize and append the toggle step to the parent composer.
+
+        Returns:
+            Composer: The parent composer for continued chaining.
+        """

gllm_pipeline/pipeline/pipeline.pyi

@@ -105,7 +105,7 @@ class Pipeline:
     steps: Incomplete
     recursion_limit: Incomplete
     name: Incomplete
-    def __init__(self, steps: list[BasePipelineStep], state_type: TypedDict | type[BaseModel] = ..., input_type: TypedDict | type[BaseModel] | None = None, output_type: TypedDict | type[BaseModel] | None = None, recursion_limit: int = 30, name: str | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None) -> None:
+    def __init__(self, steps: list[BasePipelineStep] | None = None, state_type: TypedDict | type[BaseModel] = ..., input_type: TypedDict | type[BaseModel] | None = None, output_type: TypedDict | type[BaseModel] | None = None, recursion_limit: int = 30, name: str | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None) -> None:
         '''Initializes the Pipeline with the given steps and state type.
 
         Args:
@@ -176,6 +176,24 @@ class Pipeline:
         Returns:
             ExclusionManager: The exclusion manager for this pipeline.
         """
+    @property
+    def composer(self) -> Composer:
+        """Get a Composer instance that manages this pipeline.
+
+        The Composer provides a fluent API for building pipelines by chaining
+        step-adding methods. It allows for easy composition of pipeline steps
+        in a readable, chainable manner.
+
+        Returns:
+            Composer: A composer instance that manages this pipeline.
+        """
+    def clear(self) -> None:
+        """Clears the pipeline by resetting steps, graph, and app to their initial state.
+
+        This method resets the pipeline to an empty state, clearing all steps and
+        invalidating any built graph or compiled app. Useful for reusing a pipeline
+        instance with different configurations.
+        """
     async def invoke(self, initial_state: dict[str, Any] | BaseModel, config: dict[str, Any] | None = None) -> dict[str, Any]:
         '''Runs the pipeline asynchronously with the given initial state and configuration.
 

gllm_pipeline.pyi

@@ -11,11 +11,16 @@ __name__ = ...
 import os
 import __future__
 import pydantic
-import asyncio
-import copy
 import typing
 import gllm_core
+import gllm_core.schema
 import gllm_core.utils
+import gllm_core.utils.retry
+import gllm_datastore
+import gllm_datastore.cache
+import gllm_datastore.cache.cache
+import asyncio
+import copy
 import gllm_core.utils.imports
 import gllm_core.utils.logger_manager
 import gllm_inference
@@ -24,12 +29,11 @@ import langgraph
 import langgraph.graph
 import langgraph.graph.state
 import gllm_pipeline.exclusions.ExclusionManager
+import gllm_pipeline.pipeline.composer.Composer
 import gllm_core.event
 import gllm_core.event.event_emitter
 import random
 import string
-import gllm_core.schema
-import gllm_core.utils.retry
 import abc
 import functools
 import inspect

{gllm_pipeline_binary-0.4.17.dist-info → gllm_pipeline_binary-0.4.18.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: gllm-pipeline-binary
-Version: 0.4.17
+Version: 0.4.18
 Summary: A library containing components related to Gen AI applications pipeline orchestration.
 Author-email: Dimitrij Ray <dimitrij.ray@gdplabs.id>, Henry Wicaksono <henry.wicaksono@gdplabs.id>, Kadek Denaya <kadek.d.r.diana@gdplabs.id>
 Requires-Python: <3.13,>=3.11

{gllm_pipeline_binary-0.4.17.dist-info → gllm_pipeline_binary-0.4.18.dist-info}/RECORD

@@ -1,5 +1,5 @@
-gllm_pipeline.cp312-win_amd64.pyd,sha256=HDCc1HSRbor2YeZDDCAKgIyCmDeF0i4-r4ZUMSlpiBQ,1410048
-gllm_pipeline.pyi,sha256=tmgrVnNDommRVuGW3mV-MlyI_QL32Sj-bmApduqMqaI,976
+gllm_pipeline.cp312-win_amd64.pyd,sha256=ViARHONPCsEeMKM5d96xnZJR89FtN42V65gNgDd3A6w,1572352
+gllm_pipeline.pyi,sha256=aentP4mHbDiRLyQ5Sn84-1sVyTbaLL9Vq60I1quEXNo,1108
 gllm_pipeline/__init__.pyi,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 gllm_pipeline/alias.pyi,sha256=MbRJJjogWHp6PAmtoi_1xrRmxkvGq4C_NllWk8sYiog,272
 gllm_pipeline/types.pyi,sha256=CV3cEAxlNsnVatYz5iCxqmEFPEqeKW5vv-qUD3FpF54,241
@@ -7,8 +7,15 @@ gllm_pipeline/exclusions/__init__.pyi,sha256=_LwIlqmH4Iiksn7p09d2vZG4Ek8CdKC8UcD
 gllm_pipeline/exclusions/exclusion_manager.pyi,sha256=DzoL-2KeTRmFgJEo8rzYViFYKbzZVTZGJmKvzaoTC0M,2960
 gllm_pipeline/exclusions/exclusion_set.pyi,sha256=11XTt6IfkHpzomcNybA78SfWlp752Z3AGhXfm2rL0Fk,1685
 gllm_pipeline/pipeline/__init__.pyi,sha256=1IKGdMvmLWEiOOmAKFNUPm-gdw13zrnU1gs7tDNzgEU,168
-gllm_pipeline/pipeline/pipeline.pyi,sha256=AZI2tGsNKPMyS7yN7UjFshebLcmU4dQSHoyKgsmpxpE,13437
+gllm_pipeline/pipeline/pipeline.pyi,sha256=ykxgXD38TM9X5mXsPmzJSMxsCKoV6Q_tRbuRDk0bVXg,14226
 gllm_pipeline/pipeline/states.pyi,sha256=EiyfBPwrVDZ336w5wyD1q8W4E6G1uZNzsP-bzrHDumo,6464
+gllm_pipeline/pipeline/composer/__init__.pyi,sha256=-hcOUQgpTRt1QjQfRurTf-UApFnTrhilx6vN-gYd5J0,666
+gllm_pipeline/pipeline/composer/composer.pyi,sha256=foztmOTsqdd6CW1CY4QQrObe2shy_yvEopz_knwAmFk,26697
+gllm_pipeline/pipeline/composer/guard_composer.pyi,sha256=YfbXmzyU3CwAvGnCfM-6MVcTdxk53-j6Cv3IdzNr_-c,3335
+gllm_pipeline/pipeline/composer/if_else_composer.pyi,sha256=uGyd1S7P5uXdER_fAzVIftg0yovZjMbN-L9JxgHxZNw,3196
+gllm_pipeline/pipeline/composer/parallel_composer.pyi,sha256=rL6dc9Rm1Bzo_Acl0yLEEUZZQmNmfuNNpU4jhjt3Yzg,2593
+gllm_pipeline/pipeline/composer/switch_composer.pyi,sha256=he78REg0v3Sguv89VTUck9Q3jpFYSg_9Xh0MUki9TxY,3146
+gllm_pipeline/pipeline/composer/toggle_composer.pyi,sha256=7tEEDSSwOoPeiyYeFSjLqsamLtS-enuXsqBFIrjCNYA,2835
 gllm_pipeline/steps/__init__.pyi,sha256=f_dgel-CsDow7nSWYQDVTQYOogwvty8tEeh2lZautqM,1967
 gllm_pipeline/steps/_func.pyi,sha256=fKL6aCobBmjo7vznRKJeeML4VmJtoQhD8G5L5vG3Pao,60843
 gllm_pipeline/steps/branching_step.pyi,sha256=iNarrcZgWfiRdr8CJfGm8GzUlYq13Rx5cgYXnBsNWN4,1041
@@ -39,7 +46,7 @@ gllm_pipeline/utils/mermaid.pyi,sha256=B096GTXxVAO--kw3UDsbysOsnjGOytYfozX39YaM2
 gllm_pipeline/utils/retry_converter.pyi,sha256=JPUuaGzKpVLshrbhX9rQHYl5XmC9GDa59rGU-FtOpWM,1128
 gllm_pipeline/utils/step_execution.pyi,sha256=8dGj6_VAHT7cgmg8QPJN65XDKTu3Kj4NTtkDM_AF7GA,930
 gllm_pipeline.build/.gitignore,sha256=aEiIwOuxfzdCmLZe4oB1JsBmCUxwG8x-u-HBCV9JT8E,1
-gllm_pipeline_binary-0.4.17.dist-info/METADATA,sha256=MKODVs0hh7LYIygsrvc9Q5H2IRhaYggOyahao2uu5U8,3454
-gllm_pipeline_binary-0.4.17.dist-info/WHEEL,sha256=x5rgv--I0NI0IT1Lh9tN1VG2cI637p3deednwYLKnxc,96
-gllm_pipeline_binary-0.4.17.dist-info/top_level.txt,sha256=C3yeOtoE6ZhuOnBEq_FFc_Rp954IHJBlB6fBgSdAWYI,14
-gllm_pipeline_binary-0.4.17.dist-info/RECORD,,
+gllm_pipeline_binary-0.4.18.dist-info/METADATA,sha256=vQOhDqu4EmBX6XZC5fYlLDyr2dlK1ExS6LOdztrXgD8,3454
+gllm_pipeline_binary-0.4.18.dist-info/WHEEL,sha256=x5rgv--I0NI0IT1Lh9tN1VG2cI637p3deednwYLKnxc,96
+gllm_pipeline_binary-0.4.18.dist-info/top_level.txt,sha256=C3yeOtoE6ZhuOnBEq_FFc_Rp954IHJBlB6fBgSdAWYI,14
+gllm_pipeline_binary-0.4.18.dist-info/RECORD,,