Metadata-Version: 2.4
Name: read_pdf_tool
Version: 0.2.1
Summary: Convert PDFs to Markdown with Mistral OCR or Azure Document Intelligence
Project-URL: Homepage, https://pypi.org/project/read_pdf_tool/
Project-URL: Documentation, https://pypi.org/project/read_pdf_tool/
Keywords: azure,document-intelligence,markdown,mistral,ocr,pdf
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.10
Requires-Dist: azure-ai-documentintelligence>=1.0.0
Requires-Dist: azure-core>=1.30.0
Requires-Dist: azure-identity>=1.17.0
Requires-Dist: mistralai>=2.3.1
Requires-Dist: pillow>=10.0.0
Requires-Dist: pypdfium2>=4.30.0
Description-Content-Type: text/markdown

# read_pdf_tool

Turn a PDF into clean Markdown plus one PNG snapshot per page.

Mistral OCR is the default. Azure Document Intelligence is available as an
optional provider.

## Quick start

You need [uv](https://docs.astral.sh/uv/) and a Mistral API key.

### 1. Install the command

```sh
uv tool install read_pdf_tool
```

This installs both `read_pdf` and `read_pdf_tool`. The shorter `read_pdf`
command is used below.

### 2. Save your API key

```sh
read_pdf setup --interactive
```

The prompt looks like this:

```console
$ read_pdf setup --interactive
read_pdf_tool setup

Mistral OCR configuration
Credentials will be stored in /home/you/.read_pdf/.env (mode 600).

Mistral API key (hidden):

Configuration saved.
  File: /home/you/.read_pdf/.env
  Provider: Mistral OCR
  Model: mistral-ocr-latest
```

The key is hidden while you type and stored locally in a private file.

### 3. Read a PDF

```sh
read_pdf path/to/document.pdf
```

The command prints the output paths when it finishes. Open `pages.md` for the
extracted text and the `page_N.png` files to visually check each page.

## Run without installing

Use the PyPI package name as the command:

```sh
uvx read_pdf_tool path/to/document.pdf
```

To use the shorter command through `uvx`:

```sh
uvx --from read_pdf_tool read_pdf path/to/document.pdf
```

## Non-interactive setup

Useful for servers and automation:

```sh
export MISTRAL_API_KEY="..."
read_pdf setup --non-interactive
```

You can also leave the key in the environment and skip setup entirely:

```sh
MISTRAL_API_KEY="..." uvx read_pdf_tool document.pdf
```

Existing configuration is never overwritten silently. Use `--force` when an
intentional replacement is needed.

## Output files

A default Mistral run creates a timestamped directory under
`~/.read_pdf/conversions/`:

```text
~/.read_pdf/conversions/20260722T101624Z_document_ab12cd34/
├── pages.md       # all pages, wrapped with page boundaries
├── document.md    # combined OCR Markdown
├── page_1.md      # OCR text for page 1
├── page_1.png     # rendered snapshot for visual verification
├── response.json  # complete provider response
└── metadata.json  # paths, provider, model, and page counts
```

The terminal summary contains the exact directory and file paths. Use `--json`
when another program needs to consume that summary.

## Common commands

```sh
# Write a copy of the merged Markdown to a specific path
read_pdf document.pdf --output /tmp/document.md

# Process only pages 4 and 5
read_pdf document.pdf --start-page 4 --max-pages 2

# Skip local PNG rendering
read_pdf document.pdf --no-images

# Print machine-readable result metadata
read_pdf document.pdf --json

# See every option
read_pdf --help
```

## Agent usage

The intended default workflow is:

1. Run `read_pdf <path>`.
2. Read the `pages_md` path from the terminal summary.
3. Inspect every returned `page_N.png` snapshot unless the user says visual
   verification is unnecessary.

If `read_pdf` fails, `uvx markitdown <path>` can be used as a text-only
fallback. Make it clear that the fallback may produce lower-quality output.

## Azure Document Intelligence

Mistral is the default. To configure Azure instead:

```sh
export AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT="https://example.cognitiveservices.azure.com/"
export AZURE_API_KEY="..."
read_pdf setup --non-interactive --provider azure
```

For a one-off Azure run:

```sh
read_pdf document.pdf --provider azure
```

Azure defaults to the `prebuilt-layout` model and can use
`DefaultAzureCredential` when no API key is supplied.

## Configuration

The default configuration file is `~/.read_pdf/.env` and is created with mode
`600`.

| Variable | Purpose | Default |
| --- | --- | --- |
| `READ_PDF_PROVIDER` | `mistral` or `azure` | `mistral` |
| `MISTRAL_API_KEY` | Mistral API credential | required for Mistral |
| `MISTRAL_OCR_MODEL` | Mistral OCR model | `mistral-ocr-latest` |
| `AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT` | Azure service endpoint | required for Azure |
| `AZURE_API_KEY` | Azure credential | optional with `DefaultAzureCredential` |

Environment variables take precedence over values loaded from the config file.

## Cost and privacy

PDF contents are sent to the selected OCR provider. Do not process documents
that you are not allowed to share with that provider.

Mistral OCR is usage-priced, not generally free. Check the
[current Mistral API pricing](https://mistral.ai/pricing/api/) before use.

## Troubleshooting

**`Missing Mistral API key`**

Run `read_pdf setup --interactive`, or export `MISTRAL_API_KEY`.

**The wrong provider is selected**

Pass `--provider mistral` or `--provider azure`, or update
`READ_PDF_PROVIDER` in `~/.read_pdf/.env`.

**Start over with setup**

```sh
read_pdf setup --interactive --force
```

## Development

```sh
From a local checkout:

uv sync
uv run pytest
uv run read_pdf --help
uv build
```

Test the package through its real entry point before publishing:

```sh
uvx --from . read_pdf --help
```
