Refactor transaction extraction and account lookup logic

gjong · gjong · commit 8a4faf1647d6 · 2025-04-16T17:04:51.000+02:00
Revised transaction extraction to include account IDs and enhanced fallback mechanisms for missing data. Improved account lookup logic using filters and enriched the handling of account details. Updated tests, DTOs, and configurations to align with these changes, ensuring better robustness and traceability.
diff --git a/fintrack-api/src/main/java/com/jongsoft/finance/rest/transaction/TransactionExtractResponse.java b/fintrack-api/src/main/java/com/jongsoft/finance/rest/transaction/TransactionExtractResponse.java
@@ -0,0 +1,30 @@
+package com.jongsoft.finance.rest.transaction;
+
+import com.jongsoft.finance.core.TransactionType;
+import com.jongsoft.finance.learning.TransactionResult;
+import io.micronaut.serde.annotation.Serdeable;
+
+import java.time.LocalDate;
+
+@Serdeable
+public record TransactionExtractResponse(
+        TransactionType type,
+        LocalDate date,
+        AccountRef from,
+        AccountRef to,
+        String description,
+        double amount) {
+
+    @Serdeable
+    public record AccountRef(long id, String name){}
+
+    public static TransactionExtractResponse from(TransactionResult transactionResult) {
+        return new TransactionExtractResponse(
+                transactionResult.type(),
+                transactionResult.date(),
+                new AccountRef(transactionResult.from().id(), transactionResult.from().name()),
+                new AccountRef(transactionResult.to().id(), transactionResult.to().name()),
+                transactionResult.description(),
+                transactionResult.amount());
+    }
+}
diff --git a/fintrack-api/src/main/java/com/jongsoft/finance/rest/transaction/TransactionSuggestionResource.java b/fintrack-api/src/main/java/com/jongsoft/finance/rest/transaction/TransactionSuggestionResource.java
@@ -4,10 +4,11 @@
 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.*;
+import io.micronaut.http.annotation.Body;
+import io.micronaut.http.annotation.Controller;
+import io.micronaut.http.annotation.Post;
 import io.micronaut.security.annotation.Secured;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
@@ -65,8 +66,9 @@ class TransactionSuggestionResource {
             operationId = "extractTransaction",
             summary = "Extract transaction info",
             description = "Extract transaction information from the presented text.")
-    public TransactionResult extractTransaction(TransactionExtractRequest request) {
+    public TransactionExtractResponse extractTransaction(@Body TransactionExtractRequest request) {
         return suggestionEngine.extractTransaction(request.fromText())
+                .map(TransactionExtractResponse::from)
                 .orElseThrow(() -> StatusException.badRequest("No extractor configured.", "llm.not.configured"));
     }
 }
diff --git a/fintrack-api/src/main/resources/docs/index.html b/fintrack-api/src/main/resources/docs/index.html
@@ -10,7 +10,7 @@
 </head>
 <body>
 <rapi-doc id="thedoc"
-          spec-url="/spec/fintrack-2.0.0.yml"
+          spec-url="/spec/pledger-2.0.0.yml"
           heading-text="FinTrack API"
           show-header="false"
           schema-style="table"
diff --git a/fintrack-api/src/main/resources/i18n/messages.properties b/fintrack-api/src/main/resources/i18n/messages.properties
@@ -589,10 +589,15 @@ validation.transaction.schedule.end.before.start=Start of the scheduled transact
 page.user.profile.import.account.lookup.info=During the import an account was found that is not mapped to an account in Pledger.io. Please either add it manually or correct the mapping below.
 page.settings.import.details.transactions.rules.run=Run transaction rules
 page.settings.currencies.edit=Edit currency
-page.setting.overview.setting.ImportOutdated=Import outdated entries
 page.accounts.liability.created.failed=Failed to create the liability account.
 page.login.welcome=Welcome back
 page.login.subtitle=Sign in to continue
 page.login.success=Login successful
 common.lang.or=or
 page.user.profile.two-factor=2-factor authentication
