Skip to content

Commit bdb2b43

Browse files
MrGraversenMrGraversen
committed
📝 Add initial README
1 parent e2d77f5 commit bdb2b43

1 file changed

Lines changed: 218 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 218 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,218 @@
1-
# replicate-java
1+
# Replicate AI Integration with Java 21 ☕ & Spring Boot 🍃
2+
3+
Welcome to the Replicate AI Integration project! 🎉
4+
5+
This project provides a streamlined Java 21-based framework to effortlessly interact with and create predictions for **Replicate**'s
6+
powerful AI models. Built with **Spring Boot**, it enables quick and modular access to various AI services, making integration a breeze for
7+
developers.
8+
9+
The project allows downloading of **Replicate AI** models' JSONSchemas for requests and responses through the official API, and dynamically
10+
creates a Maven module to enable developers to interact with the AI models using strongly typed Java code.
11+
12+
Furthermore, it supports **Spring Boot AutoConfiguration**, allowing efficient and powerful integration with Spring Boot applications to
13+
enable easy access to **Replicate**'s AI offerings—just add your API key!
14+
15+
## 🚀 Quick Start
16+
17+
The quickest way to get off the ground is depending on `spring-boot-starter-replicate`. The module, provided an API key to Replicate,
18+
handles all configuration of the underlying modules to ensure a smooth start.
19+
20+
```xml
21+
22+
<dependency>
23+
<groupId>io.graversen</groupId>
24+
<artifactId>spring-boot-starter-replicate</artifactId>
25+
<version>0.0.8</version>
26+
</dependency>
27+
```
28+
29+
Add your Replicate API key to your `application.yml` file.
30+
31+
```yml
32+
replicate:
33+
token: r8...
34+
```
35+
36+
... And you're good to go!
37+
38+
## Replicate Models
39+
40+
By default, this project supports a number of common AI models for text completion using large language models and text-to-image models for
41+
image generation. Specifically, the following models are currently supported out of the box:
42+
43+
### Meta Llama 3
44+
45+
* [`meta-llama-3-8b-instruct`](https://replicate.com/meta/meta-llama-3-8b-instruct)
46+
* [`meta-llama-3-70b-instruct`](https://replicate.com/meta/meta-llama-3-70b-instruct)
47+
* [`meta-llama-3.1-405b-instruct`](https://replicate.com/meta/meta-llama-3.1-405b-instruct)
48+
49+
For the Llama 3 family of models, tokenization for text completion is supported by `spring-boot-starter-replicate`, making it easy to
50+
create and maintain stateful conversations.
51+
52+
### Black Forest Labs Flux
53+
54+
* [`flux-dev`](https://replicate.com/black-forest-labs/flux-dev)
55+
* [`flux-schnell`](https://replicate.com/black-forest-labs/flux-schnell)
56+
* [`flux-pro`](https://replicate.com/black-forest-labs/flux-pro)
57+
58+
---
59+
60+
> [!TIP]
61+
> It is possible to build this project to support different AI models that are not included by default for simplicity reasons.
62+
> Please see the section describing the `replicate-tools` module.
63+
64+
## 📂 Module Overview
65+
66+
Below is a more focused description of each discrete module of this project.
67+
68+
### `replicate-client`
69+
70+
Core module for handling API requests and responses from **Replicate**. Use this if you only want to create predictions with Java code in
71+
the simplest possible manner.
72+
73+
### `replicate-models`
74+
75+
Auto-generated models from **Replicate**’s JSONSchemas, providing strongly typed Java interfaces for AI models. The models supported are
76+
generated using `replicate-tools`. From this repository, the following packages are supported:
77+
78+
* [`default`](https://github.com/MrGraversen/replicate-java/packages/2297525?version=0.0.8-default): Default models as described above.
79+
* [`llama3`](https://github.com/MrGraversen/replicate-java/packages/2297525?version=0.0.8-llama3): A specialised module consisting only of
80+
the Llama 3 family of AI models.
81+
* [`flux`](https://github.com/MrGraversen/replicate-java/packages/2297525?version=0.0.8-flux): A specialised module consisting only of the
82+
Flux family of AI models.
83+
84+
### `replicate-tools`
85+
86+
Python project to interact with **Replicate** API services to get all JSONSchemas of supplied models.
87+
88+
### Example Usage
89+
90+
Install:
91+
92+
```shell
93+
python -m pip install --upgrade pip
94+
pip install -r replicate-tools/requirements.txt
95+
```
96+
97+
Run Python script with your supplied `REPLICATE_MODELS`.
98+
99+
> [!TIP]
100+
> The models follow a `owner` / `model-name` convention, just fetch it from the Replicate URL.
101+
> For example: `https://replicate.com/black-forest-labs/flux-dev` → `black-forest-labs/flux-dev`
102+
103+
```shell
104+
REPLICATE_API_TOKEN="r8..." REPLICATE_MODELS="meta/meta-llama-3-8b-instruct,black-forest-labs/flux-dev" python download_replicate_schemas.py
105+
```
106+
107+
After this, you are able to build the `replicate-models` module using Maven.
108+
109+
```shell
110+
mvn compile
111+
```
112+
113+
> [!TIP]
114+
> If you decide to use AI models that are more complex than simple text completion or text-to-image generators, note that you may depend on
115+
> just `replicate-client` and `replicate-models` with your custom set of models, to enable easy, strongly typed access to the Replicate API.
116+
117+
### `spring-boot-starter-replicate`
118+
119+
Auto-configures **Replicate** integration, provided an API token. Through this, you will have access to more advanced encapsulations to
120+
create images and manage conversations.
121+
122+
## 📈 Examples
123+
124+
### Example 1 - Conversations with Llama 3
125+
126+
```java
127+
128+
@Slf4j
129+
@RequiredArgsConstructor
130+
public class LlamaConversationExample {
131+
private final ConversationFacade conversationFacade;
132+
private final ConversationService conversationService;
133+
134+
/**
135+
* Simple example of exchanging one message with meta-llama-3-70b-instruct
136+
*/
137+
public void runExampleOne() {
138+
final var conversationOptions = new ConversationOptions(
139+
1.25 // temperature
140+
);
141+
142+
final var createConversation = new CreateConversation(
143+
"You are a friendly and witty assistant! Respond in one short sentence only.", // systemMessage
144+
Llama3Models.LLAMA_3_70B_INSTRUCT // meta-llama-3-70b-instruct
145+
);
146+
147+
final var conversation = conversationFacade.create(createConversation, conversationOptions);
148+
149+
conversationFacade.chat(conversation.getId(), TextMessage.user("Introduce yourself to me 😊")).whenComplete(logConversation());
150+
// => I'm LLaMA, your go-to sidekick for banter, advice, and getting stuff done, with a healthy dose of sarcasm and humor! 😉
151+
}
152+
153+
/**
154+
* Example of exchanging a "deeper" conversation with meta-llama-3-70b-instruct
155+
*/
156+
public void runExampleTwo() {
157+
final var conversationOptions = new ConversationOptions(
158+
0.75 // temperature
159+
);
160+
161+
final var createConversation = new CreateConversation(
162+
"You are a calculator app. Respond only with the result of the math query.", // systemMessage
163+
Llama3Models.LLAMA_3_70B_INSTRUCT // meta-llama-3-70b-instruct
164+
);
165+
166+
final var conversation = conversationFacade.create(createConversation, conversationOptions);
167+
168+
conversationFacade.chat(conversation.getId(), TextMessage.user("What is 2 + 2?")) // => 4
169+
.thenCompose(conversationFacade.chat(TextMessage.user("What is 3 * 3?"))) // => 9
170+
.thenCompose(conversationFacade.chat(TextMessage.user("What is seven minus two?"))) // => 5
171+
.whenComplete(logConversation());
172+
}
173+
174+
private BiConsumer<Conversation, Throwable> logConversation() {
175+
return (conversation, throwable) -> {
176+
if (throwable == null) {
177+
final var x = conversationService.getById(conversation.getId());
178+
log.info("{}", conversation.getConversation());
179+
} else {
180+
log.error(throwable.getMessage(), throwable);
181+
}
182+
};
183+
}
184+
}
185+
```
186+
187+
### Example 2 - Image generation with Flux
188+
189+
```java
190+
191+
@Slf4j
192+
@RequiredArgsConstructor
193+
public class FluxExample {
194+
private final ReplicateFacade replicateFacade;
195+
196+
/**
197+
* Create one image using flux-dev
198+
*/
199+
public void runExampleOne() {
200+
final var createImagePrediction = new CreateImagePrediction(
201+
TextToImagePrompt.portrait("A photo of a sheep on a grassy field on a beautiful summer day"),
202+
1, // outputs
203+
25, // inferenceSteps
204+
null // seed (random)
205+
);
206+
207+
replicateFacade.createPrediction(
208+
FluxModels.FLUX_DEV,
209+
createImagePrediction
210+
);
211+
}
212+
}
213+
```
214+
215+
---
216+
217+
> [!NOTE]
218+
> This project is still in the early stages of development.

0 commit comments

Comments
 (0)