@nomad-e/bluma-cli 0.1.18 → 0.1.19

package/dist/config/skills/pdf/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: pdf
+description: >
+  Use this skill for any task involving PDF files. Triggers include: creating
+  new PDFs from scratch, reading or extracting text and tables from PDFs,
+  merging or splitting PDFs, rotating pages, adding watermarks, encrypting or
+  decrypting PDFs, filling PDF forms, extracting images, and OCR on scanned
+  PDFs to make them searchable. Use this skill whenever the user mentions
+  .pdf, "PDF document", "create a report as PDF", "extract from PDF",
+  "merge PDFs", "split PDF", "protect PDF", "fill a form", or any
+  PDF-related task — even if not explicitly stated as such.
+
+license: Proprietary. LICENSE.txt has complete terms
+---
+
+# PDF Processing Guide
+
+## Overview
+
+This guide covers essential PDF processing operations using Python libraries
+and command-line tools. For advanced features, JavaScript libraries, and
+detailed examples, see references/REFERENCE.md. If you need to fill out a
+PDF form, read references/FORMS.md and follow its instructions.
+
+## Quick Start
+
+```python
+from pypdf import PdfReader, PdfWriter
+
+# Read a PDF
+reader = PdfReader("document.pdf")
+print(f"Pages: {len(reader.pages)}")
+
+# Extract text
+text = ""
+for page in reader.pages:
+    text += page.extract_text()
+```
+
+## Python Libraries
+
+### pypdf — Basic Operations
+
+#### Merge PDFs
+```python
+from pypdf import PdfWriter, PdfReader
+
+writer = PdfWriter()
+for pdf_file in ["doc1.pdf", "doc2.pdf", "doc3.pdf"]:
+    reader = PdfReader(pdf_file)
+    for page in reader.pages:
+        writer.add_page(page)
+
+with open("merged.pdf", "wb") as output:
+    writer.write(output)
+```
+
+#### Split PDF
+```python
+reader = PdfReader("input.pdf")
+for i, page in enumerate(reader.pages):
+    writer = PdfWriter()
+    writer.add_page(page)
+    with open(f"page_{i+1}.pdf", "wb") as output:
+        writer.write(output)
+```
+
+#### Extract Metadata
+```python
+reader = PdfReader("document.pdf")
+meta = reader.metadata
+print(f"Title: {meta.title}")
+print(f"Author: {meta.author}")
+print(f"Subject: {meta.subject}")
+print(f"Creator: {meta.creator}")
+```
+
+#### Rotate Pages
+```python
+reader = PdfReader("input.pdf")
+writer = PdfWriter()
+
+page = reader.pages[0]
+page.rotate(90)  # Rotate 90 degrees clockwise
+writer.add_page(page)
+
+with open("rotated.pdf", "wb") as output:
+    writer.write(output)
+```
+
+### pdfplumber — Text and Table Extraction
+
+#### Extract Text with Layout
+```python
+import pdfplumber
+
+with pdfplumber.open("document.pdf") as pdf:
+    for page in pdf.pages:
+        text = page.extract_text()
+        print(text)
+```
+
+#### Extract Tables
+```python
+with pdfplumber.open("document.pdf") as pdf:
+    for i, page in enumerate(pdf.pages):
+        tables = page.extract_tables()
+        for j, table in enumerate(tables):
+            print(f"Table {j+1} on page {i+1}:")
+            for row in table:
+                print(row)
+```
+
+#### Advanced Table Extraction
+```python
+import pandas as pd
+
+with pdfplumber.open("document.pdf") as pdf:
+    all_tables = []
+    for page in pdf.pages:
+        tables = page.extract_tables()
+        for table in tables:
+            if table:
+                df = pd.DataFrame(table[1:], columns=table[0])
+                all_tables.append(df)
+
+if all_tables:
+    combined_df = pd.concat(all_tables, ignore_index=True)
+    combined_df.to_excel("extracted_tables.xlsx", index=False)
+```
+
+### reportlab — Create PDFs
+
+#### Basic PDF Creation
+```python
+from reportlab.lib.pagesizes import A4
+from reportlab.pdfgen import canvas
+
+c = canvas.Canvas("hello.pdf", pagesize=A4)
+width, height = A4
+
+# Add text
+c.drawString(100, height - 100, "Hello World!")
+c.drawString(100, height - 120, "This is a PDF created with reportlab")
+
+# Add a line
+c.line(100, height - 140, 400, height - 140)
+
+c.save()
+```
+
+#### Create PDF with Multiple Pages
+```python
+from reportlab.lib.pagesizes import A4
+from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak
+from reportlab.lib.styles import getSampleStyleSheet
+
+doc = SimpleDocTemplate("report.pdf", pagesize=A4)
+styles = getSampleStyleSheet()
+story = []
+
+# Add content
+title = Paragraph("Report Title", styles['Title'])
+story.append(title)
+story.append(Spacer(1, 12))
+
+body = Paragraph("This is the body of the report. " * 20, styles['Normal'])
+story.append(body)
+story.append(PageBreak())
+
+# Page 2
+story.append(Paragraph("Page 2", styles['Heading1']))
+story.append(Paragraph("Content for page 2", styles['Normal']))
+
+# Build PDF
+doc.build(story)
+```
+
+#### Subscripts and Superscripts
+
+**IMPORTANT**: Never use Unicode subscript/superscript characters (₀₁₂₃₄₅₆₇₈₉,
+⁰¹²³⁴⁵⁶⁷⁸⁹) in ReportLab PDFs. The built-in fonts do not include these glyphs,
+causing them to render as solid black boxes.
+
+pdftk file1.pdf file2.pdf cat output merged.pdf
+
+# Split
+pdftk input.pdf burst
+from reportlab.lib.styles import getSampleStyleSheet
+
+styles = getSampleStyleSheet()
+
+# Subscripts: use <sub> tag
+chemical = Paragraph("H<sub>2</sub>O", styles['Normal'])
+
+# Superscripts: use <super> tag
+squared = Paragraph("x<super>2</super> + y<super>2</super>", styles['Normal'])
+```
+
+For canvas-drawn text (not Paragraph objects), manually adjust font size and
+position rather than using Unicode subscripts/superscripts.
+
+## Command-Line Tools
+
+### pdftotext (poppler-utils)
+```bash
+# Extract text
+pdftotext input.pdf output.txt
+
+# Extract text preserving layout
+pdftotext -layout input.pdf output.txt
+
+# Extract specific pages
+pdftotext -f 1 -l 5 input.pdf output.txt  # Pages 1-5
+```
+
+### qpdf
+```bash
+# Merge PDFs
+qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf
+
+# Split pages
+qpdf input.pdf --pages . 1-5 -- pages1-5.pdf
+qpdf input.pdf --pages . 6-10 -- pages6-10.pdf
+
+# Rotate pages
+qpdf input.pdf output.pdf --rotate=+90:1  # Rotate page 1 by 90 degrees
+
+# Remove password
+qpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf
+```
+
+### pdftk (if available)
+```bash
+# Merge
+pdftk file1.pdf file2.pdf cat output merged.pdf
+
+# Split
+pdftk input.pdf burst
+
+# Rotate
+pdftk input.pdf rotate 1east output rotated.pdf
+```
+
+## Common Tasks
+
+### Extract Text from Scanned PDFs
+```python
+# Requires: pip install pytesseract pdf2image
+import pytesseract
+from pdf2image import convert_from_path
+
+# Convert PDF to images
+images = convert_from_path('scanned.pdf')
+
+# OCR each page
+text = ""
+for i, image in enumerate(images):
+    text += f"Page {i+1}:\n"
+    text += pytesseract.image_to_string(image, lang="por+eng")
+    text += "\n\n"
+
+print(text)
+```
+
+### Add Watermark
+```python
+from pypdf import PdfReader, PdfWriter
+
+# Load watermark
+watermark = PdfReader("watermark.pdf").pages[0]
+
+# Apply to all pages
+reader = PdfReader("document.pdf")
+writer = PdfWriter()
+
+for page in reader.pages:
+    page.merge_page(watermark)
+    writer.add_page(page)
+
+with open("watermarked.pdf", "wb") as output:
+    writer.write(output)
+```
+
+### Extract Images
+```bash
+# Using pdfimages (poppler-utils)
+pdfimages -j input.pdf output_prefix
+# Extracts all images as output_prefix-000.jpg, output_prefix-001.jpg, etc.
+```
+
+### Password Protection
+```python
+from pypdf import PdfReader, PdfWriter
+
+reader = PdfReader("input.pdf")
+writer = PdfWriter()
+
+for page in reader.pages:
+    writer.add_page(page)
+
+# Add password
+writer.encrypt("userpassword", "ownerpassword")
+
+with open("encrypted.pdf", "wb") as output:
+    writer.write(output)
+```
+
+## Quick Reference
+
+| Task                  | Best Tool    | Command/Code                        |
+|-----------------------|--------------|-------------------------------------|
+| Merge PDFs            | pypdf        | `writer.add_page(page)`             |
+| Split PDFs            | pypdf        | One page per file                   |
+| Extract text          | pdfplumber   | `page.extract_text()`               |
+| Extract tables        | pdfplumber   | `page.extract_tables()`             |
+| Create PDFs           | reportlab    | Canvas or Platypus                  |
+| Command line merge    | qpdf         | `qpdf --empty --pages ...`          |
+| OCR scanned PDFs      | pytesseract  | Convert to image first              |
+| Fill PDF forms        | pypdf / pdf-lib (see FORMS.md) | See references/FORMS.md |
+
+## Next Steps
+
+- For advanced pypdfium2 usage, see references/REFERENCE.md
+- For JavaScript libraries (pdf-lib), see references/REFERENCE.md
+- If you need to fill out a PDF form, follow the instructions in references/FORMS.md
+- For troubleshooting guides, see references/REFERENCE.md

package/dist/config/skills/pdf/references/FORMS.md

@@ -0,0 +1,69 @@
+# PDF Forms — Filling and Processing Guide
+
+This reference covers PDF form filling using Python and JavaScript libraries.
+
+## Detecting Form Fields (Python)
+
+```python
+from pypdf import PdfReader
+
+reader = PdfReader("form.pdf")
+fields = reader.get_fields()
+for name, field in fields.items():
+    print(f"Field: {name}, Type: {field.get('/FT')}, Value: {field.get('/V')}")
+```
+
+## Filling Forms with pypdf
+
+```python
+from pypdf import PdfReader, PdfWriter
+
+reader = PdfReader("form.pdf")
+writer = PdfWriter()
+writer.append(reader)
+
+writer.update_page_form_field_values(
+    writer.pages[0],
+    {
+        "name_field": "John Doe",
+        "email_field": "john@example.com",
+        "date_field": "2026-01-15",
+    }
+)
+
+with open("filled_form.pdf", "wb") as output:
+    writer.write(output)
+```
+
+## Filling Forms with pdf-lib (JavaScript)
+
+```javascript
+import { PDFDocument } from 'pdf-lib';
+import fs from 'fs';
+
+const pdfBytes = fs.readFileSync('form.pdf');
+const pdfDoc = await PDFDocument.load(pdfBytes);
+const form = pdfDoc.getForm();
+
+form.getTextField('name').setText('John Doe');
+form.getTextField('email').setText('john@example.com');
+form.getCheckBox('agree').check();
+
+const filledBytes = await pdfDoc.save();
+fs.writeFileSync('filled_form.pdf', filledBytes);
+```
+
+## Common Form Field Types
+
+| Type | pypdf Code | pdf-lib Code |
+|------|-----------|-------------|
+| Text | `update_page_form_field_values` | `getTextField().setText()` |
+| Checkbox | Set to `/Yes` or `/Off` | `getCheckBox().check()` |
+| Radio | Set to option value | `getRadioGroup().select()` |
+| Dropdown | Set to option value | `getDropdown().select()` |
+
+## Tips
+
+- Always flatten forms after filling if the PDF will be shared (prevents editing).
+- Some PDFs have XFA forms (XML-based) which are harder to fill programmatically.
+- For XFA forms, consider using pdftk or a commercial library.

package/dist/config/skills/pdf/references/REFERENCE.md

@@ -0,0 +1,52 @@
+# PDF Processing — Advanced Reference
+
+This document covers advanced PDF processing techniques beyond the basics in SKILL.md.
+
+## pypdfium2 — High-Performance Rendering
+
+```python
+import pypdfium2 as pdfium
+
+pdf = pdfium.PdfDocument("document.pdf")
+for i, page in enumerate(pdf):
+    bitmap = page.render(scale=2)
+    image = bitmap.to_pil()
+    image.save(f"page_{i+1}.png")
+```
+
+## JavaScript Libraries (pdf-lib)
+
+For browser-based or Node.js PDF manipulation:
+
+```javascript
+import { PDFDocument } from 'pdf-lib';
+
+const pdfDoc = await PDFDocument.create();
+const page = pdfDoc.addPage([600, 400]);
+page.drawText('Hello, PDF!', { x: 50, y: 350, size: 30 });
+const pdfBytes = await pdfDoc.save();
+```
+
+## pdf-lib — Modify Existing PDFs
+
+```javascript
+import { PDFDocument } from 'pdf-lib';
+import fs from 'fs';
+
+const existingPdfBytes = fs.readFileSync('input.pdf');
+const pdfDoc = await PDFDocument.load(existingPdfBytes);
+const pages = pdfDoc.getPages();
+const firstPage = pages[0];
+firstPage.drawText('WATERMARK', { x: 200, y: 400, size: 50, opacity: 0.3 });
+const pdfBytes = await pdfDoc.save();
+fs.writeFileSync('output.pdf', pdfBytes);
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "PdfReadError: EOF marker not found" | File is corrupted or not a valid PDF |
+| Empty text extraction | PDF might be image-based; use OCR (pytesseract) |
+| Tables not extracted correctly | Adjust pdfplumber table settings or try camelot |
+| Large PDF processing slow | Process pages in chunks or use pypdfium2 |

