aside-pdf

PDF Processing Guide

Reading PDFs

Use repl with aside.pdf API for visual inspection of PDFs.

interface PDFReadResult {
  pages: {
    /* Image path of the rendered page. */
    path: string; 
    /* Width of the rendered page. */
    width: number;
    /* Height of the rendered page. */
    height: number;
  }[];
  /** If there are form fields, it's metadata JSON path. Use `read_file` to read it. */
  formFieldsPath: string | undefined;
}

interface AsidePdf {
  /** Render PDF pages as images and inspect form fields using macOS native PDFKit. */
  read(options: { filePath: string; outputDir?: string; maxDimension?: number }): Promise<PDFReadResult>;

  /** Inspect AcroForm/XFA fields and return field descriptions when embedded in the PDF. */
  inspectFormFields(options: { filePath: string }): Promise<Record<string, unknown>>;

  /** Fill AcroForm fields into a new output PDF. */
  fillFormFields(options: {
    filePath: string;
    outputPath: string;
    fields: { field_id: string; value: boolean | number | string | null }[];
  })
}

REPL Examples

// Reading a PDF (pages[].path is the image path of the rendered page- use either `read_file` tool or `display(await fs.readFile(path))` to read the PDF as image)
console.log(await aside.pdf.read({ filePath: './input.pdf' }));

// Inspecting form fields
console.log(await aside.pdf.inspectFormFields({ filePath: './input.pdf' }));

// Filling form fields
await aside.pdf.fillFormFields({
  filePath: './input.pdf',
  outputPath: './artifacts/filled.pdf',
  fields: [
    { field_id: 'topmostSubform[0].Page1[0].f1_14[0]', value: 'John' },
    { field_id: 'topmostSubform[0].Page1[0].c1_1[0]', value: true }
  ]
});

Notes

Do not answer "the form is empty" when the user is asking what fields exist. Report the field meanings and separately say whether current values are blank.

If aside.pdf fails or the native helper cannot perform the requested operation, read fallback.md and use the fallback workflow.