mirror of
https://github.com/arsvendg/Stirling-PDF.git
synced 2026-07-15 11:00:47 +02:00
Pdf comment agent (#6196)
Co-authored-by: James Brunton <[email protected]>
This commit is contained in:
ConnorYoh
co-authored by
James Brunton
James Brunton
parent
2dc5276e8b
commit
86774d556e
+15
@@ -0,0 +1,15 @@
|
||||
package stirling.software.common.model.api.comments;
|
||||
|
||||
/**
|
||||
* Absolute position of a PDF annotation in the document.
|
||||
*
|
||||
* <p>Coordinates are in PDF user-space with the origin at the page's bottom-left, consistent with
|
||||
* PDFBox's {@code PDRectangle} convention.
|
||||
*
|
||||
* @param pageIndex 0-indexed page number the annotation lives on.
|
||||
* @param x bottom-left x coordinate of the annotation rectangle.
|
||||
* @param y bottom-left y coordinate of the annotation rectangle.
|
||||
* @param width width of the annotation rectangle, in user-space units.
|
||||
* @param height height of the annotation rectangle, in user-space units.
|
||||
*/
|
||||
public record AnnotationLocation(int pageIndex, float x, float y, float width, float height) {}
|
||||
+15
@@ -0,0 +1,15 @@
|
||||
package stirling.software.common.model.api.comments;
|
||||
|
||||
/**
|
||||
* Description of a single sticky-note (PDF Text) annotation to place on a document.
|
||||
*
|
||||
* <p>{@code author} and {@code subject} are optional — callers that pass {@code null} get a default
|
||||
* author/subject from {@code PdfAnnotationService}.
|
||||
*
|
||||
* @param location where to anchor the annotation icon, in PDF user-space.
|
||||
* @param text the comment body shown in the popup (required, non-blank).
|
||||
* @param author optional author label shown in the popup; {@code null} → service default.
|
||||
* @param subject optional subject line shown in the popup; {@code null} → service default.
|
||||
*/
|
||||
public record StickyNoteSpec(
|
||||
AnnotationLocation location, String text, String author, String subject) {}
|
||||
@@ -34,11 +34,17 @@ import stirling.software.common.util.TempFileManager;
|
||||
@Slf4j
|
||||
public class InternalApiClient {
|
||||
|
||||
// Allowlist for internal dispatch. Matches a fixed namespace prefix,
|
||||
// Allowlist for internal dispatch. Matches fixed namespace prefixes,
|
||||
// but rejects traversal (..), URL-encoding (%), query/fragment, backslashes, and any other
|
||||
// character that could alter the resolved endpoint on the local Spring server.
|
||||
//
|
||||
// The second alternation carves out `/api/v1/ai/tools/*` specifically — AI tools are
|
||||
// dispatchable, but the broader `/api/v1/ai/` surface (orchestrate, health, etc.) is
|
||||
// intentionally NOT permitted to avoid plan steps re-entering the orchestrator.
|
||||
private static final Pattern ALLOWED_ENDPOINT_PATH =
|
||||
Pattern.compile("^/api/v1/(general|misc|security|convert|filter)(/[A-Za-z0-9_-]+)+$");
|
||||
Pattern.compile(
|
||||
"^/api/v1/(general|misc|security|convert|filter)(/[A-Za-z0-9_-]+)+$"
|
||||
+ "|^/api/v1/ai/tools(/[A-Za-z0-9_-]+)+$");
|
||||
|
||||
private final ServletContext servletContext;
|
||||
private final UserServiceInterface userService;
|
||||
|
||||
@@ -0,0 +1,157 @@
|
||||
package stirling.software.common.service;
|
||||
|
||||
import java.util.Calendar;
|
||||
import java.util.List;
|
||||
|
||||
import org.apache.pdfbox.cos.COSName;
|
||||
import org.apache.pdfbox.pdmodel.PDDocument;
|
||||
import org.apache.pdfbox.pdmodel.common.PDRectangle;
|
||||
import org.apache.pdfbox.pdmodel.graphics.color.PDColor;
|
||||
import org.apache.pdfbox.pdmodel.graphics.color.PDDeviceRGB;
|
||||
import org.apache.pdfbox.pdmodel.interactive.annotation.PDAnnotationText;
|
||||
import org.springframework.stereotype.Service;
|
||||
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
|
||||
import stirling.software.common.model.api.comments.AnnotationLocation;
|
||||
import stirling.software.common.model.api.comments.StickyNoteSpec;
|
||||
|
||||
/**
|
||||
* Shared primitive for adding sticky-note (PDF Text) annotations to a document.
|
||||
*
|
||||
* <p>Used by:
|
||||
*
|
||||
* <ul>
|
||||
* <li>{@code /api/v1/misc/add-comments} — a deterministic, reusable tool.
|
||||
* <li>AI-agent flows that generate comment specs (e.g. PDF review agent, math auditor review
|
||||
* mode) and hand them off to this service for deterministic placement.
|
||||
* </ul>
|
||||
*/
|
||||
@Slf4j
|
||||
@Service
|
||||
public class PdfAnnotationService {
|
||||
|
||||
/** Yellow sticky-note fill colour (R, G, B in 0..1 range). */
|
||||
private static final float[] STICKY_NOTE_COLOR_RGB = {1f, 0.95f, 0.4f};
|
||||
|
||||
/** Opacity for the sticky-note icon. */
|
||||
private static final float ANNOTATION_OPACITY = 0.9f;
|
||||
|
||||
/** PDF Text-annotation icon name — {@code "Comment"} is one of the standard icons. */
|
||||
private static final String ANNOTATION_ICON_NAME = "Comment";
|
||||
|
||||
/** Default subject shown in the annotation popup when a spec does not supply one. */
|
||||
private static final String DEFAULT_SUBJECT = "Stirling AI Comment";
|
||||
|
||||
/** Default author label shown in the annotation popup when a spec does not supply one. */
|
||||
private static final String DEFAULT_AUTHOR = "Stirling AI";
|
||||
|
||||
/**
|
||||
* Cap on sticky-note text length. PDF annotation bodies can technically be much longer, but
|
||||
* anything beyond this is almost certainly pathological (accidental document-dump or malicious
|
||||
* payload) and would bloat the output file.
|
||||
*/
|
||||
private static final int MAX_COMMENT_TEXT_LENGTH = 100_000;
|
||||
|
||||
/**
|
||||
* Add a list of sticky notes to {@code doc}. Specs that reference an out-of-range page or
|
||||
* contain blank text are logged and skipped; this method never throws for a single bad spec.
|
||||
*
|
||||
* @return the number of annotations actually applied
|
||||
*/
|
||||
public int addStickyNotes(PDDocument doc, List<StickyNoteSpec> specs) {
|
||||
if (specs == null || specs.isEmpty()) {
|
||||
return 0;
|
||||
}
|
||||
int totalPages = doc.getNumberOfPages();
|
||||
Calendar now = Calendar.getInstance();
|
||||
int applied = 0;
|
||||
for (int i = 0; i < specs.size(); i++) {
|
||||
StickyNoteSpec spec = specs.get(i);
|
||||
if (!isValid(spec, totalPages, i)) {
|
||||
continue;
|
||||
}
|
||||
apply(doc, spec, now);
|
||||
applied++;
|
||||
}
|
||||
if (applied < specs.size()) {
|
||||
log.warn(
|
||||
"Applied {}/{} sticky notes; {} skipped due to invalid specs.",
|
||||
applied,
|
||||
specs.size(),
|
||||
specs.size() - applied);
|
||||
}
|
||||
return applied;
|
||||
}
|
||||
|
||||
/**
|
||||
* Add a single sticky note. Convenience wrapper; prefer {@link #addStickyNotes(PDDocument,
|
||||
* List)} when placing multiple annotations so log output is batched.
|
||||
*/
|
||||
public void addStickyNote(PDDocument doc, StickyNoteSpec spec) {
|
||||
addStickyNotes(doc, List.of(spec));
|
||||
}
|
||||
|
||||
private boolean isValid(StickyNoteSpec spec, int totalPages, int index) {
|
||||
if (spec == null || spec.location() == null) {
|
||||
log.warn("Skipping sticky-note[{}]: spec or location is null.", index);
|
||||
return false;
|
||||
}
|
||||
if (spec.text() == null || spec.text().isBlank()) {
|
||||
log.warn("Skipping sticky-note[{}]: text is blank.", index);
|
||||
return false;
|
||||
}
|
||||
if (spec.text().length() > MAX_COMMENT_TEXT_LENGTH) {
|
||||
log.warn(
|
||||
"Skipping sticky-note[{}]: text length {} exceeds limit {}.",
|
||||
index,
|
||||
spec.text().length(),
|
||||
MAX_COMMENT_TEXT_LENGTH);
|
||||
return false;
|
||||
}
|
||||
AnnotationLocation loc = spec.location();
|
||||
if (loc.width() <= 0f || loc.height() <= 0f) {
|
||||
log.warn(
|
||||
"Skipping sticky-note[{}]: non-positive dimensions width={} height={}.",
|
||||
index,
|
||||
loc.width(),
|
||||
loc.height());
|
||||
return false;
|
||||
}
|
||||
int page = loc.pageIndex();
|
||||
if (page < 0 || page >= totalPages) {
|
||||
log.warn(
|
||||
"Skipping sticky-note[{}]: pageIndex={} out of range [0, {}).",
|
||||
index,
|
||||
page,
|
||||
totalPages);
|
||||
return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
private void apply(PDDocument doc, StickyNoteSpec spec, Calendar now) {
|
||||
AnnotationLocation loc = spec.location();
|
||||
|
||||
PDAnnotationText annot = new PDAnnotationText();
|
||||
annot.setContents(spec.text());
|
||||
annot.setRectangle(new PDRectangle(loc.x(), loc.y(), loc.width(), loc.height()));
|
||||
annot.setSubject(nonBlankOr(spec.subject(), DEFAULT_SUBJECT));
|
||||
annot.setTitlePopup(nonBlankOr(spec.author(), DEFAULT_AUTHOR));
|
||||
annot.setColor(new PDColor(STICKY_NOTE_COLOR_RGB, PDDeviceRGB.INSTANCE));
|
||||
annot.setCreationDate(now);
|
||||
annot.setConstantOpacity(ANNOTATION_OPACITY);
|
||||
annot.getCOSObject().setName(COSName.NAME, ANNOTATION_ICON_NAME);
|
||||
|
||||
try {
|
||||
doc.getPage(loc.pageIndex()).getAnnotations().add(annot);
|
||||
} catch (java.io.IOException e) {
|
||||
log.warn(
|
||||
"Failed to attach sticky note to page {}: {}", loc.pageIndex(), e.getMessage());
|
||||
}
|
||||
}
|
||||
|
||||
private static String nonBlankOr(String value, String fallback) {
|
||||
return value != null && !value.isBlank() ? value : fallback;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,139 @@
|
||||
package stirling.software.common.util;
|
||||
|
||||
import java.io.IOException;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Locale;
|
||||
import java.util.Optional;
|
||||
|
||||
import org.apache.pdfbox.pdmodel.PDDocument;
|
||||
import org.apache.pdfbox.pdmodel.common.PDRectangle;
|
||||
import org.apache.pdfbox.text.PDFTextStripper;
|
||||
import org.apache.pdfbox.text.TextPosition;
|
||||
import org.springframework.stereotype.Component;
|
||||
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
|
||||
/**
|
||||
* Locate text on a specific PDF page and return its bounding box in PDF user-space (bottom-left
|
||||
* origin). Used by tools that receive "anchor by text" hints — e.g. {@code
|
||||
* /api/v1/misc/add-comments} when callers supply an {@code anchorText} instead of explicit
|
||||
* coordinates.
|
||||
*
|
||||
* <p>Matching is tolerant: case-insensitive with punctuation/whitespace stripped on both sides, so
|
||||
* a caller-supplied needle of {@code "215000"} matches page text {@code "$215,000"}, and {@code
|
||||
* "Total Revenue"} matches {@code "Total Revenue."}.
|
||||
*/
|
||||
@Slf4j
|
||||
@Component
|
||||
public class PdfTextLocator {
|
||||
|
||||
/** One found line of text with its user-space bounding box. */
|
||||
public record MatchedBox(float x, float y, float width, float height) {}
|
||||
|
||||
/**
|
||||
* Find the first line on {@code pageIndex} (0-indexed) whose text contains {@code needle} under
|
||||
* the tolerant match. Returns empty when no match, when the page index is out of range, or when
|
||||
* the needle is blank.
|
||||
*/
|
||||
public Optional<MatchedBox> findOnPage(PDDocument doc, int pageIndex, String needle) {
|
||||
if (doc == null
|
||||
|| needle == null
|
||||
|| needle.isBlank()
|
||||
|| pageIndex < 0
|
||||
|| pageIndex >= doc.getNumberOfPages()) {
|
||||
return Optional.empty();
|
||||
}
|
||||
String normalizedNeedle = normalize(needle);
|
||||
if (normalizedNeedle.isEmpty()) {
|
||||
return Optional.empty();
|
||||
}
|
||||
|
||||
List<CapturedLine> lines = new ArrayList<>();
|
||||
LineCapturingStripper stripper;
|
||||
try {
|
||||
stripper = new LineCapturingStripper(lines);
|
||||
stripper.setStartPage(pageIndex + 1);
|
||||
stripper.setEndPage(pageIndex + 1);
|
||||
stripper.setSortByPosition(true);
|
||||
// Side effect: populates `lines`. We don't need the concatenated text.
|
||||
stripper.getText(doc);
|
||||
} catch (IOException e) {
|
||||
log.warn(
|
||||
"PdfTextLocator failed to extract text on page {}: {}",
|
||||
pageIndex,
|
||||
e.getMessage());
|
||||
return Optional.empty();
|
||||
}
|
||||
|
||||
PDRectangle mediaBox = doc.getPage(pageIndex).getMediaBox();
|
||||
float pageHeight = mediaBox.getHeight();
|
||||
|
||||
for (CapturedLine line : lines) {
|
||||
if (normalize(line.text).contains(normalizedNeedle)) {
|
||||
// PDFBox's *DirAdj coords descend from the top of the page; convert to PDF
|
||||
// user-space (origin = bottom-left) so the bbox can feed a PDRectangle directly.
|
||||
float userSpaceY = pageHeight - line.yTopDown - line.height;
|
||||
return Optional.of(new MatchedBox(line.x, userSpaceY, line.width, line.height));
|
||||
}
|
||||
}
|
||||
return Optional.empty();
|
||||
}
|
||||
|
||||
/** Strip everything non-alphanumeric and lowercase for tolerant matching. */
|
||||
private static String normalize(String s) {
|
||||
return s.replaceAll("[^A-Za-z0-9]", "").toLowerCase(Locale.ROOT);
|
||||
}
|
||||
|
||||
private static final class CapturedLine {
|
||||
String text;
|
||||
float x;
|
||||
float yTopDown;
|
||||
float width;
|
||||
float height;
|
||||
}
|
||||
|
||||
private static final class LineCapturingStripper extends PDFTextStripper {
|
||||
private final List<CapturedLine> lines;
|
||||
|
||||
LineCapturingStripper(List<CapturedLine> sink) throws IOException {
|
||||
super();
|
||||
this.lines = sink;
|
||||
}
|
||||
|
||||
@Override
|
||||
protected void writeString(String text, List<TextPosition> textPositions)
|
||||
throws IOException {
|
||||
if (textPositions != null && !textPositions.isEmpty()) {
|
||||
CapturedLine line = new CapturedLine();
|
||||
line.text = text;
|
||||
|
||||
float minX = Float.MAX_VALUE;
|
||||
float maxRight = 0f;
|
||||
float minY = Float.MAX_VALUE;
|
||||
float maxHeight = 0f;
|
||||
for (TextPosition p : textPositions) {
|
||||
float x = p.getXDirAdj();
|
||||
float y = p.getYDirAdj();
|
||||
float w = p.getWidthDirAdj();
|
||||
float h = p.getHeightDir();
|
||||
if (h == 0f) {
|
||||
// Workaround: some fonts report 0 height via TextPosition; fall back to
|
||||
// the nominal font size so downstream bboxes are never zero-height.
|
||||
h = p.getFontSizeInPt();
|
||||
}
|
||||
if (x < minX) minX = x;
|
||||
if (x + w > maxRight) maxRight = x + w;
|
||||
if (y < minY) minY = y;
|
||||
if (h > maxHeight) maxHeight = h;
|
||||
}
|
||||
line.x = minX;
|
||||
line.width = maxRight - minX;
|
||||
line.yTopDown = minY;
|
||||
line.height = maxHeight;
|
||||
lines.add(line);
|
||||
}
|
||||
super.writeString(text, textPositions);
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user