Agentic retrieval pipeline

Bounded agentic retrieval pipeline block.

AgenticRetrievalPipeline(retriever, selector, evaluator, max_rounds=2, top_k=10, max_top_k=None, selected_chunk_limit=5, on_insufficient=OnInsufficientPolicy.BEST_EFFORT)

Bounded agentic retrieval pipeline block.

The pipeline follows the pattern: normalize_state -> while_do(retrieve -> select -> evaluate -> prepare_retry) -> finalize.

When on_insufficient is OnInsufficientPolicy.EMPTY, exhausted loops with no sufficient evidence return an empty chunk list. When OnInsufficientPolicy.BEST_EFFORT, the last selected chunks are kept. When max_top_k is set, top_k growth per retry is capped at that value.

Attributes:

Name	Type	Description
retriever	BaseRetriever	Retriever used in each retrieval round.
selector	SelectorStage	Selector stage for chunk selection.
evaluator	EvaluatorStage	Evaluator stage for sufficiency checks.
max_rounds	int	Maximum retrieval rounds.
top_k	int	Initial retrieval candidate size.
max_top_k	int | None	Optional upper bound for retry growth of top_k.
selected_chunk_limit	int	Maximum selected chunk count per round.
on_insufficient	OnInsufficientPolicy	Terminal behavior when evidence is insufficient after loop exhaustion.

Initialize the bounded retrieval block configuration.

Parameters:

Name	Type	Description	Default
retriever	BaseRetriever	Retriever used for each loop round.	required
selector	SelectorStage	Selector stage used to choose final chunks from candidates.	required
evaluator	EvaluatorStage	Evaluator stage used to determine evidence sufficiency.	required
max_rounds	int	Maximum retrieval rounds.	2
top_k	int	Initial retrieval candidate size.	10
max_top_k	int | None	Optional upper bound for top_k during retries.	None
selected_chunk_limit	int	Maximum selected chunk count per round.	5
on_insufficient	OnInsufficientPolicy | str	Terminal behavior when evidence remains insufficient.	BEST_EFFORT

Raises:

Type	Description
ValueError	If numeric limits or policy value are invalid.
TypeError	If selector or evaluator stage types are unsupported.

build()

Materialize a bounded retrieval loop as a pipeline.

Returns:

Name	Type	Description
Pipeline	Pipeline	Materialized pipeline implementing bounded retrieve-select-evaluate behavior.

OnInsufficientPolicy

Bases: StrEnum

Terminal behavior when loop completes with insufficient evidence.

Attributes:

Name	Type	Description
BEST_EFFORT	str	Keep selected chunks from final iteration.
EMPTY	str	Return empty chunk list on insufficiency.