How gelevanog/permission-aware-rag works
Clearance is a private, permission-aware company document RAG. Employees ask questions through the API; verified identity principals scope vector retrieval before ranking, and PostgreSQL row-level security independently restricts rows. Retrieved text is passed to a configured chat model, with audit records of usage. Documents enter through local folders or cloud connectors, then parsing, chunking, embedding, and ACL indexing. The README also describes admin, audit, and evaluation capabilities. Several implementation links below are dashed where the supplied excerpts do not establish the call path.
Main entry points: index.py Index writer · assistant.py RAG assistant · app.py HTTP API · search.py Permission-filtered search
Components 22
Document ingestion
- Local files
src/clearance/connectors/local.py - Drive and SharePoint
src/clearance/connectors - Document parser
src/clearance/ingest/parsing.py - Section chunker
src/clearance/ingest/chunking.py - Index writer
src/clearance/index.py
Identity and permissions
- ACL rules
src/clearance/acl.py - Token identity
src/clearance/auth/tokens.py - Group mapping
src/clearance/auth/mapping.py
Answer runtime
- Embeddings
src/clearance/embeddings.py - RAG assistant
src/clearance/assistant.py - Permission-filtered search
src/clearance/retrieval/search.py - Retrieval cache
src/clearance/retrieval/cache.py - Chat model
src/clearance/llm/base.py - PostgreSQL and pgvector
src/clearance/db/session.py
Interfaces and operations
- Audit log
src/clearance/audit.py - HTTP API
src/clearance/api/app.py - Web API client
web/src/lib/api.ts - Admin and audit UI
web/src/app/admin/page.tsx
Evaluation
- Evaluation runner
src/clearance/eval/runner.py - Evaluation UI
web/src/app/eval/page.tsx
Other components
- Employee
- Identity provider
Connections 22
- Employee → HTTP API: asks
src/clearance/api/app.py - HTTP API → RAG assistant: calls
src/clearance/api/app.py - RAG assistant → Embeddings: embeds query
src/clearance/assistant.py - RAG assistant → Permission-filtered search: searches
src/clearance/assistant.py - RAG assistant → Chat model: generates answer
src/clearance/assistant.py - RAG assistant → Retrieval cache: uses cache
src/clearance/assistant.py - RAG assistant → Audit log: records usage
src/clearance/assistant.py - Permission-filtered search → PostgreSQL and pgvector: queries securely
src/clearance/retrieval/search.py - Permission-filtered search → ACL rules: filters principals
src/clearance/retrieval/search.py - Token identity → Group mapping: maps groups
src/clearance/auth/tokens.py - Identity provider → Token identity: issues claims
- Local files → Index writer: supplies documents
src/clearance/connectors/local.py - Drive and SharePoint → Index writer: syncs documents
src/clearance/connectors/local.py - Index writer → Document parser: parses content
src/clearance/index.py - Index writer → Section chunker: chunks sections
src/clearance/index.py - Index writer → Embeddings: embeds chunks
src/clearance/index.py - Index writer → ACL rules: writes permissions
src/clearance/index.py - Index writer → PostgreSQL and pgvector: writes index
src/clearance/index.py - Web API client → HTTP API: calls endpoints
- Admin and audit UI → Web API client: uses client
- Evaluation UI → HTTP API: uses evaluation API
- Evaluation runner → RAG assistant: evaluates answers
src/clearance/eval/runner.py