Fix reactor CI: keep class-level @builder, re-root crash-dump paths, README

claude · claude · commit d64a3653b0ae · 2026-07-02T06:59:21.000Z
- TrainingParameters: keep class-level Lombok @builder @Getter but satisfy the strict javadoc build (failOnWarnings) — replace the raw-source-invisible {@link #builder()} with {@code builder()} and add an explicit private all-args constructor so javadoc sees a real constructor (no synthetic-default warning); Lombok generates the builder around it. Verified: compile + javadoc:jar clean, TrainingParametersTest (3) green. - publish.yml: re-root the Java test jobs' crash-dump/surefire upload globs to llama/ (hs_err_pid*, *.hprof, target/surefire-reports/*) now that surefire runs against -f llama/pom.xml; core.* stays at workspace root (absolute core_pattern). - README: add Jlama and LangChain4j to the Similar Projects section. - Apply clang-format 22.1.5 (train_engine.cpp) and spotless (Java) from the #289 merge. - .gitignore: catch llama/.jqwik-database (un-anchored pattern). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Rt1paYztGJ2AKUuBuAGDXE
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -1108,13 +1108,13 @@ jobs:
         with:
           name: error-log-linux-x86_64
           path: |
-            ${{ github.workspace }}/hs_err_pid*.log
+            ${{ github.workspace }}/llama/hs_err_pid*.log
             ${{ github.workspace }}/core.*
-            ${{ github.workspace }}/*.hprof
-            ${{ github.workspace }}/target/surefire-reports/*.dump
-            ${{ github.workspace }}/target/surefire-reports/*.dumpstream
-            ${{ github.workspace }}/target/surefire-reports/*.txt
-            ${{ github.workspace }}/target/surefire-reports/TEST-*.xml
+            ${{ github.workspace }}/llama/*.hprof
+            ${{ github.workspace }}/llama/target/surefire-reports/*.dump
+            ${{ github.workspace }}/llama/target/surefire-reports/*.dumpstream
+            ${{ github.workspace }}/llama/target/surefire-reports/*.txt
+            ${{ github.workspace }}/llama/target/surefire-reports/TEST-*.xml
           if-no-files-found: warn
 
   # ---------------------------------------------------------------------------
@@ -1202,12 +1202,12 @@ jobs:
         with:
           name: error-log-macos-14-metal
           path: |
-            ${{ github.workspace }}/hs_err_pid*.log
-            ${{ github.workspace }}/*.hprof
-            ${{ github.workspace }}/target/surefire-reports/*.dump
-            ${{ github.workspace }}/target/surefire-reports/*.dumpstream
-            ${{ github.workspace }}/target/surefire-reports/*.txt
-            ${{ github.workspace }}/target/surefire-reports/TEST-*.xml
+            ${{ github.workspace }}/llama/hs_err_pid*.log
+            ${{ github.workspace }}/llama/*.hprof
+            ${{ github.workspace }}/llama/target/surefire-reports/*.dump
+            ${{ github.workspace }}/llama/target/surefire-reports/*.dumpstream
+            ${{ github.workspace }}/llama/target/surefire-reports/*.txt
+            ${{ github.workspace }}/llama/target/surefire-reports/TEST-*.xml
           if-no-files-found: warn
 
   test-java-macos-arm64-no-metal:
@@ -1266,12 +1266,12 @@ jobs:
         with:
           name: error-log-macos-15-no-metal
           path: |
-            ${{ github.workspace }}/hs_err_pid*.log
-            ${{ github.workspace }}/*.hprof
-            ${{ github.workspace }}/target/surefire-reports/*.dump
-            ${{ github.workspace }}/target/surefire-reports/*.dumpstream
-            ${{ github.workspace }}/target/surefire-reports/*.txt
-            ${{ github.workspace }}/target/surefire-reports/TEST-*.xml
+            ${{ github.workspace }}/llama/hs_err_pid*.log
+            ${{ github.workspace }}/llama/*.hprof
+            ${{ github.workspace }}/llama/target/surefire-reports/*.dump
+            ${{ github.workspace }}/llama/target/surefire-reports/*.dumpstream
+            ${{ github.workspace }}/llama/target/surefire-reports/*.txt
+            ${{ github.workspace }}/llama/target/surefire-reports/TEST-*.xml
           if-no-files-found: warn
 
   test-java-macos-arm64-metal-15:
@@ -1330,12 +1330,12 @@ jobs:
         with:
           name: error-log-macos-15-metal
           path: |
-            ${{ github.workspace }}/hs_err_pid*.log
-            ${{ github.workspace }}/*.hprof
-            ${{ github.workspace }}/target/surefire-reports/*.dump
-            ${{ github.workspace }}/target/surefire-reports/*.dumpstream
-            ${{ github.workspace }}/target/surefire-reports/*.txt
-            ${{ github.workspace }}/target/surefire-reports/TEST-*.xml
+            ${{ github.workspace }}/llama/hs_err_pid*.log
+            ${{ github.workspace }}/llama/*.hprof
+            ${{ github.workspace }}/llama/target/surefire-reports/*.dump
+            ${{ github.workspace }}/llama/target/surefire-reports/*.dumpstream
+            ${{ github.workspace }}/llama/target/surefire-reports/*.txt
+            ${{ github.workspace }}/llama/target/surefire-reports/TEST-*.xml
           if-no-files-found: warn
 
   test-java-windows-x86_64:
@@ -1413,13 +1413,13 @@ jobs:
         with:
           name: windows-output
           path: |
-            ${{ github.workspace }}\hs_err_pid*.log
-            ${{ github.workspace }}\*.hprof
+            ${{ github.workspace }}\llama\hs_err_pid*.log
+            ${{ github.workspace }}\llama\*.hprof
             ${{ github.workspace }}\dumps\*.dmp
-            ${{ github.workspace }}\target\surefire-reports\*.dump
-            ${{ github.workspace }}\target\surefire-reports\*.dumpstream
-            ${{ github.workspace }}\target\surefire-reports\*.txt
-            ${{ github.workspace }}\target\surefire-reports\TEST-*.xml
+            ${{ github.workspace }}\llama\target\surefire-reports\*.dump
+            ${{ github.workspace }}\llama\target\surefire-reports\*.dumpstream
+            ${{ github.workspace }}\llama\target\surefire-reports\*.txt
+            ${{ github.workspace }}\llama\target\surefire-reports\TEST-*.xml
             ${{ github.workspace }}/llama/src/main/resources/net/ladenthin/llama/**/*
           if-no-files-found: warn
 
@@ -1502,13 +1502,13 @@ jobs:
         with:
           name: windows-output-msvc
           path: |
-            ${{ github.workspace }}\hs_err_pid*.log
-            ${{ github.workspace }}\*.hprof
+            ${{ github.workspace }}\llama\hs_err_pid*.log
+            ${{ github.workspace }}\llama\*.hprof
             ${{ github.workspace }}\dumps\*.dmp
-            ${{ github.workspace }}\target\surefire-reports\*.dump
-            ${{ github.workspace }}\target\surefire-reports\*.dumpstream
-            ${{ github.workspace }}\target\surefire-reports\*.txt
-            ${{ github.workspace }}\target\surefire-reports\TEST-*.xml
+            ${{ github.workspace }}\llama\target\surefire-reports\*.dump
+            ${{ github.workspace }}\llama\target\surefire-reports\*.dumpstream
+            ${{ github.workspace }}\llama\target\surefire-reports\*.txt
+            ${{ github.workspace }}\llama\target\surefire-reports\TEST-*.xml
             ${{ github.workspace }}/llama/src/main/resources/net/ladenthin/llama/**/*
           if-no-files-found: warn
 
diff --git a/.gitignore b/.gitignore
@@ -61,8 +61,8 @@ llama/src/test/resources/**/*.gbnf
 **/*.lastModified
 llama/src/main/cpp/llama.cpp/
 
-# jcstress / jqwik test outputs (generated in repo root)
-/.jqwik-database
+# jcstress / jqwik test outputs (generated in the module dir where surefire runs, e.g. llama/)
+.jqwik-database
 
 # Local AI agent tooling (not part of the project)
 AGENTS.md
diff --git a/README.md b/README.md
@@ -931,3 +931,11 @@ The system's updated C++ runtime will be used instead, resolving the crash.
 - [gptoss.java](https://github.com/mukel/gptoss.java) — GPT-OSS architecture inference.
 - [qwen35.java](https://github.com/mukel/qwen35.java) — Qwen 3.5 inference.
 - [nemotron3.java](https://github.com/mukel/nemotron3.java) — NVIDIA Nemotron-3 inference.
+
+**Pure-Java inference engines (no JNI / no llama.cpp)**
+
+- [Jlama](https://github.com/tjake/Jlama) — a full pure-Java LLM inference engine for the JVM (multiple model architectures, quantization, and distributed inference) built on the Java Vector API. A no-native alternative to the JNI approach here; different design point (pure JVM portability vs. GGUF compatibility and llama.cpp performance via JNI).
+
+**Frameworks / orchestration**
+
+- [LangChain4j](https://github.com/langchain4j/langchain4j) — LLM-application framework for Java (chat, embeddings, RAG, tool calling, agents) over a unified provider API. This project ships a first-class **in-process** integration — see the [`llama-langchain4j`](llama-langchain4j/) module — so a llama.cpp model plugs straight into LangChain4j's `ChatModel` / `StreamingChatModel` / `EmbeddingModel` / `ScoringModel` without an HTTP hop.
diff --git a/llama/src/main/cpp/train_engine.cpp b/llama/src/main/cpp/train_engine.cpp
@@ -37,8 +37,7 @@ bool finetune(const finetune_config &cfg, std::string &err) {
         params.n_ubatch = cfg.n_ubatch;
     }
 
-    params.optimizer =
-        cfg.optimizer == 1 ? GGML_OPT_OPTIMIZER_TYPE_SGD : GGML_OPT_OPTIMIZER_TYPE_ADAMW;
+    params.optimizer = cfg.optimizer == 1 ? GGML_OPT_OPTIMIZER_TYPE_SGD : GGML_OPT_OPTIMIZER_TYPE_ADAMW;
     params.lr.lr0 = cfg.learning_rate;
     params.lr.lr_min = cfg.lr_min;
     params.lr.decay_epochs = cfg.decay_epochs;
@@ -99,8 +98,8 @@ bool finetune(const finetune_config &cfg, std::string &err) {
     ggml_opt_result_t result_eval = ggml_opt_result_init();
 
     for (params.lr.epoch = 0; params.lr.epoch < params.lr.epochs; ++params.lr.epoch) {
-        llama_opt_epoch(ctx, dataset, result_train, result_eval, idata_split,
-                        ggml_opt_epoch_callback_progress_bar, ggml_opt_epoch_callback_progress_bar);
+        llama_opt_epoch(ctx, dataset, result_train, result_eval, idata_split, ggml_opt_epoch_callback_progress_bar,
+                        ggml_opt_epoch_callback_progress_bar);
         ggml_opt_result_reset(result_train);
         ggml_opt_result_reset(result_eval);
     }
@@ -118,8 +117,8 @@ bool finetune(const finetune_config &cfg, std::string &err) {
 
 } // namespace jllama_train
 
-extern "C" JNIEXPORT jstring JNICALL
-Java_net_ladenthin_llama_LlamaTrainer_finetuneNative(JNIEnv *env, jclass, jstring jconfig) {
+extern "C" JNIEXPORT jstring JNICALL Java_net_ladenthin_llama_LlamaTrainer_finetuneNative(JNIEnv *env, jclass,
+                                                                                          jstring jconfig) {
     std::string config_json;
     if (jconfig != nullptr) {
         const char *c = env->GetStringUTFChars(jconfig, nullptr);
diff --git a/llama/src/main/java/net/ladenthin/llama/LlamaTrainer.java b/llama/src/main/java/net/ladenthin/llama/LlamaTrainer.java
@@ -51,14 +51,13 @@ public static void finetune(TrainingParameters parameters) {
      * @throws LlamaException if the model cannot be loaded or training fails
      */
     public static void finetune(Path model, String trainingText, Path output, int epochs, float learningRate) {
-        finetune(
-                TrainingParameters.builder()
-                        .modelPath(model)
-                        .trainingText(trainingText)
-                        .outputPath(output)
-                        .epochs(epochs)
-                        .learningRate(learningRate)
-                        .build());
+        finetune(TrainingParameters.builder()
+                .modelPath(model)
+                .trainingText(trainingText)
+                .outputPath(output)
+                .epochs(epochs)
+                .learningRate(learningRate)
+                .build());
     }
 
     private static native String finetuneNative(String configJson);
diff --git a/llama/src/main/java/net/ladenthin/llama/parameters/TrainingParameters.java b/llama/src/main/java/net/ladenthin/llama/parameters/TrainingParameters.java
@@ -15,7 +15,7 @@
 /**
  * Immutable configuration for a {@link net.ladenthin.llama.LlamaTrainer} fine-tuning run.
  *
- * <p>Build with {@link #builder()}; only {@code modelPath} and {@code outputPath} are required, and
+ * <p>Build with {@code builder()}; only {@code modelPath} and {@code outputPath} are required, and
  * exactly one of {@code trainingText} / {@code trainingFile} should be set. All other fields default
  * to values that mirror upstream llama.cpp's fine-tuning defaults. The configuration is serialized to
  * JSON via {@link #toJson()} and parsed by the native layer, the same way {@link ModelParameters} and
@@ -38,40 +38,88 @@ public final class TrainingParameters {
     private final Path outputPath;
 
     // Number of passes over the corpus (at least 1).
-    @Builder.Default private final int epochs = 2;
+    @Builder.Default
+    private final int epochs = 2;
 
     // Learning rate at the first epoch.
-    @Builder.Default private final float learningRate = 1e-5f;
+    @Builder.Default
+    private final float learningRate = 1e-5f;
 
     // Minimum learning rate for decay, or -1 to disable decay.
-    @Builder.Default private final float lrMin = -1f;
+    @Builder.Default
+    private final float lrMin = -1f;
 
     // If > 0, decay the learning rate from learningRate to lrMin over this many epochs.
-    @Builder.Default private final float decayEpochs = -1f;
+    @Builder.Default
+    private final float decayEpochs = -1f;
 
     // Weight decay (0 disables it).
-    @Builder.Default private final float weightDecay = 0f;
+    @Builder.Default
+    private final float weightDecay = 0f;
 
     // Optimizer algorithm.
-    @Builder.Default private final Optimizer optimizer = Optimizer.ADAMW;
+    @Builder.Default
+    private final Optimizer optimizer = Optimizer.ADAMW;
 
     // Context size in tokens, or 0 to use the model's trained context.
-    @Builder.Default private final int nCtx = 0;
+    @Builder.Default
+    private final int nCtx = 0;
 
     // Layers to offload to the GPU, or -1 for automatic.
-    @Builder.Default private final int nGpuLayers = -1;
+    @Builder.Default
+    private final int nGpuLayers = -1;
 
     // Fraction of the corpus held out for validation.
-    @Builder.Default private final float valSplit = 0.05f;
+    @Builder.Default
+    private final float valSplit = 0.05f;
 
     // Logical batch size, or 0 to use the native default.
-    @Builder.Default private final int nBatch = 0;
+    @Builder.Default
+    private final int nBatch = 0;
 
     // Physical (micro) batch size, or 0 to use the native default.
-    @Builder.Default private final int nUbatch = 0;
+    @Builder.Default
+    private final int nUbatch = 0;
 
     private static final ObjectMapper MAPPER = new ObjectMapper();
 
+    // Explicit all-args constructor used by the Lombok-generated builder. Declared explicitly (rather
+    // than letting @Builder synthesize the package-private one) so Javadoc sees a real constructor and
+    // does not emit the "use of default constructor, which does not provide a comment" warning; it is
+    // private, so it is not part of the public API and is not doclint-checked.
+    private TrainingParameters(
+            Path modelPath,
+            @Nullable String trainingText,
+            @Nullable Path trainingFile,
+            Path outputPath,
+            int epochs,
+            float learningRate,
+            float lrMin,
+            float decayEpochs,
+            float weightDecay,
+            Optimizer optimizer,
+            int nCtx,
+            int nGpuLayers,
+            float valSplit,
+            int nBatch,
+            int nUbatch) {
+        this.modelPath = modelPath;
+        this.trainingText = trainingText;
+        this.trainingFile = trainingFile;
+        this.outputPath = outputPath;
+        this.epochs = epochs;
+        this.learningRate = learningRate;
+        this.lrMin = lrMin;
+        this.decayEpochs = decayEpochs;
+        this.weightDecay = weightDecay;
+        this.optimizer = optimizer;
+        this.nCtx = nCtx;
+        this.nGpuLayers = nGpuLayers;
+        this.valSplit = valSplit;
+        this.nBatch = nBatch;
+        this.nUbatch = nUbatch;
+    }
+
     /**
      * Serialize this configuration to the JSON object the native fine-tuning layer expects.
      *
diff --git a/llama/src/test/java/net/ladenthin/llama/LlamaTrainerIntegrationTest.java b/llama/src/test/java/net/ladenthin/llama/LlamaTrainerIntegrationTest.java
@@ -37,15 +37,14 @@ void finetuneWritesAnOutputModel(@TempDir Path tmp) throws Exception {
         }
 
         Path output = tmp.resolve("finetuned.gguf");
-        LlamaTrainer.finetune(
-                TrainingParameters.builder()
-                        .modelPath(Paths.get(modelPath))
-                        .trainingText(corpus.toString())
-                        .outputPath(output)
-                        .epochs(1)
-                        .learningRate(1e-5f)
-                        .optimizer(Optimizer.ADAMW)
-                        .build());
+        LlamaTrainer.finetune(TrainingParameters.builder()
+                .modelPath(Paths.get(modelPath))
+                .trainingText(corpus.toString())
+                .outputPath(output)
+                .epochs(1)
+                .learningRate(1e-5f)
+                .optimizer(Optimizer.ADAMW)
+                .build());
 
         assertThat(Files.exists(output), is(true));
         assertThat(Files.size(output), greaterThan(0L));
diff --git a/llama/src/test/java/net/ladenthin/llama/parameters/TrainingParametersTest.java b/llama/src/test/java/net/ladenthin/llama/parameters/TrainingParametersTest.java
@@ -24,12 +24,11 @@ private JsonNode json(TrainingParameters parameters) throws Exception {
 
     @Test
     void defaultsSerializeWithExpectedValues() throws Exception {
-        TrainingParameters parameters =
-                TrainingParameters.builder()
-                        .modelPath(Paths.get("base.gguf"))
-                        .trainingText("hello world")
-                        .outputPath(Paths.get("tuned.gguf"))
-                        .build();
+        TrainingParameters parameters = TrainingParameters.builder()
+                .modelPath(Paths.get("base.gguf"))
+                .trainingText("hello world")
+                .outputPath(Paths.get("tuned.gguf"))
+                .build();
 
         JsonNode node = json(parameters);
         assertThat(node.get("model_path").asText(), is("base.gguf"));
@@ -46,20 +45,19 @@ void defaultsSerializeWithExpectedValues() throws Exception {
 
     @Test
     void customValuesSerialize() throws Exception {
-        TrainingParameters parameters =
-                TrainingParameters.builder()
-                        .modelPath(Paths.get("base.gguf"))
-                        .trainingFile(Paths.get("corpus.txt"))
-                        .outputPath(Paths.get("tuned.gguf"))
-                        .epochs(5)
-                        .learningRate(3e-4f)
-                        .optimizer(Optimizer.SGD)
-                        .nCtx(512)
-                        .nGpuLayers(0)
-                        .valSplit(0.1f)
-                        .nBatch(256)
-                        .nUbatch(64)
-                        .build();
+        TrainingParameters parameters = TrainingParameters.builder()
+                .modelPath(Paths.get("base.gguf"))
+                .trainingFile(Paths.get("corpus.txt"))
+                .outputPath(Paths.get("tuned.gguf"))
+                .epochs(5)
+                .learningRate(3e-4f)
+                .optimizer(Optimizer.SGD)
+                .nCtx(512)
+                .nGpuLayers(0)
+                .valSplit(0.1f)
+                .nBatch(256)
+                .nUbatch(64)
+                .build();
 
         JsonNode node = json(parameters);
         assertThat(node.get("epochs").asInt(), is(5));
