Metadata-Version: 2.3
Name: paper2kindle
Version: 0.1.2
Summary: Convert arXiv and SSRN papers to reflowable EPUBs and send them to Kindle
Author: Markos Narinian
Author-email: Markos Narinian <manarinian@gmail.com>
Requires-Dist: docling>=2.118.0
Requires-Dist: email-validator>=2.3.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: keyring>=25.7.0
Requires-Dist: lxml>=6.1.1
Requires-Dist: pillow>=12.3.0
Requires-Dist: platformdirs>=4.11.0
Requires-Dist: pydantic-settings>=2.15.0
Requires-Dist: tomlkit>=0.15.1
Requires-Dist: typer>=0.26.8
Requires-Dist: resend>=2.35.0 ; extra == 'resend'
Requires-Python: >=3.12
Provides-Extra: resend
Description-Content-Type: text/markdown

# paper2kindle

Convert arXiv and SSRN papers into reflowable EPUB 3 documents and send them to
Kindle.

The CLI is available as both `paper2kindle` and `p2k`.

## Install

Install the published package from
[PyPI](https://pypi.org/project/paper2kindle/) with
[uv](https://docs.astral.sh/uv/getting-started/installation/):

```console
uv tool install paper2kindle@latest
paper2kindle --version
p2k --help
```

To use optional Resend delivery, install the `resend` extra:

```console
uv tool install 'paper2kindle[resend]@latest'
```

Upgrade an existing installation with `uv tool upgrade paper2kindle`.

EPUB conversion also requires the official external tools
[Pandoc](https://pandoc.org/installing.html),
[EPUBCheck](https://github.com/w3c/epubcheck/releases). The setup wizard checks
for both. Paper conversion runs locally; Docling may download its maintained
models on first use.

## Quick start

Run the first-time setup wizard, verify the configuration, then send a paper:

```console
paper2kindle setup
paper2kindle doctor
p2k send 2401.12345
```

## Setup and delivery

The interactive wizard configures your Kindle address and email delivery and is
safe to rerun. To configure or inspect only one area, use one of the mutually
exclusive scoped flags:

```console
paper2kindle setup --kindle
paper2kindle setup --email
paper2kindle setup --tools
paper2kindle setup --storage
```

SMTP is the default. Setup records the host, port, STARTTLS or SSL mode,
username, and sender; its password/token is stored in the OS keychain. Add that
exact sender to Amazon's Approved Personal Document E-mail List. Credentials
can instead be supplied with `PAPER2KINDLE_SMTP_PASSWORD`.

Resend is optional and requires a user-owned, Resend-verified sending domain:

```console
paper2kindle setup --email  # choose resend
```

Its API key is stored in the keychain or read from
`PAPER2KINDLE_RESEND_API_KEY`. Each user must provide their own key. Attachments
over 29 MiB are rejected before contacting Resend.

Send EPUB by default, or explicitly request PDF. The document is temporary
after a successful send unless retained with `--keep` or `--output`:

```console
paper2kindle send 2401.12345
p2k send 2401.12345 --delivery resend --keep
p2k send ssrn:1234567 --format pdf --output paper.pdf
p2k send 2401.12345 --dry-run
```

`--delivery` is a one-command override and does not alter saved configuration.
Dry runs prepare and retain the file without loading credentials or sending.

## Supported sources

| Source | Accepted input                                             |
| ------ | ---------------------------------------------------------- |
| arXiv  | Modern or legacy ID, `arXiv:` ID, abstract URL, or PDF URL |
| SSRN   | `ssrn:<id>`, numeric abstract ID, or canonical paper URL   |

Only publicly accessible papers are supported. paper2kindle does not bypass
authentication, paywalls, or source access controls.

## Inspect and prepare

Inspecting only performs metadata requests; it does not download or convert the
paper:

```console
paper2kindle inspect 2401.12345
p2k inspect https://arxiv.org/pdf/hep-th/9901001.pdf
p2k inspect ssrn:1234567
```

EPUB 3 is the default and is never silently changed to PDF:

```console
paper2kindle prepare 2401.12345
paper2kindle prepare ssrn:1234567 --output paper.epub
paper2kindle prepare 2401.12345 --format pdf --output paper.pdf
paper2kindle prepare 2401.12345 --strict --debug-artifacts ./debug
```

EPUB preparation requires `pandoc` and `epubcheck`. For arXiv, paper2kindle uses
arXiv's official accessible HTML when available; otherwise it uses the published
PDF with Docling while still producing EPUB. It never executes downloaded TeX.
SSRN uses only publicly advertised PDF links on approved SSRN hosts and does not
bypass access controls. Docling is installed as a Python dependency and may
download its models on first use. `--strict` rejects source-fallback warnings,
and `--debug-artifacts` retains conversion intermediates for diagnosis.

The converter checks output for missing structure and assets, fragmented text,
unresolved LaTeX, degraded equations, encoding replacement characters, and a
missing references section. Severe truncation always stops conversion;
`--strict` also stops on quality warnings.

## Security and privacy

- Downloads require HTTPS and are restricted to approved arXiv or SSRN hosts.
- Redirects, metadata, PDFs, and image assets are bounded and validated.
- Downloaded TeX is never executed. arXiv's official accessible HTML is used
  when available, with Docling PDF extraction as the EPUB fallback.
- Active HTML and SVG content is removed; raster figures are decoded,
  re-encoded, and embedded before Pandoc runs in sandbox mode.
- SMTP passwords and Resend API keys are stored in the OS keychain or supplied
  through environment variables. They are not written to the config file.
- The application does not collect telemetry.

PDF parsing and document conversion still process untrusted documents through
third-party libraries. Run the CLI with the same care as other local document
conversion software.

## Development

Python 3.12+ and uv are required:

```console
git clone https://github.com/markosnarinian/paper2kindle.git
cd paper2kindle
uv sync --all-extras
uv run pytest
uv run ruff check .
uv run pyright
uv build
```

The architecture and implementation roadmap are documented in
[PLAN.md](PLAN.md).
