pdf-concatenator 1.0.0__tar.gz

pdf_concatenator-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lorenzo Wood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pdf_concatenator-1.0.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: pdf-concatenator
+Version: 1.0.0
+Summary: Concatenate PDFs with table of contents, cover pages, and optional LLM summaries
+Author: Lorenzo Wood
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/lorenzowood/pdf-concatenator
+Project-URL: Repository, https://github.com/lorenzowood/pdf-concatenator
+Project-URL: Issues, https://github.com/lorenzowood/pdf-concatenator/issues
+Keywords: pdf,concatenate,merge,toc,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: pypdf>=4.0
+Requires-Dist: reportlab>=4.0
+Requires-Dist: tqdm>=4.66
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# pdf-concatenator
+
+Bundle many PDFs into a single submission-ready document.
+
+This tool was built to pull together a large set of PDFs for a **contract submission**: one combined file with a table of contents, cover pages, and optional short summaries so reviewers can navigate the bundle easily.
+
+## Features
+
+- Recursively discover PDFs from a directory or glob pattern
+- Sort files by path and concatenate them into one output PDF
+- Generate a **table of contents** with folder structure, page numbers, and alternating row shading
+- Insert a **cover page** before each source PDF (path, optional summary, page number)
+- Optionally generate **LLM summaries** via a sidecar file per PDF (`*.pdf.sidecar.json`)
+- Regenerate sidecars without concatenating (`--regenerate-summaries`)
+- Exclude specific files or patterns (`--exclude`)
+- Progress bar while summaries are processed
+
+## Installation
+
+With [pipx](https://pipx.pypa.io/) (recommended):
+
+```bash
+pipx install pdf-concatenator
+```
+
+With pip:
+
+```bash
+pip install pdf-concatenator
+```
+
+For development:
+
+```bash
+git clone https://github.com/lorenzowood/pdf-concatenator.git
+cd pdf-concatenator
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+Concatenate all PDFs under a folder:
+
+```bash
+pdf-concatenator -o submission.pdf contracts/
+```
+
+With summaries (requires LLM config — see below):
+
+```bash
+pdf-concatenator -o submission.pdf --include-summaries contracts/
+```
+
+Regenerate sidecar summaries only:
+
+```bash
+pdf-concatenator --regenerate-summaries contracts/
+```
+
+Exclude files:
+
+```bash
+pdf-concatenator -o submission.pdf \
+  --exclude "drafts/*" \
+  --exclude "broken.pdf" \
+  contracts/
+```
+
+Patterns can be a directory (all PDFs beneath it) or a glob, e.g. `contracts/**/*.pdf`.
+
+## LLM configuration
+
+When using `--include-summaries` or `--regenerate-summaries`, create `~/.config/pdf-concatenator`:
+
+```ini
+LLM_API=open_ai
+LLM_SERVER=127.0.0.1:28911
+LLM_API_KEY=your-api-key
+LLM_MODEL=your-model-id
+LLM_PROMPT_TITLE_AND_SUMMARY=Your prompt here
+```
+
+The server should expose an OpenAI-compatible `/v1/chat/completions` endpoint. The whole PDF is sent to the model. If the prompt key is missing but everything else is valid, a default prompt is written to the config file.
+
+Summaries are stored beside each PDF as `document.pdf.sidecar.json` and reused when the file hash matches.
+
+## Output structure
+
+1. **Contents** — tree of folders and files; page numbers point to each document's cover page. When summaries are included, a disclaimer appears in the footer.
+2. **Cover page** per PDF — relative path, optional summary, page number.
+3. **Original PDF pages** — unchanged (no added page numbers).
+
+If any PDF cannot be read, or summary generation fails when required, the run aborts and no output file is produced.
+
+## Options
+
+```
+usage: pdf-concatenator [-h] [-o filename] [--include-summaries]
+                        [--regenerate-summaries] [--exclude pattern]
+                        [--config CONFIG] [--verbose]
+                        pattern
+```
+
+| Option | Description |
+|--------|-------------|
+| `-o`, `--output` | Output PDF path (required unless `--regenerate-summaries`) |
+| `--include-summaries` | Include summaries in contents and cover pages |
+| `--regenerate-summaries` | Regenerate sidecar files only; do not concatenate |
+| `--exclude` | Glob pattern to exclude (repeatable) |
+| `--config` | Path to LLM config (default: `~/.config/pdf-concatenator`) |
+| `--verbose` | Show library warnings while reading/merging PDFs |
+
+## Development
+
+```bash
+pytest
+```
+
+## License
+
+MIT

pdf_concatenator-1.0.0/README.md

@@ -0,0 +1,123 @@
+# pdf-concatenator
+
+Bundle many PDFs into a single submission-ready document.
+
+This tool was built to pull together a large set of PDFs for a **contract submission**: one combined file with a table of contents, cover pages, and optional short summaries so reviewers can navigate the bundle easily.
+
+## Features
+
+- Recursively discover PDFs from a directory or glob pattern
+- Sort files by path and concatenate them into one output PDF
+- Generate a **table of contents** with folder structure, page numbers, and alternating row shading
+- Insert a **cover page** before each source PDF (path, optional summary, page number)
+- Optionally generate **LLM summaries** via a sidecar file per PDF (`*.pdf.sidecar.json`)
+- Regenerate sidecars without concatenating (`--regenerate-summaries`)
+- Exclude specific files or patterns (`--exclude`)
+- Progress bar while summaries are processed
+
+## Installation
+
+With [pipx](https://pipx.pypa.io/) (recommended):
+
+```bash
+pipx install pdf-concatenator
+```
+
+With pip:
+
+```bash
+pip install pdf-concatenator
+```
+
+For development:
+
+```bash
+git clone https://github.com/lorenzowood/pdf-concatenator.git
+cd pdf-concatenator
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+Concatenate all PDFs under a folder:
+
+```bash
+pdf-concatenator -o submission.pdf contracts/
+```
+
+With summaries (requires LLM config — see below):
+
+```bash
+pdf-concatenator -o submission.pdf --include-summaries contracts/
+```
+
+Regenerate sidecar summaries only:
+
+```bash
+pdf-concatenator --regenerate-summaries contracts/
+```
+
+Exclude files:
+
+```bash
+pdf-concatenator -o submission.pdf \
+  --exclude "drafts/*" \
+  --exclude "broken.pdf" \
+  contracts/
+```
+
+Patterns can be a directory (all PDFs beneath it) or a glob, e.g. `contracts/**/*.pdf`.
+
+## LLM configuration
+
+When using `--include-summaries` or `--regenerate-summaries`, create `~/.config/pdf-concatenator`:
+
+```ini
+LLM_API=open_ai
+LLM_SERVER=127.0.0.1:28911
+LLM_API_KEY=your-api-key
+LLM_MODEL=your-model-id
+LLM_PROMPT_TITLE_AND_SUMMARY=Your prompt here
+```
+
+The server should expose an OpenAI-compatible `/v1/chat/completions` endpoint. The whole PDF is sent to the model. If the prompt key is missing but everything else is valid, a default prompt is written to the config file.
+
+Summaries are stored beside each PDF as `document.pdf.sidecar.json` and reused when the file hash matches.
+
+## Output structure
+
+1. **Contents** — tree of folders and files; page numbers point to each document's cover page. When summaries are included, a disclaimer appears in the footer.
+2. **Cover page** per PDF — relative path, optional summary, page number.
+3. **Original PDF pages** — unchanged (no added page numbers).
+
+If any PDF cannot be read, or summary generation fails when required, the run aborts and no output file is produced.
+
+## Options
+
+```
+usage: pdf-concatenator [-h] [-o filename] [--include-summaries]
+                        [--regenerate-summaries] [--exclude pattern]
+                        [--config CONFIG] [--verbose]
+                        pattern
+```
+
+| Option | Description |
+|--------|-------------|
+| `-o`, `--output` | Output PDF path (required unless `--regenerate-summaries`) |
+| `--include-summaries` | Include summaries in contents and cover pages |
+| `--regenerate-summaries` | Regenerate sidecar files only; do not concatenate |
+| `--exclude` | Glob pattern to exclude (repeatable) |
+| `--config` | Path to LLM config (default: `~/.config/pdf-concatenator`) |
+| `--verbose` | Show library warnings while reading/merging PDFs |
+
+## Development
+
+```bash
+pytest
+```
+
+## License
+
+MIT

pdf_concatenator-1.0.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "pdf-concatenator"
+version = "1.0.0"
+description = "Concatenate PDFs with table of contents, cover pages, and optional LLM summaries"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Lorenzo Wood" }]
+keywords = ["pdf", "concatenate", "merge", "toc", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pypdf>=4.0",
+    "reportlab>=4.0",
+    "tqdm>=4.66",
+]
+
+[project.urls]
+Homepage = "https://github.com/lorenzowood/pdf-concatenator"
+Repository = "https://github.com/lorenzowood/pdf-concatenator"
+Issues = "https://github.com/lorenzowood/pdf-concatenator/issues"
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.0",
+    "pytest>=8.0",
+    "pytest-mock>=3.12",
+    "twine>=5.0",
+]
+
+[project.scripts]
+pdf-concatenator = "pdf_concatenator.cli:main"
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pdf_concatenator-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pdf_concatenator-1.0.0/src/pdf_concatenator/__init__.py

