sciwrite-lint 0.2.0__tar.gz → 0.2.1__tar.gz

{sciwrite_lint-0.2.0/sciwrite_lint.egg-info → sciwrite_lint-0.2.1}/PKG-INFO

@@ -1,43 +1,49 @@
 Metadata-Version: 2.4
 Name: sciwrite-lint
-Version: 0.2.0
+Version: 0.2.1
 Summary: A linter for scientific manuscripts — reference verification, consistency checking, and structural validation.
 Author: Sergey Samsonau
+Maintainer-email: Authentic Research Partners LLC <info@arpconnect.com>
 License-Expression: MIT
-Project-URL: Homepage, https://github.com/authentic-research-partners/sciwrite-lint
+Project-URL: Homepage, https://arpconnect.com
 Project-URL: Repository, https://github.com/authentic-research-partners/sciwrite-lint
+Project-URL: Documentation, https://github.com/authentic-research-partners/sciwrite-lint#readme
 Project-URL: Issues, https://github.com/authentic-research-partners/sciwrite-lint/issues
-Keywords: linter,scientific-writing,citation-verification,latex
+Keywords: linter,latex,bibtex,pdf,scientific-writing,academic-writing,citation-checker,reference-verification,claim-verification,manuscript,peer-review,arxiv,vllm,qwen
 Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
-Classifier: Topic :: Text Processing :: Markup :: LaTeX
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
 Requires-Python: <3.14,>=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: httpx>=0.27
-Requires-Dist: tenacity>=8.0
-Requires-Dist: trafilatura>=1.8
-Requires-Dist: aiosqlite>=0.20
+Requires-Dist: httpx>=0.28
+Requires-Dist: tenacity>=9.0
+Requires-Dist: trafilatura>=2.0
+Requires-Dist: aiosqlite>=0.22
 Requires-Dist: loguru>=0.7
 Requires-Dist: anyascii>=0.3
-Requires-Dist: rich>=13.0
+Requires-Dist: rich>=14.0
 Requires-Dist: defusedxml>=0.7
-Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic>=2.10
 Requires-Dist: rapidfuzz>=3.0
 Requires-Dist: bibtexparser>=1.4
-Requires-Dist: pdfplumber>=0.10
-Requires-Dist: openai>=1.0
+Requires-Dist: pdfplumber>=0.11
+Requires-Dist: openai>=2.0
 Requires-Dist: grobid-tei-xml>=0.1
-Requires-Dist: sentence-transformers>=3.0
-Requires-Dist: numpy>=1.24
+Requires-Dist: sentence-transformers>=5.0
+Requires-Dist: numpy>=2.0
 Requires-Dist: sqlite-vec>=0.1.6
-Requires-Dist: torch>=2.0
-Requires-Dist: transformers>=4.45
-Requires-Dist: Pillow>=10.0
-Requires-Dist: pypdf>=4.0
-Requires-Dist: pypdfium2>=4.0
-Requires-Dist: pdf2image>=1.16
+Requires-Dist: torch>=2.5
+Requires-Dist: transformers>=4.50
+Requires-Dist: Pillow>=12.0
+Requires-Dist: pypdf>=6.0
+Requires-Dist: pypdfium2>=5.0
+Requires-Dist: pdf2image>=1.17
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-xdist>=3.0; extra == "dev"
@@ -123,7 +129,7 @@ sciwrite-lint contributions paper.pdf --format json
 
 ### Optimizations
 
-Three models — a vision model (Qwen3-VL-2B), an embedding model (Arctic Embed), and an 8B reasoning LLM (Qwen3 via vLLM) — share a single consumer GPU. Models run in separate pipeline stages; on WSL2, CUDA memory virtualization pages idle allocations to system RAM, letting all three share physical VRAM. FP8 weights and KV cache (Ada Lovelace+) and per-paper SQLite caching with hash-based invalidation are baseline. On top of that:
+Three models — a vision model (Qwen3-VL-2B default, or 8B FP8 via `--vision-backend vllm` for +15% accuracy), an embedding model (Arctic Embed), and an 8B reasoning LLM (Qwen3 via vLLM) — share a single consumer GPU. Models run in separate pipeline stages; on WSL2, CUDA memory virtualization pages idle allocations to system RAM, letting all three share physical VRAM. FP8 weights and KV cache (Ada Lovelace+) and per-paper SQLite caching with hash-based invalidation are baseline. On top of that:
 
 - **Semantic section filtering** — embedding-based KNN retrieval sends only the ~5 most relevant sections per claim to the LLM, reducing LLM calls ~4x
 - **Prefix-first prompt structure** — shared context placed before variable content in all prompts, maximizing vLLM's automatic prefix caching
