gllm-pipeline-binary 0.4.21__cp312-cp312-macosx_13_0_arm64.whl

gllm_pipeline/steps/parallel_step.pyi

@@ -0,0 +1,128 @@
+from _typeshed import Incomplete
+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, PipelineSteps as PipelineSteps
+from gllm_pipeline.steps.branching_step import BranchingStep as BranchingStep
+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 gllm_pipeline.utils.copy import safe_deepcopy as safe_deepcopy
+from gllm_pipeline.utils.error_handling import ValidationError as ValidationError, create_error_context as create_error_context
+from gllm_pipeline.utils.graph import create_edge as create_edge
+from gllm_pipeline.utils.has_inputs_mixin import HasInputsMixin as HasInputsMixin
+from gllm_pipeline.utils.input_map import shallow_dump as shallow_dump
+from gllm_pipeline.utils.mermaid import MERMAID_HEADER as MERMAID_HEADER
+from gllm_pipeline.utils.step_execution import execute_sequential_steps as execute_sequential_steps
+from langgraph.graph import StateGraph as StateGraph
+from langgraph.runtime import Runtime as Runtime
+from langgraph.types import RetryPolicy as RetryPolicy
+from pydantic import BaseModel as BaseModel
+from typing import Any
+
+class ParallelStep(BranchingStep, HasInputsMixin):
+    """A pipeline step that executes multiple branches in parallel.
+
+    This step wraps multiple branches and executes them concurrently, then merges their results.
+    Each branch can be either a single step or a list of steps to be executed sequentially.
+
+    The step supports two execution modes controlled by the `squash` parameter:
+    1. Squashed (default): Uses asyncio.gather() to run branches in parallel within a single LangGraph node. Use for:
+       a. Better raw performance
+       b. Simpler implementation
+       c. Less overhead
+       d. Less transparent for debugging and tracing
+    2. Expanded (squash=False): Creates a native LangGraph structure with multiple parallel paths. Use for:
+       a. More native LangGraph integration
+       b. More transparent for debugging and tracing
+
+    For memory optimization, you can specify input_states to pass only specific keys to branches.
+    This is especially useful when the state is large but branches only need specific parts of it.
+    If input_states is None (default), all state keys will be passed.
+
+    Attributes:
+        name (str): A unique identifier for this pipeline step.
+        branches (dict[str, PipelineSteps]): The branches to execute in parallel.
+        input_map (dict[str, str | Val] | None): Unified input map.
+        squash (bool): Whether to squash execution into a single node.
+            1. If True, uses asyncio.gather() to run branches in parallel. This will create a single node.
+            2. If False, uses native LangGraph structures for parallelism. This will create multiple nodes.
+        retry_policy (RetryPolicy | None): Configuration for retry behavior using LangGraph's RetryPolicy.
+    """
+    squash: Incomplete
+    branches: Incomplete
+    def __init__(self, name: str, branches: list[PipelineSteps] | dict[str, PipelineSteps], input_states: list[str] | None = None, squash: bool = True, runtime_config_map: dict[str, str] | None = None, fixed_args: dict[str, Any] | 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) -> None:
+        '''Initialize a new ParallelStep.
+
+        Args:
+            name (str): A unique identifier for this pipeline step.
+            branches (list | dict[str, PipelineSteps]): The branches to execute in parallel. Can be either:
+                **List format:**
+                    Each branch can be:
+                    1. A single step
+                    2. A list of steps to execute sequentially
+                    Example: [step1, [step2, step3], step4]
+                **Dict format:**
+                    Keys are branch names, values can be:
+                    1. A single step
+                    2. A list of steps to execute sequentially
+                    Example: {"analysis": step1, "validation": [step2, step3], "cleanup": step4}
+                    Enables more intuitive step exclusion using branch names.
+            input_states (list[str] | None, optional): Keys from the state to pass to branches.
+                If None, all state keys will be passed. Defaults to None.
+            squash (bool, optional): Whether to squash execution into a single node.
+                1. If True, uses asyncio.gather() to run branches in parallel. This will create a single node.
+                2. If False, uses native LangGraph structures for parallelism. This will create multiple nodes.
+                Defaults to True.
+            runtime_config_map (dict[str, str] | None, optional): Mapping of input keys to runtime config keys.
+                Defaults to None.
+            fixed_args (dict[str, Any] | None, optional): Fixed arguments to be passed to the component.
+                Defaults to None, in which case an empty dictionary is used.
+            input_map (InputMapSpec | None, optional):
+                Unified input map. Can be a dict (arg -> str|Val) or a list with elements:
+                1. str for identity mapping
+                2. dict[str, str] for state/config mapping
+                3. dict[str, Val] for fixed args.
+                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): Strategy to handle errors during execution.
+                Defaults to None, in which case the RaiseStepErrorHandler 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.
+        '''
+    def add_to_graph(self, graph: StateGraph, previous_endpoints: list[str], retry_policy: RetryPolicy | None = None) -> list[str]:
+        """Handle both squashed and expanded modes.
+
+        For squashed mode: add the parallel step as a single node.
+        For expanded mode: add the parallel step as a single node and add children to graph.
+
+        Args:
+            graph (StateGraph): The graph to add this step to.
+            previous_endpoints (list[str]): Endpoints from previous steps to connect to.
+            retry_policy (RetryPolicy | None, optional): Retry policy to propagate to child steps.
+                Defaults to None, in which case the retry policy of the step is used.
+
+        Returns:
+            list[str]: Exit points after adding all child steps.
+        """
+    async def execute(self, state: dict[str, Any], runtime: Runtime[dict[str, Any] | BaseModel]) -> dict[str, Any] | None:
+        """Execute all branches in parallel and merge their results.
+
+        This method is only used for the squashed approach. For the expanded approach,
+        the execution is handled by the graph structure.
+
+        Args:
+            state (dict[str, Any]): The current state of the pipeline.
+            runtime (Runtime[dict[str, Any] | BaseModel]): Runtime information for this step's execution.
+
+        Returns:
+            dict[str, Any] | None: The merged results from all parallel branches, or None if no updates were produced.
+
+        Raises:
+            asyncio.CancelledError: If execution is cancelled, preserved with added context.
+            BaseInvokerError: If an error occurs during LM invocation.
+            RuntimeError: For all other exceptions during execution, wrapped with context information.
+            TimeoutError: If execution times out, preserved with added context.
+            ValidationError: If input validation fails.
+        """

