Tactic: Enhance Search using Surrounding Context

[mikewaters]

SentenceWindow splitter and vector post-processing to include surrounding sentences

[mikewaters]

• LlamaIndex - Metadata Replacement + Node Sentence Window v0.10.10 - seems deprecated
• [LlamaIndex - Node Postprocessor Modules Python Documentation](https://developers.llamaindex.ai/python/framework/module_guides/querying/node_postprocessors/node_postprocessors/)
• [Discussion #9848 - How to use Metadata Replacement + Node Sentence Window (run-llama/llama_index)](How to use Metadata Replacement + Node Sentence Window, without generating an answer to query run-llama/llama_index#9848)

---

2026-02-07 (America/New_York)
Nancy — GPT-5.2 Thinking

What MetadataReplacementPostProcessor actually did

In LlamaIndex (Python), MetadataReplacementPostProcessor is a node postprocessor: it runs after retrieval and before response synthesis. Its job is simple:

• For each retrieved node, replace the node’s text/content with the value of a chosen metadata field (most commonly "window").
• If that metadata key isn’t present, leave the node text unchanged. ([LlamaIndex]1)

This is most commonly paired with SentenceWindowNodeParser, which creates sentence-level nodes and stores a surrounding context window of sentences in node metadata. The typical pattern is:

1. Index/embedding time: embed the short sentence nodes (good retrieval granularity).
2. Query time: retrieve sentence nodes, then swap the sentence text for the larger "window" right before sending context to the LLM. ([LlamaIndex]2)

Why it “looks deprecated” / why it’s not in llama_index.legacy

What’s changed is mostly packaging and import paths, not the underlying idea:

• Older tutorials and notebooks often imported it from places like llama_index.indices.postprocessor ..., which has since been reorganized. You’ll now see it documented under llama_index.core.postprocessor. ([LlamaIndex]1)
• Separately, LlamaIndex’s legacy packaging story itself changed: the llama-index-legacy package was deprecated/removed, and many older APIs were migrated away from that “legacy” track. That can make anything you used to import from older namespaces feel “deprecated,” even when the functionality is still supported elsewhere. ([LlamaIndex]3)

So the most likely explanation for your observation is:

• the class wasn’t “deprecated away,” but your old import path was (and llama_index.legacy doesn’t include it because it’s not part of the old compatibility surface).

What replaced it (the “new” abstractions)

There isn’t a single 1:1 “new class” that supersedes it—rather, LlamaIndex standardized the surrounding architecture:

1. Node postprocessor abstraction (BaseNodePostprocessor + node_postprocessors=[...])
   LlamaIndex explicitly frames “postprocessors” as a pipeline stage that transforms/filters retrieved nodes before synthesis. That’s the core abstraction MetadataReplacementPostProcessor plugs into. ([LlamaIndex]4)

2. Parser + metadata pattern for sentence windows (SentenceWindowNodeParser)
   The “replacement” strategy is now presented as a recipe: store windows in metadata at parse time, then swap content at query time. The parser is the other half of the pattern. ([LlamaIndex]5)

3. (Naming divergence in the ecosystem) MetadataReplacementNodePostProcessor
   You may also run into third-party or ecosystem docs/notebooks that refer to a MetadataReplacementNodePostProcessor name for the same idea (sentence-window swap before synthesis). For example, TruLens’ cookbook uses that name in its narrative. Treat that as “the same concept,” but verify the exact class name in the package you’re using. ([TruLens]6)

Practical “current” guidance

• If you want the canonical behavior today, follow the docs’ current recipe:

  • parse with SentenceWindowNodeParser (window stored in metadata)
  • query with node_postprocessors=[MetadataReplacementPostProcessor(target_metadata_key="window")] ([LlamaIndex]2)

• If you’re upgrading older code, search your codebase for historical imports like llama_index.indices.postprocessor and migrate them to the current module locations (the docs now show the supported path). ([LlamaIndex]1)

If you paste the exact import that fails (and your llama-index / llama-index-core versions), I can point to the precise modern import and any compatibility shim that applies.