Frequently asked questions#

What is wardowl?#

wardowl is an open-source Python library (MIT) for permission-aware retrieval in RAG. It sits between your application and your vector store. For each question it asks your permission system what the user may read, applies that as a filter inside the store’s search, and checks every hit again before anything reaches the LLM prompt. Each user gets only the chunks they are allowed to read.

How do I stop a RAG chatbot from showing users documents they are not allowed to see?#

Enforce permissions at retrieval, before the LLM sees any text. Telling the model in a prompt to withhold documents does not work, because whatever reaches the prompt can come out in the answer. With wardowl, you pass the authenticated user to PermissionedRetriever.retrieve. It returns only chunks that user may read, and on any error from the permission system it returns nothing rather than everything. The quickstart shows the whole setup in a few lines.

What is permission-aware retrieval?#

Retrieval that takes the asking user into account. The search returns the best matches among the documents that user may read, not among all documents. The difference matters most when the user may read only a small part of the corpus: filtering after the search can leave few results, or none. Concepts explains pre-filtering, post-filtering and the re-check.

Which vector stores does wardowl support?#

pgvector, Qdrant, Milvus, MongoDB Atlas Vector Search, Weaviate, Redis, LanceDB, Elasticsearch, OpenSearch, Vespa, Apache Cassandra, Pinecone, Chroma and FAISS, plus any LangChain or LlamaIndex vector store through post-filtering. Every built-in backend passes the same conformance tests against the real store in CI. See Integrations.

Which permission systems does it work with?#

OpenFGA, SpiceDB, Ory Keto, Cerbos, Open Policy Agent, Cedar and Casbin, access lists stored in chunk metadata, tenant isolation, and your own Python rules. Authorizers can be combined with AllOf and AnyOf, and cached with a stated revocation bound. Permissions can also be copied from Google Drive onto the chunks.

Does it work with LangChain, LlamaIndex, Haystack and MCP?#

Yes. wardowl provides a LangChain retriever, a LlamaIndex retriever, a Haystack component and an MCP search tool. Each one takes the user from your application, never from the model, so an agent cannot search as someone else.

Why not just add a metadata filter to the vector store query myself?#

You can, and for one store with simple rules that may be enough. wardowl adds what is easy to get wrong:

  • one filter language, translated and tested for each store, keeping 1 and "1" apart;

  • an unsatisfiable filter that returns no results, never “no filter”;

  • a second check of every hit, so a store that ignores the filter cannot leak;

  • failing closed on errors, timeouts and malformed answers;

  • caching with a revocation bound, audit events and OpenTelemetry spans.

What happens if the permission service is down?#

Retrieval raises an error and returns nothing. wardowl never falls back to unfiltered results. A circuit breaker can make it fail fast while the service recovers. See Operations.

How fast is it?#

On pgvector with a million chunks, pre-filtered retrieval reached 129 retrievals a second on four CPUs, with recall@10 between 0.88 and 0.97. Across 21,000 benchmark retrievals, no forbidden chunk was returned. Benchmarks has the method and the scripts to reproduce it.

Is wardowl ready for production?#

It follows semantic versioning, so the public API does not break within a major version. CI tests it on Python 3.11 to 3.14 and runs the suite for every store and permission service against a real server. Releases carry Sigstore signatures, an SBOM and provenance. No independent security audit has been carried out yet. The review page lists the project’s own findings and how to check its work. Production is the checklist for a deployment.

Is it free?#

Yes. wardowl is MIT licensed, and the core has no runtime dependencies. The integrations are optional extras, such as pip install "wardowl[pgvector]".

I use needtoknow. How do I move to wardowl?#

needtoknow was the project’s name until version 2.0.0. Upgrading lists every change and what to do about it.

Where does the name come from?#

A ward is a guard, and an owl is the night’s watchful eye: wardowl watches every retrieval so each user sees only what they need to know.