Merge pull request #1617 from cescoffier/few-shot-doc

Few-shots, and Image guides

Author: geoand

docs/modules/ROOT/examples/io/quarkiverse/langchain4j/samples/fewshots/SentimentAiService.java

@@ -0,0 +1,22 @@
+package io.quarkiverse.langchain4j.samples.fewshots;
+
+import dev.langchain4j.service.SystemMessage;
+import dev.langchain4j.service.UserMessage;
+import io.quarkiverse.langchain4j.RegisterAiService;
+
+@RegisterAiService
+@SystemMessage("You are an assistant that classifies text sentiment.")
+public interface SentimentAiService {
+
+    @UserMessage("""
+                INPUT: This product is fantastic!   // <1>
+                OUTPUT: POSITIVE
+
+                INPUT: Terrible customer service.
+                OUTPUT: NEGATIVE
+
+                INPUT: {text}
+                OUTPUT:
+            """)
+    String classifySentiment(String text); // <2>
+}

docs/modules/ROOT/examples/io/quarkiverse/langchain4j/samples/fewshots/SentimentResource.java

@@ -0,0 +1,20 @@
+package io.quarkiverse.langchain4j.samples.fewshots;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.QueryParam;
+import jakarta.ws.rs.core.MediaType;
+
+@Path("/sentiment")
+@Produces(MediaType.TEXT_PLAIN)
+public class SentimentResource {
+    @Inject
+    SentimentAiService sentimentService;
+
+    @GET
+    public String analyze(@QueryParam("text") String text) {
+        return sentimentService.classifySentiment(text);
+    }
+}

docs/modules/ROOT/examples/io/quarkiverse/langchain4j/samples/images/Endpoint.java

@@ -0,0 +1,47 @@
+// tag::head[]
+package io.quarkiverse.langchain4j.samples.images;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.util.Base64;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.QueryParam;
+
+import dev.langchain4j.data.image.Image;
+
+@Path("/endpoint")
+public class Endpoint {
+
+    @Inject
+    ImageAiService imageAiService;
+
+    // end::head[]
+    // tag::url[]
+    @GET
+    @Path("/extract-menu")
+    public String fromUrl(@QueryParam("u") String url) { // <1>
+        return imageAiService.extractMenu(url);
+    }
+    // end::url[]
+
+    // tag::ocr[]
+    @GET
+    @Path("/ocr-process")
+    public String passingImage() throws IOException {
+        byte[] bytes = Files.readAllBytes(java.nio.file.Path.of("IMG_3283.jpg"));
+        String b64 = Base64.getEncoder().encodeToString(bytes);
+        Image img = Image.builder()
+                .base64Data(b64)
+                .mimeType("image/jpeg")
+                .build();
+
+        return imageAiService.extractReceiptData(img);
+    }
+    // end::ocr[]
+
+    // tag::head[]
+}
+// end::head[]

docs/modules/ROOT/examples/io/quarkiverse/langchain4j/samples/images/EndpointGeneration.java

@@ -0,0 +1,33 @@
+package io.quarkiverse.langchain4j.samples.images;
+
+import java.io.IOException;
+import java.net.URI;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+
+@Path("/endpoint")
+public class EndpointGeneration {
+
+    @Inject
+    ImageGenerationAiService imageGenerationAiService;
+
+    @GET
+    @Path("/generate-image")
+    @Produces("image/png")
+    public byte[] generateImage() {
+        var image = imageGenerationAiService.generateImage("a rabbit in a space suit");
+        return readBytes(image.url());
+    }
+
+    private byte[] readBytes(URI url) {
+        try (var is = url.toURL().openStream()) {
+            return is.readAllBytes();
+        } catch (IOException e) {
+            throw new RuntimeException("Failed to read image from URL: " + url, e);
+        }
+    }
+
+}

docs/modules/ROOT/examples/io/quarkiverse/langchain4j/samples/images/ImageAiService.java

@@ -0,0 +1,34 @@
+// tag::head[]
+package io.quarkiverse.langchain4j.samples.images;
+
+import dev.langchain4j.data.image.Image;
+import dev.langchain4j.service.SystemMessage;
+import dev.langchain4j.service.UserMessage;
+import io.quarkiverse.langchain4j.ImageUrl;
+import io.quarkiverse.langchain4j.RegisterAiService;
+
+@RegisterAiService
+@SystemMessage("Extract and summarize text from the provided image.")
+public interface ImageAiService {
+    // end::head[]
+
+    // tag::url[]
+    @UserMessage("""
+            Here is a menu image.
+            Extract the list of items.
+            """)
+    String extractMenu(@ImageUrl String imageUrl); // <1>
+    // end::url[]
+
+    // tag::ocr[]
+    @UserMessage("""
+            Extract the content of this receipt.
+            Identify the vendor, date, location and paid amount and currency (euros or USD).
+            Make sure the paid amount includes VAT.
+            For each information, add the line from the receipt where you found it.
+            """)
+    String extractReceiptData(Image image); // <1>
+    // end::ocr[]
+    // tag::head[]
+}
+// end::head[]

