feat: add FERPAMetadataFilter component for FERPA-compliant RAG pipelines

[ashutoshrana]

Summary

This PR adds FERPAMetadataFilter, a Haystack component that enforces FERPA (Family Educational Rights and Privacy Act, 34 CFR § 99) identity-scope filtering on retrieved documents before they reach the LLM context window.

Higher-education institutions using Haystack for RAG applications face a structural FERPA compliance gap: vector store retrievers return results for all students in response to any query. This component closes that gap with a clean two-layer enforcement mechanism applied at the Haystack pipeline level.

What it does

Layer 1 — Identity pre-filter: Documents whose student_id or institution_id metadata fields do not match the authorized scope are removed. Documents with no identity metadata (shared content like course catalogues or policy handbooks) pass through unchanged.

Layer 2 — Category authorization: Documents tagged with a category field are checked against the configured authorized_categories list (e.g., ["academic_record", "financial_aid"]). Unauthorized categories (e.g., disciplinary) are blocked even if the identity matches.

Both layers are configurable via field name parameters so institutions using different metadata naming conventions can adopt this without data migration.

Regulatory basis

• 34 CFR § 99.31(a)(1) — access to educational records (legitimate educational interest)
• 34 CFR § 99.32 — record of disclosures (audit requirement)

The component emits a structured FERPADisclosureRecord on every invocation for downstream compliance logging.

Usage

from haystack import Pipeline
from haystack.components.retrievers import InMemoryEmbeddingRetriever
from haystack.components.retrievers.ferpa_metadata_filter import FERPAMetadataFilter
from haystack.document_stores.in_memory import InMemoryDocumentStore

ferpa_filter = FERPAMetadataFilter(
    student_id="stu_001",
    institution_id="inst_abc",
    authorized_categories=["academic_record", "financial_aid"],
    requesting_user_id="advisor_007",
)

pipeline = Pipeline()
pipeline.add_component("retriever", InMemoryEmbeddingRetriever(doc_store))
pipeline.add_component("ferpa_filter", ferpa_filter)
pipeline.connect("retriever.documents", "ferpa_filter.documents")

result = pipeline.run({"retriever": {"query_embedding": query_emb}})
# result["ferpa_filter"]["documents"] — only stu_001's authorized records
# result["ferpa_filter"]["disclosure_record"] — 34 CFR § 99.32 audit entry

Changes

• haystack/components/retrievers/ferpa_metadata_filter.py — new component (329 lines, 25 tests)
• haystack/components/retrievers/__init__.py — exports FERPAMetadataFilter and FERPADisclosureRecord
• test/components/retrievers/test_ferpa_metadata_filter.py — 25 unit tests covering identity filter, category auth, mixed batches, serialization, custom field names, raise_on_violation mode, and run_async

Checklist

• Unit tests added (25 tests, all passing)
• to_dict() / from_dict() serialization with round-trip test
• run_async() variant for async pipelines
• No new external dependencies (uses only haystack core)
• Follows existing @component decorator pattern
• Exports added to __init__.py via LazyImporter pattern

[vercel]

Someone is attempting to deploy a commit to the deepset Team on Vercel.

A member of the Team first needs to authorize it.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

---

Ashutosh Rana seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[davidsbatista]

Thanks for the contribution, but this out of scope and too specific in any case.

[julian-risch]

@ashutoshrana You could publish and release this custom component yourself using our template repository if you believe it benefits a larger group of users: https://github.com/deepset-ai/custom-component