@qvac/skills 0.0.0 → 0.1.0

package/skills/pdf/references/create.md

@@ -0,0 +1,169 @@
+# Creating a PDF (fpdf2)
+
+Create a new `.pdf` from scratch by running Python through the `exec` tool.
+A new PDF needs **no** `inputs` — do not invent attachment ids. **Exactly one**
+`exec` call per user request when that call succeeds.
+
+This file is also the recipe for **changing the content of an existing PDF**
+(add a paragraph, reword, restyle): pypdf cannot edit page content, so the job
+is writing the whole document again with fpdf2 — every original section,
+reproduced unchanged, plus the requested change. A rebuild that condenses,
+summarizes, or drops original sections is a failed turn; the user must get
+their document back with only the asked-for difference. Save the rebuild under
+a **new** output name (`updated.pdf`, never the original file's name), and
+stop after the one successful build.
+
+## The exec call
+
+```json
+{
+  "language": "python",
+  "packages": ["fpdf2==2.8.8"],
+  "outputs": ["report.pdf"],
+  "command": "..."
+}
+```
+
+- `packages` — pin exactly `fpdf2==2.8.8` (imported as `fpdf`). This version
+  ships with the app and installs with no network; any other version has to be
+  downloaded, which fails on a device that is offline. Never install `fpdf`
+  (no `2`) — that is an abandoned, incompatible library.
+- `outputs` — the file to deliver. `pdf.output("report.pdf")` must match the
+  declared output name exactly.
+- `command` — the multi-line Python source, with real newline characters.
+  Never collapse it to one line joined by `;` — a `for`/`if`/`with` after a
+  semicolon is a `SyntaxError`.
+
+## The Recipe
+
+Start from this. It is a complete, working document — title, body paragraphs,
+a bulleted section, a table, automatic page breaks, saved under the declared
+output name. Copy it and change the content; do not assemble a PDF from memory.
+
+```python
+from fpdf import FPDF
+
+pdf = FPDF(format="A4")
+pdf.set_auto_page_break(auto=True, margin=15)
+pdf.add_page()
+
+pdf.set_font("helvetica", style="B", size=24)
+pdf.multi_cell(0, 12, "Quarterly Report", new_x="LMARGIN", new_y="NEXT")
+
+pdf.set_font("helvetica", size=12)
+pdf.ln(4)
+pdf.multi_cell(0, 6, "Revenue grew 20% quarter over quarter, driven by APAC. "
+                     "EMEA held flat while new logos offset churn.",
+               new_x="LMARGIN", new_y="NEXT")
+pdf.ln(2)
+
+pdf.set_font("helvetica", style="B", size=14)
+pdf.multi_cell(0, 10, "Highlights", new_x="LMARGIN", new_y="NEXT")
+pdf.set_font("helvetica", size=12)
+for point in [
+    "APAC bookings grew 34% and drove most of the quarter",
+    "EMEA held flat; new logos offset churn",
+    "Gross margin improved 2 points on infra savings",
+]:
+    pdf.multi_cell(0, 6, "- " + point, new_x="LMARGIN", new_y="NEXT")
+pdf.ln(2)
+
+with pdf.table() as table:
+    for row_data in [("Region", "Revenue"), ("APAC", "$1.2M"), ("EMEA", "$0.9M")]:
+        row = table.row()
+        for cell_text in row_data:
+            row.cell(cell_text)
+
+pdf.output("report.pdf")               # must match the declared output exactly
+print(f"{pdf.pages_count} pages")
+```
+
+## The Rules That Keep It Working
+
+- **Sizes are positional — there is no `width=` or `height=` keyword.** The
+  first two arguments of `cell` and `multi_cell` are `w` and `h`; passing
+  `width=` raises `TypeError`. The fix is renaming the arguments as in the
+  sample — never deleting the `new_x`/`new_y` keywords, which "fixes" the
+  error and prints every later line on top of the previous one.
+- **Every line of text goes through
+  `pdf.multi_cell(0, h, text, new_x="LMARGIN", new_y="NEXT")` — headings,
+  paragraphs, and bullets alike. Do not use `pdf.cell` at all.** `cell` does
+  not wrap, so a long heading is silently clipped at the right margin, and
+  without `new_x`/`new_y` it leaves the cursor at the END of the line so the
+  next write starts at the right margin — raising
+  `FPDFException: Not enough horizontal space` or printing on top of earlier
+  text. `multi_cell` wraps everything. Keep `new_x="LMARGIN", new_y="NEXT"`
+  on every call, exactly as in the sample. A bullet is one
+  `multi_cell(0, 6, "- " + point, …)` per point — never several bullets
+  packed into one string. `pdf.text(x, y, s)` is not a third option: it
+  paints at a fixed point with no wrapping and exists only for the watermark
+  stamp in `references/transform.md`.
+- **Write the whole document, not a cover page.** "A small PDF about X"
+  still means real content: a title, then several short sections, each a
+  heading plus a paragraph or bullets, as in the sample. A PDF containing
+  only a title and a subtitle is a failed turn — the explanation the user
+  asked for belongs inside the PDF, not in your chat reply.
+- **`set_font` before every block, not once.** A heading's bold 14-24 pt
+  style stays active until changed — reset to `pdf.set_font("helvetica",
+  size=12)` after each heading or the whole body renders huge and bold.
+  Core fonts: `helvetica`, `times`, `courier`; body text 10-12 pt.
+- **ASCII punctuation only.** The core fonts cover latin-1 and nothing else,
+  and one character outside it fails the whole cell with
+  `FPDFUnicodeEncodingException`. Curly quotes, em dashes, arrows, the •
+  bullet, CJK, and emoji are all outside. Write straight quotes `"` `'` and
+  hyphens `-` in every string — a bullet is `"- "`, never the `•` character.
+  Accented latin (`café`, `naïve`) is fine. When user content may carry smart
+  punctuation, normalize it first:
+
+  ```python
+  def latin1(text):
+      for bad, good in [("‘", "'"), ("’", "'"), ("“", '"'),
+                        ("”", '"'), ("–", "-"), ("—", "-"),
+                        ("…", "..."), ("→", "->"), ("•", "-")]:
+          text = text.replace(bad, good)
+      return text
+  ```
+
+  Text that genuinely needs CJK or emoji cannot be rendered — there are no
+  font files in this runtime and `add_font` has nothing to load, so never call
+  it. Say so and offer a latin transliteration instead of shipping `?`.
+- **Units are millimetres**, page format defaults to A4. `FPDF(format="letter")`
+  for US letter. An A4 page is 210 x 297 mm with 10 mm margins; a width of
+  `0` extends to the right margin.
+- **No markdown syntax in strings.** fpdf2 prints text literally — `##`,
+  `**bold**`, and `*italics*` come out as those exact characters. Headings
+  and emphasis are made with `set_font(..., style="B", size=…)`, as in the
+  sample.
+- **`pdf.output("name.pdf")` writes the deliverable.** Calling `output()`
+  with no argument returns the bytes instead — useful only for in-memory
+  intermediates; the file the user receives must be written under its
+  declared `outputs` name.
+- Never print the PDF's bytes or base64 — stdout is capped and the file
+  travels through `outputs`. Print only the page-count line.
+
+## Errors
+
+- `ModuleNotFoundError: No module named 'fpdf'` — `packages` was missing or
+  wrong; the pin is `fpdf2==2.8.8` (imported as `fpdf`). Never try to install
+  inside the script.
+- `TypeError: FPDF.cell() (or multi_cell) got an unexpected keyword argument
+  'width'` (or `'height'`) — the size parameters are the positional `w` and
+  `h`. Rewrite the call as in the sample —
+  `multi_cell(0, 6, text, new_x="LMARGIN", new_y="NEXT")`. Renaming is the
+  whole fix; deleting the keywords instead produces overlapping text.
+- `FPDFException: Not enough horizontal space to render a single character` —
+  an earlier `cell`/`multi_cell` left the cursor at the right margin. Add
+  `new_x="LMARGIN", new_y="NEXT"` to every `cell` and `multi_cell` call.
+- `FPDFUnicodeEncodingException: Character "…" is outside the range …` — a
+  non-latin-1 character reached a core font. Normalize the string (see the
+  `latin1` helper) and rerun; for CJK or emoji, tell the user it cannot be
+  rendered.
+- On an `AttributeError` or `TypeError` from fpdf2 the API name or arguments
+  are wrong — fix against this file's recipe. Do not retry the same call and
+  do not switch to a shell.
+
+## Finish
+
+When `exitCode` is `0` and `attachments` lists the `.pdf`, stop tool use and
+answer with one line: file name + the page count from stdout. Exactly one
+successful `exec` per request.

package/skills/pdf/references/transform.md

@@ -0,0 +1,270 @@
+# Transforming an Existing PDF (pypdf)
+
+Transform a PDF that is already in this chat by running Python through the
+`exec` tool: merge, split, rotate, watermark, encrypt, decrypt, fill form
+fields, extract text.
+
+**pypdf transforms pages; it cannot restyle or edit their content.** Merging,
+splitting, rotating, stamping, and encrypting work on a staged PDF. Adding a
+paragraph, rewording, or changing fonts, sizes, or colors does not — never
+poke at page objects to try (`KeyError`/`IndexError` is that mistake). For a
+content change, load `references/create.md` NOW and rebuild the whole document
+with fpdf2: every original section, unchanged, plus the requested change (no
+`inputs` needed when the original text is already in this chat; otherwise run
+the extract-text script below first). A rebuilt PDF that condenses or drops
+original sections is a failed turn.
+
+## Staging the PDF
+
+Any PDF already in this chat can be staged, whoever put it there. Stage it as
+an input by its `attachmentId` and open it with `PdfReader("existing.pdf")` or
+`PdfWriter(clone_from="existing.pdf")`; then transform and save a **new**
+output such as `merged.pdf`. Never overwrite the staged input. The working
+directory starts empty on every call, so a file you do not stage does not
+exist — opening last turn's PDF by name alone raises `FileNotFoundError`.
+
+The id comes from wherever the PDF entered the chat:
+
+- **Produced earlier in this chat** (a prior `exec` output, a `create_pdf`
+  result) — the `attachmentId` is in that tool result.
+- **Uploaded by the user** — the `[Attached file …]` line on their message
+  names it, and every non-image upload gets one:
+
+  ```
+  [Attached file "contract.pdf" (application/pdf) — attachmentId: 4f9c2ab1]
+  ```
+
+Copy the id verbatim — never placeholders like `att_pdf` or any id you made
+up. A `.pdf` is never staged id-less: the id-less form resolves to an uploaded
+*image*, so it cannot reach a PDF. Id-less entries (`{ "path": "photo.png" }`,
+no `attachmentId` key) are only for images the user uploaded — the first
+id-less entry is the first image of the user's latest message, and so on.
+
+If no `attachmentId` for the PDF is available anywhere in the chat, ask the
+user to attach it again. Do not invent ids and do not retry.
+
+## The exec call
+
+```json
+{
+  "language": "python",
+  "packages": ["pypdf==6.15.0"],
+  "inputs": [
+    { "attachmentId": "<id from the tool result that built a.pdf>", "path": "a.pdf" },
+    { "attachmentId": "<id from the tool result that built b.pdf>", "path": "b.pdf" }
+  ],
+  "outputs": ["merged.pdf"],
+  "command": "..."
+}
+```
+
+- `packages` — pin exactly `pypdf==6.15.0`; add `fpdf2==2.8.8` when one run
+  also builds pages (watermark). Add `"cryptography"` (deliberately unpinned —
+  the runtime supplies its own build) only for AES encryption or decrypting
+  AES-encrypted files. These exact versions ship with the app and install with
+  no network; any other version has to be downloaded, which fails on a device
+  that is offline.
+- `inputs` — the staged attachments. Paths must be unique bare filenames;
+  staged files land in the working directory under those names — reference
+  `PdfReader("a.pdf")` by that name only.
+- `outputs` — the files to deliver. A file you write but do not declare here
+  is discarded, and an undeclared `.pdf` earns a warning — build intermediate
+  pages in memory (`io.BytesIO`, as in the watermark recipe) instead of
+  writing extra files.
+- `command` — the multi-line Python source, with real newline characters.
+  Never collapse it to one line joined by `;`.
+
+`attachment … not found in this chat` means you invented an id or the file is
+not attached. Re-copy the exact id from the tool result or the
+`[Attached file …]` line that names the PDF; if neither exists, ask the user to
+attach it again instead of retrying.
+
+## Scripted Transforms — Run These, Do Not Write Them
+
+Merge, rotate, extract text, encrypt, and decrypt are bundled scripts: run them
+by naming the script in the `exec` call — no Python source at all. Stage the
+attachment(s) as `inputs`, declare the produced file in `outputs`, and pass the
+file names again as `scriptArgs` (scripts see the working directory, so the
+same bare names). Always write a new output name — never the staged input's.
+
+**Merge** several PDFs into one — args: output first, then the inputs in order:
+
+```json
+{
+  "language": "python",
+  "packages": ["pypdf==6.15.0"],
+  "inputs": [
+    { "attachmentId": "<real id>", "path": "a.pdf" },
+    { "attachmentId": "<real id>", "path": "b.pdf" }
+  ],
+  "outputs": ["merged.pdf"],
+  "skill": "pdf",
+  "script": "scripts/merge.py",
+  "scriptArgs": ["merged.pdf", "a.pdf", "b.pdf"]
+}
+```
+
+**Rotate** every page — args: input, output, degrees (a multiple of 90):
+
+```json
+{
+  "language": "python",
+  "packages": ["pypdf==6.15.0"],
+  "inputs": [{ "attachmentId": "<real id>", "path": "existing.pdf" }],
+  "outputs": ["rotated.pdf"],
+  "skill": "pdf",
+  "script": "scripts/rotate.py",
+  "scriptArgs": ["existing.pdf", "rotated.pdf", "90"]
+}
+```
+
+**Extract text** into a delivered `.txt` — args: input, output:
+
+```json
+{
+  "language": "python",
+  "packages": ["pypdf==6.15.0"],
+  "inputs": [{ "attachmentId": "<real id>", "path": "existing.pdf" }],
+  "outputs": ["extracted.txt"],
+  "skill": "pdf",
+  "script": "scripts/extract_text.py",
+  "scriptArgs": ["existing.pdf", "extracted.txt"]
+}
+```
+
+The script refuses a scanned PDF (no text layer, no OCR in this runtime) with a
+message saying so — tell the user the pages are images rather than rerunning.
+
+**Encrypt** with AES-256 — args: input, output, password. Needs the extra
+`"cryptography"` package entry (deliberately unpinned):
+
+```json
+{
+  "language": "python",
+  "packages": ["pypdf==6.15.0", "cryptography"],
+  "inputs": [{ "attachmentId": "<real id>", "path": "existing.pdf" }],
+  "outputs": ["locked.pdf"],
+  "skill": "pdf",
+  "script": "scripts/encrypt.py",
+  "scriptArgs": ["existing.pdf", "locked.pdf", "s3cret"]
+}
+```
+
+**Decrypt** — args: input, output, password (the password must come from the
+user). Needs `"cryptography"` too when the file is AES-encrypted:
+
+```json
+{
+  "language": "python",
+  "packages": ["pypdf==6.15.0", "cryptography"],
+  "inputs": [{ "attachmentId": "<real id>", "path": "locked.pdf" }],
+  "outputs": ["unlocked.pdf"],
+  "skill": "pdf",
+  "script": "scripts/decrypt.py",
+  "scriptArgs": ["locked.pdf", "unlocked.pdf", "s3cret"]
+}
+```
+
+### If a script fails
+
+Read its stderr first — the scripts print exactly what is wrong (bad argument
+order, wrong password, scanned pages). A failure is almost always fixed by
+correcting `scriptArgs` or `inputs` and running the script again. Only when the
+message does not explain it, load the script's source to inspect it — call the
+`skill` tool with `name: "pdf"` and `file: "scripts/<name>.py"` — then either
+rerun the script with fixed arguments or fall back to an inline `command`
+adapted from that source. Never load script sources up front; run them.
+
+## Coded Transforms
+
+Split, watermark, and form filling take shapes a fixed script cannot cover, so
+they stay inline Python in `command` (no `script` key). Each recipe below is
+complete; stage the attachment(s) as `inputs` first. `reader.pages` is
+zero-indexed. Always write a new output name — never the staged input's.
+
+**Split** — keep a page range (here: pages 1-3, i.e. indexes 0-2):
+
+```python
+from pypdf import PdfReader, PdfWriter
+
+reader = PdfReader("existing.pdf")
+part = PdfWriter()
+for page in reader.pages[0:3]:
+    part.add_page(page)
+part.write("pages-1-3.pdf")
+print(f"{len(part.pages)} pages")
+```
+
+**Watermark** — build the stamp with fpdf2 in memory, merge it onto every
+page. Needs both packages (`pypdf==6.15.0` and `fpdf2==2.8.8`). `over=False`
+puts the mark under the content, `over=True` on top:
+
+```python
+import io
+from fpdf import FPDF
+from pypdf import PdfReader, PdfWriter
+
+mark = FPDF(format="A4")
+mark.add_page()
+mark.set_font("helvetica", style="B", size=60)
+mark.set_text_color(200, 200, 200)
+with mark.rotation(45, x=105, y=148):
+    mark.text(30, 160, "DRAFT")      # text(x, y, s) is stamp-only: fixed point, no wrapping
+stamp = PdfReader(io.BytesIO(mark.output())).pages[0]
+
+writer = PdfWriter(clone_from="existing.pdf")
+for page in writer.pages:
+    page.merge_page(stamp, over=False)
+writer.write("watermarked.pdf")
+print(f"{len(writer.pages)} pages")
+```
+
+**Fill form fields** — inspect the field names first (`get_fields`), then set
+them by exact name:
+
+```python
+from pypdf import PdfReader, PdfWriter
+
+reader = PdfReader("form.pdf")
+fields = reader.get_fields()
+print("fields:", sorted(fields) if fields else "none")
+
+writer = PdfWriter(clone_from="form.pdf")
+writer.update_page_form_field_values(
+    writer.pages[0], {"name": "Ada Lovelace", "email": "ada@example.com"}
+)
+writer.write("filled.pdf")
+print(f"{len(writer.pages)} pages")
+```
+
+If `get_fields()` returns `None` the PDF has no form layer — flattened forms
+cannot be filled; say so instead of guessing at overlay coordinates.
+
+## Errors
+
+- `ModuleNotFoundError: No module named 'pypdf'` — `packages` was missing or
+  wrong; the pin is `pypdf==6.15.0`. Never try to install inside the script.
+- `DependencyError: cryptography>=3.1 is required for AES algorithm` — add
+  `"cryptography"` to `packages` and rerun. The encrypt/decrypt scripts clear
+  pypdf's cached crypto backend themselves.
+- `usage: <script>.py …` on stderr — the `scriptArgs` were wrong (order,
+  count, or a non-numeric degrees). Fix the arguments and run the script
+  again; do not rewrite the script as inline code for an argument mistake.
+- `EOF marker not found` or `PdfReadError` on open — the staged file is not a
+  complete PDF; check the right attachment was staged, or ask the user to
+  re-attach it.
+- `File has not been decrypted` — the input is password-protected: ask the
+  user for the password and run the decrypt recipe first.
+- `FileNotFoundError` — the file was never staged, or the name does not match
+  an `inputs` path. The working directory starts empty on every call: stage
+  the PDF via `inputs` with the `attachmentId` from the tool result that
+  produced it, or rebuild from scratch. Do not invent ids.
+- On an `AttributeError` or `TypeError` from pypdf the API name or arguments
+  are wrong — fix against this file's recipes. Do not retry the same call and
+  do not switch to a shell.
+
+## Finish
+
+When `exitCode` is `0` and `attachments` lists the output file, stop tool use
+and answer with one line: file name + the page count from stdout. Exactly one
+successful `exec` per request.

package/skills/pdf/scripts/decrypt.py

@@ -0,0 +1,26 @@
+"""Decrypt a password-protected PDF (requires the "cryptography" package entry for AES files).
+
+Usage: decrypt.py <input.pdf> <output.pdf> <password>
+"""
+
+import sys
+
+# pypdf picks its crypto backend at first import and the interpreter is reused
+# across calls — clear it so the backend is chosen with "cryptography" present.
+for name in [m for m in sys.modules if m.startswith("pypdf")]:
+    del sys.modules[name]
+from pypdf import PdfReader, PdfWriter
+
+if len(sys.argv) != 4:
+    sys.exit("usage: decrypt.py <input.pdf> <output.pdf> <password> — the password never prints")
+
+source, target, password = sys.argv[1], sys.argv[2], sys.argv[3]
+if source == target:
+    sys.exit(f"output {target} must be a new name, not the staged input")
+
+reader = PdfReader(source)
+if reader.is_encrypted and not reader.decrypt(password):
+    sys.exit("wrong password — ask the user for the correct one; do not retry blind")
+writer = PdfWriter(clone_from=reader)
+writer.write(target)
+print(f"{len(writer.pages)} pages")

package/skills/pdf/scripts/encrypt.py

@@ -0,0 +1,25 @@
+"""Encrypt a PDF with AES-256 (requires the "cryptography" package entry).
+
+Usage: encrypt.py <input.pdf> <output.pdf> <password>
+"""
+
+import sys
+
+# pypdf picks its crypto backend at first import and the interpreter is reused
+# across calls, so an earlier pypdf run without "cryptography" would otherwise
+# pin the backend without AES.
+for name in [m for m in sys.modules if m.startswith("pypdf")]:
+    del sys.modules[name]
+from pypdf import PdfWriter
+
+if len(sys.argv) != 4:
+    sys.exit("usage: encrypt.py <input.pdf> <output.pdf> <password> — the password never prints")
+
+source, target, password = sys.argv[1], sys.argv[2], sys.argv[3]
+if source == target:
+    sys.exit(f"output {target} must be a new name, not the staged input")
+
+writer = PdfWriter(clone_from=source)
+writer.encrypt(user_password=password, algorithm="AES-256")
+writer.write(target)
+print(f"{len(writer.pages)} pages, AES-256")

package/skills/pdf/scripts/extract_text.py

@@ -0,0 +1,25 @@
+"""Extract all text from a PDF into a .txt file.
+
+Usage: extract_text.py <input.pdf> <output.txt>
+"""
+
+import sys
+
+from pypdf import PdfReader
+
+if len(sys.argv) != 3:
+    sys.exit(f"usage: extract_text.py <input.pdf> <output.txt> — got {sys.argv[1:]}")
+
+source, target = sys.argv[1], sys.argv[2]
+reader = PdfReader(source)
+text = "\n\n".join(page.extract_text() for page in reader.pages)
+
+if not text.strip():
+    sys.exit(
+        f"{source} has no text layer ({len(reader.pages)} pages are images; "
+        "there is no OCR in this runtime) — tell the user instead of rerunning"
+    )
+
+with open(target, "w") as f:
+    f.write(text)
+print(f"{len(reader.pages)} pages, {len(text)} characters")

package/skills/pdf/scripts/merge.py

@@ -0,0 +1,21 @@
+"""Merge two or more PDFs into one, in argument order.
+
+Usage: merge.py <output.pdf> <input1.pdf> <input2.pdf> [more inputs...]
+"""
+
+import sys
+
+from pypdf import PdfWriter
+
+if len(sys.argv) < 4:
+    sys.exit(f"usage: merge.py <output.pdf> <input1.pdf> <input2.pdf> [...] — got {sys.argv[1:]}")
+
+target, sources = sys.argv[1], sys.argv[2:]
+if target in sources:
+    sys.exit(f"output {target} must be a new name, not one of the staged inputs")
+
+merged = PdfWriter()
+for source in sources:
+    merged.append(source)
+merged.write(target)
+print(f"{len(merged.pages)} pages from {len(sources)} files")

package/skills/pdf/scripts/rotate.py

@@ -0,0 +1,27 @@
+"""Rotate every page of a PDF clockwise by a multiple of 90 degrees.
+
+Usage: rotate.py <input.pdf> <output.pdf> <degrees>
+"""
+
+import sys
+
+from pypdf import PdfWriter
+
+if len(sys.argv) != 4:
+    sys.exit(f"usage: rotate.py <input.pdf> <output.pdf> <degrees> — got {sys.argv[1:]}")
+
+source, target, degrees_raw = sys.argv[1], sys.argv[2], sys.argv[3]
+if source == target:
+    sys.exit(f"output {target} must be a new name, not the staged input")
+try:
+    degrees = int(degrees_raw)
+except ValueError:
+    sys.exit(f"degrees must be an integer multiple of 90, got: {degrees_raw}")
+if degrees % 90 != 0:
+    sys.exit(f"degrees must be a multiple of 90, got: {degrees}")
+
+writer = PdfWriter(clone_from=source)
+for page in writer.pages:
+    page.rotate(degrees)
+writer.write(target)
+print(f"{len(writer.pages)} pages rotated {degrees} degrees")