adding LLM parsing and FlexRequests

Author: Zach Ebner

README.md

@@ -13,7 +13,7 @@ The official Java SDK for the Textkernel Tx v10 API for resume/CV and job parsin
 ### Gradle Users
 Add this dependency to your project's build file:
 ```
-implementation "com.textkernel:tx-java:2.0.0"
+implementation "com.textkernel:tx-java:2.1.0"
 ```
 
 ### Maven Users
@@ -22,13 +22,13 @@ Add this dependency to your project's POM:
 <dependency>
   <groupId>com.textkernel</groupId>
   <artifactId>tx-java</artifactId>
-  <version>2.0.0</version>
+  <version>2.1.0</version>
 </dependency>
 ```
 
 ### Others
 You'll need to manually install the following JARs:
-- The Textkernel Tx JAR from https://repo1.maven.org/maven2/com/textkernel/tx-java/2.0.0/tx-java-2.0.0.jar
+- The Textkernel Tx JAR from https://repo1.maven.org/maven2/com/textkernel/tx-java/2.1.0/tx-java-2.1.0.jar
 - [Google Gson][gson_url] from https://repo1.maven.org/maven2/com/google/code/gson/gson/2.9.0/gson-2.9.0.jar
 - [Square OkHttp][okhttp_url] from https://repo1.maven.org/maven2/com/squareup/okhttp3/okhttp/4.9.3/okhttp-4.9.3.jar
 

pom.xml

@@ -4,7 +4,7 @@
     <groupId>com.textkernel</groupId>
     <artifactId>tx-java</artifactId>
 
-    <version>2.0.0</version>
+    <version>2.1.0</version>
 
     <packaging>jar</packaging>
     <name>Textkernel Tx Java SDK</name>

src/main/java/com/textkernel/tx/models/api/parsing/FlexRequest.java

@@ -0,0 +1,36 @@
+// Copyright © 2023 Textkernel BV. All rights reserved.
+// This file is provided for use by, or on behalf of, Textkernel licensees
+// within the terms of their license of Textkernel products or Textkernel customers
+// within the Terms of Service pertaining to the Textkernel SaaS products.
+
+
+package com.textkernel.tx.models.api.parsing;
+
+import java.util.List;
+
+/**
+ * Custom requests to ask during parsing. 
+ * See the <a href="https://developer.textkernel.com/tx-platform/v10/resume-parser/overview/llm-parser/#flex-requests">overview documentation</a> for more details.
+ * <a href="https://developer.textkernel.com/tx-platform/v10/overview/#transaction-cost">Additional charges</a> will apply.
+ */
+public class FlexRequest {
+    /**
+     * The prompt to be sent to the LLM Parsing Engine
+     */
+    public String Prompt;
+
+    /**
+     * Unique field name to be returned alongside the reply in the response
+     */
+    public String Identifier;
+
+    /**
+     * The data type for the reply
+     */
+    public FlexRequestDataType DataType;
+
+    /**
+     * If DataType is {@link FlexRequestDataType#Enumeration}, this is the list of possible replies. This is limited to a maximum of 50 values.
+     */
+    public List<String> EnumerationValues;
+}

src/main/java/com/textkernel/tx/models/api/parsing/FlexRequestDataType.java

@@ -0,0 +1,12 @@
+package com.textkernel.tx.models.api.parsing;
+
+/**
+ * Possible data types for FlexRequests
+ */
+public enum FlexRequestDataType {
+    Text,
+    Numeric,
+    Bool,
+    List,
+    Enumeration
+}

src/main/java/com/textkernel/tx/models/api/parsing/FlexResponse.java

@@ -0,0 +1,35 @@
+// Copyright © 2023 Textkernel BV. All rights reserved.
+// This file is provided for use by, or on behalf of, Textkernel licensees
+// within the terms of their license of Textkernel products or Textkernel customers
+// within the Terms of Service pertaining to the Textkernel SaaS products.
+
+
+package com.textkernel.tx.models.api.parsing;
+
+import java.util.List;
+
+/**
+ * Information about the FlexRequests transaction, if any were provided.
+ */
+public class FlexResponse {
+    
+    /** See https://developer.textkernel.com/tx-platform/v10/overview/#http-status-codes*/
+    public String Code;
+
+    /** A short human-readable description explaining the {@link #Code} value*/
+    public String Message;
+    
+    /**
+     * Responses to FlexRequests
+     */
+    public List<FlexResponseItem> Responses;
+
+    public boolean isSuccess() {
+        switch (Code) {
+            case "Success":
+                return true;
+        }
+
+        return false;
+    }
+}

src/main/java/com/textkernel/tx/models/api/parsing/FlexResponseItem.java

@@ -0,0 +1,31 @@
+// Copyright © 2023 Textkernel BV. All rights reserved.
+// This file is provided for use by, or on behalf of, Textkernel licensees
+// within the terms of their license of Textkernel products or Textkernel customers
+// within the Terms of Service pertaining to the Textkernel SaaS products.
+
+
+package com.textkernel.tx.models.api.parsing;
+
+import java.util.List;
+
+/**
+ * Responses to FlexRequests
+ */
+public class FlexResponseItem {
+    
+    /**
+     * Unique field name assigned to the respective FlexRequest
+     */
+    public String Identifier;
+
+    /**
+     * Reply to the FlexRequest Prompt
+     */
+    public String Reply;
+    
+    /**
+     * List of replies to the FlexRequest Prompt if the FlexRequest had a {@link FlexRequestDataType#Enumeration} DataType
+     */
+    public List<String> ReplyList;
+
+}

src/main/java/com/textkernel/tx/models/api/parsing/ParseOptions.java

@@ -5,6 +5,8 @@
 
 package com.textkernel.tx.models.api.parsing;
 
+import java.util.List;
+
 import com.textkernel.tx.models.api.geocoding.GeocodeOptions;
 import com.textkernel.tx.models.api.indexes.IndexSingleDocumentInfo;
 
@@ -41,6 +43,20 @@ public class ParseOptions extends BasicParseOptions {
     */
     public IndexSingleDocumentInfo IndexingOptions;
 
+    /**
+     * Only used for resumes. When {@code true}, and the document is English, the LLM Parser will be used. 
+     * See the <a href="https://developer.textkernel.com/tx-platform/v10/resume-parser/overview/llm-parser/#overview">overview documentation</a> for more information.
+     * <a href="https://developer.textkernel.com/tx-platform/v10/overview/#transaction-cost">Additional charges</a> will apply.
+    */
+    public boolean UseLLMParser;
+
+    /**
+     * Only used for resumes. Custom requests to ask during parsing. 
+     * See the <a href="https://developer.textkernel.com/tx-platform/v10/resume-parser/overview/llm-parser/#flex-requests">overview documentation</a> for more information.
+     * <a href="https://developer.textkernel.com/tx-platform/v10/overview/#transaction-cost">Additional charges</a> will apply.
+    */
+    public List<FlexRequest> FlexRequests;
+
     //********************************
     //IF YOU ADD ANY PARAMS HERE BE SURE TO ADD THEM IN THE DEEP COPY INSIDE ParseRequest.ctor() !!
     //********************************

src/main/java/com/textkernel/tx/models/api/parsing/ParseRequest.java

@@ -57,6 +57,8 @@ public ParseRequest(Document doc, ParseOptions optionsToUse) {
             this.SkillsData = optionsToUse.SkillsData;
             this.SkillsSettings = optionsToUse.SkillsSettings;
             this.ProfessionsSettings = optionsToUse.ProfessionsSettings;
+            this.UseLLMParser = optionsToUse.UseLLMParser;
+            this.FlexRequests = optionsToUse.FlexRequests;
         }
     }
 }

src/main/java/com/textkernel/tx/models/api/parsing/ParseResumeResponseValue.java

@@ -22,4 +22,9 @@ public class ParseResumeResponseValue extends BaseParseResponseValue {
      * this property will contain no {@link ParsedResume#ContactInformation}.
     */
     public ParsedResume RedactedResumeData;
+
+    /**
+     * Information about the FlexRequests transaction, if any were provided.
+    */
+    public FlexResponse FlexResponse;
 }

src/test/java/com/textkernel/tx/integration/ParsingTests.java

@@ -16,8 +16,6 @@
 import com.textkernel.tx.models.api.geocoding.GeocodeProvider;
 import com.textkernel.tx.models.api.indexes.IndexSingleDocumentInfo;
 import com.textkernel.tx.models.api.parsing.*;
-import com.textkernel.tx.models.api.parsing.SkillsSettings;
-import com.textkernel.tx.models.api.parsing.ParseJobResponseValue;
 
 import static org.junit.jupiter.api.Assertions.*;
 
@@ -35,6 +33,7 @@
 import java.nio.file.Files;
 import java.nio.file.Paths;
 import java.time.LocalDate;
+import java.util.ArrayList;
 import java.util.UUID;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.stream.Stream;
@@ -719,4 +718,36 @@ public void TestJobOrderProfessionNormalization() throws Exception {
         assertNotNull(response.Value.JobData.JobTitles.NormalizedProfession.ONET);
         assertNotEquals(0, response.Value.JobData.JobTitles.NormalizedProfession.Confidence);
     }
+    
+    @Test
+    public void TestLLMParse() throws Exception {
+        Document document = getTestFileAsDocument("resume.docx");
+        ParseOptions options = new ParseOptions();
+        options.UseLLMParser = true;
+        ParseResumeResponse response = Client.parseResume(new ParseRequest(document, options));
+
+        assertTrue(response.Info.isSuccess());
+        assertNotNull(response.Value.ResumeData.ContactInformation.CandidateName.GivenName);
+        assertNull(response.Value.ResumeData.Patents); // Patents is not parsed during LLM Parsing
+    }
+
+    @Test
+    public void TestFlexRequests() throws Exception {
+        Document document = getTestFileAsDocument("resume.docx");
+        ParseOptions options = new ParseOptions();
+        options.FlexRequests = new ArrayList<FlexRequest>();
+        FlexRequest prompt = new FlexRequest();
+        prompt.Prompt = "How many years has this person spent in a leadership position?";
+        prompt.DataType = FlexRequestDataType.Text;
+        prompt.Identifier = "YearsLeadership";
+        options.FlexRequests.add(prompt);
+        ParseResumeResponse response = Client.parseResume(new ParseRequest(document, options));
+
+        assertTrue(response.Info.isSuccess());
+        assertNotNull(response.Value.FlexResponse);
+        assertTrue(response.Value.FlexResponse.isSuccess());
+        assertNotNull(response.Value.FlexResponse.Responses);
+        assertEquals("YearsLeadership", response.Value.FlexResponse.Responses.get(0).Identifier);
+        assertNotNull(response.Value.FlexResponse.Responses.get(0).Reply);
+    }
 }