gllm_pipeline/steps/pipeline_step.pyi

@@ -0,0 +1,231 @@
+import abc
+from _typeshed import Incomplete
+from abc import ABC, abstractmethod
+from gllm_core.utils.retry import RetryConfig as RetryConfig
+from gllm_datastore.cache.cache import BaseCache as BaseCache
+from gllm_pipeline.alias import PipelineState as PipelineState
+from gllm_pipeline.exclusions import ExclusionSet as ExclusionSet
+from gllm_pipeline.pipeline.pipeline import Pipeline as Pipeline
+from gllm_pipeline.steps.step_error_handler import RaiseStepErrorHandler as RaiseStepErrorHandler
+from gllm_pipeline.steps.step_error_handler.step_error_handler import BaseStepErrorHandler as BaseStepErrorHandler
+from gllm_pipeline.utils.error_handling import ErrorContext as ErrorContext
+from gllm_pipeline.utils.graph import create_edge as create_edge
+from gllm_pipeline.utils.retry_converter import retry_config_to_langgraph_policy as retry_config_to_langgraph_policy
+from langgraph.graph import StateGraph as StateGraph
+from langgraph.runtime import Runtime as Runtime
+from langgraph.types import RetryPolicy as RetryPolicy
+from pydantic import BaseModel as BaseModel
+from typing import Any
+
+LANGGRAPH_CONFIG_PREFIX: str
+
+class BasePipelineStep(ABC, metaclass=abc.ABCMeta):
+    '''The base class for all pipeline steps.
+
+    A pipeline step represents a single operation or task within a larger processing pipeline.
+    Each step must implement:
+    1. execute() - to perform the actual operation
+    2. add_to_graph() - to integrate with the pipeline structure (optional, default implementation provided)
+
+    The default implementation of add_to_graph is suitable for steps that:
+    1. Have a single entry point
+    2. Have a single exit point
+    3. Connect to all previous endpoints
+
+    For more complex graph structures (e.g., conditional branching), steps should override add_to_graph.
+
+    Examples:
+        1. Basic Usage:
+            ```python
+            step = MyCustomStep("my_step")
+            ```
+
+        2. Adding Step Level Caching:
+            ```python
+            step = MyCustomStep(
+                "my_step",
+                cache_store=cache_store,
+                cache_config={"ttl": 1800}
+            )
+
+        3. Retry Configuration:
+            ```python
+            retry_config = RetryConfig(max_retries=3, backoff_factor=2)
+            step = MyCustomStep(
+                "my_step",
+                retry_config=retry_config
+            )
+            ```
+
+        4. Error Handling:
+            ```python
+            step = MyCustomStep(
+                "my_step",
+                error_handler=error_handler
+            )
+            ```
+
+    Attributes:
+        name (str): A unique identifier for the pipeline step.
+        retry_policy (RetryPolicy | None): Configuration for retry behavior using LangGraph\'s RetryPolicy.
+        cache_store ("BaseCache" | None): The cache store used for caching step results, if configured.
+        is_cache_enabled (bool): Property indicating whether caching is enabled for this step.
+    '''
+    name: Incomplete
+    error_handler: Incomplete
+    retry_policy: Incomplete
+    cache_store: Incomplete
+    def __init__(self, name: str, retry_config: RetryConfig | None = None, error_handler: BaseStepErrorHandler | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None) -> None:
+        '''Initializes a new pipeline step.
+
+        Args:
+            name (str): A unique identifier for the pipeline step.
+            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.
+                The RetryConfig is automatically converted to LangGraph\'s RetryPolicy when needed for internal use.
+                Note that `timeout` is not supported and will be ignored.
+            error_handler (BaseStepErrorHandler | None, optional): Strategy to handle errors during execution.
+                Defaults to None, in which case the RaiseStepErrorHandler is used.
+            cache_store ("BaseCache" | None, optional): The cache store to use for caching step results.
+                Defaults to None. If None, no caching will be used.
+            cache_config (dict[str, Any] | None, optional): Configuration for the cache store.
+                1. key_func: A function to generate cache keys. If None, the cache instance will use its own key
+                    function.
+                2. name: The name of the cache. If None, the cache instance will use its own key function.
+                3. ttl: The time-to-live for the cache. If None, the cache will not have a TTL.
+                4. matching_strategy: The strategy for matching cache keys.
+                    If None, the cache instance will use "exact".
+                5. matching_config: Configuration for the matching strategy.
+                    If None, the cache instance will use its own default matching strategy configuration.
+
+        Caching Mechanism:
+            When a cache_store is provided, the step\'s execution method is automatically
+            wrapped with a cache decorator. This means:
+            1. Before execution, the cache is checked for existing results based on input parameters
+            2. If a cached result exists and is valid, it\'s returned immediately
+            3. If no cached result exists, the step executes normally and the result is cached
+            4. Cache keys are generated from the step\'s input state and configuration
+            5. The cache name defaults to "step_{step_name}" if not specified
+        '''
+    @property
+    def is_cache_enabled(self) -> bool:
+        """Check if this step has caching enabled.
+
+        Returns:
+            bool: True if caching is enabled, False otherwise.
+        """
+    @property
+    def is_excluded(self) -> bool:
+        """Whether this step is excluded from execution/graph integration.
+
+        Returns:
+            bool: True if the step is excluded, False otherwise.
+        """
+    @is_excluded.setter
+    def is_excluded(self, value: bool) -> None:
+        """Set the exclusion state for this step.
+
+        Args:
+            value (bool): Exclusion flag.
+        """
+    def add_to_graph(self, graph: StateGraph, previous_endpoints: list[str], retry_policy: RetryPolicy | None = None) -> list[str]:
+        """Integrates this step into the pipeline's internal structure.
+
+        This method is responsible for:
+        1. Adding the step's node(s) to the graph if not already present
+        2. Creating edges from previous endpoints to this step's entry points
+        3. Returning this step's exit points (endpoints)
+
+        This method provides a default implementation suitable for simple steps.
+        Steps with more complex graph structures should override this method.
+
+        This method is used by `Pipeline` to manage the pipeline's execution flow.
+        It should not be called directly by users.
+
+        Args:
+            graph (StateGraph): The internal representation of the pipeline structure.
+            previous_endpoints (list[str]): The endpoints from previous steps to connect to.
+            retry_policy (RetryPolicy | None): Configuration for retry behavior using LangGraph's RetryPolicy.
+                If None, the retry policy of the step is used. If the step is not a retryable step,
+                this parameter is ignored.
+
+        Returns:
+            list[str]: The exit points (endpoints) of this step.
+        """
+    @abstractmethod
+    async def execute(self, state: PipelineState, runtime: Runtime[dict[str, Any] | BaseModel]) -> dict[str, Any] | None:
+        """Executes the operation defined for this pipeline step.
+
+        This method should be implemented by subclasses to perform the actual processing or computation for this step.
+
+        Args:
+            state (PipelineState): The current state of the pipeline, containing all data.
+            runtime (Runtime[dict[str, Any] | BaseModel]): Runtime information for this step's execution.
+
+        Returns:
+            dict[str, Any] | None: The update to the pipeline state after this step's operation.
+                This should include new or modified data produced by this step, not the entire state.
+                Returns None if no state update is needed.
+
+        Raises:
+            NotImplementedError: If the subclass does not implement this method.
+        """
+    async def execute_direct(self, state: dict[str, Any], runtime: Runtime[dict[str, Any] | BaseModel]) -> dict[str, Any] | None:
+        """Execute this step directly, bypassing graph-based execution.
+
+        This method is used when a step needs to be executed directly, such as in parallel execution.
+        The default implementation calls _execute_with_error_handling for consistent error handling.
+
+        Args:
+            state (dict[str, Any]): The current state of the pipeline.
+            runtime (Runtime[dict[str, Any] | BaseModel]): Runtime information for this step's execution.
+
+        Returns:
+            dict[str, Any] | None: Updates to apply to the pipeline state, or None if no updates.
+        """
+    def apply_exclusions(self, exclusions: ExclusionSet) -> None:
+        """Apply exclusions to this step.
+
+        Args:
+            exclusions (ExclusionSet): The exclusion set to apply.
+        """
+    def get_mermaid_diagram(self) -> str:
+        """Generates a Mermaid diagram representation of the pipeline step.
+
+        This method provides a default implementation that can be overridden by subclasses
+        to provide more detailed or specific diagrams.
+
+        It is recommended to implement this method for subclasses that have multiple connections to other steps.
+
+        Returns:
+            str: Empty string.
+        """
+    def __or__(self, other: BasePipelineStep | Pipeline) -> Pipeline:
+        """Combines this step with another step or pipeline.
+
+        This method allows for easy composition of pipeline steps using the | operator.
+
+        Args:
+            other (BasePipelineStep | Pipeline): Another step or pipeline to combine with this one.
+
+        Returns:
+            Pipeline: A new pipeline containing the combined steps.
+        """
+    def __lshift__(self, other: BasePipelineStep | Pipeline) -> Pipeline:
+        """Combines this step with another step or pipeline using the '<<' operator.
+
+        Args:
+            other (BasePipelineStep | Pipeline): The step or pipeline to add after this step.
+
+        Returns:
+            Pipeline: A new pipeline with this step followed by the other step or pipeline.
+        """
+    def __rshift__(self, other: BasePipelineStep | Pipeline) -> Pipeline:
+        """Combines this step with another step or pipeline using the '>>' operator.
+
+        Args:
+            other (BasePipelineStep | Pipeline): The step or pipeline to include this step in.
+
+        Returns:
+            Pipeline: A new pipeline with this step included in the other step or pipeline.
+        """

