Skip to content

Split big-window rule per source kind; add Java 8 checker-qual override docs #128

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bernardladenthin merged 2 commits into from
Jun 30, 2026
Merged

Split big-window rule per source kind; add Java 8 checker-qual override docs #128

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
695ca92
docs: note Java-8 checker-qual override (3.55.1) for plugin execution
claude Jun 30, 2026
a10b13c
feat(selftest): add big-window-sql rule, rename big-window -> big-win…
claude Jun 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,9 @@ The release procedure (prompt template and step-by-step instructions) lives in [

## [Unreleased]

### Changed
- Split the big-window size-routing rule per source kind in the `ai-index-selftest` example POM: the former single `big-window` rule is now `big-window-java` (prompt `file-body-java`), and a matching `big-window-sql` rule (prompt `file-body-sql`) routes oversized `.sql` sources to the same large-context model — so an oversized `.sql` file keeps the SQL prompt instead of being misrouted/uncovered.

## [1.0.1] - 2026-06-29

### Added
Expand Down
41 changes: 40 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,45 @@ The plugin runs in three phases, building a navigable index from fine to coarse.
- Maven 3.6.3+
- Local GGUF model (llama.cpp compatible)

### Running under Java 8: override `checker-qual`

The plugin itself is compiled to Java 8 bytecode, but it pulls in
[`org.checkerframework:checker-qual`](https://central.sonatype.com/artifact/org.checkerframework/checker-qual)
transitively, and the version it builds against (`4.2.0`) ships its classes as **Java 11
bytecode** (class-file major version 55). On a **Java 8** JVM, loading those annotation
classes fails with `UnsupportedClassVersionError`.

If you run the plugin under a Java 8 Maven/JVM, **override `checker-qual` to `3.55.1`** — the
**last release whose runtime classes are Java 8 bytecode** (major 52). The `checker-qual` line
switched to Java 11 bytecode in `4.0.0`; every `3.x` release (`3.42.0` … `3.55.1`) is Java 8
loadable, and `3.55.1` is the newest of them. (`checker-qual` `3.43.0`–`3.55.1` additionally
carry a root `module-info.class`, which a Java 8 classpath simply ignores; if you want a jar
with no `module-info.class` at all, `3.42.0` is the last such release.)

Because this is a *plugin* dependency, the override goes inside the plugin's own
`<dependencies>` block (a project-level `<dependencyManagement>` does **not** affect a plugin's
classpath):

```xml
<plugin>
<groupId>net.ladenthin</groupId>
<artifactId>llamacpp-ai-index-maven-plugin</artifactId>
<!-- ... version + configuration ... -->
<dependencies>
<!-- Java 8 execution: pin the last Java-8-bytecode checker-qual.
The plugin builds against 4.2.0, which is Java 11 bytecode and
cannot be loaded by a Java 8 JVM. -->
<dependency>
<groupId>org.checkerframework</groupId>
<artifactId>checker-qual</artifactId>
<version>3.55.1</version>
</dependency>
</dependencies>
</plugin>
```

Running the plugin under Java 11 or newer needs no override.

## Dependency

The plugin depends on [`net.ladenthin:llama`](https://central.sonatype.com/artifact/net.ladenthin/llama), the Java/JNI binding for llama.cpp.
Expand Down Expand Up @@ -168,7 +207,7 @@ The plugin is configured from three building blocks, declared on the plugin insi
file too large for the window would lose content if trimmed, so the build **always fails** (a hard
abort). The fix is **configuration only** — the plugin never picks a model for you: add a
`<fieldGeneration>` rule with a size `<condition>` that routes oversized files to a model with a large
enough window (see the `granite-4.0-h-tiny-bigwindow` definition + the `big-window` rule in the POM —
enough window (see the `granite-4.0-h-tiny-bigwindow` definition + the `big-window-java` / `big-window-sql` rules in the POM —
IBM Granite 4.0-H-Tiny, Apache-2.0, a hybrid Mamba model whose KV cache grows only linearly, configured
at a 384K window to cover files up to ~1 MB; verified summarizing a ~995 KB / ~268K-token file on an
8 GB GPU with no OOM. Quality is best within Granite's validated 128K (~500 KB) and degrades gradually
Expand Down
44 changes: 32 additions & 12 deletions pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1559,8 +1559,8 @@ SPDX-License-Identifier: Apache-2.0
the window check over-counts tokens and never lets a file overflow the
window at run time); the cpt-3 check admits up to ~1.16 MB. reasoningEffort
is empty: Granite has no gpt-oss harmony channels, so no reasoning kwarg is
sent. The size-routing rule that targets this key lives in the ai-generate
<fieldGenerations> below (id big-window). For >~1 MB files, split them or
sent. The size-routing rules that target this key live in the ai-generate
<fieldGenerations> below (ids big-window-java and big-window-sql). For >~1 MB files, split them or
add a still-larger preset (Granite allocates up to its 512K training limit
here, with further quality loss). -->
<aiDefinition>
Expand Down Expand Up @@ -2024,20 +2024,22 @@ message: the path on the first line, then a blank line, then the summaries to sy
<fileExtension>.sql</fileExtension>
</fileExtensions>
<fieldGenerations>
<!-- Big-window fallback rule: a .java file larger than the default
<!-- Big-window fallback rules: a source larger than the default
model's window (~275 KB at 96K/charsPerToken 3) would be trimmed,
so route it to the large-context granite-4.0-h-tiny-bigwindow
model instead (Granite's 384K window covers up to ~1 MB; the
cpt-3 window check admits up to ~1.16 MB). Higher priority than the plain java rule so it
wins for oversized files; normal-sized files never match (size
min) and fall through to the java rule. Without a rule like this,
a file larger than the default model's window hard-fails the build
(the plugin never auto-selects a model) - this is how YOU satisfy
that check. Threshold is conservative; tune to your model's
window. (A file beyond Granite's window fails too: split it or add
a still-larger fallback.) -->
cpt-3 window check admits up to ~1.16 MB). There is one big-window
rule per source kind so each keeps its own prompt: big-window-java
(file-body-java) and big-window-sql (file-body-sql). Each has higher
priority than its plain java/sql counterpart so it wins for oversized
files; normal-sized files never match (size min) and fall through to
the plain rule. Without rules like these, a file larger than the
default model's window hard-fails the build (the plugin never
auto-selects a model) - this is how YOU satisfy that check. Threshold
is conservative; tune to your model's window. (A file beyond Granite's
window fails too: split it or add a still-larger fallback.) -->
<fieldGeneration>
<id>big-window</id>
<id>big-window-java</id>
<promptKey>file-body-java</promptKey>
<aiDefinitionKey>granite-4.0-h-tiny-bigwindow</aiDefinitionKey>
<priority>100</priority>
Expand All @@ -2054,6 +2056,24 @@ message: the path on the first line, then a blank line, then the summaries to sy
</and>
</condition>
</fieldGeneration>
<fieldGeneration>
<id>big-window-sql</id>
<promptKey>file-body-sql</promptKey>
<aiDefinitionKey>granite-4.0-h-tiny-bigwindow</aiDefinitionKey>
<priority>100</priority>
<condition>
<and>
<conditions>
<condition>
<extensions><extension>.sql</extension></extensions>
</condition>
<condition>
<size><min>275000</min></size>
</condition>
</conditions>
</and>
</condition>
</fieldGeneration>
<fieldGeneration>
<id>java</id>
<promptKey>file-body-java</promptKey>
Expand Down
Loading