Pdf comment agent (#6196)

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

engine/src/stirling/api/app.py

@@ -9,12 +9,14 @@ from pydantic_ai.models.instrumented import InstrumentationSettings
 
 from stirling.agents import ExecutionPlanningAgent, OrchestratorAgent, PdfEditAgent, PdfQuestionAgent, UserSpecAgent
 from stirling.agents.ledger import MathAuditorAgent
+from stirling.agents.pdf_comment import PdfCommentAgent
 from stirling.api.middleware import UserIdMiddleware
 from stirling.api.routes import (
     agent_draft_router,
     execution_router,
     ledger_router,
     orchestrator_router,
+    pdf_comments_router,
     pdf_edit_router,
     pdf_question_router,
     rag_router,
@@ -44,6 +46,7 @@ async def lifespan(fast_api: FastAPI):
     fast_api.state.user_spec_agent = UserSpecAgent(runtime)
     fast_api.state.execution_planning_agent = ExecutionPlanningAgent(runtime)
     fast_api.state.math_auditor_agent = MathAuditorAgent(runtime)
+    fast_api.state.pdf_comment_agent = PdfCommentAgent(runtime)
     tracer_provider = setup_posthog_tracking(settings)
     if tracer_provider:
         Agent.instrument_all(InstrumentationSettings(tracer_provider=tracer_provider))
@@ -61,6 +64,7 @@ app.include_router(agent_draft_router)
 app.include_router(execution_router)
 app.include_router(rag_router)
 app.include_router(ledger_router)
+app.include_router(pdf_comments_router)
 
 
 @app.get("/health", response_model=HealthResponse)

engine/src/stirling/api/dependencies.py

@@ -4,6 +4,7 @@ from fastapi import Request
 
 from stirling.agents import ExecutionPlanningAgent, OrchestratorAgent, PdfEditAgent, PdfQuestionAgent, UserSpecAgent
 from stirling.agents.ledger import MathAuditorAgent
+from stirling.agents.pdf_comment import PdfCommentAgent
 from stirling.rag import RagService
 from stirling.services import AppRuntime
 
@@ -42,3 +43,7 @@ def get_rag_embedding_model(request: Request) -> str:
 
 def get_math_auditor_agent(request: Request) -> MathAuditorAgent:
     return request.app.state.math_auditor_agent
+
+
+def get_pdf_comment_agent(request: Request) -> PdfCommentAgent:
+    return request.app.state.pdf_comment_agent

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)