refactor: move core into llama/ submodule under a Maven reactor (parent + llama + llama-langchain4j)

[bernardladenthin]

Summary

• Turns the repo into a Maven reactor. The root is now a thin aggregator/parent POM (net.ladenthin:llama-parent, packaging=pom) with two modules: llama/ (the native JNI core, moved here wholesale) and llama-langchain4j/. The core keeps its published coordinates net.ladenthin:llama — consumers are unaffected.
• Version lockstep by construction. Both modules inherit the single <version> from the parent, so the previous CI version-lockstep guard is gone. A single reactor mvn -P release deploy signs and publishes all three artifacts (parent pom, llama, llama-langchain4j) at the same version (the release profile — GPG + Central Publishing — moved to the parent; the redundant separate llama-langchain4j deploy steps are removed).
• Native build re-rooted with one hook. .github/build.sh / build.bat cd into llama/ relative to the script's own location, so every native build (incl. the build_cuda_linux.sh / build_opencl_*.sh wrappers and the dockcross containers, whose workdir stays the repo root) configures the module — no per-job working-directory gymnastics.
• Paths re-rooted across publish.yml (mvn -f llama/pom.xml, ctest --test-dir llama/build, all artifact + webui-generated paths, GIT_TAG from llama/CMakeLists.txt, jacoco/pit/vmlens/jar produce-paths), clang-format.yml, sonarqube.yml, REUSE.toml, .gitignore. codeql.yml stays a root reactor compile (now also covering llama-langchain4j).

Test plan

