elizaos--eliza/plugins/plugin-pdf/README.md

@elizaos/plugin-pdf

PDF text extraction plugin for elizaOS.

Adds PdfService to an Eliza agent runtime so that PDF buffers can be parsed and their text content extracted. The service is available to any action, provider, or agent code via runtime.getService(ServiceType.PDF).

Installation

elizaos plugins add @elizaos/plugin-pdf

or with bun directly:

bun add @elizaos/plugin-pdf

Configuration

No environment variables or configuration required. Uses unpdf for local, self-contained PDF processing.

Enabling the Plugin

Add the package name to the plugins array in your character file:

const character: Partial<Character> = {
  name: "MyAgent",
  plugins: ["@elizaos/plugin-pdf"],
};

PdfService API

Retrieve the service instance from the runtime:

import { ServiceType } from "@elizaos/core";
import type { PdfService } from "@elizaos/plugin-pdf";

const pdfService = runtime.getService<PdfService>(ServiceType.PDF);

Methods

convertPdfToText(pdfBuffer: Buffer): Promise<string>

Extracts all text from every page as a single cleaned string.

import * as fs from "node:fs/promises";

const buffer = await fs.readFile("document.pdf");
const text = await pdfService.convertPdfToText(buffer);

convertPdfToTextWithOptions(pdfBuffer: Buffer, options?: PdfExtractionOptions): Promise<PdfConversionResult>

Extracts text with control over page range, whitespace, and cleanup. Returns a result object with success, text, pageCount, and error fields.

const result = await pdfService.convertPdfToTextWithOptions(buffer, {
  startPage: 1,
  endPage: 5,
  preserveWhitespace: false,
  cleanContent: true,
});

if (result.success) {
  console.log(result.text);
}

getDocumentInfo(pdfBuffer: Buffer): Promise<PdfDocumentInfo>

Returns full document information: page count, per-page dimensions + text, and metadata (title, author, subject, keywords, creator, producer, creation/modification dates).

Exported Types

PdfConversionResult   // { success, text?, pageCount?, error? }
PdfExtractionOptions  // { startPage?, endPage?, preserveWhitespace?, cleanContent? }
PdfPageInfo           // { pageNumber, width, height, text }
PdfMetadata           // { title?, author?, subject?, keywords?, creator?, producer?, creationDate?, modificationDate? }
PdfDocumentInfo       // { pageCount, metadata, text, pages }

Platform Support

Builds for both Node.js and browser environments. The exports field in package.json selects the correct entry point automatically.

Dependencies

• unpdf — PDF parsing (wraps PDF.js for Node + browser)