gllm_pipeline/steps/state_operator_step.pyi

@@ -0,0 +1,75 @@
+from _typeshed import Incomplete
+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, PipelineState as PipelineState
+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 gllm_pipeline.utils.async_utils import execute_callable as execute_callable
+from gllm_pipeline.utils.error_handling import ErrorContext as ErrorContext
+from gllm_pipeline.utils.has_inputs_mixin import HasInputsMixin as HasInputsMixin
+from gllm_pipeline.utils.input_map import shallow_dump as shallow_dump
+from langgraph.runtime import Runtime
+from pydantic import BaseModel as BaseModel
+from typing import Any, Callable
+
+class StateOperatorStep(BasePipelineStep, HasInputsMixin):
+    """A pipeline step that performs an operation on the pipeline state and updates it.
+
+    This step executes a given operation using selected data from the current pipeline state and runtime configuration,
+    then updates the state with the operation's result.
+
+    Attributes:
+        name (str): A unique identifier for this pipeline step.
+        input_map (dict[str, str | Val] | None): Unified input map.
+        output_state (str | list[str]): Key(s) to store the operation result in the pipeline state.
+        operation (Callable[[dict[str, Any]], Any]): The operation to execute.
+            Accepts a dictionary of input data, which consists of the extracted state and runtime configuration.
+        retry_policy (RetryPolicy | None): Configuration for retry behavior using LangGraph's RetryPolicy.
+    """
+    output_state: Incomplete
+    operation: Incomplete
+    def __init__(self, name: str, input_states: list[str] | None = None, output_state: str | list[str] | None = None, operation: Callable[[dict[str, Any]], Any] | None = None, runtime_config_map: dict[str, str] | None = None, fixed_args: dict[str, Any] | 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) -> None:
+        '''Initializes a new StateOperatorStep.
+
+        Args:
+            name (str): A unique identifier for this pipeline step.
+            input_states (list[str]): Keys of the state data required by the operation.
+            output_state (str | list[str]): Key(s) to store the operation result in the pipeline state.
+            operation (Callable[[dict[str, Any]], Any]): The operation to execute.
+                It should accept a dictionary of input data and return the operation result.
+            runtime_config_map (dict[str, str] | None, optional): Mapping of operation input arguments to
+                runtime configuration keys. Defaults to None.
+            fixed_args (dict[str, Any] | None, optional): Fixed arguments to be passed to the operation.
+                Defaults to None.
+            input_map (InputMapSpec | None, optional):
+                Unified input map. Can be a dict (arg -> str|Val) or a list with elements:
+                1. str for identity mapping
+                2. dict[str, str] for state/config mapping
+                3. dict[str, Val] for fixed args.
+                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): Strategy to handle errors during execution.
+                Defaults to None, in which case the RaiseStepErrorHandler 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.
+        '''
+    async def execute(self, state: PipelineState, runtime: Runtime[dict[str, Any] | BaseModel]) -> dict[str, Any]:
+        """Executes the operation and processes its output.
+
+        This method validates inputs, prepares data, executes the operation, and formats the output for integration
+        into the pipeline state.
+
+        Args:
+            state (PipelineState): The current state of the pipeline, containing all data.
+            runtime (Runtime[dict[str, Any] | BaseModel]): Runtime information for this step's execution.
+
+        Returns:
+            dict[str, Any]: The update to the pipeline state after this step's operation.
+                This includes new or modified data produced by the operation, not the entire state.
+
+        Raises:
+            RuntimeError: If an error occurs during operation execution.
+        """

