feat: add langchain4j integration for llmprovider

Author: ugur-vaadin

pom.xml

@@ -98,6 +98,7 @@
         <jakarta.web.api.version>11.0.0</jakarta.web.api.version>
         <spring-data-commons.version>4.0.1</spring-data-commons.version>
         <reactor-core.version>3.8.2</reactor-core.version>
+        <langchain4j.version>1.10.0</langchain4j.version>
 
         <!-- spreadsheet -->
         <poi.version>5.5.1</poi.version>

vaadin-ai-components-flow-parent/vaadin-ai-components-flow/pom.xml

@@ -27,6 +27,12 @@
             <version>${project.version}</version>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>dev.langchain4j</groupId>
+            <artifactId>langchain4j</artifactId>
+            <version>${langchain4j.version}</version>
+            <optional>true</optional>
+        </dependency>
         <dependency>
             <groupId>io.projectreactor</groupId>
             <artifactId>reactor-core</artifactId>

vaadin-ai-components-flow-parent/vaadin-ai-components-flow/src/main/java/com/vaadin/flow/component/ai/provider/LLMProviderHelpers.java

@@ -0,0 +1,144 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.flow.component.ai.provider;
+
+import java.nio.ByteBuffer;
+import java.nio.charset.CharacterCodingException;
+import java.nio.charset.CodingErrorAction;
+import java.nio.charset.StandardCharsets;
+import java.util.Base64;
+import java.util.Objects;
+
+/**
+ * Utility methods for LLM provider implementations.
+ * <p>
+ * Intended only for internal use and can be removed in the future.
+ */
+public final class LLMProviderHelpers {
+
+    /**
+     * Supported content type categories for attachments.
+     */
+    public enum AttachmentContentType {
+        /** Image content types (image/*). */
+        IMAGE,
+        /** Text content types (text/*). */
+        TEXT,
+        /** PDF content types (application/pdf, application/x-pdf). */
+        PDF,
+        /** Unsupported or unknown content types. */
+        UNSUPPORTED;
+
+        /**
+         * Detects the content type category from a MIME type string.
+         *
+         * @param contentType
+         *            the MIME content type
+         * @return the corresponding category, or {@code UNSUPPORTED} if not
+         *         recognized
+         */
+        public static AttachmentContentType fromMimeType(String contentType) {
+            if (contentType != null) {
+                if (contentType.startsWith("image/")) {
+                    return IMAGE;
+                }
+                if (contentType.contains("text")) {
+                    return TEXT;
+                }
+                if (contentType.contains("pdf")) {
+                    return PDF;
+                }
+            }
+            return UNSUPPORTED;
+        }
+    }
+
+    /**
+     * Decodes byte array as UTF-8 text.
+     *
+     * @param data
+     *            the byte array to decode
+     * @param fileName
+     *            the file name for error messages
+     * @param strict
+     *            if {@code true}, throws exception on invalid UTF-8; if
+     *            {@code false}, replaces invalid sequences
+     * @return the decoded string
+     * @throws IllegalArgumentException
+     *             if {@code strict} is {@code true} and data contains invalid
+     *             UTF-8
+     */
+    public static String decodeAsUtf8(byte[] data, String fileName,
+            boolean strict) {
+        if (!strict) {
+            return new String(data, StandardCharsets.UTF_8);
+        }
+        var decoder = StandardCharsets.UTF_8.newDecoder()
+                .onMalformedInput(CodingErrorAction.REPORT)
+                .onUnmappableCharacter(CodingErrorAction.REPORT);
+        try {
+            return decoder.decode(ByteBuffer.wrap(data)).toString();
+        } catch (CharacterCodingException e) {
+            throw new IllegalArgumentException(
+                    "File '" + fileName + "' contains invalid UTF-8 data.", e);
+        }
+    }
+
+    /**
+     * Converts binary data to a Base64-encoded data URL.
+     *
+     * @param data
+     *            the binary data to encode
+     * @param contentType
+     *            the MIME content type (e.g., "image/png")
+     * @return a data URL in the format "data:{contentType};base64,{data}"
+     */
+    public static String toBase64DataUrl(byte[] data, String contentType) {
+        var base64 = Base64.getEncoder().encodeToString(data);
+        return "data:" + contentType + ";base64," + base64;
+    }
+
+    /**
+     * Formats text content as an attachment block.
+     *
+     * @param fileName
+     *            the file name to include in the attachment tag
+     * @param content
+     *            the text content
+     * @return formatted attachment string
+     */
+    public static String formatTextAttachment(String fileName, String content) {
+        return "\n<attachment filename=\"" + fileName + "\">\n" + content
+                + "\n</attachment>\n";
+    }
+
+    /**
+     * Validates that an attachment and its required fields are not
+     * {@code null}.
+     *
+     * @param attachment
+     *            the attachment to validate
+     * @throws NullPointerException
+     *             if attachment, content type, or data is {@code null}
+     */
+    public static void validateAttachment(LLMProvider.Attachment attachment) {
+        Objects.requireNonNull(attachment, "Attachment must not be null");
+        Objects.requireNonNull(attachment.contentType(),
+                "Attachment content type must not be null");
+        Objects.requireNonNull(attachment.data(),
+                "Attachment data must not be null");
+    }
+}