Pdf comment agent (#6196)

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

engine/src/stirling/api/routes/__init__.py

@@ -2,6 +2,7 @@ from .agent_drafts import router as agent_draft_router
 from .execution import router as execution_router
 from .ledger import router as ledger_router
 from .orchestrator import router as orchestrator_router
+from .pdf_comments import router as pdf_comments_router
 from .pdf_edit import router as pdf_edit_router
 from .pdf_questions import router as pdf_question_router
 from .rag import router as rag_router
@@ -11,6 +12,7 @@ __all__ = [
     "execution_router",
     "ledger_router",
     "orchestrator_router",
+    "pdf_comments_router",
     "pdf_edit_router",
     "pdf_question_router",
     "rag_router",

engine/src/stirling/api/routes/pdf_comments.py

@@ -0,0 +1,33 @@
+"""
+PDF Comment Agent (pdfCommentAgent) — FastAPI routes.
+
+One internal endpoint, called only by the Java PdfCommentAgentOrchestrator:
+
+  POST /api/v1/ai/pdf-comment-agent/generate
+      Java sends a PdfCommentRequest (prompt + positioned text chunks).
+      Python returns a PdfCommentResponse listing which chunks to comment on.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+
+from stirling.agents.pdf_comment import PdfCommentAgent
+from stirling.api.dependencies import get_pdf_comment_agent
+from stirling.contracts.pdf_comments import PdfCommentRequest, PdfCommentResponse
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/v1/ai/pdf-comment-agent", tags=["pdf-comment-agent"])
+
+
+@router.post("/generate", response_model=PdfCommentResponse)
+async def generate_endpoint(
+    request: PdfCommentRequest,
+    agent: Annotated[PdfCommentAgent, Depends(get_pdf_comment_agent)],
+) -> PdfCommentResponse:
+    """Generate review comments for the supplied text chunks."""
+    return await agent.generate(request)