gllm_pipeline/steps/step_error_handler/__init__.pyi

@@ -0,0 +1,6 @@
+from gllm_pipeline.steps.step_error_handler.empty_step_error_handler import EmptyStepErrorHandler as EmptyStepErrorHandler
+from gllm_pipeline.steps.step_error_handler.fallback_step_error_handler import FallbackStepErrorHandler as FallbackStepErrorHandler
+from gllm_pipeline.steps.step_error_handler.keep_step_error_handler import KeepStepErrorHandler as KeepStepErrorHandler
+from gllm_pipeline.steps.step_error_handler.raise_step_error_handler import RaiseStepErrorHandler as RaiseStepErrorHandler
+
+__all__ = ['EmptyStepErrorHandler', 'FallbackStepErrorHandler', 'KeepStepErrorHandler', 'RaiseStepErrorHandler']

gllm_pipeline/steps/step_error_handler/empty_step_error_handler.pyi

@@ -0,0 +1,20 @@
+from _typeshed import Incomplete
+from gllm_pipeline.steps.step_error_handler.step_error_handler import BaseStepErrorHandler as BaseStepErrorHandler
+from gllm_pipeline.utils.error_handling import ErrorContext as ErrorContext
+from langgraph.runtime import Runtime as Runtime
+from pydantic import BaseModel as BaseModel
+
+class EmptyStepErrorHandler(BaseStepErrorHandler):
+    """Strategy that replace the current state of the output states to None on error.
+
+    Attributes:
+        output_state (list[str]): Output key(s) to map input values to.
+    """
+    output_state: Incomplete
+    def __init__(self, output_state: str | list[str]) -> None:
+        """Initialize the strategy with optional output state mapping.
+
+        Args:
+            output_state (str | list[str]): Output key(s) to map input values to.
+                Can be a single string, list of strings.
+        """