@@ -134,11 +140,11 @@ Three models — a vision model (Qwen3-VL-2B), an embedding model (Arctic Embed)
 - **8-source full-text cascade** — early exit on first successful download across arXiv, Semantic Scholar, OpenAlex, PubMed Central, Europe PMC, Unpaywall, bioRxiv, CORE
 - **Live monitoring** *(advanced)* — `sciwrite-lint containers monitor` shows service health, VRAM usage, and KV cache utilization in a terminal dashboard
 
-Full pipeline on a 50-reference paper: ~30 minutes initial (dominated by downloads and claim verification), minutes on cached reruns. On native Linux, embedding and vision default to CPU (tens of times slower) due to limited VRAM on consumer GPUs and no transparent paging of inactive vLLM container allocations; force GPU via config if VRAM permits.
+Full pipeline on a 50-reference paper: ~30 minutes initial (dominated by downloads and claim verification), minutes on cached reruns. On native Linux, the pipeline automatically swaps vLLM containers to free GPU for embedding and vision stages (~50x faster than CPU). *(Native Linux GPU swap is preliminary — tested on WSL2 only; expected to work, may need minor fixes.)*
 
 ## Install
 
-**Assumed setup:** A workstation with an NVIDIA GPU (16+ GB VRAM). Developed and tested on Windows (WSL2). Native Linux is likely to work with GPU memory allocation tuning (see [docs/services.md](docs/services.md#embedding-device)). Not tested on macOS.
+**Assumed setup:** A workstation with an NVIDIA GPU (16+ GB VRAM). Developed and tested on Windows (WSL2). Native Linux is likely to work with GPU memory allocation tuning (see [docs/services.md](https://github.com/authentic-research-partners/sciwrite-lint/blob/main/docs/services.md#embedding-device)). Not tested on macOS.
 
 Requires [uv](https://docs.astral.sh/uv/getting-started/installation/), a container runtime (podman or docker), CUDA drivers, and [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html).
 
@@ -157,7 +163,7 @@ sciwrite-lint containers start         # start GROBID + vLLM (needs GPU for vLLM
 sciwrite-lint containers monitor       # live dashboard: service health, VRAM, KV cache
 ```
 
-![Monitor dashboard](docs/monitor.png)
+![Monitor dashboard](https://github.com/authentic-research-partners/sciwrite-lint/raw/main/docs/monitor.png)
 
 `init` detects `.tex` files and their `.bib` references and generates a `.sciwrite-lint.toml` config. Review to confirm the right files were detected.
 
@@ -170,7 +176,7 @@ sciwrite-lint config show              # see what's configured
 sciwrite-lint config set-key semantic-scholar YOUR_KEY  # dedicated rate limit
 ```
 
-See [docs/services.md](docs/services.md) for GPU requirements, all external APIs, and API key details.
+See [docs/services.md](https://github.com/authentic-research-partners/sciwrite-lint/blob/main/docs/services.md) for GPU requirements, all external APIs, and API key details.
 
 ## Usage
 
@@ -256,12 +262,12 @@ Output formats: terminal (default) or `--format json`.
 
 - `sciwrite-lint checks` — list all checks
 - `sciwrite-lint <command> --help` — detailed usage for any command
-- [docs/services.md](docs/services.md) — GROBID, vLLM, external APIs, configuration
+- [docs/services.md](https://github.com/authentic-research-partners/sciwrite-lint/blob/main/docs/services.md) — GROBID, vLLM, external APIs, configuration
 
 For contributors and advanced users:
 
-- [docs/evals.md](docs/evals.md) — detection evaluation framework, adding test cases
-- [docs/calibration.md](docs/calibration.md) — SciLint Score calibration against ground-truth papers
+- [docs/evals.md](https://github.com/authentic-research-partners/sciwrite-lint/blob/main/docs/evals.md) — detection evaluation framework, adding test cases
+- [docs/calibration.md](https://github.com/authentic-research-partners/sciwrite-lint/blob/main/docs/calibration.md) — SciLint Score calibration against ground-truth papers
 
 ## License
 

{sciwrite_lint-0.2.0 → sciwrite_lint-0.2.1}/README.md

@@ -78,7 +78,7 @@ sciwrite-lint contributions paper.pdf --format json
 
 ### Optimizations
 
-Three models — a vision model (Qwen3-VL-2B), an embedding model (Arctic Embed), and an 8B reasoning LLM (Qwen3 via vLLM) — share a single consumer GPU. Models run in separate pipeline stages; on WSL2, CUDA memory virtualization pages idle allocations to system RAM, letting all three share physical VRAM. FP8 weights and KV cache (Ada Lovelace+) and per-paper SQLite caching with hash-based invalidation are baseline. On top of that:
+Three models — a vision model (Qwen3-VL-2B default, or 8B FP8 via `--vision-backend vllm` for +15% accuracy), an embedding model (Arctic Embed), and an 8B reasoning LLM (Qwen3 via vLLM) — share a single consumer GPU. Models run in separate pipeline stages; on WSL2, CUDA memory virtualization pages idle allocations to system RAM, letting all three share physical VRAM. FP8 weights and KV cache (Ada Lovelace+) and per-paper SQLite caching with hash-based invalidation are baseline. On top of that:
 
 - **Semantic section filtering** — embedding-based KNN retrieval sends only the ~5 most relevant sections per claim to the LLM, reducing LLM calls ~4x
 - **Prefix-first prompt structure** — shared context placed before variable content in all prompts, maximizing vLLM's automatic prefix caching
@@ -89,11 +89,11 @@ Three models — a vision model (Qwen3-VL-2B), an embedding model (Arctic Embed)
 - **8-source full-text cascade** — early exit on first successful download across arXiv, Semantic Scholar, OpenAlex, PubMed Central, Europe PMC, Unpaywall, bioRxiv, CORE
 - **Live monitoring** *(advanced)* — `sciwrite-lint containers monitor` shows service health, VRAM usage, and KV cache utilization in a terminal dashboard
 
-Full pipeline on a 50-reference paper: ~30 minutes initial (dominated by downloads and claim verification), minutes on cached reruns. On native Linux, embedding and vision default to CPU (tens of times slower) due to limited VRAM on consumer GPUs and no transparent paging of inactive vLLM container allocations; force GPU via config if VRAM permits.
+Full pipeline on a 50-reference paper: ~30 minutes initial (dominated by downloads and claim verification), minutes on cached reruns. On native Linux, the pipeline automatically swaps vLLM containers to free GPU for embedding and vision stages (~50x faster than CPU). *(Native Linux GPU swap is preliminary — tested on WSL2 only; expected to work, may need minor fixes.)*
 
 ## Install
 
-**Assumed setup:** A workstation with an NVIDIA GPU (16+ GB VRAM). Developed and tested on Windows (WSL2). Native Linux is likely to work with GPU memory allocation tuning (see [docs/services.md](docs/services.md#embedding-device)). Not tested on macOS.
+**Assumed setup:** A workstation with an NVIDIA GPU (16+ GB VRAM). Developed and tested on Windows (WSL2). Native Linux is likely to work with GPU memory allocation tuning (see [docs/services.md](https://github.com/authentic-research-partners/sciwrite-lint/blob/main/docs/services.md#embedding-device)). Not tested on macOS.
 
 Requires [uv](https://docs.astral.sh/uv/getting-started/installation/), a container runtime (podman or docker), CUDA drivers, and [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html).
 
@@ -112,7 +112,7 @@ sciwrite-lint containers start         # start GROBID + vLLM (needs GPU for vLLM
 sciwrite-lint containers monitor       # live dashboard: service health, VRAM, KV cache
 ```
 
-![Monitor dashboard](docs/monitor.png)
+![Monitor dashboard](https://github.com/authentic-research-partners/sciwrite-lint/raw/main/docs/monitor.png)
 
 `init` detects `.tex` files and their `.bib` references and generates a `.sciwrite-lint.toml` config. Review to confirm the right files were detected.
 
@@ -125,7 +125,7 @@ sciwrite-lint config show              # see what's configured
 sciwrite-lint config set-key semantic-scholar YOUR_KEY  # dedicated rate limit
 ```
 
-See [docs/services.md](docs/services.md) for GPU requirements, all external APIs, and API key details.
+See [docs/services.md](https://github.com/authentic-research-partners/sciwrite-lint/blob/main/docs/services.md) for GPU requirements, all external APIs, and API key details.
 
 ## Usage
 
@@ -211,12 +211,12 @@ Output formats: terminal (default) or `--format json`.
 
 - `sciwrite-lint checks` — list all checks
 - `sciwrite-lint <command> --help` — detailed usage for any command
-- [docs/services.md](docs/services.md) — GROBID, vLLM, external APIs, configuration
+- [docs/services.md](https://github.com/authentic-research-partners/sciwrite-lint/blob/main/docs/services.md) — GROBID, vLLM, external APIs, configuration
 
 For contributors and advanced users:
 
-- [docs/evals.md](docs/evals.md) — detection evaluation framework, adding test cases
-- [docs/calibration.md](docs/calibration.md) — SciLint Score calibration against ground-truth papers
+- [docs/evals.md](https://github.com/authentic-research-partners/sciwrite-lint/blob/main/docs/evals.md) — detection evaluation framework, adding test cases
+- [docs/calibration.md](https://github.com/authentic-research-partners/sciwrite-lint/blob/main/docs/calibration.md) — SciLint Score calibration against ground-truth papers
 
 ## License
 

{sciwrite_lint-0.2.0 → sciwrite_lint-0.2.1}/pyproject.toml

@@ -4,48 +4,54 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sciwrite-lint"
-version = "0.2.0"
+version = "0.2.1"
 description = "A linter for scientific manuscripts — reference verification, consistency checking, and structural validation."
 requires-python = ">=3.13,<3.14"
 license = "MIT"
 authors = [{ name = "Sergey Samsonau" }]
+maintainers = [{ name = "Authentic Research Partners LLC", email = "info@arpconnect.com" }]
 readme = "README.md"
-keywords = ["linter", "scientific-writing", "citation-verification", "latex"]
+keywords = ["linter", "latex", "bibtex", "pdf", "scientific-writing", "academic-writing", "citation-checker", "reference-verification", "claim-verification", "manuscript", "peer-review", "arxiv", "vllm", "qwen"]
 classifiers = [
     "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
     "Intended Audience :: Science/Research",
-    "Topic :: Text Processing :: Markup :: LaTeX",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Quality Assurance",
+    "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
 ]
 dependencies = [
-    "httpx>=0.27",
-    "tenacity>=8.0",
-    "trafilatura>=1.8",
-    "aiosqlite>=0.20",
+    "httpx>=0.28",
+    "tenacity>=9.0",
+    "trafilatura>=2.0",
+    "aiosqlite>=0.22",
     "loguru>=0.7",
     "anyascii>=0.3",
-    "rich>=13.0",
+    "rich>=14.0",
     "defusedxml>=0.7",
-    "pydantic>=2.0",
+    "pydantic>=2.10",
     "rapidfuzz>=3.0",
     "bibtexparser>=1.4",
-    "pdfplumber>=0.10",
-    "openai>=1.0",
+    "pdfplumber>=0.11",
+    "openai>=2.0",
     "grobid-tei-xml>=0.1",
-    "sentence-transformers>=3.0",
-    "numpy>=1.24",
+    "sentence-transformers>=5.0",
+    "numpy>=2.0",
     "sqlite-vec>=0.1.6",
-    "torch>=2.0",
-    "transformers>=4.45",
-    "Pillow>=10.0",
-    "pypdf>=4.0",
-    "pypdfium2>=4.0",
-    "pdf2image>=1.16",
+    "torch>=2.5",
+    "transformers>=4.50",
+    "Pillow>=12.0",
+    "pypdf>=6.0",
+    "pypdfium2>=5.0",
+    "pdf2image>=1.17",
 ]
 
 [project.urls]
-Homepage = "https://github.com/authentic-research-partners/sciwrite-lint"
+Homepage = "https://arpconnect.com"
 Repository = "https://github.com/authentic-research-partners/sciwrite-lint"
+Documentation = "https://github.com/authentic-research-partners/sciwrite-lint#readme"
 Issues = "https://github.com/authentic-research-partners/sciwrite-lint/issues"
 
 [project.optional-dependencies]

{sciwrite_lint-0.2.0 → sciwrite_lint-0.2.1}/sciwrite_lint/__init__.py

@@ -1,3 +1,3 @@
 """sciwrite-lint: a linter for scientific manuscripts."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"

{sciwrite_lint-0.2.0 → sciwrite_lint-0.2.1}/sciwrite_lint/__main__.py

@@ -18,6 +18,10 @@ from loguru import logger
 
 from sciwrite_lint import __version__
 from sciwrite_lint.config import LintConfig, PaperConfig, load_config
+from sciwrite_lint.vllm.vllm_server import MODELS as _VLLM_MODELS
+
+_ALL_MODELS = sorted(_VLLM_MODELS.keys())
+_TEXT_MODELS = [k for k, v in _VLLM_MODELS.items() if v["kind"] == "text"]
 
 
 # ---------------------------------------------------------------------------
@@ -179,6 +183,12 @@ def main(argv: list[str] | None = None) -> int:
         "limit. Above 4, the live monitor may fail to track progress and "
         "vLLM/API throughput plateaus.",
     )
+    p_check.add_argument(
+        "--vision-backend",
+        choices=["transformers", "vllm"],
+        default=None,
+        help="Vision backend: transformers (2B, default) or vllm (8B FP8 on port 5002)",
+    )
     p_check.set_defaults(func=run_check)
 
     # --- checks ---
@@ -296,7 +306,7 @@ def main(argv: list[str] | None = None) -> int:
     )
     p_vc.add_argument(
         "--model",
-        choices=["qwen3", "gemma3"],
+        choices=_TEXT_MODELS,
         default="",
         help="vLLM model preset (default: qwen3)",
     )
@@ -381,14 +391,20 @@ def main(argv: list[str] | None = None) -> int:
     # --- vision ---
     p_vision = sub.add_parser(
         "vision",
-        help="Extract and describe manuscript figures via Qwen3-VL-2B (also runs automatically in check pipeline).",
+        help="Extract and describe manuscript figures (transformers 2B or vLLM 8B FP8).",
     )
     p_vision.add_argument("--paper", required=True, help="Paper name from [[papers]]")
     p_vision.add_argument(
         "--device",
         choices=["auto", "cpu", "cuda"],
-        default="auto",
-        help="Device for VL inference (default: auto — CUDA if available)",
+        default=None,
+        help="Device for VL inference (default: auto — CUDA if available, transformers only)",
+    )
+    p_vision.add_argument(
+        "--backend",
+        choices=["transformers", "vllm"],
+        default=None,
+        help="Vision backend: transformers (2B, default) or vllm (8B FP8 on port 5002)",
     )
     p_vision.add_argument(
         "--fresh",
@@ -407,9 +423,7 @@ def main(argv: list[str] | None = None) -> int:
         choices=["start", "stop", "restart", "status", "monitor"],
         help="start/stop/restart/status/monitor of all containers",
     )
-    p_containers.add_argument(
-        "--model", choices=["qwen3", "gemma3"], help="vLLM model to use"
-    )
+    p_containers.add_argument("--model", choices=_ALL_MODELS, help="vLLM model to use")
     p_containers.add_argument(
         "--update",
         action="store_true",
@@ -427,6 +441,11 @@ def main(argv: list[str] | None = None) -> int:
         action="store_true",
         help="Remove and recreate containers (applies config changes like memory limits)",
     )
+    p_containers.add_argument(
+        "--vision",
+        action="store_true",
+        help="Also start vision vLLM (qwen3-vl-8b-fp8 on port 5002)",
+    )
     p_containers.add_argument("--config", help="Path to .sciwrite-lint.toml")
     p_containers.set_defaults(func=run_containers)
 
@@ -452,9 +471,7 @@ def main(argv: list[str] | None = None) -> int:
     p_vllm_status.set_defaults(func=run_vllm)
 
     p_vllm_start = vllm_sub.add_parser("start", help="Start vLLM server")
-    p_vllm_start.add_argument(
-        "--model", choices=["qwen3", "gemma3"], help="Model to serve"
-    )
+    p_vllm_start.add_argument("--model", choices=_ALL_MODELS, help="Model to serve")
     p_vllm_start.add_argument(
         "--update",
         action="store_true",
@@ -464,13 +481,11 @@ def main(argv: list[str] | None = None) -> int:
     p_vllm_start.set_defaults(func=run_vllm)
 
     p_vllm_stop = vllm_sub.add_parser("stop", help="Stop vLLM server")
-    p_vllm_stop.add_argument(
-        "--model", choices=["qwen3", "gemma3"], help="Model to stop"
-    )
+    p_vllm_stop.add_argument("--model", choices=_ALL_MODELS, help="Model to stop")
     p_vllm_stop.set_defaults(func=run_vllm)
 
     p_vllm_logs = vllm_sub.add_parser("logs", help="Show vLLM container logs")
-    p_vllm_logs.add_argument("--model", choices=["qwen3", "gemma3"])
+    p_vllm_logs.add_argument("--model", choices=_ALL_MODELS)
     p_vllm_logs.add_argument(
         "-f", "--follow", action="store_true", help="Follow log output"
     )
@@ -478,7 +493,7 @@ def main(argv: list[str] | None = None) -> int:
     p_vllm_logs.set_defaults(func=run_vllm)
 
     p_vllm_rm = vllm_sub.add_parser("rm", help="Remove vLLM container")
-    p_vllm_rm.add_argument("--model", choices=["qwen3", "gemma3"])
+    p_vllm_rm.add_argument("--model", choices=_ALL_MODELS)
     p_vllm_rm.add_argument(
         "--force", action="store_true", help="Force remove even if running"
     )

{sciwrite_lint-0.2.0 → sciwrite_lint-0.2.1}/sciwrite_lint/checks/cross_section_consistency.py

@@ -44,6 +44,9 @@ For each item, set is_genuine to true ONLY if the values or claims \
 CONFLICT. Set is_genuine to false if the passages agree or discuss \
 different topics.
 
+Report at most 4 contradictions. If you find more, return only the 4 \
+most clear-cut cases.
+
 Reply with JSON: {"contradictions": [\
 {"type": "number|claim|framing", "section_a_says": "...", \
 "section_b_says": "...", "explanation": "...", "is_genuine": true/false}]}

{sciwrite_lint-0.2.0 → sciwrite_lint-0.2.1}/sciwrite_lint/checks/full_paper_consistency.py

@@ -73,6 +73,8 @@ using established terminology loosely).
 - Set is_genuine to true ONLY for clear, unambiguous factual errors. \
 When in doubt, set is_genuine to false.
 - Prefer returning {{"issues": []}} over flagging borderline cases.
+- Report at most 5 issues. If you find more than 5 genuine issues, \
+return only the 5 most important ones.
 
 Return ONLY valid JSON: {{"issues": [{{"description": "...", "evidence": "...", \
 "location": "section or paragraph where the issue appears", \
@@ -93,12 +95,21 @@ Return {{"issues": []}} if no genuine issues found.\
 # question prompt) plus 2K safety padding for token estimation error.
 _OVERHEAD_TOKENS = 2500
 
-# Minimum output budget: enough for a few issues.
-_MIN_OUTPUT_TOKENS = 1024
+# Output budget reserved for the JSON response. Matches the vLLM model
+# default (VLLM_MODELS["qwen3"]["max_tokens"]). FullPaperIssueList caps
+# the issues list at 5, which fits comfortably in this budget.
+_OUTPUT_RESERVE_TOKENS = 2048
+
+# Worst-case thinking budget (medium preset, see THINKING_PRESETS).
+_THINKING_RESERVE_TOKENS = 1024
 
 # Rough chars-to-tokens ratio (conservative: overestimates tokens).
 _CHARS_PER_TOKEN = 3.5
 
+# Total tokens reserved for overhead + thinking + output. Whatever is left
+# in max_model_len is the budget for paper body + figure descriptions.
+_RESERVED_TOKENS = _OVERHEAD_TOKENS + _OUTPUT_RESERVE_TOKENS + _THINKING_RESERVE_TOKENS
+
 
 def _estimate_tokens(text: str) -> int:
     """Estimate token count from character length (conservative)."""
@@ -151,8 +162,10 @@ def _get_max_model_len(config: "LintConfig") -> int:
 def _get_paper_body(tex_path: Path, config: "LintConfig") -> tuple[str, int] | None:
     """Return (paper_body, token_estimate) or *None* if too large.
 
-    Checks the paper body against ``max_model_len`` minus fixed overhead,
-    ensuring enough room for thinking + output.
+    Checks the paper body against ``max_model_len`` minus the fixed reserve
+    for prompt overhead, thinking budget, and output. The output budget is
+    constant — large papers are rejected rather than squeezed into a smaller
+    output window, because findings scale with paper size.
     """
     from sciwrite_lint.manuscript_store import get_or_create_manuscript_context
 
@@ -165,7 +178,7 @@ def _get_paper_body(tex_path: Path, config: "LintConfig") -> tuple[str, int] | N
     body_tokens = _estimate_tokens(body)
 
     max_model_len = _get_max_model_len(config)
-    max_body_tokens = max_model_len - _OVERHEAD_TOKENS - _MIN_OUTPUT_TOKENS
+    max_body_tokens = max_model_len - _RESERVED_TOKENS
     if body_tokens > max_body_tokens:
         logger.info(
             "Paper body ~{}K tokens (limit ~{}K from max_model_len={}) "
@@ -180,21 +193,6 @@ def _get_paper_body(tex_path: Path, config: "LintConfig") -> tuple[str, int] | N
     return body, body_tokens
 
 
-def _compute_max_tokens(body_tokens: int, config: "LintConfig") -> int:
-    """Compute max_tokens for output based on remaining context budget.
-
-    ``max_tokens`` only caps the non-thinking output (JSON).  Thinking
-    budget is separate (set via ``extra_body.thinking.budget``).  We give
-    the output as much room as possible after the input fills the context.
-    """
-    max_model_len = _get_max_model_len(config)
-    # Available = total context - input (body + overhead) - thinking budget
-    # Thinking budget for medium=1024, low=200.  Use 1024 as worst case.
-    available = max_model_len - body_tokens - _OVERHEAD_TOKENS - 1024
-    # Clamp to reasonable range
-    return max(512, min(available, 4096))
-
-
 def _load_figure_descriptions(config: "LintConfig") -> str:
     """Load cached figure descriptions from the vision cache, if available."""
     if not config.current_paper:
@@ -213,11 +211,12 @@ def _build_system_prompt(
     tex_path: Path,
     config: "LintConfig",
     figure_descriptions: str = "",
-) -> tuple[str, int] | None:
+) -> str | None:
     """Build the shared system prompt with the full paper body.
 
-    Returns ``(system_prompt, max_tokens)`` or *None* if too large.
-    ``max_tokens`` is computed dynamically based on remaining context.
+    Returns the system prompt string, or *None* if the paper body plus
+    figure descriptions would overflow the context window after reserving
+    the constant output + thinking + overhead budget.
 
     If ``figure_descriptions`` is not provided, attempts to load them
     from the vision cache in the paper workspace.
@@ -237,7 +236,7 @@ def _build_system_prompt(
     total_input_tokens = body_tokens + fig_tokens
 
     max_model_len = _get_max_model_len(config)
-    max_input = max_model_len - _OVERHEAD_TOKENS - _MIN_OUTPUT_TOKENS
+    max_input = max_model_len - _RESERVED_TOKENS
     if total_input_tokens > max_input:
         logger.info(
             "Paper body + figures ~{}K tokens (limit ~{}K) — too large",
@@ -246,13 +245,10 @@ def _build_system_prompt(
         )
         return None
 
-    system = _SYSTEM_TEMPLATE.format(
+    return _SYSTEM_TEMPLATE.format(
         paper_body=body,
         figure_section=figure_section,
     )
-    max_tokens = _compute_max_tokens(total_input_tokens, config)
-
-    return system, max_tokens
 
 
 # ---------------------------------------------------------------------------
@@ -542,12 +538,10 @@ def _make_check_fns(
     def _build_queries(
         tex_path: Path, config: "LintConfig"
     ) -> list[tuple[str, str, dict, str]]:
-        result = _build_system_prompt(tex_path, config)
-        if result is None:
+        system = _build_system_prompt(tex_path, config)
+        if system is None:
             _build_queries._state = None  # type: ignore[attr-defined]
-            _build_queries._max_tokens = None  # type: ignore[attr-defined]
             return []
-        system, max_tokens = result
 
         # Skip figure checks when no figure descriptions are available
         if (
@@ -555,11 +549,9 @@ def _make_check_fns(
             and "Not available." in system.split("</figure_descriptions>")[0]
         ):
             _build_queries._state = None  # type: ignore[attr-defined]
-            _build_queries._max_tokens = None  # type: ignore[attr-defined]
             return []
 
         _build_queries._state = tex_path  # type: ignore[attr-defined]
-        _build_queries._max_tokens = max_tokens  # type: ignore[attr-defined]
         return [(system, question, _ISSUE_SCHEMA, "FullPaperIssue")]
 
     def _process_results(results: list[dict | None]) -> list[Finding]:

{sciwrite_lint-0.2.0 → sciwrite_lint-0.2.1}/sciwrite_lint/checks/ref_internal_checks.py

@@ -538,49 +538,24 @@ def _describe_cited_figures(
     Returns {ref_key: formatted_figure_descriptions}.
     """
     from sciwrite_lint.vision.cache import format_descriptions_from_db
-    from sciwrite_lint.vision.image_extraction import (
-        ExtractedImage,
-        extract_images_from_pdf,
-    )
-
-    # Collect images from all cited PDFs
-    all_images: list[ExtractedImage] = []
-    ref_image_ranges: dict[str, tuple[int, int]] = {}  # key → (start, end) index
-
-    output_dir = references_dir / "parsed" / "ref_figures"
-    output_dir.mkdir(parents=True, exist_ok=True)
-
-    for key in ref_keys:
-        # Find the PDF for this key (may have suffix like _core, _arxiv)
-        candidates = sorted(references_dir.glob(f"{key}*.pdf"))
-        if not candidates:
-            continue
-        pdf_path = candidates[0]
-
-        ref_output = output_dir / key
-        start = len(all_images)
-        images = extract_images_from_pdf(pdf_path, ref_output)
-        all_images.extend(images)
-        if images:
-            ref_image_ranges[key] = (start, len(all_images))
+    from sciwrite_lint.vision.image_extraction import collect_cited_images
 
+    all_images, ref_image_ranges = collect_cited_images(ref_keys, references_dir)
     if not all_images:
         return {}
 
-    # Run VL inference on all images at once (batched)
-    from sciwrite_lint.vision.describe import describe_figures
+    # Run VL inference per-ref so each gets tagged with its source key.
+    from sciwrite_lint.vision.describe import describe_figures_by_source
 
-    describe_figures(
-        all_images,
-        references_dir=references_dir,
-        fresh=fresh,
+    describe_figures_by_source(
+        all_images, ref_image_ranges, references_dir, fresh=fresh
     )
 
     # Build per-ref description strings
     result: dict[str, str] = {}
     for key, (start, end) in ref_image_ranges.items():
         ref_images = all_images[start:end]
-        desc = format_descriptions_from_db(ref_images, references_dir)
+        desc = format_descriptions_from_db(ref_images, references_dir, source=key)
         if desc:
             result[key] = desc
 
@@ -598,6 +573,9 @@ def _describe_cited_figures_vl(references_dir_str: str, fresh: bool = False) ->
 
     Extracts images, runs VL model, caches results in workspace.db.
     Called by _stage_cited_vision() in a subprocess for CUDA isolation.
+
+    Each ref's images are described separately so the cache entries get
+    tagged with the correct ``source=ref_key``.
     """
     from pathlib import Path
 
@@ -607,25 +585,14 @@ def _describe_cited_figures_vl(references_dir_str: str, fresh: bool = False) ->
     if not keys:
         return
 
-    from sciwrite_lint.vision.describe import describe_figures
-    from sciwrite_lint.vision.image_extraction import (
-        ExtractedImage,
-        extract_images_from_pdf,
-    )
-
-    all_images: list[ExtractedImage] = []
-    output_dir = references_dir / "parsed" / "ref_figures"
-    output_dir.mkdir(parents=True, exist_ok=True)
-
-    for key in keys:
-        candidates = sorted(references_dir.glob(f"{key}*.pdf"))
-        if not candidates:
-            continue
-        images = extract_images_from_pdf(candidates[0], output_dir / key)
-        all_images.extend(images)
+    from sciwrite_lint.vision.describe import describe_figures_by_source
+    from sciwrite_lint.vision.image_extraction import collect_cited_images
 
+    all_images, ref_image_ranges = collect_cited_images(keys, references_dir)
     if all_images:
-        describe_figures(all_images, references_dir=references_dir, fresh=fresh)
+        describe_figures_by_source(
+            all_images, ref_image_ranges, references_dir, fresh=fresh
+        )
 
 
 # ---------------------------------------------------------------------------