visual-rag-toolkit 0.1.1__tar.gz → 0.1.2__tar.gz

{visual_rag_toolkit-0.1.1 → visual_rag_toolkit-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: visual-rag-toolkit
-Version: 0.1.1
+Version: 0.1.2
 Summary: End-to-end visual document retrieval with ColPali, featuring two-stage pooling for scalable search
 Project-URL: Homepage, https://github.com/Ara-Yeroyan/visual-rag-toolkit
 Project-URL: Documentation, https://github.com/Ara-Yeroyan/visual-rag-toolkit#readme
@@ -85,10 +85,14 @@ Description-Content-Type: text/markdown
 
 # Visual RAG Toolkit
 
-[![PyPI version](https://badge.fury.io/py/visual-rag-toolkit.svg)](https://badge.fury.io/py/visual-rag-toolkit)
-[![CI](https://github.com/Ara-Yeroyan/visual-rag-toolkit/actions/workflows/ci.yaml/badge.svg)](https://github.com/Ara-Yeroyan/visual-rag-toolkit/actions/workflows/ci.yaml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/visual-rag-toolkit)](https://pypi.org/project/visual-rag-toolkit/)
+[![Python](https://img.shields.io/pypi/pyversions/visual-rag-toolkit)](https://pypi.org/project/visual-rag-toolkit/)
+[![License](https://img.shields.io/pypi/l/visual-rag-toolkit)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/Ara-Yeroyan/visual-rag-toolkit/ci.yaml?branch=main)](https://github.com/Ara-Yeroyan/visual-rag-toolkit/actions/workflows/ci.yaml)
+
+Note:
+- The **PyPI badge** shows “not found” until the first release is published.
+- The **CI badge** requires the GitHub repo to be **public** (GitHub does not serve Actions badges for private repos).
 
 End-to-end visual document retrieval toolkit featuring **fast multi-stage retrieval** (prefetch with pooled vectors + exact MaxSim reranking).
 
@@ -112,11 +116,10 @@ This repo contains:
 pip install visual-rag-toolkit
 
 # With specific features
-pip install visual-rag-toolkit[embedding]    # ColSmol/ColPali embedding support
-pip install visual-rag-toolkit[pdf]          # PDF processing
+pip install visual-rag-toolkit[ui]           # Streamlit demo dependencies
 pip install visual-rag-toolkit[qdrant]       # Vector database
+pip install visual-rag-toolkit[embedding]    # ColSmol/ColPali embedding support
 pip install visual-rag-toolkit[cloudinary]   # Image CDN
-pip install visual-rag-toolkit[ui]           # Streamlit demo dependencies
 
 # All dependencies
 pip install visual-rag-toolkit[all]
@@ -157,6 +160,80 @@ for r in results[:3]:
     print(r["id"], r["score_final"])
 ```
 
+### End-to-end: ingest PDFs (with cropping) → index in Qdrant
+
+This is the “SDK-style” pipeline: PDF → images → optional crop → embed → store vectors + payload in Qdrant.
+
+```python
+import os
+from pathlib import Path
+
+import numpy as np
+import torch
+
+from visual_rag import VisualEmbedder
+from visual_rag.indexing import ProcessingPipeline, QdrantIndexer
+
+QDRANT_URL = os.environ["SIGIR_QDRANT_URL"]  # or QDRANT_URL
+QDRANT_KEY = os.getenv("SIGIR_QDRANT_KEY", "")  # or QDRANT_API_KEY
+
+collection = "my_visual_docs"
+
+embedder = VisualEmbedder(
+    model_name="vidore/colSmol-500M",
+    torch_dtype=torch.float16,
+    output_dtype=np.float16,
+    batch_size=8,
+)
+
+indexer = QdrantIndexer(
+    url=QDRANT_URL,
+    api_key=QDRANT_KEY,
+    collection_name=collection,
+    prefer_grpc=True,
+    vector_datatype="float16",
+)
+indexer.create_collection(force_recreate=False)
+
+pipeline = ProcessingPipeline(
+    embedder=embedder,
+    indexer=indexer,
+    embedding_strategy="all",  # store full tokens + pooled vectors in one pass
+    crop_empty=True,
+    crop_empty_percentage_to_remove=0.99,  # kept for traceability
+    crop_empty_remove_page_number=True,
+    crop_empty_preserve_border_px=1,
+    crop_empty_uniform_rowcol_std_threshold=3.0,
+)
+
+pdfs = [Path("docs/a.pdf"), Path("docs/b.pdf")]
+for pdf_path in pdfs:
+    pipeline.process_pdf(
+        pdf_path,
+        skip_existing=True,
+        upload_to_cloudinary=False,
+        upload_to_qdrant=True,
+    )
+```
+
+CLI equivalent:
+
+```bash
+export SIGIR_QDRANT_URL="https://YOUR_QDRANT"
+export SIGIR_QDRANT_KEY="YOUR_KEY"
+
+visual-rag process \
+  --reports-dir ./docs \
+  --collection my_visual_docs \
+  --model vidore/colSmol-500M \
+  --strategy all \
+  --batch-size 8 \
+  --qdrant-vector-dtype float16 \
+  --prefer-grpc \
+  --crop-empty \
+  --crop-empty-remove-page-number
+```
+
 ### Process a PDF into images (no embedding, no vector DB)
 
 ```python
@@ -209,16 +286,11 @@ visual-rag-toolkit/
 Configure via environment variables or YAML:
 
 ```bash
-# Qdrant credentials (preferred names used by the demo + scripts)
-export SIGIR_QDRANT_URL="https://your-cluster.qdrant.io"
-export SIGIR_QDRANT_KEY="your-api-key"
 
-# Backwards-compatible fallbacks (also supported)
+# Qdrant credentials (preferred names used by the demo + scripts)
 export QDRANT_URL="https://your-cluster.qdrant.io"
 export QDRANT_API_KEY="your-api-key"
 
-export VISUALRAG_MODEL="vidore/colSmol-500M"
-
 # Special token handling (default: filter them out)
 export VISUALRAG_INCLUDE_SPECIAL_TOKENS=true  # Include special tokens
 ```
@@ -269,7 +341,7 @@ python -m benchmarks.vidore_beir_qdrant.run_qdrant_beir \
 ```
 
 More commands (including multi-stage variants and cropping configs) live in:
-- `benchmarks/vidore_tatdqa_test/COMMANDS.md`
+- `examples/COMMANDS.md`
 
 ## 🔧 Development
 

{visual_rag_toolkit-0.1.1 → visual_rag_toolkit-0.1.2}/README.md

@@ -1,9 +1,13 @@
 # Visual RAG Toolkit
 
-[![PyPI version](https://badge.fury.io/py/visual-rag-toolkit.svg)](https://badge.fury.io/py/visual-rag-toolkit)
-[![CI](https://github.com/Ara-Yeroyan/visual-rag-toolkit/actions/workflows/ci.yaml/badge.svg)](https://github.com/Ara-Yeroyan/visual-rag-toolkit/actions/workflows/ci.yaml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/visual-rag-toolkit)](https://pypi.org/project/visual-rag-toolkit/)
+[![Python](https://img.shields.io/pypi/pyversions/visual-rag-toolkit)](https://pypi.org/project/visual-rag-toolkit/)
+[![License](https://img.shields.io/pypi/l/visual-rag-toolkit)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/Ara-Yeroyan/visual-rag-toolkit/ci.yaml?branch=main)](https://github.com/Ara-Yeroyan/visual-rag-toolkit/actions/workflows/ci.yaml)
+
+Note:
+- The **PyPI badge** shows “not found” until the first release is published.
+- The **CI badge** requires the GitHub repo to be **public** (GitHub does not serve Actions badges for private repos).
 
 End-to-end visual document retrieval toolkit featuring **fast multi-stage retrieval** (prefetch with pooled vectors + exact MaxSim reranking).
 
@@ -27,11 +31,10 @@ This repo contains:
 pip install visual-rag-toolkit
 
 # With specific features
-pip install visual-rag-toolkit[embedding]    # ColSmol/ColPali embedding support
-pip install visual-rag-toolkit[pdf]          # PDF processing
+pip install visual-rag-toolkit[ui]           # Streamlit demo dependencies
 pip install visual-rag-toolkit[qdrant]       # Vector database
+pip install visual-rag-toolkit[embedding]    # ColSmol/ColPali embedding support
 pip install visual-rag-toolkit[cloudinary]   # Image CDN
-pip install visual-rag-toolkit[ui]           # Streamlit demo dependencies
 
 # All dependencies
 pip install visual-rag-toolkit[all]
@@ -72,6 +75,80 @@ for r in results[:3]:
     print(r["id"], r["score_final"])
 ```
 
+### End-to-end: ingest PDFs (with cropping) → index in Qdrant
+
+This is the “SDK-style” pipeline: PDF → images → optional crop → embed → store vectors + payload in Qdrant.
+
+```python
+import os
+from pathlib import Path
+
+import numpy as np
+import torch
+
+from visual_rag import VisualEmbedder
+from visual_rag.indexing import ProcessingPipeline, QdrantIndexer
+
+QDRANT_URL = os.environ["SIGIR_QDRANT_URL"]  # or QDRANT_URL
+QDRANT_KEY = os.getenv("SIGIR_QDRANT_KEY", "")  # or QDRANT_API_KEY
+
+collection = "my_visual_docs"
+
+embedder = VisualEmbedder(
+    model_name="vidore/colSmol-500M",
+    torch_dtype=torch.float16,
+    output_dtype=np.float16,
+    batch_size=8,
+)
+
+indexer = QdrantIndexer(
+    url=QDRANT_URL,
+    api_key=QDRANT_KEY,
+    collection_name=collection,
+    prefer_grpc=True,
+    vector_datatype="float16",
+)
+indexer.create_collection(force_recreate=False)
+
+pipeline = ProcessingPipeline(
+    embedder=embedder,
+    indexer=indexer,
+    embedding_strategy="all",  # store full tokens + pooled vectors in one pass
+    crop_empty=True,
+    crop_empty_percentage_to_remove=0.99,  # kept for traceability
+    crop_empty_remove_page_number=True,
+    crop_empty_preserve_border_px=1,
+    crop_empty_uniform_rowcol_std_threshold=3.0,
+)
+
+pdfs = [Path("docs/a.pdf"), Path("docs/b.pdf")]
+for pdf_path in pdfs:
+    pipeline.process_pdf(
+        pdf_path,
+        skip_existing=True,
+        upload_to_cloudinary=False,
+        upload_to_qdrant=True,
+    )
+```
+
+CLI equivalent:
+
+```bash
+export SIGIR_QDRANT_URL="https://YOUR_QDRANT"
+export SIGIR_QDRANT_KEY="YOUR_KEY"
+
+visual-rag process \
+  --reports-dir ./docs \
+  --collection my_visual_docs \
+  --model vidore/colSmol-500M \
+  --strategy all \
+  --batch-size 8 \
+  --qdrant-vector-dtype float16 \
+  --prefer-grpc \
+  --crop-empty \
+  --crop-empty-remove-page-number
+```
+
 ### Process a PDF into images (no embedding, no vector DB)
 
 ```python
@@ -124,16 +201,11 @@ visual-rag-toolkit/
 Configure via environment variables or YAML:
 
 ```bash
-# Qdrant credentials (preferred names used by the demo + scripts)
-export SIGIR_QDRANT_URL="https://your-cluster.qdrant.io"
-export SIGIR_QDRANT_KEY="your-api-key"
 
-# Backwards-compatible fallbacks (also supported)
+# Qdrant credentials (preferred names used by the demo + scripts)
 export QDRANT_URL="https://your-cluster.qdrant.io"
 export QDRANT_API_KEY="your-api-key"
 
-export VISUALRAG_MODEL="vidore/colSmol-500M"
-
 # Special token handling (default: filter them out)
 export VISUALRAG_INCLUDE_SPECIAL_TOKENS=true  # Include special tokens
 ```
@@ -184,7 +256,7 @@ python -m benchmarks.vidore_beir_qdrant.run_qdrant_beir \
 ```
 
 More commands (including multi-stage variants and cropping configs) live in:
-- `benchmarks/vidore_tatdqa_test/COMMANDS.md`
+- `examples/COMMANDS.md`
 
 ## 🔧 Development
 

{visual_rag_toolkit-0.1.1 → visual_rag_toolkit-0.1.2}/demo/indexing.py

@@ -1,10 +1,12 @@
 """Indexing runner with UI updates."""
 
 import hashlib
+import importlib.util
 import json
 import time
 import traceback
 from datetime import datetime
+from pathlib import Path
 from typing import Any, Dict, Optional
 
 import numpy as np
@@ -19,8 +21,35 @@ TORCH_DTYPE_MAP = {
     "float32": torch.float32,
     "bfloat16": torch.bfloat16,
 }
-from visual_rag.indexing import QdrantIndexer
-from benchmarks.vidore_tatdqa_test.dataset_loader import load_vidore_beir_dataset
+
+# --- Robust imports (Spaces-friendly) ---
+# Some environments can have a third-party `benchmarks` package installed, or
+# resolve `visual_rag.indexing` oddly. These fallbacks keep the demo working.
+try:
+    from visual_rag.indexing import QdrantIndexer
+except Exception:  # pragma: no cover
+    from visual_rag.indexing.qdrant_indexer import QdrantIndexer
+
+
+def _load_local_benchmark_module(module_filename: str):
+    root = Path(__file__).resolve().parents[1]  # demo/.. = repo root
+    target = root / "benchmarks" / "vidore_tatdqa_test" / module_filename
+    if not target.exists():
+        raise ModuleNotFoundError(f"Missing local benchmark module file: {target}")
+    name = f"_visual_rag_toolkit_local_{target.stem}"
+    spec = importlib.util.spec_from_file_location(name, str(target))
+    if spec is None or spec.loader is None:
+        raise ModuleNotFoundError(f"Could not load module spec for: {target}")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)  # type: ignore[attr-defined]
+    return mod
+
+
+try:
+    from benchmarks.vidore_tatdqa_test.dataset_loader import load_vidore_beir_dataset
+except ModuleNotFoundError:  # pragma: no cover
+    _dl = _load_local_benchmark_module("dataset_loader.py")
+    load_vidore_beir_dataset = _dl.load_vidore_beir_dataset
 
 from demo.qdrant_utils import get_qdrant_credentials
 

{visual_rag_toolkit-0.1.1 → visual_rag_toolkit-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "visual-rag-toolkit"
-version = "0.1.1"
+version = "0.1.2"
 description = "End-to-end visual document retrieval with ColPali, featuring two-stage pooling for scalable search"
 readme = "README.md"
 license = {file = "LICENSE"}

visual_rag_toolkit-0.1.1/benchmarks/vidore_tatdqa_test/COMMANDS.md

@@ -1,83 +0,0 @@
-# ViDoRe TAT-DQA (Qdrant) — commands
-
-## Environment
-
-Either export:
-
-```bash
-export QDRANT_URL="..."
-export QDRANT_API_KEY="..."  # optional
-```
-
-Or create a `.env` file in `visual-rag-toolkit/` with the same variables.
-
-## Index + evaluate (single run)
-
-This is the “all-in-one” script (indexes, then evaluates once):
-
-```bash
-python -m benchmarks.vidore_tatdqa_test.run_qdrant \
-  --dataset vidore/tatdqa_test \
-  --collection vidore_tatdqa_test \
-  --recreate --index \
-  --indexing-threshold 0 \
-  --batch-size 6 \
-  --upload-batch-size 12 \
-  --upload-workers 0 \
-  --loader-workers 0 \
-  --prefer-grpc \
-  --torch-dtype float16 \
-  --no-upsert-wait \
-  --qdrant-vector-dtype float16
-```
-
-## Evaluate only (no re-index) — baseline + sweeps
-
-These commands assume the Qdrant collection already exists and is populated.
-
-### Baseline: single-stage full MaxSim
-
-```bash
-python -m benchmarks.vidore_tatdqa_test.sweep_eval \
-  --dataset vidore/tatdqa_test \
-  --collection vidore_tatdqa_test \
-  --prefer-grpc \
-  --mode single_full \
-  --torch-dtype auto \
-  --query-batch-size 32 \
-  --top-k 10 \
-  --out-dir results/sweeps
-```
-
-### Two-stage sweep (preferred): stage-1 tokens vs tiles, stage-2 full rerank
-
-```bash
-python -m benchmarks.vidore_tatdqa_test.sweep_eval \
-  --dataset vidore/tatdqa_test \
-  --collection vidore_tatdqa_test \
-  --prefer-grpc \
-  --mode two_stage \
-  --stage1-mode tokens_vs_tiles \
-  --prefetch-ks 20,50,100,200,400 \
-  --torch-dtype auto \
-  --query-batch-size 32 \
-  --top-k 10 \
-  --out-dir results/sweeps
-```
-
-### Smoke test (optional): run only N queries
-
-```bash
-python -m benchmarks.vidore_tatdqa_test.sweep_eval \
-  --dataset vidore/tatdqa_test \
-  --collection vidore_tatdqa_test \
-  --prefer-grpc \
-  --mode single_full \
-  --torch-dtype auto \
-  --query-batch-size 32 \
-  --top-k 10 \
-  --max-queries 50 \
-  --out-dir results/sweeps
-```
-
-