Metadata-Version: 2.4
Name: zipdf
Version: 0.1.0
Summary: Bundle diverse file types into a single, LLM-optimized PDF archive.
Author: Joshua Cortez
License-Expression: MIT
License-File: LICENSE
Keywords: archive,bundler,context,llm,pdf
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: fpdf2>=2.8
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# ZiPDF

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

## Quick Start

```bash
pip install -e .
```

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

```python
# 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

```bash
pip install zipdf
```

### From source

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

Create and activate a virtual environment:

```bash
# 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:

```bash
pip install -e .
```

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

## Usage

### CLI

```bash
# 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

```python
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

```python
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
