HBX-2996 New module containing natural language building blocks

language/README.md

@@ -0,0 +1,25 @@
+<!--
+  ~ Copyright 2010 - 2025 Red Hat, Inc.
+  ~
+  ~ 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.
+  -->
+
+[![Hibernate](https://static.jboss.org/hibernate/images/hibernate_200x150.png)](https://tools.hibernate.org)
+
+# Hibernate Tools for Natural Language
+
+This project contains the `HibernateAssistant` interface, which is aimed at providing a natural language interface to Hibernate ORM's persistence capabilities, through the capabilities of modern LLMs. **Its implementation is not included here**, but different providers can implement this interface with their own logic to interact with the underlying Generative AI model, taking advantage of the building blocks and utilities that _are_ included here.
+
+To be able to interact with different model providers, the `MetamodelSerializer` and `ResultsSerializer` SPIs can be used to generate a textual (JSON) representation of Hibernate's mapping model and data. This text can be easily fed to an LLM that will enable interacting with your database through simple natural language interactions.
+
+WARNING: This entire module is currently incubating and may experience breaking changes at any time, including in a micro (patch) release.

language/pom.xml

@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Copyright 2010 - 2025 Red Hat, Inc.
+  ~
+  ~ 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.
+  -->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>org.hibernate.tool</groupId>
+        <artifactId>hibernate-tools-parent</artifactId>
+        <version>7.0.1-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>hibernate-tools-language</artifactId>
+
+    <name>Hibernate Tools Natural Language</name>
+    <description>
+        Tools to aid Hibernate developers through natural language,
+        leveraging LLMs and generative AI functionalities.
+    </description>
+    <packaging>jar</packaging>
+
+    <properties>
+        <version.org.assertj.assertj-core>3.27.1</version.org.assertj.assertj-core>
+        <version.com.fasterxml.jackson.core>2.19.0</version.com.fasterxml.jackson.core>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.hibernate.orm</groupId>
+            <artifactId>hibernate-core</artifactId>
+        </dependency>
+
+        <!-- test only dependencies -->
+        <dependency>
+            <groupId>org.hibernate.orm</groupId>
+            <artifactId>hibernate-testing</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>com.h2database</groupId>
+            <artifactId>h2</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-engine</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <version>${version.org.assertj.assertj-core}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-core</artifactId>
+            <version>${version.com.fasterxml.jackson.core}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+            <version>${version.com.fasterxml.jackson.core}</version>
+        </dependency>
+    </dependencies>
+
+</project>

language/src/main/java/org/hibernate/tool/language/HibernateAssistant.java

@@ -0,0 +1,90 @@
+/*
+ * Hibernate Tools, Tooling for your Hibernate Projects
+ *
+ * Copyright 2023-2025 Red Hat, Inc.
+ *
+ * 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 org.hibernate.tool.language;
+
+import org.hibernate.SharedSessionContract;
+import org.hibernate.query.SelectionQuery;
+
+/**
+ * Hibernate Assistant allows interacting with an underlying LLM to help you retrieve persistent data.
+ * It leverages Hibernate ORM's mapping models, query language, cross-platform support and
+ * built-in data restrictions to make access to information stored in relational databases
+ * as easy as a natural language prompt.
+ */
+public interface HibernateAssistant {
+	/**
+	 * Creates a {@link SelectionQuery} by providing the specified natural language {@code message} to the LLM
+	 * and interpreting the obtained response.
+	 *
+	 * @param message the natural language prompt
+	 * @param session Hibernate session
+	 *
+	 * @return the {@link SelectionQuery} generated by the LLM
+	 */
+	default SelectionQuery<?> createAiQuery(String message, SharedSessionContract session) {
+		return createAiQuery( message, session, null );
+	}
+
+	/**
+	 * Creates a {@link SelectionQuery} by providing the specified natural language {@code message} to the LLM
+	 * and interpreting the obtained response.
+	 *
+	 * @param message the natural language prompt
+	 * @param session Hibernate session
+	 * @param resultType The {@link Class} representing the expected query result type
+	 *
+	 * @return the {@link SelectionQuery} generated by the LLM
+	 */
+	<T> SelectionQuery<T> createAiQuery(String message, SharedSessionContract session, Class<T> resultType);
+
+	/**
+	 * Prompts the underlying LLM with the provided natural language message and tries to answer it with
+	 * data extracted from the database through the persistence model.
+	 *
+	 * @param message the natural language request
+	 * @param session Hibernate session
+	 *
+	 * @return a natural language response based on the results of the query
+	 */
+	String executeQuery(String message, SharedSessionContract session);
+
+	/**
+	 * Executes the given {@link SelectionQuery}, and provides a natural language
+	 * response by passing the resulting data back to the underlying LLM.
+	 * <p>
+	 * To directly obtain a natural language response from a natural language prompt,
+	 * you can use {@link #executeQuery(String, SharedSessionContract)} instead.
+	 * <p>
+	 * If you wish to execute the query manually and obtain the structured results yourself,
+	 * you should use {@link SelectionQuery}'s direct execution methods, e.g. {@link SelectionQuery#getResultList()}
+	 * or {@link SelectionQuery#getSingleResult()}.
+	 *
+	 * @param query the AI query to execute
+	 * @param session the session in which to execute the query
+	 *
+	 * @return a natural language response based on the results of the query
+	 */
+	String executeQuery(SelectionQuery<?> query, SharedSessionContract session);
+
+	/**
+	 * Reset the assistant's current chat context. This can be helpful when
+	 * creating a new {@link SelectionQuery} that should not rely on the context
+	 * of previous requests.
+	 */
+	void clear();
+}