llamaIndex - 💡(How to fix) Fix [Feature Request]: Metadata-aware section routing for heterogeneous financial documents in VectorStoreIndex

Feature Description

Background

In Issue #21318, @logan-markewich correctly pointed out that "semantic bleed" at section boundaries in financial documents (10-Ks, earnings calls) is not a bug — it's an expected retrieval behavior. The recommendation was to use metadata filtering with a predefined schema. This feature request formalizes what that metadata schema should look like for heterogeneous financial documents.

The Problem

Financial documents have a well-defined hierarchical structure, but LlamaIndex has no built-in conventions for:

1. Section-type metadata — distinguishing MD&A, Risk Factors, Balance Sheet, Income Statement, Footnotes, etc.
2. Document-part routing — routing queries to the correct index/namespace based on query intent
3. Cross-section reference handling — footnotes that reference other sections

Without conventions, every team building on LlamaIndex for financial docs reinvents a custom metadata schema, often inconsistently.

Proposed Feature

A FinancialDocumentMetadataExtractor (or more generically, a HierarchicalDocumentMetadataExtractor) that:

1. Annotates chunks with structured metadata:

{
  "doc_type": "10-K",  # 10-K | 10-Q | earnings_call | proxy
  "section": "MD&A",  # Risk Factors | MD&A | Balance Sheet | etc.
  "section_level": 1,  # hierarchy depth
  "fiscal_year": "2024",
  "company_ticker": "AAPL",
  "chunk_role": "body"  # header | body | table | footnote
}

1. Enables LLM-inferred filter routing:

index = VectorStoreIndex.from_documents(
    docs,
    metadata_extractor=FinancialDocMetadataExtractor()
)

retriever = index.as_retriever(
    auto_filter_schema=FinancialDocFilterSchema  # LLM infers filters from query
)

1. Optionally creates section-specific sub-indexes for highest-precision retrieval.

Why This Matters

For financial RAG (SEC filings, earnings calls), metadata-aware routing is the difference between production-quality QA and retrieval that surfaces neighboring sections. The pattern is domain-specific enough to justify a first-class integration.

I've implemented a prototype of this approach in my finrag-eval project. Happy to contribute a reference implementation or cookbook example if the team is interested.

Reason

Current workarounds require manually defining metadata schemas, creating multiple indexes per document section, and writing custom filter inference logic. There are no built-in LlamaIndex conventions for financial document taxonomy, so every team using LlamaIndex for SEC filings or earnings calls builds this from scratch. The lack of a standard schema means these implementations are incompatible and hard to share or benchmark.

Value of Feature

Financial document RAG is a high-value use case for LlamaIndex (asset managers, research teams, compliance tools). A standardized FinancialDocumentMetadataExtractor would:

• Reduce the time-to-production for financial RAG pipelines
• Enable reproducible benchmarking across teams
• Provide a reusable cookbook pattern for the LlamaIndex community
• Directly address the root cause of the semantic bleed issue reported in #21318