Relevance Filter

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

`DMRelevanceFilter(dm_invoker, threshold=DEFAULT_THRESHOLD, relevance_question=None, context_config=None, batch_size=_DEFAULT_BATCH_SIZE, max_concurrency=_DEFAULT_MAX_CONCURRENCY)`

Bases: BaseRelevanceFilter, DMComponent

[BETA] Relevance filter that uses a decision model to determine chunk relevance.

Text chunks are evaluated in batches with one binary (noul) relevance question per chunk. Chunks whose positive probability meets the configured threshold are retained, in their original order. The decision-model invoker contracts are in beta, so this filter is intended for local prototyping.

Examples:

Using the from_config class method

Build the decision-model invoker from a provider-qualified model ID.

relevance_filter = DMRelevanceFilter.from_config(model_id="openrouter/typesafe/jev-1.13", threshold=0.6)
relevant_chunks = await relevance_filter.filter(chunks=chunks, query=query)

Using the class constructor

Useful when supplying a preconfigured decision-model invoker.

dm_invoker = build_dm_invoker(model_id="openrouter/typesafe/jev-1.13")
relevance_filter = DMRelevanceFilter(dm_invoker=dm_invoker)
relevant_chunks = await relevance_filter.filter(chunks=chunks, query=query)

Attributes:

Name	Type	Description
`dm_invoker`	`BaseDMInvoker`	The decision model invoker used to evaluate chunks.
`threshold`	`float`	Minimum positive relevance probability required to retain a chunk (0 to 1).
`relevance_question`	`DMQuestion`	Binary relevance definition used to assess each chunk. Its instructions and criteria are used to construct one named `noul` question per chunk; chunk targeting is added internally.
`batch_size`	`int`	Number of chunks evaluated in each decision-model call.
`max_concurrency`	`int`	Maximum number of simultaneous decision-model calls.
`context_config`	`ContextConfig \| None`	Configuration for rendering chunk context before evaluation.

Initialize the DMRelevanceFilter.

Parameters:

Name	Type	Description	Default
`dm_invoker`	`BaseDMInvoker`	The decision model invoker used to evaluate each chunk.	required
`threshold`	`float`	Minimum positive probability required to retain a chunk (0 to 1). Defaults to DEFAULT_THRESHOLD.	`DEFAULT_THRESHOLD`
`relevance_question`	`DMQuestion \| None`	A `noul` relevance definition for each chunk. Its instructions and criteria are used to construct one named question per chunk. Defaults to a built-in question that checks whether the chunk helps answer the query.	`None`
`context_config`	`ContextConfig \| None`	Configuration for rendering chunk context. If it renders an empty string for a chunk, the raw chunk content is used. Defaults to None.	`None`
`batch_size`	`int`	Number of chunks to evaluate in each decision-model call. Defaults to _DEFAULT_BATCH_SIZE.	`_DEFAULT_BATCH_SIZE`
`max_concurrency`	`int`	Maximum number of simultaneous decision-model calls. Defaults to _DEFAULT_MAX_CONCURRENCY.	`_DEFAULT_MAX_CONCURRENCY`

Raises:

Type	Description
`GenerationValueError`

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

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}
`context_config`	`ContextConfig \| None`	Configuration for rendering context text from chunks.

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`	Deprecated. List of metadata fields to include. Will be removed in v0.7. Use `context_config` instead. Defaults to None.	`None`
`chunk_format`	`str \| Callable[[Chunk], str] \| None`	Deprecated. Either a format string or a callable for custom chunk formatting. Will be removed in v0.7. Use `context_config` instead. Defaults to None, in which case `DEFAULT_CHUNK_TEMPLATE` will be used.	`None`
`context_config`	`ContextConfig \| None`	Configuration for rendering context text from chunks. Takes precedence over `chunk_format` and `metadata` when provided. Defaults to None.	`None`

`LMRelevanceFilter(lm_invoker, batch_size=_DEFAULT_BATCH_SIZE, on_failure_keep_all=True, metadata=None, chunk_format=None, fallback_lms=None, context_config=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}
`context_config`	`ContextConfig \| None`	Configuration for rendering context text from chunks.

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`	Deprecated. List of metadata fields to include. Will be removed in v0.7. Use `context_config` instead. Defaults to None.	`None`
`chunk_format`	`str \| Callable[[Chunk], str] \| None`	Deprecated. Either a format string or a callable for custom chunk formatting. Will be removed in v0.7. Use `context_config` instead. Defaults to None, in which case `_DEFAULT_CHUNK_TEMPLATE` will be used.	`None`
`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`
`context_config`	`ContextConfig \| None`	Configuration for rendering context text from chunks. Takes precedence over `chunk_format` and `metadata` when provided. 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=DEFAULT_THRESHOLD, context_config=None)`

Bases: SimilarityRelevanceFilter

Deprecated compatibility 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.
`context_config`	`ContextConfig \| None`	Configuration for rendering context text from chunks.

Initialize the deprecated filter name with the legacy constructor API.

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 DEFAULT_THRESHOLD.	`DEFAULT_THRESHOLD`
`context_config`	`ContextConfig \| None`	Configuration for rendering context text from chunks. If context_config renders an empty string for a chunk, it falls back to raw chunk content to ensure non-empty text input for the embedding model. Defaults to None.	`None`

`SimilarityRelevanceFilter(em_invoker, threshold=DEFAULT_THRESHOLD, context_config=None)`

Bases: BaseRelevanceFilter, EMComponent

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.
`context_config`	`ContextConfig \| None`	Configuration for rendering context text from chunks.

Initialize the SimilarityRelevanceFilter.

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.	`DEFAULT_THRESHOLD`
`context_config`	`ContextConfig \| None`	Configuration for rendering context text from chunks. If context_config renders an empty string for a chunk, it falls back to raw chunk content to ensure non-empty text input for the embedding model. Defaults to None.	`None`

Relevance Filter

DMRelevanceFilter(dm_invoker, threshold=DEFAULT_THRESHOLD, relevance_question=None, context_config=None, batch_size=_DEFAULT_BATCH_SIZE, max_concurrency=_DEFAULT_MAX_CONCURRENCY)

Using the from_config class method

Using the class constructor

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

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

Using the from_preset class method

Using the from_config class method

Using the class constructor

from_preset(model_id, **kwargs) classmethod

SimilarityBasedRelevanceFilter(em_invoker, threshold=DEFAULT_THRESHOLD, context_config=None)

SimilarityRelevanceFilter(em_invoker, threshold=DEFAULT_THRESHOLD, context_config=None)

`DMRelevanceFilter(dm_invoker, threshold=DEFAULT_THRESHOLD, relevance_question=None, context_config=None, batch_size=_DEFAULT_BATCH_SIZE, max_concurrency=_DEFAULT_MAX_CONCURRENCY)`

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

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

`from_preset(model_id, **kwargs)` `classmethod`

`SimilarityBasedRelevanceFilter(em_invoker, threshold=DEFAULT_THRESHOLD, context_config=None)`

`SimilarityRelevanceFilter(em_invoker, threshold=DEFAULT_THRESHOLD, context_config=None)`