PyStreamPDF 2.2.0__tar.gz → 2.3.0__tar.gz

{pystreampdf-2.2.0 → pystreampdf-2.3.0}/Cargo.lock

@@ -16,9 +16,9 @@ dependencies = [
 
 [[package]]
 name = "android_system_properties"
-version = "0.1.6"
+version = "0.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ae221649c9976a6f6c56ae1facf410f3ddb33cc661c4b7b61020a912d4237fbc"
+checksum = "819e7219dbd41043ac279b19830f2efc897156490d7fd6ea916720117ee66311"
 dependencies = [
  "libc",
 ]
@@ -31,9 +31,9 @@ checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
 
 [[package]]
 name = "bitflags"
-version = "2.13.1"
+version = "2.13.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
 
 [[package]]
 name = "block-buffer"
@@ -52,9 +52,9 @@ checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
 
 [[package]]
 name = "bytemuck"
-version = "1.25.2"
+version = "1.25.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "95832e849adfb21180ccb6826a99da14e5d266ae5c2e668e1602cf234f153797"
+checksum = "d6aedf8ae72766347502cf3cb4f41cf5e9cc37d28bee90f1fdaaae15f9cf9424"
 
 [[package]]
 name = "byteorder"
@@ -76,9 +76,9 @@ checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
 
 [[package]]
 name = "cc"
-version = "1.4.2"
+version = "1.2.67"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5d262e149917187838d5b42777c8253bcb64500067342904e7d429499a6f277e"
+checksum = "e17dd265a7d0f31ef544e1b20e03add05d3b45b491b633b10d67145d2acc1a38"
 dependencies = [
  "find-msvc-tools",
  "shlex",
@@ -160,9 +160,9 @@ dependencies = [
 
 [[package]]
 name = "either"
-version = "1.17.0"
+version = "1.16.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9e5e8f6c15a24b9a3ee5efec809ccd006d3b30e8b3bb63c39af737c7f87daa1d"
+checksum = "91622ff5e7162018101f2fea40d6ebf4a78bbe5a49736a2020649edf9693679e"
 
 [[package]]
 name = "errno"
@@ -188,27 +188,27 @@ checksum = "7360491ce676a36bf9bb3c56c1aa791658183a54d2744120f27285738d90465a"
 
 [[package]]
 name = "find-msvc-tools"
-version = "0.1.10"
+version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "26b73573e6edcd2af0cdf47bd6cb58f0b3839491263c314eaad1ccf24430e1de"
+checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
 
 [[package]]
 name = "futures-core"
-version = "0.3.34"
+version = "0.3.32"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e"
+checksum = "7e3450815272ef58cec6d564423f6e755e25379b217b0bc688e295ba24df6b1d"
 
 [[package]]
 name = "futures-task"
-version = "0.3.34"
+version = "0.3.32"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd"
+checksum = "037711b3d59c33004d3856fbdc83b99d4ff37a24768fa1be9ce3538a1cde4393"
 
 [[package]]
 name = "futures-util"
-version = "0.3.34"
+version = "0.3.32"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc"
+checksum = "389ca41296e6190b48053de0321d02a77f32f8a5d2461dd38762c0593805c6d6"
 dependencies = [
  "futures-core",
  "futures-task",
@@ -314,9 +314,9 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
 [[package]]
 name = "js-sys"
-version = "0.3.104"
+version = "0.3.103"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0e0c1080212aad755ea003d18543e8768dd432c48819efd73a7bf1e39b7a5a3a"
+checksum = "53b44bfcdb3f8d5837a46dae1ca9660a837176eee74a28b229bc626816589102"
 dependencies = [
  "cfg-if",
  "futures-util",
@@ -325,9 +325,9 @@ dependencies = [
 
 [[package]]
 name = "libc"
-version = "0.2.189"
+version = "0.2.186"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
 
 [[package]]
 name = "libloading"
@@ -491,15 +491,15 @@ checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e"
 
 [[package]]
 name = "portable-atomic"
-version = "1.15.0"
+version = "1.13.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
 
 [[package]]
 name = "proc-macro2"
-version = "1.0.107"
+version = "1.0.106"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
 dependencies = [
  "unicode-ident",
 ]
@@ -557,7 +557,7 @@ dependencies = [
  "proc-macro2",
  "pyo3-macros-backend",
  "quote",
- "syn 2.0.119",
+ "syn",
 ]
 
 [[package]]
@@ -570,12 +570,12 @@ dependencies = [
  "proc-macro2",
  "pyo3-build-config",
  "quote",
- "syn 2.0.119",
+ "syn",
 ]
 
 [[package]]
 name = "pystreampdf"
-version = "2.2.0"
+version = "2.3.0"
 dependencies = [
  "chrono",
  "pyo3",
@@ -584,9 +584,9 @@ dependencies = [
 
 [[package]]
 name = "quote"
-version = "1.0.47"
+version = "1.0.46"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
 dependencies = [
  "proc-macro2",
 ]
@@ -629,9 +629,9 @@ checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
 [[package]]
 name = "serde"
-version = "1.0.229"
+version = "1.0.228"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
 dependencies = [
  "serde_core",
  "serde_derive",
@@ -639,29 +639,29 @@ dependencies = [
 
 [[package]]
 name = "serde_core"
-version = "1.0.229"
+version = "1.0.228"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
 dependencies = [
  "serde_derive",
 ]
 
 [[package]]
 name = "serde_derive"
-version = "1.0.229"
+version = "1.0.228"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.3",
+ "syn",
 ]
 
 [[package]]
 name = "serde_json"
-version = "1.0.151"
+version = "1.0.150"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
+checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
 dependencies = [
  "itoa",
  "memchr",
@@ -721,7 +721,7 @@ dependencies = [
 
 [[package]]
 name = "streampdf-core"
-version = "2.2.0"
+version = "2.3.0"
 dependencies = [
  "chrono",
  "pdfium-render",
@@ -746,17 +746,6 @@ dependencies = [
  "unicode-ident",
 ]
 
-[[package]]
-name = "syn"
-version = "3.0.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
-dependencies = [
- "proc-macro2",
- "quote",
- "unicode-ident",
-]
-
 [[package]]
 name = "target-lexicon"
 version = "0.12.16"
@@ -780,14 +769,14 @@ checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.119",
+ "syn",
 ]
 
 [[package]]
 name = "tokio"
-version = "1.53.1"
+version = "1.52.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "202caea871b69668250d242070849eb495be178ed697a3e98aebce5bc81a0bed"
+checksum = "8fc7f01b389ac15039e4dc9531aa973a135d7a4135281b12d7c1bc79fd57fffe"
 dependencies = [
  "bytes",
  "libc",
@@ -802,13 +791,13 @@ dependencies = [
 
 [[package]]
 name = "tokio-macros"
-version = "2.7.2"
+version = "2.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "78773a2a397f451582ce068015985c33193cf6dea8b74d2a639fe457b2f07b0e"
+checksum = "385a6cb71ab9ab790c5fe8d67f1645e6c450a7ce006a33de03daa956cf70a496"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.3",
+ "syn",
 ]
 
 [[package]]
@@ -830,7 +819,7 @@ checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.119",
+ "syn",
 ]
 
 [[package]]
@@ -898,9 +887,9 @@ checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
 
 [[package]]
 name = "wasm-bindgen"
-version = "0.2.127"
+version = "0.2.126"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1b70935747edd64d89de3efa29d73789b806c15798f8e7dca4d8ac356b50ce70"
+checksum = "4b067c0c11094aef6b7a801c1e34a26affafdf3d051dba08456b868789aaf9a4"
 dependencies = [
  "cfg-if",
  "once_cell",
@@ -911,9 +900,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-futures"
-version = "0.4.77"
+version = "0.4.76"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6b7777d5cc23d0e91404e53ce2d5e8ec7acae3026b16233dba62cd3246457950"
+checksum = "c62df1340f32221cb9c54d6a27b030e3dba64361d4a95bed55f9aacb44da291d"
 dependencies = [
  "js-sys",
  "wasm-bindgen",
@@ -921,9 +910,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro"
-version = "0.2.127"
+version = "0.2.126"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "77775f8f3f7217702089053b94958f8f54061a3f663417df76e19cbdcca29bc1"
+checksum = "167ce5e579f6bcf889c4f7175a8a5a585de84e8ff93976ce393efa5f2837aab1"
 dependencies = [
  "quote",
  "wasm-bindgen-macro-support",
@@ -931,31 +920,31 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro-support"
-version = "0.2.127"
+version = "0.2.126"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e11d33f857dc2fb11b8bc75aee111aa9cbeb12cd9f25efd3d4c2a3dd4e235284"
+checksum = "f3997c7839262f4ef12cf90b818d6340c18e80f263f1a94bf157d0ec4420380e"
 dependencies = [
  "bumpalo",
  "proc-macro2",
  "quote",
- "syn 2.0.119",
+ "syn",
  "wasm-bindgen-shared",
 ]
 
 [[package]]
 name = "wasm-bindgen-shared"
-version = "0.2.127"
+version = "0.2.126"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7ef64dbcc55df09c7e5a46182d181c2cfa3e925f3da937ea764728b4bbb9dcbf"
+checksum = "dc1b4cb0cc549fcf58d7dfc081778139b3d283a081644e833e84682ad71cea24"
 dependencies = [
  "unicode-ident",
 ]
 
 [[package]]
 name = "web-sys"
-version = "0.3.104"
+version = "0.3.103"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c435338968042f4f59a557f690a253676d47ce13ceb55d70100e7facf6620a30"
+checksum = "8622dcb61c0bcc9fffa6938bed81210af2da9a7e4a1a834b2e37a59b6dfb6141"
 dependencies = [
  "js-sys",
  "wasm-bindgen",
@@ -982,7 +971,7 @@ checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.119",
+ "syn",
 ]
 
 [[package]]
@@ -993,7 +982,7 @@ checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.119",
+ "syn",
 ]
 
 [[package]]
@@ -1031,22 +1020,22 @@ dependencies = [
 
 [[package]]
 name = "zerocopy"
-version = "0.8.56"
+version = "0.8.54"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "556764e583adb45a9f8d413c2a147fa7e8d821e48e12b14fd560b607998b75eb"
+checksum = "b7cbbc0a705a0fd05cc3676525980d2bf5a9bc4adac6d6475209a7887cf59d19"
 dependencies = [
  "zerocopy-derive",
 ]
 
 [[package]]
 name = "zerocopy-derive"
-version = "0.8.56"
+version = "0.8.54"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f2ab42fc20575779bd240faa45f94a74256f755c0fa9e89f0ede20d91d0cdfc1"
+checksum = "e2e817b7b52d0c7358d3246da9d69935ebb18116b2b102b4230dac079b4862f5"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.119",
+ "syn",
 ]
 
 [[package]]
@@ -1057,9 +1046,9 @@ checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
 
 [[package]]
 name = "zune-core"
-version = "0.5.3"
+version = "0.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d56377fd46368984a170bc5aac5567e52ca5da874caa60bea39fcbca78fb658b"
+checksum = "cb8a0807f7c01457d0379ba880ba6322660448ddebc890ce29bb64da71fb40f9"
 
 [[package]]
 name = "zune-jpeg"

{pystreampdf-2.2.0 → pystreampdf-2.3.0}/Cargo.toml

@@ -3,7 +3,7 @@ members = ["core", "python"]
 resolver = "2"
 
 [workspace.package]
-version = "2.2.0"
+version = "2.3.0"
 edition = "2021"
 authors = ["Georgi Mammen Mullassery <mullassery@gmail.com>"]
 license = "Proprietary"

{pystreampdf-2.2.0 → pystreampdf-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyStreamPDF
-Version: 2.2.0
+Version: 2.3.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -35,13 +35,16 @@ Project-URL: Repository, https://github.com/Mullassery/StreamPDF
 
 # PyStreamPDF
 
-**Reduce RAG costs 50-70%. Extract only what matters from PDFs.**
+**Extract only what matters from PDFs, so you send less to LLMs.**
 
-Stop sending entire documents to LLMs. PyStreamPDF analyzes structure, identifies relevant sections, and extracts only critical content. Cut token costs 50-70% while improving retrieval accuracy.
+Stop sending entire documents to LLMs. PyStreamPDF parses PDF structure and
+splits content into semantic, token-budget-aware chunks so you can send
+only the relevant parts of a document to a model. See "Token Savings"
+below for how much that saves in practice — it depends on your documents.
 
 [![PyPI](https://img.shields.io/pypi/v/pystreampdf)](https://pypi.org/project/pystreampdf)
 [![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-blue)](https://www.python.org)
-[![Tests: 536 Passing](https://img.shields.io/badge/tests-536%20passing-success)](./tests)
+[![Tests: 557 Passing](https://img.shields.io/badge/tests-557%20passing-success)](./tests)
 [![License: Proprietary](https://img.shields.io/badge/License-Proprietary-blue.svg)](./LICENSE)
 
 ---
@@ -49,21 +52,24 @@ Stop sending entire documents to LLMs. PyStreamPDF analyzes structure, identifie
 ## 30-Second Start
 
 ```python
-from pystreampdf import Document
+from pystreampdf import SemanticChunker, ElementType
 
-# Extract only relevant content from PDF
-doc = Document("financial_report.pdf")
+with open("financial_report.pdf", "rb") as f:
+    text = f.read().decode("latin-1", errors="ignore")  # or use a real PDF text extractor first
 
-# Smart content extraction
-relevant = doc.extract_relevant("revenue for Q3 2024")
-print(f"Extracted {len(relevant)} chunks")
-print(f"Token savings: {relevant.token_savings:.0%}")  # 60% savings
-
-# Send only relevant parts to LLM
-for chunk in relevant:
-    response = llm.query(chunk, "What was Q3 revenue?")
+chunker = SemanticChunker(target_tokens=500)
+chunks = chunker.chunk_content(
+    text, element_type=ElementType.TEXT, page_start=1, page_end=1
+)
+print(f"Split into {len(chunks)} semantic chunks")
 ```
 
+There is no `Document`/`.extract_relevant()` class in this package —
+`SemanticChunker` (shown above) and `PDFCache` (see "Quick Start: Document
+Extraction" below) are the real, exported API. If you built against a
+`Document` class from an earlier version of these docs, it never actually
+existed in source; see Known Issues.
+
 ---
 
 ## Why PyStreamPDF?
@@ -75,10 +81,10 @@ for chunk in relevant:
 - No way to know which parts actually matter
 
 **The Solution:**
-- Intelligent document analysis finds relevant sections
-- Semantic chunking with context awareness
-- 50-70% reduction in token usage
-- Better retrieval accuracy (less noise)
+- Semantic chunking with context awareness (real, in `SemanticChunker`)
+- Token-budget-aware caching (real, in `PDFCache` / `TokenBudgetConfig`)
+- Reduces the volume of text you send per query — see "Token Savings"
+  below for what's measured vs. illustrative
 
 ---
 
@@ -92,52 +98,24 @@ for chunk in relevant:
 - **Token Budgeting:** Allocate tokens by document type
 - **Smart Caching:** L1 memory + L2 disk (HMAC-signed on disk — no unverified deserialization)
 - **Metadata Preservation:** Keep tables, images, structure
-- **Production-Ready:** 536 passing tests (2 skipped when optional OCR system deps aren't installed)
+- **Production-Ready:** 557 passing tests (2 skipped when optional OCR system deps aren't installed)
 
 ---
 
 ## Real-World Use Cases
 
-**Financial Documents:**
-```python
-# Extract relevant sections from annual report
-doc = Document("10-K_2024.pdf")
-revenue_sections = doc.extract_relevant("revenue")
-earnings_sections = doc.extract_relevant("earnings")
-
-# 70% fewer tokens than sending whole PDF
-for section in revenue_sections:
-    summary = llm.query(section, "What was total revenue?")
-```
-
-**Legal Contracts:**
-```python
-# Find clauses without reading everything
-doc = Document("contract.pdf")
-liability = doc.extract_relevant("liability", "indemnification")
-print(f"Found in {len(liability)} sections")
-```
-
-**Research Papers:**
-```python
-# Extract methodology and results
-doc = Document("paper.pdf")
-methods = doc.extract_relevant("methods", "experiment")
-results = doc.extract_relevant("results", "findings")
-```
+See [examples/basic_parse.py](examples/basic_parse.py) for the Rust-backed
+`pystreampdf.open()` path (document/page/structure inspection — requires
+the compiled `_core` extension, see Known Issues) and
+[examples/token_budget_and_cache_example.py](examples/token_budget_and_cache_example.py)
+for the pure-Python `SemanticChunker` + `PDFCache` + `TokenBudgetConfig`
+path shown above. Both are real, runnable scripts — copying them is more
+reliable than a README snippet for an evolving API.
 
 ---
 
 ## Token Savings
 
-| Document | Size | Full PDF Tokens | PyStreamPDF | Savings |
-|----------|------|-----------------|-------------|---------|
-| Annual Report | 200 pages | 50K | 15K | 70% |
-| Contract | 50 pages | 12K | 4K | 67% |
-| Research Paper | 30 pages | 8K | 2K | 75% |
-
-**Results:** Lower costs + better retrieval accuracy + faster responses
-
 **A note on how token counts are computed:** by default, token counts use a
 `len(text) / 4` heuristic (a common rule of thumb, but approximate — it can
 be off by a meaningful margin, especially for code or non-English text).
@@ -150,9 +128,15 @@ pip install "pystreampdf[tiktoken]"
 When `tiktoken` is installed, `pystreampdf.tokenizer.is_exact()` returns
 `True` and counts use the real `cl100k_base` encoding; otherwise it falls
 back to the heuristic. Check `pystreampdf.tokenizer.TOKENIZER_MODE` to see
-which mode produced a given number. The savings figures in the table above
-were measured using the heuristic mode; your exact numbers with `tiktoken`
-enabled may differ slightly.
+which mode produced a given number.
+
+Actual token savings depend entirely on your documents and how narrowly
+you scope `extract_relevant`-style queries — there's no committed
+benchmark result in this repo backing a specific percentage (the earlier
+"70%"/"10-50x" style claims in this README and in `__init__.py`'s
+docstring weren't measured against anything checked in). Run
+[examples/token_budget_and_cache_example.py](examples/token_budget_and_cache_example.py)
+against your own documents to get a real number for your use case.
 
 ---
 
@@ -242,11 +226,46 @@ structure detection, metadata, chunking, citations, validation). It's
 opt-in, binds to `127.0.0.1` only, and requires `allow_remote=True` to be
 exposed beyond localhost. See [examples/mcp_pystreampdf.py](examples/mcp_pystreampdf.py).
 
+## Known Issues
+
+- Earlier versions of this README documented a `Document` class with
+  `.extract_relevant()` and a `.token_savings` attribute — verified
+  against source: this class has never existed in this package. Fixed
+  in this pass to describe the real, exported API (`SemanticChunker`,
+  `PDFCache`, `TokenBudgetConfig`, and the Rust-backed `pystreampdf.open()`).
+- The published PyPI wheel is the only wheel on PyPI — macOS arm64 only,
+  no sdist. On any other platform or Python version, `pip install` will
+  fail without a local Rust toolchain to build from source.
+- ~~The published version (2.2.1) is ahead of what's tagged in this repo's
+  Cargo.toml/__init__.py (2.2.0)~~ Resolved: 2.3.0 (this release) is
+  unambiguously ahead of both 2.2.0 and 2.2.1.
+- The Rust-backed `pystreampdf.open()` / `pystreampdf.load_index()` API
+  (used in `examples/basic_parse.py`) silently becomes `None` if the
+  compiled `_core` extension isn't available (e.g. a from-source install
+  without `maturin develop`) — falling back to `SemanticChunker`/`PDFCache`
+  in that case, per the code above, not a hard error.
+- The "Tests & Build" GitHub Actions workflow was red for several weeks
+  due to two CI infrastructure bugs (not the test suite itself), both
+  now fixed and confirmed green in CI:
+  [run 32611116541](https://github.com/Mullassery/PyStreamPDF/actions/runs/32611116541).
+  First, `dtolnay/rust-toolchain@v1` required an explicit `toolchain`
+  input the workflow didn't provide, failing both jobs before any tests
+  ran — fixed by pinning to `dtolnay/rust-toolchain@stable`. Second, once
+  that was fixed, `maturin develop` failed in the Python-test job because
+  `actions/setup-python` doesn't provide an active virtualenv, which
+  maturin requires — fixed by creating and activating a `.venv` before
+  the build step. Actual CI output as of 2.2.0: `pytest` — 536 passed, 2
+  skipped (Python 3.10, 3.11, and 3.12, each identical); `cargo test` — 23
+  passed, 0 failed. (The Rust suite has 23 tests, not 536 — an earlier
+  version of this section conflated the pytest count with the Rust one.)
+  As of 2.3.0: `pytest` — 557 passed, 2 skipped (21 new tests added for
+  `tests/test_mcp_tools.py`).
+
 ## License
 
 Proprietary License — Free to use with explicit attribution. See [LICENSE](LICENSE).
 
 ---
 
-**PyStreamPDF v2.2.0** | Intelligent PDF processing for AI | Python 3.9+ | 536 passing tests
+**PyStreamPDF v2.3.0** | Intelligent PDF processing for AI | Python 3.9+ | 557 passing tests