Add endpoint to extract transaction information from a text.

Author: gjong

fintrack-api/src/main/java/com/jongsoft/finance/rest/transaction/TransactionExtractRequest.java

@@ -0,0 +1,10 @@
+package com.jongsoft.finance.rest.transaction;
+
+import io.micronaut.serde.annotation.Serdeable;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Serdeable
+record TransactionExtractRequest(
+        @Schema(description = "The text to extract the transaction information from.")
+        String fromText) {
+}

fintrack-api/src/main/java/com/jongsoft/finance/rest/transaction/TransactionSuggestionResource.java

@@ -1,13 +1,13 @@
 package com.jongsoft.finance.rest.transaction;
 
 import com.jongsoft.finance.core.RuleColumn;
+import com.jongsoft.finance.core.exception.StatusException;
 import com.jongsoft.finance.learning.SuggestionEngine;
 import com.jongsoft.finance.learning.SuggestionInput;
+import com.jongsoft.finance.learning.TransactionResult;
 import com.jongsoft.finance.rest.model.TagResponse;
 import com.jongsoft.finance.security.AuthenticationRoles;
-import io.micronaut.http.annotation.Body;
-import io.micronaut.http.annotation.Controller;
-import io.micronaut.http.annotation.Post;
+import io.micronaut.http.annotation.*;
 import io.micronaut.security.annotation.Secured;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
@@ -18,7 +18,7 @@
 import java.util.Optional;
 
 @Tag(name = "Transactions")
