Struct Pipeline 

pub struct Pipeline { /* private fields */ }

A composable pipeline that passes a string through a sequence of named stages.

Guarantees

• Stages execute in insertion order
• First stage failure short-circuits remaining stages (unless an error handler is set)
• Non-panicking

Implementations

impl Pipeline

pub fn new() -> Self

Create a new empty pipeline.

pub fn with_error_handler( self, handler: impl Fn(&str, &str) -> String + Send + Sync + 'static, ) -> Self

Attach a recovery callback for stage failures.

When a stage fails, handler(stage_name, error_message) is called. The returned string becomes the input to the next stage. If no handler is set, stage failures propagate as errors.

pub fn add_stage( self, name: impl Into<String>, handler: impl Fn(String) -> Result<String, AgentRuntimeError> + Send + Sync + 'static, ) -> Self

Append a stage to the pipeline.

pub fn prepend_stage( self, name: impl Into<String>, handler: impl Fn(String) -> Result<String, AgentRuntimeError> + Send + Sync + 'static, ) -> Self

Insert a stage at the front of the pipeline (index 0).

All existing stages are shifted to higher indices. The pipeline’s stage names remain unique only if the caller ensures uniqueness.

pub fn is_empty(&self) -> bool

Return true if the pipeline has no stages.

pub fn has_error_handler(&self) -> bool

Return true if a stage error handler has been configured via with_error_handler.

pub fn stage_count(&self) -> usize

Return the number of stages in the pipeline.

pub fn has_stage(&self, name: &str) -> bool

Return true if a stage with the given name is registered.

pub fn stage_names(&self) -> Vec<&str>

Return the names of all stages in execution order.

pub fn stage_names_owned(&self) -> Vec<String>

Return the names of all stages as owned Strings.

Unlike stage_names this does not borrow self, making it easier to use the result after self is moved or mutated.

pub fn get_stage_name_at(&self, index: usize) -> Option<&str>

Return the name of the stage at zero-based index, or None if out of bounds.

pub fn stage_index(&self, name: &str) -> Option<usize>

Return the zero-based index of the first stage with the given name.

Returns None if no stage with that name exists.

pub fn first_stage_name(&self) -> Option<&str>

Return the name of the first stage in the pipeline, or None if empty.

pub fn last_stage_name(&self) -> Option<&str>

Return the name of the last stage in the pipeline, or None if empty.

pub fn remove_stage(&mut self, name: &str) -> bool

Remove the first stage whose name equals name.

Returns true if a stage was found and removed, false if no stage with that name was registered.

pub fn rename_stage( &mut self, old_name: &str, new_name: impl Into<String>, ) -> bool

Rename the first stage whose name equals old_name to new_name.

Returns true if a stage was found and renamed, false if no stage with old_name exists.

pub fn clear(&mut self)

Remove all stages from the pipeline.

The error handler (if any) is preserved; only the stage list is cleared.

pub fn count_stages_matching(&self, keyword: &str) -> usize

Return the number of stages whose name contains keyword (case-insensitive).

pub fn swap_stages(&mut self, a: &str, b: &str) -> bool

Swap the positions of two stages by name.

Returns true if both stages were found and swapped. Returns false if either name is not present in the pipeline (no state change).

pub fn run(&self, input: String) -> Result<String, AgentRuntimeError>

Execute the pipeline, passing input through each stage in order.

pub fn execute_timed( &self, input: String, ) -> Result<PipelineResult, AgentRuntimeError>

Execute the pipeline with per-stage timing.

Returns a PipelineResult whose stage_timings contains (stage_name, duration_ms) pairs in execution order.

pub fn description(&self) -> String

Return a human-readable description of this pipeline.

Format: "Pipeline[{n} stage(s): stage1 → stage2 → ...]". Returns "Pipeline[empty]" when no stages have been added.

Intended for logging and debugging — not a stable serialization format.

pub fn has_unique_stage_names(&self) -> bool

Return true if every stage in the pipeline has a unique name.

Duplicate stage names can lead to ambiguous lookups with stage_index and has_stage. Use this predicate to assert pipeline integrity during construction.

pub fn stage_names_sorted(&self) -> Vec<&str>

Return stage names sorted in ascending lexicographic order.

Unlike stage_names, which returns names in insertion order, this always produces a stable sort regardless of the order stages were added.

pub fn longest_stage_name(&self) -> Option<&str>

Return the name of the stage with the most bytes, or None for an empty pipeline.

When multiple stages share the maximum byte length, the first one in insertion order is returned.

pub fn shortest_stage_name(&self) -> Option<&str>

Return the name of the stage with the fewest bytes, or None for an empty pipeline.

When multiple stages share the minimum byte length, the first one in insertion order is returned.

pub fn stage_name_lengths(&self) -> Vec<usize>

Return the byte lengths of all stage names in order.

Returns an empty Vec for an empty pipeline.

pub fn avg_stage_name_length(&self) -> f64

Return the average byte length of stage names.

Returns 0.0 for an empty pipeline.

pub fn stages_containing(&self, substring: &str) -> Vec<&str>

Return the names of stages whose name contains substring (case-sensitive).

Returns an empty Vec if no stage names match.

pub fn stage_is_first(&self, name: &str) -> bool

Return true if the stage named name is the first stage in the pipeline.

Returns false if the pipeline is empty or the stage is not present.

pub fn stage_is_last(&self, name: &str) -> bool

Return true if the stage named name is the last stage in the pipeline.

Returns false if the pipeline is empty or the stage is not present.

pub fn total_stage_name_bytes(&self) -> usize

Return the total byte length of all stage names combined.

Returns 0 for an empty pipeline.

pub fn stages_before(&self, name: &str) -> Vec<&str>

Return the names of all stages that appear before name in the pipeline.

Returns an empty Vec if name is not present, is the first stage, or the pipeline is empty.

pub fn stages_after(&self, name: &str) -> Vec<&str>

Return the names of all stages that appear after name in the pipeline.

Returns an empty Vec if name is not present, is the last stage, or the pipeline is empty.

pub fn stage_pairs(&self) -> Vec<(&str, &str)>

Return all consecutive stage name pairs (from, to) in pipeline order.

For a pipeline with stages [a, b, c] this returns [("a", "b"), ("b", "c")]. Returns an empty Vec for pipelines with fewer than two stages.

pub fn stage_count_above_name_len(&self, min_len: usize) -> usize

Return the number of stages whose name byte length is strictly greater than min_len.

Returns 0 for an empty pipeline or when no stage name exceeds min_len bytes.

pub fn stage_count_below_name_len(&self, max_len: usize) -> usize

Return the number of stages whose name is strictly shorter than max_len bytes.

Complement of stage_count_above_name_len.

pub fn stage_at(&self, idx: usize) -> Option<&str>

Return the name of the stage at position idx, or None if idx is out of bounds.

Indices are zero-based from the start of the pipeline.

pub fn stages_reversed(&self) -> Vec<&str>

Return stage names in reverse pipeline order.

For a pipeline [a, b, c] this returns ["c", "b", "a"]. Returns an empty Vec for an empty pipeline.

pub fn pipeline_is_empty(&self) -> bool

Return true if the pipeline has no stages.

Equivalent to stage_count() == 0.

pub fn unique_stage_names(&self) -> Vec<&str>

Return sorted, deduplicated stage names.

Stage names are unique by construction, so this is equivalent to stage_names sorted alphabetically. Useful for set-membership checks without knowing insertion order.

pub fn stage_names_with_prefix<'a>(&'a self, prefix: &str) -> Vec<&'a str>

Return all stage names whose name starts with prefix.

Returned names preserve pipeline order. Returns an empty Vec when no stage name has the given prefix or the pipeline is empty.

pub fn contains_stage_with_prefix(&self, prefix: &str) -> bool

Return true if any stage name starts with prefix.

A convenience predicate over stage_names_with_prefix that avoids allocating a Vec when only existence is needed.

pub fn stages_with_suffix<'a>(&'a self, suffix: &str) -> Vec<&'a str>

Return the names of all stages whose name ends with suffix.

Complementary to stage_names_with_prefix; useful for filtering stages by a common naming convention (e.g. "_validate"). Returns an empty Vec when no stage matches or the pipeline is empty.

pub fn has_stage_with_name_containing(&self, substr: &str) -> bool

Return true if any stage name contains substr as a substring.

A quick existence check that avoids allocating a full Vec. Returns false for an empty pipeline.

pub fn stage_names_containing<'a>(&'a self, substr: &str) -> Vec<&'a str>

