The Papertrail: AI PDF Renaming and the Tokens That Make It Interesting
Abstract
Everyone has a Downloads folder full of “scan0023.pdf” and “document(3)-final-FINAL.pdf”. Renaming them by content sounds trivial — read the file, understand what it is, give it a name. The implementation reveals something useful about how LLMs actually handle text: what a token is, why context windows matter in practice, why you want structured output instead of prose, and why heuristics should go first. The project, now called Folionym, is at github.com/sebastianspicker/folionym.
Contents
The project has since been renamed and refactored as Folionym, at
github.com/sebastianspicker/folionym;
the old AI-PDF-Renamer address redirects there. Where this post says “the
tool”, it means Folionym. Its current source identifies itself as 0.4.0a1, an
alpha candidate.
Repository configuration and Ollama documentation checked through 2026-10-24. Model names, context settings, endpoint compatibility, and remote-service privacy are configuration-dependent and should be rechecked against the installed release before use.
The Problem
Every PDF acquisition pipeline eventually produces the same chaos.
Journal articles downloaded from publisher sites arrive as
513194-008.pdf or 1-s2.0-S0360131520302700-main.pdf. Scanned
letters from the tax authority arrive as scan0023.pdf. Invoices arrive
as Rechnung.pdf — every invoice from every vendor, overwriting each
other if you are not paying attention. The actual content is
in the file. The filename tells you nothing.
The human solution is trivial: open the PDF, glance at the title or date or sender, type a descriptive name. Thirty seconds per file, multiplied by several hundred files accumulated over a year, becomes a task that perpetually does not get done.
The automated solution sounds equally trivial: read the text, decide what the document is, generate a filename. What could be involved?
Quite a bit, it turns out. Working through the implementation is a useful way to make concrete some things about LLMs and text processing that are easy to understand in the abstract but clearer with a specific task in front of you. In Folionym, renaming passes through seven stages, plus OCR when it is switched on, and one of the seven, the model call, can be skipped (Fig. 1).
--no-llm, and is skipped for a
document that a rules-file entry names or that has under 50 characters of
text. The column follows the steps below; the side boxes are the two
branches. OCR runs only with --ocr, and the rename log is written only
with --rename-log.Step One: Getting Text Out of a PDF
A PDF is not a text file. It is a binary format designed for page layout and print fidelity — it encodes character positions, fonts, and rendering instructions, not a linear stream of prose. The text in a PDF has to be extracted by a parser that reassembles it from the position data.
For PDFs with embedded text (most modern documents), this works well
enough. For scanned PDFs — images of pages, with no embedded text at all —
you need OCR as a fallback. Folionym extracts native text with PyMuPDF first. OCR through OCRmyPDF is
optional and off by default (--ocr); when enabled, it runs if native
extraction yields fewer than 50 characters (MIN_CHARS_BEFORE_OCR in
src/folionym/extraction/pdf.py).
The result is a string. Already there are failure modes: two-column layouts produce interleaved text if the parser reads left-to-right across both columns simultaneously; footnotes appear in the middle of sentences; tables produce gibberish unless the parser handles them specifically. These are not catastrophic — for renaming purposes, the first paragraph and the document header are usually enough, and those are less likely to be badly formatted than the body. But they are real, and they mean that the text passed to the next stage is not always clean.
Step Two: The Token Budget
Once you have a string representing the document’s text, you cannot always pass all of it to a language model, and you may not want to. Two reasons: the hard limit of the context window, and waste — even when the window is large enough, filling it with the full text of a thirty-page document is wasteful for a task that only needs the title, date, and category.
Language models do not process characters directly. They process tokens — units produced by a model-specific tokeniser, often a subword tokeniser but not necessarily the same BPE scheme I described in the strawberry post. A rough practical rule for English text is:
$$N_{\text{tokens}} \;\approx\; \frac{N_{\text{chars}}}{4}$$This is an approximation — technical text, non-English content, and code tokenise differently — but it is useful for budgeting. A ten-page academic paper might contain around 30,000 characters, which is approximately 7,500 tokens.
The repository’s apple-silicon preset uses qwen2.5:3b via Ollama and is
sized for a 32K context; the gpu preset uses qwen2.5:7b-instruct and is
sized for 128K. Qwen gives these models 32,768 and 131,072 tokens [[1]] [[2]],
but the 7B model reaches 128K only with YaRN, a rescaling of its rotary
position encoding that the shipped configuration leaves off [[2]], and
Ollama’s qwen2.5:7b-instruct tag, like qwen2.5:3b, comes with a 32K
window [[3]]. The runtime then decides what is actually available. Ollama
sets its default context by available VRAM: 4k tokens below 24 GiB, 32k
from 24 to 48 GiB and 256k from 48 GiB [[4]]. Its OpenAI-compatible
endpoint cannot change that per request; a larger window is set when
starting the server (OLLAMA_CONTEXT_LENGTH) [[4]] or with num_ctx in a
Modelfile [[5]].
The tool defaults to 28,000 tokens of extracted text
(DEFAULT_MAX_CONTENT_TOKENS, overridable with FOLIONYM_MAX_TOKENS), which leaves
4,768 tokens of a 32,768-token window for the prompt and response. That fit
holds only if the server runs with a context of about 32K or more; the
budget is almost seven times Ollama’s 4k default, and this post does not
test what the server then does with the excess. For documents that
exceed the budget, the extraction is truncated to the front of the text, on the
reasonable assumption that titles, dates, and document types appear early. The
count uses tiktoken when the optional tokens extra is installed and
otherwise falls back to the four-characters-per-token rule above. Both are
estimates of what the model sees: the tool asks tiktoken for OpenAI’s
cl100k_base encoding [[6]], while Qwen uses its own byte-level BPE with
151,643 regular tokens [[1]].
In pages, with the same two assumptions (3,000 characters per page, four characters per token, hence 750 tokens per page), the budget is
$$\frac{28{,}000\ \text{tokens}}{750\ \text{tokens per page}} \;\approx\; 37\ \text{pages}.$$A ten-page paper fills about a quarter of it, a thirty-page document (22,500 tokens) goes to the model whole, and truncation starts partway through page 38 (Fig. 2, panel b). The number 28,000 follows from the smaller window, not from what the filename needs: it fills 85% of a 32K window and 21% of a 128K one (panel a).
Truncating from the front is still a design decision, not a limitation to be apologised for, but I gave it the wrong reason. Until this revision the post said that the first two pages of a document contain everything the filename needs, as if that set the budget. They usually contain most of it, which is why cutting the back of a long document costs little; the budget itself is set by the window. A strategy that extracts the first page plus the last page (which often has a date, a signature, or a reference number) would work for some document types. The current implementation keeps it simple: take the front, stay within budget.
The default deals with the hard limit, not with the waste. Anyone who wants
only the front can lower FOLIONYM_MAX_TOKENS; the first two pages at these
densities are 1,500 tokens.
Step Three: Heuristics First
Here is something that improves almost any LLM pipeline for structured extraction tasks: do as much work as possible with deterministic rules before touching the model.
Folionym applies a scoring pass over the extracted text. The scores come from
regex patterns in the bundled heuristic_scores.json. The heuristics are regex-based
rules that look for patterns likely to appear in specific document types:
- Date patterns, handled in
src/folionym/naming/dates.py: ISO and compact dates, day-month-year forms such as15.03.2025, German and English long-form dates, and month-year forms - Category patterns: weighted regexes such as the invoice markers
(
rechnungs\s*nummer,invoice\s*number,vat\s*invoice) in the bundledsrc/folionym/data/heuristic_scores.json - Category aliases and stopwords, in the bundled
category_aliases.jsonandmeta_stopwords.json, plus an optional rules file for overrides
Each pattern that fires contributes a score to a category. How much that score
spares the model is configurable and, by default, limited. With the LLM enabled
(the default), the model is still asked for a summary and keywords; the category
request is skipped only when both skip_llm_category_if_heuristic_score_ge and
skip_llm_category_if_heuristic_gap_ge are set and the heuristic category
clears them, and both default to unset. The LLM is skipped for a document when
--no-llm is given, or when a rules file lists its heuristic category under
skip_llm_if_heuristic_category. In those cases the file is renamed from the
heuristic output.
This matters because heuristics are deterministic and can avoid a model call. How much faster they are, and what share of documents they could settle on their own, depends on hardware, rules and corpus; this post benchmarks neither.
The LLM is intended to supply what rules cannot: a summary and keywords for unusual formats, mixed languages or ambiguous document types, and a category when the heuristic is unsure. Under the defaults described above, it runs for every document with at least 50 characters of extracted text, unless a cached reply for the same file is reused; the heuristic category is what naming falls back on.
Step Four: What to Ask the LLM, and How
Unless --no-llm or a rule skips it, the pipeline builds a prompt from the
extracted text and sends it to the local endpoint. What the prompt asks for matters enormously.
The naive approach: “Please rename this PDF. Here is the content: [text].” The response will be a sentence. Maybe several sentences. It will not be parseable as a filename without further processing, and that further processing is itself an LLM call or a fragile regex.
The better approach: ask for structured output. The prompt in
src/folionym/naming/prompts.py requests a JSON object with three fields, in
the English prompt:
{
"summary": "1-2 precise sentences",
"keywords": ["KW1", "KW2", "KW3", "KW4", "KW5", "KW6"],
"category": "Category"
}
The rules in the prompt ask for a 1–2 sentence summary and 5–7 keywords. The
date is not part of this request; it comes from the date patterns above,
then from the PDF’s metadata, and failing both, from the day of the run. The
model returns JSON, and the response parser in src/folionym/llm/parsing.py
validates it and can accept lenient JSON for list fields such as keywords.
The naming code then filters stopwords, keeps the first three keywords and the
first five summary tokens, and cleans each token before assembling the
filename (_build_metadata_parts in src/folionym/naming/metadata.py).
Structured JSON creates a schema that can be parsed and validated. Reliability still depends on model, runtime, decoding, prompt and document; this post does not measure a failure rate.
Schema checks can reject shape and allowed-value errors. They do not by themselves prove that a plausible summary, keyword or category is supported by the source; that requires source-grounded validation and human review in the dry run.
Step Five: The Filename
The output format is YYYYMMDD-category-keywords-summary.pdf. A few
design decisions embedded in this:
Date first. Lexicographic sorting of filenames then gives you chronological sorting for free. This is the most useful sort order for most document types — you want to find the most recent invoice, not the alphabetically first one.
Lowercase, hyphens by default. No spaces (which require escaping in many
contexts), no special characters (which are illegal in some filesystems
or require quoting), no uppercase (which creates case-sensitivity issues
across platforms). The token cleaning in src/folionym/naming/tokens.py transliterates umlauts,
removes characters that are illegal in Windows filenames, lowercases, and
replaces whitespace with underscores; the default case style is kebabCase,
joined with hyphens (desired_case, with camelCase and snakeCase as
alternatives).
Collision resolution. Two documents with the same date, category,
keywords, and summary would produce the same filename. The resolver
appends a counter suffix (_1, _2, …) when a target name already
exists (src/folionym/rename_ops/execution.py). Which of the two files gets the
suffix therefore depends on processing order. In a command-line run at commit
3056b89 (18 October 2026), files are processed newest-modified first, so the
most recently modified file gets the plain name; files with the same
modification time keep the order of the directory listing, which is no
defined tie-break.
Local-First
The repository’s Apple-Silicon and GPU presets use Ollama at http://127.0.0.1:11434; its
documented configured completion URL is http://127.0.0.1:11434/v1/completions,
from which the default chat mode derives /v1/chat/completions; --no-chat-api
uses the completions URL itself. Ollama’s OpenAI-compatibility documentation
leads with /v1/chat/completions and also lists /v1/completions as
supported [[5]]; which endpoint a given release and configuration accept is
still worth checking. This
local default is a deliberate choice
for a document management tool. The documents being renamed are likely
to include medical records, financial statements, legal correspondence —
content that should not be routed through an external API by default.
The default preset (apple-silicon) is a 3B Qwen 2.5 model, while the GPU preset is a 7B instruction model; model
choice, latency, and extraction quality depend on hardware, runtime, language, scan quality, and
the documents. This is a utility task that can often use a small local model, but suitability
should be established with a representative dry run rather than inferred from parameter count.
For users who want to use a remote API, the endpoint is configurable. That changes the data-flow and privacy boundary; the local default is a sensible starting point, not a guarantee once a remote endpoint, proxy, hook, or third-party OCR service is configured.
What It Cannot Do
Renaming is a classification problem disguised as a text generation problem. The tool works well when documents have standard structure — title on page one, date near the header or footer, document type identifiable from a few keywords. It works less well for documents that are structurally atypical: a hand-written letter scanned at poor resolution, a PDF that is essentially a single large image, a document in a language the model handles badly.
With --no-llm, or when the LLM returns nothing usable, naming rests on the
heuristic category. The rename log (written when --rename-log is given) and
the folionym-undo command mean that a bad batch run can be reversed, subject
to the constraints in the README. These
are not complete solutions to the hard cases, but they are the right
design response to a tool that handles real-world document noise.
The harder limit is semantic: the tool can tell you that a document is an invoice, find its date and pick keywords that may include the vendor’s name. It cannot tell you whether the invoice has been paid, whether it matches a purchase order, or whether the amount is correct. For those questions, renaming is just the first step in a longer pipeline.
The code is at github.com/sebastianspicker/folionym. The tokenisation background in the extraction and budgeting sections connects to the strawberry tokenisation post and the context window post.
References
[1] Qwen Team: Yang, A., Yang, B., Zhang, B., Hui, B., Zheng, B., Yu, B., et al. (2024). Qwen2.5 technical report. arXiv:2412.15115 (Section 2 and Table 1). DOI: 10.48550/arXiv.2412.15115
[2] Qwen. Qwen2.5-3B-Instruct and Qwen2.5-7B-Instruct model cards. Hugging Face. Retrieved 24 October 2026 from https://huggingface.co/Qwen/Qwen2.5-3B-Instruct and https://huggingface.co/Qwen/Qwen2.5-7B-Instruct
[3] Ollama. qwen2.5 model tags. Retrieved 24 October 2026 from https://ollama.com/library/qwen2.5/tags
[4] Ollama. Context length (documentation). Retrieved 24 October 2026 from https://docs.ollama.com/context-length
[5] Ollama. OpenAI compatibility (documentation). Retrieved 24 October 2026 from https://docs.ollama.com/openai
[6] OpenAI. tiktoken (README and tiktoken/model.py). Retrieved 24 October 2026 from https://github.com/openai/tiktoken
Changelog
- 2026-04-02: Corrected the default model name from
qwen3:8btoqwen2.5:3b. The codebase default isqwen2.5:3b(apple-silicon preset) orqwen2.5:7b-instruct(gpu preset). - 2026-04-02: Corrected
DEFAULT_MAX_CONTENT_TOKENSdescription from “28,000 characters … roughly 7,000 tokens” to “28,000 tokens.” The variable is a token limit, not a character limit. - 2026-07-11: Corrected tokenizer, model, endpoint, privacy, benchmark, JSON-validation, fallback-rate, and collision-order claims to distinguish documented defaults from untested behaviour.
- 2026-10-03: Updated the repository link and implementation details after
the project was renamed and refactored as Folionym: new address, file paths
(
llm/prompts.py,llm/parsing.py,naming/), prompt fields (1–2 sentence summary, 5–7 keywords, with three keywords and five summary tokens kept in the filename), collision suffixes (_1,_2), optional OCR, and when the LLM is skipped. - 2026-10-24: Corrected the truncation rationale: at 3,000 characters
per page and four per token, the 28,000-token budget holds about 37 pages,
so it is set by the 32K window, not by the two title pages, and fits only
if the server runs with about 32K of context (Ollama’s default is 4k below
24 GiB of VRAM; its
qwen2.5:7b-instructtag ships 32K, not 128K). Removed sentences pointing at claims deleted on 2026-07-11. Stated when the model is skipped (including texts under 50 characters), the date fallbacks, the collision order, that the rename log needs--rename-logand that heuristics are deterministic. The prompt now lives innaming/prompts.py. Added Figs. 1–2 and references.