-@Controller("/api/transactions/suggestions")
+@Controller("/api/transactions")
 @Secured(AuthenticationRoles.IS_AUTHENTICATED)
 class TransactionSuggestionResource {
 
@@ -28,13 +28,12 @@ class TransactionSuggestionResource {
         this.suggestionEngine = suggestionEngine;
     }
 
-    @Post
+    @Post("suggestions")
     @Operation(
             operationId = "suggestTransaction",
             summary = "Suggest changes",
             description = "Suggest changes to a transaction based upon the rules in the system.")
     Map<String, ?> suggest(@Body TransactionForSuggestionRequest request) {
-
         var transactionInput = new SuggestionInput(
                 LocalDate.now(),
                 request.description(),
@@ -60,4 +59,14 @@ class TransactionSuggestionResource {
 
         return output;
     }
+
+    @Post("/generate-transaction")
+    @Operation(
+            operationId = "extractTransaction",
+            summary = "Extract transaction info",
+            description = "Extract transaction information from the presented text.")
+    public TransactionResult extractTransaction(TransactionExtractRequest request) {
+        return suggestionEngine.extractTransaction(request.fromText())
+                .orElseThrow(() -> StatusException.badRequest("No extractor configured.", "llm.not.configured"));
+    }
 }

learning/learning-module-llm/src/main/java/com/jongsoft/finance/llm/AiSuggestionEngine.java

@@ -3,7 +3,9 @@
 import com.jongsoft.finance.learning.SuggestionEngine;
 import com.jongsoft.finance.learning.SuggestionInput;
 import com.jongsoft.finance.learning.SuggestionResult;
+import com.jongsoft.finance.learning.TransactionResult;
 import com.jongsoft.finance.llm.agent.ClassificationAgent;
+import com.jongsoft.finance.llm.agent.TransactionExtractorAgent;
 import com.jongsoft.finance.llm.stores.ClassificationEmbeddingStore;
 import io.micronaut.context.annotation.Primary;
 import jakarta.inject.Singleton;
@@ -24,10 +26,15 @@ class AiSuggestionEngine implements SuggestionEngine {
 
     private final ClassificationEmbeddingStore embeddingStore;
     private final ClassificationAgent classificationAgent;
+    private final TransactionExtractorAgent transactionExtractorAgent;
 
-    public AiSuggestionEngine(ClassificationEmbeddingStore embeddingStore, ClassificationAgent classificationAgent) {
+    public AiSuggestionEngine(
+            ClassificationEmbeddingStore embeddingStore,
+            ClassificationAgent classificationAgent,
+            TransactionExtractorAgent transactionExtractorAgent) {
         this.embeddingStore = embeddingStore;
         this.classificationAgent = classificationAgent;
+        this.transactionExtractorAgent = transactionExtractorAgent;
     }
 
     @Override
@@ -47,6 +54,19 @@ public SuggestionResult makeSuggestions(SuggestionInput transactionInput) {
         return suggestions;
     }
 
+    @Override
+    public Optional<TransactionResult> extractTransaction(String transactionInput) {
+        var extracted = transactionExtractorAgent.extractTransaction(transactionInput);
+        return Optional.of(new TransactionResult(
+                extracted.type(),
+                extracted.date(),
+                extracted.fromAccount().name().isBlank() ? null : extracted.fromAccount().name(),
+                extracted.toAccount().name().isBlank() ? null : extracted.toAccount().name(),
+                extracted.description(),
+                extracted.amount()
+        ));
+    }
+
     private SuggestionResult fallbackToLLM(SuggestionInput transactionInput) {
         log.debug("No embedding found for the input, falling back to LLM.");
         var suggestion = classificationAgent.classifyTransaction(UUID.randomUUID(),

learning/learning-module-llm/src/test/java/com/jongsoft/finance/llm/AiSuggestionEngineTest.java

@@ -1,8 +1,13 @@
 package com.jongsoft.finance.llm;
 
+import com.jongsoft.finance.core.TransactionType;
 import com.jongsoft.finance.learning.SuggestionInput;
+import com.jongsoft.finance.learning.TransactionResult;
 import com.jongsoft.finance.llm.agent.ClassificationAgent;
+import com.jongsoft.finance.llm.agent.TransactionExtractorAgent;
+import com.jongsoft.finance.llm.dto.AccountDTO;
 import com.jongsoft.finance.llm.dto.ClassificationDTO;
+import com.jongsoft.finance.llm.dto.TransactionDTO;
 import com.jongsoft.finance.llm.stores.ClassificationEmbeddingStore;
 import org.junit.jupiter.api.Test;
 
@@ -20,7 +25,7 @@ class AiSuggestionEngineTest {
     void makeSuggestions() {
         // given
         var mockAiAgent = mock(ClassificationAgent.class);
-        var subject = new AiSuggestionEngine(mock(ClassificationEmbeddingStore.class), mockAiAgent);
+        var subject = new AiSuggestionEngine(mock(ClassificationEmbeddingStore.class), mockAiAgent, mock(TransactionExtractorAgent.class));
         var suggestion = new SuggestionInput(
                 LocalDate.of(2022, 1, 1),
                 "My transaction",
@@ -38,4 +43,31 @@ void makeSuggestions() {
                 .extracting("budget", "category", "tags")
                 .containsExactly("Food", "Groceries", List.of("shopping", "groceries"));
     }
+
+    @Test
+    void extractTransaction() {
+        var mockExtractionAgent = mock(TransactionExtractorAgent.class);
+        var subject = new AiSuggestionEngine(mock(ClassificationEmbeddingStore.class), mock(ClassificationAgent.class), mockExtractionAgent);
+
+        when(mockExtractionAgent.extractTransaction(anyString()))
+                .thenReturn(new TransactionDTO(
+                        new AccountDTO("Checking account", "checking"),
+                        new AccountDTO("Savings account", "savings"),
+                        "My transaction",
+                        LocalDate.of(2010, 1, 1),
+                        20.2D,
+                        TransactionType.DEBIT));
+
+        var answer = subject.extractTransaction("My transaction");
+
+        assertThat(answer)
+                .isPresent()
+                .contains(new TransactionResult(
+                        TransactionType.DEBIT,
+                        LocalDate.of(2010, 1, 1),
+                        "Checking account",
+                        "Savings account",
+                        "My transaction",
+                        20.2D));
+    }
 }

learning/learning-module/src/main/java/com/jongsoft/finance/learning/SuggestionEngine.java

@@ -1,7 +1,18 @@
 package com.jongsoft.finance.learning;
 
+import java.util.Optional;
+
 public interface SuggestionEngine {
 
     SuggestionResult makeSuggestions(SuggestionInput transactionInput);
 
+    /**
+     * Extracts a transaction based on the given input string and returns a {@code TransactionResult}.
+     *
+     * @param transactionInput the raw transaction input string to be processed
+     * @return a {@code TransactionResult} containing the extracted transaction data
+     */
+    default Optional<TransactionResult> extractTransaction(String transactionInput) {
+        return Optional.empty();
+    }
 }

learning/learning-module/src/main/java/com/jongsoft/finance/learning/TransactionResult.java

@@ -0,0 +1,8 @@
+package com.jongsoft.finance.learning;
+
+import com.jongsoft.finance.core.TransactionType;
+
+import java.time.LocalDate;
+
+public record TransactionResult(TransactionType type, LocalDate date, String from, String to, String description, double amount) {
+}