pikuri-pdf 0.0.7 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15262ec68d575017876fbd0d6fc1812187fd004b72bd35d9d14180da89d68158
-  data.tar.gz: ac8496b5f58cb08b0dc10d86bd9c9911097117746cc4e39298c3a04347bf6fa9
+  metadata.gz: e875a8f930f496ea5e0524e9c89d1323c950a84f8eb3112b9dc46c966f18a271
+  data.tar.gz: 2a19155e640dde0d04645afd6d74cdcec6da6856b2cba997fd3b79b261a0438e
 SHA512:
-  metadata.gz: e3177ca8f534ebaa3033b730d68f305670eef81ddd66180930f44be1e6e62811fc33abe8ebfd94b2fc654f8e29b015e39fccf1eb4b40defbc22f569c84501794
-  data.tar.gz: b7fcb7ded03135da14351889b47cdb67bd11049cd5dba42651ac8fd678631aa67377367187019ecc6d9260cde5ba38f77aa59b9ee684f23eac193dd1a2adf6be
+  metadata.gz: deff0dfd33c26fed2becf99b70a978108debb56ef12e6a2d1b1b7a08eef07de6fc21c9deb47103d86f6e6974efffe5e2247510362b966ee8a263ac0d7e02f198
+  data.tar.gz: e44291c7b532cd9433963707d3c612b4759206cfa15028aa7326b942014ac9ea5731ee239cc1c155f46cb547c4277b85b59832642517e204b37ee4d444b4de53

data/README.md

@@ -37,8 +37,9 @@ posture. This gem is the no-infrastructure wiring — in-process
 means no docker and no host CLIs, and it's what makes the lazy
 page-windowed reads possible (a subprocess converter must convert
 the whole document before emitting anything, and re-converts it on
-every paged read). The guide wires this gem in chapter 3 and
-supersedes it with pikuri-extractors in chapter 7's assistant.
+every paged read). The guide wires this gem in the vector-DB
+chapter and supersedes it with pikuri-extractors in the
+universal-assistant chapter.
 
 ## Install
 

data/lib/pikuri/extractors/pdf.rb

@@ -4,48 +4,34 @@ require 'pdf-reader'
 
 module Pikuri
   module Extractors
-    # PDF → text extractor. Wraps the +pdf-reader+ gem: walk every
-    # page, emit a +"--- Page N ---"+ marker line followed by that
-    # page's extracted text, join the blocks with single newlines.
-    # The markers give every consumer page provenance — the Read
-    # tools tell the model to cite pages back to the user from them,
-    # +vectordb_search+ chunks carry them so a hit can say which page
-    # it came from, and what +vectordb_read+ shows matches what was
-    # indexed exactly. Pages with no extractable text contribute
-    # nothing (no marker either), so a fully scanned PDF extracts to
-    # the empty String — a deliberate silent skip callers detect by
-    # length if they care. No OCR in this path.
+    # PDF → text extractor over the +pdf-reader+ gem: each page emits a
+    # +"--- Page N ---"+ marker line then its text, blocks joined by
+    # single newlines. The markers carry page provenance downstream (a
+    # cited answer, a +vectordb+ hit's page number). A page with no
+    # extractable text contributes nothing — no marker — so a fully
+    # scanned PDF extracts to the empty String, a deliberate silent
+    # skip callers detect by length. No OCR here: +pdf-reader+ gives
+    # clean text from digitally-generated PDFs, nothing from scans.
     #
     # == Why a separate gem
     #
-    # This extractor lived in pikuri-core until pdf-reader's
-    # dependency tail (Ascii85, afm, hashery, ruby-rc4, ttfunk) became
-    # the largest single bite in the core's audit tree — five gems for
-    # one file format, serving nothing else in core. Splitting it out
-    # keeps the core minimal; hosts that want PDFs opt in with one
-    # {.register} call. Distinct from pikuri-extractors' sandboxed
-    # subprocess converters: this one is in-process and *lazy*
-    # ({.extract_lines} parses pages on demand), a property a
-    # subprocess converter structurally cannot have — see
-    # +Pikuri::Extractor+'s windowing yardoc.
+    # Split from pikuri-core to keep pdf-reader's five-gem dependency
+    # tail (Ascii85, afm, hashery, ruby-rc4, ttfunk) out of the core
+    # audit tree — five gems for one format nothing else in core uses.
+    # Hosts opt in with one {.register} call. Being in-process, it pages
+    # *lazily* ({.extract_lines} parses pages on demand) — a property a
+    # subprocess converter structurally cannot have. (The full
+    # this-gem-vs-pikuri-extractors PDF trade-off is in
+    # +pikuri-extractors/DESIGN.md+.)
     #
     # == Registration is explicit
     #
