Relevance Filter

Modules used to filter chunks based on its relevance to a given query.

LMBasedRelevanceFilter(lm_request_processor, batch_size=DEFAULT_BATCH_SIZE, on_failure_keep_all=True, metadata=None, chunk_format=DEFAULT_CHUNK_TEMPLATE)

Bases: BaseRelevanceFilter, UsesLM

Relevance filter that uses an LM to determine chunk relevance.

This filter processes chunks in batches, sending them to an LM for relevance determination. It handles potential LM processing failures with a simple strategy controlled by the 'on_failure_keep_all' parameter.

The LM is expected to return a specific output format for each chunk, indicating its relevance to the given query.

The expected LM output format is:

    {
        "results": [
            {
                "explanation": str,
                "is_relevant": bool
            },
            ...
        ]
    }

The number of items in "results" should match the number of input chunks.

Attributes:

Name	Type	Description
lm_request_processor	LMRequestProcessor	The LM request processor used for LM calls.
batch_size	int	The number of chunks to process in each LM call.
on_failure_keep_all	bool	If True, keep all chunks when LM processing fails. If False, discard all chunks from the failed batch.
metadata	list[str] | None	List of metadata fields to include. If None, no metadata is included.
chunk_format	str | Callable[[Chunk], str]	Either a format string or a callable for custom chunk formatting. If using a format string: - Use {content} for chunk content - Use {metadata} for auto-formatted metadata block - Or reference metadata fields directly: {field_name}

Initialize the LMBasedRelevanceFilter.

Parameters:

Name	Type	Description	Default
lm_request_processor	LMRequestProcessor	The LM request processor to use for LM calls.	required
batch_size	int	The number of chunks to process in each LM call. Defaults to DEFAULT_BATCH_SIZE.	DEFAULT_BATCH_SIZE
on_failure_keep_all	bool	If True, keep all chunks when LM processing fails. If False, discard all chunks from the failed batch. Defaults to True.	True
metadata	list[str] | None	List of metadata fields to include. If None, no metadata is included.	None
chunk_format	str | Callable[[Chunk], str]	Either a format string or a callable for custom chunk formatting. If using a format string: - Use {content} for chunk content - Use {metadata} for auto-formatted metadata block - Or reference metadata fields directly: {field_name} Defaults to DEFAULT_CHUNK_TEMPLATE.	DEFAULT_CHUNK_TEMPLATE

LMRelevanceFilter(lm_invoker, batch_size=_DEFAULT_BATCH_SIZE, on_failure_keep_all=True, metadata=None, chunk_format=_DEFAULT_CHUNK_TEMPLATE, fallback_lms=None)

Bases: BaseRelevanceFilter, LMComponent

Relevance filter that uses an LM to determine chunk relevance.

This filter processes chunks in batches, sending them to an LM for relevance determination. It handles potential LM processing failures with a simple strategy controlled by the 'on_failure_keep_all' parameter.

Examples:

Using the from_preset class method

The most straightforward method. Uses the built-in prompt templates and response schema.

relevance_filter = LMRelevanceFilter.from_preset("openai/gpt-5.4-nano")
relevant = await relevance_filter.filter(chunks=chunks, query=query)

Using the from_config class method

Useful for customizing several configurations, such as prompt templates and response schema.

relevance_filter = LMRelevanceFilter.from_config(
    model_id="openai/gpt-5-nano",
    system_template=SYSTEM_TEMPLATE,
    config={"response_schema": RelevanceFilter},
)

Using the class constructor

Useful for passing a pre-defined LM invoker.

relevance_filter = LMRelevanceFilter(lm_invoker=lm_invoker)
relevant = await relevance_filter.filter(chunks=chunks, query=query)

Attributes:

Name	Type	Description
lm_invoker	BaseLMInvoker	The language model invoker used for LM calls.
batch_size	int	The number of chunks to process in each LM call.
on_failure_keep_all	bool	If True, keep all chunks when LM processing fails. If False, discard all chunks from the failed batch.
metadata	list[str]	List of metadata fields to include.
chunk_format	str | Callable[[Chunk], str]	Either a format string or a callable for custom chunk formatting. If using a format string: - Use {content} for chunk content - Use {metadata} for auto-formatted metadata block - Or reference metadata fields directly: {field_name}

Initialize the LMRelevanceFilter.

Parameters:

Name	Type	Description	Default
lm_invoker	BaseLMInvoker	The language model invoker to use for LM calls.	required
batch_size	int	The number of chunks to process in each LM call. Defaults to _DEFAULT_BATCH_SIZE.	_DEFAULT_BATCH_SIZE
on_failure_keep_all	bool	If True, keep all chunks when LM processing fails. If False, discard all chunks from the failed batch. Defaults to True.	True
metadata	list[str] | None	List of metadata fields to include. Defaults to None, in which case no metadata is included.	None
chunk_format	str | Callable[[Chunk], str]	Either a format string or a callable for custom chunk formatting. If using a format string: - Use {content} for chunk content - Use {metadata} for auto-formatted metadata block - Or reference metadata fields directly: {field_name} Defaults to _DEFAULT_CHUNK_TEMPLATE.	_DEFAULT_CHUNK_TEMPLATE
fallback_lms	list[BaseLMInvoker] | None	A list of language model invokers to use as fallback if the main language model fails. Defaults to None.	None

from_preset(model_id, **kwargs) classmethod

Creates a relevance filter with preset prompt templates and response schema.

Parameters:

Name	Type	Description	Default
model_id	str | ModelId	The model id.	required
**kwargs	Any	Additional keyword arguments.	{}

Returns:

Name	Type	Description
Self	Self	A relevance filter with preset prompt templates and response schema.

SimilarityBasedRelevanceFilter(em_invoker, threshold=0.5)

Bases: BaseRelevanceFilter

Relevance filter that uses semantic similarity to determine chunk relevance.

Attributes:

Name	Type	Description
em_invoker	BaseEMInvoker	The embedding model invoker to use for vectorization.
threshold	float	The similarity threshold for relevance (0 to 1). Defaults to 0.5.

Initialize the SimilarityBasedRelevanceFilter.

Parameters:

Name	Type	Description	Default
em_invoker	BaseEMInvoker	The embedding model invoker to use for vectorization.	required
threshold	float	The similarity threshold for relevance (0 to 1). Defaults to 0.5.	0.5

Raises:

Type	Description
ValueError	If the threshold is not between 0 and 1.