+page.transactions.process=Process transaction
+page.transactions.generate=Extract from text
+page.transactions.generate.info=Paste a transaction description from your bank statement to extract the relevant information.
+page.transactions.generated=Extracted transaction
+page.transactions.generate.confirm=Create transaction
+common.action.back=Back
diff --git a/learning/learning-module-llm/src/main/java/com/jongsoft/finance/llm/AiSuggestionEngine.java b/learning/learning-module-llm/src/main/java/com/jongsoft/finance/llm/AiSuggestionEngine.java
@@ -56,12 +56,16 @@ public SuggestionResult makeSuggestions(SuggestionInput transactionInput) {
 
     @Override
     public Optional<TransactionResult> extractTransaction(String transactionInput) {
-        var extracted = transactionExtractorAgent.extractTransaction(transactionInput);
+        var extracted = transactionExtractorAgent.extractTransaction(UUID.randomUUID(), 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(),
+                Optional.ofNullable(extracted.fromAccount())
+                        .map(e -> new TransactionResult.AccountResult(Optional.ofNullable(e.id()).orElse(-1L), e.name()))
+                        .orElse(null),
+                Optional.ofNullable(extracted.toAccount())
+                        .map(e -> new TransactionResult.AccountResult(Optional.ofNullable(e.id()).orElse(-1L), e.name()))
+                        .orElse(null),
                 extracted.description(),
                 extracted.amount()
         ));
diff --git a/learning/learning-module-llm/src/main/java/com/jongsoft/finance/llm/LanguageModelStarter.java b/learning/learning-module-llm/src/main/java/com/jongsoft/finance/llm/LanguageModelStarter.java
@@ -34,9 +34,11 @@ public ClassificationAgent transactionSupportAgent(
         log.info("Setting up transaction support chat agent.");
         var aiBuilder =  AiServices.builder(ClassificationAgent.class)
                 .chatLanguageModel(model)
-                .chatMemoryProvider(chatMemoryProvider())
-                .tools(aiTools.getTools());
+                .chatMemoryProvider(chatMemoryProvider());
 
+        if (aiTools.getTools().length > 0) {
+            aiBuilder.tools(aiTools.getTools());
+        }
         Optional.ofNullable(retrievalAugmentor).ifPresent(aiBuilder::retrievalAugmentor);
 
         return aiBuilder.build();
@@ -45,11 +47,15 @@ public ClassificationAgent transactionSupportAgent(
     @Bean
     public TransactionExtractorAgent transactionExtractorAgent(ChatLanguageModel model, ToolSupplier aiTools) {
         log.info("Setting up transaction extractor chat agent.");
-        return AiServices.builder(TransactionExtractorAgent.class)
+        var aiBuilder = AiServices.builder(TransactionExtractorAgent.class)
                 .chatLanguageModel(model)
-                .chatMemoryProvider(chatMemoryProvider())
-                .tools(aiTools.getTools())
-                .build();
+                .chatMemoryProvider(chatMemoryProvider());
+
+        if (aiTools.getTools().length > 0) {
+            aiBuilder.tools(aiTools.getTools());
+        }
+
+        return aiBuilder.build();
     }
 
     @Bean
diff --git a/learning/learning-module-llm/src/main/java/com/jongsoft/finance/llm/agent/TransactionExtractorAgent.java b/learning/learning-module-llm/src/main/java/com/jongsoft/finance/llm/agent/TransactionExtractorAgent.java
@@ -1,8 +1,12 @@
 package com.jongsoft.finance.llm.agent;
 
 import com.jongsoft.finance.llm.dto.TransactionDTO;
+import dev.langchain4j.service.MemoryId;
 import dev.langchain4j.service.SystemMessage;
 import dev.langchain4j.service.UserMessage;
+import dev.langchain4j.service.V;
+
+import java.util.UUID;
 
 @SystemMessage({
         """
@@ -15,7 +19,9 @@
                 Parse and extract transaction data from user-provided text.
                 Construct and return a JSON object (or array of objects, if multiple transactions) that exactly matches the TransactionDTO and AccountDTO schema.
                 Field requirements:
+                    - fromAccount.id: The unique identifier of the sender account.
                     - fromAccount.name: The name of the sender account (e.g., “My Savings”, “Bank of America”).
+                    - toAccount.id: The unique identifier of the receiver account.
                     - toAccount.name: The name of the receiver account (e.g., “John Doe”, “Amazon”, “Chase Checking”).
                     - type: One of debit, credit, or transfer, based on the context:
                         - debit = money received
@@ -25,8 +31,11 @@ Construct and return a JSON object (or array of objects, if multiple transaction
                     - amount: A non-negative number, parsed from the text (currency symbols are ignored).
                     - date: The date of the transaction, in YYYY-MM-DD format. Parse approximate or relative dates (e.g., “yesterday”).
 
+                The description field must be in the same language as the input text.
+                You must lookup the accounts using the tools provided to you.
                 If any field is missing or cannot be confidently inferred, leave it out of the output.
-                Return only the structured JSON data—do not include any commentary or explanations."""
+                Only return the JSON of the extracted transaction, do not include any other fields or reasoning.
+                ```"""
 })
 public interface TransactionExtractorAgent {
 
@@ -36,6 +45,8 @@ public interface TransactionExtractorAgent {
                     Only include fields that can be confidently identified.
                     Here's the text: {{input}}"""
     })
-    TransactionDTO extractTransaction(String input);
+    TransactionDTO extractTransaction(
+            @MemoryId UUID chat,
+            @V("input") String input);
 
 }
diff --git a/learning/learning-module-llm/src/main/java/com/jongsoft/finance/llm/augmenters/ClassificationAugmenter.java b/learning/learning-module-llm/src/main/java/com/jongsoft/finance/llm/augmenters/ClassificationAugmenter.java
@@ -46,8 +46,7 @@ public AugmentationResult augment(AugmentationRequest augmentationRequest) {
         throw new IllegalStateException("Could not augment a message of type " + augmentationRequest.chatMessage().getClass().getName());
     }
 
-    @Override
-    public UserMessage augment(UserMessage userMessage, Metadata metadata) {
+    private UserMessage augment(UserMessage userMessage, Metadata metadata) {
         var currentMessage = userMessage.singleText();
 
         String allowedList = "";
diff --git a/learning/learning-module-llm/src/main/java/com/jongsoft/finance/llm/dto/AccountDTO.java b/learning/learning-module-llm/src/main/java/com/jongsoft/finance/llm/dto/AccountDTO.java
@@ -4,6 +4,8 @@
 
 @Description("A financial account that can be used in transactions.")
 public record AccountDTO(
+        @Description("The unique identifier of the account.")
+        Long id,
         @Description("The name of the account.")
         String name,
         @Description("The type of the account, leave blank at all times.")
diff --git a/learning/learning-module-llm/src/main/java/com/jongsoft/finance/llm/dto/TransactionDTO.java b/learning/learning-module-llm/src/main/java/com/jongsoft/finance/llm/dto/TransactionDTO.java
@@ -13,7 +13,7 @@ public record TransactionDTO(
         AccountDTO toAccount,
         @Description("Write a short description for the transaction, excludes dates and amounts. Be creative.")
         String description,
-        @Description("The date of the transaction.")
+        @Description("The date of the transaction, in YYYY-MM-DD format.")
         LocalDate date,
         @Description("The amount of the transaction, cannot be a negative number.")
         double amount,
diff --git a/learning/learning-module-llm/src/main/java/com/jongsoft/finance/llm/models/OllamaModelSetup.java b/learning/learning-module-llm/src/main/java/com/jongsoft/finance/llm/models/OllamaModelSetup.java
@@ -14,6 +14,7 @@
 import dev.langchain4j.model.ollama.OllamaEmbeddingModel;
 import dev.langchain4j.model.ollama.OllamaModelCard;
 import dev.langchain4j.model.ollama.OllamaModels;
+import dev.langchain4j.rag.AugmentationResult;
 import dev.langchain4j.rag.RetrievalAugmentor;
 import io.micronaut.context.annotation.Bean;
 import io.micronaut.context.annotation.Factory;
@@ -55,7 +56,9 @@ RetrievalAugmentor classificationAugmenter(BudgetProvider budgetProvider, Catego
             return new ClassificationAugmenter(budgetProvider, categoryProvider, tagProvider);
         }
 
-        return (userMessage, metadata) -> userMessage;
+        return (userMessage) -> AugmentationResult.builder()
+                .chatMessage(userMessage.chatMessage())
+                .build();
     }
 
     @Bean
diff --git a/learning/learning-module-llm/src/main/java/com/jongsoft/finance/llm/tools/AccountLookupTool.java b/learning/learning-module-llm/src/main/java/com/jongsoft/finance/llm/tools/AccountLookupTool.java
@@ -1,6 +1,7 @@
 package com.jongsoft.finance.llm.tools;
 
 import com.jongsoft.finance.domain.account.Account;
+import com.jongsoft.finance.factory.FilterFactory;
 import com.jongsoft.finance.llm.AiEnabled;
 import com.jongsoft.finance.llm.dto.AccountDTO;
 import com.jongsoft.finance.providers.AccountProvider;
@@ -12,31 +13,40 @@
 @AiEnabled
 public class AccountLookupTool implements AiTool {
     private static final Logger LOGGER = org.slf4j.LoggerFactory.getLogger(AccountLookupTool.class);
-    private static final AccountDTO UNKNOWN_ACCOUNT = new AccountDTO("Unknown", "");
+    private static final AccountDTO UNKNOWN_ACCOUNT = new AccountDTO(-1L,"Unknown", "");
 
     private final AccountProvider accountProvider;
+    private final FilterFactory filterFactory;
 
-    public AccountLookupTool(AccountProvider accountProvider) {
+    public AccountLookupTool(AccountProvider accountProvider, FilterFactory filterFactory) {
         this.accountProvider = accountProvider;
+        this.filterFactory = filterFactory;
     }
 
-    @Tool("""
-            Fetches detailed account information based on the account name.
-            Use this to populate the fromAccount or toAccount fields when only the account name is known.
-            You have access to a tool named lookupAccount that allows you to retrieve information about a financial account by name.
-            Use this tool whenever you need to resolve an account name into an AccountDTO object.
-            
-            Only invoke this tool when you are ready to fill in account information using a recognized name.""")
+    @Tool("Fetch account information for a given account name.")
     public AccountDTO lookup(String accountName) {
-        LOGGER.trace("Ai tool looking up account information for {}.", accountName);
-        return accountProvider.lookup(accountName)
-                .map(this::convert)
-                .getOrSupply(() -> accountProvider.synonymOf(accountName)
-                        .map(this::convert)
-                        .getOrSupply(() -> UNKNOWN_ACCOUNT));
+        LOGGER.debug("Ai tool looking up account information for {}.", accountName);
+
+        var filter = filterFactory.account()
+                .name(accountName, false)
+                .page(0, 1);
+
+        var result = accountProvider.lookup(filter)
+                .content()
+                .map(this::convert);
+        if (result.isEmpty()) {
+            return accountProvider.synonymOf(accountName)
+                    .map(this::convert)
+                    .getOrSupply(() -> {
+                        LOGGER.trace("Ai tool could not find account information for {}.", accountName);
+                        return UNKNOWN_ACCOUNT;
+                    });
+        }
+
+        return result.head();
     }
 
     private AccountDTO convert(Account account) {
-        return new AccountDTO(account.getName(), account.getType());
+        return new AccountDTO(account.getId(), account.getName(), account.getType());
     }
 }
diff --git a/learning/learning-module-llm/src/test/java/com/jongsoft/finance/llm/AiSuggestionEngineTest.java b/learning/learning-module-llm/src/test/java/com/jongsoft/finance/llm/AiSuggestionEngineTest.java
@@ -49,10 +49,10 @@ void extractTransaction() {
         var mockExtractionAgent = mock(TransactionExtractorAgent.class);
         var subject = new AiSuggestionEngine(mock(ClassificationEmbeddingStore.class), mock(ClassificationAgent.class), mockExtractionAgent);
 
-        when(mockExtractionAgent.extractTransaction(anyString()))
+        when(mockExtractionAgent.extractTransaction(any(), anyString()))
                 .thenReturn(new TransactionDTO(
-                        new AccountDTO("Checking account", "checking"),
-                        new AccountDTO("Savings account", "savings"),
+                        new AccountDTO(1L,"Checking account", "checking"),
+                        new AccountDTO(2L,"Savings account", "savings"),
                         "My transaction",
                         LocalDate.of(2010, 1, 1),
                         20.2D,
@@ -65,8 +65,8 @@ void extractTransaction() {
                 .contains(new TransactionResult(
                         TransactionType.DEBIT,
                         LocalDate.of(2010, 1, 1),
-                        "Checking account",
-                        "Savings account",
+                        new TransactionResult.AccountResult(1L ,"Checking account"),
+                        new TransactionResult.AccountResult(2L ,"Savings account"),
                         "My transaction",
                         20.2D));
     }
diff --git a/learning/learning-module-llm/src/test/java/com/jongsoft/finance/llm/augmenters/ClassificationAugmenterTest.java b/learning/learning-module-llm/src/test/java/com/jongsoft/finance/llm/augmenters/ClassificationAugmenterTest.java
@@ -9,8 +9,12 @@
 import com.jongsoft.lang.Collections;
 import com.jongsoft.lang.Control;
 import dev.langchain4j.data.message.UserMessage;
+import dev.langchain4j.rag.AugmentationRequest;
+import dev.langchain4j.rag.query.Metadata;
+import org.assertj.core.api.InstanceOfAssertFactories;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
+import org.mockito.Mockito;
 
 import java.time.LocalDate;
 import java.util.Arrays;
@@ -45,11 +49,16 @@ void augmentForBudget() {
         when(budgetProvider.lookup(LocalDate.now().getYear(), LocalDate.now().getMonthValue()))
                 .thenReturn(Control.Option(budget));
 
-        var response = augmenter.augment(UserMessage.userMessage(messageBase.formatted("category")), null);
+        var response = augmenter.augment(augmentationRequest(messageBase.formatted("category")));
 
-        assertThat(response.singleText())
-                .isNotBlank()
-                .contains("You must choose from the following options: [Food,Transportation,Shopping,Entertainment]");
+        assertThat(response.chatMessage())
+                .isNotNull()
+                .asInstanceOf(InstanceOfAssertFactories.type(UserMessage.class))
+                .satisfies(e -> {
+                    assertThat(e.singleText())
+                            .contains("You must choose from the following options: [Food,Transportation,Shopping,Entertainment]");
+
+                });
     }
 
     @Test
@@ -60,11 +69,16 @@ void augmentForCategory() {
                         Category.builder().label("Food").build(),
                         Category.builder().label("Car").build()));
 
-        var response = augmenter.augment(UserMessage.userMessage(messageBase.formatted("subcategory")), null);
+        var response = augmenter.augment(augmentationRequest(messageBase.formatted("subcategory")));
+
+        assertThat(response.chatMessage())
+                .isNotNull()
+                .asInstanceOf(InstanceOfAssertFactories.type(UserMessage.class))
+                .satisfies(e -> {
+                    assertThat(e.singleText())
+                            .contains("You must choose from the following options: [Groceries,Food,Car]");
 
-        assertThat(response.singleText())
-                .isNotBlank()
-                .contains("You must choose from the following options: [Groceries,Food,Car]");
+                });
     }
 
     @Test
@@ -73,10 +87,19 @@ void augmentForTags() {
                 new com.jongsoft.finance.domain.transaction.Tag("food"),
                 new Tag("beverage")));
 
-        var response = augmenter.augment(UserMessage.userMessage(messageBase.formatted("tags")), null);
+        var response = augmenter.augment(augmentationRequest(messageBase.formatted("tags")));
+
+        assertThat(response.chatMessage())
+                .isNotNull()
+                .asInstanceOf(InstanceOfAssertFactories.type(UserMessage.class))
+                .satisfies(e -> {
+                    assertThat(e.singleText())
+                            .contains(
+                                    "You must choose from the following options: [food,beverage]");
+                });
+    }
 
-        assertThat(response.singleText())
-                .isNotBlank()
-                .contains("You must choose from the following options: [food,beverage]");
+    private AugmentationRequest augmentationRequest(String message) {
+        return new AugmentationRequest(UserMessage.userMessage(message), Mockito.mock(Metadata.class));
     }
-}
+}
diff --git a/learning/learning-module-llm/src/test/java/com/jongsoft/finance/llm/feature/TransactionExtractorAgentIT.java b/learning/learning-module-llm/src/test/java/com/jongsoft/finance/llm/feature/TransactionExtractorAgentIT.java
diff --git a/learning/learning-module-llm/src/test/java/com/jongsoft/finance/llm/tools/AccountLookupToolTest.java b/learning/learning-module-llm/src/test/java/com/jongsoft/finance/llm/tools/AccountLookupToolTest.java
diff --git a/learning/learning-module-llm/src/test/resources/en/extractor-data.json b/learning/learning-module-llm/src/test/resources/en/extractor-data.json
diff --git a/learning/learning-module/src/main/java/com/jongsoft/finance/learning/TransactionResult.java b/learning/learning-module/src/main/java/com/jongsoft/finance/learning/TransactionResult.java
diff --git a/settings.gradle.kts b/settings.gradle.kts

Original file line number	Diff line number	Diff line change
`@@ -46,8 +46,7 @@ public AugmentationResult augment(AugmentationRequest augmentationRequest) {`
`46`	`46`	`throw new IllegalStateException("Could not augment a message of type " + augmentationRequest.chatMessage().getClass().getName());`
`47`	`47`	`}`
`48`	`48`
`49`		`- @Override`
`50`		`- public UserMessage augment(UserMessage userMessage, Metadata metadata) {`
	`49`	`+ private UserMessage augment(UserMessage userMessage, Metadata metadata) {`
`51`	`50`	`var currentMessage = userMessage.singleText();`
`52`	`51`
`53`	`52`	`String allowedList = "";`