-    # Requiring pikuri-pdf defines this module but registers nothing.
-    # A host script opts in with +Pikuri::Extractors::PDF.register+,
-    # which inserts it at the *front* of the registry — unlike
-    # pikuri-extractors' before-the-terminal insert — because the
-    # +%PDF-+ magic-byte sniff is the strongest signal in the
-    # registry: it must win over +HTML+'s content-type match so a PDF
-    # served under a lying header is still extracted, and it never
-    # misfires on text.
-    #
-    # Matched by the +%PDF-+ magic prefix *or* an +application/pdf+
-    # content-type.
-    #
-    # Best-effort by design: +pdf-reader+ produces clean text from
-    # PDFs generated from a digital source (LaTeX, Word export, ...)
-    # but nothing useful from scanned documents.
+    # Requiring the gem registers nothing; a host opts in with
+    # +Pikuri::Extractors::PDF.register+, which *front*-inserts into the
+    # registry (unlike pikuri-extractors' before-terminal insert)
+    # because the +%PDF-+ magic sniff is the registry's strongest
+    # signal — it must beat +HTML+'s content-type match so a PDF under a
+    # lying header still extracts, and it never misfires on text.
     module PDF
       # Insert this extractor at the front of
       # +Pikuri::Extractor.registry+ (see "Registration is explicit"
@@ -94,17 +80,14 @@ module Pikuri
       # +Pikuri::Extractor.extract_paged+ window) never pays for the
       # pages past its window.
       #
-      # +pdf-reader+ raises a handful of typed exceptions for
-      # documents it cannot parse — broken xrefs
-      # ({::PDF::Reader::MalformedPDFError}), invalid page references
-      # ({::PDF::Reader::InvalidPageError}), encrypted/XFA files
-      # ({::PDF::Reader::UnsupportedFeatureError}). All three describe
-      # a property of the document the LLM can react to ("try a
-      # different URL / file"), so they re-raise as
-      # {Pikuri::Extractor::Error} — from inside the enumerator, i.e.
-      # at consumption time, which for a broken xref means the first
-      # +next+. Genuine bugs in +pdf-reader+ itself surface as their
-      # own classes and crash loud.
+      # The three typed +pdf-reader+ parse failures — broken xrefs
+      # ({::PDF::Reader::MalformedPDFError}), bad page refs
+      # ({::PDF::Reader::InvalidPageError}), encrypted/XFA
+      # ({::PDF::Reader::UnsupportedFeatureError}) — are document
+      # properties the LLM can react to, so they re-raise as
+      # {Pikuri::Extractor::Error}, from *inside* the enumerator: at
+      # consumption time, which for a broken xref means the first
+      # +next+. Other +pdf-reader+ errors are bugs and crash loud.
       #
       # @param io [IO, StringIO] seekable IO positioned at the start
       #   of the PDF bytes; must remain open while the enumerator is

data/lib/pikuri-pdf.rb

@@ -2,21 +2,13 @@
 
 require 'pikuri-core'
 
-# Entry file for the pikuri-pdf gem. Sets up a dedicated Zeitwerk
-# loader rooted at this gem's +lib/+, contributing to the shared
-# +Pikuri::+ namespace alongside pikuri-core. After +require
-# 'pikuri-pdf'+, +Pikuri::Extractors::PDF+ is defined — but *nothing
-# is registered*: extractors plug into +Pikuri::Extractor.registry+
-# only when the host script calls their +register+ explicitly, so a
-# +bin/pikuri-*+ picks which extractors it wires in (same opt-in
-# philosophy as +c.add_extension+, same shape as pikuri-extractors'
-# +DOCUMENTS.register+).
-#
-# The +Pikuri::Extractors+ namespace is cooperative: pikuri-extractors
-# contributes +Documents+ / +DOCUMENTS+, this gem contributes +PDF+.
-# Each gem's loader manages only its own files; the loader constant is
-# +PDF_LOADER+ (not +LOADER+) so both gems can be loaded together
-# without colliding in the shared namespace.
+# Entry file for the pikuri-pdf gem: a per-gem Zeitwerk loader
+# contributing +Pikuri::Extractors::PDF+ to the shared +Pikuri::+
+# namespace. Defining the module registers *nothing* — a host opts in
+# with {Pikuri::Extractors::PDF.register} (see there). The
+# +Pikuri::Extractors+ namespace is cooperative (pikuri-extractors adds
+# +Documents+/+DOCUMENTS+), so the loader constant is +PDF_LOADER+, not
+# +LOADER+, to avoid a collision when both gems load together.
 module Pikuri
   module Extractors
     PDF_LOADER = Zeitwerk::Loader.new

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pikuri-pdf
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.1.0
 platform: ruby
 authors:
 - Martin Vysny
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.7
+        version: 0.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.7
+        version: 0.1.0
 - !ruby/object:Gem::Dependency
   name: pdf-reader
   requirement: !ruby/object:Gem::Requirement