gllm_pipeline/steps/step_error_handler/fallback_step_error_handler.pyi

@@ -0,0 +1,24 @@
+from _typeshed import Incomplete
+from gllm_pipeline.steps.step_error_handler.step_error_handler import BaseStepErrorHandler as BaseStepErrorHandler
+from gllm_pipeline.utils.error_handling import ErrorContext as ErrorContext
+from langgraph.runtime import Runtime as Runtime
+from pydantic import BaseModel as BaseModel
+from typing import Any, Callable
+
+class FallbackStepErrorHandler(BaseStepErrorHandler):
+    """Strategy that executes a fallback callable on error.
+
+    Attributes:
+        fallback (Callable[[Exception, dict[str, Any], Runtime[dict[str, Any] | BaseModel], ErrorContext], Any]):
+            A callable that generates the fallback state dynamically.
+            It should accept (error, state, runtime, context) and return a fallback state.
+    """
+    fallback: Incomplete
+    def __init__(self, fallback: Callable[[Exception, dict[str, Any], Runtime[dict[str, Any] | BaseModel], ErrorContext], Any]) -> None:
+        """Initialize the strategy with a fallback callable.
+
+        Args:
+            fallback (Callable[[Exception, dict[str, Any], Runtime[dict[str, Any] | BaseModel], ErrorContext], Any]):
+                A callable that generates the fallback state dynamically.
+                It should accept (error, state, runtime, context) and return a fallback state.
+        """

