Pdf comment agent (#6196)

Co-authored-by: James Brunton <[email protected]>

engine/src/stirling/contracts/comments.py

@@ -0,0 +1,36 @@
+"""Structured sticky-note comment specs for the ``add-comments`` tool.
+
+The ``/api/v1/misc/add-comments`` tool takes a JSON string of comment specs
+(see :class:`stirling.models.tool_models.AddCommentsParams`). This module
+defines the typed Python shape we serialise into that string so callers
+don't have to hand-roll dictionaries.
+"""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from stirling.models import ApiModel
+
+
+class CommentSpec(ApiModel):
+    """Sticky-note spec serialised into the ``comments`` JSON string sent to
+    ``/api/v1/misc/add-comments``. The backend's tool contract takes the JSON
+    string form, not this type; this is the engine-side structured representation.
+    """
+
+    page_index: int = Field(description="0-indexed page number.")
+    x: float = Field(description="Bottom-left x coord of the icon (PDF user-space).")
+    y: float = Field(description="Bottom-left y coord of the icon (PDF user-space).")
+    width: float = Field(description="Width of the icon in user-space units.")
+    height: float = Field(description="Height of the icon in user-space units.")
+    text: str = Field(description="Comment body shown in the popup.")
+    author: str | None = Field(default=None)
+    subject: str | None = Field(default=None)
+    anchor_text: str | None = Field(
+        default=None,
+        description=(
+            "Optional text snippet to locate on the page; when set, the server anchors"
+            " the icon at the first matching line and ignores the x/y coords."
+        ),
+    )