From Individual Tools to Composable Pipelines
Stirling PDF becomes a platform rather than a collection of isolated endpoints when one operation can pass a predictable result to the next. This chapter focuses on the contracts and runtime paths that make that possible: what format a tool accepts, what it produces, how many files cross the boundary, how compatibility is checked before execution, and how the editor represents the result afterward. The practical outcome is a way to sketch a multi-step workflow without assuming that every step receives one ordinary PDF and returns one ordinary PDF.
A useful example is an invoice flow that converts a source document, runs OCR, compresses the result, and then applies a watermark. The sequence looks linear to a person, but it may not be linear in data shape. A conversion can change the format, OCR can optionally return a package containing a sidecar, compression may process files individually, and a later merge may combine several inputs. A pipeline must preserve those distinctions or discover the mistake only after work has begun.
A tool contract describes the boundary
Stirling PDF's tool metadata treats an endpoint as a typed boundary. The contract records the formats an operation accepts, the format it produces, special input-extension behavior, whether an image reader determines the accepted inputs, the number of files entering or leaving, and cases in which a parameter changes the output. The point is not to make every PDF concept formal for its own sake. It is to give the next operation enough information to decide whether it can receive the previous one.
Format and filename are not the same thing. The source models encrypted PDF as a distinct format from ordinary PDF. An endpoint that accepts plain PDF does not automatically accept an encrypted document merely because both filenames end in .pdf. At the same time, the repository notes that extensions are a lossy projection: a filename can identify pdf, but it cannot reveal whether the bytes are encrypted. A compatibility system that looks only at the suffix can therefore be useful for quick filtering while still being unable to settle every semantic question.
The contract also models cardinality, or how many files enter and leave an operation. A single-input, single-output operation is different from one that accepts many inputs and produces one result, such as a merge. A splitter may accept one PDF and produce many PDFs. An operation may also accept many inputs and produce many outputs. Stirling PDF represents these shapes with single/multiple input and output arities rather than pretending that every multi-output result is simply a ZIP document.
That distinction matters because an archive can be either a transport container or the actual deliverable. When a splitter returns several PDFs packaged for transport, the caller can unpack them and continue treating the individual files as PDFs. When an operation's intended result is an archive, ZIP is the declared format and the archive remains packed. The bytes may look similar at the HTTP boundary, but the workflow meaning is different.
Parameter-dependent output is another important case. An operation may normally produce a PDF but produce a ZIP when a sidecar or related artifact is requested. The contract can describe that conditional result instead of choosing one permanent answer. If the relevant parameter has not been set, the validator can mark the output as uncertain rather than pretending that it knows the exact shape.
These declarations are also a way to keep implementation surfaces aligned. The repository describes the tool metadata as a source of truth that is published through the OpenAPI specification and used to generate corresponding information for the frontend and AI engine.