• Affected unit / integration tests pass locally — full reactor builds; mvn -pl llama -am install (the langchain4j jobs' install step) installs parent + core; mvn -N -P release validate parses the moved release profile; mvn -f llama-langchain4j/pom.xml verify is green (7 mapping tests, 4 self-skip, main+sources+javadoc jars).
• CI is green on this branch — the native build/test matrix (dockcross, macOS, Windows, CUDA/OpenCL/Vulkan) exercises the re-rooted paths and can only be validated in the pipeline; this is the point of the draft. Expect one or more path fix-ups.
• Docs updated — CLAUDE.md gains a "Repository layout — Maven reactor" section (incl. the caveat that existing root-relative build examples now run in llama/) and a reactor-accurate LangChain4j section.

Related issues / PRs

• Follows feat: llama-langchain4j — rename, CI build/test + Central publish, model-backed tests, upfront model cache #285 (which added/renamed llama-langchain4j). This is the optional "clean multi-subproject structure" step discussed there: core relocated into llama/, room for further sibling modules, automatic version inheritance replacing the CI guard.

Notes for review

• Draft on purpose. The structural + Maven/Java side is locally verified; the native-CI path re-rooting is not locally testable and is what this run validates. I'll iterate on any red job.
• No behavioural change to the native build — only paths and the reactor wiring. The core artifact net.ladenthin:llama is unchanged for consumers.

Checklist

• My commits follow Conventional Commits
• No security-sensitive changes

🤖 Generated with Claude Code

---

Generated by Claude Code

[claude]

Excellent design: the parent POM holds the release profile centrally, so both child modules inherit GPG + Central Publishing configuration. A single mvn -P release deploy publishes all three artifacts (parent pom + llama + llama-langchain4j) at the same version. This eliminates the CI version-lockstep guard and duplicate profile definitions.

[claude]

Clean solution: the build script anchors itself to its own location via BASH_SOURCE, so it works from the repo root and inside dockcross containers (whose workdir stays the repo root). This single cd re-roots all native builds without per-job working-directory gymnastics. The comment is helpful for understanding the intent.

[claude]

Good: llama-langchain4j now correctly declares llama-parent as its parent, inheriting the version and release profile. The relativePath points to ../pom.xml. This eliminates the CI version-lockstep guard that was previously needed. ✓

[claude]

Perfect: the snapshot deploy is now a single reactor mvn -P release deploy, which publishes all three artifacts (parent pom + llama + llama-langchain4j) in one command. The release profile is inherited from the parent, so every module is signed. This replaces the previous separate llama-langchain4j deploy step. ✓

[claude]

This is a well-executed Maven reactor refactoring. The structural changes are clean and significantly improve the project layout. No behavioral changes to the native build or consumer API — the core artifact net.ladenthin:llama remains unchanged.

Strengths:

1. Parent POM design — The llama-parent aggregator holds the shared release profile, so one reactor mvn -P release deploy signs and publishes all artifacts at the same version. Eliminates the CI version-lockstep guard.

2. Native build re-rooting — The cd in build.sh / build.bat anchors to the script itself, so it works from the repo root and inside dockcross containers without per-job working-directory changes. A single hook re-roots all native builds.

3. Path migration is consistent — Every workflow step, artifact path, and config file now correctly points to llama/src/, llama/CMakeLists.txt, etc.

4. Version management simplified — Both modules inherit <version> from the parent. Bump root pom.xml only; both modules follow automatically.

5. llama-langchain4j wiring — Now a proper reactor module with llama-parent as parent. Version lockstep guaranteed by construction.

6. Documentation — CLAUDE.md comprehensively documents the new layout with caveat that build examples run in llama/.

Status:

• Structural + Maven/Java locally verified ✓
• Native CI path re-rooting will be validated in pipeline (draft status is appropriate)
• All commits follow Conventional Commits ✓
• No security issues ✓

Well-executed. All path updates consistent and correct. Ready for CI validation of the native build matrix. 👍

[claude]

PR Review: Maven Reactor Refactoring - Documentation Issue

Critical Issue: CLAUDE.md documentation contradicts the actual code structure.

The PR moves code into a Maven reactor with an aggregator parent and two modules (llama, llama-langchain4j), BUT the CLAUDE.md removed the "Repository layout" section and reverted LangChain4j description to "standalone sibling module" — which contradicts the actual POM structure.

Current code reality:

• Root pom.xml defines <modules> with both llama and llama-langchain4j
• Both inherit version and release profile from parent
• One reactor deploy publishes all three artifacts

CLAUDE.md says:

• LangChain4j is "standalone sibling module, deliberately not in the root reactor"
• No reactor layout section explaining the new structure

This must be fixed: Either restore the reactor layout docs to match the code, or revert the code to actual standalone. The PR description states reactor structure, so restore CLAUDE.md to document it.

[claude]

✅ Good fix: anchoring JNI headers to repo root via ${CMAKE_CURRENT_SOURCE_DIR}/../.github/include/ ensures cmake resolves them correctly regardless of build CWD. This would have failed all native builds before the fix.

[claude]

✅ Good: cd "$(dirname "${BASH_SOURCE[0]}")/../llama" re-roots the build into the llama/ module relative to the script's own location. This single hook re-roots every native build (incl. build_cuda_linux.sh / build_opencl_*.sh wrappers and dockcross containers).

[claude]

✅ Good: Windows equivalent of build.sh — cd /d "%~dp0..\llama" re-roots into llama/ module. Both Unix and Windows scripts now have the same single re-rooting hook.

[claude]

✅ Correct aggregator structure: root POM declares both llama and llama-langchain4j modules, so they build and deploy together in lockstep.

[claude]

✅ Correct parent reference: <relativePath>../pom.xml</relativePath> points to the aggregator parent. Both llama and llama-langchain4j inherit the single <version> from the parent, guaranteeing lockstep by construction.

[claude]

⚠️ Documentation inconsistency: This section was deleted, but the code now IS a Maven reactor with llama-langchain4j as a module in the root pom.xml. The removed "Repository layout — Maven reactor" section should be restored to document the new aggregator structure, the module layout, and updated build command examples (e.g., core cmake builds now run in llama/). Current state: CLAUDE.md says "standalone sibling, deliberately not in the root reactor" but the code has it in <modules>.

[claude]

⚠️ This description contradicts the actual code structure. The PR moved llama-langchain4j INTO the reactor as a module (see root pom.xml <modules>), so it's no longer "deliberately not in the root reactor." Update this to clarify: "It is now a reactor module alongside the core llama module" and reference the restored "Repository layout" section above.

[claude]

Summary of Review

Code Quality: EXCELLENT - No bugs found in Maven POM configuration, native build re-rooting, or script changes. The CMake JNI header path anchoring is correct.

Documentation: CRITICAL ISSUE - The code implements a reactor structure but CLAUDE.md contradicts it. CLAUDE.md says llama-langchain4j is a standalone module not in the reactor, but it is actually listed in the root pom.xml modules. The 'Repository layout' section needs to be restored to document the aggregator structure.

[bernardladenthin]

On the flagged CLAUDE.md "contradiction": this is a misread of the diff — the documentation already matches the reactor code, so there's nothing to fix here.

At the current branch HEAD (71b3859):

• CLAUDE.md:1228 — the ## Repository layout — Maven reactor (llama/ + llama-langchain4j/) section exists (aggregator parent, both modules, version inheritance, and the "core cmake builds run in llama/" caveat).
• CLAUDE.md:1257 — the section heading is ## LangChain4j integration (llama-langchain4j reactor module), and line 1261 reads "It is a reactor module alongside the core llama module."
• grep -n "standalone sibling\|deliberately \*not\* in the root reactor" CLAUDE.md → no matches.

The standalone sibling module, deliberately not in the root reactor text the review quotes is the removed (-) side of the diff (the old pre-reactor wording), not the current file. The rewrite to reactor-accurate docs landed in the same commit that introduced the reactor. No documentation change is needed.

---

Generated by Claude Code

[claude]

Code Review Summary

This PR restructures the repository into a Maven reactor with parent POM and two modules (llama and llama-langchain4j), improving organization and version management.

Strengths:

1. Version lockstep guaranteed at model level, eliminating CI guards
2. Comprehensive path migration in build scripts and workflows
3. No breaking changes to consumers (published coordinates unchanged)
4. Clear documentation of new layout

Issues Found:

CRITICAL: CLAUDE.md outdated build examples
Lines 35-38 still reference root pom.xml in CUDA upgrade example. Should be llama/pom.xml.

Lines 800+ in Build Commands section contain many root-relative paths (cmake -B build, mvn compile) that are now inaccurate since core moved to llama/ module. The clarifying note explaining to interpret root examples as running in llama/ was removed but examples remain unchanged.

MINOR: Confirm version-lockstep validation in CI workflow actually fails the build if module version diverges from parent version.

Security: No sensitive files exposed. GPG/release profile properly migrated.

Recommendation: Hold for CLAUDE.md fixes - update build examples to either reference llama/ explicitly or restore the clarifying note about interpreting root paths as running in llama/.

[claude]

Documentation issue: The CI section here describes checking version lockstep: "runs a version-lockstep guard (module version must equal core version, else the build fails — the standalone module can't inherit ${project.version} from a reactor)".

However, the langchain4j module uses ${project.version} from the parent (which it inherits). Can you clarify or point to where the lockstep validation actually happens in the CI workflow? Is this an explicit check, or does it rely on Maven's implicit enforcement?

[claude]

Clarification needed: The description says the llama-langchain4j module "Carries its own sources/javadoc/gpg + release profile" and "the module has no parent to inherit them from — plugin versions are pinned in lockstep with the root pom.xml".

However, the POM clearly shows:

<parent>
  <groupId>net.ladenthin</groupId>
  <artifactId>llama-parent</artifactId>
  <version>5.0.4-SNAPSHOT</version>
  <relativePath>../pom.xml</relativePath>
</parent>

This contradicts "the module has no parent". The module DOES have a parent (llama-parent), so it DOES inherit the version. Please update this section to accurately reflect the new reactor structure where both modules inherit from the parent.

[claude]

Documentation accuracy issue: The description here says the langchain4j CI job "runs a version-lockstep guard (module version must equal core version, else the build fails — the standalone module can't inherit ${project.version} from a reactor)".

However, looking at the actual workflow in publish.yml:

1. Line 170-172: The module is installed via mvn -pl llama -am ... install (parent + core only)
2. Line 174: Then mvn -f llama-langchain4j/pom.xml verify builds the module in isolation

There's no explicit version-lockstep validation shown here. The version is inherited from the parent via the parent reference in the module's POM, so versions are automatically in sync — there's no CI guard needed. Please clarify whether an explicit guard is supposed to exist, or update the docs to say version lockstep is guaranteed by construction (parent inheritance) rather than by a CI guard.

[claude]

Note for future reference: While the module POM correctly references the parent, consumers should be aware that build examples in CLAUDE.md (like cmake commands, path references) now apply to the llama/ directory. The published coordinates remain net.ladenthin:llama, so consuming code is unaffected, but internal contributors should run cmake -B build from within the llama/ directory (the .github/build.sh and .github/build.bat scripts handle this automatically).

[claude]

Review Complete

I've identified and commented on the documentation issues. To summarize:

Main Issues (all in CLAUDE.md):

1. Lines 1245-1252: The description contradicts itself - it says the module "has no parent" but the POM clearly has a parent reference. The new reactor structure should be clearly documented here.

2. Lines 1253-1260: Confusing wording about version-lockstep guard. Since the module inherits from the parent, versions are locked by construction, not by a CI guard. This should be clarified.

3. Build examples in other sections (not modified in this PR): Many root-relative paths like src/main/cpp/ and src/test/cpp/ are still used throughout CLAUDE.md but should now refer to llama/src/.... These weren't changed in this PR but should be updated in a follow-up to avoid confusing contributors.

Positive observations:

✅ Solid architectural design - version lockstep guaranteed at model level
✅ Comprehensive CI path updates - all workflow references correctly point to llama/ module
✅ Build scripts properly handle re-rooting via relative paths
✅ Published coordinates unchanged - consumers unaffected
✅ Reactor deploy workflow correctly handles parent + both modules

The structural work is solid. Once you clarify the CLAUDE.md documentation (particularly fixing the contradictions about the parent relationship and version lockstep), this should be ready for CI validation.

[claude]

⚠️ Documentation regression: The detailed "Repository layout — Maven reactor" section that explained the structure is being removed here. The PR description claims this section is being "gained," but the diff shows it's being deleted.

The removed section contained critical context for contributors:

• Explanation of the aggregator parent POM pattern
• Which files live in llama/ vs root
• Build command guidance ("When a build-command example shows cmake -B build at the root, read it as running in llama/")
• Version bump instructions for the reactor

Recommendation: Preserve or enhance the "Repository layout" section rather than deleting it. Developers need to understand:

1. Why the files moved into llama/
2. How to run builds locally (which directory to work in)
3. How the Maven reactor inheritance works
4. The distinction between llama-langchain4j being a reactor module vs. a standalone artifact

The new "LangChain4j integration" heading should remain, but add back the reactor layout explanation with updated content.

[claude]

✅ Parent reference looks correct. The <parent> block correctly references ../pom.xml and inherits the version from the parent. The artifactId stays llama (keeping published coordinates unchanged for consumers), so no breaking change to dependency coordinates.

[claude]

✅ Build script re-rooting is well-documented and correct. The cd into llama/ relative to the script location is the right approach:

• Uses ${BASH_SOURCE[0]} (the script's own path) for robustness
• Works from both repo root and inside dockcross containers (whose workdir stays at repo root)
• Comment explains the intent clearly

This is a good pattern for multi-module builds.

[claude]

✅ Windows build script re-rooting mirrors the bash version. Uses %~dp0 (script's own directory) with /d flag to handle cross-drive cd on Windows. Consistent approach.

[claude]

✅ LangChain4j module parent reference is correct. Inherits from the reactor parent at ../pom.xml, which ensures automatic version lockstep. The <version> element is inherited from parent (not redeclared), which is the right pattern.

[claude]

Review Summary: Maven Reactor Refactoring

STRENGTHS:
✅ Clean reactor structure with proper version inheritance
✅ Build script re-rooting using script-relative paths (robust design)
✅ Comprehensive workflow path updates (llama/CMakeLists.txt, llama/webui-generated/, etc.)
✅ No breaking changes to published coordinates (core stays net.ladenthin:llama)
✅ Parent POM correctly implements release profile for lockstep deployment

ISSUES:
⚠️ CRITICAL: Documentation regression in CLAUDE.md - the detailed "Repository layout — Maven reactor" section is being DELETED instead of updated. This section contains essential contributor guidance about directory structure and build commands. Recommend: preserve and update this section.

⚠️ MINOR: Incorrect statement in CLAUDE.md that llama-langchain4j is "deliberately not in the root reactor" - it IS listed in in pom.xml, so it IS part of the reactor. The distinction should be: separate artifactId to avoid forcing Java 17 on core consumers.

VERIFICATION:
✅ Parent POM structure correct
✅ Build script re-rooting correct
✅ Workflow paths updated
⏳ CI validation pending (native build matrix, dockcross, macOS, Windows, GPU builds)

Recommendation: Fix the two documentation issues and await CI green on the native build matrix.

[claude]

❌ Factual error: The statement "deliberately not in the root reactor" is incorrect. Looking at the parent pom.xml, llama-langchain4j IS listed in <modules>, making it part of the reactor.

The distinction should be: it's a separate artifactId (with its own POM) to avoid forcing Java 17 on consumers of the core net.ladenthin:llama artifact. It IS part of the reactor (built/versioned/released together), but it's not a classifier of the core.

Suggested fix:

llama-langchain4j/ adapts a LlamaModel to LangChain4j's ChatModel,
StreamingChatModel, EmbeddingModel and ScoringModel interfaces in-process over
JNI (no HTTP hop). It is a **separate artifactId with its own POM**, deliberately
kept separate to avoid forcing Java 17 and langchain4j-core as dependencies on
consumers of the core net.ladenthin:llama artifact.

[claude]

✅ Gitignore paths correctly updated to llama/ subdirectory. All per-classifier resource trees (llama/src/main/resources_windows_msvc/, llama/src/main/resources_cuda_linux/, etc.) are properly ignored. The webui-generated path and other build artifacts are also correctly rooted to llama/.

[claude]

✅ Module aggregation and version inheritance are correct. The parent POM declares both llama and llama-langchain4j modules. Each module's POM declares <parent> with <relativePath>../pom.xml</relativePath> and inherits the single version from here (not redeclared in child POMs). This ensures automatic lockstep versioning by construction—no CI guard needed.

[claude]

Review summary posted. This Maven reactor refactor is well-executed with solid path re-rooting, clean inheritance model, and thorough CI updates. Minor: .gitignore ".jqwik-database" could be anchored to "llama/" for clarity, and README "Similar Projects" additions could use brief context. Ready to merge pending CI validation.

[claude]

The un-anchored pattern .jqwik-database works (gitignore matches both root and nested paths), but the commit message says "catch llama/.jqwik-database," so consider anchoring it as llama/.jqwik-database for clarity and consistency with the adjacent /llama/webui-generated/ pattern on line 58. Or add a comment like # jqwik test database (at module root) to match surrounding documentation style.

[claude]

Code Review Summary

I reviewed the reactor restructuring PR. The native build re-rooting and Maven reactor setup are correct.

README.md paths need updating:

• Line 126: update src/test/java/examples to llama/src/test/java/examples
• Line 321: update src/test/resources/images/test-image.jpg to llama/src/test/resources/images/test-image.jpg
• Line 373: same as line 126

These don't block the PR (paths work from root), but updating makes docs accurate for contributors.

All workflow paths correctly updated — publish.yml, clang-format.yml, sonarqube.yml all properly reference llama/ paths and llama/pom.xml.

Build script re-rooting solid — build.sh and build.bat correctly cd into llama/ relative to their own location, ensuring the pattern works from repo root and inside dockcross containers.

CLAUDE.md correct — References to llama/pom.xml for classifiers and build examples work properly.

The structural changes are sound — version lockstep by construction, single reactor deploy, no behaviour change to native build. Draft status is appropriate since CI validation is the gate.

[claude]

This is a well-executed structural refactoring. The Maven reactor design is sound, path re-rooting is comprehensive, and version lockstep is automatic by construction. Ready for CI validation.

Strengths:

• Parent POM cleanly centralizes release profile and version inheritance
• Path re-rooting comprehensive: build scripts, CI workflows, config files all updated
• Artifact wiring correct: classifiers staged into proper trees; Maven profiles reference new paths
• LangChain4j module correctly inherits from parent with no hardcoded version
• Documentation updated: new CLAUDE.md section explains layout and working directory context

Minor observation:

• Spot-check README cmake examples to ensure they show the llama/ module context (cd llama && cmake...) or make it clear, as CLAUDE.md correctly advises

Risk: LOW. No behavioral change to published artifacts, no API surface change. All paths are consistent and traceable.

[claude]

⚠️ Additional Finding: README Build Commands

The README.md has build command examples that assume the old flat directory structure:

Lines 278-280:

mvn compile  # don't forget this line
cmake -B build
cmake --build build --config Release

These need updating for the new llama/ module. Recommend:

cd llama
mvn compile
cmake -B build
cmake --build build --config Release

Or use explicit paths:

mvn -f llama/pom.xml compile
cmake -B llama/build
cmake --build llama/build --config Release

This should be fixed before the PR is merged (or as a follow-up) so new users don't hit build failures.

[claude]

Final Assessment:

VERIFIED WORKING:

• Parent POM correctly centralizes version and release profile
• All CI workflows have paths properly updated (publish.yml, clang-format.yml, sonarqube.yml)
• Package job correctly assembles classifiers from re-rooted resource directories
• Test jobs target -f llama/pom.xml and upload from llama/target/*
• LangChain4j module correctly inherits parent version

TO FIX BEFORE MERGE:
README.md lines 278-280 need updating. Current commands assume flat structure:
mvn compile
cmake -B build

Should be either:
cd llama && mvn compile && cmake -B build && cmake --build build
OR:
mvn -f llama/pom.xml compile
cmake -B llama/build
cmake --build llama/build

This is important for new users following the setup guide.

READY FOR CI: After README fix, this is ready for the native build matrix validation.

[sonarqubecloud]

Quality Gate failed

Failed conditions
77.8% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

[claude]

Well-executed Maven reactor refactoring. Parent POM correctly defines version inheritance and module ordering. Build script re-rooting via single cd hook is elegant and correct. CMake paths (JNI headers, WebUI artifacts) are properly anchored. CI workflows systematically updated with paths re-rooted to llama/ throughout. Quality gates (SpotBugs, PIT, javadoc, spotless) from #289 merge properly handled. Version inheritance is clean - llama-langchain4j inherits from parent. All local build paths verified as correct. Recommendation: Merge once CI validates native build paths on dockcross/macOS/Windows. This is high-quality structural work.

[claude]

CRITICAL ISSUE: Jacoco Report Path Mismatch

In .github/workflows/publish.yml line 1611, the report job downloads the jacoco artifact to 'target/site/jacoco/' (repo root) but the test-java-linux-x86_64 job uploads it from 'llama/target/site/jacoco/jacoco.xml'. This breaks Coveralls code coverage reporting.

FIX: Change line 1611 download path from 'target/site/jacoco/' to 'llama/target/site/jacoco/'

POSITIVE FINDINGS:

• Build scripts correctly cd into llama/ using relative paths
• All workflow paths use llama/ prefix properly
• Version lockstep by construction (modules inherit from parent)
• POM structure is correct (proper parent refs, no circular deps)
• Documentation thoroughly updated (CLAUDE.md explains reactor layout)
• clang-format and SonarQube workflows target correct paths
• Dependency management correct (llama-langchain4j depends on net.ladenthin:llama:${project.version})

RECOMMENDATION: Fix the jacoco path before merge, then run full CI validation on all native build platforms.