build_tools.pipeline_tui.services.pipeline
==========================================

.. py:module:: build_tools.pipeline_tui.services.pipeline

.. autoapi-nested-parse::

   Pipeline execution service for Pipeline TUI.

   This module provides subprocess-based execution of the syllable extraction
   pipeline stages (extraction, normalization, annotation) with progress
   monitoring, cancellation support, and log capture.

   **Design Principles:**

   - Non-blocking execution via asyncio subprocess
   - Cancellation support via process termination
   - Real-time log capture and progress updates
   - Clean error handling with informative messages

   **Usage Example:**

       >>> from build_tools.pipeline_tui.services.pipeline import PipelineExecutor
       >>> from build_tools.pipeline_tui.core.state import ExtractionConfig, ExtractorType
       >>>
       >>> config = ExtractionConfig(
       ...     extractor_type=ExtractorType.PYPHEN,
       ...     source_path=Path("/data/corpus"),
       ...     output_dir=Path("_working/output"),
       ...     language="en_US",
       ... )
       >>>
       >>> executor = PipelineExecutor()
       >>> result = await executor.run_pipeline(
       ...     config=config,
       ...     run_normalize=True,
       ...     run_annotate=True,
       ...     on_progress=lambda stage, pct, msg: print(f"{stage}: {pct}% - {msg}"),
       ... )



Attributes
----------

.. autoapisummary::

   build_tools.pipeline_tui.services.pipeline.ProgressCallback


Classes
-------

.. autoapisummary::

   build_tools.pipeline_tui.services.pipeline.StageResult
   build_tools.pipeline_tui.services.pipeline.PipelineResult
   build_tools.pipeline_tui.services.pipeline.PipelineExecutor


Module Contents
---------------

.. py:data:: ProgressCallback

.. py:class:: StageResult

   Result from executing a single pipeline stage.

   .. attribute:: stage

      Name of the stage (extraction, normalization, annotation)

   .. attribute:: success

      Whether the stage completed successfully

   .. attribute:: output_path

      Path to the output (run directory or file)

   .. attribute:: return_code

      Process return code

   .. attribute:: stdout

      Captured standard output

   .. attribute:: stderr

      Captured standard error

   .. attribute:: duration_seconds

      How long the stage took

   .. attribute:: error_message

      Error message if stage failed


   .. py:attribute:: stage
      :type:  str


   .. py:attribute:: success
      :type:  bool


   .. py:attribute:: output_path
      :type:  pathlib.Path | None
      :value: None



   .. py:attribute:: return_code
      :type:  int
      :value: 0



   .. py:attribute:: stdout
      :type:  str
      :value: ''



   .. py:attribute:: stderr
      :type:  str
      :value: ''



   .. py:attribute:: duration_seconds
      :type:  float
      :value: 0.0



   .. py:attribute:: error_message
      :type:  str
      :value: ''



.. py:class:: PipelineResult

   Result from executing the full pipeline.

   .. attribute:: success

      Whether all stages completed successfully

   .. attribute:: stages

      List of individual stage results

   .. attribute:: run_directory

      Path to the output run directory

   .. attribute:: cancelled

      Whether the pipeline was cancelled

   .. attribute:: total_duration_seconds

      Total pipeline duration


   .. py:attribute:: success
      :type:  bool


   .. py:attribute:: stages
      :type:  list[StageResult]
      :value: []



   .. py:attribute:: run_directory
      :type:  pathlib.Path | None
      :value: None



   .. py:attribute:: cancelled
      :type:  bool
      :value: False



   .. py:attribute:: total_duration_seconds
      :type:  float
      :value: 0.0



.. py:class:: PipelineExecutor

   Executes pipeline stages as subprocesses with progress monitoring.

   This class manages the execution of extraction, normalization, and
   annotation stages as separate Python subprocesses. It provides:

   - Real-time stdout/stderr capture
   - Progress updates via callbacks
   - Cancellation support
   - Clean error handling

   .. attribute:: _current_process

      Currently running subprocess (for cancellation)

   .. attribute:: _cancelled

      Flag indicating if cancellation was requested

   .. admonition:: Example

      >>> executor = PipelineExecutor()
      >>> result = await executor.run_pipeline(config, on_progress=callback)
      >>> if result.success:
      ...     print(f"Output: {result.run_directory}")

   Initialize the pipeline executor.


   .. py:method:: run_pipeline(config, run_normalize = True, run_annotate = True, on_progress = None, on_log = None)
      :async:


      Execute the full pipeline with configured stages.

      Runs extraction, then optionally normalization and annotation.
      Progress is reported via callbacks for UI updates.

      :param config: Extraction configuration specifying source, output, etc.
      :param run_normalize: Whether to run normalization after extraction
      :param run_annotate: Whether to run annotation after normalization
      :param on_progress: Callback for progress updates (stage, percent, message)
      :param on_log: Callback for log messages

      :returns: PipelineResult with success status and stage results

      :raises ValueError: If config is invalid



   .. py:method:: cancel()
      :async:


      Cancel the currently running pipeline.

      Terminates the current subprocess if one is running.