docs/modules/ROOT/examples/io/quarkiverse/langchain4j/samples/images/ImageGenerationAiService.java

@@ -0,0 +1,21 @@
+// tag::head[]
+package io.quarkiverse.langchain4j.samples.images;
+
+import dev.langchain4j.data.image.Image;
+import dev.langchain4j.service.SystemMessage;
+import dev.langchain4j.service.UserMessage;
+import io.quarkiverse.langchain4j.RegisterAiService;
+
+@RegisterAiService
+@SystemMessage("You are an AI that generates images from text prompts.")
+public interface ImageGenerationAiService {
+    // end::head[]
+
+    // tag::generation[]
+    @UserMessage("Generate an image of a {subject}.")
+    Image generateImage(String subject);
+    // end::generation[]
+
+    // tag::head[]
+}
+// end::head[]

docs/modules/ROOT/nav.adoc

@@ -11,20 +11,23 @@
 [.list-top-item]
 .Guides
 
+* xref:guide-few-shots.adoc[Using few-shots in prompts]
 * xref:guide-prompt-engineering.adoc[Prompt engineering patterns]
 // * xref:guide-ai-services-patterns.adoc[AI Services patterns]
 * xref:guide-fault-tolerance.adoc[Fault Tolerance]
 * xref:guide-csv.adoc[Index CSVs in a RAG pipeline]
 * xref:guide-web-search.adoc[Using Tavily Web Search]
+* xref:guide-passing-image.adoc[Passing Images to Models]
+* xref:guide-generating-image.adoc[Generating Images]
 // * xref:guide-agentic-patterns.adoc[Implementing Agentic patterns]
 // * xref:guide-structured-output.adoc[Returning structured data from a model]
 // * xref:guide-streamed-responses.adoc[Using function calling]
 // * xref:guide-log.adoc[Logging Model Interactions]
 // * xref:guide-token.adoc[Tracking token usages]
-// * xref:guide-few-shots.adoc[Using few-shots in prompts]
+
 // * xref:guide-local-models.adoc[Using local models]
 // * xref:guide-in-process-models.adoc[Using in-process models]
-// * xref:guide-passing-images.adoc[Passing Images to Models]
+
 // * xref:guide-generating-images.adoc[Generating Images from Prompts]
 // Add evaluation and guardrails and testing guides
 // Give knowledge to AI models

docs/modules/ROOT/pages/guide-few-shots.adoc

@@ -0,0 +1,80 @@
+= Implementing Few-Shot Prompting
+
+include::./includes/attributes.adoc[]
+include::./includes/customization.adoc[]
+
+Few-shot prompting lets you guide an LLM by embedding a handful of input–output examples directly in the prompt—no fine-tuning required.
+It strikes a balance between zero-shot and one-shot prompting, boosting accuracy on tasks like classification, extraction, and summarization while keeping your code simple.
+
+This guide walks you through three implementation steps to build a sentiment-classification microservice using Quarkus LangChain4j.
+
+== What is the Few-Shot Technique
+
+Few-shot prompting is an in-context learning technique where you provide two or more _input–output demonstrations_ in the same prompt to establish a pattern the model can generalize.
+This approach:
+
+* Improves accuracy over zero- and one-shot prompting for complex tasks.
+* Avoids the overhead of model fine-tuning or external retrieval.
+* Is ideal for tasks requiring a consistent output format or style.
+
+However, this technique is not intended to be used to add new knowledge to the model, but rather to guide its output style and format.
+
+== Step 1. Define the AI service
+
+Declare your AI Service interface with CDI and LangChain4j annotations so Quarkus can manage it:
+In this example, we will create a service that classifies text sentiment as either positive or negative.
+
+[source,java]
+----
+package io.quarkiverse.langchain4j.samples.fewshots;
+
+import dev.langchain4j.service.SystemMessage;
+import dev.langchain4j.service.UserMessage;
+import io.quarkiverse.langchain4j.RegisterAiService;
+
+
+@RegisterAiService
+@SystemMessage("You are an assistant that classifies text sentiment.")
+public interface SentimentAiService {
+    // few-shot method defined in Step 2
+}
+----
+
+Here, `@RegisterAiService` creates the xref:ai-services.adoc[AI Service], and `@SystemMessage` supplies the global instruction for all methods in the service.
+
+== Step 2. Add Few-Shots
+
+Inside the same interface, define a method with `@UserMessage` that inlines your examples:
+
+[source,java]
+----
+include::{examples-dir}/io/quarkiverse/langchain4j/samples/fewshots/SentimentAiService.java[]
+----
+
+<1>	The multi-line string contains two complete "INPUT: … OUTPUT: …" pairs followed by the placeholder `\{text}` for the new query.
+<2> When the method is invoked, Quarkus Langchain4j will replace `\{text}` with the actual text parameter.
+
+[TIP]
+While in this example we added the few-shot example in the user message, they can also be added in the system message.
+
+== Step 3. Invoke the AI Service from an HTTP Endpoint
+
+Finally, expose a REST resource that injects and calls your AI Service:
+
+[source,java]
+----
+include::{examples-dir}/io/quarkiverse/langchain4j/samples/fewshots/SentimentResource.java[]
+----
+
+This `SentimentResource` bean handles HTTP GET requests, delegates to the few-shot prompt method, and returns the classification.
+The endpoint can be tested with a simple HTTP client or browser by accessing:
+
+[source,curl]
+----
+curl http://localhost:8080/sentiment?text=I%20love%20this%20product!
+----
+
+== Conclusion
+
+By defining an AI service, embedding a few-shot prompt, and wiring it to a REST endpoint, you’ve built a complete sentiment-classification microservice with minimal code.
+Find more details about the few-shot technique in the xref:guide-prompt-engineering.adoc#few-shot[Prompt Engineering Guide].

