1  """Protocol for filter builders."""
 2  from __future__ import annotations
 3  
 4  from typing import Any, Protocol
 5  
 6  
 7  class FilterBuilder(Protocol):
 8      """Protocol for building access control filters for vector stores.
 9  
10      Each vector store implementation should provide its own filter builder
11      that converts access control parameters into the appropriate filter format.
12  
13      The system uses tag-based filtering exclusively. Roles are automatically
14      converted to tags using role_mapping for a simpler, more consistent model.
15      """
16  
17      def build(
18          self,
19          user_role: str | None = None,
20          role_mapping: dict[str, list[str]] | None = None,
21      ) -> Any | None:
22          """Build a metadata filter for tag-based access control.
23  
24          Roles are automatically expanded to tags using role_mapping.
25          Only filters by access_tags for consistency.
26  
27          Parameters
28          ----------
29          user_role : str, optional
30              User's primary role (will be expanded to tags via role_mapping).
31          role_mapping : dict[str, list[str]], optional
32              Mapping of roles to authorized tags.
33          """
34          ...
35