gllm_pipeline/steps/step_error_handler/keep_step_error_handler.pyi

@@ -0,0 +1,9 @@
+from gllm_pipeline.steps.step_error_handler.step_error_handler import BaseStepErrorHandler as BaseStepErrorHandler
+from gllm_pipeline.utils.error_handling import ErrorContext as ErrorContext
+from langgraph.runtime import Runtime as Runtime
+from pydantic import BaseModel as BaseModel
+
+class KeepStepErrorHandler(BaseStepErrorHandler):
+    """Strategy that preserves the current state on error."""
+    def __init__(self) -> None:
+        """Initialize the keep error handler."""

gllm_pipeline/steps/step_error_handler/raise_step_error_handler.pyi

@@ -0,0 +1,9 @@
+from gllm_pipeline.steps.step_error_handler.step_error_handler import BaseStepErrorHandler as BaseStepErrorHandler
+from gllm_pipeline.utils.error_handling import ErrorContext as ErrorContext
+from langgraph.runtime import Runtime as Runtime
+from pydantic import BaseModel as BaseModel
+
+class RaiseStepErrorHandler(BaseStepErrorHandler):
+    """Strategy that raises exceptions with enhanced context."""
+    def __init__(self) -> None:
+        """Initialize the raise error handler."""

gllm_pipeline/steps/step_error_handler/step_error_handler.pyi

@@ -0,0 +1,46 @@
+import abc
+from _typeshed import Incomplete
+from abc import ABC
+from gllm_pipeline.utils.error_handling import ErrorContext as ErrorContext
+from langgraph.runtime import Runtime as Runtime
+from pydantic import BaseModel as BaseModel
+from typing import Any
+
+class BaseStepErrorHandler(ABC, metaclass=abc.ABCMeta):
+    """Abstract base class for error handling strategies.
+
+    Attributes:
+        log_level (int): The logging level to use when logging errors.
+        logger (logging.Logger): The logger to use when logging errors.
+    """
+    log_level: Incomplete
+    logger: Incomplete
+    def __init__(self, log_level: int = ...) -> None:
+        """Initialize the error handler with a specific log level.
+
+        Args:
+            log_level (int): The logging level to use when logging errors.
+                Defaults to logging.ERROR. Common values:
+                1. logging.DEBUG: Detailed information for debugging.
+                2. logging.INFO: General information messages.
+                3. logging.WARNING: Warning messages.
+                4. logging.ERROR: Error messages (default).
+                5. logging.CRITICAL: Critical error messages.
+        """
+    def handle(self, error: Exception, state: dict[str, Any], runtime: Runtime[dict[str, Any] | BaseModel], context: ErrorContext) -> dict[str, Any] | None:
+        """Handle an error that occurred during pipeline step execution.
+
+        This method logs the error first, then delegates to the concrete implementation.
+
+        Args:
+            error (Exception): The exception that was raised.
+            state (dict[str, Any]): The current pipeline state when the error occurred.
+            runtime (Runtime[dict[str, Any] | BaseModel]): Runtime information for this step's execution.
+            context (ErrorContext): Additional context about the error.
+
+        Returns:
+            dict[str, Any] | None: State updates to apply, or None if no updates needed.
+
+        Raises:
+            Exception: May raise exceptions based on the strategy implementation.
+        """

gllm_pipeline/steps/subgraph_step.pyi