package/dist/config/skills/pdf/scripts/create_report.py

@@ -0,0 +1,59 @@
+"""
+Create a simple PDF report from CSV data using reportlab.
+
+Usage:
+    python create_report.py --input data.csv --output ./artifacts/report.pdf
+    python create_report.py --input data.csv --output report.pdf --title "Sales Report Q1 2026"
+"""
+import argparse
+import csv
+import sys
+
+def create_report(input_csv: str, output_pdf: str, title: str = "Report") -> None:
+    try:
+        from reportlab.lib.pagesizes import A4
+        from reportlab.lib import colors
+        from reportlab.platypus import SimpleDocTemplate, Table, TableStyle, Paragraph, Spacer
+        from reportlab.lib.styles import getSampleStyleSheet
+    except ImportError:
+        print("Error: reportlab is required. Install with: pip install reportlab", file=sys.stderr)
+        sys.exit(1)
+
+    with open(input_csv, "r", encoding="utf-8") as f:
+        reader = csv.reader(f)
+        data = list(reader)
+
+    if not data:
+        print("Error: CSV file is empty", file=sys.stderr)
+        sys.exit(1)
+
+    doc = SimpleDocTemplate(output_pdf, pagesize=A4)
+    styles = getSampleStyleSheet()
+    elements = []
+
+    elements.append(Paragraph(title, styles["Title"]))
+    elements.append(Spacer(1, 20))
+
+    table = Table(data)
+    table.setStyle(TableStyle([
+        ("BACKGROUND", (0, 0), (-1, 0), colors.grey),
+        ("TEXTCOLOR", (0, 0), (-1, 0), colors.whitesmoke),
+        ("ALIGN", (0, 0), (-1, -1), "CENTER"),
+        ("FONTNAME", (0, 0), (-1, 0), "Helvetica-Bold"),
+        ("FONTSIZE", (0, 0), (-1, 0), 12),
+        ("BOTTOMPADDING", (0, 0), (-1, 0), 12),
+        ("BACKGROUND", (0, 1), (-1, -1), colors.beige),
+        ("GRID", (0, 0), (-1, -1), 1, colors.black),
+    ]))
+    elements.append(table)
+
+    doc.build(elements)
+    print(f"Report created: {output_pdf} ({len(data)-1} data rows)")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Create PDF report from CSV")
+    parser.add_argument("--input", "-i", required=True, help="Input CSV file")
+    parser.add_argument("--output", "-o", required=True, help="Output PDF path")
+    parser.add_argument("--title", "-t", default="Report", help="Report title")
+    args = parser.parse_args()
+    create_report(args.input, args.output, args.title)