docs/modules/ROOT/pages/guide-generating-image.adoc

@@ -0,0 +1,73 @@
+= Generating Images
+
+include::./includes/attributes.adoc[]
+include::./includes/customization.adoc[]
+
+Text completions are powerful, but many modern AI use cases also demand image generation.
+With Quarkus LangChain4j’s Image model support, you can declare a service method that returns a `dev.langchain4j.data.image.Image` instance, letting your microservice request, receive, and expose AI‐generated visuals seamlessly.
+
+== Prerequisites
+
+* A Quarkus project with the `quarkus-langchain4j-openai` extension on the classpath (or another model provider that supports image models)
+* OpenAI (or another provider) API Key configured in `application.properties` or via `QUARKUS_LANGCHAIN4J_OPENAI_API_KEY`
+* An **Image Model** enabled (e.g. `dall-e-3` or `GPT-Image-1`) in your config:
+
+[source,properties]
+----
+quarkus.langchain4j.openai.api-key=${OPENAI_API_KEY}
+quarkus.langchain4j.openai.image-model.model-name=dall-e-3 # This is the default model, but you can specify another one if needed
+----
+
+* Extended timeout for image generation, which can take longer than text completions. For example:
+
+[source,properties]
+----
+quarkus.langchain4j.openai.timeout=60s
+----
+
+== Step 1. Define the AI service
+
+Declare an AI Service interface to encapsulate image generation calls:
+
+[source,java]
+----
+include::{examples-dir}/io/quarkiverse/langchain4j/samples/images/ImageGenerationAiService.java[tags=head]
+----
+
+Here, `@RegisterAiService` creates the xref:ai-services.adoc[AI Service], and `@SystemMessage` supplies the global instruction for all methods in the service.
+
+== Step 2. Define the Generation Method
+
+Add a method annotated with `@UserMessage` that returns Image.
+Quarkus LangChain4j will call the configured image model and wrap the response in an `Image` object.
+
+[source,java]
+----
+include::{examples-dir}/io/quarkiverse/langchain4j/samples/images/ImageGenerationAiService.java[tags=head;generation]
+----
+
+When invoked, Quarkus will substitute the subject into the prompt, send it to the AI model provider, and return the generated image (URL or Base64).
+
+NOTE: When using OpenAI image model, the returned `Image` object contains a URL to the generated image, which you can use to display or download the image.
+
+
+== Step 3. Expose an HTTP Endpoint
+
+Finally, expose a REST resource that injects and calls your AI Service:
+
+Use the `Image` data type for local or in-memory images:
+
+[source,java]
+----
+include::{examples-dir}/io/quarkiverse/langchain4j/samples/images/EndpointGeneration.java[]
+----
+
+== Conclusion
+
+You’ve now seen how to:
+1.	Register an image‐generation AI service (`@RegisterAiService`).
+2.	Declare a method returning `Image` with `@UserMessage`.
+3.	Expose a REST endpoint that returns the generated image back to clients.
+
+With this pattern, you can build rich, AI‐driven visual applications—everything from dynamic marketing graphics to in‐app illustration.
+