Implementation:Run llama Llama index BaseNodePostprocessor

Knowledge Sources	Run_llama_Llama_index
Domains	Postprocessing, AbstractBaseClass, Architecture
Last Updated	2026-02-11 19:00 GMT

Overview

BaseNodePostprocessor is the abstract base class that defines the interface for all node postprocessors in LlamaIndex, providing synchronous and asynchronous methods for transforming retrieved nodes after retrieval.

Description

BaseNodePostprocessor extends BaseComponent, DispatcherSpanMixin, and Python's ABC to form the foundation of the postprocessor hierarchy. It defines a consistent contract that all concrete postprocessors must implement:

• _postprocess_nodes (abstract) - The core method that subclasses must implement. Receives a list of NodeWithScore objects and an optional QueryBundle, and returns a transformed list of NodeWithScore objects.
• postprocess_nodes - The public synchronous entry point. Accepts either a query_bundle or a query_str parameter (but not both), converts query_str to a QueryBundle if provided, and delegates to _postprocess_nodes.
• apostprocess_nodes - The public asynchronous entry point with the same parameter handling logic as the synchronous version, delegating to _apostprocess_nodes.
• _apostprocess_nodes - Default async implementation that wraps the synchronous _postprocess_nodes in asyncio.to_thread for thread-based concurrency. Subclasses can override this for native async implementations.

The class includes default no-op implementations of prompt management methods (_get_prompts, _update_prompts, _get_prompt_modules) so that subclasses without prompts do not need to implement them.

Configuration uses ConfigDict(arbitrary_types_allowed=True) and includes a CallbackManager field excluded from serialization.

Usage

Use BaseNodePostprocessor as the parent class when implementing custom node postprocessors. It ensures that your postprocessor integrates seamlessly with LlamaIndex query engines, callback systems, and instrumentation infrastructure. All built-in postprocessors (rerankers, PII maskers, optimizers, etc.) extend this class.

Code Reference

Source Location

• Repository: Run_llama_Llama_index
• File: llama-index-core/llama_index/core/postprocessor/types.py

Signature

class BaseNodePostprocessor(BaseComponent, DispatcherSpanMixin, ABC):
    model_config = ConfigDict(arbitrary_types_allowed=True)
    callback_manager: CallbackManager = Field(
        default_factory=CallbackManager, exclude=True
    )

    @abstractmethod
    def _postprocess_nodes(
        self,
        nodes: List[NodeWithScore],
        query_bundle: Optional[QueryBundle] = None,
    ) -> List[NodeWithScore]:
        ...

Import

from llama_index.core.postprocessor.types import BaseNodePostprocessor

I/O Contract

Inputs (postprocess_nodes)

Name	Type	Required	Description
nodes	List[NodeWithScore]	Yes	List of retrieved nodes with their scores to be postprocessed.
query_bundle	Optional[QueryBundle]	No	The query bundle containing the query string and optional embeddings.
query_str	Optional[str]	No	Alternative to query_bundle; a plain query string that will be converted to a QueryBundle.

Outputs

Name	Type	Description
nodes	List[NodeWithScore]	Transformed list of nodes after postprocessing.

Usage Examples

from llama_index.core.postprocessor.types import BaseNodePostprocessor
from llama_index.core.schema import NodeWithScore, QueryBundle
from typing import List, Optional


class MyCustomPostprocessor(BaseNodePostprocessor):
    """Example custom postprocessor that filters nodes by minimum score."""

    min_score: float = 0.5

    @classmethod
    def class_name(cls) -> str:
        return "MyCustomPostprocessor"

    def _postprocess_nodes(
        self,
        nodes: List[NodeWithScore],
        query_bundle: Optional[QueryBundle] = None,
    ) -> List[NodeWithScore]:
        return [n for n in nodes if n.score and n.score >= self.min_score]


# Usage
postprocessor = MyCustomPostprocessor(min_score=0.7)
filtered_nodes = postprocessor.postprocess_nodes(nodes, query_str="my query")

Related Pages

• Environment:Run_llama_Llama_index_Python_LlamaIndex_Core
• Run_llama_Llama_index_PromptMixin - Prompt management mixin inherited via BaseComponent
• Run_llama_Llama_index_SentenceEmbeddingOptimizer - Concrete subclass
• Run_llama_Llama_index_PII_Postprocessors - Concrete subclasses for PII masking
• Run_llama_Llama_index_RankGPTRerank - Concrete subclass for RankGPT reranking
• Run_llama_Llama_index_SentenceTransformerRerank - Concrete subclass for CrossEncoder reranking
• Run_llama_Llama_index_StructuredLLMRerank - Concrete subclass for structured LLM reranking