Agentic AI Fraud Detection in Plain Java

An open-source initiative demonstrating how to build intelligent, autonomous systems using Plain Java and the Tools4AI framework.

This project shows that you don't need heavy frameworks or complex Python stacks to build sophisticated AI Agents. You can remain in the type-safe, performant world of Java while leveraging the power of Large Language Models (LLMs).

Code for the article is here https://github.com/vishalmysore/frauddetectionagentinjava

---

💡 The Core Initiative: Language as Code

The goal of this project is to showcase Natural Language Intent Mapping. Instead of writing complex controllers or parsers, we let the AI understand the user's intent and map it directly to Java methods.

1. NLP Intent Mapping: From Language to Logic

Imagine a user types:

"Analyze transaction of $25000 from Oakhaven at 2am"

In a traditional system, you'd need a CLI parser, a REST endpoint, and complex Regex. Here, we simply define an @Action in a Plain Old Java Object (POJO):

@Agent(groupName = "Transaction Analysis")
public class TransactionAnalysisAction {

    @Action(description = "Analyze a single transaction for fraud indicators")
    public String analyzeTransaction(Transaction transaction) {
        // transaction is already populated with $25000, "Oakhaven", and "2am"
        // purely via NLP mapping!
        return process(transaction);
    }
}

Executing it is just one line:

AIProcessor processor = PredictionLoader.getInstance().createOrGetAIProcessor();
String result = (String) processor.processSingleAction("Analyze transaction of $25000 from Oakhaven at 2am");

---

How the mapping works (Under the hood):
When you pass the string "Analyze transaction of $25000 from Oakhaven at 2am", the framework automatically extracts:

• amount -> 25000
• location -> "Oakhaven"
• timestamp -> (converted to internal format if needed, or mapped to a String field)

This is mapped directly to your Transaction POJO:

public class Transaction {
    private Double amount;
    private String location;
    private String timestamp;
    // Getters and Setters...
}

No manual parsing, no complex logic—just plain Java objects.

---

2. Dynamic Rules: Unstructured Logic to Structured POJOs

Business rules shouldn't be hard-coded. We use the PromptTransformer to turn human-readable text into Java objects at runtime.

The Unstructured Logic (rules.txt)

Flag transactions from Oakhaven or Shadowreach as high risk.
Target amount threshold is 10000.
Odd hours are between 11 PM and 6 AM.

The Transformation Code

// Transform plain English into a validated Java object
OpenAIPromptTransformer transformer = new OpenAIPromptTransformer();
String text = Files.readString(Paths.get("rules.txt"));

FraudRules rules = (FraudRules) transformer.transformIntoPojo(text, FraudRules.class);

// Now your logic is dynamic but type-safe
if (transaction.getAmount() > rules.getHighAmountThreshold()) {
    indicators.add("HIGH_AMOUNT");
}

---

3. Intent Chaining: Orchestrating Actions via NLP

Agents can "talk" to other agents' actions using the same natural language interface. This creates a flexible, decoupled orchestration layer.

@Action(description = "Run full fraud investigation")
public String investigateFraudCase(Transaction transaction, CustomerProfile customer) {
    // Intent-based mapping - The framework finds the 'analyzeTransaction' action
    String analysis = (String) getProcessor().processSingleAction(
        "Analyze transaction " + transaction.getTransactionId() + " from " + transaction.getLocation()
    );

    // The framework finds the 'assessFraudRisk' action in FraudDetectionAction
    FraudAlert alert = (FraudAlert) getProcessor().processSingleAction(
        "Calculate fraud risk for customer " + customer.getCustomerId()
    );

    // Intent: "Get transaction history for customer CUST-123 last 30 days"
    // This AUTOMATICALLY maps to FraudDetectionAction.getTransactionHistory()
    Map<String, Object> history = (Map<String, Object>) getProcessor().processSingleAction(
            "Get transaction history for customer " + customer.getCustomerId() + " last 30 days");

    return generateReport(analysis, alert, history);
}

How the Agent finds the right code:

1. The Query: "Get transaction history..."
2. The Discovery: Tools4AI scans @Action(description = "Check customer transaction history for patterns") in FraudDetectionAction.java.
3. The Parameter Extraction: The framework extracts the days parameter (30) from the phrase "last 30 days" and maps it to the @Prompt annotated argument in the method.

---

## � See it in Action: Real Logs

The best way to understand the power of this initiative is to see what happens inside the JVM during execution.

### 1. Semantic Parameter Extraction
When the system receives a query like *"Analyze transaction of $25000 from Oakhaven"*, the framework extracts the parameters and populates the Java fields automatically:

text
[main] INFO com.t4a.processor.OpenAiActionProcessor - {
"methodName": "analyzeTransaction",
"parameters": [{
"name": "arg0",
"fields": [
{
"fieldName": "amount",
"fieldType": "double",
"fieldValue": 25000.0
},
{
"fieldName": "merchant",
"fieldType": "String",
"fieldValue": "Oakhaven"
}
],
"type": "io.github.vishalmysore.fraud.domain.Transaction"
}]
}

### 2. Autonomous Rule Transformation
The internal `RuleLoader` converts unstructured text into a validated Java POJO. Notice the audit trail ensuring safety:

text
Audit: Attempting to load and transform fraud rules...
Audit: Rules successfully transformed and validated.
[main] INFO com.t4a.JsonUtils - {
"className": "io.github.vishalmysore.fraud.domain.FraudRules",
"fields": [
{"fieldName": "highRiskLocations", "fieldValue": ["Oakhaven", "Shadowreach", "Veridiania", "Frostholm"]},
{"fieldName": "highAmountThreshold", "fieldValue": 10000},
{"fieldName": "nightStartHour", "fieldValue": 23},
{"fieldName": "nightEndHour", "fieldValue": 6}
]
}

### 3. Multi-Agent Orchestration Trace
In a full investigation, one agent triggers multiple actions using plain language. The audit trail shows the coordination:

text
=== FRAUD MONITORING AUDIT TRAIL ===
[2026-02-01 09:34:57] WORKING - Step 1: Analyzing transaction patterns...
[2026-02-01 09:35:06] WORKING - Step 2: Calculating risk score...
[2026-02-01 09:35:22] WORKING - Step 3: Reviewing transaction history...
[2026-02-01 09:36:14] COMPLETED - Investigation complete
=== END AUDIT TRAIL ===

---

## �🛠️ Key Features of the Initiative

*   **Plain Java approach**: No heavy spring-boot or complex infrastructure required.
*   **Zero-Parser Logic**: No more writing Regex or JSON parsers for user input.
*   **Deterministic Execution**: While rule *loading* uses AI, the *execution* of the business logic is standard, debuggable Java.
*   **Human-in-the-Loop**: Seamlessly pause AI execution to wait for a human approval decision.

---

## 🚀 Getting Started

### Prerequisites
*   Java 18+
*   Maven 3.6+
*   OpenAI API Key (set in `tools4ai.properties`)

### Quick Run

bash
mvn clean install
mvn exec:java -Dexec.mainClass="io.github.vishalmysore.fraud.FraudDetectionExample"

### Example Queries to Try:
1.  *"Check for fraud in transaction of $50000 from Shadowreach"*
2.  *"Assess investigation report for user CUST-456"*
3.  *"Freeze account ACC-12345 due to fraudulent wire transfer"*

---

## 🎯 Vision
This initiative is meant to inspire Java developers to embrace AI internal to their existing codebases. By using language as an interface, we can build systems that are more flexible, easier to maintain, and closer to real business requirements.

Built with [Tools4AI](https://github.com/vishalmysore/tools4ai).