PDF Content Renamer

PDF Content Renamer

Rename PDFs based on evidence found inside the document. Prefer accurate, boring filenames over clever summaries, and preserve enough traceability to explain how each name was chosen.

Naming Standard

Use this format unless the user specifies another convention:

YY-MM-DD Name Type Detail.pdf

Rules:

• Start every filename with YY-MM-DD.
• Use the most relevant date found in the document. If no reliable date is found, use today's date in the user's timezone.
• After the date, use human-readable Title Case words separated by spaces.
• Prefer this order after the date: person/entity or provider name, document type, and useful distinguishing detail.
• Keep names concise: name/provider, document type, subject/account tail, period, location/state, or short distinguishing detail.
• Remove unsafe filesystem characters: < > : " / \ | ? *, control characters, repeated spaces, and trailing dots.
• Do not overwrite existing files. Add -v2, -v3, etc. only when needed.
• Preserve the original .pdf extension.

Examples:

26-06-30 CommBank Bank Statement Everyday 1234.pdf
25-11-14 Jane Smith Driver Licence NSW.pdf
26-02-03 Sydney Clinic Medical Report Blood Test.pdf
26-07-06 Patricio Perpetua Driver License Victoria.pdf
26-07-03 Unknown Document Unclassified.pdf

Date Selection

Pick the date that best identifies the document, not necessarily the first date encountered.

Convert all dates to YY-MM-DD. If the document only gives a month or period, use the period end when clear; otherwise use the first day of the month and mention the uncertainty.

Prerequisites

• Node.js 20.19+
• Install @singleton-sd/ai-plattform-tools-pdf-context (once per machine or project)

Install from GitLab npm registry (recommended)

The package is public — no GitLab token required. Point the @singleton-sd scope at the project registry (once per machine or project), in .npmrc:

@singleton-sd:registry=https://gitlab.com/api/v4/projects/singleton-sd%2Fai-plattform%2Ftools%2Fpdf-context/packages/npm/

Then install:

npm install @singleton-sd/ai-plattform-tools-pdf-context

One-off run (no install; .npmrc scope line still required):

npx @singleton-sd/ai-plattform-tools-pdf-context \
  --pdf "C:/path/to/document.pdf" \
  --max-pages 3

After install, the CLI binary is pdf-context (from node_modules/.bin).

Install from source (development)

git clone git@gitlab.com:singleton-sd/ai-plattform/tools/pdf-context.git
cd pdf-context
yarn install

When working inside the ai-plattform workspace, the tool repo is at tools/pdf-context/.

Workflow

Task progress:
- [ ] Confirm pdf path(s)
- [ ] Install `@singleton-sd/ai-plattform-tools-pdf-context` if not present (see Prerequisites)
- [ ] Run pdf-context for each PDF
- [ ] Route large or scanned PDFs to pdf-to-markdown when needed
- [ ] Classify, pick date, propose filename(s)
- [ ] Present proposals (rename only if user confirms)

1. Resolve inputs.

   • Accept a single PDF, a folder, or a batch list.
   • Work from absolute paths.
   • For bulk renames, create a manifest with original path, proposed path, inferred date, date evidence, document type, confidence, and notes.

2. Extract enough content.

   • Prefer Node.js tools for all extraction, parsing, manifest generation, and renaming commands.
   • Always start with pdf-context — use the published CLI (do not hand-roll extraction unless the tool fails):

pdf-context \
  --pdf "C:/path/to/document.pdf" \
  --max-pages 3

If the package is not on PATH, use npx @singleton-sd/ai-plattform-tools-pdf-context.

When developing from source inside ai-plattform:

node tools/pdf-context/extract_context.mjs \
  --pdf "C:/path/to/document.pdf" \
  --max-pages 3

• Parse the JSON stdout for page_count, metadata, pages, combined_text, and likely_scanned.
• If page_count ≤ 3 and likely_scanned is false, use that JSON as the evidence source for classification, date selection, and filename proposals.
• Use metadata.creation_date / metadata.mod_date (already YY-MM-DD) as date hints, then apply the date selection table using text from pages or combined_text.
• If page_count > 3, use the documents/pdf-to-markdown skill instead of loading the whole PDF into context.
• If likely_scanned is true, route through the OCR-capable mode in documents/pdf-to-markdown; do not create ad hoc Python extraction scripts.
• Stop once there is enough evidence for a high-confidence name.

3. Classify the document.

   • Identify the document type from headings, labels, issuer, and repeated terms.
   • Prefer specific types such as bank-statement, driver-licence, medical-report, pathology-result, invoice, receipt, insurance-notice, or tax-notice.
   • Use unknown-document when evidence is weak.

4. Build the proposed filename.

   • Apply the date rules first.
   • Use human-readable Title Case words separated by spaces after the date.
   • Add person/entity or issuer/provider when visible.
   • Add a safe identifier only when useful, such as account last four digits, licence state, patient name, claim number, or document reference.
   • Avoid full account numbers, full licence numbers, Medicare numbers, tax file numbers, or other high-risk identifiers.

5. Verify and rename.

   • Present proposed names before renaming unless the user explicitly asked for immediate renaming.
   • Use filesystem-safe move/rename commands and avoid overwrites.
   • After renaming, report the old path, new path, and any low-confidence decisions.

Confidence Rules

Use high confidence only when the document type and date are both directly supported by text or reliable metadata. Use medium confidence when the type is clear but the best date needed judgment. Use low confidence when the file is scanned poorly, mostly blank, encrypted, or has conflicting document labels.

For low-confidence items:

• Keep unknown-document or unclassified in the filename.
• Use today's date only when no document date is reliable.
• Do not invent issuers, dates, names, or categories.
• Include a short note explaining what could not be verified.

Reporting Template

PDF rename proposals

1. {original_filename}
   Proposed: {YY-MM-DD-name.pdf}
   Basis: {document type}, {date source}, {issuer/provider}
   Confidence: {high|medium|low}
   Notes: {only if needed}

Renamed files:
- {old_path} -> {new_path}

Troubleshooting

Additional resources

• Tool package: @singleton-sd/ai-plattform-tools-pdf-context
• Full conversion for large/scanned PDFs: documents/pdf-to-markdown
• Tool repo: pdf-context