@@ -0,0 +1,90 @@
+from _typeshed import Incomplete
+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, PipelineState as PipelineState
+from gllm_pipeline.exclusions import ExclusionSet as ExclusionSet
+from gllm_pipeline.pipeline.pipeline import Pipeline as Pipeline
+from gllm_pipeline.steps.composite_step import BaseCompositeStep as BaseCompositeStep
+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 gllm_pipeline.utils.error_handling import ErrorContext as ErrorContext
+from gllm_pipeline.utils.has_inputs_mixin import HasInputsMixin as HasInputsMixin
+from gllm_pipeline.utils.input_map import shallow_dump as shallow_dump
+from langgraph.runtime import Runtime as Runtime
+from pydantic import BaseModel as BaseModel
+from typing import Any
+
+class SubgraphStep(BaseCompositeStep, HasInputsMixin):
+    """A pipeline step that executes another pipeline as a subgraph.
+
+    This step allows for encapsulation and reuse of pipeline logic by treating another pipeline as a step.
+    The subgraph can have its own state schema, and this step handles the mapping between the parent and
+    subgraph states.
+
+    Attributes:
+        name (str): A unique identifier for this pipeline step.
+        subgraph (Pipeline): The pipeline to be executed as a subgraph.
+        input_map (dict[str, str | Val] | None): Unified input map.
+        output_state_map (dict[str, str]): Mapping of parent pipeline state keys to subgraph output keys.
+        retry_policy (RetryPolicy | None): Configuration for retry behavior using LangGraph's RetryPolicy.
+    """
+    subgraph: Incomplete
+    output_state_map: Incomplete
+    def __init__(self, name: str, subgraph: Pipeline, input_state_map: dict[str, str] | None = None, output_state_map: dict[str, str] | None = None, runtime_config_map: dict[str, str] | None = None, fixed_args: dict[str, Any] | 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) -> None:
+        '''Initializes a new SubgraphStep.
+
+        Args:
+            name (str): A unique identifier for this pipeline step.
+            subgraph (Pipeline): The pipeline to be executed as a subgraph.
+            input_state_map (dict[str, str]): Mapping of subgraph input keys to parent pipeline state keys.
+                Defaults to None.
+            output_state_map (dict[str, str] | None, optional): Mapping of parent pipeline state keys to
+                subgraph output keys. Defaults to None.
+            runtime_config_map (dict[str, str] | None, optional): Mapping of subgraph input keys to runtime
+                configuration keys. Defaults to None, in which case an empty dictionary is used.
+            fixed_args (dict[str, Any] | None, optional): Fixed arguments to be passed to the subgraph.
+                Defaults to None, in which case an empty dictionary is used.
+            input_map (InputMapSpec | None, optional):
+                Unified input map. Can be a dict (arg -> str|Val) or a list with elements:
+                1. str for identity mapping
+                2. dict[str, str] for state/config mapping
+                3. dict[str, Val] for fixed args.
+                Defaults to None.
+            retry_config (RetryConfig | None, optional): Configuration for retry behavior using the SDK\'s RetryConfig.
+                If None, no retry policy is applied.
+            error_handler (BaseStepErrorHandler | None, optional): Error handler to be used for this step.
+                If None, no error handler is applied.
+            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.
+        '''
+    async def execute(self, state: PipelineState, runtime: Runtime[dict[str, Any] | BaseModel]) -> dict[str, Any]:
+        """Executes the subgraph and processes its output.
+
+        This method prepares data, executes the subgraph, and formats the output for integration
+        into the parent pipeline state. It only uses keys that are actually present in the state,
+        ignoring missing keys to prevent errors.
+
+        Args:
+            state (PipelineState): The current state of the pipeline, containing all data.
+            runtime (Runtime[dict[str, Any] | BaseModel]): Runtime information for this step's execution.
+
+        Returns:
+            dict[str, Any]: The update to the pipeline state after this step's operation.
+                This includes new or modified data produced by the subgraph, not the entire state.
+                If a requested output key is not present in the subgraph result, its value will be None.
+
+        Raises:
+            RuntimeError: If an error occurs during subgraph execution, with details about which step caused the error.
+        """
+    is_excluded: Incomplete
+    def apply_exclusions(self, exclusions: ExclusionSet) -> None:
+        """Apply exclusions to this subgraph and its children.
+
+        Subgraph has no internal structural changes. It marks itself and
+        uniformly propagates child exclusions to all subgraph steps.
+
+        Args:
+            exclusions (ExclusionSet): The exclusion set to apply.
+        """