Skip to content

https://arxiv.org/abs/2606.28344. The end of web parsing. The beginning of scalable pixel-native search. link: https://pixelrag.ai/

fix(index): accept a single file as a source path (#130)

sylvere BAMENOU7b47d34d05a9
diff --git a/README.md b/README.md
index 83f3c3e..2cae1e5 100644
--- a/README.md
+++ b/README.md
@@ -174,8 +174,11 @@ pixelrag serve --index-dir ./my_index --port 30001
No GPU required — runs on macOS (Apple Silicon) or any machine with Python 3.10+.
+PDF rendering needs the `pdf` extra and poppler (`brew install poppler`, or
+`apt-get install poppler-utils` on Debian/Ubuntu).
+
```bash
-pip install 'pixelrag[index]'
+pip install 'pixelrag[index,pdf]'
# 1. Grab a sample PDF (or use your own)
curl -L -o paper.pdf https://raw.githubusercontent.com/StarTrail-org/PixelRAG/main/assets/pixelrag-paper.pdf
diff --git a/index/src/pixelrag_index/sources/local.py b/index/src/pixelrag_index/sources/local.py
index 4611fa6..0b32856 100644
--- a/index/src/pixelrag_index/sources/local.py
+++ b/index/src/pixelrag_index/sources/local.py
@@ -1,4 +1,4 @@
-"""Local directory source — auto-detect file types."""
+"""Local source — a single file or a directory tree; auto-detect file types."""
from pathlib import Path
from typing import Iterator
@@ -20,10 +20,13 @@ EXTENSIONS = {
class LocalSource(Source):
def __init__(self, path: str, **kwargs):
self.path = Path(path)
+ # A path pointing straight at a document is a single-item source; rglob
+ # on a file yields nothing, so branch before walking.
+ candidates = (
+ [self.path] if self.path.is_file() else sorted(self.path.rglob("*"))
+ )
self._files = [
- f
- for f in sorted(self.path.rglob("*"))
- if f.is_file() and f.suffix.lower() in EXTENSIONS
+ f for f in candidates if f.is_file() and f.suffix.lower() in EXTENSIONS
]
def __iter__(self) -> Iterator[Document]:
diff --git a/index/src/pixelrag_index/sources/pdf.py b/index/src/pixelrag_index/sources/pdf.py
index 7e2d52a..62633f6 100644
--- a/index/src/pixelrag_index/sources/pdf.py
+++ b/index/src/pixelrag_index/sources/pdf.py
@@ -1,4 +1,4 @@
-"""PDF directory source."""
+"""PDF source — a single .pdf file or a directory tree of them."""
from pathlib import Path
from typing import Iterator
@@ -9,7 +9,13 @@ from .base import Document, Source
class PDFSource(Source):
def __init__(self, path: str, **kwargs):
self.path = Path(path)
- self._files = sorted(self.path.glob("**/*.pdf"))
+ # A path pointing straight at a .pdf is a single-item source; the glob
+ # below only ever matches inside a directory.
+ self._files = (
+ [self.path]
+ if self.path.is_file() and self.path.suffix.lower() == ".pdf"
+ else sorted(self.path.glob("**/*.pdf"))
+ )
def __iter__(self) -> Iterator[Document]:
for pdf in self._files:
diff --git a/tests/test_source_single_file.py b/tests/test_source_single_file.py
new file mode 100644
index 0000000..6f8e83f
--- /dev/null
+++ b/tests/test_source_single_file.py
@@ -0,0 +1,50 @@
+"""A source path may point straight at a document, not just a directory.
+
+`pixelrag index build --source ./paper.pdf` is the form the README documents,
+but both adapters used to walk the path as a directory — which silently
+yielded zero documents and failed several stages later at index build.
+"""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parents[1] / "index" / "src"))
+from pixelrag_index.sources.local import LocalSource
+from pixelrag_index.sources.pdf import PDFSource
+
+
+def docs_dir(tmp_path):
+ (tmp_path / "paper.pdf").write_bytes(b"%PDF-1.4\n")
+ (tmp_path / "notes.md").write_text("# Notes")
+ (tmp_path / "ignored.csv").write_text("a,b,c")
+ nested = tmp_path / "sub"
+ nested.mkdir()
+ (nested / "deep.pdf").write_bytes(b"%PDF-1.4\n")
+ return tmp_path
+
+
+def test_pdf_source_accepts_a_single_file(docs_dir):
+ source = PDFSource(str(docs_dir / "paper.pdf"))
+ assert [d.id for d in source] == ["paper"]
+ assert len(source) == 1
+
+
+def test_local_source_accepts_a_single_file(docs_dir):
+ source = LocalSource(str(docs_dir / "notes.md"))
+ docs = list(source)
+ assert [d.id for d in docs] == ["notes"]
+ assert docs[0].metadata["type"] == "text"
+
+
+def test_local_source_single_file_still_filters_by_extension(docs_dir):
+ """An unsupported suffix yields nothing, matching directory behaviour."""
+ assert len(LocalSource(str(docs_dir / "ignored.csv"))) == 0
+
+
+def test_directory_traversal_is_unchanged(docs_dir):
+ """The directory path must keep recursing into sub-directories."""
+ assert {d.id for d in PDFSource(str(docs_dir))} == {"paper", "deep"}
+ assert {d.id for d in LocalSource(str(docs_dir))} == {"paper", "notes", "deep"}