Add Java orchestrator to connect to the AI engine (Stirling-Tools#6003)

# Description of Changes
Add Java orchestration layer which can connect and go back and forth
with the AI engine to get results for the user. It's expected that the
AI engine will not be publicly available and this Java layer will always
be in front of it, to manage sessions and auth etc.

Author: jbrunton96

.gitignore

@@ -181,6 +181,7 @@ venv.bak/
 .idea/
 *.iml
 out/
+.junie/
 
 # Ignore Mac DS_Store files
 .DS_Store

app/common/src/main/java/stirling/software/common/model/ApplicationProperties.java

@@ -75,6 +75,7 @@ public class ApplicationProperties {
     private AutoPipeline autoPipeline = new AutoPipeline();
     private ProcessExecutor processExecutor = new ProcessExecutor();
     private PdfEditor pdfEditor = new PdfEditor();
+    private AiEngine aiEngine = new AiEngine();
 
     @Bean
     public PropertySource<?> dynamicYamlPropertySource(ConfigurableEnvironment environment)
@@ -231,6 +232,13 @@ public static class Library {
         }
     }
 
+    @Data
+    public static class AiEngine {
+        private boolean enabled = false;
+        private String url = "http://localhost:5001";
+        private int timeoutSeconds = 120;
+    }
+
     @Data
     public static class Legal {
         private String termsAndConditions;

app/core/src/main/resources/settings.yml.template

@@ -325,6 +325,11 @@ processExecutor:
     ghostscriptTimeoutMinutes: 30
     ocrMyPdfTimeoutMinutes: 30
 
+aiEngine:
+  enabled: false # Set to 'true' to enable the AI engine integration
+  url: http://localhost:5001 # URL of the Python AI engine
+  timeoutSeconds: 120 # Timeout in seconds for AI engine requests
+
 pdfEditor:
   fallback-font: classpath:/static/fonts/NotoSans-Regular.ttf # Override to point at a custom fallback font
   cache:

app/proprietary/src/main/java/stirling/software/proprietary/controller/api/AiEngineController.java

@@ -0,0 +1,83 @@
+package stirling.software.proprietary.controller.api;
+
+import java.io.IOException;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.ModelAttribute;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.server.ResponseStatusException;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+import jakarta.validation.Valid;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.proprietary.model.api.ai.AiWorkflowRequest;
+import stirling.software.proprietary.model.api.ai.AiWorkflowResponse;
+import stirling.software.proprietary.service.AiEngineClient;
+import stirling.software.proprietary.service.AiWorkflowService;
+
+import tools.jackson.core.JacksonException;
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.ObjectMapper;
+
+@Slf4j
+@RestController
+@RequestMapping("/api/v1/ai")
+@RequiredArgsConstructor
+@Tag(name = "AI Engine", description = "Endpoints for AI-powered PDF workflows")
+public class AiEngineController {
+
+    private final AiEngineClient aiEngineClient;
+    private final AiWorkflowService aiWorkflowService;
+    private final ObjectMapper objectMapper;
+
+    @GetMapping("/health")
+    @Operation(
+            summary = "AI engine health check",
+            description = "Returns the health status of the AI engine including configured models")
+    public ResponseEntity<String> health() throws IOException {
+        String response = aiEngineClient.get("/health");
+        return ResponseEntity.ok().contentType(MediaType.APPLICATION_JSON).body(response);
+    }
+
+    @PostMapping(value = "/orchestrate", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    @Operation(
+            summary = "Run an AI workflow against a PDF",
+            description =
+                    "Accepts a PDF upload and a user message and returns an AI workflow result")
+    public ResponseEntity<AiWorkflowResponse> orchestrate(
+            @Valid @ModelAttribute AiWorkflowRequest request) throws IOException {
+        return ResponseEntity.ok(aiWorkflowService.orchestrate(request));
+    }
+
+    @PostMapping(value = "/pdf/edit", consumes = MediaType.APPLICATION_JSON_VALUE)
+    @Operation(
+            summary = "Generate a PDF edit plan",
+            description =
+                    "Sends a user message to the PDF edit agent which returns a structured plan"
+                            + " of tool operations to perform")
+    public ResponseEntity<String> pdfEdit(@RequestBody String requestBody) throws IOException {
+        validateJson(requestBody);
+        String response = aiEngineClient.post("/api/v1/pdf/edit", requestBody);
+        return ResponseEntity.ok().contentType(MediaType.APPLICATION_JSON).body(response);
+    }
+
+    private void validateJson(String body) {
+        try {
+            objectMapper.readValue(body, JsonNode.class);
+        } catch (JacksonException e) {
+            throw new ResponseStatusException(
+                    HttpStatus.BAD_REQUEST, "Request body is not valid JSON");
+        }
+    }
+}

app/proprietary/src/main/java/stirling/software/proprietary/model/api/ai/AiPdfContentType.java

@@ -0,0 +1,57 @@
+package stirling.software.proprietary.model.api.ai;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonValue;
+
+/**
+ * Types of content that can be extracted from a PDF and sent to the AI.
+ *
+ * <p>Values MUST match {@code PdfContentType} in {@code engine/src/stirling/contracts/common.py}.
+ */
+public enum AiPdfContentType {
+    // Document-level structured data
+    PAGE_LAYOUT("page_layout"),
+    DOCUMENT_METADATA("document_metadata"),
+    ENCRYPTION_INFO("encryption_info"),
+    BOOKMARKS("bookmarks"),
+    LAYERS("layers"),
+    EMBEDDED_FILES("embedded_files"),
+    JAVASCRIPT("javascript"),
+    LINKS("links"),
+    IMAGE_INFO("image_info"),
+    FONTS("fonts"),
+
+    // Text and content
+    PAGE_TEXT("page_text"),
+    FULL_TEXT("full_text"),
+    FORM_FIELDS("form_fields"),
+    ANNOTATIONS("annotations"),
+    SIGNATURES("signatures"),
+    STRUCTURE_TREE("structure_tree"),
+    XMP_METADATA("xmp_metadata"),
+
+    // Heavy content
+    COMPLIANCE("compliance"),
+    IMAGES("images");
+
+    private final String value;
+
+    AiPdfContentType(String value) {
+        this.value = value;
+    }
+
+    @JsonValue
+    public String getValue() {
+        return value;
+    }
+
+    @JsonCreator
+    public static AiPdfContentType fromValue(String value) {
+        for (AiPdfContentType type : values()) {
+            if (type.value.equals(value)) {
+                return type;
+            }
+        }
+        throw new IllegalArgumentException("Unknown PDF content type: " + value);
+    }
+}

app/proprietary/src/main/java/stirling/software/proprietary/model/api/ai/AiWorkflowFileInput.java

@@ -0,0 +1,22 @@
+package stirling.software.proprietary.model.api.ai;
+
+import org.springframework.http.MediaType;
+import org.springframework.web.multipart.MultipartFile;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import jakarta.validation.constraints.NotNull;
+
+import lombok.Data;
+
+@Data
+@Schema(description = "A single PDF file input")
+public class AiWorkflowFileInput {
+
+    @NotNull
+    @Schema(
+            description = "The input PDF file",
+            contentMediaType = MediaType.APPLICATION_PDF_VALUE,
+            format = "binary")
+    private MultipartFile fileInput;
+}

app/proprietary/src/main/java/stirling/software/proprietary/model/api/ai/AiWorkflowFileRequest.java

@@ -0,0 +1,22 @@
+package stirling.software.proprietary.model.api.ai;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import lombok.Data;
+
+@Data
+@Schema(description = "Per-file content extraction request from the AI engine")
+public class AiWorkflowFileRequest {
+
+    @Schema(description = "Original filename of the requested file", example = "contract.pdf")
+    private String fileName;
+
+    @Schema(description = "Specific 1-based page numbers to extract from this file")
+    private List<Integer> pageNumbers = new ArrayList<>();
+
+    @Schema(description = "Content types to extract from this file")
+    private List<AiPdfContentType> contentTypes = new ArrayList<>();
+}

app/proprietary/src/main/java/stirling/software/proprietary/model/api/ai/AiWorkflowOutcome.java

@@ -0,0 +1,43 @@
+package stirling.software.proprietary.model.api.ai;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonValue;
+
+/**
+ * Discriminator values for AI workflow responses.
+ *
+ * <p>Values MUST match {@code WorkflowOutcome} in {@code engine/src/stirling/contracts/common.py}.
+ */
+public enum AiWorkflowOutcome {
+    ANSWER("answer"),
+    NOT_FOUND("not_found"),
+    NEED_CONTENT("need_content"),
+    PLAN("plan"),
+    NEED_CLARIFICATION("need_clarification"),
+    CANNOT_DO("cannot_do"),
+    TOOL_CALL("tool_call"),
+    COMPLETED("completed"),
+    UNSUPPORTED_CAPABILITY("unsupported_capability"),
+    CANNOT_CONTINUE("cannot_continue");
+
+    private final String value;
+
+    AiWorkflowOutcome(String value) {
+        this.value = value;
+    }
+
+    @JsonValue
+    public String getValue() {
+        return value;
+    }
+
+    @JsonCreator
+    public static AiWorkflowOutcome fromValue(String value) {
+        for (AiWorkflowOutcome outcome : values()) {
+            if (outcome.value.equals(value)) {
+                return outcome;
+            }
+        }
+        throw new IllegalArgumentException("Unknown AI workflow outcome: " + value);
+    }
+}

app/proprietary/src/main/java/stirling/software/proprietary/model/api/ai/AiWorkflowRequest.java

@@ -0,0 +1,23 @@
+package stirling.software.proprietary.model.api.ai;
+
+import java.util.List;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+
+import lombok.Data;
+
+@Data
+@Schema(description = "Run an AI workflow against one or more PDF files")
+public class AiWorkflowRequest {
+
+    @NotNull
+    @Schema(description = "The input PDF files")
+    private List<AiWorkflowFileInput> fileInputs;
+
+    @NotBlank
+    @Schema(description = "The user message to orchestrate", example = "Summarise these documents")
+    private String userMessage;
+}

app/proprietary/src/main/java/stirling/software/proprietary/model/api/ai/AiWorkflowResponse.java

@@ -0,0 +1,58 @@
+package stirling.software.proprietary.model.api.ai;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import lombok.Data;
+
+@Data
+@Schema(description = "Structured AI workflow result")
+public class AiWorkflowResponse {
+
+    @Schema(description = "Workflow outcome")
+    private AiWorkflowOutcome outcome;
+
+    @Schema(description = "Answer returned by the AI workflow when applicable")
+    private String answer;
+
+    @Schema(description = "Summary returned by the AI workflow when applicable")
+    private String summary;
+
+    @Schema(description = "Rationale returned by the AI workflow when applicable")
+    private String rationale;
+
+    @Schema(description = "Reason when the AI workflow cannot proceed")
+    private String reason;
+
+    @Schema(description = "Clarification question for the user when more input is required")
+    private String question;
+
+    @Schema(
+            description =
+                    "Unsupported capability identifier when the workflow cannot route the request")
+    private String capability;
+
+    @Schema(description = "Message returned for unsupported capability outcomes")
+    private String message;
+
+    @Schema(description = "Supporting evidence snippets from extracted PDF text")
+    private List<AiWorkflowTextSelection> evidence = new ArrayList<>();
+
+    @Schema(description = "Structured tool steps when the workflow returns a plan")
+    private List<Map<String, Object>> steps = new ArrayList<>();
+
+    @Schema(description = "Per-file text extraction requests from the AI engine")
+    private List<AiWorkflowFileRequest> files = new ArrayList<>();
+
+    @Schema(description = "Maximum number of pages the AI engine wants text extracted from")
+    private Integer maxPages;
+
+    @Schema(description = "Maximum number of characters the AI engine wants extracted")
+    private Integer maxCharacters;
+
+    @Schema(description = "AI engine capability to resume with on the next turn")
+    private String resumeWith;
+}