Skip to content

Commit b08d818

Browse files
mbelladembellade
committed
HBX-2996 New module containing natural language building blocks
1 parent 8a02715 commit b08d818

16 files changed

+3486
-0
lines changed

‎language/README.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
<!--
2+
~ Copyright 2010 - 2025 Red Hat, Inc.
3+
~
4+
~ Licensed under the Apache License, Version 2.0 (the "License");
5+
~ you may not use this file except in compliance with the License.
6+
~ You may obtain a copy of the License at
7+
~
8+
~ http://www.apache.org/licenses/LICENSE-2.0
9+
~
10+
~ Unless required by applicable law or agreed to in writing, software
11+
~ distributed under the License is distributed on an "AS IS" basis,
12+
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
~ See the License for the specific language governing permissions and
14+
~ limitations under the License.
15+
-->
16+
17+
[![Hibernate](https://static.jboss.org/hibernate/images/hibernate_200x150.png)](https://tools.hibernate.org)
18+
19+
# Hibernate Tools for Natural Language
20+
21+
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.
22+
23+
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.
24+
25+
WARNING: This entire module is currently incubating and may experience breaking changes at any time, including in a micro (patch) release.

‎language/pom.xml

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
~ Copyright 2010 - 2025 Red Hat, Inc.
4+
~
5+
~ Licensed under the Apache License, Version 2.0 (the "License");
6+
~ you may not use this file except in compliance with the License.
7+
~ You may obtain a copy of the License at
8+
~
9+
~ http://www.apache.org/licenses/LICENSE-2.0
10+
~
11+
~ Unless required by applicable law or agreed to in writing, software
12+
~ distributed under the License is distributed on an "AS IS" basis,
13+
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
~ See the License for the specific language governing permissions and
15+
~ limitations under the License.
16+
-->
17+
<project xmlns="http://maven.apache.org/POM/4.0.0"
18+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
19+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
20+
<modelVersion>4.0.0</modelVersion>
21+
<parent>
22+
<groupId>org.hibernate.tool</groupId>
23+
<artifactId>hibernate-tools-parent</artifactId>
24+
<version>7.0.1-SNAPSHOT</version>
25+
</parent>
26+
27+
<artifactId>hibernate-tools-language</artifactId>
28+
29+
<name>Hibernate Tools Natural Language</name>
30+
<description>
31+
Tools to aid Hibernate developers through natural language,
32+
leveraging LLMs and generative AI functionalities.
33+
</description>
34+
<packaging>jar</packaging>
35+
36+
<properties>
37+
<version.org.assertj.assertj-core>3.27.1</version.org.assertj.assertj-core>
38+
<version.com.fasterxml.jackson.core>2.19.0</version.com.fasterxml.jackson.core>
39+
</properties>
40+
41+
<dependencies>
42+
<dependency>
43+
<groupId>org.hibernate.orm</groupId>
44+
<artifactId>hibernate-core</artifactId>
45+
</dependency>
46+
47+
<!-- test only dependencies -->
48+
<dependency>
49+
<groupId>org.hibernate.orm</groupId>
50+
<artifactId>hibernate-testing</artifactId>
51+
<scope>test</scope>
52+
</dependency>
53+
<dependency>
54+
<groupId>com.h2database</groupId>
55+
<artifactId>h2</artifactId>
56+
<scope>test</scope>
57+
</dependency>
58+
<dependency>
59+
<groupId>org.junit.jupiter</groupId>
60+
<artifactId>junit-jupiter-engine</artifactId>
61+
<scope>test</scope>
62+
</dependency>
63+
<dependency>
64+
<groupId>org.assertj</groupId>
65+
<artifactId>assertj-core</artifactId>
66+
<version>${version.org.assertj.assertj-core}</version>
67+
<scope>test</scope>
68+
</dependency>
69+
<dependency>
70+
<groupId>com.fasterxml.jackson.core</groupId>
71+
<artifactId>jackson-core</artifactId>
72+
<version>${version.com.fasterxml.jackson.core}</version>
73+
<scope>test</scope>
74+
</dependency>
75+
<dependency>
76+
<groupId>com.fasterxml.jackson.core</groupId>
77+
<artifactId>jackson-databind</artifactId>
78+
<version>${version.com.fasterxml.jackson.core}</version>
79+
</dependency>
80+
</dependencies>
81+
82+
</project>

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

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
/*
2+
* Hibernate Tools, Tooling for your Hibernate Projects
3+
*
4+
* Copyright 2023-2025 Red Hat, Inc.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" basis,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
package org.hibernate.tool.language;
19+
20+
import org.hibernate.SharedSessionContract;
21+
import org.hibernate.query.SelectionQuery;
22+
23+
/**
24+
* Hibernate Assistant allows interacting with an underlying LLM to help you retrieve persistent data.
25+
* It leverages Hibernate ORM's mapping models, query language, cross-platform support and
26+
* build-in data restrictions to make access to information stored in relational databases
27+
* as easy as a natural language prompt.
28+
*/
29+
public interface HibernateAssistant {
30+
/**
31+
* Creates a {@link SelectionQuery} by providing the specified natural language {@code message} to the LLM
32+
* and interpreting the obtained response.
33+
*
34+
* @param message the natural language prompt
35+
* @param session Hibernate session
36+
*
37+
* @return the {@link SelectionQuery} generated by the LLM
38+
*/
39+
default SelectionQuery<?> createAiQuery(String message, SharedSessionContract session) {
40+
return createAiQuery( message, session, null );
41+
}
42+
43+
/**
44+
* Creates a {@link SelectionQuery} by providing the specified natural language {@code message} to the LLM
45+
* and interpreting the obtained response.
46+
*
47+
* @param message the natural language prompt
48+
* @param session Hibernate session
49+
* @param resultType The {@link Class} representing the expected query result type
50+
*
51+
* @return the {@link SelectionQuery} generated by the LLM
52+
*/
53+
<T> SelectionQuery<T> createAiQuery(String message, SharedSessionContract session, Class<T> resultType);
54+
55+
/**
56+
* Prompts the underlying LLM with the provided natural language message and tries to answer it with
57+
* data extracted from the database through the persistence model.
58+
*
59+
* @param message the natural language request
60+
* @param session Hibernate session
61+
*
62+
* @return a natural language response based on the results of the query
63+
*/
64+
String executeQuery(String message, SharedSessionContract session);
65+
66+
/**
67+
* Executes the given {@link SelectionQuery}, and provides a natural language
68+
* response by passing the resulting data back to the underlying LLM.
69+
* <p>
70+
* To directly obtain a natural language response from a natural language prompt,
71+
* you can use {@link #executeQuery(String, SharedSessionContract)} instead.
72+
* <p>
73+
* If you wish to execute the query manually and obtain the structured results yourself,
74+
* you should use {@link SelectionQuery}'s direct execution methods, e.g. {@link SelectionQuery#getResultList()}
75+
* or {@link SelectionQuery#getSingleResult()}.
76+
*
77+
* @param query the AI query to execute
78+
* @param session the session in which to execute the query
79+
*
80+
* @return a natural language response based on the results of the query
81+
*/
82+
String executeQuery(SelectionQuery<?> query, SharedSessionContract session);
83+
84+
/**
85+
* Reset the assistant's current chat context. This can be helpful when
86+
* creating a new {@link SelectionQuery} that should not rely on the context
87+
* of previous requests.
88+
*/
89+
void clear();
90+
}

0 commit comments

Comments
 (0)