Return the names of all stages whose name contains substr.

Complements has_stage_with_name_containing by returning the full list rather than just a boolean. Returns an empty Vec when no stage matches or the pipeline is empty.

pub fn stage_name_bytes_total(&self) -> usize

Return the total number of bytes across all stage name strings.

Useful for estimating the overhead of storing pipeline metadata. Returns 0 for an empty pipeline.

pub fn stage_count_above_name_bytes(&self, min_bytes: usize) -> usize

Return the number of stages whose name byte length exceeds min_bytes.

Useful for identifying long stage names that may indicate over-verbose naming conventions. Returns 0 for an empty pipeline.

pub fn stage_at_index(&self, index: usize) -> Option<&Stage>

Return a reference to the stage at 0-based index, or None if out of range.

pub fn stage_position_from_end(&self, name: &str) -> Option<usize>

Return the position of the stage named name counted from the end of the pipeline (0 = last stage, 1 = second-to-last, …).

Returns None if no stage with that name exists.

pub fn contains_all_stages(&self, names: &[&str]) -> bool

Return true if every name in names corresponds to an existing stage.

Returns true for an empty names slice (vacuously true).

pub fn stage_name_from_end(&self, n: usize) -> Option<&str>

Return the stage name at position n from the end of the pipeline (0-indexed, so 0 is the last stage).

