zipdf 0.1.0

Bundle diverse file types into a single, LLM-optimized PDF archive.

ZiPDF

Bundle diverse file types into a single, LLM-optimised PDF archive.

Quick Start

pip install -e .

# Bundle a folder into a PDF
zipdf ./my_project -o context.pdf

# Or use it in Python
from zipdf import ZiPDF
ZiPDF("context.pdf").add("./my_project").build()

That's it. Upload context.pdf to any LLM.

---

Why?

LLMs work best with a single, consolidated context. But real projects are spread across dozens of files — source code, configs, docs, data. Most chat interfaces only accept PDFs or have strict file-count limits.

ZiPDF solves this by zipping your project into one clean PDF that any LLM can parse: structured headers, a table of contents, and raw file content in a consistent format.

Install

From PyPI

pip install zipdf

From source

git clone https://github.com/josh-api/zipdf.git
cd zipdf

Create and activate a virtual environment:

# macOS / Linux
python -m venv .venv
source .venv/bin/activate

# Windows (CMD)
python -m venv .venv
.venv\Scripts\activate.bat

# Windows (PowerShell)
python -m venv .venv
.venv\Scripts\Activate.ps1

Then install:

pip install -e .

Use pip install -e ".[dev]" to also install development dependencies (pytest).

Usage

CLI

# Bundle an entire directory
zipdf ./my_project -o context.pdf

# Bundle specific files
zipdf main.py utils.py config.yaml -o context.pdf

# Custom exclusions (replaces defaults)
zipdf ./src --exclude "*.log" "tmp/" "*.pyc"

Library

from zipdf import ZiPDF

# Fluent API
ZiPDF("context.pdf").add("src/").add("README.md").build()

# Or step by step
archive = ZiPDF(output="out.pdf", exclude={"*.log", "node_modules"})
archive.add("app/")
archive.add("requirements.txt")
archive.build()

Extending with custom file handlers

from zipdf import register

@register(".csv")
def read_csv_pretty(path: str) -> str:
    """Custom handler that formats CSV nicely."""
    import csv
    with open(path) as f:
        reader = csv.reader(f)
        return "\n".join(",  ".join(row) for row in reader)

PDF Structure

Every generated PDF follows this layout:

1. System Prompt — Tells the LLM this is a multi-file archive.
2. Table of Contents — Lists every file with its page number.
3. File Sections — Each file on a new page:

   --- FILE: src/app.py ---
   [raw file content]
   --- END OF FILE ---
   

Default Exclusions

These patterns are excluded when scanning directories:

.git, __pycache__, .DS_Store, node_modules, .env, .venv, venv, *.pyc, *.pyo, *.egg-info, dist, build

Override with --exclude (CLI) or exclude= (library).

License

MIT