Metadata-Version: 2.4
Name: paperlypdf
Version: 0.4.0
Summary: Python client for Paperly — turn prompts or CSV/Excel files into polished, downloadable PDF reports.
License: MIT
Project-URL: Homepage, https://saas-pdf-kappa.vercel.app
Keywords: pdf,report,ai,generator,document,paperly
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Office/Business
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25

# Paperly Python SDK

Turn a prompt — or a CSV/Excel file — into a polished, downloadable **PDF report**
in a few lines of Python. The AI builds a designed, multi-page document
(table of contents, tables, summary section) and renders it to PDF — no manual
formatting.

```bash
pip install paperlypdf
```

## Quickstart

```python
from paperlypdf import PaperlyPdf

client = PaperlyPdf(api_key="pdf_YOUR_API_KEY")

pdf = client.generate_to_pdf(
    "Write a quarterly sales analysis for Q2 2026.",
    length="standard",          # concise | standard | in-depth
    output_path="report.pdf",
)
```

That's it — submit, poll, download. `report.pdf` lands on disk.

## Data file → PDF report (the killer use case)

```python
import csv
import io
from paperlypdf import PaperlyPdf

client = PaperlyPdf(api_key="pdf_YOUR_API_KEY")

def csv_as_text(path):
    with open(path, encoding="utf-8-sig") as f:
        rows = list(csv.DictReader(f))
    out = io.StringIO()
    out.write(f"Source: {path} ({len(rows)} rows)\n\n")
    for row in rows:
        out.write(" | ".join(f"{k}: {v}" for k, v in row.items()))
        out.write("\n")
    return out.getvalue()

client.generate_to_pdf(
    "Organize this data into a clean business report with tables, "
    "then add an analysis section with concrete recommendations.",
    file_text=csv_as_text("sales.csv"),
    length="standard",
    output_path="sales_report.pdf",
)
```

For Excel (`.xlsx`) use pandas to read and pass a text representation the same way:

```python
import pandas as pd
client.generate_to_pdf("Summarize this into a clean report.", file_text=pd.read_excel("orders.xlsx").to_string())
```

## Low-level API

| Method | Purpose |
|---|---|
| `generate(prompt, length, mode, file_text, plain, clarify, answers, web_search, images)` | Submit a job — returns `jobId` |
| `get_job(job_id)` | Poll status: `pending` / `running` / `done` / `failed` |
| `wait(job_id)` | Block until `done` (raises on `failed` or timeout) |
| `download(job_id, output_path)` | Fetch the finished PDF (bytes) |
| `generate_to_pdf(...)` | All of the above in one call |
| `generate_from_text_file(path, prompt, ...)` | Read a text/CSV file locally and generate a PDF from it |
| `generate_from_image_file(path, prompt, ...)` | Read a local image — AI vision analyzes it, then generate a PDF |
| `me()` | API-key info: balance, usage, caps |

### Handling clarifying questions

Pass `clarify=True` and the API may ask questions first:

```python
res = client.generate("I need a document about ice cream.", clarify=True)
if res.get("needsInput"):
    print(res["questions"])   # -> ask the user, then retry with answers:
    res = client.generate("I need a document about ice cream.",
                          clarify=True,
                          answers=["Tutorial", "Beginner home cooks", "3 sections"])
job = client.wait(res["jobId"])
client.download(job["jobId"], "out.pdf")
```

### Live web search (B2B plans)

Pass `web_search=True` to let the AI fetch a few live web pages it proposes and
fold their text into the document, so it can use current facts (prices, news,
figures). Adds a small per-job surcharge:

```python
client.generate_to_pdf(
    "Write a market brief on specialty coffee wholesale pricing in 2026.",
    length="standard",
    web_search=True,
    output_path="market-brief.pdf",
)
```

### Plain document mode

Pass `plain=True` to any generation call for a clean, Word-style document with
minimal visual styling — the PDF reads as hand-written rather than AI-designed,
the file is smaller, and generation is faster and cheaper. Content stays just as
complete:

```python
client.generate_to_pdf(
    "A one-page project status memo.",
    length="concise",
    plain=True,
    output_path="memo.pdf",
)
```

### Image → PDF (vision)

Pass one or more images (base64, or a `data:image/...;base64,...` URL). An AI
vision model describes each one and the descriptions fold into the document
context, so photos, sketches, or screenshots become part of the report. Billed
through the file-character surcharge; no vision call runs unless you send images.

```python
client.generate_to_pdf(
    "Describe what this image shows and turn it into a clean document.",
    images=[{"name": "sketch.png", "data": "<base64>"}],
    output_path="from-image.pdf",
)
```

Shortcut — read a local image file directly:

```python
client.generate_from_image_file("photo.png", output_path="from-image.pdf")
```

## Errors

Non-2xx responses raise `PaperlyError` with the server's error message. Failed
jobs raise `PaperlyError` too. Jobs expire after 30 minutes.

## Pricing

Prepaid, pay-as-you-go: `concise` $0.30 · `standard` $0.30 · `in-depth` $1.00,
plus $0.10 per 100K characters of file data. No subscription.
