From: Svjatoslav Agejenko Date: Sun, 23 Mar 2025 22:40:46 +0000 (+0200) Subject: Improve code comments X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=commitdiff_plain;h=224e6720d74b2fb7a943c2a630e8d4403e5bd6cd;p=alyverkko-cli.git Improve code comments --- diff --git a/src/main/java/eu/svjatoslav/alyverkko_cli/Utils.java b/src/main/java/eu/svjatoslav/alyverkko_cli/Utils.java index 6523174..8f42cde 100644 --- a/src/main/java/eu/svjatoslav/alyverkko_cli/Utils.java +++ b/src/main/java/eu/svjatoslav/alyverkko_cli/Utils.java @@ -1,7 +1,15 @@ package eu.svjatoslav.alyverkko_cli; +/** + * Utility functions for miscellaneous tasks such as colored console output. + */ public class Utils { + /** + * Prints a message in red text to the console. + * + * @param message the text to print in red. + */ public static void printRedMessageToConsole(String message) { // set output color to red System.out.print("\033[0;31m"); @@ -9,5 +17,4 @@ public class Utils { // reset output color System.out.print("\033[0m"); } - } diff --git a/src/main/java/eu/svjatoslav/alyverkko_cli/configuration/Configuration.java b/src/main/java/eu/svjatoslav/alyverkko_cli/configuration/Configuration.java index 63769f8..3970e2f 100644 --- a/src/main/java/eu/svjatoslav/alyverkko_cli/configuration/Configuration.java +++ b/src/main/java/eu/svjatoslav/alyverkko_cli/configuration/Configuration.java @@ -5,53 +5,94 @@ import com.fasterxml.jackson.dataformat.yaml.YAMLFactory; import com.fasterxml.jackson.annotation.JsonProperty; import lombok.Data; - import java.io.*; import java.util.List; import static eu.svjatoslav.commons.file.IOHelper.getFileContentsAsString; +/** + * Encapsulates all user configuration for the Älyverkko CLI application, + * such as model directories, mail directory, default temperature, + * llama-cli path, etc. + */ @Data public class Configuration { - public static final String DEFAULT_CONFIG_FILE_PATH = "~/.config/alyverkko-cli/alyverkko-cli.yaml".replaceFirst("^~", System.getProperty("user.home")); + /** + * The default path for the YAML config file, typically under the user's home directory. + */ + public static final String DEFAULT_CONFIG_FILE_PATH = "~/.config/alyverkko-cli/alyverkko-cli.yaml" + .replaceFirst("^~", System.getProperty("user.home")); + /** + * Directory where AI tasks (mail) are placed and discovered. + */ @JsonProperty("mail_directory") private File mailDirectory; + /** + * Directory that contains AI model files in GGUF format. + */ @JsonProperty("models_directory") private File modelsDirectory; + /** + * The default "temperature" used by the AI for creative/deterministic + * tradeoff. Ranges roughly between 0 and 3. + */ @JsonProperty("default_temperature") private float defaultTemperature; + /** + * The filesystem path to the llama-cli executable, which processes + * AI tasks via llama.cpp. + */ @JsonProperty("llama_cli_path") private File llamaCliPath; + /** + * Number of CPU threads used for input prompt processing. + */ @JsonProperty("batch_thread_count") private int batchThreadCount; + /** + * Number of CPU threads used for AI inference. + */ @JsonProperty("thread_count") private int threadCount; + /** + * Directory containing text prompt files. Each file is a separate + * "prompt" by alias (the filename minus ".txt"). + */ @JsonProperty("prompts_directory") private File promptsDirectory; + /** + * The list of models defined in this configuration. + */ private List models; - public void setModels(List models) { - this.models = models; - } - - public Configuration() { - } - + /** + * Loads the configuration from the default file path. + * + * @return the {@link Configuration} object, or null if the file doesn't exist or fails parsing. + * @throws IOException if file I/O fails during reading. + */ public static Configuration loadConfiguration() throws IOException { return loadConfiguration(null); } + /** + * Loads the configuration from a given file, or from the default + * path if {@code configFile} is null. + * + * @param configFile the file containing the YAML config; may be null. + * @return the {@link Configuration} object, or null if not found/invalid. + * @throws IOException if file I/O fails during reading. + */ public static Configuration loadConfiguration(File configFile) throws IOException { - if (configFile == null) { // Load configuration from the default path configFile = new File(DEFAULT_CONFIG_FILE_PATH); @@ -66,6 +107,14 @@ public class Configuration { return mapper.readValue(configFile, Configuration.class); } + /** + * Retrieves the contents of a prompt file by alias, e.g. "writer" + * maps to "writer.txt" in the prompts directory. + * + * @param alias the name of the prompt file (without ".txt"). + * @return the full text content of the prompt file. + * @throws IOException if reading the prompt file fails. + */ public String getPromptByAlias(String alias) throws IOException { File promptFile = new File(promptsDirectory, alias + ".txt"); return getFileContentsAsString(promptFile); diff --git a/src/main/java/eu/svjatoslav/alyverkko_cli/model/Model.java b/src/main/java/eu/svjatoslav/alyverkko_cli/model/Model.java index 8a49497..e985ac1 100644 --- a/src/main/java/eu/svjatoslav/alyverkko_cli/model/Model.java +++ b/src/main/java/eu/svjatoslav/alyverkko_cli/model/Model.java @@ -2,34 +2,40 @@ package eu.svjatoslav.alyverkko_cli.model; import java.io.File; +/** + * Represents an AI model stored on the filesystem, including details such + * as path, context size, alias, and an optional end-of-text marker. + */ public class Model { + /** - * The path to the file system where the model will be stored. + * The path to the model file on the filesystem. */ public final File filesystemPath; /** - * The size of the context in terms of tokens. + * The size of the context (in tokens) that this model is able to handle. */ public final int contextSizeTokens; /** - * The alias for the model. + * A user-friendly alias for the model, e.g. "default" or "mistral". */ public final String alias; /** - * The marker used to signify the end of AI generated text. + * An optional marker indicating end of the AI-generated text (e.g., "###"). + * If non-null, it can be used to detect where the model has finished answering. */ public final String endOfTextMarker; - /** - * The constructor for the Model class. - * @param filesystemPath The path to the file system where the model will be stored. - * @param contextSizeTokens The size of the context in terms of tokens. - * @param modelAlias The alias for the model. - * @param endOfTextMarker The marker used to signify the end of AI generated text. + * Constructs a {@link Model} instance. + * + * @param filesystemPath The path to the model file on the filesystem. + * @param contextSizeTokens The size of the context in tokens. + * @param modelAlias A short alias by which the model is referenced. + * @param endOfTextMarker Optional text that signifies the end of the AI's output. */ public Model(File filesystemPath, int contextSizeTokens, String modelAlias, String endOfTextMarker) { this.filesystemPath = filesystemPath; @@ -39,12 +45,11 @@ public class Model { } /** - * Prints the details of the model. + * Prints the model's alias, path, and context size to standard output. */ - public void printModelDetails(){ + public void printModelDetails() { System.out.println("Model: " + alias); System.out.println(" Path: " + filesystemPath); System.out.println(" Context size: " + contextSizeTokens); } - }