package/dist/config/skills/pdf/scripts/merge_pdfs.py

@@ -0,0 +1,39 @@
+"""
+Merge multiple PDF files into a single output PDF.
+
+Usage:
+    python merge_pdfs.py --output merged.pdf file1.pdf file2.pdf file3.pdf
+    python merge_pdfs.py --output ./artifacts/combined.pdf *.pdf
+"""
+import argparse
+import sys
+
+def merge_pdfs(input_files: list[str], output_path: str) -> None:
+    try:
+        from pypdf import PdfWriter, PdfReader
+    except ImportError:
+        print("Error: pypdf is required. Install with: pip install pypdf", file=sys.stderr)
+        sys.exit(1)
+
+    writer = PdfWriter()
+    for pdf_file in input_files:
+        try:
+            reader = PdfReader(pdf_file)
+            for page in reader.pages:
+                writer.add_page(page)
+            print(f"Added: {pdf_file} ({len(reader.pages)} pages)")
+        except Exception as e:
+            print(f"Error reading {pdf_file}: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    with open(output_path, "wb") as f:
+        writer.write(f)
+
+    print(f"Merged {len(input_files)} files -> {output_path}")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Merge PDF files")
+    parser.add_argument("files", nargs="+", help="PDF files to merge")
+    parser.add_argument("--output", "-o", required=True, help="Output file path")
+    args = parser.parse_args()
+    merge_pdfs(args.files, args.output)

package/dist/config/skills/skill-creator/LICENSE.txt

@@ -0,0 +1,26 @@
+© 2026 NomadEngenuity LDA. All rights reserved.
+
+LICENSE: Use of these materials (including all code, prompts, assets, files,
+and other components of this Skill) is governed by your agreement with
+NomadEngenuity LDA regarding use of NomadEngenuity LDA's services. If no
+separate agreement exists, use is governed by NomadEngenuity LDA's applicable
+Terms of Service.
+
+ADDITIONAL RESTRICTIONS: Notwithstanding anything in the Agreement to the
+contrary, users may not:
+
+- Extract these materials from the Services or retain copies of these
+  materials outside the Services
+- Reproduce or copy these materials, except for temporary copies created
+  automatically during authorized use of the Services
+- Create derivative works based on these materials
+- Distribute, sublicense, or transfer these materials to any third party
+- Make, offer to sell, sell, or import any inventions embodied in these
+  materials
+- Reverse engineer, decompile, or disassemble these materials
+
+The receipt, viewing, or possession of these materials does not convey or
+imply any license or right beyond those expressly granted above.
+
+NomadEngenuity LDA retains all right, title, and interest in these materials,
+including all copyrights, patents, and other intellectual property rights.