From dec2df05961f7727771458b1f48e7dc8715c33a2 Mon Sep 17 00:00:00 2001 From: Svjatoslav Agejenko Date: Fri, 13 Jun 2025 17:47:20 +0300 Subject: [PATCH] Better JavaDoc --- .../eu/svjatoslav/alyverkko_cli/AiTask.java | 39 +++++++------------ .../eu/svjatoslav/alyverkko_cli/Command.java | 12 ++++-- .../eu/svjatoslav/alyverkko_cli/Utils.java | 5 ++- .../commands/JoinFilesCommand.java | 15 +++++++ .../commands/ListModelsCommand.java | 12 +++++- .../alyverkko_cli/commands/WizardCommand.java | 23 ++++++----- .../MailCorrespondentCommand.java | 23 ++++++----- .../mail_correspondant/package-info.java | 12 ++++-- .../alyverkko_cli/commands/package-info.java | 13 +++++-- .../configuration/Configuration.java | 14 +++++-- .../configuration/ConfigurationHelper.java | 11 ++++++ .../configuration/package-info.java | 14 ++++--- .../svjatoslav/alyverkko_cli/model/Model.java | 25 ++++++++++-- .../alyverkko_cli/model/package-info.java | 12 ++++-- .../alyverkko_cli/package-info.java | 13 +++++-- 15 files changed, 166 insertions(+), 77 deletions(-) diff --git a/src/main/java/eu/svjatoslav/alyverkko_cli/AiTask.java b/src/main/java/eu/svjatoslav/alyverkko_cli/AiTask.java index 925284d..06bbc74 100644 --- a/src/main/java/eu/svjatoslav/alyverkko_cli/AiTask.java +++ b/src/main/java/eu/svjatoslav/alyverkko_cli/AiTask.java @@ -9,9 +9,19 @@ import static eu.svjatoslav.alyverkko_cli.Main.configuration; import static java.lang.String.join; /** - * Encapsulates the process of running an AI inference query via - * llama.cpp. It prepares an input file, spawns the process, collects - * output, and cleans up temporary files. + *

Executes AI inference tasks through llama.cpp CLI. This class handles the complete workflow + * from prompt construction to response formatting, including temporary file management and process execution.

+ *

Key processing steps: + *

    + *
  1. Build standardized input prompt
    2. + *
  2. Create temporary input file
    3. + *
  3. Execute llama.cpp with appropriate parameters
    4. + *
  4. Capture and filter output
    5. + *
  5. Perform cleanup operations
    6. + *
+ *

+ *

Temperature settings, context size, and thread counts are all derived from the current configuration. + * The response is formatted to match org-mode conventions while preserving original conversation structure.

*/ public class AiTask { @@ -250,29 +260,6 @@ public class AiTask { "--file " + inputFile ); -// Old solution that sometimes went into an infinite loop, for backup purposes: -// -// return join(" ", -// "nice", "-n", Integer.toString(niceValue), -// executablePath, -// "--model " + mailQuery.model.filesystemPath, -// "--threads " + configuration.getThreadCount(), -// "--threads-batch " + configuration.getBatchThreadCount(), -// "--mirostat 2", -// "--flash-attn", -// "--cache-type-k q8_0", -// "--cache-type-v q8_0", -// "--no-display-prompt", -// "--no-warmup", -// "--temp " + temperature, -// "--ctx-size " + mailQuery.model.contextSizeTokens, -// "--batch-size 8", -// "--no-conversation", -// "-n -1", -// "--repeat_penalty 1.1", -// "--file " + inputFile -// ); - } /** diff --git a/src/main/java/eu/svjatoslav/alyverkko_cli/Command.java b/src/main/java/eu/svjatoslav/alyverkko_cli/Command.java index dfd9b14..fca9e37 100644 --- a/src/main/java/eu/svjatoslav/alyverkko_cli/Command.java +++ b/src/main/java/eu/svjatoslav/alyverkko_cli/Command.java @@ -3,9 +3,15 @@ package eu.svjatoslav.alyverkko_cli; import java.io.IOException; /** - * A simple interface for all subcommands used by the Älyverkko CLI. - * Implementing classes define a unique name (e.g., "wizard") and an - * {@code execute} method for the command's logic. + *

Base interface for all subcommands in the Älyverkko CLI. Each command must define its name and execution logic.

+ *

Commands typically: + *

+ *

+ *

Commands should be stateless and self-contained, using the configuration object for persistent data when needed.

*/ public interface Command { diff --git a/src/main/java/eu/svjatoslav/alyverkko_cli/Utils.java b/src/main/java/eu/svjatoslav/alyverkko_cli/Utils.java index 8f42cde..4e0c94d 100644 --- a/src/main/java/eu/svjatoslav/alyverkko_cli/Utils.java +++ b/src/main/java/eu/svjatoslav/alyverkko_cli/Utils.java @@ -1,7 +1,10 @@ package eu.svjatoslav.alyverkko_cli; /** - * Utility functions for miscellaneous tasks such as colored console output. + *

General utility functions for the Älyverkko CLI application. Currently provides ANSI color output capabilities for + * console messages.

+ *

Color formatting follows standard ANSI escape sequences, with specific methods for common message types like errors.

+ *

For future extensions, this class could include additional helper functions for file operations or string processing.

*/ public class Utils { diff --git a/src/main/java/eu/svjatoslav/alyverkko_cli/commands/JoinFilesCommand.java b/src/main/java/eu/svjatoslav/alyverkko_cli/commands/JoinFilesCommand.java index 072bb3a..e74e5a2 100644 --- a/src/main/java/eu/svjatoslav/alyverkko_cli/commands/JoinFilesCommand.java +++ b/src/main/java/eu/svjatoslav/alyverkko_cli/commands/JoinFilesCommand.java @@ -29,6 +29,21 @@ import static eu.svjatoslav.alyverkko_cli.configuration.ConfigurationHelper.load * alyverkko-cli joinfiles -s /path/to/source -p "*.java" -t "my_topic" --edit * */ + +/** + *

Aggregates files from a source directory into a single file for AI processing. + * This is particularly useful for creating comprehensive inputs from multiple files + * matching a specified pattern.

+ *

Features include: + *

+ *

+ *

By default, the output file is saved in the mail directory with a .org extension.

+ */ public class JoinFilesCommand implements Command { /** diff --git a/src/main/java/eu/svjatoslav/alyverkko_cli/commands/ListModelsCommand.java b/src/main/java/eu/svjatoslav/alyverkko_cli/commands/ListModelsCommand.java index 5078177..177a443 100644 --- a/src/main/java/eu/svjatoslav/alyverkko_cli/commands/ListModelsCommand.java +++ b/src/main/java/eu/svjatoslav/alyverkko_cli/commands/ListModelsCommand.java @@ -10,8 +10,16 @@ import static eu.svjatoslav.alyverkko_cli.configuration.ConfigurationHelper.getC import static eu.svjatoslav.alyverkko_cli.configuration.ConfigurationHelper.loadConfiguration; /** - * Lists all configured models in the system, loading them from the - * user’s configuration and printing them to the console. + *

Displays all available AI models in the configured models directory. This command provides a quick overview of + * currently available models and their metadata.

+ *

The implementation: + *

+ *

+ *

This command is primarily intended for administrative use to verify model availability before running tasks.

*/ public class ListModelsCommand implements Command { diff --git a/src/main/java/eu/svjatoslav/alyverkko_cli/commands/WizardCommand.java b/src/main/java/eu/svjatoslav/alyverkko_cli/commands/WizardCommand.java index 36616d6..c9df3ca 100644 --- a/src/main/java/eu/svjatoslav/alyverkko_cli/commands/WizardCommand.java +++ b/src/main/java/eu/svjatoslav/alyverkko_cli/commands/WizardCommand.java @@ -19,16 +19,19 @@ import static eu.svjatoslav.alyverkko_cli.configuration.ConfigurationHelper.getC import static eu.svjatoslav.commons.cli_helper.CLIHelper.*; /** - * A single WizardCommand that: - * 1. Loads existing configuration (if any). - * 2. Performs "selftest" style validation checks interactively, - * prompting the user to fix invalid or missing items. - * 3. If no config file exists, it goes through all config parameters - * from scratch. - * 4. Offers to remove model entries that reference missing files. - * 5. Autodiscovers new .gguf files and lets the user add them to the config. - * 6. Saves the resulting (fixed) config file. - * 7. Prints a final pass/fail summary for the user. + *

Interactive configuration wizard that helps users validate and fix their configuration files. + * It performs system checks and offers to fix any missing or invalid paths, discovers new models, + * and updates the configuration accordingly.

+ *

Key workflow steps: + *

    + *
  1. Load or create configuration
    2. + *
  2. Validate core directory paths
    3. + *
  3. Discover and annotate new models
    4. + *
  4. Save updated configuration
    5. + *
+ *

+ *

When handling split models (.gguf files with part numbering), the wizard automatically + * detects base models and only adds part-1 files to the configuration.

*/ public class WizardCommand implements Command { diff --git a/src/main/java/eu/svjatoslav/alyverkko_cli/commands/mail_correspondant/MailCorrespondentCommand.java b/src/main/java/eu/svjatoslav/alyverkko_cli/commands/mail_correspondant/MailCorrespondentCommand.java index bf291dc..cb71e41 100644 --- a/src/main/java/eu/svjatoslav/alyverkko_cli/commands/mail_correspondant/MailCorrespondentCommand.java +++ b/src/main/java/eu/svjatoslav/alyverkko_cli/commands/mail_correspondant/MailCorrespondentCommand.java @@ -24,16 +24,21 @@ import static java.nio.file.StandardWatchEventKinds.ENTRY_CREATE; import static java.nio.file.StandardWatchEventKinds.ENTRY_MODIFY; /** - * The MailCorrespondentCommand continuously monitors a specified mail - * directory for new or modified text files, checks if they have a - * "TOCOMPUTE:" marker, and if so, processes them with an AI model. - * Once processed, results are appended to the same file. - *

- * Usage: - * 

- *   alyverkko-cli mail
- *
+ *

Monitors a designated mail directory for text files containing "TOCOMPUTE:" markers. + * When new or modified files are detected, it processes them with appropriate AI models + * and appends the results using a standardized format.

+ *

The processing pipeline includes: + *

    + *
  1. Initial scan of existing files
    2. + *
  2. WatchService registration for real-time monitoring
    3. + *
  3. Query construction from file metadata
    4. + *
  4. AI response formatting and appending
    5. + *
+ *

+ *

This implementation uses a sleep delay (1 second) after detecting file changes to allow complete writes before + * processing. The response format follows org-mode conventions for easy reading and further processing.

*/ + public class MailCorrespondentCommand implements Command { /** diff --git a/src/main/java/eu/svjatoslav/alyverkko_cli/commands/mail_correspondant/package-info.java b/src/main/java/eu/svjatoslav/alyverkko_cli/commands/mail_correspondant/package-info.java index 64ce203..3bf376d 100644 --- a/src/main/java/eu/svjatoslav/alyverkko_cli/commands/mail_correspondant/package-info.java +++ b/src/main/java/eu/svjatoslav/alyverkko_cli/commands/mail_correspondant/package-info.java @@ -1,8 +1,12 @@ /** - * This package contains mail processing commands for the Älyverkko CLI application. - *

- * The MailCorrespondentCommand monitors a mail directory for tasks and processes them - * using AI models. MailQuery encapsulates the data needed for each mail-based query. + *

This subpackage implements the mail-based AI task processing functionality. It watches mail directories for + * new/modified files with specific markers and processes them using AI models.

+ *

Key components: + *

*

*/ diff --git a/src/main/java/eu/svjatoslav/alyverkko_cli/commands/package-info.java b/src/main/java/eu/svjatoslav/alyverkko_cli/commands/package-info.java index 0d525af..33f0c48 100644 --- a/src/main/java/eu/svjatoslav/alyverkko_cli/commands/package-info.java +++ b/src/main/java/eu/svjatoslav/alyverkko_cli/commands/package-info.java @@ -1,8 +1,13 @@ /** - * This package contains all command implementations for the Älyverkko CLI application. - *

- * Each command class implements the Command interface and provides functionality for - * specific user actions like model management, file joining, and mail processing. + *

This package implements all subcommands available in the Älyverkko CLI application. Each command class provides a + * specific functionality through the Command interface.

+ *

Available commands include: + *

*

*/ 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 8394e42..d25d723 100644 --- a/src/main/java/eu/svjatoslav/alyverkko_cli/configuration/Configuration.java +++ b/src/main/java/eu/svjatoslav/alyverkko_cli/configuration/Configuration.java @@ -9,9 +9,17 @@ 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. + *

Central configuration class storing all application parameters. + * This class is serialized to YAML format for user editing and persistence.

+ *

Configuration parameters include: + *

+ *

+ *

All paths are resolved relative to the user's home directory by default, but can be customized. The class provides + * direct access to prompt content for AI query construction.

*/ @Data public class Configuration { diff --git a/src/main/java/eu/svjatoslav/alyverkko_cli/configuration/ConfigurationHelper.java b/src/main/java/eu/svjatoslav/alyverkko_cli/configuration/ConfigurationHelper.java index 45891db..7a4a36b 100644 --- a/src/main/java/eu/svjatoslav/alyverkko_cli/configuration/ConfigurationHelper.java +++ b/src/main/java/eu/svjatoslav/alyverkko_cli/configuration/ConfigurationHelper.java @@ -7,6 +7,17 @@ import eu.svjatoslav.commons.cli_helper.parameter_parser.parameter.FileOption; import java.io.File; import java.io.IOException; +/** + *

Helper class for configuration file operations. Provides methods for loading configurations + * and determining the default configuration file path in the user's home directory.

+ *

Key functionality includes: + *

+ *

+ */ public class ConfigurationHelper { /** diff --git a/src/main/java/eu/svjatoslav/alyverkko_cli/configuration/package-info.java b/src/main/java/eu/svjatoslav/alyverkko_cli/configuration/package-info.java index c95e44c..3fb3ba6 100644 --- a/src/main/java/eu/svjatoslav/alyverkko_cli/configuration/package-info.java +++ b/src/main/java/eu/svjatoslav/alyverkko_cli/configuration/package-info.java @@ -1,9 +1,13 @@ /** - * This package contains configuration-related classes for the Älyverkko CLI application. - *

- * The Configuration class holds global settings, while ConfigurationModel represents - * individual model configurations. ConfigurationHelper provides utility methods for - * loading and managing configuration files. + *

This package handles the configuration system for the Älyverkko CLI application. + * It provides classes for storing and retrieving application-wide settings, including + * model configurations, directory paths, and performance parameters.

+ *

Configuration is stored in YAML format and includes: + *

*

*/ 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 e985ac1..8cf7bfd 100644 --- a/src/main/java/eu/svjatoslav/alyverkko_cli/model/Model.java +++ b/src/main/java/eu/svjatoslav/alyverkko_cli/model/Model.java @@ -3,8 +3,17 @@ 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. + *

Represents an AI model stored on the filesystem with metadata about its capabilities and identification. + * This class serves as a lightweight container for model information, enabling quick lookup and validation.

+ *

Models are typically discovered through configuration files and stored in the ModelLibrary for easy access. + *

Key fields include: + *

+ *

*/ public class Model { @@ -44,8 +53,18 @@ public class Model { this.endOfTextMarker = endOfTextMarker; } + /** - * Prints the model's alias, path, and context size to standard output. + *

Prints the model's metadata to standard output in a consistent format. This includes the model's alias, + * filesystem path, and context token capacity. The output format is designed to be both human-readable and + * machine-parsable when needed.

+ *

Typical output: + * 

+     * Model: default
+     *   Path: /path/to/model.gguf
+     *   Context size: 32768
+     *
+ *

*/ public void printModelDetails() { System.out.println("Model: " + alias); diff --git a/src/main/java/eu/svjatoslav/alyverkko_cli/model/package-info.java b/src/main/java/eu/svjatoslav/alyverkko_cli/model/package-info.java index 9fb1aca..717d44e 100644 --- a/src/main/java/eu/svjatoslav/alyverkko_cli/model/package-info.java +++ b/src/main/java/eu/svjatoslav/alyverkko_cli/model/package-info.java @@ -1,8 +1,12 @@ /** - * This package contains classes for managing AI models in the Älyverkko CLI application. - *

- * The Model class represents an AI model with metadata like path and context size. - * The ModelLibrary class manages a collection of models, providing lookup and validation. + *

This package defines the model management system for the Älyverkko CLI. + * It includes classes for representing AI models and maintaining a library of available models.

+ *

Key features: + *

*

*/ diff --git a/src/main/java/eu/svjatoslav/alyverkko_cli/package-info.java b/src/main/java/eu/svjatoslav/alyverkko_cli/package-info.java index 619e817..491400e 100644 --- a/src/main/java/eu/svjatoslav/alyverkko_cli/package-info.java +++ b/src/main/java/eu/svjatoslav/alyverkko_cli/package-info.java @@ -1,7 +1,14 @@ /** - * This package contains core components of the Älyverkko CLI application. - *

- * It includes the Main entry point, Command interface, and utility classes like Utils. + *

This package contains the core components of the Älyverkko CLI application, including the main entry point, + * command interfaces, and utility classes. It serves as the central hub for orchestrating subcommands and core + * application behavior.

+ *

Key responsibilities include: + *

+ *

*/ package eu.svjatoslav.alyverkko_cli; \ No newline at end of file -- 2.20.1