javadoc

Author: michael-ameri

gemini-api/src/main/java/swiss/ameri/gemini/api/Content.java

@@ -3,23 +3,43 @@
 import java.util.List;
 import java.util.Locale;
 
+/**
+ * Content which can be sent to gemini API.
+ */
 public sealed interface Content {
 
     // todo add builder (with support for role enum)
 
+    /**
+     * A part of a conversation that contains text.
+     *
+     * @param role belonging to this turn in the conversation. see {@link Role}
+     * @param text by the role
+     */
     record TextContent(
             String role,
             String text
     ) implements Content {
     }
 
+    /**
+     * A part of a conversation that contains media.
+     *
+     * @param role  belonging to this turn in the conversation. see {@link Role}
+     * @param media data
+     */
     record MediaContent(
             String role,
             MediaData media
     ) implements Content {
         // todo test
     }
 
+    /**
+     * A part of a conversation that contains text and media.
+     *
+     * @param role belonging to this turn in the conversation. see {@link Role}
+     */
     record TextAndMediaContent(
             String role,
             String text,
@@ -28,6 +48,12 @@ record TextAndMediaContent(
         // todo test
     }
 
+    /**
+     * Media used during a conversion.
+     *
+     * @param mimeType    e.g. image/jpeg
+     * @param mediaBase64 the media, base64 encoded
+     */
     record MediaData(
             String mimeType,
             String mediaBase64

gemini-api/src/main/java/swiss/ameri/gemini/api/GenAi.java

@@ -12,6 +12,11 @@
 import java.util.concurrent.CompletableFuture;
 import java.util.stream.Stream;
 
+// todo decide if thread-safe or not, once responses are stored
+
+/**
+ * Entry point for all interactions with Gemini API.
+ */
 public class GenAi {
 
     private static final String STREAM_LINE_PREFIX = "data: ";
@@ -44,6 +49,9 @@ public GenAi(
         this.client = client;
     }
 
+    /**
+     * List models that are currently available.
+     */
     public List<Model> listModels() {
         return execute(() -> {
             HttpResponse<String> response = client.send(
@@ -59,8 +67,13 @@ public List<Model> listModels() {
         });
     }
 
+    /***
+     * Get information of a model. Can be used to create a {@link GenerativeModel}.
+     * @param model of which the information is wanted.
+     * @see #listModels()
+     */
     public Model getModel(ModelVariant model) {
-        // todo return GenerativeModelBuilder
+        // todo return GenerativeModelBuilder. or add "toGenerativeModelBuilder" method. or add separate method...
         return getModel(model.variant());
     }
 
@@ -82,7 +95,14 @@ public Model getModel(String model) {
         });
     }
 
-
+    /**
+     * Generates a response from Gemini API based on the given {@code model}. The response is streamed in chunks of text. The
+     * stream items are delivered as they arrive.
+     *
+     * @param model with the necessary information for Gemini API to generate content
+     * @return A live stream of the response, as it arrives
+     * @see #generateContent(GenerativeModel) which returns the whole response at once (asynchronously)
+     */
     public Stream<GeneratedContent> generateContentStream(GenerativeModel model) {
         // todo, keep responses in the state.
         //  add up the usageMetadata
@@ -112,6 +132,14 @@ public Stream<GeneratedContent> generateContentStream(GenerativeModel model) {
         });
     }
 
+    /**
+     * Generates a response from Gemini API based on the given {@code model}.
+     *
+     * @param model with the necessary information for Gemini API to generate content
+     * @return a {@link CompletableFuture} which completes once the response from Gemini API has arrived. The {@link CompletableFuture}
+     * fails, if an unexpected response returns (e.g. invalid token or parameters are used)
+     * @see #generateContentStream(GenerativeModel) to stream the response in chunks, instead of receiving all at once
+     */
     public CompletableFuture<GeneratedContent> generateContent(GenerativeModel model) {
         return execute(() -> {
             CompletableFuture<HttpResponse<String>> response = client.sendAsync(
@@ -201,6 +229,9 @@ private <T> T execute(ThrowingSupplier<T> supplier) {
         }
     }
 
+    /**
+     * Content generated by Gemini API.
+     */
     public record GeneratedContent(
             String text
     ) {
@@ -240,7 +271,6 @@ private record GenerateContentRequest(
     ) {
     }
 
-
     private record GenerationContent(
             String role,
             List<GenerationPart> parts
@@ -254,7 +284,6 @@ private record GenerationPart(
     ) {
     }
 
-
     private record ModelResponse(List<Model> models) {
     }
 

gemini-api/src/main/java/swiss/ameri/gemini/api/GenerationConfig.java

@@ -3,7 +3,34 @@
 import java.util.List;
 
 /**
- * According to <a href="https://ai.google.dev/api/rest/v1beta/GenerationConfig">GenerationConfig</a>
+ * Generation configuration.
+ *
+ * @param stopSequences    Optional. The set of character sequences (up to 5) that will stop output generation.
+ *                         If specified, the API will stop at the first appearance of a stop sequence.
+ *                         The stop sequence will not be included as part of the response.
+ * @param responseMimeType Optional. Output response mimetype of the generated candidate text.
+ *                         Supported mimetype: text/plain: (default) Text output.
+ *                         application/json: JSON response in the candidates.
+ * @param responseSchema   Optional. Output response schema of the generated candidate text when response mime type can have schema.
+ *                         Schema can be objects, primitives or arrays and is a subset of OpenAPI schema.
+ *                         If set, a compatible responseMimeType must also be set. Compatible mimetypes: application/json: Schema for JSON response.
+ * @param maxOutputTokens  Optional. The maximum number of tokens to include in a candidate.
+ *                         Note: The default value varies by model, see the Model.output_token_limit attribute of the Model returned from the getModel function.
+ * @param temperature      Optional. Controls the randomness of the output.
+ *                         Note: The default value varies by model, see the Model. temperature attribute of the Model returned from the getModel function.
+ *                         Values can range from [0.0, 2.0].
+ * @param topP             Optional. The maximum cumulative probability of tokens to consider when sampling.
+ *                         The model uses combined Top-k and nucleus sampling.
+ *                         Tokens are sorted based on their assigned probabilities so that only the most likely tokens are considered.
+ *                         Top-k sampling directly limits the maximum number of tokens to consider, while Nucleus sampling limits number of tokens based on the cumulative probability.
+ *                         Note: The default value varies by model, see the Model.top_p attribute of the Model returned from the getModel function.
+ * @param topK             Optional. The maximum number of tokens to consider when sampling.
+ *                         Models use nucleus sampling or combined Top-k and nucleus sampling.
+ *                         Top-k sampling considers the set of topK most probable tokens.
+ *                         Models running with nucleus sampling don't allow topK setting.
+ *                         Note: The default value varies by model, see the Model.top_k attribute of the Model returned from the getModel function.
+ *                         Empty topK field in Model indicates the model doesn't apply top-k sampling and doesn't allow setting topK on requests.
+ * @see <a href="https://ai.google.dev/api/rest/v1beta/GenerationConfig">GenerationConfig</a>
  */
 public record GenerationConfig(
         List<String> stopSequences,

gemini-api/src/main/java/swiss/ameri/gemini/api/GenerativeModel.java

@@ -2,6 +2,14 @@
 
 import java.util.List;
 
+/**
+ * Contains all the information needed for Gemini API to generate new content.
+ *
+ * @param modelName        to be used. see {@link ModelVariant}. Must start with "models/"
+ * @param contents         given as input to Gemini API
+ * @param safetySettings   optional, to adjust safety settings
+ * @param generationConfig optional, to configure the prompt
+ */
 public record GenerativeModel(
         String modelName,
         List<Content> contents,

gemini-api/src/main/java/swiss/ameri/gemini/api/ModelVariant.java

@@ -1,6 +1,8 @@
 package swiss.ameri.gemini.api;
 
 /**
+ * (Potentially non-exhaustive) list of supported models.
+ *
  * @see <a href="https://ai.google.dev/gemini-api/docs/models/gemini">Gemini Models</a>
  */
 public enum ModelVariant {
@@ -9,7 +11,6 @@ public enum ModelVariant {
     GEMINI_1_0_PRO("gemini-1.0-pro"),
     GEMINI_1_0_PRO_VISION("gemini-pro-vision"),
     TEXT_EMBEDDING_004("text-embedding-004"),
-
     ;
 
     private final String variant;

gemini-api/src/main/java/swiss/ameri/gemini/api/SafetySetting.java

@@ -1,10 +1,17 @@
 package swiss.ameri.gemini.api;
 
+/**
+ * Safety settings according to <a href="https://ai.google.dev/api/rest/v1beta/SafetySetting#harmblockthreshold">SafetySetting</a>.
+ */
 public record SafetySetting(
         String category,
         String threshold
 ) {
 
+    /**
+     * Create a SafetySetting by using the provided enums. Use the constructor for custom string values that might
+     * be missing in the enums.
+     */
     public static SafetySetting of(
             HarmCategory category,
             HarmBlockThreshold threshold

gemini-api/src/main/java/swiss/ameri/gemini/spi/JsonParser.java

@@ -1,9 +1,20 @@
 package swiss.ameri.gemini.spi;
 
+/**
+ * Used to (un-) marshal java objects (mainly {@code record}s) to JSON Strings.
+ * To keep this library dependency free, no implementation is provided directly.
+ * {@code swiss.ameri:gemini-gson} provides an example implementation using a gson dependency.
+ */
 public interface JsonParser {
 
+    /**
+     * This method serializes the specified object into its equivalent JSON representation.
+     */
     String toJson(Object object);
 
+    /**
+     * This method deserializes the specified JSON into an object of the specified class.
+     */
     <T> T fromJson(String json, Class<T> clazz);
 
 }

gemini-gson/src/main/java/swiss/ameri/gemini/gson/GsonJsonParser.java

@@ -3,19 +3,27 @@
 import com.google.gson.Gson;
 import swiss.ameri.gemini.spi.JsonParser;
 
+/**
+ * Reference implementation of {@link JsonParser} using {@link Gson} dependency.
+ */
 public class GsonJsonParser implements JsonParser {
 
     private final Gson gson;
 
+    /**
+     * Create a {@link JsonParser} with a custom {@link Gson}.
+     */
     public GsonJsonParser(Gson gson) {
         this.gson = gson;
     }
 
+    /**
+     * Create a default {@link JsonParser} instance.
+     */
     public GsonJsonParser() {
         this(new Gson());
     }
 
-
     @Override
     public String toJson(Object object) {
         return gson.toJson(object);