Package com.tnsai.tools.file

Class PdfTools

java.lang.Object

com.tnsai.tools.file.PdfTools

public class PdfTools
extends Object

Function-shape PDF tools — the LangChain-style replacement for the legacy PDFExtractorTool / PDFMergeTool / PDFToImageTool (see issue #188 — RFC).

Five typed @Tool methods cover the PDF operations the framework's agents actually use:

Method	Purpose
pdfExtractText(java.lang.String)	Extract all text from a PDF
pdfExtractPages(java.lang.String, java.lang.String)	Extract text from a page range like "1-5" or "1,3,5-7"
pdfMetadata(java.lang.String)	Title / author / page count / dates
pdfMerge(java.util.List<java.lang.String>, java.lang.String)	Combine multiple PDFs into one
pdfToImage(java.lang.String, java.lang.String, java.lang.String)	Render each page as PNG/JPEG

pdfSplit and pdfCompress from the legacy tool family are out of scope for this batch — both have low usage in cookbook flows; they land in a follow-up batch (or stay as separate niche tools) once the core extract / merge / convert workflow is migrated.

All PDF I/O goes through Apache PDFBox; the dependency is declared <optional>true</optional> in this module's pom, so consumers without PDFBox on the classpath will see PdfTools fail at registration — ToolMethodRegistry discovers @Tool methods reflectively, so the missing dependency surfaces there rather than at compile time.

Since:

0.5.7 (Phase 2 batch 3 — built-in tool migration to function shape, see #188)

Field Summary

Fields

Modifier and Type	Field	Description
static final Set<String>	DEFAULT_EXTENSIONS

Constructor Summary

Constructors

Constructor	Description
PdfTools()
PdfTools(FileGuardConfig guardConfig)
PdfTools(FileGuardConfig guardConfig, DoclingProvider doclingProvider)	Creates PDF tools with an optional Docling page-rendering fallback.

Method Summary

Modifier and Type	Method	Description
String	pdfExtractPages(String path, String pages)
String	pdfExtractText(String path)
String	pdfMerge(List<String> inputPaths, String outputPath)
String	pdfMetadata(String path)
String	pdfToImage(String path, String outputDir, String format)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

DEFAULT_EXTENSIONS

public static final Set<String> DEFAULT_EXTENSIONS

Constructor Details

PdfTools

public PdfTools()

PdfTools

public PdfTools(FileGuardConfig guardConfig)

PdfTools

public PdfTools(FileGuardConfig guardConfig,
 DoclingProvider doclingProvider)

Creates PDF tools with an optional Docling page-rendering fallback. PDFBox remains the primary renderer; Docling is consulted only when PDFBox cannot open the admitted source.

Method Details

pdfExtractText

@Tool(name="pdf_extract_text",
      description="Extract all text content from a PDF file as a single string. Use this for full-document analysis, summarization, or feeding into a RAG pipeline. For specific page ranges, use pdf_extract_pages instead.",
      keywords={"pdf","extract","text","read","content"},
      idempotent=true)
public String pdfExtractText(@ToolParam(description="Absolute file path to a .pdf file")
 String path)
                      throws IOException

Throws:

IOException

pdfExtractPages

@Tool(name="pdf_extract_pages",
      description="Extract text from a specific page range of a PDF. The range syntax mirrors print-range conventions: \"1-5\" (range), \"3\" (single page), \"1,3,5-7\" (comma-separated mix). Page numbers are 1-indexed. Returns the concatenated text of the requested pages with page-break markers between sections.",
      keywords={"pdf","extract","pages","range"},
      idempotent=true)
public String pdfExtractPages(@ToolParam(description="Absolute file path to a .pdf file")
 String path,
 @ToolParam(description="1-indexed page range, e.g. \"1-5\", \"3\", \"1,3,5-7\"")
 String pages)
                       throws IOException

Throws:

IOException

pdfMetadata

@Tool(name="pdf_metadata",
      description="Read the document metadata of a PDF: title, author, subject, keywords, creator, producer, creation/modification dates, and page count. Returns a multi-line key:value summary.",
      keywords={"pdf","metadata","info","properties"},
      idempotent=true)
public String pdfMetadata(@ToolParam(description="Absolute file path to a .pdf file")
 String path)
                   throws IOException

Throws:

IOException

pdfMerge

@Tool(name="pdf_merge",
      description="Combine multiple PDF files into a single output PDF. Files are concatenated in the given order. The output directory is created if missing. Returns a one-line success message including the output path and file count.",
      keywords={"pdf","merge","combine","concatenate"})
public String pdfMerge(@ToolParam(description="Ordered list of absolute paths to .pdf files to merge")
 List<String> inputPaths,
 @ToolParam(description="Absolute path of the merged output .pdf file")
 String outputPath)
                throws IOException

Throws:

IOException

pdfToImage

@Tool(name="pdf_to_image",
      description="Render each page of a PDF as a separate image file (PNG by default; \"jpg\" or \"jpeg\" also accepted) into the output directory. Files are named <basename>_page_<NNN>.<ext>. Returns the list of image paths, one per line.",
      keywords={"pdf","image","render","convert","png","jpeg"})
public String pdfToImage(@ToolParam(description="Absolute path to a .pdf file")
 String path,
 @ToolParam(description="Output directory for the rendered page images")
 String outputDir,
 @ToolParam(description="Image format: \"png\" (default), \"jpg\", or \"jpeg\"",required=false,defaultValue="png")
 String format)
                  throws IOException

Throws:

IOException