publish version 1beta.0.1.0 (and adjust some javadoc warnings)

Author: michael-ameri

gemini-api/pom.xml

@@ -6,7 +6,7 @@
     <parent>
         <groupId>swiss.ameri</groupId>
         <artifactId>gemini</artifactId>
-        <version>1beta.0.0.1-SNAPSHOT</version>
+        <version>1beta.0.1.0</version>
     </parent>
 
     <artifactId>gemini-api</artifactId>

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

@@ -77,13 +77,21 @@ record MediaContent(
     /**
      * A part of a conversation that contains text and media.
      *
-     * @param role belonging to this turn in the conversation. see {@link Role}
+     * @param role  belonging to this turn in the conversation. see {@link Role}
+     * @param text  of the conversation part
+     * @param media the medias
      */
     record TextAndMediaContent(
             String role,
             String text,
             List<MediaData> media
     ) implements Content {
+
+        /**
+         * Create a {@link TextAndMediaContentBuilder}.
+         *
+         * @return a new builder
+         */
         public static TextAndMediaContentBuilder builder() {
             return new TextAndMediaContentBuilder();
         }
@@ -168,9 +176,17 @@ record MediaData(
     ) {
     }
 
-
+    /**
+     * The producer of the content. Mainly relevant for multi turn conversations.
+     */
     enum Role {
+        /**
+         * Content by user.
+         */
         USER,
+        /**
+         * Content by model.
+         */
         MODEL;
 
         private final String roleName;
@@ -179,6 +195,11 @@ enum Role {
             this.roleName = name().toLowerCase(Locale.ROOT);
         }
 
+        /**
+         * Role name for the api
+         *
+         * @return Role name for the api
+         */
         public String roleName() {
             return roleName;
         }

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

@@ -37,6 +37,12 @@ public class GenAi implements AutoCloseable {
     private final JsonParser jsonParser;
     private final Map<UUID, GenerateContentResponse> responseById = new ConcurrentHashMap<>();
 
+    /**
+     * Create a new instance with a default {@link HttpClient}
+     *
+     * @param apiKey     to be used for all communications with Gemini API
+     * @param jsonParser used to (de-)serialize JSON objects
+     */
     public GenAi(
             String apiKey,
             JsonParser jsonParser
@@ -48,6 +54,13 @@ public GenAi(
         );
     }
 
+    /**
+     * Create a new instance
+     *
+     * @param apiKey     to be used for all communications with Gemini API
+     * @param jsonParser used to (de-)serialize JSON objects
+     * @param client     a custom {@link HttpClient} for communication with Gemini API
+     */
     public GenAi(
             String apiKey,
             JsonParser jsonParser,
@@ -60,6 +73,8 @@ public GenAi(
 
     /**
      * List models that are currently available.
+     *
+     * @return available models
      */
     public List<Model> listModels() {
         return execute(() -> {
@@ -80,6 +95,7 @@ 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.
+     * @return information of a model
      * @see #listModels()
      */
     public Model getModel(ModelVariant model) {
@@ -90,6 +106,7 @@ public Model getModel(ModelVariant model) {
      * Get model information.
      *
      * @param model must start with "models/"
+     * @return information of a model
      */
     public Model getModel(String model) {
         return execute(() -> {
@@ -388,7 +405,8 @@ public void close() {
     /**
      * Content generated by Gemini API.
      *
-     * @param id the id of the request, for subsequent queries regarding metadata of the query
+     * @param id   the id of the request, for subsequent queries regarding metadata of the query
+     * @param text of the generated content
      */
     public record GeneratedContent(
             UUID id,
@@ -458,6 +476,59 @@ public record ContentEmbedding(
     ) {
     }
 
+    /**
+     * Information on a model
+     *
+     * @param name                       The resource name of the Model.
+     *                                   <p>
+     *                                   Format: models/{model} with a {model} naming convention of:
+     *                                   <p>
+     *                                   "{baseModelId}-{version}"
+     *                                   Examples:
+     *                                   <p>
+     *                                   models/chat-bison-001
+     * @param baseModelId                The name of the base model, pass this to the generation request.
+     * @param version                    The version number of the model.
+     * @param displayName                The human-readable name of the model. E.g. "Chat Bison".
+     *                                   <p>
+     *                                   The name can be up to 128 characters long and can consist of any UTF-8 characters.
+     * @param description                A short description of the model.
+     * @param inputTokenLimit            Maximum number of input tokens allowed for this model.
+     * @param outputTokenLimit           Maximum number of output tokens available for this model.
+     * @param supportedGenerationMethods The model's supported generation methods.
+     *                                   <p>
+     *                                   The method names are defined as Pascal case strings, such as generateMessage which correspond to API methods.
+     * @param temperature                Controls the randomness of the output.
+     *                                   <p>
+     *                                   Values can range over [0.0,2.0], inclusive.
+     *                                   A higher value will produce responses that are more varied,
+     *                                   while a value closer to 0.0 will typically result in less surprising responses from the model.
+     *                                   This value specifies default to be used by the backend while making the call to the model.
+     * @param topP                       For Nucleus sampling.
+     *                                   <p>
+     *                                   Nucleus sampling considers the smallest set of tokens whose probability sum is at least topP.
+     *                                   This value specifies default to be used by the backend while making the call to the model.
+     * @param topK                       For Top-k sampling.
+     *                                   <p>
+     *                                   Top-k sampling considers the set of topK most probable tokens.
+     *                                   This value specifies default to be used by the backend while making the call to the model.
+     *                                   If empty, indicates the model doesn't use top-k sampling, and topK isn't allowed as a generation parameter.
+     */
+    public record Model(
+            String name,
+            String baseModelId,
+            String version,
+            String displayName,
+            String description,
+            int inputTokenLimit,
+            int outputTokenLimit,
+            List<String> supportedGenerationMethods,
+            double temperature,
+            double topP,
+            int topK
+    ) {
+    }
+
     private record BatchEmbedContentRequest(
             List<EmbedContentRequest> requests
     ) {
@@ -533,20 +604,6 @@ private record InlineData(
     private record ModelResponse(List<Model> models) {
     }
 
-    public record Model(
-            String name,
-            String version,
-            String displayName,
-            String description,
-            int inputTokenLimit,
-            int outputTokenLimit,
-            List<String> supportedGenerationMethods,
-            double temperature,
-            double topP,
-            int topK
-    ) {
-    }
-
     private interface ThrowingSupplier<T> {
         T get() throws IOException, InterruptedException;
     }

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

@@ -36,6 +36,9 @@ public static class GenerativeModelBuilder {
         private final List<Content> contents = new ArrayList<>();
         private final List<SafetySetting> safetySettings = new ArrayList<>();
 
+        private GenerativeModelBuilder() {
+        }
+
         /**
          * Set the model name.
          *

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

@@ -6,10 +6,25 @@
  * @see <a href="https://ai.google.dev/gemini-api/docs/models/gemini">Gemini Models</a>
  */
 public enum ModelVariant {
+    /**
+     * Complex reasoning tasks such as code and text generation, text editing, problem-solving, data extraction and generation.
+     */
     GEMINI_1_5_PRO("gemini-1.5-pro"),
+    /**
+     * Fast and versatile performance across a diverse variety of tasks.
+     */
     GEMINI_1_5_FLASH("gemini-1.5-flash"),
+    /**
+     * Natural language tasks, multi-turn text and code chat, and code generation.
+     */
     GEMINI_1_0_PRO("gemini-1.0-pro"),
+    /**
+     * Visual-related tasks, like generating image descriptions or identifying objects in images.
+     */
     GEMINI_1_0_PRO_VISION("gemini-pro-vision"),
+    /**
+     * Measuring the relatedness of text strings.
+     */
     TEXT_EMBEDDING_004("text-embedding-004"),
     ;
 
@@ -19,6 +34,11 @@ public enum ModelVariant {
         this.variant = variant;
     }
 
+    /**
+     * Model variant name.
+     *
+     * @return Model variant name as needed by Gemini API
+     */
     public String variant() {
         return "models/" + variant;
     }

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

@@ -2,6 +2,9 @@
 
 /**
  * Safety settings according to <a href="https://ai.google.dev/api/rest/v1beta/SafetySetting#harmblockthreshold">SafetySetting</a>.
+ *
+ * @param category  the harm category, see  {@link HarmCategory}
+ * @param threshold the threshold, see {@link HarmBlockThreshold}
  */
 public record SafetySetting(
         String category,
@@ -11,6 +14,10 @@ public record SafetySetting(
     /**
      * Create a SafetySetting by using the provided enums. Use the constructor for custom string values that might
      * be missing in the enums.
+     *
+     * @param category  the harm category, see  {@link HarmCategory}
+     * @param threshold the threshold, see {@link HarmBlockThreshold}
+     * @return the new {@link SafetySetting}
      */
     public static SafetySetting of(
             HarmCategory category,

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

@@ -9,11 +9,19 @@ public interface JsonParser {
 
     /**
      * This method serializes the specified object into its equivalent JSON representation.
+     *
+     * @param object to be serialized
+     * @return the serialized object
      */
     String toJson(Object object);
 
     /**
      * This method deserializes the specified JSON into an object of the specified class.
+     *
+     * @param json  to be deserialized
+     * @param clazz to be created from the json
+     * @param <T>   type of the class
+     * @return the deserialized object
      */
     <T> T fromJson(String json, Class<T> clazz);
 

gemini-gson/pom.xml

@@ -7,7 +7,7 @@
     <parent>
         <groupId>swiss.ameri</groupId>
         <artifactId>gemini</artifactId>
-        <version>1beta.0.0.1-SNAPSHOT</version>
+        <version>1beta.0.1.0</version>
     </parent>
 
     <artifactId>gemini-gson</artifactId>

gemini-tester/pom.xml

@@ -7,7 +7,7 @@
     <parent>
         <groupId>swiss.ameri</groupId>
         <artifactId>gemini</artifactId>
-        <version>1beta.0.0.1-SNAPSHOT</version>
+        <version>1beta.0.1.0</version>
     </parent>
     <artifactId>gemini-tester</artifactId>
 

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>swiss.ameri</groupId>
     <artifactId>gemini</artifactId>
-    <version>1beta.0.0.1-SNAPSHOT</version>
+    <version>1beta.0.1.0</version>
     <packaging>pom</packaging>
 
     <licenses>
@@ -77,6 +77,15 @@
                         <goals>
                             <goal>jar</goal>
                         </goals>
+                        <configuration>
+                            <tags>
+                                <tag>
+                                    <name>apiNote</name>
+                                    <placement>a</placement>
+                                    <head>API Note</head>
+                                </tag>
+                            </tags>
+                        </configuration>
                     </execution>
                 </executions>
             </plugin>