Returns None when n is out of bounds or the pipeline is empty.

pub fn all_stage_names(&self) -> Vec<String>

Return all stage names as an owned Vec<String>.

Unlike unique_stage_names this preserves order and includes duplicates.

pub fn has_exactly_n_stages(&self, n: usize) -> bool

Return true if the pipeline contains exactly n stages.

pub fn stage_index_of(&self, name: &str) -> Option<usize>

Return the 0-based index of the first stage whose name matches name, or None if no such stage exists.

pub fn has_no_stages(&self) -> bool

Return true if the pipeline has no stages.

Equivalent to stage_count() == 0.

pub fn longest_stage_name_len(&self) -> usize

Return the byte length of the longest stage name in the pipeline.

Returns 0 for an empty pipeline.

pub fn stage_names_joined(&self, sep: &str) -> String

Join all stage names with sep and return the resulting string.

Returns an empty string for an empty pipeline.

pub fn stage_count_with_name_containing(&self, substr: &str) -> usize

Return the count of stages whose name contains substr.

Returns 0 for an empty pipeline or when no stage name matches.

pub fn has_stage_at_index(&self, idx: usize) -> bool

Return true if a stage exists at zero-based index idx.

pub fn all_stage_names_start_with(&self, prefix: &str) -> bool

Return true if all stage names start with prefix.

Returns true for an empty pipeline (vacuously true) and for an empty prefix string (all strings start with “”).

pub fn any_stage_has_name(&self, name: &str) -> bool

Return true if any stage in the pipeline has exactly the given name.

Unlike Pipeline::has_stage_with_name_containing this checks for an exact match, and unlike Pipeline::contains_all_stages it accepts a single name without requiring slice syntax.

pub fn stage_name_at(&self, idx: usize) -> Option<&str>

Return the name of the stage at idx, or None if the index is out of bounds.

Convenience wrapper around stage_at_index that returns Option<&str> directly instead of Option<&Stage>, avoiding the need to project through the Stage struct at the call site.

pub fn all_stage_names_contain(&self, substr: &str) -> bool

Return true if every stage name contains substr as a substring.

Returns true vacuously for an empty pipeline (no stages to violate the condition).

Trait Implementations

impl Debug for Pipeline

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Pipeline

fn default() -> Self

Returns the “default value” for a type.