@@ -0,0 +1,3 @@
+"""PDF concatenator with TOC, cover pages, and optional LLM summaries."""
+
+__version__ = "1.0.0"

pdf_concatenator-1.0.0/src/pdf_concatenator/cli.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from pdf_concatenator.config import ConfigError, DEFAULT_CONFIG_PATH
+from pdf_concatenator.discovery import DiscoveredPdf, discover_pdfs
+from pdf_concatenator.llm import LlmError
+from pdf_concatenator.pdf_build import DocumentInfo, PdfBuildError, build_concatenated_pdf
+from pdf_concatenator.summaries import load_llm_config, resolve_sidecar
+from tqdm import tqdm
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pdf-concatenator",
+        description="Concatenate PDFs with a table of contents and optional summaries.",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        metavar="filename",
+        help="Output PDF filename (required unless --regenerate-summaries)",
+    )
+    parser.add_argument(
+        "--include-summaries",
+        action="store_true",
+        help="Include summaries in the table of contents and cover pages",
+    )
+    parser.add_argument(
+        "--regenerate-summaries",
+        action="store_true",
+        help="Regenerate sidecar summary files only; do not concatenate",
+    )
+    parser.add_argument(
+        "--exclude",
+        action="append",
+        default=[],
+        metavar="pattern",
+        help="Exclude files matching pattern (may be repeated)",
+    )
+    parser.add_argument(
+        "--config",
+        default=str(DEFAULT_CONFIG_PATH),
+        help="Path to LLM config file",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Show library warnings while reading and merging PDFs",
+    )
+    parser.add_argument("pattern", help="Directory or glob pattern for PDF files")
+    return parser
+
+
+def _configure_logging(verbose: bool) -> None:
+    level = logging.WARNING if verbose else logging.ERROR
+    logging.getLogger("pypdf").setLevel(level)
+
+
+def _summary_progress(
+    pdfs: list[DiscoveredPdf],
+    *,
+    disable: bool | None = None,
+):
+    if disable is None:
+        disable = not sys.stderr.isatty()
+    return tqdm(
+        pdfs,
+        desc="Summaries",
+        unit="pdf",
+        total=len(pdfs),
+        disable=disable,
+        file=sys.stderr,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exc:
+        code = exc.code
+        return int(code) if isinstance(code, int) else 1
+
+    _configure_logging(args.verbose)
+
+    if args.regenerate_summaries:
+        if args.output:
+            print(
+                "error: --output cannot be used with --regenerate-summaries",
+                file=sys.stderr,
+            )
+            return 2
+        return _regenerate_summaries(args)
+
+    if not args.output:
+        print(
+            "error: the following arguments are required: -o/--output",
+            file=sys.stderr,
+        )
+        return 2
+
+    return _concatenate(args)
+
+
+def _discover(args: argparse.Namespace):
+    pdfs = discover_pdfs(args.pattern, excludes=args.exclude)
+    if not pdfs:
+        print("No PDF files matched pattern.", file=sys.stderr)
+        return None
+    return pdfs
+
+
+def _regenerate_summaries(args: argparse.Namespace) -> int:
+    pdfs = _discover(args)
+    if pdfs is None:
+        return 1
+
+    try:
+        config = load_llm_config(Path(args.config))
+    except ConfigError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    for pdf in _summary_progress(pdfs):
+        try:
+            resolve_sidecar(pdf.path, config, force=True)
+        except LlmError as exc:
+            print(str(exc), file=sys.stderr)
+            return 1
+
+    return 0
+
+
+def _concatenate(args: argparse.Namespace) -> int:
+    pdfs = _discover(args)
+    if pdfs is None:
+        return 1
+
+    output_path = Path(args.output)
+    config = None
+    if args.include_summaries:
+        try:
+            config = load_llm_config(Path(args.config))
+        except ConfigError as exc:
+            print(str(exc), file=sys.stderr)
+            return 1
+
+    documents: list[DocumentInfo] = []
+    summary_pdfs = pdfs if args.include_summaries else []
+    for pdf in _summary_progress(summary_pdfs) if summary_pdfs else pdfs:
+        summary: str | None = None
+        title = pdf.path.stem
+        if args.include_summaries:
+            assert config is not None
+            try:
+                sidecar = resolve_sidecar(pdf.path, config, force=False)
+            except LlmError as exc:
+                print(str(exc), file=sys.stderr)
+                return 1
+            summary = sidecar.summary
+            title = sidecar.title
+
+        documents.append(
+            DocumentInfo(
+                path=pdf.path,
+                relative_path=pdf.relative_path,
+                title=title,
+                summary=summary,
+            )
+        )
+
+    try:
+        build_concatenated_pdf(
+            documents,
+            output_path,
+            include_summaries=args.include_summaries,
+        )
+    except PdfBuildError as exc:
+        print(str(exc), file=sys.stderr)
+        if output_path.exists():
+            output_path.unlink()
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pdf_concatenator-1.0.0/src/pdf_concatenator/config.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_CONFIG_PATH = Path.home() / ".config" / "pdf-concatenator"
+
+DEFAULT_PROMPT = (
+    "You are summarising a PDF document. Given the filename, metadata, and PDF "
+    "below, produce a concise title and a summary under 100 words (ideally one "
+    "sentence, but use more only if needed). Respond with JSON only: "
+    '{"title": "...", "summary": "..."}'
+)
+
+REQUIRED_KEYS = ("LLM_API", "LLM_SERVER", "LLM_API_KEY", "LLM_MODEL")
+
+
+class ConfigError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class LlmConfig:
+    api: str
+    server: str
+    api_key: str
+    model: str
+    prompt: str
+
+
+def _parse_config_text(text: str) -> dict[str, str]:
+    values: dict[str, str] = {}
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        values[key.strip()] = value.strip()
+    return values
+
+
+def load_config(path: Path = DEFAULT_CONFIG_PATH) -> LlmConfig:
+    if not path.exists():
+        raise ConfigError(f"Config file not found: {path}")
+
+    values = _parse_config_text(path.read_text())
+    for key in REQUIRED_KEYS:
+        if key not in values or not values[key]:
+            raise ConfigError(f"Missing required config key: {key}")
+
+    return LlmConfig(
+        api=values["LLM_API"],
+        server=values["LLM_SERVER"],
+        api_key=values["LLM_API_KEY"],
+        model=values["LLM_MODEL"],
+        prompt=values.get("LLM_PROMPT_TITLE_AND_SUMMARY", ""),
+    )
+
+
+def ensure_prompt(config: LlmConfig, path: Path = DEFAULT_CONFIG_PATH) -> LlmConfig:
+    if config.prompt:
+        return config
+    try:
+        existing = path.read_text()
+        if existing and not existing.endswith("\n"):
+            existing += "\n"
+        path.write_text(
+            existing + f"LLM_PROMPT_TITLE_AND_SUMMARY={DEFAULT_PROMPT}\n"
+        )
+    except OSError as exc:
+        raise ConfigError(f"Failed to write default prompt to config: {exc}") from exc
+    return LlmConfig(
+        api=config.api,
+        server=config.server,
+        api_key=config.api_key,
+        model=config.model,
+        prompt=DEFAULT_PROMPT,
+    )