qdrant-lens 0.1.0

A knowledge browser and audit layer for Qdrant vector databases

qdrant-lens

A knowledge browser for Qdrant vector databases.

Qdrant's own dashboard is a point browser — it shows raw vectors and payloads. qdrant-lens is the layer above that: it shows developers what the team has actually ingested, organised the way a human thinks about it.

• Knowledge tree — browse ingested content by source → document type → document → chunk, not by vector ID
• Accountability layer — every upsert and delete is intercepted, signed with the actor identity and timestamp, and written to an append-only audit log; raw Qdrant has no concept of who wrote a point or why — qdrant-lens ensures nothing in the cluster changes without a trace
• _lens schema enforcement — every point carries a validated metadata namespace; violations are surfaced before bad data reaches the index
• Sync-aware pipeline — chunk-hash dedup means re-ingesting a folder only embeds what actually changed; a scroll-diff pattern keeps Qdrant in sync with your filesystem the same way git tracks your working tree
• Structural graph layer — document relationships (same source, shared tags, same author) derived purely from payload fields, no Neo4j required
• Parser-agnostic ingest — LiteParse (default) handles PDFs, Office docs, images, and Jupyter notebooks natively; falls back to a pdfplumber/pytesseract stack automatically if needed
• Chat agent — ask questions about a collection in plain English, get answers backed by live tree/history/search tools; destructive operations require explicit typed confirmation before executing

---

Visual guides

Ingest pipeline → How a file moves from disk to Qdrant — the 7-step pipeline with the OKF branch shown at step 3.

Dashboard UI → What the browser dashboard looks like — tree, history feed, chunk inspector, and how OKF files are labelled.

---

Documentation

Guide	Description
Quickstart	Install, first run, Day 1/Day 2, env setup
Ingest Pipeline	File ingestion, parsers, chunking, dedup, hybrid search
Client Reference	QdrantLensClient API, audit log, schema, core concepts
Dashboard	lens serve, UI views, FastAPI routes
Parsers	liteparse vs auto, system deps, troubleshooting
Testing	Test suite overview, per-module test descriptions
Contributing	Project structure, module map, adding parsers/routes/fields

---

Prerequisites

Requirement	Version	Notes
Python	>= 3.12
Qdrant	>= 1.18.0	Self-hosted, Docker, or Qdrant Cloud
Docker	any	For docker compose up (optional — can run components separately)
Tesseract	any	OCR only — sudo apt install tesseract-ocr / brew install tesseract
LibreOffice	any	Office → PDF conversion (bundled in [ingest])
Neo4j	>= 5.0	Graph RAG only — docker compose --profile graph up

---

Install

# Core: client wrapper + dashboard API only
pip install qdrant-lens

# + full ingestion pipeline (PDF parsing, OCR, chunking) — includes LiteParse by default
pip install "qdrant-lens[ingest]"

# + FastEmbed for CLI embeddings and sparse vectors (bm25_enable=True)
pip install "qdrant-lens[embed]"

# Everything
pip install "qdrant-lens[all]"

See docs/quickstart.md for uv, Docker, and .env setup.

---

Quickstart

Day 1 — 5 minutes, zero code changes

pip install qdrant-lens
lens serve --url http://localhost:6333
# Dashboard opens at http://localhost:7367
# Tree renders from your existing collection immediately

Day 2 — two line changes, audit log starts

from qdrant_lens import QdrantLensClient

# Drop-in replacement for QdrantClient — all existing calls unchanged
client = QdrantLensClient(url="http://localhost:6333", api_key="...")

# All upsert/delete calls now validate _lens metadata and write audit events
client.upsert(collection_name="docs", points=[...])

# New lens-only methods
doc_id = client.make_doc_id("github", "repo/auth/login.py")
tree   = client.tree("docs")
events = client.history("docs", last_n=20)
violations = client.validate("docs")

Async

from qdrant_lens import AsyncQdrantLensClient

client = AsyncQdrantLensClient(url="...", api_key="...")
tree = await client.tree("docs")

---

See docs/client.md for the full API reference and docs/ingest.md for the ingest pipeline.

---

Compatibility

• qdrant-client >= 1.18.0 required. Earlier versions are not supported.
• Python >= 3.12 (3.10 and 3.11 may work but are untested).

See COMPATIBILITY.md for the full version matrix and system dependency notes.

---

Built with

qdrant-lens stands on the shoulders of several excellent open-source projects:

Project	Role
Chonkie	Chunking backbone — token-aware RecursiveChunker, SemanticChunker, and CodeChunker strategies
PdfItDown	Office and image → PDF conversion in the auto parser stack (.docx, .pptx, .xlsx, .png, .jpg)
LiteParse	Default parser — single-library extraction for PDFs, Office docs, images, and more without a LibreOffice dependency