retrieval-acl-filter-py 0.1.0

Enforce document ACLs after retrieval and before prompting. Python port of @mukundakatta/retrieval-acl-filter.

retrieval-acl-filter-py

Enforce document ACLs after retrieval and before prompting. Your vector store doesn't know who's asking. Pipe its results through this filter to drop any chunk the current user shouldn't see, before those chunks land in the prompt. Zero runtime dependencies.

Python port of @mukundakatta/retrieval-acl-filter.

Install

pip install retrieval-acl-filter-py

Usage

from retrieval_acl_filter import filter_by_acl, explain_acl_drop

docs = [
    {"id": "public",  "text": "...", "acl": {"public": True}},
    {"id": "team",    "text": "...", "acl": {"groups": ["eng"]}},
    {"id": "personal","text": "...", "acl": {"users":  ["alice"]}},
    {"id": "secret",  "text": "...", "acl": {"groups": ["execs"]}},
    {"id": "no_acl",  "text": "..."},  # missing ACL -> open by default
]

user = {"id": "alice", "groups": ["eng"]}

allowed = filter_by_acl(docs, user)
[d["id"] for d in allowed]   # ["public", "team", "personal", "no_acl"]

# Audit which docs got dropped and why:
report = explain_acl_drop(docs, user)
report[3]   # {"id": "secret", "allowed": False, "reason": "missing_acl_match"}

Custom ACL field name

Some retrievers stamp the ACL field as permissions or similar. Use acl_field=:

filter_by_acl(docs, user, acl_field="permissions")

API

Symbol	Behavior
filter_by_acl(docs, user, *, acl_field='acl')	Returns the subset of docs user may see.
explain_acl_drop(docs, user, *, acl_field='acl')	Per-doc verdict list with id, allowed, reason.

Match semantics (matches the JS sibling)

A document is allowed if any of these is true:

1. doc.acl.users includes user.id.
2. doc.acl.groups shares any value with user.groups.
3. doc.acl.public is True.
4. The doc has no ACL at all (acl is missing or empty) -- open-by-default.

Otherwise the document is dropped with reason="missing_acl_match".

Heads-up: the open-by-default rule is intentional for back-compat with the JS sibling, but if you're enforcing real ACLs you probably want to flip it. Tag every chunk with an explicit ACL at retrieval time and the open-default never fires.

See the JS sibling's README for the full design notes.