diff --git a/docs/ai-index-benchmark/AGENTIC-CPU-BENCH.md b/docs/ai-index-benchmark/AGENTIC-CPU-BENCH.md new file mode 100644 index 0000000..19715f7 --- /dev/null +++ b/docs/ai-index-benchmark/AGENTIC-CPU-BENCH.md @@ -0,0 +1,100 @@ + + +# Agentic reaction‑time benchmark (local models, CPU) + +Measures **reaction time** (time‑to‑first‑token / prefill), decode speed, and **native +tool‑calling capability** for an agentic use case (e.g. Continue.dev), via `llama-server` +with `--jinja` (OpenAI‑compatible `/v1/chat/completions` + `tools`). One tool is defined +(`run_tests(module)`) and the model must emit a valid `tool_call`. + +- **Hardware:** AMD Ryzen 7 5800H (8 threads), CPU‑only unless noted. RTX 3070 8 GB for the GPU note. +- **Harness:** `tools/agentic-cpu-ctx.sh` (context sweep) and `tools/agentic-bench.sh` (single‑shot), + parsers `tools/parse-agentic*.py`, plot `tools/plot-context-curves.py`. Raw data in `tools/*.tsv`. + +## 1. Which models can actually do agentic (native tool_calls)? + +| Model | tool_call | note | +|---|---|---| +| **granite‑4.0‑h‑tiny** (1B‑act hybrid) | ✅ native | + fastest | +| **gpt‑oss‑20b** (3.6B‑act) | ✅ native | quality, but slow (reasoning) | +| Qwen2.5‑Coder‑14B / 32B | ⚠️ **text only** | emits `` as prose; llama‑server didn't parse it natively here | +| DeepSeek‑Coder‑7B‑v1.5 (Q8) | ❌ **none** | 2024 coder, no tool training | + +Only **h‑tiny** and **gpt‑oss** produced valid native tool calls out of the box. + +## 2. Reaction time vs. context (the agent loads files → context grows) + +CPU reaction time (TTFT) and prefill speed vs. context size for the two agentic‑capable models: + +![h-tiny vs gpt-oss, CPU, context](htiny-vs-gptoss-cpu-context.png) + +| context (tokens) | h‑tiny TTFT | gpt‑oss TTFT | h‑tiny faster by | +|---|---|---|---| +| ~700 | 5.7 s | 10.2 s | 1.8× | +| ~2,200 | 8.2 s | 13.4 s | 1.6× | +| ~4,200 | 12.8 s | 21.0 s | 1.6× | +| ~8,200 | 23.2 s | 40.1 s | 1.7× | +| ~12,000 | 33.4 s | 67.4 s | 2.0× | +| ~16,000 | 43.9 s | 93.0 s | **2.1×** | + +**No speed crossover: h‑tiny wins at every context, and the lead *grows* as context fills.** +Prefill speed explains it — h‑tiny (hybrid/Mamba) *rises* with context and plateaus high +(129 → 366 tok/s); gpt‑oss (transformer) peaks (~203) then *degrades* (172 at 16k) as O(L²) +attention bites. + +## 3. Full 5‑model CPU table (reaction time by context) + +From `tools/agentic-5models-cpu.tsv` (TTFT / decode tok/s / tool_ok): + +| Model | ~700 tok | ~3.3k tok | ~16k tok | decode | +|---|---|---|---|---| +| granite‑4.0‑h‑tiny | 6.0 s / ✅ | 19.3 s / ✅ | 46 s / ✅ | ~9 | +| gpt‑oss‑20b | 30 s* / ✅ | 18.8 s / ✅ | 101 s / ✅ | 3–7 | +| deepseek‑coder‑7b‑v1.5 | 18.9 s / ❌ | 69.6 s / ❌ | — | 3–5 | +| Qwen2.5‑Coder‑14B | 32 s / ⚠️ | 108 s / ⚠️ | ctx‑err | 2.5–3 | +| Qwen2.5‑Coder‑32B | 45 s / ⚠️ | 113 s / ⚠️ | ctx‑err | 1.6–1.9 | + +\* cold first request; warm prefill ~160 tok/s. + +## 3b. GPU backend: OpenCL vs Vulkan (non‑CUDA), and CPU‑vs‑GPU curves + +Goal: a **non‑CUDA** GPU path on the RTX 3070 (8 GB). + +- **OpenCL does NOT work on this NVIDIA GPU.** llama.cpp's OpenCL backend finds the card but rejects + it: `ggml_opencl: unsupported GPU 'NVIDIA GeForce RTX 3070 Laptop GPU'. drop unsupported device` → + `no usable GPU found, --gpu-layers ignored` (falls back to CPU). llama.cpp OpenCL targets + Adreno/Qualcomm; desktop NVIDIA/AMD are out. +- **Vulkan works and is ~CUDA‑fast** (vendor‑neutral). The winget `llama-server` is a Vulkan build and + sees the 3070 as `Vulkan1`. Use `--device Vulkan1 -ngl `. + +CPU vs Vulkan‑GPU, reaction time + prefill vs context, both models: + +![CPU vs Vulkan GPU](htiny-vs-gptoss-cpu-vs-vulkan.png) + +| combination | TTFT @16k | prefill | +|---|---|---| +| **granite‑h‑tiny · GPU (Vulkan, full)** | **5.2 s** | ~3100 tok/s | +| granite‑h‑tiny · CPU | 43.9 s | ~366 tok/s | +| gpt‑oss‑20b · GPU (Vulkan, 6/24 layers) | 80.7 s | ~200 tok/s | +| gpt‑oss‑20b · CPU | 93.0 s | ~172 tok/s | + +**h‑tiny fully fits the 8 GB GPU → the only interactive combo** (TTFT stays < 5.2 s even at 16k). +**gpt‑oss (11 GB) does not fit → only 6/24 layers offload → barely faster than CPU** (still 8–81 s); +it stays CPU‑bound. So on this hardware the winning setup is unambiguous: **run the small hybrid on +the GPU (Vulkan); big models are async/CPU only.** + +## 4. Takeaways for interactive/agentic use on this laptop + +- **The only responsive agentic model on CPU is `granite‑h‑tiny`** — smallest, hybrid, native + tool‑calling, fastest, and its lead grows with context. +- **`granite‑h‑tiny` fits the 8 GB GPU (3.96 GB)** → measured **165 ms** TTFT + 146 tok/s there + (vs 5.7 s on CPU). So run it on the GPU: the CPU curves above are the worst case. +- **gpt‑oss** = quality/async only (30–100 s reaction). +- **14B/32B dense coders are async‑only on CPU** (45–113 s even at low context) — "hand it off, + get coffee". `RAM fitting ≠ interactive speed` — the CPU memory‑bandwidth bottleneck dominates. +- Big‑model "20–30 tok/s on CPU" claims do **not** hold here: measured decode is ~2–3 tok/s (14B/32B). + +> Temporary experiment scaffold, not production config. diff --git a/docs/ai-index-benchmark/HSMALL-VS-GPTOSS.md b/docs/ai-index-benchmark/HSMALL-VS-GPTOSS.md new file mode 100644 index 0000000..6abfcbe --- /dev/null +++ b/docs/ai-index-benchmark/HSMALL-VS-GPTOSS.md @@ -0,0 +1,176 @@ + + +# Granite 4.0 H‑Small vs gpt‑oss‑20B — one model for everything? + +A focused head‑to‑head between **IBM Granite 4.0 H‑Small** (Unsloth **UD‑Q4_K_XL**, hybrid +Mamba‑2 + sparse‑MoE, 32B total / ~9B active) and **OpenAI gpt‑oss‑20B** (UD‑Q4_K_XL, MoE, +~3.6B active) for the plugin's code‑summarization task, on **CPU and GPU**. + +Motivating question: *can a single well‑configured Granite hybrid replace the two‑model setup +(gpt‑oss for precision, H‑Tiny for speed), given Mamba's long‑context advantage?* + +## TL;DR verdict + +- **Quality: a genuine peer.** On the identical 24‑file tree, H‑Small matches gpt‑oss's + faithfulness and structure, with **zero** code‑fence or reasoning‑leak defects, and is + **noticeably leaner** (it does not pad the large config file the way gpt‑oss does). +- **Speed: the "Granite is faster" assumption is *false* for H‑Small on this workload/hardware.** + H‑Small activates ~9B params/token vs gpt‑oss's ~3.6B, so its **decode is ~4× slower on CPU** + (5 vs 22 tok/s). Decode dominates summary *generation*, so H‑Small is slower overall. +- **The Mamba win is real but narrow:** H‑Small's **prefill is faster and stays flat at long + context on GPU** (215 tok/s vs gpt‑oss 154→73), and its **KV/state memory is flat** (only 4 of + 40 layers grow a KV cache). Those advantages help *large inputs / long context*, not the + decode‑bound generation of short summaries. +- **On an 8 GB GPU neither model fits** (H‑Small ~17 GB, gpt‑oss ~12 GB), so both are + partial‑offload; that accelerates prefill but **not decode** → little real‑world gain for this task. +- **They cross at ~5,000 input tokens (~15–20 KB).** gpt‑oss prefills far faster on small inputs + (~600 tok/s) then collapses (O(L²)); H‑Small is flat (~205) and overtakes above ~5k. This is the + natural **size‑tier boundary** (§3b) — route small files to gpt‑oss, large files to a hybrid. +- **So:** H‑Small is a **quality‑parity, RAM‑light** option, **not** the fast one. The fast Granite + remains **H‑Tiny (1B active)**. "One model for everything" only holds if you accept gpt‑oss‑class + (or slower) speed in exchange for a single, permissive, long‑context‑cheap model. + +## Setup + +- **Scope:** `config` + `provider` subtree, **24 source files → 35 `.ai.md`** (24 file + 10 package + + 1 project), prompt **v1**, context **16384**. Both models run on the *same current tree* + (the older `ai__gptoss-20b__v1` cell was the stale 12‑file tree and is **not** comparable). +- **Hardware:** AMD Ryzen 7 5800H (8 threads) · NVIDIA RTX 3070 **8 GB** · `net.ladenthin:llama` + 5.0.4 (llama.cpp JNI), CUDA 13.3. +- **Params (from the research pass):** + - H‑Small — **greedy** (`temperature=0`, `topP=1`, `topK=0`, `repeatPenalty=1`), **no thinking + mode** (Granite 4.0 Instruct has none). IBM+Unsloth's official recommendation. + - gpt‑oss — `temperature=0.7`, `topP=1`, `topK=0`, `minP=0.05`, `repeatPenalty=1`, + **`reasoning_effort=low`** (the right setting for summarization; corroborated by COMPARISON.md §11). +- **Outputs:** `outputs/ai__granite4-h-small__v1/` and `outputs/ai__gptoss-20b__v1cur/`. + +## 1. Quality (CPU, identical 24 files) + +| Metric | **H‑Small UD‑Q4_K_XL** | **gpt‑oss‑20B (c16k)** | +|---|---|---| +| files summarized | 24 | 24 | +| avgLn (per file `.ai.md`) | 61.2 | 62.5 | +| KB (all 35 `.ai.md`) | 100 | 99 | +| stray code fences | **0** | **0** | +| reasoning/harmony leak | **0** | **0** | +| enum lines (trivial file) | 42 | 43 | +| **pojo lines (large config)** | **108** | **168** | + +Both emit all 9 sections and the identical (deterministic) `` block. The one real +difference is verbosity on the large `AiGenerationConfig.java`: gpt‑oss elaborates to 168 lines, +H‑Small to 108 — **H‑Small is the more concise at equal faithfulness**. Neither hallucinated the +structural facts (those are prepended deterministically). A tighter (v2‑style) prompt would rein +in both. + +## 2. Speed — CPU (16k context) + +| CPU | prefill tok/s | decode tok/s | source | +|---|---|---|---| +| gpt‑oss‑20B (~3.6B active) | **42** | **22.2** | real 24‑file run (35 gens) | +| Granite H‑Small (~9B active) | 23 | **5.0** | calibrate (near‑window 13k) | + +gpt‑oss is faster on **both** axes on CPU. Decode — the tokens‑out that dominate summary +generation — is **~4.4× faster** on gpt‑oss because it activates far fewer params per token, and +llama.cpp's hybrid/SSM decode kernels are not yet optimized (see ggml‑org/llama.cpp#16454). + +## 3. Speed — GPU partial offload (8 GB, neither model fits) + +| GPU (partial) | layers on GPU | prefill tok/s | decode tok/s | +|---|---|---|---| +| Granite H‑Small | 14 / 40 | **215** (flat) | 5 | +| gpt‑oss‑20B | 16 / 24 | 154 → **73** (degrades with ctx) | ~15–19 | + +- **Prefill:** GPU offload helps H‑Small a lot (23 → 215) and, crucially, its prefill **stays flat** + as context grows, whereas gpt‑oss's attention prefill **degrades** (154 → 73 from ~5k → ~10k + tokens). This is the Mamba long‑context advantage made visible — but it needs the GPU to appear. +- **Decode:** unchanged for H‑Small (still 5 tok/s — the 26 CPU‑resident layers gate every token) + and no better (arguably worse) for gpt‑oss than pure CPU. **Partial offload does not help the + decode‑bound generation step on 8 GB.** + +## 3b. Context scaling — where they cross (GPU prefill sweep) + +Prefill throughput vs input length (GPU partial offload; raw data in +`tools/context-scaling-sweep.tsv`): + +| input tokens | gpt‑oss prefill tok/s | H‑Small prefill tok/s | winner | +|---|---|---|---| +| ~1,000 | ~600 | ~150 | gpt‑oss (4×) | +| ~2,200 | 592 | ~185 | gpt‑oss | +| ~2,600 | 287 | ~198 | gpt‑oss | +| ~4,700 | 226 | 205 | ≈ tie | +| ~5,400 | 154 | 205 | H‑Small | +| ~9,700 | 73 | ~212 | H‑Small (3×) | +| ~13,000 | ~60 | 215 | H‑Small (3.5×) | + +- gpt‑oss starts far **ahead** at small inputs (~600 tok/s) then **collapses** past ~2.5k tokens + (O(L²) attention prefill). H‑Small is slow‑but‑**flat** (~205, Mamba O(L) prefill). +- **Prefill crossover ≈ 5,000 input tokens** (~15–20 KB Java, ~250–400 lines). +- **Total‑time crossover for summarization ≈ the same ~5k tokens:** decode time per summary is + roughly equal despite gpt‑oss's ~4× faster decode *rate*, because `reasoning_effort=low` still + emits ~4× more tokens (analysis channel) — so both spend ~110 s decoding a summary, and prefill + is the tie‑breaker. + +**Cure / sweet spot = the plugin's size‑tiered routing.** Cap gpt‑oss's input and route larger +files to the hybrid: `maxFileSizeBytes ≈ 15000` on the gpt‑oss ``, larger files to +a Granite hybrid (H‑Small for quality, H‑Tiny for speed), and/or `` `mapReduce` to chunk. +The "cure" for gpt‑oss's long‑input collapse is simply **not feeding it long inputs**. (Crossover +value is quant/offload‑dependent on the 8 GB card; the *shape* — gpt‑oss high‑then‑collapsing vs +hybrid flat — is architectural. On CPU both rates are ~10× lower and gpt‑oss stays competitive +further out, but H‑Small's slow absolute speed makes it unattractive there regardless.) + +## 4. Memory / long context (research‑established) + +Only **4 of H‑Small's 40 layers** are attention (grow a KV cache with context); the other 36 are +Mamba‑2 with a **fixed‑size recurrent state**. llama.cpp implements this split +(`llama_memory_hybrid`), so H‑Small holds long context in far less RAM than a transformer whose KV +grows linearly (gpt‑oss mitigates this only via GQA + sliding‑window). This is the durable Granite +advantage for *very large single files* / long windows — orthogonal to the decode‑speed gap above. +(Sources: Mamba‑2 arXiv 2405.21060; IBM Granite 4.0 announcement; llama.cpp #13550/#16454/#19264.) + +Caveat for this plugin: llama.cpp does **not** yet reuse a shared prompt‑prefix KV for recurrent +models (#19264), so the per‑file `cache_prompt` optimization (COMPARISON.md §10) does **not** help +H‑Small — each file recomputes the template prefix. + +## 5. Answering the goal + +**"Can Granite H‑Small be the single model for everything (with a good config)?"** + +- **Yes, on quality and RAM** — it equals gpt‑oss's faithfulness, is leaner in output, permissive + (Apache‑2.0), 128K‑capable, and cheap on memory at long context. +- **No, on speed** — on CPU it is ~2× slower prefill and ~4× slower decode than gpt‑oss; on an 8 GB + GPU that doesn't change (decode stays CPU‑gated). It is **not** the fast option the Mamba + reputation suggests; that role belongs to **H‑Tiny (1B active)**. +- **Where H‑Small would win outright:** a **≥24 GB GPU** (full offload → its flat‑state prefill and + memory dominate at long context), or workloads dominated by **huge inputs** rather than long + generation. + +Net: H‑Small is a strong **precision + long‑context + permissive** single model if you can accept +gpt‑oss‑class (or slower) throughput; it is not a speed upgrade on 8 GB / CPU. + +## Reproduce + +Quality cells (both on the current tree, prompt v1, 16k): + +```bash +mvn install -DskipTests # install the plugin locally first +mvn -o prepare-package -P ai-index-selftest -DskipTests \ + -Dexp.model=EXP-Granite-4.0-H-Small \ + -Dexp.filePrompt=file-body-java -Dexp.pkgPrompt=package-body \ + -Dai.index.output.directory=docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1 +mvn -o prepare-package -P ai-index-selftest -DskipTests \ + -Dexp.model=gpt-oss-20B-c16k -Dai.gpuLayers=0 \ + -Dexp.filePrompt=file-body-java -Dexp.pkgPrompt=package-body \ + -Dai.index.output.directory=docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur +``` + +Speed (exact prefill/decode tok/s) via a standalone calibrate POM parameterized by +`bench.model` / `bench.ctx` / `bench.ngl` / `bench.temp` / `bench.effort`, run with +`mvn ai-index:calibrate -f `; GPU adds `-Dbench.ngl= +-Dllama.classifier=cuda13-windows-x86-64` with the CUDA toolkit on `PATH`. The `EXP-Granite-4.0-H-Small` +`` lives in the `ai-index-selftest` profile in `pom.xml`. + +> Temporary experiment scaffold (not production config), analogous to the `claude2026_06_26_00` +> benchmark cells. diff --git a/docs/ai-index-benchmark/README.md b/docs/ai-index-benchmark/README.md index 398aa29..2033fa9 100644 --- a/docs/ai-index-benchmark/README.md +++ b/docs/ai-index-benchmark/README.md @@ -4,6 +4,8 @@ This directory captures a controlled comparison of **local GGUF models** and **t versions** for the plugin's code-summarization task (`.ai.md` generation), run on CPU. - **[COMPARISON.md](COMPARISON.md)** — scored results, per-model pros/cons, source deep-dive, recommendation. +- **[HSMALL-VS-GPTOSS.md](HSMALL-VS-GPTOSS.md)** — focused Granite 4.0 H‑Small (UD‑Q4_K_XL) vs gpt‑oss‑20B head‑to‑head, **CPU + GPU**, on the current 24‑file tree: quality parity, but H‑Small is slower (9B active) — the Mamba win is memory + long‑context prefill, not decode. +- **[AGENTIC-CPU-BENCH.md](AGENTIC-CPU-BENCH.md)** — agentic **reaction‑time** benchmark (tool‑calling via `llama-server --jinja`): which local models can do native tool_calls, and reaction time vs. context size. h‑tiny (hybrid) beats gpt‑oss at every context and the lead grows; big coders are async‑only on CPU. - **[outputs/](outputs/)** — the raw generated `.ai.md` trees, one directory per cell. ## Bottom line diff --git a/docs/ai-index-benchmark/htiny-vs-gptoss-cpu-context.png b/docs/ai-index-benchmark/htiny-vs-gptoss-cpu-context.png new file mode 100644 index 0000000..a326706 Binary files /dev/null and b/docs/ai-index-benchmark/htiny-vs-gptoss-cpu-context.png differ diff --git a/docs/ai-index-benchmark/htiny-vs-gptoss-cpu-context.png.license b/docs/ai-index-benchmark/htiny-vs-gptoss-cpu-context.png.license new file mode 100644 index 0000000..ac8b117 --- /dev/null +++ b/docs/ai-index-benchmark/htiny-vs-gptoss-cpu-context.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2026 Bernard Ladenthin + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/ai-index-benchmark/htiny-vs-gptoss-cpu-vs-vulkan.png b/docs/ai-index-benchmark/htiny-vs-gptoss-cpu-vs-vulkan.png new file mode 100644 index 0000000..71f9da6 Binary files /dev/null and b/docs/ai-index-benchmark/htiny-vs-gptoss-cpu-vs-vulkan.png differ diff --git a/docs/ai-index-benchmark/htiny-vs-gptoss-cpu-vs-vulkan.png.license b/docs/ai-index-benchmark/htiny-vs-gptoss-cpu-vs-vulkan.png.license new file mode 100644 index 0000000..ac8b117 --- /dev/null +++ b/docs/ai-index-benchmark/htiny-vs-gptoss-cpu-vs-vulkan.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2026 Bernard Ladenthin + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiCalibration.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiCalibration.java.ai.md new file mode 100644 index 0000000..6437903 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiCalibration.java.ai.md @@ -0,0 +1,55 @@ +### AiCalibration.java +- H: 1.0 +- C: C4C9EE6C +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:42:43Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 8; TODO/FIXME: 0; @Override: 0; methods (approx): 7; constructors: 1; field declarations (w/ modifier): 3 + +> Holds per‑model calibration data for AI inference timing and token‑to‑character ratios, used by the estimator to adjust time estimates to the target hardware. + +#### Purpose +- Stores calibration metrics for AI model inference. +- Supplies values to the estimator when both prefill and decode rates are set. + +#### Type +- `class` + `public` + `@SuppressWarnings({"NullAway.Init","initialization.fields.uninitialized"})` + `@ToString` (Lombok) + +#### Input +- Constructor: no arguments. +- Setters: + - `setPrefillTokensPerSecond(double)` + - `setDecodeTokensPerSecond(double)` + - `setCharsPerToken(double)` + +#### Output +- Getters return the stored calibration values. +- `toString()` provides a string representation of all fields. + +#### Core logic +- Simple storage of three double values. +- No additional computation or validation performed. + +#### Public API +- `getPrefillTokensPerSecond() -> double` – read prefill rate +- `setPrefillTokensPerSecond(double) -> void` – set prefill rate +- `getDecodeTokensPerSecond() -> double` – read decode rate +- `setDecodeTokensPerSecond(double) -> void` – set decode rate +- `getCharsPerToken() -> double` – read chars‑per‑token +- `setCharsPerToken(double) -> void` – set chars‑per‑token + +#### Dependencies +- `lombok.ToString` + +#### Exceptions / Errors +- No checked exceptions. +- No null handling; primitive types. + +#### Concurrency +- Not thread‑safe; intended for single‑threaded configuration use. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiCondition.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiCondition.java.ai.md new file mode 100644 index 0000000..54ed2ed --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiCondition.java.ai.md @@ -0,0 +1,65 @@ +### AiCondition.java +- H: 1.0 +- C: 15F73517 +- D: 2026-06-29T19:51:15Z +- T: 2026-07-02T22:44:06Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 20; TODO/FIXME: 0; @Override: 0; methods (approx): 10; constructors: 1; field declarations (w/ modifier): 0 + +> A recursive boolean tree for matching files in a Maven routing rule. + +#### Purpose +- Represents a composable file‑matching condition. +- Validated by `AiConditionEvaluator#validate`. + +#### Type +- Class, `public`, annotated `@ToString`. +- Fields: `AiConditionGroup and, or, AiCondition not; List extensions; AiRangeCondition size, lines; String modifiedAfter, modifiedBefore, pathGlob`. + +#### Input +- Constructor: no‑arg. +- Setters receive `AiConditionGroup`, `Collection`, `AiRangeCondition`, or `String` values. +- Fields store configuration for evaluation. + +#### Output +- Getters return stored values or `null`. +- Setters clone collections to prevent external mutation. + +#### Core logic +- No internal logic; serves as a mutable JavaBean for configuration. + +#### Public API +- `getAnd() -> AiConditionGroup` – retrieve AND group. +- `setAnd(AiConditionGroup) -> void` – set AND group. +- `getOr() -> AiConditionGroup` – retrieve OR group. +- `setOr(AiConditionGroup) -> void` – set OR group. +- `getNot() -> AiCondition` – retrieve NOT child. +- `setNot(AiCondition) -> void` – set NOT child. +- `getExtensions() -> List` – retrieve extensions list. +- `setExtensions(Collection) -> void` – set extensions. +- `getSize() -> AiRangeCondition` – retrieve size range. +- `setSize(AiRangeCondition) -> void` – set size range. +- `getLines() -> AiRangeCondition` – retrieve lines range. +- `setLines(AiRangeCondition) -> void` – set lines range. +- `getModifiedAfter() -> String` – retrieve modified‑after timestamp. +- `setModifiedAfter(String) -> void` – set modified‑after timestamp. +- `getModifiedBefore() -> String` – retrieve modified‑before timestamp. +- `setModifiedBefore(String) -> void` – set modified‑before timestamp. +- `getPathGlob() -> String` – retrieve path glob. +- `setPathGlob(String) -> void` – set path glob. + +#### Dependencies +- `java.util.ArrayList`, `java.util.Collection`, `java.util.List`. +- `lombok.ToString`. +- `org.jspecify.annotations.Nullable`. +- `net.ladenthin.maven.llamacpp.aiindex.config.AiConditionGroup`. +- `net.ladenthin.maven.llamacpp.aiindex.config.AiRangeCondition`. + +#### Exceptions / Errors +- No exceptions thrown; setters accept `null`. + +#### Concurrency +- Not thread‑safe; mutable state. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiConditionEvaluator.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiConditionEvaluator.java.ai.md new file mode 100644 index 0000000..7a279de --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiConditionEvaluator.java.ai.md @@ -0,0 +1,55 @@ +### AiConditionEvaluator.java +- H: 1.0 +- C: 66F4DB55 +- D: 2026-06-29T19:51:15Z +- T: 2026-07-02T22:45:43Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 5; TODO/FIXME: 0; @Override: 0; methods (approx): 10; constructors: 1; field declarations (w/ modifier): 1 + +> Evaluates and validates file‑matching conditions for an indexer, supporting logical combinations, size, line count, modification dates, and glob patterns. + +#### Purpose +- Validates `AiCondition` trees for correctness. +- Matches a file context against a condition tree. +- Determines if line counting is required. + +#### Type +final class `AiConditionEvaluator` (no generics). + +#### Input +- `AiCondition` trees (nodes with `and`, `or`, `not`, `extensions`, `size`, `lines`, `modifiedAfter`, `modifiedBefore`, `pathGlob`). +- `AiFileContext` (file facts: name, size, lines, last modified, relative path). + +#### Output +- Boolean match results. +- Exceptions on validation or parsing errors. + +#### Core logic +- `matches`: recursively evaluates `and`, `or`, `not`, and leaf conditions. +- `validate`: ensures exactly one branch/leaf per node, checks bounds, parses dates, verifies non‑blank glob. +- `usesLines`: recursive search for any `lines` condition to avoid unnecessary file reads. +- Helper methods: `validateGroup`, `branchCount`, `matchesExtension`, `globMatches`, `parseEpochMilli`. + +#### Public API +- `matches(AiCondition, AiFileContext) -> boolean` – evaluate condition against file. +- `validate(AiCondition) -> void` – throw if misconfigured. +- `usesLines(AiCondition) -> boolean` – detect line‑count requirement. + +#### Dependencies +- `java.time.Instant`, `java.time.format.DateTimeParseException`. +- `java.util.Collections`, `java.util.List`. +- `net.ladenthin.maven.llamacpp.aiindex.support.AiSourceExcludeFilter`. +- `org.jspecify.annotations.Nullable`. + +#### Exceptions / Errors +- `IllegalStateException` if node has no branch/leaf. +- `IllegalArgumentException` for validation failures or invalid ISO‑8601 dates. + +#### Concurrency +- Stateless; thread‑safe for concurrent use. + +#### Fields +1. `private static final String ERROR_ONE_BRANCH` – error message template. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiConditionGroup.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiConditionGroup.java.ai.md new file mode 100644 index 0000000..6945d49 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiConditionGroup.java.ai.md @@ -0,0 +1,52 @@ +### AiConditionGroup.java +- H: 1.0 +- C: B4457D08 +- D: 2026-06-29T19:51:15Z +- T: 2026-07-02T22:47:24Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 4; TODO/FIXME: 0; @Override: 0; methods (approx): 2; constructors: 1; field declarations (w/ modifier): 0 + +> Holds a list of child conditions for an / combinator in the AI index configuration. + +#### Purpose +- Represents the body of an or element in the AI index configuration. + +#### Type +- Class AiConditionGroup + - Modifiers: public, final (implicit) + - Annotations: @ToString, @SuppressWarnings({"NullAway.Init","initialization.fields.uninitialized"}) + - Extends: none + +#### Input +- `Collection conditions` passed to `setConditions` (nullable). +- No constructor parameters; default constructor does nothing. + +#### Output +- `List getConditions()` returns the stored list or `null`. +- `setConditions` assigns a defensive copy of the provided collection or `null`. + +#### Core logic +- Defensive copy of input collection into an `ArrayList` to prevent external mutation. +- `null` handling: if input is `null`, internal list is set to `null`. +- Simple getter returns the internal list reference (may be `null`). + +#### Public API +- `AiConditionGroup()` → constructs an empty group. +- `List getConditions()` → returns child conditions or `null`. +- `void setConditions(Collection conditions)` → sets child conditions defensively. + +#### Dependencies +- `java.util.ArrayList`, `java.util.Collection`, `java.util.List` +- `lombok.ToString` +- `org.jspecify.annotations.Nullable` +- `net.ladenthin.maven.llamacpp.aiindex.config.AiCondition` + +#### Exceptions / Errors +- No checked exceptions thrown. +- Defensive copy may throw `NullPointerException` if `conditions` is non‑null but contains `null` elements. + +#### Concurrency +- Not thread‑safe; mutable state is not synchronized. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactCounter.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactCounter.java.ai.md new file mode 100644 index 0000000..3979734 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactCounter.java.ai.md @@ -0,0 +1,51 @@ +### AiFactCounter.java +- H: 1.0 +- C: 2BFA8358 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:48:10Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 6; TODO/FIXME: 0; @Override: 0; methods (approx): 5; constructors: 1; field declarations (w/ modifier): 2 + +> Counts non‑overlapping regex matches for a given label in source files. + +#### Purpose +- Stores a label and a Java regex used to count occurrences in source. +- Provides mutable JavaBean for Maven plugin configuration. + +#### Type +- Class, public, mutable. No interfaces or generics. +- Annotated `@ToString` (Lombok). Suppresses uninitialized field warnings. + +#### Input +- Constructor: no parameters. +- `setLabel(String)` – sets human‑readable label. +- `setPattern(String)` – sets regex pattern. +- Fields `label`, `pattern` are read by getters. + +#### Output +- `getLabel()` returns stored label. +- `getPattern()` returns stored regex. +- Lombok `toString()` outputs `label` and `pattern`. + +#### Core logic +- Simple field assignments in setters. +- Getters return current field values. + +#### Public API +- `AiFactCounter()` – instantiate counter. +- `getLabel() -> String` – retrieve label. +- `setLabel(String)` – set label. +- `getPattern() -> String` – retrieve pattern. +- `setPattern(String)` – set pattern. + +#### Dependencies +- `lombok.ToString` + +#### Exceptions / Errors +- No explicit exceptions thrown or caught. + +#### Concurrency +- No synchronization; class is not thread‑safe. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinition.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinition.java.ai.md new file mode 100644 index 0000000..67d3449 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinition.java.ai.md @@ -0,0 +1,54 @@ +### AiFactDefinition.java +- H: 1.0 +- C: F74A4B9F +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:48:51Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 6; TODO/FIXME: 0; @Override: 0; methods (approx): 4; constructors: 1; field declarations (w/ modifier): 1 + +> Defines a reusable collection of AI fact counters referenced by routing rules in a Maven plugin configuration. + +#### Purpose +- Represents a named group of AiFactCounter instances. +- Configurable via Maven plugin framework. + +#### Type +- Class, public, mutable JavaBean. +- Extends java.lang.Object. +- Annotations: @SuppressWarnings({"NullAway.Init","initialization.fields.uninitialized"}), @ToString. + +#### Input +- Constructor: no parameters. +- Methods: setKey(String), setFacts(List). +- Fields: key (String), facts (List). + +#### Output +- Methods: getKey() -> String, getFacts() -> List (nullable). +- toString() generated by Lombok. + +#### Core logic +- Stores a lookup key and optional list of AiFactCounter. +- Provides getters/setters for Maven reflection population. +- No additional processing or validation. + +#### Public API +- `AiFactDefinition()` – no‑op constructor. +- `String getKey()` – returns lookup key. +- `void setKey(String)` – sets lookup key. +- `List getFacts()` – returns fact counters. +- `void setFacts(List)` – sets fact counters. + +#### Dependencies +- java.util.List +- lombok.ToString +- org.jspecify.annotations.Nullable +- net.ladenthin.maven.llamacpp.aiindex.config.AiFactCounter + +#### Exceptions / Errors +- No exceptions thrown; setters accept null for facts. + +#### Concurrency +- No synchronization; mutable fields. Not thread‑safe. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinitionSupport.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinitionSupport.java.ai.md new file mode 100644 index 0000000..8e8e2ea --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinitionSupport.java.ai.md @@ -0,0 +1,57 @@ +### AiFactDefinitionSupport.java +- H: 1.0 +- C: D98D3BA4 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:49:36Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 4; TODO/FIXME: 0; @Override: 0; methods (approx): 3; constructors: 1; field declarations (w/ modifier): 3 + +> Resolves shared fact counter groups and applies them to routing rules, ensuring each rule references the correct counters. + +#### Purpose +- Provides lookup of fact counter groups by key. +- Applies referenced groups to rules, replacing inline facts. + +#### Type +- Final class `AiFactDefinitionSupport` (no generics, implements nothing). + +#### Input +- Constructor receives `List` (may be null/empty). +- `resolveFactsKeys` consumes `Iterable` (may contain null entries). + +#### Output +- `facts(String)` returns `List` (never null). +- `resolveFactsKeys` mutates each rule’s `facts` field via `setFacts`. + +#### Core logic +- Constructor: + 1. If `definitions` null → empty map. + 2. For each definition: + - Enforce non‑null key. + - Map key to its `facts` list (or empty list if null). +- `facts(key)`: + - Retrieve list; throw `IllegalArgumentException` if key missing. +- `resolveFactsKeys(rules)`: + - Iterate rules; skip nulls. + - If rule has `factsKey`, replace its facts with the group from `facts(factsKey)`. + +#### Public API +- `AiFactDefinitionSupport(List) -> void` (constructor) +- `facts(String) -> List` (lookup counters) +- `resolveFactsKeys(Iterable) -> void` (apply group to rules) + +#### Dependencies +- `java.util.*` +- `lombok.ToString` +- `net.ladenthin.maven.llamacpp.aiindex.support.Java8CompatibilityHelper` +- `org.jspecify.annotations.Nullable` + +#### Exceptions / Errors +- `NullPointerException` if any definition’s key is null. +- `IllegalArgumentException` if `facts(String)` key missing or rule’s `factsKey` unresolved. + +#### Concurrency +- No explicit synchronization; instances are immutable after construction except for the mutable map used only during construction. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactExtractor.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactExtractor.java.ai.md new file mode 100644 index 0000000..4b4096d --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactExtractor.java.ai.md @@ -0,0 +1,56 @@ +### AiFactExtractor.java +- H: 1.0 +- C: C5F253BD +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:50:43Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 7; TODO/FIXME: 0; @Override: 0; methods (approx): 4; constructors: 1; field declarations (w/ modifier): 4 + +> Generates a deterministic “facts” block with exact counts of regex matches for configured fact counters, to prepend to AI summaries. + +#### Purpose +- Compute exact counts of regex matches in source code. +- Produce a formatted facts header for AI output. + +#### Type +Class, final, public, no inheritance. + +#### Input +- `List counters` (nullable, may be empty). +- `String source` (full source text). +- `AiFactCounter` fields: `label`, `pattern`. + +#### Output +- `String` facts block (header + `label: count` entries + blank line) or empty string. +- Side effect: none (pure calculation). + +#### Core logic +- If counters null/empty → return empty. +- Iterate counters: + - Skip null counter or missing label/pattern. + - Append `label: count` to `StringBuilder`, separating entries with `ENTRY_SEPARATOR`. + - `countMatches(pattern, source)` counts non‑overlapping regex matches. +- If no valid entries → return empty. +- Prepend `FACTS_HEADER` and append `FACTS_SUFFIX`. + +#### Public API +- `factsBlock(List counters, String source) -> String` – build facts block. +- `validate(List counters) -> void` – ensure counters have labels, patterns, and compile. + +#### Dependencies +- `java.util.List` +- `java.util.regex.Matcher` +- `java.util.regex.Pattern` +- `java.util.regex.PatternSyntaxException` +- `org.jspecify.annotations.Nullable` +- `net.ladenthin.maven.llamacpp.aiindex.config.AiFactCounter` + +#### Exceptions / Errors +- `IllegalArgumentException` from `validate` if counter missing label/pattern or regex fails to compile. +- `PatternSyntaxException` caught and rethrown as `IllegalArgumentException`. + +#### Concurrency +- Thread‑safe: all methods are static and stateless; no shared mutable state. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationConfig.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationConfig.java.ai.md new file mode 100644 index 0000000..25a18f3 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationConfig.java.ai.md @@ -0,0 +1,75 @@ +### AiFieldGenerationConfig.java +- H: 1.0 +- C: 6D5D78F0 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:51:49Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 25; TODO/FIXME: 0; @Override: 0; methods (approx): 19; constructors: 1; field declarations (w/ modifier): 6 + +> A mutable configuration bean that defines a routing rule for AI‑based field generation, including file selection, priority, action, oversize handling, and optional deterministic fact extraction. + +#### Purpose +- Holds a single routing rule for the `generate` goal. +- Determines file matching, action (route, skip, fallback), and strategy for oversized files. + +#### Type +- `class` (mutable JavaBean). +- Modifiers: none. +- Annotations: `@ToString`, `@SuppressWarnings({"NullAway.Init","initialization.fields.uninitialized"})`. + +#### Input +- Constructor: no arguments. +- Fields set via setters: `id`, `promptKey`, `aiDefinitionKey`, `condition`, `priority`, `fallback`, `skip`, `onOversize`, `maxChunks`, `facts`, `factsKey`. +- Dependencies: `AiCondition`, `AiOversizeStrategy`, `AiFactCounter`, `AiFactDefinitionSupport`. + +#### Output +- Getter methods expose the configured values. +- `getOversizeStrategy()` parses `onOversize` into an `AiOversizeStrategy` enum. +- No external resources written. + +#### Core logic +- `getOversizeStrategy()` delegates to `AiOversizeStrategy.fromConfig(onOversize)`. +- All other methods are simple property accessors. + +#### Public API +- `String getId() -> return optional rule id` +- `void setId(String) -> set rule id` +- `String getPromptKey() -> return prompt key` +- `void setPromptKey(String) -> set prompt key` +- `String getAiDefinitionKey() -> return model key` +- `void setAiDefinitionKey(String) -> set model key` +- `AiCondition getCondition() -> return file condition` +- `void setCondition(AiCondition) -> set file condition` +- `int getPriority() -> return selection priority` +- `void setPriority(int) -> set priority` +- `boolean isFallback() -> check fallback flag` +- `void setFallback(boolean) -> set fallback` +- `boolean isSkip() -> check skip flag` +- `void setSkip(boolean) -> set skip` +- `String getOnOversize() -> return oversize token` +- `void setOnOversize(String) -> set oversize token` +- `AiOversizeStrategy getOversizeStrategy() -> parse oversize strategy` +- `int getMaxChunks() -> return chunk cap` +- `void setMaxChunks(int) -> set chunk cap` +- `List getFacts() -> return fact counters` +- `void setFacts(List) -> set fact counters` +- `String getFactsKey() -> return facts key` +- `void setFactsKey(String) -> set facts key` + +#### Dependencies +- `java.util.List` +- `lombok.ToString` +- `org.jspecify.annotations.Nullable` +- `net.ladenthin.maven.llamacpp.aiindex.config.AiCondition` +- `net.ladenthin.maven.llamacpp.aiindex.config.AiOversizeStrategy` +- `net.ladenthin.maven.llamacpp.aiindex.fact.AiFactCounter` +- `net.ladenthin.maven.llamacpp.aiindex.fact.AiFactDefinitionSupport` + +#### Exceptions / Errors +- `getOversizeStrategy()` throws `IllegalArgumentException` if `onOversize` is non‑blank and does not match a strategy. + +#### Concurrency +- No thread‑safety guarantees; intended for single‑threaded configuration building. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationSelector.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationSelector.java.ai.md new file mode 100644 index 0000000..9cff266 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationSelector.java.ai.md @@ -0,0 +1,70 @@ +### AiFieldGenerationSelector.java +- H: 1.0 +- C: 4A116EC6 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:54:18Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 4; TODO/FIXME: 0; @Override: 0; methods (approx): 3; constructors: 1; field declarations (w/ modifier): 1 + +> Determines which AI field‑generation rule applies to a file and validates rule sets. + +#### Purpose +- Chooses a matching `AiFieldGenerationConfig` for a file. +- Validates rule configurations for correctness. + +#### Type +- Final class `AiFieldGenerationSelector` (no inheritance). +- Field: `private final AiConditionEvaluator conditionEvaluator`. + +#### Input +- `Iterable configs` (declared order, may contain `null`). +- `AiFileContext context` (file facts). +- `AiFieldGenerationConfig` objects provide `isFallback()`, `isSkip()`, `getCondition()`, `getPriority()`, `getOversizeStrategy()`, `getFacts()`, `getPromptKey()`, `getAiDefinitionKey()`. + +#### Output +- `select` returns an `AiFieldGenerationConfig` (or `null`). +- `validate` throws `IllegalArgumentException` on misconfiguration. + +#### Core logic +- **select** + - Iterate configs in declaration order. + - Skip `null`. + - Store first fallback rule. + - For non‑fallback rules: if condition matches (via `AiConditionEvaluator`) and priority higher than current best, update best. + - Return best if found; otherwise fallback; otherwise `null`. +- **validate** + - Count fallbacks; enforce at most one. + - For each rule: + - `getOversizeStrategy()` and `AiFactExtractor.validate()` to trigger early failures. + - If fallback: must not be skip, must have no condition, must have prompt & AI definition keys. + - If non‑fallback: must have a condition; validate the condition; if not skip, require prompt & AI definition keys. + - Throw detailed `IllegalArgumentException` on any violation. + +#### Public API +- `AiFieldGenerationSelector() -> no-op` – constructs selector. +- `select(Iterable, AiFileContext) -> AiFieldGenerationConfig` – chooses rule. +- `validate(Iterable) -> void` – validates rules. + +#### Dependencies +- `AiConditionEvaluator` +- `AiFieldGenerationConfig` +- `AiFileContext` +- `AiCondition` +- `AiFactExtractor` +- Lombok `@ToString` +- `org.jspecify.annotations.Nullable` + +#### Exceptions / Errors +- `IllegalArgumentException` thrown by `validate` for: + - Multiple fallbacks. + - Fallback being a skip or having a condition. + - Non‑fallback lacking a condition. + - Missing prompt or AI definition keys. + - Invalid oversize strategy or facts extraction. + +#### Concurrency +- No explicit synchronization; immutable after construction. +- Thread‑safe if `AiConditionEvaluator` and `AiFieldGenerationConfig` are thread‑safe. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFileContext.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFileContext.java.ai.md new file mode 100644 index 0000000..312ecd1 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFileContext.java.ai.md @@ -0,0 +1,46 @@ +### AiFileContext.java +- H: 1.0 +- C: ADE292A5 +- D: 2026-06-29T19:51:15Z +- T: 2026-07-02T22:55:42Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 7; TODO/FIXME: 0; @Override: 0; methods (approx): 6; constructors: 1; field declarations (w/ modifier): 5 + +> Immutable snapshot of a file’s metadata for AI condition evaluation. + +#### Purpose +- Holds file facts for AI condition checks. +- Provides read‑only access to metadata. + +#### Type +- `final class` `AiFileContext` +- Lombok `@ToString` annotation. + +#### Input +- Constructor parameters: `fileName`, `relativePath`, `sizeBytes`, `lineCount`, `lastModifiedEpochMilli`. + +#### Output +- Getter methods exposing each field. + +#### Core logic +- Stores constructor arguments in final fields. +- Provides simple accessor methods for each field. + +#### Public API +- `fileName() -> String` – returns file name. +- `relativePath() -> String` – returns base‑relative path. +- `sizeBytes() -> long` – returns size in bytes. +- `lineCount() -> int` – returns line count. +- `lastModifiedEpochMilli() -> long` – returns last‑modified epoch milliseconds. + +#### Dependencies +- `lombok.ToString`. + +#### Exceptions / Errors +- None. + +#### Concurrency +- Immutable; thread‑safe. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiGenerationConfig.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiGenerationConfig.java.ai.md new file mode 100644 index 0000000..85912f8 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiGenerationConfig.java.ai.md @@ -0,0 +1,168 @@ +### AiGenerationConfig.java +- H: 1.0 +- C: 2B41382A +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:56:18Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 86; TODO/FIXME: 0; @Override: 0; methods (approx): 57; constructors: 1; field declarations (w/ modifier): 54 + +> A mutable JavaBean holding all parameters for a single AI generation step (model, sampling, caching, GPU, DRY, etc.). + +#### Purpose +- Stores configuration for an AI generation request. +- Supplies values to provider implementations. + +#### Type +- Class `AiGenerationConfig` (mutable JavaBean). +- `@ToString` generated. +- No inheritance. + +#### Input +- Constructor: no arguments, defaults initialized. +- Setter methods for every field. +- `setDevices(String)` accepts `null` to reset to default. +- `setDrySequenceBreakers(List)` and `setStopStrings(List)` accept `null` to clear. + +#### Output +- Getter methods expose field values. +- `getDrySequenceBreakers()` and `getStopStrings()` return unmodifiable lists. + +#### Core logic +- Simple state storage; no algorithmic processing. +- Constants provide default values. +- `setDevices` normalizes `null` to the empty default. +- `setDrySequenceBreakers` and `setStopStrings` replace `null` with empty lists. + +#### Public API +- `getModelPath() -> String` + Retrieves GGUF model file path. +- `setModelPath(String)` + Sets GGUF model file path. +- `getContextSize() -> int` + Retrieves context window size. +- `setContextSize(int)` + Sets context window size. +- `getMaxOutputTokens() -> int` + Retrieves maximum output tokens. +- `setMaxOutputTokens(int)` + Sets maximum output tokens. +- `getTemperature() -> float` + Retrieves sampling temperature. +- `setTemperature(float)` + Sets sampling temperature. +- `getThreads() -> int` + Retrieves number of CPU threads. +- `setThreads(int)` + Sets number of CPU threads. +- `getCharsPerToken() -> int` + Retrieves characters‑per‑token ratio. +- `setCharsPerToken(int)` + Sets characters‑per‑token ratio. +- `getMaxInputChars() -> int` + Retrieves maximum input characters. +- `setMaxInputChars(int)` + Sets maximum input characters. +- `isWarnOnTrim() -> boolean` + Checks if trim warnings enabled. +- `setWarnOnTrim(boolean)` + Enables/disables trim warnings. +- `getTopP() -> float` + Retrieves nucleus‑sampling threshold. +- `setTopP(float)` + Sets nucleus‑sampling threshold. +- `getTopK() -> int` + Retrieves top‑k limit. +- `setTopK(int)` + Sets top‑k limit. +- `getRepeatPenalty() -> float` + Retrieves repetition penalty. +- `setRepeatPenalty(float)` + Sets repetition penalty. +- `getMinP() -> float` + Retrieves min‑p threshold. +- `setMinP(float)` + Sets min‑p threshold. +- `getTopNSigma() -> float` + Retrieves top‑n‑sigma threshold. +- `setTopNSigma(float)` + Sets top‑n‑sigma threshold. +- `isChatTemplateEnableThinking() -> boolean` + Checks chat‑template thinking mode. +- `setChatTemplateEnableThinking(boolean)` + Enables/disables chat‑template thinking. +- `isCachePrompt() -> boolean` + Checks if prompt prefix KV reuse enabled. +- `setCachePrompt(boolean)` + Enables/disables prompt caching. +- `isSwaFull() -> boolean` + Checks if full‑size SWA KV kept. +- `setSwaFull(boolean)` + Enables/disables full SWA KV. +- `getCacheReuse() -> int` + Retrieves cache‑reuse chunk size. +- `setCacheReuse(int)` + Sets cache‑reuse chunk size. +- `getGpuLayers() -> int` + Retrieves GPU layer offload count. +- `setGpuLayers(int)` + Sets GPU layer offload count. +- `getMainGpu() -> int` + Retrieves primary GPU index. +- `setMainGpu(int)` + Sets primary GPU index. +- `getDevices() -> String` + Retrieves device list. +- `setDevices(String)` + Sets device list (null → default). +- `getReasoningEffort() -> String` + Retrieves reasoning‑effort level. +- `setReasoningEffort(String)` + Sets reasoning‑effort level. +- `getReasoningBudgetTokens() -> int` + Retrieves reasoning‑budget token limit. +- `setReasoningBudgetTokens(int)` + Sets reasoning‑budget token limit. +- `getDryMultiplier() -> float` + Retrieves DRY multiplier. +- `setDryMultiplier(float)` + Sets DRY multiplier. +- `getDryBase() -> float` + Retrieves DRY base. +- `setDryBase(float)` + Sets DRY base. +- `getDryAllowedLength() -> int` + Retrieves DRY allowed length. +- `setDryAllowedLength(int)` + Sets DRY allowed length. +- `getDryPenaltyLastN() -> int` + Retrieves DRY penalty look‑back. +- `setDryPenaltyLastN(int)` + Sets DRY penalty look‑back. +- `getDrySequenceBreakers() -> List` + Unmodifiable list of DRY sequence breakers. +- `setDrySequenceBreakers(List)` + Replaces DRY sequence breakers (null → empty). +- `getStopStrings() -> List` + Unmodifiable list of stop strings. +- `setStopStrings(List)` + Replaces stop strings (null → empty). +- `getCalibration() -> AiCalibration` + Retrieves calibration (may be null). +- `setCalibration(AiCalibration)` + Sets calibration. + +#### Dependencies +- `java.util.ArrayList`, `java.util.Collections`, `java.util.List`. +- `lombok.ToString`. +- `org.jspecify.annotations.Nullable`. +- `net.ladenthin.maven.llamacpp.aiindex.config.AiCalibration`. + +#### Exceptions / Errors +- No checked exceptions thrown. +- Null handling: setters accept `null` for lists and devices; they reset to defaults. + +#### Concurrency +- No synchronization; class is not thread‑safe. Instances intended for single‑thread use or external coordination. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiGenerationKind.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiGenerationKind.java.ai.md new file mode 100644 index 0000000..14719d3 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiGenerationKind.java.ai.md @@ -0,0 +1,43 @@ +### AiGenerationKind.java +- H: 1.0 +- C: 502093E2 +- D: 2026-06-25T05:31:58Z +- T: 2026-07-02T23:02:58Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 1; TODO/FIXME: 0; @Override: 0; methods (approx): 0; constructors: 0; field declarations (w/ modifier): 0 + +> Enumerates the scope of an AI generation step—either per-file or per-package. + +#### Purpose +- Defines the granularity of AI generation. + +#### Type +- `enum` AiGenerationKind + - No modifiers + - No supertype or interfaces + +#### Input +- None + +#### Output +- None + +#### Core logic +- Two constants: + - `FILE_SUMMARY` – generation for a single source file. + - `PACKAGE_SUMMARY` – generation for a package aggregate. + +#### Public API +- None + +#### Dependencies +- None + +#### Exceptions / Errors +- None + +#### Concurrency +- None diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinition.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinition.java.ai.md new file mode 100644 index 0000000..576b07f --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinition.java.ai.md @@ -0,0 +1,109 @@ +### AiModelDefinition.java +- H: 1.0 +- C: 7AF67E46 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T23:03:15Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 60; TODO/FIXME: 0; @Override: 0; methods (approx): 56; constructors: 1; field declarations (w/ modifier): 26 + +> Holds a unique key and full set of parameters for a GGUF AI model, used by the Maven plugin to configure inference. + +#### Purpose +- Stores all AI model configuration values for Maven plugin use. +- Enables reuse of a single model definition across multiple generation goals. + +#### Type +- Class, mutable JavaBean, `@ToString`, `@SuppressWarnings({"NullAway.Init","initialization.fields.uninitialized"})`. + +#### Input +- Constructor: no parameters. +- Setters: 31 public setters (`setKey`, `setModelPath`, …, `setCalibration`). +- Direct field access via setters; no external dependencies. + +#### Output +- Getters: 31 public getters (`getKey`, `getModelPath`, …, `getCalibration`). +- Mutated state: all 31 fields. +- No external side effects. + +#### Core logic +- Default field values are taken from `AiGenerationConfig` constants. +- `setDevices` normalizes `null` to the default empty string. +- Collection setters (`setDrySequenceBreakers`, `setStopStrings`) copy input into a mutable list. +- Collection getters return an unmodifiable view or `null`. + +#### Public API +- `AiModelDefinition()` → constructs with defaults. +- `String getKey()` → unique lookup key. +- `void setKey(String)` → assign key. +- `String getModelPath()` → path to GGUF file. +- `void setModelPath(String)` → assign model path. +- `int getContextSize()` → context window size. +- `void setContextSize(int)` → set context size. +- `int getMaxOutputTokens()` → max output tokens. +- `void setMaxOutputTokens(int)` → set max output tokens. +- `float getTemperature()` → sampling temperature. +- `void setTemperature(float)` → set temperature. +- `int getThreads()` → CPU threads. +- `void setThreads(int)` → set threads. +- `int getCharsPerToken()` → chars-per-token ratio. +- `void setCharsPerToken(int)` → set ratio. +- `boolean isWarnOnTrim()` → trim warning flag. +- `void setWarnOnTrim(boolean)` → set flag. +- `float getTopP()` → nucleus-sampling threshold. +- `void setTopP(float)` → set threshold. +- `int getTopK()` → top‑k limit. +- `void setTopK(int)` → set limit. +- `float getRepeatPenalty()` → repetition penalty. +- `void setRepeatPenalty(float)` → set penalty. +- `float getMinP()` → min‑p threshold. +- `void setMinP(float)` → set threshold. +- `float getTopNSigma()` → top‑n‑sigma threshold. +- `void setTopNSigma(float)` → set threshold. +- `boolean isChatTemplateEnableThinking()` → chat‑template thinking flag. +- `void setChatTemplateEnableThinking(boolean)` → set flag. +- `boolean isCachePrompt()` → llama.cpp prompt caching flag. +- `void setCachePrompt(boolean)` → set flag. +- `boolean isSwaFull()` → full‑size SWA KV cache flag. +- `void setSwaFull(boolean)` → set flag. +- `int getCacheReuse()` → KV prefix‑reuse chunk size. +- `void setCacheReuse(int)` → set chunk size. +- `int getGpuLayers()` → GPU layer offload count. +- `void setGpuLayers(int)` → set offload count. +- `int getMainGpu()` → primary GPU index. +- `void setMainGpu(int)` → set index. +- `String getDevices()` → comma‑separated device list. +- `void setDevices(String)` → set list or reset to default. +- `String getReasoningEffort()` → gpt‑oss reasoning‑effort level. +- `void setReasoningEffort(String)` → set level. +- `int getReasoningBudgetTokens()` → reasoning token budget. +- `void setReasoningBudgetTokens(int)` → set budget. +- `float getDryMultiplier()` → DRY multiplier. +- `void setDryMultiplier(float)` → set multiplier. +- `float getDryBase()` → DRY base. +- `void setDryBase(float)` → set base. +- `int getDryAllowedLength()` → DRY allowed length. +- `void setDryAllowedLength(int)` → set length. +- `int getDryPenaltyLastN()` → DRY penalty look‑back window. +- `void setDryPenaltyLastN(int)` → set window. +- `List getDrySequenceBreakers()` → DRY sequence breakers. +- `void setDrySequenceBreakers(Collection)` → set breakers. +- `List getStopStrings()` → stop strings. +- `void setStopStrings(Collection)` → set stop strings. +- `AiCalibration getCalibration()` → per‑machine timing calibration. +- `void setCalibration(AiCalibration)` → set calibration. + +#### Dependencies +- `net.ladenthin.maven.llamacpp.aiindex.config.AiGenerationConfig` +- `net.ladenthin.maven.llamacpp.aiindex.config.AiCalibration` +- `java.util.*` +- `lombok.ToString` +- `org.jspecify.annotations.Nullable` + +#### Exceptions / Errors +- No explicit exceptions thrown; setters assume valid input. + +#### Concurrency +- No synchronization; intended for single‑threaded configuration use. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinitionSupport.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinitionSupport.java.ai.md new file mode 100644 index 0000000..a913e98 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinitionSupport.java.ai.md @@ -0,0 +1,55 @@ +### AiModelDefinitionSupport.java +- H: 1.0 +- C: 05A1DA33 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T23:07:53Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 3; TODO/FIXME: 0; @Override: 0; methods (approx): 3; constructors: 1; field declarations (w/ modifier): 3 + +> Builds a lookup table that maps AI model keys to ready‑to‑use generation configurations. + +#### Purpose +- Provides fast retrieval of `AiGenerationConfig` by model key. +- Validates configuration entries at construction time. + +#### Type +- `final class AiModelDefinitionSupport` +- Lombok `@ToString` + +#### Input +- `List definitions` (may be null or empty) +- Each `AiModelDefinition` must have a non‑null `key` and other fields. + +#### Output +- `AiGenerationConfig` instances stored in an internal `Map configs`. + +#### Core logic +- If `definitions` is null, create empty map. +- Presize map using `Java8CompatibilityHelper.hashMapCapacityFor(count)`. +- Iterate over `definitions`: + - Validate non‑null `definition.getKey()`; throw `NullPointerException` with list index if null. + - Convert `AiModelDefinition` to `AiGenerationConfig` via `toConfig` and put into map keyed by `definition.getKey()`. +- `getConfig(key)`: + - Retrieve from map; if absent, throw `IllegalArgumentException` with missing key message. +- `toConfig(definition)`: + - Instantiate `AiGenerationConfig`. + - Copy all fields from `definition` to the config. + +#### Public API +- `AiGenerationConfig getConfig(String key) -> retrieves config for key` +- `AiModelDefinitionSupport(List definitions) -> builds lookup table` + +#### Dependencies +- `java.util.*` +- `lombok.ToString` +- `net.ladenthin.maven.llamacpp.aiindex.support.Java8CompatibilityHelper` + +#### Exceptions / Errors +- `NullPointerException` if any definition has a null key (includes index and entry in message). +- `IllegalArgumentException` if `getConfig` is called with an unregistered key. + +#### Concurrency +- Immutable after construction; safe for concurrent reads. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiOversizeStrategy.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiOversizeStrategy.java.ai.md new file mode 100644 index 0000000..85db5e1 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiOversizeStrategy.java.ai.md @@ -0,0 +1,46 @@ +### AiOversizeStrategy.java +- H: 1.0 +- C: C8604282 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T23:09:06Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 4; TODO/FIXME: 0; @Override: 0; methods (approx): 2; constructors: 1; field declarations (w/ modifier): 2 + +> Determines how oversized source files are handled during AI routing. + +#### Purpose +- Configures handling of source files larger than a model’s context window. +- Provides strategies for automatic or manual processing of oversized files. + +#### Type +- `enum` `AiOversizeStrategy` (public, final). +- Extends `java.lang.Enum`. +- No interfaces or generics. + +#### Input +- `AiOversizeStrategy.fromConfig(String)` receives a configuration string (nullable). +- Enum constants internally hold a `String configValue`. + +#### Output +- `configValue()` returns the strategy’s config token. +- `fromConfig(String)` returns an `AiOversizeStrategy` instance. +- `DEFAULT` constant is returned for null/blank values. + +#### Core logic +- `fromConfig` trims input, checks for null/blank, iterates over all enum constants comparing `configValue` case‑insensitively, returns match or throws `IllegalArgumentException` if none found. + +#### Public API +- `configValue() -> String` – retrieves the config token. +- `fromConfig(String) -> AiOversizeStrategy` – parses strategy from config string. + +#### Dependencies +- `org.jspecify.annotations.Nullable` for nullable parameter annotation. + +#### Exceptions / Errors +- `IllegalArgumentException` thrown when a non‑blank config value does not match any strategy. + +#### Concurrency +- Immutable enum; thread‑safe by design. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiRangeCondition.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiRangeCondition.java.ai.md new file mode 100644 index 0000000..84bfa27 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiRangeCondition.java.ai.md @@ -0,0 +1,55 @@ +### AiRangeCondition.java +- H: 1.0 +- C: 694E254D +- D: 2026-06-29T19:51:15Z +- T: 2026-07-02T23:09:57Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 8; TODO/FIXME: 0; @Override: 0; methods (approx): 7; constructors: 1; field declarations (w/ modifier): 2 + +> Defines a numeric range used by AI index conditions for file size or line count. + +#### Purpose +- Holds an exclusive lower bound and an inclusive upper bound for numeric conditions. +- Enables checking whether a value falls within the configured range. + +#### Type +- Class `AiRangeCondition` (public). +- Uses Lombok `@ToString`. +- No inheritance or interfaces. + +#### Input +- `min` and `max` fields set via setters or Maven plugin configuration. +- Constructor initializes an empty instance. + +#### Output +- `contains(long)` returns whether a value is within bounds. +- `hasBound()` indicates if any bound is active. +- Lombok-generated `toString()` representation. + +#### Core logic +- `contains(value)`: + 1. If `min > 0` and `value <= min` → `false`. + 2. If `max > 0` and `value > max` → `false`. + 3. Otherwise → `true`. +- `hasBound()` returns `true` when `min > 0` or `max > 0`. + +#### Public API +- `AiRangeCondition()` → constructs empty range. +- `getMin() -> long` – returns exclusive lower bound. +- `setMin(long)` – sets exclusive lower bound. +- `getMax() -> long` – returns inclusive upper bound. +- `setMax(long)` – sets inclusive upper bound. +- `contains(long) -> boolean` – checks value inside range. +- `hasBound() -> boolean` – checks if range has active bounds. + +#### Dependencies +- `lombok.ToString`. + +#### Exceptions / Errors +- No checked or unchecked exceptions thrown. + +#### Concurrency +- No synchronization; instance is mutable and not thread‑safe. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/package.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/package.ai.md new file mode 100644 index 0000000..5a3398b --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/config/package.ai.md @@ -0,0 +1,88 @@ +### main/java/net/ladenthin/maven/llamacpp/aiindex/config +- H: 1.0 +- C: C16C9ACE +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T23:19:39Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: package +- F: [AiCalibration.java](AiCalibration.java.ai.md) +- F: [AiCondition.java](AiCondition.java.ai.md) +- F: [AiConditionEvaluator.java](AiConditionEvaluator.java.ai.md) +- F: [AiConditionGroup.java](AiConditionGroup.java.ai.md) +- F: [AiFactCounter.java](AiFactCounter.java.ai.md) +- F: [AiFactDefinition.java](AiFactDefinition.java.ai.md) +- F: [AiFactDefinitionSupport.java](AiFactDefinitionSupport.java.ai.md) +- F: [AiFactExtractor.java](AiFactExtractor.java.ai.md) +- F: [AiFieldGenerationConfig.java](AiFieldGenerationConfig.java.ai.md) +- F: [AiFieldGenerationSelector.java](AiFieldGenerationSelector.java.ai.md) +- F: [AiFileContext.java](AiFileContext.java.ai.md) +- F: [AiGenerationConfig.java](AiGenerationConfig.java.ai.md) +- F: [AiGenerationKind.java](AiGenerationKind.java.ai.md) +- F: [AiModelDefinition.java](AiModelDefinition.java.ai.md) +- F: [AiModelDefinitionSupport.java](AiModelDefinitionSupport.java.ai.md) +- F: [AiOversizeStrategy.java](AiOversizeStrategy.java.ai.md) +- F: [AiRangeCondition.java](AiRangeCondition.java.ai.md) +--- +> A Maven plugin that configures, evaluates, and routes AI‑based code‑analysis tasks using llama‑cpp models, applying file‑matching rules, fact extraction, and oversize handling. + +#### Purpose +- Configure AI model parameters and routing rules for source‑code generation. +- Evaluate file selection conditions and apply fact extraction. +- Resolve model and fact definitions into concrete runtime configurations. + +#### Responsibilities +- **Model configuration** – `AiModelDefinition`, `AiModelDefinitionSupport`, `AiGenerationConfig`. +- **Fact management** – `AiFactDefinition`, `AiFactDefinitionSupport`, `AiFactCounter`, `AiFactExtractor`. +- **Condition evaluation** – `AiCondition`, `AiConditionGroup`, `AiRangeCondition`, `AiConditionEvaluator`. +- **Routing selection** – `AiFieldGenerationConfig`, `AiFieldGenerationSelector`. +- **Oversize handling** – `AiOversizeStrategy`. +- **Calibration** – `AiCalibration`. +- **Context snapshot** – `AiFileContext`. + +#### Key units +- `AiModelDefinition` – key + full GGUF model settings. +- `AiModelDefinitionSupport` – builds `Map`. +- `AiGenerationConfig` – mutable runtime parameters for llama‑cpp. +- `AiFactDefinition` – named group of `AiFactCounter` regexes. +- `AiFactDefinitionSupport` – resolves fact keys to counters. +- `AiFactExtractor` – produces deterministic facts block. +- `AiCondition` – recursive boolean tree for file selection. +- `AiConditionGroup` – container for AND/OR children. +- `AiRangeCondition` – numeric bounds for size/lines. +- `AiConditionEvaluator` – validates and matches conditions. +- `AiFieldGenerationConfig` – single routing rule (priority, action, oversize, facts). +- `AiFieldGenerationSelector` – selects applicable rule for a file. +- `AiOversizeStrategy` – enum of oversize handling options. +- `AiCalibration` – per‑model timing and token‑to‑char ratios. +- `AiFileContext` – immutable snapshot of file metadata. + +#### Data flow +1. **Configuration phase** + - Maven plugin loads `AiModelDefinition` and `AiFactDefinition` lists. + - `AiModelDefinitionSupport` converts models to `AiGenerationConfig`. + - `AiFactDefinitionSupport` maps fact keys to counters. + +2. **Routing decision** + - `AiFieldGenerationSelector` iterates `AiFieldGenerationConfig` rules. + - Uses `AiConditionEvaluator` to test each rule’s `AiCondition` against a `AiFileContext`. + - Highest‑priority matching rule (or fallback) is chosen. + +3. **Fact extraction** + - If the rule defines facts (inline or via key), `AiFactExtractor.factsBlock` generates a header string with exact regex counts. + +4. **Model execution** + - The selected `AiGenerationConfig` (from `AiModelDefinitionSupport`) provides all runtime parameters to llama‑cpp. + - `AiCalibration` supplies hardware‑specific timing adjustments. + +#### Dependencies +- **Internal** – `AiConditionEvaluator`, `AiFieldGenerationSelector`, `AiFactExtractor`, `AiModelDefinitionSupport`, `AiFactDefinitionSupport`. +- **External libraries** – Lombok (`@ToString`), jspecify (`@Nullable`), Java 8 `java.time`, regex APIs. +- **Data sources** – Maven plugin configuration XML, source files (via `AiFileContext`). + +#### Cross‑cutting +- All configuration beans use Lombok `@ToString` and suppress uninitialized field warnings. +- Mutable configuration classes are not thread‑safe; instances are built once during plugin execution. +- Validation logic resides in `AiConditionEvaluator` and `AiFieldGenerationSelector`. +- Fact extraction is pure and stateless, enabling reuse across threads. +- Enums (`AiOversizeStrategy`, `AiGenerationKind`) provide immutable, thread‑safe configuration constants. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/package.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/package.ai.md new file mode 100644 index 0000000..09c3f1d --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/package.ai.md @@ -0,0 +1,83 @@ +### main/java/net/ladenthin/maven/llamacpp/aiindex +- H: 1.0 +- C: E77032F7 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T23:30:01Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: package +- F: [config/](config/package.ai.md) +- F: [provider/](provider/package.ai.md) +--- +> A Maven plugin framework that configures, evaluates, and routes AI‑based code‑analysis tasks using llama‑cpp models, applying file‑matching rules, fact extraction, and oversize handling. + +#### Purpose +- Configure AI model parameters and routing rules for source‑code generation. +- Evaluate file selection conditions and apply fact extraction. +- Resolve model and fact definitions into concrete runtime configurations. + +#### Responsibilities +- **Model configuration** – handling GGUF model settings and runtime parameters. +- **Fact management** – defining, resolving, and extracting deterministic fact blocks. +- **Condition evaluation** – recursive boolean logic for file selection. +- **Routing selection** – choosing the appropriate generation rule per file. +- **Oversize handling** – strategies for large inputs. +- **Calibration** – hardware‑specific timing and token‑to‑char ratios. +- **Context snapshot** – immutable representation of file metadata. + +#### Key units +- `AiModelDefinition` – full GGUF model settings. +- `AiModelDefinitionSupport` – builds `Map`. +- `AiGenerationConfig` – mutable runtime parameters for llama‑cpp. +- `AiFactDefinition` – named group of regex counters. +- `AiFactDefinitionSupport` – resolves fact keys to counters. +- `AiFactExtractor` – generates deterministic facts header. +- `AiCondition` / `AiConditionGroup` – recursive boolean tree for selection. +- `AiRangeCondition` – numeric bounds for size/lines. +- `AiConditionEvaluator` – validates and matches conditions. +- `AiFieldGenerationConfig` – single routing rule (priority, action, oversize, facts). +- `AiFieldGenerationSelector` – selects applicable rule for a file. +- `AiOversizeStrategy` – enum of oversize handling options. +- `AiCalibration` – per‑model timing and token‑to‑char ratios. +- `AiFileContext` – immutable snapshot of file metadata. +- `AiGenerationProvider` – interface for text generation. +- `AiGenerationProviderFactory` – creates mock or JNI providers. +- `MockAiGenerationProvider` – deterministic mock implementation. +- `LlamaCppJniAiGenerationProvider` – JNI‑backed provider. +- `LlamaCppJniConfig` – immutable config holder for llama.cpp runtime options. +- `AiCompletionParser` – removes thinking blocks from completions. +- `AiGenerationTimings` – immutable DTO with text, token counts, throughput. + +#### Data flow +1. **Configuration** + - Plugin loads `AiModelDefinition` and `AiFactDefinition` lists. + - `AiModelDefinitionSupport` → `AiGenerationConfig`; + - `AiFactDefinitionSupport` → fact counters. + +2. **Routing** + - `AiFieldGenerationSelector` iterates `AiFieldGenerationConfig` rules. + - `AiConditionEvaluator` tests each rule’s `AiCondition` against `AiFileContext`. + - Highest‑priority rule chosen. + +3. **Fact extraction** + - `AiFactExtractor.factsBlock` generates header string. + +4. **Generation** + - `AiGenerationProviderFactory` creates provider. + - Provider receives `AiGenerationRequest`. + - JNI provider loads `LlamaModel`, builds `InferenceParameters`, runs chat completion, parses with `AiCompletionParser`, extracts timings, returns `AiGenerationTimings`. + - Mock provider returns deterministic text and synthetic timings. + +#### Dependencies +- **Internal** – `AiConditionEvaluator`, `AiFieldGenerationSelector`, `AiFactExtractor`, `AiModelDefinitionSupport`, `AiFactDefinitionSupport`, `AiGenerationProviderFactory`, `AiCompletionParser`. +- **External** – Lombok (`@ToString`), jspecify (`@Nullable`), Java 8 `java.time`, regex APIs, `net.ladenthin:llama` JNI library. +- **Data sources** – Maven plugin configuration XML, source files via `AiFileContext`. + +#### Cross‑cutting +- Lombok `@ToString` on all configuration beans; uninitialized warnings suppressed. +- Mutable configuration classes are single‑use, not thread‑safe. +- Immutable config (`LlamaCppJniConfig`, `AiGenerationTimings`) are thread‑safe. +- Fact extraction is pure and stateless, enabling reuse across threads. +- Validation logic centralized in `AiConditionEvaluator` and `AiFieldGenerationSelector`. +- Lazy model loading in `LlamaCppJniAiGenerationProvider`. +- Mock provider facilitates unit testing without native dependencies. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiCompletionParser.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiCompletionParser.java.ai.md new file mode 100644 index 0000000..01a8568 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiCompletionParser.java.ai.md @@ -0,0 +1,50 @@ +### AiCompletionParser.java +- H: 1.0 +- C: 78BEBEB3 +- D: 2026-06-25T05:31:58Z +- T: 2026-07-02T23:10:45Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 5; TODO/FIXME: 0; @Override: 0; methods (approx): 2; constructors: 1; field declarations (w/ modifier): 2 + +> Parses raw LLM completion text to extract the model answer by stripping any model‑internal thinking block before the result is stored in an AI index file. + +#### Purpose +- Extracts final model answer from Gemma‑4 style completions. +- Removes internal chain‑of‑thought blocks. +- Validates token budget exhaustion. + +#### Type +- Class, non‑final, public. +- Annotated `@ToString` (Lombok). +- No inheritance or interfaces. + +#### Input +- `parseCompletion(String response)` receives raw model output, may be `null`. +- No injected dependencies or external resources. + +#### Output +- Returns a non‑null, trimmed answer string. +- May throw `IOException` when a thinking block is started but not closed. + +#### Core logic +- If `response` is `null` → return empty string. +- Find last index of `THINKING_BLOCK_END_MARKER`; if found → return substring after it, trimmed. +- If only `THINKING_BLOCK_START_MARKER` present → throw `IOException` with explanatory message. +- Otherwise → return trimmed `response`. + +#### Public API +- `AiCompletionParser()` → constructs an empty parser. +- `String parseCompletion(String response) throws IOException` → cleans completion text. + +#### Dependencies +- `java.io.IOException` +- `lombok.ToString` + +#### Exceptions / Errors +- Throws `IOException` if a thinking block is started but not closed, indicating token budget exhaustion. + +#### Concurrency +- Stateless; safe for concurrent use. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationProvider.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationProvider.java.ai.md new file mode 100644 index 0000000..9a568d0 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationProvider.java.ai.md @@ -0,0 +1,52 @@ +### AiGenerationProvider.java +- H: 1.0 +- C: 14BD5D6E +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T23:11:35Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 1; TODO/FIXME: 0; @Override: 1; methods (approx): 3; constructors: 0; field declarations (w/ modifier): 0 + +> Provides a pluggable AI backend that generates text for an AI generation request, with optional timing metrics. + +#### Purpose +- Supplies generated text for `AiGenerationRequest`. +- Optional timing information for calibration. + +#### Type +- Interface `AiGenerationProvider` (public, extends `AutoCloseable`). + +#### Input +- Method `generate(AiGenerationRequest request)` – receives `AiGenerationRequest` containing prompt key, source file, source text, and current header. +- Method `generateWithTimings(AiGenerationRequest request)` – same request input. +- Inherited `close()` – no parameters. + +#### Output +- `generate` returns a non‑null `String` (possibly blank). +- `generateWithTimings` returns an `AiGenerationTimings` containing generated text and timing metrics. +- `close` has no return value. + +#### Core logic +- `generate` is abstract; implementations provide model inference. +- `generateWithTimings` default: calls `generate`, wraps result in `AiGenerationTimings` with zeroed timing fields. +- `close` default: no action. + +#### Public API +- `generate(AiGenerationRequest request) -> String` – produce text from request. +- `generateWithTimings(AiGenerationRequest request) -> AiGenerationTimings` – generate text with timing. +- `close() -> void` – release resources. + +#### Dependencies +- `java.io.IOException` +- `net.ladenthin.maven.llamacpp.aiindex.document.AiGenerationRequest` +- `net.ladenthin.maven.llamacpp.aiindex.provider.AiGenerationTimings` (used in default method). + +#### Exceptions / Errors +- `generate` may throw `IOException` if provider fails. +- `generateWithTimings` may throw `IOException`. +- `close` may throw `IOException`. + +#### Concurrency +- No explicit thread‑safety guarantees; implementations may manage concurrency. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationProviderFactory.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationProviderFactory.java.ai.md new file mode 100644 index 0000000..45907b8 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationProviderFactory.java.ai.md @@ -0,0 +1,54 @@ +### AiGenerationProviderFactory.java +- H: 1.0 +- C: 0ADDB961 +- D: 2026-06-25T05:31:58Z +- T: 2026-07-02T23:12:20Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 3; TODO/FIXME: 0; @Override: 0; methods (approx): 2; constructors: 1; field declarations (w/ modifier): 1 + +> Instantiates AI generation providers (mock or llama.cpp JNI) based on a name. + +#### Purpose +- Factory for `AiGenerationProvider` instances. +- Chooses implementation according to provider key. + +#### Type +- Class `AiGenerationProviderFactory` (public, final by default, no annotations except `@ToString`). + +#### Input +- `String providerName` – key (“mock” or “llamacpp-jni”). +- `LlamaCppJniConfig llamaConfig` – config for JNI provider. +- `AiPromptSupport promptSupport` – prompt lookup for providers that need it. +- Internal `Java8CompatibilityHelper` for blank checks. + +#### Output +- Returns a new `AiGenerationProvider` instance. +- Throws `IllegalArgumentException` for unsupported names. + +#### Core logic +- If `providerName` is null or blank → return `MockAiGenerationProvider`. +- Switch on `providerName`: + - `"mock"` → `MockAiGenerationProvider`. + - `"llamacpp-jni"` → `LlamaCppJniAiGenerationProvider(llamaConfig, promptSupport)`. + - Default → throw `IllegalArgumentException`. + +#### Public API +- `AiGenerationProviderFactory()` → constructor, no side effects. +- `AiGenerationProvider create(String, LlamaCppJniConfig, AiPromptSupport) → new provider instance` – selects and creates provider. + +#### Dependencies +- `net.ladenthin.maven.llamacpp.aiindex.prompt.AiPromptSupport` +- `net.ladenthin.maven.llamacpp.aiindex.support.Java8CompatibilityHelper` +- `lombok.ToString` +- `MockAiGenerationProvider` +- `LlamaCppJniAiGenerationProvider` +- `LlamaCppJniConfig` + +#### Exceptions / Errors +- `IllegalArgumentException` when provider name is unsupported. + +#### Concurrency +- Stateless; thread‑safe. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationTimings.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationTimings.java.ai.md new file mode 100644 index 0000000..9c1a8fc --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationTimings.java.ai.md @@ -0,0 +1,46 @@ +### AiGenerationTimings.java +- H: 1.0 +- C: 1D58E849 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T23:13:06Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 7; TODO/FIXME: 0; @Override: 0; methods (approx): 6; constructors: 1; field declarations (w/ modifier): 5 + +> Holds text output with model timing metrics for AI generation. + +#### Purpose +- Encapsulates generated text and performance data for calibration. + +#### Type +- final class `AiGenerationTimings` +- Annotations: `@ConvertToRecord`, `@ToString`, `@EqualsAndHashCode` + +#### Input +- Constructor parameters: `String text`, `int promptTokens`, `double prefillTokensPerSecond`, `int predictedTokens`, `double decodeTokensPerSecond` + +#### Output +- Getter methods returning each field value. + +#### Core logic +- Stores supplied values in private final fields. +- Provides accessor methods that simply return those fields. + +#### Public API +- `AiGenerationTimings(String, int, double, int, double) -> AiGenerationTimings` – create instance +- `text() -> String` – get generated text +- `promptTokens() -> int` – get prompt token count +- `prefillTokensPerSecond() -> double` – get prefill throughput +- `predictedTokens() -> int` – get generated token count +- `decodeTokensPerSecond() -> double` – get decode throughput + +#### Dependencies +- `lombok.EqualsAndHashCode`, `lombok.ToString`, `net.ladenthin.maven.llamacpp.aiindex.support.ConvertToRecord` + +#### Exceptions / Errors +- None declared; constructor accepts all parameters directly. + +#### Concurrency +- Immutable after construction; thread‑safe. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/LlamaCppJniAiGenerationProvider.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/LlamaCppJniAiGenerationProvider.java.ai.md new file mode 100644 index 0000000..ebe8037 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/LlamaCppJniAiGenerationProvider.java.ai.md @@ -0,0 +1,58 @@ +### LlamaCppJniAiGenerationProvider.java +- H: 1.0 +- C: 3EAED1F5 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T23:13:50Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 5; TODO/FIXME: 0; @Override: 3; methods (approx): 6; constructors: 1; field declarations (w/ modifier): 9 + +> Provides local, llama.cpp‑backed text generation for Maven AI indexing, exposing a high‑level request API and timing metrics. + +#### Purpose +- Implements `AiGenerationProvider` using the `net.ladenthin:llama` JNI binding. +- Delivers text completions and optional timing data for AI index generation. + +#### Type +- `final class` with `@ToString` Lombok annotation. +- Implements `AiGenerationProvider, AutoCloseable`. +- Fields: `config`, `model`, `promptSupport`, `completionParser`, `chatResponseParser`, `compatibilityHelper`. +- Static constants: `REUSE_SLOT_ID`, `ENABLE_THINKING_KWARG`, `REASONING_EFFORT_KWARG`, `CHAT_TEMPLATE_KWARG_COUNT`. + +#### Input +- Constructor receives `LlamaCppJniConfig config` and `AiPromptSupport promptSupport`. +- `generate(AiGenerationRequest)` and `generateWithTimings(AiGenerationRequest)` consume `AiGenerationRequest` objects. +- `buildInferenceParameters` uses `AiGenerationRequest` plus `config` to create `InferenceParameters`. + +#### Output +- `generate` returns a `String` completion. +- `generateWithTimings` returns `AiGenerationTimings` (text, prompt token count, prompt rate, predicted token count, predicted rate). +- `close()` frees the native `LlamaModel`. + +#### Core logic +- **Lazy model loading**: `model()` constructs a `LlamaModel` on first use, configuring it with model path, context size, threads, GPU settings, SWA, cache reuse, and chat‑template kwargs. +- **Prompt construction**: `buildInferenceParameters` builds immutable `InferenceParameters` by combining system and user prompts, chat‑template usage, temperature, token limits, top‑p/k, penalties, DRY settings, stop strings, cache prompt, and slot ID. +- **Text generation**: `generate` calls `chatCompleteText` via `completionParser`. +- **Timing extraction**: `generateWithTimings` parses full JSON response with `chatResponseParser`, extracts `Timings`, and packages them with the first choice’s content. + +#### Public API +- `generate(AiGenerationRequest) -> String` – produce completion text. +- `generateWithTimings(AiGenerationRequest) -> AiGenerationTimings` – produce completion text with model timings. +- `close() -> void` – release native resources. + +#### Dependencies +- `net.ladenthin.llama.LlamaModel`, `net.ladenthin.llama.args.ReasoningFormat`, `net.ladenthin.llama.json.ChatResponseParser`, `net.ladenthin.llama.parameters.*`, `net.ladenthin.llama.value.*`. +- `net.ladenthin.maven.llamacpp.aiindex.*` (request, prompt, support). +- `lombok.ToString`. +- `org.jspecify.annotations.Nullable`. + +#### Exceptions / Errors +- `generate` declares `throws IOException`. +- Internal unchecked exceptions may propagate from native calls or parsing. +- Null checks via `Objects.requireNonNull` for constructor parameters. + +#### Concurrency +- Thread‑unsafe; `LlamaModel` is not synchronized. +- Instance state (model, config) is immutable after construction except for lazy initialization. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/LlamaCppJniConfig.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/LlamaCppJniConfig.java.ai.md new file mode 100644 index 0000000..d595104 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/LlamaCppJniConfig.java.ai.md @@ -0,0 +1,68 @@ +### LlamaCppJniConfig.java +- H: 1.0 +- C: C7A880F8 +- D: 2026-06-29T19:51:15Z +- T: 2026-07-02T23:16:08Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 28; TODO/FIXME: 0; @Override: 0; methods (approx): 27; constructors: 1; field declarations (w/ modifier): 26 + +> Immutable configuration holder for llama.cpp JNI provider. + +#### Purpose +- Stores runtime parameters for llama.cpp JNI execution. + +#### Type +- Final class `LlamaCppJniConfig`; extends `Object`; implements no interfaces; annotated with `@ConvertToRecord`, `@ToString`, `@EqualsAndHashCode`. + +#### Input +- Constructor parameters: 26 values (`String libraryPath`, `String modelPath`, `int contextSize`, `int maxOutputTokens`, `float temperature`, `int threads`, `float topP`, `int topK`, `float minP`, `float topNSigma`, `float repeatPenalty`, `boolean chatTemplateEnableThinking`, `boolean cachePrompt`, `boolean swaFull`, `int cacheReuse`, `int gpuLayers`, `int mainGpu`, `String devices`, `String reasoningEffort`, `int reasoningBudgetTokens`, `float dryMultiplier`, `float dryBase`, `int dryAllowedLength`, `int dryPenaltyLastN`, `List drySequenceBreakers`, `List stopStrings`). + +#### Output +- Public accessors return stored values; `drySequenceBreakers()` and `stopStrings()` return unmodifiable lists. + +#### Core logic +- Constructor validates non‑null `modelPath` and assigns all fields, defaulting null list parameters to empty lists. +- Accessors simply expose field values; list accessors wrap with `Collections.unmodifiableList`. + +#### Public API +- `LlamaCppJniConfig(...) -> LlamaCppJniConfig` constructor (initialization) +- `libraryPath() -> String` returns native lib path +- `modelPath() -> String` returns GGUF model path +- `contextSize() -> int` context window size +- `maxOutputTokens() -> int` max output tokens +- `temperature() -> float` sampling temperature +- `threads() -> int` CPU thread count +- `topP() -> float` nucleus sampling threshold +- `topK() -> int` top‑k limit +- `minP() -> float` min‑p threshold +- `topNSigma() -> float` top‑n‑sigma threshold +- `repeatPenalty() -> float` repetition penalty +- `chatTemplateEnableThinking() -> boolean` chat‑template mode flag +- `cachePrompt() -> boolean` prompt caching flag +- `swaFull() -> boolean` full‑size SWA flag +- `cacheReuse() -> int` KV prefix‑reuse chunk size +- `gpuLayers() -> int` GPU layers offload +- `mainGpu() -> int` primary GPU index +- `devices() -> String` device selection +- `reasoningEffort() -> String` reasoning‑effort value +- `reasoningBudgetTokens() -> int` reasoning token budget +- `dryMultiplier() -> float` DRY multiplier +- `dryBase() -> float` DRY base +- `dryAllowedLength() -> int` DRY allowed length +- `dryPenaltyLastN() -> int` DRY penalty look‑back +- `drySequenceBreakers() -> List` unmodifiable DRY breakers +- `stopStrings() -> List` unmodifiable stop strings + +#### Dependencies +- `java.util.Collections`, `java.util.List`, `java.util.Objects` +- Lombok: `@EqualsAndHashCode`, `@ToString` +- `net.ladenthin.maven.llamacpp.aiindex.support.ConvertToRecord` + +#### Exceptions / Errors +- `NullPointerException` thrown by `Objects.requireNonNull` if `modelPath` is null. + +#### Concurrency +- All fields are `final`; class is immutable and thread‑safe. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/MockAiGenerationProvider.java.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/MockAiGenerationProvider.java.ai.md new file mode 100644 index 0000000..5fb1ff8 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/MockAiGenerationProvider.java.ai.md @@ -0,0 +1,60 @@ +### MockAiGenerationProvider.java +- H: 1.0 +- C: CEF2EE28 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T23:18:43Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 4; TODO/FIXME: 0; @Override: 2; methods (approx): 3; constructors: 1; field declarations (w/ modifier): 4 + +> Provides deterministic AI summary generation for testing, returning a mock summary string and synthetic timing metrics. + +#### Purpose +- Supplies a mock implementation of `AiGenerationProvider` for unit tests. +- Returns deterministic summaries and timing data without invoking an actual model. + +#### Type +- Class `MockAiGenerationProvider` +- Implements `AiGenerationProvider` +- Annotated with `@ToString` + +#### Input +- `AiGenerationRequest request` (source file path and source text). + +#### Output +- `String` mock summary: `"Mock summary for "`. +- `AiGenerationTimings` with synthetic token counts and throughputs. + +#### Core logic +- Extract file name from `request.sourceFile()`; fallback to file path if absent. +- Construct summary string using the file name. +- Compute prompt token count: `request.sourceText().length() / MOCK_CHARS_PER_TOKEN`. +- Create `AiGenerationTimings` with: + - summary string, prompt token count, prefill throughput, predicted token count, decode throughput. + +#### Public API +- `MockAiGenerationProvider()` → constructs instance. +- `generate(AiGenerationRequest)` → returns mock summary. +- `generateWithTimings(AiGenerationRequest)` → returns mock timing data. + +#### Dependencies +- `java.io.IOException` +- `java.nio.file.Path` +- `lombok.ToString` +- `net.ladenthin.maven.llamacpp.aiindex.document.AiGenerationRequest` +- `net.ladenthin.maven.llamacpp.aiindex.provider.AiGenerationProvider` (interface) +- `net.ladenthin.maven.llamacpp.aiindex.provider.AiGenerationTimings` + +#### Exceptions / Errors +- Throws `IOException` (declared but not actually thrown in current logic). + +#### Concurrency +- Stateless; thread‑safe. + +#### Fields +- `MOCK_PREFILL_TOKENS_PER_SECOND = 1000.0d` +- `MOCK_DECODE_TOKENS_PER_SECOND = 100.0d` +- `MOCK_CHARS_PER_TOKEN = 4` +- `MOCK_PREDICTED_TOKENS = 64` diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/package.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/package.ai.md new file mode 100644 index 0000000..6b1484c --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/package.ai.md @@ -0,0 +1,61 @@ +### main/java/net/ladenthin/maven/llamacpp/aiindex/provider +- H: 1.0 +- C: 073ED68B +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T23:27:05Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: package +- F: [AiCompletionParser.java](AiCompletionParser.java.ai.md) +- F: [AiGenerationProvider.java](AiGenerationProvider.java.ai.md) +- F: [AiGenerationProviderFactory.java](AiGenerationProviderFactory.java.ai.md) +- F: [AiGenerationTimings.java](AiGenerationTimings.java.ai.md) +- F: [LlamaCppJniAiGenerationProvider.java](LlamaCppJniAiGenerationProvider.java.ai.md) +- F: [LlamaCppJniConfig.java](LlamaCppJniConfig.java.ai.md) +- F: [MockAiGenerationProvider.java](MockAiGenerationProvider.java.ai.md) +--- +> A framework for generating and timing AI‑based text completions, with a pluggable backend that supports a mock provider for testing and a native llama.cpp JNI provider for production. + +#### Purpose +- Provide a pluggable AI text generation service for Maven AI indexing. +- Offer optional performance metrics for calibration. + +#### Responsibilities +- **Request handling** – accept `AiGenerationRequest` objects containing prompt data. +- **Provider selection** – instantiate the correct `AiGenerationProvider` (mock or llama.cpp JNI) via a factory. +- **Completion parsing** – strip internal thinking blocks from raw LLM outputs. +- **Timing extraction** – capture model token counts and throughput for analysis. +- **Configuration** – expose immutable runtime settings for the llama.cpp backend. + +#### Key units +- `AiGenerationProvider` (interface) – defines `generate` and `generateWithTimings`. +- `AiGenerationProviderFactory` – selects and creates providers based on a key. +- `MockAiGenerationProvider` – deterministic mock implementation for tests. +- `LlamaCppJniAiGenerationProvider` – JNI‑backed provider that loads a `LlamaModel`, builds inference parameters, runs chat completion, and parses timing. +- `LlamaCppJniConfig` – immutable config holder for llama.cpp runtime options. +- `AiCompletionParser` – removes thinking blocks from raw completions. +- `AiGenerationTimings` – immutable DTO with text, token counts, and throughput. + +#### Data flow +1. **Client code** requests generation via `AiGenerationProviderFactory.create(...)`. +2. Factory returns a concrete provider (mock or JNI) based on the supplied name. +3. Provider receives an `AiGenerationRequest` (prompt key, source file/text, header). +4. For the JNI provider: + - Lazily loads a `LlamaModel` using `LlamaCppJniConfig`. + - Builds `InferenceParameters` from the request and config. + - Calls the native model to produce a chat completion JSON. + - Parses the first choice’s content with `AiCompletionParser`. + - Extracts `Timings` from the JSON and wraps results in `AiGenerationTimings`. +5. For the mock provider: + - Generates a deterministic summary string and synthetic timing data. + +#### Dependencies +- **Internal**: `AiGenerationRequest`, `AiPromptSupport`, `AiCompletionParser`, `ChatResponseParser`, `InferenceParameters`, `LlamaModel`. +- **External**: `net.ladenthin:llama` JNI library, Lombok annotations, `org.jspecify.annotations.Nullable`. +- **Config**: `LlamaCppJniConfig` provides all runtime parameters for the native provider. + +#### Cross‑cutting +- **Immutability**: `LlamaCppJniConfig` and `AiGenerationTimings` are final and thread‑safe. +- **Error handling**: `AiCompletionParser` throws `IOException` for malformed thinking blocks; providers propagate `IOException` on failures. +- **Lazy initialization**: `LlamaCppJniAiGenerationProvider` defers model loading until first request. +- **Mock support**: `MockAiGenerationProvider` offers deterministic outputs for unit tests, avoiding native dependencies. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/package.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/package.ai.md new file mode 100644 index 0000000..bf2f53e --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/llamacpp/package.ai.md @@ -0,0 +1,67 @@ +### main/java/net/ladenthin/maven/llamacpp +- H: 1.0 +- C: BB07F829 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T23:32:14Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: package +- F: [aiindex/](aiindex/package.ai.md) +--- +> A Maven plugin framework that orchestrates llama‑cpp based AI code‑analysis tasks, handling model configuration, fact extraction, rule routing, and oversize strategies. + +#### Purpose +- Configure AI model parameters and routing rules for source‑code generation. +- Evaluate file selection conditions and apply fact extraction. +- Resolve model and fact definitions into concrete runtime configurations. + +#### Responsibilities +- **Model configuration** – GGUF settings and runtime parameters. +- **Fact management** – deterministic fact block definition and extraction. +- **Condition evaluation** – recursive boolean logic for file selection. +- **Routing selection** – choose appropriate generation rule per file. +- **Oversize handling** – strategies for large inputs. +- **Calibration** – hardware‑specific timing and token‑to‑char ratios. +- **Context snapshot** – immutable representation of file metadata. + +#### Key units +- `AiModelDefinition` – full GGUF model settings. +- `AiModelDefinitionSupport` – builds `Map`. +- `AiGenerationConfig` – mutable runtime parameters for llama‑cpp. +- `AiFactDefinition` – named group of regex counters. +- `AiFactDefinitionSupport` – resolves fact keys to counters. +- `AiFactExtractor` – generates deterministic facts header. +- `AiCondition` / `AiConditionGroup` – recursive boolean tree for selection. +- `AiRangeCondition` – numeric bounds for size/lines. +- `AiConditionEvaluator` – validates and matches conditions. +- `AiFieldGenerationConfig` – single routing rule (priority, action, oversize, facts). +- `AiFieldGenerationSelector` – selects applicable rule for a file. +- `AiOversizeStrategy` – enum of oversize handling options. +- `AiCalibration` – per‑model timing and token‑to‑char ratios. +- `AiFileContext` – immutable snapshot of file metadata. +- `AiGenerationProvider` – interface for text generation. +- `AiGenerationProviderFactory` – creates mock or JNI providers. +- `MockAiGenerationProvider` – deterministic mock implementation. +- `LlamaCppJniAiGenerationProvider` – JNI‑backed provider. +- `LlamaCppJniConfig` – immutable config holder for llama.cpp runtime options. +- `AiCompletionParser` – removes thinking blocks from completions. +- `AiGenerationTimings` – immutable DTO with text, token counts, throughput. + +#### Data flow +1. **Configuration** – load `AiModelDefinition` and `AiFactDefinition`; build runtime `AiGenerationConfig` and fact counters. +2. **Routing** – `AiFieldGenerationSelector` iterates `AiFieldGenerationConfig` rules, using `AiConditionEvaluator` against `AiFileContext`; highest‑priority rule is chosen. +3. **Fact extraction** – `AiFactExtractor.factsBlock` produces header string. +4. **Generation** – `AiGenerationProviderFactory` creates provider; provider receives `AiGenerationRequest`, runs chat completion via JNI or mock, parses output with `AiCompletionParser`, records timings, returns `AiGenerationTimings`. + +#### Dependencies +- Internal: `AiConditionEvaluator`, `AiFieldGenerationSelector`, `AiFactExtractor`, `AiModelDefinitionSupport`, `AiFactDefinitionSupport`, `AiGenerationProviderFactory`, `AiCompletionParser`. +- External: Lombok (`@ToString`), jspecify (`@Nullable`), Java 8 time, regex APIs, `net.ladenthin:llama` JNI library. +- Data sources: Maven plugin configuration XML, source files via `AiFileContext`. + +#### Cross-cutting +- Lombok `@ToString` on configuration beans; uninitialized warnings suppressed. +- Mutable configuration classes are single‑use, not thread‑safe; immutable classes (`LlamaCppJniConfig`, `AiGenerationTimings`) are thread‑safe. +- Fact extraction is pure and stateless, enabling reuse across threads. +- Validation logic centralized in `AiConditionEvaluator` and `AiFieldGenerationSelector`. +- Lazy model loading in `LlamaCppJniAiGenerationProvider`. +- Mock provider facilitates unit testing without native dependencies. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/package.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/package.ai.md new file mode 100644 index 0000000..a802970 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/maven/package.ai.md @@ -0,0 +1,58 @@ +### main/java/net/ladenthin/maven +- H: 1.0 +- C: 84F070A1 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T23:34:00Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: package +- F: [llamacpp/](llamacpp/package.ai.md) +--- +> A Maven plugin framework that orchestrates llama‑cpp based AI code‑analysis tasks, handling model configuration, fact extraction, rule routing, and oversize strategies. + +#### Purpose +- Configure AI model parameters and routing rules for source‑code generation. +- Evaluate file selection conditions and apply fact extraction. +- Resolve model and fact definitions into concrete runtime configurations. + +#### Responsibilities +- **Model configuration** – GGUF settings and runtime parameters. +- **Fact management** – deterministic fact block definition and extraction. +- **Condition evaluation** – recursive boolean logic for file selection. +- **Routing selection** – choose appropriate generation rule per file. +- **Oversize handling** – strategies for large inputs. +- **Calibration** – hardware‑specific timing and token‑to‑char ratios. +- **Context snapshot** – immutable representation of file metadata. + +#### Key units +- `AiModelDefinition`, `AiModelDefinitionSupport` – GGUF model settings and builder. +- `AiGenerationConfig`, `AiGenerationProvider`, `AiGenerationProviderFactory` – runtime generation parameters and provider creation. +- `AiFactDefinition`, `AiFactDefinitionSupport`, `AiFactExtractor` – named regex counter groups and fact header generation. +- `AiCondition`, `AiConditionGroup`, `AiRangeCondition`, `AiConditionEvaluator` – recursive boolean tree for file selection. +- `AiFieldGenerationConfig`, `AiFieldGenerationSelector` – routing rule definition and rule selection. +- `AiOversizeStrategy` – enum of oversize handling options. +- `AiCalibration` – per‑model timing and token‑to‑char ratios. +- `AiFileContext` – immutable snapshot of file metadata. +- `LlamaCppJniAiGenerationProvider`, `LlamaCppJniConfig` – JNI‑backed provider and immutable runtime config. +- `MockAiGenerationProvider` – deterministic mock implementation. +- `AiCompletionParser` – removes thinking blocks from completions. +- `AiGenerationTimings` – immutable DTO with text, token counts, throughput. + +#### Data flow +1. **Configuration** – load `AiModelDefinition` and `AiFactDefinition`; build runtime `AiGenerationConfig` and fact counters. +2. **Routing** – `AiFieldGenerationSelector` iterates `AiFieldGenerationConfig` rules, using `AiConditionEvaluator` against `AiFileContext`; highest‑priority rule is chosen. +3. **Fact extraction** – `AiFactExtractor.factsBlock` produces header string. +4. **Generation** – `AiGenerationProviderFactory` creates provider; provider receives `AiGenerationRequest`, runs chat completion via JNI or mock, parses output with `AiCompletionParser`, records timings, returns `AiGenerationTimings`. + +#### Dependencies +- Internal: `AiConditionEvaluator`, `AiFieldGenerationSelector`, `AiFactExtractor`, `AiModelDefinitionSupport`, `AiFactDefinitionSupport`, `AiGenerationProviderFactory`, `AiCompletionParser`. +- External: Lombok (`@ToString`), jspecify (`@Nullable`), Java 8 time, regex APIs, `net.ladenthin:llama` JNI library. +- Data sources: Maven plugin configuration XML, source files via `AiFileContext`. + +#### Cross-cutting +- Lombok `@ToString` on configuration beans; uninitialized warnings suppressed. +- Mutable configuration classes are single‑use, not thread‑safe; immutable classes (`LlamaCppJniConfig`, `AiGenerationTimings`) are thread‑safe. +- Fact extraction is pure and stateless, enabling reuse across threads. +- Validation logic centralized in `AiConditionEvaluator` and `AiFieldGenerationSelector`. +- Lazy model loading in `LlamaCppJniAiGenerationProvider`. +- Mock provider facilitates unit testing without native dependencies. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/package.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/package.ai.md new file mode 100644 index 0000000..3dd25c7 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/ladenthin/package.ai.md @@ -0,0 +1,58 @@ +### main/java/net/ladenthin +- H: 1.0 +- C: DCA70847 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T23:35:39Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: package +- F: [maven/](maven/package.ai.md) +--- +> A Maven plugin framework that orchestrates llama‑cpp based AI code‑analysis tasks, handling model configuration, fact extraction, rule routing, and oversize strategies. + +#### Purpose +- Configure AI model parameters and routing rules for source‑code generation. +- Evaluate file selection conditions and apply fact extraction. +- Resolve model and fact definitions into concrete runtime configurations. + +#### Responsibilities +- **Model configuration** – GGUF settings and runtime parameters. +- **Fact management** – deterministic fact block definition and extraction. +- **Condition evaluation** – recursive boolean logic for file selection. +- **Routing selection** – choose appropriate generation rule per file. +- **Oversize handling** – strategies for large inputs. +- **Calibration** – hardware‑specific timing and token‑to‑char ratios. +- **Context snapshot** – immutable representation of file metadata. + +#### Key units +- `AiModelDefinition`, `AiModelDefinitionSupport` – GGUF model settings and builder. +- `AiGenerationConfig`, `AiGenerationProvider`, `AiGenerationProviderFactory` – runtime generation parameters and provider creation. +- `AiFactDefinition`, `AiFactDefinitionSupport`, `AiFactExtractor` – named regex counter groups and fact header generation. +- `AiCondition`, `AiConditionGroup`, `AiRangeCondition`, `AiConditionEvaluator` – recursive boolean tree for file selection. +- `AiFieldGenerationConfig`, `AiFieldGenerationSelector` – routing rule definition and rule selection. +- `AiOversizeStrategy` – enum of oversize handling options. +- `AiCalibration` – per‑model timing and token‑to‑char ratios. +- `AiFileContext` – immutable snapshot of file metadata. +- `LlamaCppJniAiGenerationProvider`, `LlamaCppJniConfig` – JNI‑backed provider and immutable runtime config. +- `MockAiGenerationProvider` – deterministic mock implementation. +- `AiCompletionParser` – removes thinking blocks from completions. +- `AiGenerationTimings` – immutable DTO with text, token counts, throughput. + +#### Data flow +1. **Configuration** – load `AiModelDefinition` and `AiFactDefinition`; build runtime `AiGenerationConfig` and fact counters. +2. **Routing** – `AiFieldGenerationSelector` iterates `AiFieldGenerationConfig` rules, using `AiConditionEvaluator` against `AiFileContext`; highest‑priority rule is chosen. +3. **Fact extraction** – `AiFactExtractor.factsBlock` produces header string. +4. **Generation** – `AiGenerationProviderFactory` creates provider; provider receives `AiGenerationRequest`, runs chat completion via JNI or mock, parses output with `AiCompletionParser`, records timings, returns `AiGenerationTimings`. + +#### Dependencies +- Internal: `AiConditionEvaluator`, `AiFieldGenerationSelector`, `AiFactExtractor`, `AiModelDefinitionSupport`, `AiFactDefinitionSupport`, `AiGenerationProviderFactory`, `AiCompletionParser`. +- External: Lombok (`@ToString`), jspecify (`@Nullable`), Java 8 time, regex APIs, `net.ladenthin:llama` JNI library. +- Data sources: Maven plugin configuration XML, source files via `AiFileContext`. + +#### Cross-cutting +- Lombok `@ToString` on configuration beans; uninitialized warnings suppressed. +- Mutable configuration classes are single‑use, not thread‑safe; immutable classes (`LlamaCppJniConfig`, `AiGenerationTimings`) are thread‑safe. +- Fact extraction is pure and stateless, enabling reuse across threads. +- Validation logic centralized in `AiConditionEvaluator` and `AiFieldGenerationSelector`. +- Lazy model loading in `LlamaCppJniAiGenerationProvider`. +- Mock provider facilitates unit testing without native dependencies. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/package.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/package.ai.md new file mode 100644 index 0000000..51a176c --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/net/package.ai.md @@ -0,0 +1,58 @@ +### main/java/net +- H: 1.0 +- C: FAF52897 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T23:37:12Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: package +- F: [ladenthin/](ladenthin/package.ai.md) +--- +> A Maven‑plugin framework that orchestrates llama‑cpp based AI code‑analysis tasks, managing model config, fact extraction, rule routing, and oversize strategies. + +#### Purpose +- Configure AI model parameters and routing rules for source‑code generation. +- Evaluate file selection conditions and apply fact extraction. +- Resolve model and fact definitions into concrete runtime configurations. + +#### Responsibilities +- **Model configuration** – GGUF settings and runtime parameters. +- **Fact management** – deterministic fact block definition and extraction. +- **Condition evaluation** – recursive boolean logic for file selection. +- **Routing selection** – choose appropriate generation rule per file. +- **Oversize handling** – strategies for large inputs. +- **Calibration** – hardware‑specific timing and token‑to‑char ratios. +- **Context snapshot** – immutable representation of file metadata. + +#### Key units +- `AiModelDefinition`, `AiModelDefinitionSupport` – GGUF model settings and builder. +- `AiGenerationConfig`, `AiGenerationProvider`, `AiGenerationProviderFactory` – runtime generation parameters and provider creation. +- `AiFactDefinition`, `AiFactDefinitionSupport`, `AiFactExtractor` – named regex counter groups and fact header generation. +- `AiCondition`, `AiConditionGroup`, `AiRangeCondition`, `AiConditionEvaluator` – recursive boolean tree for file selection. +- `AiFieldGenerationConfig`, `AiFieldGenerationSelector` – routing rule definition and rule selection. +- `AiOversizeStrategy` – enum of oversize handling options. +- `AiCalibration` – per‑model timing and token‑to‑char ratios. +- `AiFileContext` – immutable snapshot of file metadata. +- `LlamaCppJniAiGenerationProvider`, `LlamaCppJniConfig` – JNI‑backed provider and immutable runtime config. +- `MockAiGenerationProvider` – deterministic mock implementation. +- `AiCompletionParser` – removes thinking blocks from completions. +- `AiGenerationTimings` – immutable DTO with text, token counts, throughput. + +#### Data flow +1. **Configuration** – load `AiModelDefinition` and `AiFactDefinition`; build runtime `AiGenerationConfig` and fact counters. +2. **Routing** – `AiFieldGenerationSelector` iterates `AiFieldGenerationConfig` rules, using `AiConditionEvaluator` against `AiFileContext`; highest‑priority rule is chosen. +3. **Fact extraction** – `AiFactExtractor.factsBlock` produces header string. +4. **Generation** – `AiGenerationProviderFactory` creates provider; provider receives `AiGenerationRequest`, runs chat completion via JNI or mock, parses output with `AiCompletionParser`, records timings, returns `AiGenerationTimings`. + +#### Dependencies +- Internal: `AiConditionEvaluator`, `AiFieldGenerationSelector`, `AiFactExtractor`, `AiModelDefinitionSupport`, `AiFactDefinitionSupport`, `AiGenerationProviderFactory`, `AiCompletionParser`. +- External: Lombok (`@ToString`), jspecify (`@Nullable`), Java 8 time, regex APIs, `net.ladenthin:llama` JNI library. +- Data sources: Maven plugin configuration XML, source files via `AiFileContext`. + +#### Cross-cutting +- Lombok `@ToString` on configuration beans; uninitialized warnings suppressed. +- Mutable configuration classes are single‑use, not thread‑safe; immutable classes (`LlamaCppJniConfig`, `AiGenerationTimings`) are thread‑safe. +- Fact extraction is pure and stateless, enabling reuse across threads. +- Validation logic centralized in `AiConditionEvaluator` and `AiFieldGenerationSelector`. +- Lazy model loading in `LlamaCppJniAiGenerationProvider`. +- Mock provider facilitates unit testing without native dependencies. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/package.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/package.ai.md new file mode 100644 index 0000000..24b2628 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/java/package.ai.md @@ -0,0 +1,56 @@ +### main/java +- H: 1.0 +- C: E34B0133 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T23:38:45Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: package +- F: [net/](net/package.ai.md) +--- +> A Maven‑plugin framework that orchestrates llama‑cpp based AI code‑analysis tasks, managing model config, fact extraction, rule routing, and oversize strategies. + +#### Purpose +- Configure AI model parameters and routing rules for source‑code generation. +- Evaluate file selection conditions and apply fact extraction. +- Resolve model and fact definitions into concrete runtime configurations. + +#### Responsibilities +- **Model configuration** – GGUF settings, runtime parameters, and calibration. +- **Fact management** – deterministic fact block definition, extraction, and header generation. +- **Condition evaluation** – recursive boolean logic for file selection. +- **Routing selection** – choosing the appropriate generation rule per file. +- **Oversize handling** – strategies for large inputs. +- **Context snapshot** – immutable representation of file metadata. + +#### Key units +- `AiModelDefinition`, `AiModelDefinitionSupport` – GGUF model settings and builder. +- `AiGenerationConfig`, `AiGenerationProvider`, `AiGenerationProviderFactory` – runtime generation parameters and provider creation. +- `AiFactDefinition`, `AiFactDefinitionSupport`, `AiFactExtractor` – named regex counter groups and fact header generation. +- `AiCondition`, `AiConditionGroup`, `AiRangeCondition`, `AiConditionEvaluator` – recursive boolean tree for file selection. +- `AiFieldGenerationConfig`, `AiFieldGenerationSelector` – routing rule definition and rule selection. +- `AiOversizeStrategy` – enum of oversize handling options. +- `AiCalibration` – per‑model timing and token‑to‑char ratios. +- `AiFileContext` – immutable snapshot of file metadata. +- `LlamaCppJniAiGenerationProvider`, `LlamaCppJniConfig` – JNI‑backed provider and immutable runtime config. +- `MockAiGenerationProvider` – deterministic mock implementation. +- `AiCompletionParser` – removes thinking blocks from completions. +- `AiGenerationTimings` – immutable DTO with text, token counts, throughput. + +#### Data flow +1. Load `AiModelDefinition` and `AiFactDefinition`; build `AiGenerationConfig` and fact counters. +2. `AiFieldGenerationSelector` evaluates `AiConditionEvaluator` against `AiFileContext` to pick a routing rule. +3. `AiFactExtractor.factsBlock` creates the fact header string. +4. `AiGenerationProviderFactory` creates a provider; provider runs a chat completion via JNI or mock, parses output with `AiCompletionParser`, records timings, and returns `AiGenerationTimings`. + +#### Dependencies +- Internal: `AiConditionEvaluator`, `AiFieldGenerationSelector`, `AiFactExtractor`, `AiModelDefinitionSupport`, `AiFactDefinitionSupport`, `AiGenerationProviderFactory`, `AiCompletionParser`. +- External: Lombok (`@ToString`), jspecify (`@Nullable`), Java 8 time, regex APIs, `net.ladenthin:llama` JNI library. +- Configuration sources: Maven plugin XML, source files via `AiFileContext`. + +#### Cross-cutting +- Lombok `@ToString` on configuration beans; mutable configuration classes are single‑use, not thread‑safe; immutable classes (`LlamaCppJniConfig`, `AiGenerationTimings`) are thread‑safe. +- Fact extraction is pure and stateless, enabling reuse across threads. +- Validation logic centralized in `AiConditionEvaluator` and `AiFieldGenerationSelector`. +- Lazy model loading in `LlamaCppJniAiGenerationProvider`. +- Mock provider facilitates unit testing without native dependencies. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/package.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/package.ai.md new file mode 100644 index 0000000..0d3b58a --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/main/package.ai.md @@ -0,0 +1,56 @@ +### main +- H: 1.0 +- C: 1886955F +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T23:40:14Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: package +- F: [java/](java/package.ai.md) +--- +> A Maven‑plugin framework that orchestrates llama‑cpp based AI code‑analysis tasks, managing model config, fact extraction, rule routing, and oversize strategies. + +#### Purpose +- Configure AI model parameters and routing rules for source‑code generation. +- Evaluate file selection conditions and apply fact extraction. +- Resolve model and fact definitions into concrete runtime configurations. + +#### Responsibilities +- **Model configuration** – GGUF settings, runtime parameters, and calibration. +- **Fact management** – deterministic fact block definition, extraction, and header generation. +- **Condition evaluation** – recursive boolean logic for file selection. +- **Routing selection** – choosing the appropriate generation rule per file. +- **Oversize handling** – strategies for large inputs. +- **Context snapshot** – immutable representation of file metadata. + +#### Key units +- `AiModelDefinition`, `AiModelDefinitionSupport` – GGUF model settings and builder. +- `AiGenerationConfig`, `AiGenerationProvider`, `AiGenerationProviderFactory` – runtime generation parameters and provider creation. +- `AiFactDefinition`, `AiFactDefinitionSupport`, `AiFactExtractor` – named regex counter groups and fact header generation. +- `AiCondition`, `AiConditionGroup`, `AiRangeCondition`, `AiConditionEvaluator` – recursive boolean tree for file selection. +- `AiFieldGenerationConfig`, `AiFieldGenerationSelector` – routing rule definition and rule selection. +- `AiOversizeStrategy` – enum of oversize handling options. +- `AiCalibration` – per‑model timing and token‑to‑char ratios. +- `AiFileContext` – immutable snapshot of file metadata. +- `LlamaCppJniAiGenerationProvider`, `LlamaCppJniConfig` – JNI‑backed provider and immutable runtime config. +- `MockAiGenerationProvider` – deterministic mock implementation. +- `AiCompletionParser` – removes thinking blocks from completions. +- `AiGenerationTimings` – immutable DTO with text, token counts, throughput. + +#### Data flow +1. Load `AiModelDefinition` and `AiFactDefinition`; build `AiGenerationConfig` and fact counters. +2. `AiFieldGenerationSelector` evaluates `AiConditionEvaluator` against `AiFileContext` to pick a routing rule. +3. `AiFactExtractor.factsBlock` creates the fact header string. +4. `AiGenerationProviderFactory` creates a provider; provider runs a chat completion via JNI or mock, parses output with `AiCompletionParser`, records timings, and returns `AiGenerationTimings`. + +#### Dependencies +- Internal: `AiConditionEvaluator`, `AiFieldGenerationSelector`, `AiFactExtractor`, `AiModelDefinitionSupport`, `AiFactDefinitionSupport`, `AiGenerationProviderFactory`, `AiCompletionParser`. +- External: Lombok (`@ToString`), jspecify (`@Nullable`), Java 8 time, regex APIs, `net.ladenthin:llama` JNI library. +- Configuration sources: Maven plugin XML, source files via `AiFileContext`. + +#### Cross-cutting +- Lombok `@ToString` on configuration beans; mutable configuration classes are single‑use, not thread‑safe; immutable classes (`LlamaCppJniConfig`, `AiGenerationTimings`) are thread‑safe. +- Fact extraction is pure and stateless, enabling reuse across threads. +- Validation logic centralized in `AiConditionEvaluator` and `AiFieldGenerationSelector`. +- Lazy model loading in `LlamaCppJniAiGenerationProvider`. +- Mock provider facilitates unit testing without native dependencies. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/package.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/package.ai.md new file mode 100644 index 0000000..569cbb7 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/package.ai.md @@ -0,0 +1,56 @@ +### ai +- H: 1.0 +- C: 193DCE8A +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T23:41:41Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: package +- F: [main/](main/package.ai.md) +--- +> A Maven‑plugin framework that orchestrates llama‑cpp based AI code‑analysis tasks, managing model config, fact extraction, rule routing, and oversize strategies. + +#### Purpose +- Configure AI model parameters and routing rules for source‑code generation. +- Evaluate file selection conditions and apply fact extraction. +- Resolve model and fact definitions into concrete runtime configurations. + +#### Responsibilities +- **Model configuration** – GGUF settings, runtime parameters, and calibration. +- **Fact management** – deterministic fact block definition, extraction, and header generation. +- **Condition evaluation** – recursive boolean logic for file selection. +- **Routing selection** – choosing the appropriate generation rule per file. +- **Oversize handling** – strategies for large inputs. +- **Context snapshot** – immutable representation of file metadata. + +#### Key units +- **AiModelDefinition / AiModelDefinitionSupport** – GGUF model settings and builder. +- **AiGenerationConfig / AiGenerationProvider / AiGenerationProviderFactory** – runtime generation parameters and provider creation. +- **AiFactDefinition / AiFactDefinitionSupport / AiFactExtractor** – named regex counter groups and fact header generation. +- **AiCondition / AiConditionGroup / AiRangeCondition / AiConditionEvaluator** – recursive boolean tree for file selection. +- **AiFieldGenerationConfig / AiFieldGenerationSelector** – routing rule definition and rule selection. +- **AiOversizeStrategy** – enum of oversize handling options. +- **AiCalibration** – per‑model timing and token‑to‑char ratios. +- **AiFileContext** – immutable snapshot of file metadata. +- **LlamaCppJniAiGenerationProvider / LlamaCppJniConfig** – JNI‑backed provider and immutable runtime config. +- **MockAiGenerationProvider** – deterministic mock implementation. +- **AiCompletionParser** – removes thinking blocks from completions. +- **AiGenerationTimings** – immutable DTO with text, token counts, throughput. + +#### Data flow +1. Load `AiModelDefinition` and `AiFactDefinition`; build `AiGenerationConfig` and fact counters. +2. `AiFieldGenerationSelector` evaluates `AiConditionEvaluator` against `AiFileContext` to pick a routing rule. +3. `AiFactExtractor.factsBlock` creates the fact header string. +4. `AiGenerationProviderFactory` creates a provider; provider runs a chat completion via JNI or mock, parses output with `AiCompletionParser`, records timings, and returns `AiGenerationTimings`. + +#### Dependencies +- Internal: `AiConditionEvaluator`, `AiFieldGenerationSelector`, `AiFactExtractor`, `AiModelDefinitionSupport`, `AiFactDefinitionSupport`, `AiGenerationProviderFactory`, `AiCompletionParser`. +- External: Lombok (`@ToString`), jspecify (`@Nullable`), Java 8 time, regex APIs, `net.ladenthin:llama` JNI library. +- Configuration sources: Maven plugin XML, source files via `AiFileContext`. + +#### Cross-cutting +- Lombok `@ToString` on configuration beans; mutable configuration classes are single‑use, not thread‑safe; immutable classes (`LlamaCppJniConfig`, `AiGenerationTimings`) are thread‑safe. +- Fact extraction is pure and stateless, enabling reuse across threads. +- Validation logic centralized in `AiConditionEvaluator` and `AiFieldGenerationSelector`. +- Lazy model loading in `LlamaCppJniAiGenerationProvider`. +- Mock provider facilitates unit testing without native dependencies. diff --git a/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/project.ai.md b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/project.ai.md new file mode 100644 index 0000000..3385d71 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__gptoss-20b__v1cur/project.ai.md @@ -0,0 +1,35 @@ +### llamacpp-ai-index-maven-plugin +- H: 1.0 +- C: D514A04D +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T23:43:12Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: project +- F: [main/java/net/ladenthin/maven/llamacpp/aiindex/config](main/java/net/ladenthin/maven/llamacpp/aiindex/config/package.ai.md) +- F: [main/java/net/ladenthin/maven/llamacpp/aiindex](main/java/net/ladenthin/maven/llamacpp/aiindex/package.ai.md) +- F: [main/java/net/ladenthin/maven/llamacpp/aiindex/provider](main/java/net/ladenthin/maven/llamacpp/aiindex/provider/package.ai.md) +- F: [main/java/net/ladenthin/maven/llamacpp](main/java/net/ladenthin/maven/llamacpp/package.ai.md) +- F: [main/java/net/ladenthin/maven](main/java/net/ladenthin/maven/package.ai.md) +- F: [main/java/net/ladenthin](main/java/net/ladenthin/package.ai.md) +- F: [main/java/net](main/java/net/package.ai.md) +- F: [main/java](main/java/package.ai.md) +- F: [main](main/package.ai.md) +- F: [.](package.ai.md) +--- +> Project index of llamacpp-ai-index-maven-plugin: one line per package; leads here, clickable links in the header F list. + +#### Overview +The project is a Maven plugin framework that orchestrates AI‑based code‑analysis tasks using llama‑cpp models. Core functionality includes configuring the model, extracting facts from source files, routing tasks through file‑matching rules, and handling oversize inputs. A pluggable provider layer supplies text completions, with a native JNI backend for production and a mock provider for testing. The architecture ties together configuration, rule routing, fact extraction, and provider timing to deliver end‑to‑end AI analysis within Maven builds. + +#### Packages +- main/java/net/ladenthin/maven/llamacpp/aiindex/config — A Maven plugin that configures, evaluates, and routes AI‑based code‑analysis tasks using llama‑cpp models, applying file‑matching rules, fact extraction, and oversize handling. +- main/java/net/ladenthin/maven/llamacpp/aiindex — A Maven plugin framework that configures, evaluates, and routes AI‑based code‑analysis tasks using llama‑cpp models, applying file‑matching rules, fact extraction, and oversize handling. +- main/java/net/ladenthin/maven/llamacpp/aiindex/provider — A framework for generating and timing AI‑based text completions, with a pluggable backend that supports a mock provider for testing and a native llama.cpp JNI provider for production. +- main/java/net/ladenthin/maven/llamacpp — A Maven plugin framework that orchestrates llama‑cpp based AI code‑analysis tasks, handling model configuration, fact extraction, rule routing, and oversize strategies. +- main/java/net/ladenthin/maven — A Maven plugin framework that orchestrates llama‑cpp based AI code‑analysis tasks, handling model configuration, fact extraction, rule routing, and oversize strategies. +- main/java/net/ladenthin — A Maven plugin framework that orchestrates llama‑cpp based AI code‑analysis tasks, handling model configuration, fact extraction, rule routing, and oversize strategies. +- main/java/net — A Maven‑plugin framework that orchestrates llama‑cpp based AI code‑analysis tasks, managing model config, fact extraction, rule routing, and oversize strategies. +- main/java — A Maven‑plugin framework that orchestrates llama‑cpp based AI code‑analysis tasks, managing model config, fact extraction, rule routing, and oversize strategies. +- main — A Maven‑plugin framework that orchestrates llama‑cpp based AI code‑analysis tasks, managing model config, fact extraction, rule routing, and oversize strategies. +- . — A Maven‑plugin framework that orchestrates llama‑cpp based AI code‑analysis tasks, managing model config, fact extraction, rule routing, and oversize strategies. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiCalibration.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiCalibration.java.ai.md new file mode 100644 index 0000000..9c0de0d --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiCalibration.java.ai.md @@ -0,0 +1,56 @@ +### AiCalibration.java +- H: 1.0 +- C: C4C9EE6C +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T21:36:44Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 8; TODO/FIXME: 0; @Override: 0; methods (approx): 7; constructors: 1; field declarations (w/ modifier): 3 + +> Holds per-model, per-machine timing calibration data for AI index planning. + +#### Purpose +- Stores calibration metrics for AI model performance. +- Enables accurate time estimation in AI index plans. + +#### Type +- Class `AiCalibration` (public, mutable JavaBean). +- Annotated with `@ToString` (Lombok). +- No equals/hashCode generated. + +#### Input +- Constructor: no parameters. +- Setters: `setPrefillTokensPerSecond(double)`, `setDecodeTokensPerSecond(double)`, `setCharsPerToken(double)`. +- Fields: `prefillTokensPerSecond`, `decodeTokensPerSecond`, `charsPerToken`. + +#### Output +- Getters: `getPrefillTokensPerSecond()`, `getDecodeTokensPerSecond()`, `getCharsPerToken()`. +- `toString()` via Lombok. + +#### Core logic +- Simple storage of three double values. +- No validation or computation; values are directly assigned and retrieved. + +#### Public API +- `AiCalibration()` – creates a new calibration instance. +- `double getPrefillTokensPerSecond()` – return prefill throughput. +- `void setPrefillTokensPerSecond(double)` – set prefill throughput. +- `double getDecodeTokensPerSecond()` – return decode throughput. +- `void setDecodeTokensPerSecond(double)` – set decode throughput. +- `double getCharsPerToken()` – return characters per token. +- `void setCharsPerToken(double)` – set characters per token. +- `String toString()` – generated string representation. + +#### Dependencies +- `lombok.ToString`. +- `net.ladenthin.maven.llamacpp.aiindex.config` package. + +#### Exceptions / Errors +- No explicit exceptions thrown. +- No null handling needed; primitive doubles used. + +#### Concurrency +- No synchronization; mutable state is not thread‑safe. +- Intended for single‑threaded configuration use. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiCondition.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiCondition.java.ai.md new file mode 100644 index 0000000..c81e2d9 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiCondition.java.ai.md @@ -0,0 +1,66 @@ +### AiCondition.java +- H: 1.0 +- C: 15F73517 +- D: 2026-06-29T19:51:15Z +- T: 2026-07-02T21:38:21Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 20; TODO/FIXME: 0; @Override: 0; methods (approx): 10; constructors: 1; field declarations (w/ modifier): 0 + +> A configurable boolean tree for matching files in a Maven plugin. + +#### Purpose +- Holds a file‑matching rule for routing. +- Supports combinators (`and`, `or`, `not`) and leaf conditions (extension, size, lines, modified dates, path glob). + +#### Type +- Class, public, annotated with `@ToString`. +- Fields are nullable; no modifiers. + +#### Input +- Constructor: no parameters. +- Setter methods accept `AiConditionGroup`, `Collection`, `AiRangeCondition`, `String`. +- Dependencies: `AiConditionGroup`, `AiRangeCondition`. + +#### Output +- Getter methods expose current field values. +- Internal state mutated by setters. + +#### Core logic +- No business logic; serves as a data holder for the evaluator. + +#### Public API +- `AiCondition()` → constructor. +- `getAnd() -> AiConditionGroup` 1. +- `setAnd(AiConditionGroup) -> void` 2. +- `getOr() -> AiConditionGroup` 3. +- `setOr(AiConditionGroup) -> void` 4. +- `getNot() -> AiCondition` 5. +- `setNot(AiCondition) -> void` 6. +- `getExtensions() -> List` 7. +- `setExtensions(Collection) -> void` 8. +- `getSize() -> AiRangeCondition` 9. +- `setSize(AiRangeCondition) -> void` 10. +- `getLines() -> AiRangeCondition` 11. +- `setLines(AiRangeCondition) -> void` 12. +- `getModifiedAfter() -> String` 13. +- `setModifiedAfter(String) -> void` 14. +- `getModifiedBefore() -> String` 15. +- `setModifiedBefore(String) -> void` 16. +- `getPathGlob() -> String` 17. +- `setPathGlob(String) -> void` 18. + +#### Dependencies +- `AiConditionGroup` +- `AiRangeCondition` +- `java.util.ArrayList`, `java.util.Collection`, `java.util.List` +- `lombok.ToString` +- `org.jspecify.annotations.Nullable` + +#### Exceptions / Errors +- No explicit exceptions thrown. + +#### Concurrency +- No synchronization; instance is mutable and not thread‑safe. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiConditionEvaluator.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiConditionEvaluator.java.ai.md new file mode 100644 index 0000000..d21b7c5 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiConditionEvaluator.java.ai.md @@ -0,0 +1,58 @@ +### AiConditionEvaluator.java +- H: 1.0 +- C: 66F4DB55 +- D: 2026-06-29T19:51:15Z +- T: 2026-07-02T21:40:00Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 5; TODO/FIXME: 0; @Override: 0; methods (approx): 10; constructors: 1; field declarations (w/ modifier): 1 + +> Evaluates and validates file‑based conditions for an AI indexer, determining matches, validation, and line‑usage needs. + +#### Purpose +- Validate condition trees for correctness. +- Determine if a file context satisfies a condition tree. +- Detect if line counting is required. + +#### Type +`class` (final). No extends/implements. + +#### Input +- `AiCondition` tree (constructor of evaluator does nothing). +- `AiFileContext` facts for `matches`. +- `AiCondition` for `validate` and `usesLines`. + +#### Output +- `boolean` from `matches`, `usesLines`. +- `IllegalArgumentException` for invalid conditions. + +#### Core logic +- `matches`: recursively walk `and`, `or`, `not`, leafs (`extensions`, `size`, `lines`, `modifiedAfter`, `modifiedBefore`, `pathGlob`). +- `validate`: enforce single branch/leaf per node, check non‑empty lists, bounds, parse dates, non‑blank glob. +- `usesLines`: recursively search for a `lines` node. +- `branchCount`: count non‑null branch/leaf fields. +- `matchesExtension`: check file name suffixes. +- `globMatches`: use `AiSourceExcludeFilter` to test path. +- `parseEpochMilli`: parse ISO‑8601 to epoch ms. + +#### Public API +- `matches(AiCondition, AiFileContext) -> boolean` – check file matches condition tree. +- `validate(AiCondition) -> void` – ensure tree is well‑formed. +- `usesLines(AiCondition) -> boolean` – detect if line counting is needed. + +#### Dependencies +- `net.ladenthin.maven.llamacpp.aiindex.support.AiSourceExcludeFilter` +- `net.ladenthin.maven.llamacpp.aiindex.config.AiCondition`, `AiConditionGroup`, `AiRangeCondition`, `AiFileContext` +- `java.time.Instant`, `java.time.format.DateTimeParseException` +- `java.util.Collections`, `java.util.List` +- `org.jspecify.annotations.Nullable` + +#### Exceptions / Errors +- `IllegalArgumentException` for invalid condition nodes. +- `IllegalStateException` if a node has no branch/leaf. +- `DateTimeParseException` wrapped in `IllegalArgumentException` for malformed dates. + +#### Concurrency +- Immutable evaluator; no shared mutable state. Thread‑safe. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiConditionGroup.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiConditionGroup.java.ai.md new file mode 100644 index 0000000..a096cab --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiConditionGroup.java.ai.md @@ -0,0 +1,53 @@ +### AiConditionGroup.java +- H: 1.0 +- C: B4457D08 +- D: 2026-06-29T19:51:15Z +- T: 2026-07-02T21:41:47Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 4; TODO/FIXME: 0; @Override: 0; methods (approx): 2; constructors: 1; field declarations (w/ modifier): 0 + +> Holds a list of child conditions for an and/or combinator in the AI index configuration. + +#### Purpose +- Represents the body of an `` or `` combinator in an `AiCondition`. +- Provides a container for child `AiCondition` instances. + +#### Type +- Class `AiConditionGroup` +- Modifiers: public, final (implicit), Lombok `@ToString`. +- No inheritance or interfaces. + +#### Input +- Constructor: no parameters. +- `setConditions(Collection)`: accepts a collection of child conditions, may be `null`. + +#### Output +- `getConditions()`: returns the list of child conditions or `null`. +- Internal state: private `@Nullable List conditions`. + +#### Core logic +- `setConditions`: if argument not null, copies into a new `ArrayList`; otherwise sets field to `null`. +- `getConditions`: simply returns the stored list. + +#### Public API +- `AiConditionGroup() -> void` – default constructor. +- `getConditions() -> @Nullable List` – retrieve child conditions. +- `setConditions(@Nullable Collection) -> void` – set child conditions, defensive copy. + +#### Dependencies +- `java.util.ArrayList`, `java.util.Collection`, `java.util.List`. +- `lombok.ToString`. +- `org.jspecify.annotations.Nullable`. +- `net.ladenthin.maven.llamacpp.aiindex.config.AiCondition`. + +#### Exceptions / Errors +- No checked exceptions thrown. +- Accepts `null` for the collection parameter; results in `null` field. + +#### Concurrency +- No synchronization; class is not thread‑safe. + +--- diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactCounter.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactCounter.java.ai.md new file mode 100644 index 0000000..eafd0e9 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactCounter.java.ai.md @@ -0,0 +1,47 @@ +### AiFactCounter.java +- H: 1.0 +- C: 2BFA8358 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T21:42:30Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 6; TODO/FIXME: 0; @Override: 0; methods (approx): 5; constructors: 1; field declarations (w/ modifier): 2 + +> Provides a mutable configuration object for counting regex matches in source files. + +#### Purpose +- Holds a label and a regex pattern for counting matches. +- Supplies getters and setters for Maven plugin reflection. + +#### Type +- Class `AiFactCounter` (public, mutable JavaBean). + +#### Input +- Constructor: none. +- Fields set via `setLabel(String)` and `setPattern(String)` (via reflection or code). + +#### Output +- `getLabel()` returns the human‑readable label. +- `getPattern()` returns the regex pattern. +- `toString()` (Lombok) provides diagnostic representation. + +#### Core logic +- None beyond field accessors; purely a data holder. + +#### Public API +- `AiFactCounter()` – creates an empty instance. +- `String getLabel()` – returns current label. +- `void setLabel(String)` – assigns label. +- `String getPattern()` – returns current pattern. +- `void setPattern(String)` – assigns pattern. + +#### Dependencies +- `lombok.ToString` for `toString()` generation. + +#### Exceptions / Errors +- No exceptions thrown; methods accept and return `String` without validation. + +#### Concurrency +- No thread‑safety guarantees; intended for single‑thread configuration usage. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinition.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinition.java.ai.md new file mode 100644 index 0000000..21b2c72 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinition.java.ai.md @@ -0,0 +1,52 @@ +### AiFactDefinition.java +- H: 1.0 +- C: F74A4B9F +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T21:43:10Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 6; TODO/FIXME: 0; @Override: 0; methods (approx): 4; constructors: 1; field declarations (w/ modifier): 1 + +> Defines a named group of reusable AI fact counters for Maven plugin configuration. + +#### Purpose +- Stores a lookup key for reference in routing rules. +- Holds an optional list of `AiFactCounter` objects. + +#### Type +Class, mutable JavaBean, Lombok `@ToString`, annotated with `@SuppressWarnings`. + +#### Input +- Constructor: none (default). +- `setKey(String key)` – sets the lookup key. +- `setFacts(List facts)` – assigns the fact counter list. + +#### Output +- `getKey()` – returns the lookup key. +- `getFacts()` – returns the list of `AiFactCounter` or `null`. + +#### Core logic +- Simple field assignments and retrievals; no additional logic. + +#### Public API +- `AiFactDefinition()` → constructs a new instance +- `String getKey()` → get the lookup key +- `void setKey(String key)` → set the lookup key +- `List getFacts()` → get configured fact counters +- `void setFacts(List facts)` → set fact counters + +#### Dependencies +- `java.util.List` +- `lombok.ToString` +- `org.jspecify.annotations.Nullable` +- `net.ladenthin.maven.llamacpp.aiindex.config.AiFactCounter` + +#### Exceptions / Errors +- No checked or unchecked exceptions thrown. +- Null handling: `facts` may be `null`. + +#### Concurrency +- No synchronization; class is not thread‑safe. +- Intended for single‑threaded configuration usage. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinitionSupport.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinitionSupport.java.ai.md new file mode 100644 index 0000000..e7b9826 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinitionSupport.java.ai.md @@ -0,0 +1,66 @@ +### AiFactDefinitionSupport.java +- H: 1.0 +- C: D98D3BA4 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T21:43:55Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 4; TODO/FIXME: 0; @Override: 0; methods (approx): 3; constructors: 1; field declarations (w/ modifier): 3 + +> Provides shared fact counter groups for routing rules and injects them into rule configurations. + +#### Purpose +- Holds reusable fact counter groups. +- Resolves rule references to these groups. + +#### Type +- `final class AiFactDefinitionSupport` + - Extends `Object`. + - No interfaces. + - Uses Lombok `@ToString`. + +#### Input +- Constructor: `List definitions` (nullable). +- `resolveFactsKeys`: `Iterable rules` (may contain nulls). + +#### Output +- `facts(String key)` returns `List` (never null). +- `resolveFactsKeys` mutates each non‑null rule’s `facts` list. + +#### Core logic +- **Constructor** + 1. If `definitions` null → empty map. + 2. Else iterate definitions. + 3. Validate each `definition.getKey()` not null. + 4. Map key → `definition.getFacts()` or empty list. +- **facts(key)** + 1. Retrieve from map. + 2. Throw `IllegalArgumentException` if missing. +- **resolveFactsKeys(rules)** + 1. For each non‑null rule. + 2. If `factsKey` present, replace rule’s facts with `facts(factsKey)`. + +#### Public API +- `AiFactDefinitionSupport(List definitions)` → constructs support. +- `List facts(String key)` → get counters for key. +- `void resolveFactsKeys(Iterable rules)` → inject counters into rules. + +#### Dependencies +- `java.util.*` (Map, List, HashMap, Collections, Objects). +- `lombok.ToString`. +- `net.ladenthin.maven.llamacpp.aiindex.support.Java8CompatibilityHelper`. +- `org.jspecify.annotations.Nullable`. +- `net.ladenthin.maven.llamacpp.aiindex.config.AiFactDefinition`. +- `net.ladenthin.maven.llamacpp.aiindex.config.AiFactCounter`. +- `net.ladenthin.maven.llamacpp.aiindex.config.AiFieldGenerationConfig`. + +#### Exceptions / Errors +- Constructor: `NullPointerException` if any definition key null. +- `facts`: `IllegalArgumentException` if key missing. +- `resolveFactsKeys`: same as `facts` for missing key. + +#### Concurrency +- Immutable after construction; thread‑safe read operations. +- `resolveFactsKeys` mutates rule objects; caller responsible for synchronization. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactExtractor.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactExtractor.java.ai.md new file mode 100644 index 0000000..9452357 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactExtractor.java.ai.md @@ -0,0 +1,47 @@ +### AiFactExtractor.java +- H: 1.0 +- C: C5F253BD +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T21:45:15Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 7; TODO/FIXME: 0; @Override: 0; methods (approx): 4; constructors: 1; field declarations (w/ modifier): 4 + +> Generates a deterministic, language‑agnostic facts block summarizing exact regex‑based counts from a source file. + +#### Purpose +- Computes exact counts of patterns for AI summaries. +- Prepends facts to AI body for oversize paths. + +#### Type +- `final class AiFactExtractor` + +#### Input +- `List counters` (may be null/empty). +- `String source` (full source text). + +#### Output +- `String` facts block ending with a blank line, or empty string if no counters. + +#### Core logic +- Iterate counters; skip null, missing label/pattern. +- For each valid counter, count non‑overlapping regex matches in `source`. +- Append `label: count` entries separated by `"; "`; prepend header and suffix. + +#### Public API +- `factsBlock(List, String) -> String` – build facts block. +- `validate(List) -> void` – check counters for nulls and valid regexes. + +#### Dependencies +- `java.util.List` +- `java.util.regex.Matcher`, `Pattern`, `PatternSyntaxException` +- `org.jspecify.annotations.Nullable` +- `AiFactCounter` + +#### Exceptions / Errors +- `IllegalArgumentException` if counter label/pattern missing or regex invalid. + +#### Concurrency +- Stateless; thread‑safe. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationConfig.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationConfig.java.ai.md new file mode 100644 index 0000000..b5c36c6 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationConfig.java.ai.md @@ -0,0 +1,72 @@ +### AiFieldGenerationConfig.java +- H: 1.0 +- C: 6D5D78F0 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T21:46:08Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 25; TODO/FIXME: 0; @Override: 0; methods (approx): 19; constructors: 1; field declarations (w/ modifier): 6 + +> Defines a routing rule for AI‑generated field indexing, specifying file selection, model, prompt, priority, and oversize handling. + +#### Purpose +- Encapsulates one routing rule for the `generate` goal. +- Determines file routing, skipping, or fallback behavior. + +#### Type +- Class, mutable JavaBean, Lombok `@ToString`, no explicit modifiers. + +#### Input +- Constructor: no arguments. +- Setter methods: `setId`, `setPromptKey`, `setAiDefinitionKey`, `setCondition`, `setPriority`, `setFallback`, `setSkip`, `setOnOversize`, `setMaxChunks`, `setFacts`, `setFactsKey`. +- Fields: `id`, `promptKey`, `aiDefinitionKey`, `condition`, `priority`, `fallback`, `skip`, `onOversize`, `maxChunks`, `facts`, `factsKey`. + +#### Output +- Getter methods: `getId`, `getPromptKey`, `getAiDefinitionKey`, `getCondition`, `getPriority`, `isFallback`, `isSkip`, `getOnOversize`, `getOversizeStrategy`, `getMaxChunks`, `getFacts`, `getFactsKey`. +- Mutated fields via setters; no other side effects. + +#### Core logic +- Stores configuration for a routing rule. +- Parses `onOversize` token into `AiOversizeStrategy` via `getOversizeStrategy`. +- Exposes all properties through getters and setters for reflection-based population. + +#### Public API +- `getId() -> String?` – returns rule label. +- `setId(String?)` – set rule label. +- `getPromptKey() -> String` – prompt template key. +- `setPromptKey(String)` – set prompt key. +- `getAiDefinitionKey() -> String` – model definition key. +- `setAiDefinitionKey(String)` – set model key. +- `getCondition() -> AiCondition?` – file match condition. +- `setCondition(AiCondition?)` – set condition. +- `getPriority() -> int` – rule priority. +- `setPriority(int)` – set priority. +- `isFallback() -> boolean` – fallback flag. +- `setFallback(boolean)` – set fallback. +- `isSkip() -> boolean` – skip flag. +- `setSkip(boolean)` – set skip. +- `getOnOversize() -> String?` – raw oversize token. +- `setOnOversize(String?)` – set oversize token. +- `getOversizeStrategy() -> AiOversizeStrategy` – parsed strategy. +- `getMaxChunks() -> int` – max map‑reduce chunks. +- `setMaxChunks(int)` – set max chunks. +- `getFacts() -> List?` – deterministic counters. +- `setFacts(List?)` – set counters. +- `getFactsKey() -> String?` – shared facts reference key. +- `setFactsKey(String?)` – set facts key. + +#### Dependencies +- `java.util.List` +- `lombok.ToString` +- `org.jspecify.annotations.Nullable` +- `net.ladenthin.maven.llamacpp.aiindex.config.AiCondition` +- `net.ladenthin.maven.llamacpp.aiindex.config.AiOversizeStrategy` +- `net.ladenthin.maven.llamacpp.aiindex.config.AiFactCounter` + +#### Exceptions / Errors +- `getOversizeStrategy` throws `IllegalArgumentException` if `onOversize` is non‑blank and does not match a known strategy. + +#### Concurrency +- No synchronization; instance is mutable and not thread‑safe. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationSelector.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationSelector.java.ai.md new file mode 100644 index 0000000..a8c8997 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationSelector.java.ai.md @@ -0,0 +1,73 @@ +### AiFieldGenerationSelector.java +- H: 1.0 +- C: 4A116EC6 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T21:48:39Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 4; TODO/FIXME: 0; @Override: 0; methods (approx): 3; constructors: 1; field declarations (w/ modifier): 1 + +> Determines which AI generation rule applies to a file based on its metadata and rule priority. + +#### Purpose +- Chooses the applicable `AiFieldGenerationConfig` for a given file. +- Validates a set of generation rules for consistency. + +#### Type +- final class `AiFieldGenerationSelector` +- No inheritance; contains a single private final field. + +#### Input +- Constructor: no parameters. +- `select(configs, context)`: + - `Iterable configs` – rule set in declaration order; `null` entries ignored. + - `AiFileContext context` – facts about the file to evaluate conditions. +- `validate(configs)`: + - `Iterable configs` – rule set to check. + +#### Output +- `select` returns the winning `AiFieldGenerationConfig` or `null` if no rule applies. +- `validate` throws `IllegalArgumentException` on misconfiguration; otherwise no output. + +#### Core logic +- Iterate through `configs`: + - Skip `null` entries. + - If rule is a fallback, store as `fallback` (first encountered). + - For non‑fallback rules: + - Evaluate `config.getCondition()` with `AiConditionEvaluator`. + - If matches and priority higher than current best, set as `best`. +- Return `best` if found; else return `fallback`. +- `validate`: + - Count fallbacks; enforce at most one. + - For every rule: + - Validate `oversizeStrategy` and `facts` via helper methods. + - If fallback: ensure no `condition`, not a skip, and has route keys. + - If non‑fallback: ensure a condition and that it validates; if not a skip, require route keys. + - Throw `IllegalArgumentException` with descriptive message on any violation. + +#### Public API +- `AiFieldGenerationSelector()` – constructs selector. +- `AiFieldGenerationConfig select(Iterable, AiFileContext) -> AiFieldGenerationConfig` – resolves rule. +- `void validate(Iterable) -> void` – checks rule set consistency. + +#### Dependencies +- `lombok.ToString` +- `org.jspecify.annotations.Nullable` +- `net.ladenthin.maven.llamacpp.aiindex.config.AiConditionEvaluator` +- `net.ladenthin.maven.llamacpp.aiindex.config.AiFieldGenerationConfig` +- `net.ladenthin.maven.llamacpp.aiindex.config.AiFileContext` +- `net.ladenthin.maven.llamacpp.aiindex.config.AiCondition` +- `net.ladenthin.maven.llamacpp.aiindex.config.AiFactExtractor` + +#### Exceptions / Errors +- `IllegalArgumentException` thrown by `validate` for: + - Multiple fallbacks. + - Fallback being a skip or having a condition. + - Missing prompt or AI definition keys. + - Invalid oversize strategy or facts. +- `IllegalArgumentException` from `conditionEvaluator.validate` if condition is malformed. + +#### Concurrency +- Stateless except for immutable `conditionEvaluator`; thread‑safe for concurrent reads. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFileContext.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFileContext.java.ai.md new file mode 100644 index 0000000..4a6d869 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFileContext.java.ai.md @@ -0,0 +1,54 @@ +### AiFileContext.java +- H: 1.0 +- C: ADE292A5 +- D: 2026-06-29T19:51:15Z +- T: 2026-07-02T21:50:07Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 7; TODO/FIXME: 0; @Override: 0; methods (approx): 6; constructors: 1; field declarations (w/ modifier): 5 + +> Immutable snapshot of file metadata for condition evaluation + +#### Purpose +- Holds file facts for AiCondition evaluation. +- Immutable data holder for name, path, size, lines, modified time. + +#### Type +- final class AiFileContext +- @ToString +- No superclass, no interfaces. + +#### Input +- Constructor parameters: `fileName` (String), `relativePath` (String), `sizeBytes` (long), `lineCount` (int), `lastModifiedEpochMilli` (long). + +#### Output +- `fileName()` → String +- `relativePath()` → String +- `sizeBytes()` → long +- `lineCount()` → int +- `lastModifiedEpochMilli()` → long + +#### Core logic +- Store constructor arguments into final fields. +- Provide getter methods returning those fields. +- @ToString automatically generates `toString` representation. + +#### Public API +- `AiFileContext(String fileName, String relativePath, long sizeBytes, int lineCount, long lastModifiedEpochMilli)` → AiFileContext (constructor) +- `fileName()` → String (returns file name) +- `relativePath()` → String (returns relative path) +- `sizeBytes()` → long (returns size in bytes) +- `lineCount()` → int (returns line count) +- `lastModifiedEpochMilli()` → long (returns last-modified epoch milliseconds) + +#### Dependencies +- `lombok.ToString` +- `net.ladenthin.maven.llamacpp.aiindex.config.AiCondition` (via Javadoc reference) + +#### Exceptions / Errors +- None declared; constructor does not validate inputs. + +#### Concurrency +- Immutable; thread‑safe by design. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiGenerationConfig.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiGenerationConfig.java.ai.md new file mode 100644 index 0000000..13a569b --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiGenerationConfig.java.ai.md @@ -0,0 +1,108 @@ +### AiGenerationConfig.java +- H: 1.0 +- C: 2B41382A +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T21:50:54Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 86; TODO/FIXME: 0; @Override: 0; methods (approx): 57; constructors: 1; field declarations (w/ modifier): 54 + +> Holds AI generation parameters (model path, sampling, prompt limits, GPU settings) passed between Maven configuration and AI provider. + +#### Purpose +* Mutable JavaBean for AI inference settings. +* Transports configuration from Maven plugin to provider implementations. + +#### Type +Class, final Lombok @ToString, mutable, no inheritance. + +#### Input +* Constructor: no arguments. +* Setter methods: all fields. +* Injected via Maven plugin framework. +* Optional `AiCalibration` instance. + +#### Output +* Getter methods expose all fields. +* `getDrySequenceBreakers` & `getStopStrings` return unmodifiable lists. +* `isCachePrompt`, `isSwaFull`, etc. expose boolean flags. + +#### Core logic +* Stores primitive and string configuration values. +* Provides defensive copying for list getters. +* Handles `null` for optional fields (`AiCalibration`, list setters). +* No additional computation beyond storing and retrieving values. + +#### Public API +* `String getModelPath() -> model file path` +* `void setModelPath(String) -> set model path` +* `int getContextSize() -> context window size` +* `void setContextSize(int) -> set context size` +* `int getMaxOutputTokens() -> max output tokens` +* `void setMaxOutputTokens(int) -> set max output` +* `float getTemperature() -> sampling temperature` +* `void setTemperature(float) -> set temperature` +* `int getThreads() -> CPU thread count` +* `void setThreads(int) -> set thread count` +* `int getCharsPerToken() -> chars per token` +* `void setCharsPerToken(int) -> set ratio` +* `int getMaxInputChars() -> max input chars` +* `void setMaxInputChars(int) -> set max input` +* `boolean isWarnOnTrim() -> trim warning flag` +* `void setWarnOnTrim(boolean) -> set trim warning` +* `float getTopP() -> nucleus threshold` +* `void setTopP(float) -> set top‑p` +* `int getTopK() -> top‑k limit` +* `void setTopK(int) -> set top‑k` +* `float getRepeatPenalty() -> repetition penalty` +* `void setRepeatPenalty(float) -> set repeat penalty` +* `float getMinP() -> min‑p threshold` +* `void setMinP(float) -> set min‑p` +* `float getTopNSigma() -> top‑sigma threshold` +* `void setTopNSigma(float) -> set top‑sigma` +* `boolean isChatTemplateEnableThinking() -> chat‑template flag` +* `void setChatTemplateEnableThinking(boolean) -> set flag` +* `boolean isCachePrompt() -> prompt cache flag` +* `boolean isSwaFull() -> full‑SWA flag` +* `void setSwaFull(boolean) -> set full‑SWA` +* `int getCacheReuse() -> prefix reuse size` +* `void setCacheReuse(int) -> set reuse size` +* `int getGpuLayers() -> GPU layer count` +* `void setGpuLayers(int) -> set GPU layers` +* `int getMainGpu() -> primary GPU index` +* `void setMainGpu(int) -> set primary GPU` +* `String getDevices() -> device list` +* `void setDevices(String) -> set device list` +* `void setCachePrompt(boolean) -> set prompt cache` +* `String getReasoningEffort() -> reasoning effort` +* `void setReasoningEffort(String) -> set effort` +* `int getReasoningBudgetTokens() -> reasoning budget` +* `void setReasoningBudgetTokens(int) -> set budget` +* `float getDryMultiplier() -> DRY multiplier` +* `void setDryMultiplier(float) -> set multiplier` +* `float getDryBase() -> DRY base` +* `void setDryBase(float) -> set base` +* `int getDryAllowedLength() -> DRY allowed length` +* `void setDryAllowedLength(int) -> set length` +* `int getDryPenaltyLastN() -> DRY penalty window` +* `void setDryPenaltyLastN(int) -> set window` +* `List getDrySequenceBreakers() -> unmodifiable breakers` +* `void setDrySequenceBreakers(List) -> set breakers` +* `List getStopStrings() -> unmodifiable stops` +* `void setStopStrings(List) -> set stops` +* `AiCalibration getCalibration() -> calibration` +* `void setCalibration(AiCalibration) -> set calibration` + +#### Dependencies +* `java.util.ArrayList`, `java.util.Collections`, `java.util.List` +* `lombok.ToString` +* `org.jspecify.annotations.Nullable` +* `AiCalibration` + +#### Exceptions / Errors +* No exceptions thrown; setters accept null for optional fields. + +#### Concurrency +* All fields are mutable; no synchronization. Intended for single‑threaded Maven configuration usage. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiGenerationKind.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiGenerationKind.java.ai.md new file mode 100644 index 0000000..1981448 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiGenerationKind.java.ai.md @@ -0,0 +1,42 @@ +### AiGenerationKind.java +- H: 1.0 +- C: 502093E2 +- D: 2026-06-25T05:31:58Z +- T: 2026-07-02T21:56:45Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 1; TODO/FIXME: 0; @Override: 0; methods (approx): 0; constructors: 0; field declarations (w/ modifier): 0 + +> Enumerates whether AI generation targets a single source file or an entire package. + +#### Purpose +- Defines AI generation scope for summarization steps. + +#### Type +- `enum` AiGenerationKind; public. + +#### Input +- None. + +#### Output +- None. + +#### Core logic +- Provides two constants: + - `FILE_SUMMARY` for file‑level generation. + - `PACKAGE_SUMMARY` for package‑level generation. + +#### Public API +- `FILE_SUMMARY -> single‑file generation` +- `PACKAGE_SUMMARY -> package‑level generation` + +#### Dependencies +- Java language enum. + +#### Exceptions / Errors +- None. + +#### Concurrency +- Immutable enum constants. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinition.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinition.java.ai.md new file mode 100644 index 0000000..9271a78 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinition.java.ai.md @@ -0,0 +1,107 @@ +### AiModelDefinition.java +- H: 1.0 +- C: 7AF67E46 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T21:57:02Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 60; TODO/FIXME: 0; @Override: 0; methods (approx): 56; constructors: 1; field declarations (w/ modifier): 26 + +> A Maven plugin configuration POJO that defines a named set of AI model parameters for reuse across field‑generation goals. + +#### Purpose +- Holds AI model configuration for Maven goals. +- Enables reuse of a single model definition by key. + +#### Type +- Class, mutable JavaBean, no annotations except `@ToString`. + +#### Input +- Constructor: default. +- Setters: `setKey`, `setModelPath`, `setContextSize`, `setMaxOutputTokens`, `setTemperature`, `setThreads`, `setCharsPerToken`, `setWarnOnTrim`, `setTopP`, `setTopK`, `setRepeatPenalty`, `setMinP`, `setTopNSigma`, `setChatTemplateEnableThinking`, `setCachePrompt`, `setSwaFull`, `setCacheReuse`, `setGpuLayers`, `setMainGpu`, `setDevices`, `setReasoningEffort`, `setReasoningBudgetTokens`, `setDryMultiplier`, `setDryBase`, `setDryAllowedLength`, `setDryPenaltyLastN`, `setDrySequenceBreakers`, `setStopStrings`, `setCalibration`. + +#### Output +- Getters: `getKey`, `getModelPath`, `getContextSize`, `getMaxOutputTokens`, `getTemperature`, `getThreads`, `getCharsPerToken`, `isWarnOnTrim`, `getTopP`, `getTopK`, `getRepeatPenalty`, `getMinP`, `getTopNSigma`, `isChatTemplateEnableThinking`, `isCachePrompt`, `isSwaFull`, `getCacheReuse`, `getGpuLayers`, `getMainGpu`, `getDevices`, `getReasoningEffort`, `getReasoningBudgetTokens`, `getDryMultiplier`, `getDryBase`, `getDryAllowedLength`, `getDryPenaltyLastN`, `getDrySequenceBreakers`, `getStopStrings`, `getCalibration`. + +#### Core logic +- Holds primitive and object fields with default values from `AiGenerationConfig`. +- Provides standard getters and setters for all fields. +- Defensive copying for mutable list fields (`drySequenceBreakers`, `stopStrings`). +- `setDevices` normalises null to default. +- `getDrySequenceBreakers`/`getStopStrings` return unmodifiable views if set. + +#### Public API +- `AiModelDefinition() -> void` (constructor) +- `setKey(String) -> void` (store lookup key) +- `setModelPath(String) -> void` (store GGUF path) +- `setContextSize(int) -> void` (context window) +- `setMaxOutputTokens(int) -> void` (max output) +- `setTemperature(float) -> void` (sampling temperature) +- `setThreads(int) -> void` (CPU threads) +- `setCharsPerToken(int) -> void` (chars per token) +- `setWarnOnTrim(boolean) -> void` (trim warning) +- `setTopP(float) -> void` (nucleus threshold) +- `setTopK(int) -> void` (top‑k limit) +- `setRepeatPenalty(float) -> void` (repetition penalty) +- `setMinP(float) -> void` (min‑p threshold) +- `setTopNSigma(float) -> void` (top‑n‑sigma threshold) +- `setChatTemplateEnableThinking(boolean) -> void` (chat‑template thinking) +- `setCachePrompt(boolean) -> void` (prompt cache) +- `setSwaFull(boolean) -> void` (full‑size SWA) +- `setCacheReuse(int) -> void` (KV reuse chunk) +- `setGpuLayers(int) -> void` (GPU layer offload) +- `setMainGpu(int) -> void` (primary GPU) +- `setDevices(String) -> void` (device list) +- `setReasoningEffort(String) -> void` (reasoning level) +- `setReasoningBudgetTokens(int) -> void` (thinking budget) +- `setDryMultiplier(float) -> void` (DRY multiplier) +- `setDryBase(float) -> void` (DRY base) +- `setDryAllowedLength(int) -> void` (DRY allowed length) +- `setDryPenaltyLastN(int) -> void` (DRY penalty window) +- `setDrySequenceBreakers(Collection) -> void` (DRY breakers) +- `setStopStrings(Collection) -> void` (stop strings) +- `setCalibration(AiCalibration) -> void` (timing calibration) +- `getKey() -> String` (lookup key) +- `getModelPath() -> String` (model path) +- `getContextSize() -> int` (context) +- `getMaxOutputTokens() -> int` (max output) +- `getTemperature() -> float` (temperature) +- `getThreads() -> int` (threads) +- `getCharsPerToken() -> int` (chars per token) +- `isWarnOnTrim() -> boolean` (trim warning flag) +- `getTopP() -> float` (top‑p) +- `getTopK() -> int` (top‑k) +- `getRepeatPenalty() -> float` (repeat penalty) +- `getMinP() -> float` (min‑p) +- `getTopNSigma() -> float` (top‑n‑sigma) +- `isChatTemplateEnableThinking() -> boolean` (chat‑template flag) +- `isCachePrompt() -> boolean` (prompt cache flag) +- `isSwaFull() -> boolean` (SWA full flag) +- `getCacheReuse() -> int` (cache reuse) +- `getGpuLayers() -> int` (GPU layers) +- `getMainGpu() -> int` (main GPU) +- `getDevices() -> String` (device list) +- `getReasoningEffort() -> String` (reasoning level) +- `getReasoningBudgetTokens() -> int` (budget) +- `getDryMultiplier() -> float` (DRY multiplier) +- `getDryBase() -> float` (DRY base) +- `getDryAllowedLength() -> int` (DRY allowed length) +- `getDryPenaltyLastN() -> int` (DRY penalty) +- `getDrySequenceBreakers() -> List` (unmodifiable) +- `getStopStrings() -> List` (unmodifiable) +- `getCalibration() -> AiCalibration` (timing calibration) + +#### Dependencies +- `java.util.*` (ArrayList, Collection, List, Collections) +- `lombok.ToString` +- `org.jspecify.annotations.Nullable` +- `net.ladenthin.maven.llamacpp.aiindex.config.AiGenerationConfig` +- `net.ladenthin.maven.llamacpp.aiindex.config.AiCalibration` + +#### Exceptions / Errors +- No checked exceptions thrown; setters accept null for optional fields. + +#### Concurrency +- No synchronization; instance is mutable and intended for single‑thread configuration usage. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinitionSupport.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinitionSupport.java.ai.md new file mode 100644 index 0000000..83ea83a --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinitionSupport.java.ai.md @@ -0,0 +1,59 @@ +### AiModelDefinitionSupport.java +- H: 1.0 +- C: 05A1DA33 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:02:16Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 3; TODO/FIXME: 0; @Override: 0; methods (approx): 3; constructors: 1; field declarations (w/ modifier): 3 + +> Builds a lookup table that maps AI model definition keys to ready‑to‑use generation configurations for Maven LlamaCPP plugin. + +#### Purpose +- Provides configuration lookup for AI model definitions. +- Validates definitions at construction time. + +#### Type +- `final class AiModelDefinitionSupport` +- Implements no interfaces or inheritance. +- Annotated with `@ToString`. + +#### Input +- Constructor receives `List definitions` (may be `null`). +- Reads each `AiModelDefinition`’s `key` and other fields. +- Uses `Java8CompatibilityHelper` to pre‑size internal `HashMap`. + +#### Output +- Stores `Map configs`. +- `getConfig(key)` returns the corresponding `AiGenerationConfig`. + +#### Core logic +- If `definitions` is `null` → create empty `configs`. +- Else: + - Pre‑size `configs` based on list size. + - Iterate list, enforce non‑null `key` with `Objects.requireNonNull`. + - Convert each definition to an `AiGenerationConfig` via `toConfig` and put into `configs`. +- `getConfig(key)` retrieves config or throws `IllegalArgumentException` with message prefix. +- `toConfig` copies all fields from `AiModelDefinition` to a new `AiGenerationConfig`. + +#### Public API +- `AiModelDefinitionSupport(List) -> AiModelDefinitionSupport` + *Constructs definition lookup table.* +- `AiGenerationConfig getConfig(String) -> AiGenerationConfig` + *Retrieves config by key.* + +#### Dependencies +- `java.util.HashMap`, `java.util.List`, `java.util.Map`, `java.util.Objects`. +- `lombok.ToString`. +- `net.ladenthin.maven.llamacpp.aiindex.support.Java8CompatibilityHelper`. +- `net.ladenthin.maven.llamacpp.aiindex.config.AiModelDefinition`. +- `net.ladenthin.maven.llamacpp.aiindex.config.AiGenerationConfig`. + +#### Exceptions / Errors +- `NullPointerException` if any definition has a `null` key. +- `IllegalArgumentException` if `getConfig` receives an unknown key. + +#### Concurrency +- Instance is immutable after construction; thread‑safe for concurrent reads. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiOversizeStrategy.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiOversizeStrategy.java.ai.md new file mode 100644 index 0000000..d8e477e --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiOversizeStrategy.java.ai.md @@ -0,0 +1,49 @@ +### AiOversizeStrategy.java +- H: 1.0 +- C: C8604282 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:03:53Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 4; TODO/FIXME: 0; @Override: 0; methods (approx): 2; constructors: 1; field declarations (w/ modifier): 2 + +> Defines how to handle source files exceeding the context window of the selected model. + +#### Purpose +- Configures oversized‑file handling per routing rule. +- Provides default and alternative strategies (fail, sample, map‑reduce, deterministic). + +#### Type +- `enum` with `public` visibility, no modifiers. +- Constants: `FAIL`, `SAMPLE`, `MAP_REDUCE`, `DETERMINISTIC`. +- Field: `private final String configValue`. +- Static field: `public static final AiOversizeStrategy DEFAULT`. +- Annotated with `@Nullable` for `fromConfig` parameter. + +#### Input +- Constructor: `AiOversizeStrategy(String configValue)` receives the config token. +- Method `fromConfig(@Nullable String value)` accepts a config string (may be null or blank). + +#### Output +- `configValue()` returns the token string. +- `fromConfig()` returns the matching enum or throws `IllegalArgumentException`. + +#### Core logic +- `fromConfig()` trims input; null or empty yields `DEFAULT`. +- Iterates over `values()`; case‑insensitive match on `configValue`. +- Throws exception if no match. + +#### Public API +- `configValue() -> String` – return the strategy’s config token. +- `fromConfig(String) -> AiOversizeStrategy` – parse config token, default or error. + +#### Dependencies +- `org.jspecify.annotations.Nullable`. + +#### Exceptions / Errors +- `IllegalArgumentException` in `fromConfig` when value is non‑blank and unmatched. + +#### Concurrency +- Immutable enum; thread‑safe. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiRangeCondition.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiRangeCondition.java.ai.md new file mode 100644 index 0000000..75abad3 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiRangeCondition.java.ai.md @@ -0,0 +1,59 @@ +### AiRangeCondition.java +- H: 1.0 +- C: 694E254D +- D: 2026-06-29T19:51:15Z +- T: 2026-07-02T22:04:44Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 8; TODO/FIXME: 0; @Override: 0; methods (approx): 7; constructors: 1; field declarations (w/ modifier): 2 + +> A numeric range definition used by the Maven plugin to filter files by size or line count. + +#### Purpose +- Represents a leaf condition for numeric ranges in `AiCondition`. +- Supports exclusive lower and inclusive upper bounds. +- Serves as a mutable JavaBean for Maven configuration. + +#### Type +Class, public, not abstract or sealed. +Lombok `@ToString` annotation. + +#### Input +- Constructor: no parameters. +- `setMin(long)` and `setMax(long)` set the bounds. +- `contains(long)` checks a value against the bounds. + +#### Output +- `getMin()` and `getMax()` return the configured bounds. +- `contains(long)` returns `true` if a value is within the range. +- `hasBound()` indicates if any bound is active. +- Lombok-generated `toString()` provides a textual representation. + +#### Core logic +- `contains(long)`: + 1. If `min > 0` and `value <= min` → false. + 2. If `max > 0` and `value > max` → false. + 3. Otherwise → true. +- `hasBound()` returns true when `min > 0` or `max > 0`. + +#### Public API +- `AiRangeCondition()` → construct an empty range. +- `long getMin()` → get exclusive lower bound. +- `void setMin(long)` → set exclusive lower bound. +- `long getMax()` → get inclusive upper bound. +- `void setMax(long)` → set inclusive upper bound. +- `boolean contains(long)` → test value against range. +- `boolean hasBound()` → check if range is usable. + +#### Dependencies +- `lombok.ToString`. + +#### Exceptions / Errors +- No explicit exceptions thrown. +- Methods assume non-null primitive types; no null checks needed. + +#### Concurrency +- No synchronization; mutable state is not thread‑safe. +- Designed for single‑thread use within Maven configuration. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/package.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/package.ai.md new file mode 100644 index 0000000..ced59e9 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/config/package.ai.md @@ -0,0 +1,75 @@ +### main/java/net/ladenthin/maven/llamacpp/aiindex/config +- H: 1.0 +- C: C16C9ACE +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:14:19Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: package +- F: [AiCalibration.java](AiCalibration.java.ai.md) +- F: [AiCondition.java](AiCondition.java.ai.md) +- F: [AiConditionEvaluator.java](AiConditionEvaluator.java.ai.md) +- F: [AiConditionGroup.java](AiConditionGroup.java.ai.md) +- F: [AiFactCounter.java](AiFactCounter.java.ai.md) +- F: [AiFactDefinition.java](AiFactDefinition.java.ai.md) +- F: [AiFactDefinitionSupport.java](AiFactDefinitionSupport.java.ai.md) +- F: [AiFactExtractor.java](AiFactExtractor.java.ai.md) +- F: [AiFieldGenerationConfig.java](AiFieldGenerationConfig.java.ai.md) +- F: [AiFieldGenerationSelector.java](AiFieldGenerationSelector.java.ai.md) +- F: [AiFileContext.java](AiFileContext.java.ai.md) +- F: [AiGenerationConfig.java](AiGenerationConfig.java.ai.md) +- F: [AiGenerationKind.java](AiGenerationKind.java.ai.md) +- F: [AiModelDefinition.java](AiModelDefinition.java.ai.md) +- F: [AiModelDefinitionSupport.java](AiModelDefinitionSupport.java.ai.md) +- F: [AiOversizeStrategy.java](AiOversizeStrategy.java.ai.md) +- F: [AiRangeCondition.java](AiRangeCondition.java.ai.md) +--- +> A Maven plugin configuration library that models AI‑generation rules, file‑matching conditions, fact extraction, and runtime AI settings for the LlamaCPP indexer. + +#### Purpose +- Store and validate AI‑generation routing rules and model configurations. +- Provide immutable file metadata and condition evaluators for rule selection. +- Generate deterministic fact blocks from source files for AI prompts. + +#### Responsibilities +- **Configuration POJOs** – `AiFieldGenerationConfig`, `AiCondition`, `AiFactDefinition`, `AiModelDefinition`, `AiGenerationConfig`, `AiCalibration`. +- **Condition logic** – `AiConditionEvaluator`, `AiConditionGroup`, `AiRangeCondition`, `AiOversizeStrategy`. +- **Fact handling** – `AiFactCounter`, `AiFactExtractor`, `AiFactDefinitionSupport`. +- **Rule selection** – `AiFieldGenerationSelector`. +- **Support utilities** – `AiFileContext`, `AiGenerationKind`, `AiModelDefinitionSupport`. + +#### Key units +- **`AiFieldGenerationConfig`** – routing rule: condition, model key, prompt key, priority, fallback/skip flags, oversize strategy, fact counters. +- **`AiCondition` / `AiConditionGroup` / `AiRangeCondition`** – tree of file‑matching predicates (extensions, size, lines, dates, path glob). +- **`AiConditionEvaluator`** – validates condition trees, tests file matches, detects line‑usage. +- **`AiFactExtractor`** – builds deterministic `label: count` blocks from regex counters. +- **`AiFactDefinitionSupport`** – resolves shared fact counter groups into rule configs. +- **`AiModelDefinitionSupport`** – maps model keys to fully‑configured `AiGenerationConfig` instances. +- **`AiGenerationConfig` / `AiCalibration`** – AI inference parameters and timing calibration. +- **`AiFieldGenerationSelector`** – picks the best rule for a file, enforces fallback semantics. + +#### Data flow +1. **Configuration phase** + - Maven reads XML into **`AiFieldGenerationConfig`**, **`AiFactDefinition`**, **`AiModelDefinition`** objects. + - `AiFactDefinitionSupport` injects fact counters into each rule. + - `AiModelDefinitionSupport` converts model definitions into ready‑to‑use `AiGenerationConfig` instances. + +2. **Runtime phase** + - `AiFileContext` is created per source file (name, path, size, lines, modified time). + - `AiFieldGenerationSelector` iterates rules, using `AiConditionEvaluator` to test matches and determine the applicable rule. + - If a rule requires facts, `AiFactExtractor` generates the fact block from the file content. + - The selected rule’s `AiGenerationConfig` (including `AiCalibration`) drives the LlamaCPP inference engine. + +#### Dependencies +- Lombok (`@ToString`) for concise POJOs. +- `org.jspecify.annotations.Nullable` for optional fields. +- `java.time` for date parsing in conditions. +- `java.util.regex` in fact extraction. +- Internal support: `AiSourceExcludeFilter`, `Java8CompatibilityHelper`. +- External: Maven plugin framework (not shown) for configuration binding. + +#### Cross‑cutting +- All configuration classes are plain JavaBeans with getters/setters, enabling Maven’s XML‑to‑object binding. +- Validation is centralized in `AiConditionEvaluator` and `AiFieldGenerationSelector`. +- Immutable value objects (`AiFileContext`, enums) ensure thread safety during rule evaluation. +- Mutable runtime objects (`AiGenerationConfig`, `AiCalibration`) are used only in single‑threaded plugin execution. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/package.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/package.ai.md new file mode 100644 index 0000000..80d0e6b --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/package.ai.md @@ -0,0 +1,57 @@ +### main/java/net/ladenthin/maven/llamacpp/aiindex +- H: 1.0 +- C: E77032F7 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:24:45Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: package +- F: [config/](config/package.ai.md) +- F: [provider/](provider/package.ai.md) +--- +> A Maven plugin that indexes source files for AI‑generation, routing each file to a suitable LlamaCPP model based on declarative rules and extracting deterministic facts to drive prompt construction. + +#### Purpose +- Parse Maven configuration into AI‑generation rules, facts, and model settings. +- Evaluate source files against these rules to select a LlamaCPP provider. +- Invoke the provider, capture timing metrics, and return cleaned AI completions. + +#### Responsibilities +- **Configuration handling** – read and validate XML into immutable POJOs (`AiFieldGenerationConfig`, `AiFactDefinition`, `AiModelDefinition`). +- **Rule evaluation** – match files to rules using predicate trees (`AiCondition`, `AiRangeCondition`) and selector logic (`AiFieldGenerationSelector`). +- **Fact extraction** – generate deterministic `label: count` blocks from source content (`AiFactExtractor`). +- **Provider orchestration** – instantiate the correct AI backend (`AiGenerationProviderFactory`) and expose a uniform generation API. +- **JNI integration** – load and run a GGUF model via `LlamaCppJniAiGenerationProvider`, parse raw completions, and record per‑token throughput. +- **Mocking & calibration** – provide a deterministic mock provider for tests and expose timing data (`AiGenerationTimings`) for calibration. + +#### Key units +- **`AiFieldGenerationConfig`** – rule definition: condition, model key, prompt key, priority, fallbacks, oversize strategy, fact counters. +- **`AiConditionEvaluator`** – validates and evaluates condition trees against `AiFileContext`. +- **`AiFactExtractor`** – produces fact blocks from regex counters in a file. +- **`AiModelDefinitionSupport`** – maps model keys to fully‑configured `AiGenerationConfig`. +- **`AiGenerationProviderFactory`** – builds `AiGenerationProvider` instances (`mock`, `llamacpp-jni`). +- **`LlamaCppJniAiGenerationProvider`** – JNI‑backed provider that loads `LlamaModel`, runs `chatCompleteText`, and parses responses. +- **`MockAiGenerationProvider`** – deterministic summary generator with synthetic timings. +- **`AiCompletionParser`** – removes internal chain‑of‑thought blocks from Gemma‑4 completions. +- **`AiGenerationTimings`** – immutable holder of generated text, token counts, and throughput metrics. + +#### Data flow +1. **Configuration**: Maven XML → `AiFieldGenerationConfig`, `AiFactDefinition`, `AiModelDefinition`. +2. **Setup**: `AiFactDefinitionSupport` injects fact counters into rules; `AiModelDefinitionSupport` creates `AiGenerationConfig` instances. +3. **Runtime**: For each source file, + - Build `AiFileContext`. + - `AiFieldGenerationSelector` uses `AiConditionEvaluator` to pick the best rule. + - If facts are needed, `AiFactExtractor` generates the fact block. + - `AiGenerationProviderFactory` supplies the appropriate provider. + - Provider runs inference, `AiCompletionParser` cleans the output, and `AiGenerationTimings` records metrics. +4. **Result**: Cleaned AI completion returned to the plugin; timings optionally used for calibration. + +#### Dependencies +- **Internal**: `AiPromptSupport`, `Java8CompatibilityHelper`, `ConvertToRecord`, Lombok (`@ToString`), `org.jspecify.annotations.Nullable`. +- **External**: Maven plugin framework, native `net.ladenthin.llama` bindings (`LlamaModel`, `InferenceParameters`, `ChatResponseParser`), Java standard libraries (`java.time`, `java.util.regex`, `java.nio.file.Path`). + +#### Cross-cutting +- **Immutability & thread safety** – configuration POJOs and timing records are immutable; provider factories are stateless. +- **Validation & error handling** – centralized in `AiConditionEvaluator` and `AiFieldGenerationSelector`; `AiCompletionParser` throws `IOException` for malformed responses. +- **Configuration normalization** – `LlamaCppJniConfig` turns nullable lists into immutable empty lists; all fields are final. +- **Consistent response parsing** – `AiCompletionParser` ensures all providers return the same cleaned text format. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiCompletionParser.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiCompletionParser.java.ai.md new file mode 100644 index 0000000..e0a75f7 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiCompletionParser.java.ai.md @@ -0,0 +1,49 @@ +### AiCompletionParser.java +- H: 1.0 +- C: 78BEBEB3 +- D: 2026-06-25T05:31:58Z +- T: 2026-07-02T22:05:38Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 5; TODO/FIXME: 0; @Override: 0; methods (approx): 2; constructors: 1; field declarations (w/ modifier): 2 + +> Extracts the final answer from a Gemma‑4 LLM response by removing any internal chain‑of‑thought block. + +#### Purpose +- Parses raw LLM completion text. +- Strips internal reasoning blocks before persisting answers. + +#### Type +- Class `AiCompletionParser`, non‑final, public. +- Annotated `@ToString`. + +#### Input +- `parseCompletion(String response)`: raw completion text, may be `null`. +- Constructor requires no arguments. + +#### Output +- Returns a non‑null trimmed string containing only the final answer. +- May throw `IOException` if a thinking block is incomplete. + +#### Core logic +- If `response` is `null`, return empty string. +- Find last index of `THINKING_BLOCK_END_MARKER`. + - If found, return substring after marker, trimmed. +- If no end marker but start marker present, throw `IOException` with explanatory message. +- Otherwise, return trimmed original response. + +#### Public API +- `AiCompletionParser() -> no-op constructor` +- `parseCompletion(String) -> String` – parse and clean response + +#### Dependencies +- `java.io.IOException` +- `lombok.ToString` + +#### Exceptions / Errors +- Throws `IOException` when a thinking block starts but does not close. + +#### Concurrency +- Stateless; thread‑safe for concurrent use. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationProvider.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationProvider.java.ai.md new file mode 100644 index 0000000..cdf34f8 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationProvider.java.ai.md @@ -0,0 +1,49 @@ +### AiGenerationProvider.java +- H: 1.0 +- C: 14BD5D6E +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:06:25Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 1; TODO/FIXME: 0; @Override: 1; methods (approx): 3; constructors: 0; field declarations (w/ modifier): 0 + +> Provides an AI backend for generating text from a prompt request, optionally returning timing data. + +#### Purpose +- Interface for pluggable AI generation backends. +- Supports local models (llama.cpp) or test mocks. + +#### Type +- `interface` `AiGenerationProvider` with `AutoCloseable` supertype. + +#### Input +- `generate(AiGenerationRequest request)` receives a request containing prompt key, source file, source text, and current header. +- `generateWithTimings(AiGenerationRequest request)` same input. + +#### Output +- `generate` returns non‑null generated text (may be blank). +- `generateWithTimings` returns an `AiGenerationTimings` instance containing text and timing metrics (default rates 0). +- `close` performs no action by default. + +#### Core logic +- `generate`: abstract; implementations provide text generation logic. +- `generateWithTimings`: default implementation calls `generate`, wraps result in `AiGenerationTimings` with zeroed metrics; overrideable by providers exposing real timings. +- `close`: default empty implementation; allows resources to be released if needed. + +#### Public API +- `generate(AiGenerationRequest request) -> String` generates text for the request. +- `generateWithTimings(AiGenerationRequest request) -> AiGenerationTimings` generates text with timing data. +- `close() -> void` closes provider resources. + +#### Dependencies +- `java.io.IOException` +- `net.ladenthin.maven.llamacpp.aiindex.document.AiGenerationRequest` +- `net.ladenthin.maven.llamacpp.aiindex.document.AiGenerationTimings` + +#### Exceptions / Errors +- `generate` and `generateWithTimings` throw `IOException` if the underlying provider fails. + +#### Concurrency +- No explicit thread‑safety guarantees; providers may be stateful. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationProviderFactory.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationProviderFactory.java.ai.md new file mode 100644 index 0000000..56e976d --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationProviderFactory.java.ai.md @@ -0,0 +1,57 @@ +### AiGenerationProviderFactory.java +- H: 1.0 +- C: 0ADDB961 +- D: 2026-06-25T05:31:58Z +- T: 2026-07-02T22:07:09Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 3; TODO/FIXME: 0; @Override: 0; methods (approx): 2; constructors: 1; field declarations (w/ modifier): 1 + +> Instantiates AI generation providers based on a string key, defaulting to a mock implementation. + +#### Purpose +- Supplies an `AiGenerationProvider` instance for a given provider name. +- Handles defaulting, validation, and provider-specific construction. + +#### Type +- Class, final (implicitly), no inheritance. +- Annotated with `@ToString`. +- Declares a private final field `compatibilityHelper` of type `Java8CompatibilityHelper`. + +#### Input +- `create(String providerName, LlamaCppJniConfig llamaConfig, AiPromptSupport promptSupport)` + - `providerName`: key string (`"mock"` or `"llamacpp-jni"`). + - `llamaConfig`: configuration for the JNI provider. + - `promptSupport`: lookup support for providers that need it. + +#### Output +- Returns a new `AiGenerationProvider` instance. +- Throws `IllegalArgumentException` for unsupported provider names. + +#### Core logic +- If `providerName` is null or blank (checked via `compatibilityHelper.isBlank`), return `MockAiGenerationProvider`. +- Switch on `providerName`: + - `"mock"` → `MockAiGenerationProvider`. + - `"llamacpp-jni"` → `LlamaCppJniAiGenerationProvider(llamaConfig, promptSupport)`. + - Default → throw `IllegalArgumentException("Unsupported AI provider: " + providerName)`. + +#### Public API +- `AiGenerationProviderFactory()` → constructor, no parameters. +- `create(String providerName, LlamaCppJniConfig llamaConfig, AiPromptSupport promptSupport) -> AiGenerationProvider` – builds provider by name. + +#### Dependencies +- `lombok.ToString` +- `net.ladenthin.maven.llamacpp.aiindex.prompt.AiPromptSupport` +- `net.ladenthin.maven.llamacpp.aiindex.support.Java8CompatibilityHelper` +- `net.ladenthin.maven.llamacpp.aiindex.provider.MockAiGenerationProvider` +- `net.ladenthin.maven.llamacpp.aiindex.provider.LlamaCppJniAiGenerationProvider` +- `net.ladenthin.maven.llamacpp.aiindex.provider.LlamaCppJniConfig` (assumed from context) + +#### Exceptions / Errors +- Throws `IllegalArgumentException` when `providerName` is unrecognized. + +#### Concurrency +- No explicit synchronization; instances are stateless except for the single helper field. +- Thread‑safe by default. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationTimings.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationTimings.java.ai.md new file mode 100644 index 0000000..79667c0 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationTimings.java.ai.md @@ -0,0 +1,55 @@ +### AiGenerationTimings.java +- H: 1.0 +- C: 1D58E849 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:08:07Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 7; TODO/FIXME: 0; @Override: 0; methods (approx): 6; constructors: 1; field declarations (w/ modifier): 5 + +> Records generation text and per‑token timing for AI model calibration. + +#### Purpose +- Holds a generated text and timing metrics for calibration. +- Supplies data to `ai-index:calibrate` goal. + +#### Type +- `final class AiGenerationTimings` +- Implements `ConvertToRecord`, `ToString`, `EqualsAndHashCode` via Lombok. + +#### Input +- Constructor parameters: + - `String text` + - `int promptTokens` + - `double prefillTokensPerSecond` + - `int predictedTokens` + - `double decodeTokensPerSecond` + +#### Output +- Accessor methods returning the stored fields. +- `toString()`, `equals()`, `hashCode()` via Lombok. + +#### Core logic +- Stores supplied values in final fields. +- Provides simple getters that return those values. + +#### Public API +- `AiGenerationTimings(String, int, double, int, double)` – construct instance with timing data +- `String text()` – return generated text +- `int promptTokens()` – return prompt token count +- `double prefillTokensPerSecond()` – return prefill throughput +- `int predictedTokens()` – return predicted token count +- `double decodeTokensPerSecond()` – return decode throughput + +#### Dependencies +- `lombok.EqualsAndHashCode` +- `lombok.ToString` +- `net.ladenthin.maven.llamacpp.aiindex.support.ConvertToRecord` + +#### Exceptions / Errors +- None declared; constructor accepts any values. + +#### Concurrency +- Immutable after construction; thread‑safe. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/LlamaCppJniAiGenerationProvider.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/LlamaCppJniAiGenerationProvider.java.ai.md new file mode 100644 index 0000000..f9b553e --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/LlamaCppJniAiGenerationProvider.java.ai.md @@ -0,0 +1,56 @@ +### LlamaCppJniAiGenerationProvider.java +- H: 1.0 +- C: 3EAED1F5 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:08:54Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 5; TODO/FIXME: 0; @Override: 3; methods (approx): 6; constructors: 1; field declarations (w/ modifier): 9 + +> Provides local AI generation by loading a GGUF model via llama.cpp and generating text or timing information from an `AiGenerationRequest`. + +#### Purpose +- Implements `AiGenerationProvider` for local generation. +- Offers generation with or without timing data. + +#### Type +- Final class `LlamaCppJniAiGenerationProvider` implements `AiGenerationProvider`, `AutoCloseable`. +- Extends `Object`; no generics. +- Annotated with Lombok `@ToString`. + +#### Input +- Constructor parameters: `LlamaCppJniConfig config`, `AiPromptSupport promptSupport`. +- `generate(AiGenerationRequest)` and `generateWithTimings(AiGenerationRequest)` consume an `AiGenerationRequest` (prompt key, source file, source text). +- Reads configuration fields (temperature, max tokens, etc.) and prompt templates via `promptSupport`. + +#### Output +- `generate` returns a `String` (completion text). +- `generateWithTimings` returns `AiGenerationTimings` (text plus token counts and rates). +- `close` releases the native `LlamaModel` resource. + +#### Core logic +- Lazy‑loads `LlamaModel` on first generation; configures model parameters (model path, context, threads, GPU options, SWA, cache reuse, reasoning format, chat‑template kwargs). +- Builds `InferenceParameters` from request and config: system prompt, user message, chat template, temperature, token limits, sampling, repetition penalties, dry settings, stop strings, cache prompt, reuse slot. +- Executes `model().chatCompleteText` or `model().chatComplete` and parses the response via `AiCompletionParser` or `ChatResponseParser`. +- Extracts timings from the parsed `ChatResponse` and creates `AiGenerationTimings`. + +#### Public API +- `generate(AiGenerationRequest request) -> String` – produces completion text. +- `generateWithTimings(AiGenerationRequest request) -> AiGenerationTimings` – produces completion text with timing metrics. +- `close() -> void` – releases native resources. + +#### Dependencies +- `net.ladenthin.llama.LlamaModel`, `InferenceParameters`, `ModelParameters`, `ReasoningFormat`, `ChatResponseParser`, `AiCompletionParser`. +- `net.ladenthin.maven.llamacpp.aiindex.document.AiGenerationRequest`. +- `net.ladenthin.maven.llamacpp.aiindex.prompt.AiPromptSupport`. +- `net.ladenthin.maven.llamacpp.aiindex.support.Java8CompatibilityHelper`. +- `java.util` collections, `org.jspecify.annotations.Nullable`. + +#### Exceptions / Errors +- `generate` declares `IOException` (though underlying calls throw unchecked exceptions). +- `generateWithTimings` and other methods propagate unchecked runtime exceptions from the native binding. + +#### Concurrency +- Single‑threaded usage implied; no explicit synchronization. The native `LlamaModel` is reused across calls. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/LlamaCppJniConfig.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/LlamaCppJniConfig.java.ai.md new file mode 100644 index 0000000..962dbfd --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/LlamaCppJniConfig.java.ai.md @@ -0,0 +1,76 @@ +### LlamaCppJniConfig.java +- H: 1.0 +- C: C7A880F8 +- D: 2026-06-29T19:51:15Z +- T: 2026-07-02T22:11:02Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 28; TODO/FIXME: 0; @Override: 0; methods (approx): 27; constructors: 1; field declarations (w/ modifier): 26 + +> Immutable configuration holder for llama.cpp JNI provider, exposing all runtime options as record‑style accessors. + +#### Purpose +- Stores llama.cpp native library and model configuration. +- Provides immutable, value‑semantics access to all runtime parameters. + +#### Type +- `final class LlamaCppJniConfig` (no inheritance). +- Annotations: `@ConvertToRecord`, `@ToString`, `@EqualsAndHashCode`. +- 26 private final fields: 20 primitives, 6 `List`. + +#### Input +- Constructor parameters: 26 values covering library path, model path, token limits, sampling parameters, thread count, GPU options, reasoning settings, DRY settings, and stop strings. +- `modelPath` required (`Objects.requireNonNull`). +- `drySequenceBreakers` and `stopStrings` default to empty lists if `null`. + +#### Output +- 26 accessor methods (`libraryPath()`, `modelPath()`, …, `stopStrings()`) returning primitive or immutable list views. +- Immutable state: fields never change after construction. + +#### Core logic +- Constructor validates non‑null `modelPath`. +- Assigns all parameters to fields. +- Normalizes nullable list parameters to empty immutable lists. +- Accessors simply return stored values; list getters wrap with `Collections.unmodifiableList`. + +#### Public API +- `LlamaCppJniConfig( String, String, int, int, float, int, float, int, float, float, float, boolean, boolean, boolean, int, int, int, int, String, String, int, float, float, int, int, List, List ) -> void` (constructor) +- `libraryPath() -> String` (return library path) +- `modelPath() -> String` (return model path) +- `contextSize() -> int` (return context size) +- `maxOutputTokens() -> int` (return max output tokens) +- `temperature() -> float` (return temperature) +- `threads() -> int` (return thread count) +- `topP() -> float` (return top‑p) +- `topK() -> int` (return top‑k) +- `minP() -> float` (return min‑p) +- `topNSigma() -> float` (return top‑sigma) +- `repeatPenalty() -> float` (return repetition penalty) +- `chatTemplateEnableThinking() -> boolean` (return chat‑template flag) +- `cachePrompt() -> boolean` (return prompt caching flag) +- `swaFull() -> boolean` (return SWA KV flag) +- `cacheReuse() -> int` (return cache‑reuse size) +- `gpuLayers() -> int` (return GPU layer count) +- `mainGpu() -> int` (return primary GPU index) +- `devices() -> String` (return device list) +- `reasoningEffort() -> String` (return reasoning effort) +- `reasoningBudgetTokens() -> int` (return reasoning budget) +- `dryMultiplier() -> float` (return DRY multiplier) +- `dryBase() -> float` (return DRY base) +- `dryAllowedLength() -> int` (return DRY allowed length) +- `dryPenaltyLastN() -> int` (return DRY penalty window) +- `drySequenceBreakers() -> List` (return unmodifiable DRY breakers) +- `stopStrings() -> List` (return unmodifiable stop strings) + +#### Dependencies +- `java.util.Collections`, `java.util.List`, `java.util.Objects` +- Lombok annotations: `@EqualsAndHashCode`, `@ToString` +- Custom annotation: `net.ladenthin.maven.llamacpp.aiindex.support.ConvertToRecord` + +#### Exceptions / Errors +- `NullPointerException` thrown if `modelPath` is `null`. + +#### Concurrency +- Immutable after construction; safe for concurrent use. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/MockAiGenerationProvider.java.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/MockAiGenerationProvider.java.ai.md new file mode 100644 index 0000000..47b3a3b --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/MockAiGenerationProvider.java.ai.md @@ -0,0 +1,58 @@ +### MockAiGenerationProvider.java +- H: 1.0 +- C: CEF2EE28 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:13:31Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: file +--- +**Facts (exact, whole file):** type declarations: 1; public declarations: 4; TODO/FIXME: 0; @Override: 2; methods (approx): 3; constructors: 1; field declarations (w/ modifier): 4 + +> Provides deterministic AI summaries for test purposes. + +#### Purpose +- Supplies mock AI generation results. +- Supplies fixed timing metrics for deterministic tests. + +#### Type +- Class `MockAiGenerationProvider` + Implements `AiGenerationProvider` + Annotated `@ToString` + No modifiers. + +#### Input +- `AiGenerationRequest request` in `generate` and `generateWithTimings`. + Uses `request.sourceFile()` and `request.sourceText()`. + +#### Output +- `String` summary in `generate`. +- `AiGenerationTimings` in `generateWithTimings` containing: + - mock summary string + - prompt token count + - prefill throughput 1000.0 + - predicted tokens 64 + - decode throughput 100.0 + +#### Core logic +- `generate`: Extract file name from `request.sourceFile()`; return `"Mock summary for " + fileName`. +- `generateWithTimings`: Compute `promptTokens` as `request.sourceText().length() / 4`; create new `AiGenerationTimings` with mock data. + +#### Public API +- `MockAiGenerationProvider()` → constructor, no side effects. +- `generate(AiGenerationRequest) -> String` → returns deterministic summary. +- `generateWithTimings(AiGenerationRequest) -> AiGenerationTimings` → returns mock timings. + +#### Dependencies +- `java.io.IOException` +- `java.nio.file.Path` +- `lombok.ToString` +- `net.ladenthin.maven.llamacpp.aiindex.document.AiGenerationRequest` + +#### Exceptions / Errors +- Both public methods declare `throws IOException` but never throw. + +#### Concurrency +- Stateless; thread‑safe. + +--- diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/package.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/package.ai.md new file mode 100644 index 0000000..e3760b3 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/package.ai.md @@ -0,0 +1,61 @@ +### main/java/net/ladenthin/maven/llamacpp/aiindex/provider +- H: 1.0 +- C: 073ED68B +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:21:36Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: package +- F: [AiCompletionParser.java](AiCompletionParser.java.ai.md) +- F: [AiGenerationProvider.java](AiGenerationProvider.java.ai.md) +- F: [AiGenerationProviderFactory.java](AiGenerationProviderFactory.java.ai.md) +- F: [AiGenerationTimings.java](AiGenerationTimings.java.ai.md) +- F: [LlamaCppJniAiGenerationProvider.java](LlamaCppJniAiGenerationProvider.java.ai.md) +- F: [LlamaCppJniConfig.java](LlamaCppJniConfig.java.ai.md) +- F: [MockAiGenerationProvider.java](MockAiGenerationProvider.java.ai.md) +--- +> Provides a pluggable AI generation engine for Maven AI‑index, exposing local llama.cpp bindings and a deterministic mock, along with utilities to parse responses, record timing metrics, and build providers from configuration. + +#### Purpose +- Supply AI text generation backends to Maven AI‑index. +- Offer a mock implementation for testing and a JNI‑based llama.cpp provider. +- Record generation timings for calibration. + +#### Responsibilities +- **Provider Instantiation** – `AiGenerationProviderFactory` selects and constructs a provider by name. +- **Generation API** – `AiGenerationProvider` defines `generate` and `generateWithTimings`. +- **JNI Implementation** – `LlamaCppJniAiGenerationProvider` loads a GGUF model, executes chat completions, and extracts timings. +- **Configuration** – `LlamaCppJniConfig` holds immutable runtime options for the JNI provider. +- **Mocking** – `MockAiGenerationProvider` returns deterministic summaries and synthetic timing data. +- **Response Parsing** – `AiCompletionParser` strips internal chain‑of‑thought blocks from Gemma‑4 completions. +- **Timing Data** – `AiGenerationTimings` stores text and per‑token throughput metrics. + +#### Key units +- **`AiGenerationProvider`** – interface with `generate`, `generateWithTimings`, `close`. +- **`AiGenerationProviderFactory`** – builds providers; handles `"mock"` and `"llamacpp-jni"`. +- **`LlamaCppJniAiGenerationProvider`** – JNI provider; lazy‑loads `LlamaModel`, builds `InferenceParameters`, calls `chatCompleteText`, parses with `AiCompletionParser`. +- **`LlamaCppJniConfig`** – immutable record of library path, model path, token limits, sampling, threads, GPU, reasoning, DRY, stop strings. +- **`MockAiGenerationProvider`** – deterministic summary generator; returns fixed `AiGenerationTimings`. +- **`AiCompletionParser`** – static method `parseCompletion(String)` removes thinking blocks, throws `IOException` on incomplete block. +- **`AiGenerationTimings`** – immutable holder of text, promptTokens, prefillTokensPerSecond, predictedTokens, decodeTokensPerSecond. + +#### Data flow +1. **Client** requests generation via `AiGenerationProvider.generate(request)`. +2. **Factory** supplies provider instance (`Mock` or `LlamaCppJni`). +3. **Provider** builds `InferenceParameters` from `LlamaCppJniConfig` and `AiPromptSupport`. +4. **JNI provider** invokes `LlamaModel.chatCompleteText` (or `chatComplete`), obtaining a raw completion. +5. **Parser** cleans the completion (`AiCompletionParser.parseCompletion`). +6. **Provider** returns cleaned text or `AiGenerationTimings` containing text and token throughput. +7. **Client** consumes result; calibration goal may use `AiGenerationTimings`. + +#### Dependencies +- **Internal**: `AiPromptSupport`, `Java8CompatibilityHelper`, `ConvertToRecord`, Lombok annotations. +- **External**: `net.ladenthin.llama` native bindings (`LlamaModel`, `InferenceParameters`, `ChatResponseParser`). +- **Java**: `java.io.IOException`, `java.nio.file.Path`, collections, `org.jspecify.annotations.Nullable`. + +#### Cross-cutting +- **Immutability**: `LlamaCppJniConfig` and `AiGenerationTimings` are value objects. +- **Thread safety**: `MockAiGenerationProvider` is stateless; factory and config are thread‑safe; JNI provider is single‑threaded (no explicit sync). +- **Error handling**: `AiCompletionParser` throws `IOException` for malformed thinking blocks; provider methods propagate `IOException` for generation failures. +- **Configuration**: `LlamaCppJniConfig` normalizes nullable lists to empty immutable lists; all fields are final. +- **Parsing**: `AiCompletionParser` centralizes response cleaning, ensuring consistent output across providers. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/package.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/package.ai.md new file mode 100644 index 0000000..de329cf --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/llamacpp/package.ai.md @@ -0,0 +1,56 @@ +### main/java/net/ladenthin/maven/llamacpp +- H: 1.0 +- C: BB07F829 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:26:50Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: package +- F: [aiindex/](aiindex/package.ai.md) +--- +> A Maven plugin that analyses Java source files, selects a suitable LlamaCPP model based on declarative rules, extracts deterministic facts, runs inference via JNI, and returns cleaned AI completions with timing data. + +#### Purpose +- Parse Maven configuration into AI‑generation rules, facts, and model settings. +- Evaluate source files against these rules to select a LlamaCPP provider. +- Invoke the provider, capture timing metrics, and return cleaned AI completions. + +#### Responsibilities +- **Configuration handling** – read and validate XML into immutable POJOs (`AiFieldGenerationConfig`, `AiFactDefinition`, `AiModelDefinition`). +- **Rule evaluation** – match files to rules using predicate trees (`AiCondition`, `AiRangeCondition`) and selector logic (`AiFieldGenerationSelector`). +- **Fact extraction** – generate deterministic `label: count` blocks from source content (`AiFactExtractor`). +- **Provider orchestration** – instantiate the correct AI backend (`AiGenerationProviderFactory`) and expose a uniform generation API. +- **JNI integration** – load and run a GGUF model via `LlamaCppJniAiGenerationProvider`, parse raw completions, and record per‑token throughput. +- **Mocking & calibration** – provide a deterministic mock provider for tests and expose timing data (`AiGenerationTimings`) for calibration. + +#### Key units +- **`AiFieldGenerationConfig`** – rule definition: condition, model key, prompt key, priority, fallbacks, oversize strategy, fact counters. +- **`AiConditionEvaluator`** – validates and evaluates condition trees against `AiFileContext`. +- **`AiFactExtractor`** – produces fact blocks from regex counters in a file. +- **`AiModelDefinitionSupport`** – maps model keys to fully‑configured `AiGenerationConfig`. +- **`AiGenerationProviderFactory`** – builds `AiGenerationProvider` instances (`mock`, `llamacpp-jni`). +- **`LlamaCppJniAiGenerationProvider`** – JNI‑backed provider that loads `LlamaModel`, runs `chatCompleteText`, and parses responses. +- **`MockAiGenerationProvider`** – deterministic summary generator with synthetic timings. +- **`AiCompletionParser`** – removes internal chain‑of‑thought blocks from Gemma‑4 completions. +- **`AiGenerationTimings`** – immutable holder of generated text, token counts, and throughput metrics. + +#### Data flow +1. **Configuration**: Maven XML → `AiFieldGenerationConfig`, `AiFactDefinition`, `AiModelDefinition`. +2. **Setup**: `AiFactDefinitionSupport` injects fact counters into rules; `AiModelDefinitionSupport` creates `AiGenerationConfig` instances. +3. **Runtime**: For each source file, + - Build `AiFileContext`. + - `AiFieldGenerationSelector` uses `AiConditionEvaluator` to pick the best rule. + - If facts are needed, `AiFactExtractor` generates the fact block. + - `AiGenerationProviderFactory` supplies the appropriate provider. + - Provider runs inference, `AiCompletionParser` cleans the output, and `AiGenerationTimings` records metrics. +4. **Result**: Cleaned AI completion returned to the plugin; timings optionally used for calibration. + +#### Dependencies +- **Internal**: `AiPromptSupport`, `Java8CompatibilityHelper`, `ConvertToRecord`, Lombok (`@ToString`), `org.jspecify.annotations.Nullable`. +- **External**: Maven plugin framework, native `net.ladenthin.llama` bindings (`LlamaModel`, `InferenceParameters`, `ChatResponseParser`), Java standard libraries (`java.time`, `java.util.regex`, `java.nio.file.Path`). + +#### Cross-cutting +- **Immutability & thread safety** – configuration POJOs and timing records are immutable; provider factories are stateless. +- **Validation & error handling** – centralized in `AiConditionEvaluator` and `AiFieldGenerationSelector`; `AiCompletionParser` throws `IOException` for malformed responses. +- **Configuration normalization** – `LlamaCppJniConfig` turns nullable lists into immutable empty lists; all fields are final. +- **Consistent response parsing** – `AiCompletionParser` ensures all providers return the same cleaned text format. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/package.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/package.ai.md new file mode 100644 index 0000000..6a4c3f2 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/maven/package.ai.md @@ -0,0 +1,58 @@ +### main/java/net/ladenthin/maven +- H: 1.0 +- C: 84F070A1 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:28:33Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: package +- F: [llamacpp/](llamacpp/package.ai.md) +--- +> A Maven plugin that automatically selects and runs a LlamaCPP model to generate AI‑based code insights, returning clean completions and timing metrics. + +#### Purpose +- Parse Maven XML into AI‑generation rules, facts, and model settings. +- Evaluate source files against these rules to choose a suitable LlamaCPP provider. +- Run inference via JNI, parse completions, and expose timing data. + +#### Responsibilities +- **Configuration handling** – XML → immutable POJOs (`AiFieldGenerationConfig`, `AiFactDefinition`, `AiModelDefinition`). +- **Rule evaluation** – predicate trees (`AiCondition`, `AiRangeCondition`) and selector (`AiFieldGenerationSelector`). +- **Fact extraction** – deterministic `label: count` blocks via `AiFactExtractor`. +- **Provider orchestration** – factory (`AiGenerationProviderFactory`) builds mock or JNI providers. +- **JNI integration** – `LlamaCppJniAiGenerationProvider` loads `LlamaModel`, runs `chatCompleteText`, parses responses, records throughput. +- **Mocking & calibration** – deterministic mock provider (`MockAiGenerationProvider`) and timing holder (`AiGenerationTimings`). + +#### Key units +- `AiFieldGenerationConfig` – rule definition (condition, model key, prompt key, priority, fallbacks, oversize strategy, fact counters). +- `AiConditionEvaluator` – validates and evaluates condition trees against `AiFileContext`. +- `AiFactExtractor` – generates fact blocks from regex counters in a file. +- `AiModelDefinitionSupport` – maps model keys to fully‑configured `AiGenerationConfig`. +- `AiGenerationProviderFactory` – builds `AiGenerationProvider` instances (`mock`, `llamacpp-jni`). +- `LlamaCppJniAiGenerationProvider` – JNI‑backed provider that loads `LlamaModel`, runs `chatCompleteText`, parses responses, and records per‑token throughput. +- `MockAiGenerationProvider` – deterministic summary generator with synthetic timings. +- `AiCompletionParser` – removes internal chain‑of‑thought blocks from Gemma‑4 completions. +- `AiGenerationTimings` – immutable holder of generated text, token counts, and throughput metrics. + +#### Data flow +1. **Configuration**: Maven XML → `AiFieldGenerationConfig`, `AiFactDefinition`, `AiModelDefinition`. +2. **Setup**: Fact counters injected via `AiFactDefinitionSupport`; model configs built by `AiModelDefinitionSupport`. +3. **Runtime per file**: + - Build `AiFileContext`. + - `AiFieldGenerationSelector` + `AiConditionEvaluator` pick the best rule. + - If facts required, `AiFactExtractor` generates fact block. + - `AiGenerationProviderFactory` supplies the appropriate provider. + - Provider runs inference → raw completion. + - `AiCompletionParser` cleans output. + - `AiGenerationTimings` records metrics. +4. **Result**: Cleaned AI completion returned to plugin; timings optionally used for calibration. + +#### Dependencies +- Internal: `AiPromptSupport`, `Java8CompatibilityHelper`, `ConvertToRecord`, Lombok (`@ToString`), `org.jspecify.annotations.Nullable`. +- External: Maven plugin framework, native `net.ladenthin.llama` bindings (`LlamaModel`, `InferenceParameters`, `ChatResponseParser`), Java standard libraries (`java.time`, `java.util.regex`, `java.nio.file.Path`). + +#### Cross-cutting +- **Immutability & thread safety** – configuration POJOs and timing records are immutable; provider factories are stateless. +- **Validation & error handling** – centralized in `AiConditionEvaluator` and `AiFieldGenerationSelector`; `AiCompletionParser` throws `IOException` for malformed responses. +- **Configuration normalization** – `LlamaCppJniConfig` turns nullable lists into immutable empty lists; all fields are final. +- **Consistent response parsing** – `AiCompletionParser` ensures all providers return the same cleaned text format. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/package.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/package.ai.md new file mode 100644 index 0000000..47af4be --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/ladenthin/package.ai.md @@ -0,0 +1,58 @@ +### main/java/net/ladenthin +- H: 1.0 +- C: DCA70847 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:30:11Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: package +- F: [maven/](maven/package.ai.md) +--- +> A Maven plugin that selects and runs a LlamaCPP model to generate AI‑based code insights, returning clean completions and timing metrics. + +#### Purpose +- Parse Maven XML into AI‑generation rules, facts, and model settings. +- Evaluate source files against these rules to choose a suitable LlamaCPP provider. +- Run inference via JNI, parse completions, and expose timing data. + +#### Responsibilities +- **Configuration handling** – XML → immutable POJOs (`AiFieldGenerationConfig`, `AiFactDefinition`, `AiModelDefinition`). +- **Rule evaluation** – predicate trees (`AiCondition`, `AiRangeCondition`) and selector (`AiFieldGenerationSelector`). +- **Fact extraction** – deterministic `label: count` blocks via `AiFactExtractor`. +- **Provider orchestration** – factory (`AiGenerationProviderFactory`) builds mock or JNI providers. +- **JNI integration** – `LlamaCppJniAiGenerationProvider` loads `LlamaModel`, runs `chatCompleteText`, parses responses, records throughput. +- **Mocking & calibration** – deterministic mock provider (`MockAiGenerationProvider`) and timing holder (`AiGenerationTimings`). + +#### Key units +- `AiFieldGenerationConfig` – rule definition (condition, model key, prompt key, priority, fallbacks, oversize strategy, fact counters). +- `AiConditionEvaluator` – validates and evaluates condition trees against `AiFileContext`. +- `AiFactExtractor` – generates fact blocks from regex counters in a file. +- `AiModelDefinitionSupport` – maps model keys to fully‑configured `AiGenerationConfig`. +- `AiGenerationProviderFactory` – builds `AiGenerationProvider` instances (`mock`, `llamacpp-jni`). +- `LlamaCppJniAiGenerationProvider` – JNI‑backed provider that loads `LlamaModel`, runs `chatCompleteText`, parses responses, and records per‑token throughput. +- `MockAiGenerationProvider` – deterministic summary generator with synthetic timings. +- `AiCompletionParser` – removes internal chain‑of‑thought blocks from Gemma‑4 completions. +- `AiGenerationTimings` – immutable holder of generated text, token counts, and throughput metrics. + +#### Data flow +1. **Configuration**: Maven XML → `AiFieldGenerationConfig`, `AiFactDefinition`, `AiModelDefinition`. +2. **Setup**: Fact counters injected via `AiFactDefinitionSupport`; model configs built by `AiModelDefinitionSupport`. +3. **Runtime per file**: + - Build `AiFileContext`. + - `AiFieldGenerationSelector` + `AiConditionEvaluator` pick the best rule. + - If facts required, `AiFactExtractor` generates fact block. + - `AiGenerationProviderFactory` supplies the appropriate provider. + - Provider runs inference → raw completion. + - `AiCompletionParser` cleans output. + - `AiGenerationTimings` records metrics. +4. **Result**: Cleaned AI completion returned to plugin; timings optionally used for calibration. + +#### Dependencies +- Internal: `AiPromptSupport`, `Java8CompatibilityHelper`, `ConvertToRecord`, Lombok (`@ToString`), `org.jspecify.annotations.Nullable`. +- External: Maven plugin framework, native `net.ladenthin.llama` bindings (`LlamaModel`, `InferenceParameters`, `ChatResponseParser`), Java standard libraries (`java.time`, `java.util.regex`, `java.nio.file.Path`). + +#### Cross-cutting +- **Immutability & thread safety** – configuration POJOs and timing records are immutable; provider factories are stateless. +- **Validation & error handling** – centralized in `AiConditionEvaluator` and `AiFieldGenerationSelector`; `AiCompletionParser` throws `IOException` for malformed responses. +- **Configuration normalization** – `LlamaCppJniConfig` turns nullable lists into immutable empty lists; all fields are final. +- **Consistent response parsing** – `AiCompletionParser` ensures all providers return the same cleaned text format. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/package.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/package.ai.md new file mode 100644 index 0000000..bfaa97d --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/net/package.ai.md @@ -0,0 +1,58 @@ +### main/java/net +- H: 1.0 +- C: FAF52897 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:31:48Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: package +- F: [ladenthin/](ladenthin/package.ai.md) +--- +> A Maven plugin that selects a suitable LlamaCPP model for each source file, runs inference via JNI, parses the completion, and records timing metrics for AI‑based code insights. + +#### Purpose +- Transform Maven XML rules into immutable configuration objects. +- Evaluate source files against these rules to determine the appropriate AI model. +- Execute model inference through JNI, clean the output, and capture performance data. + +#### Responsibilities +- **Configuration** – parse XML into `AiFieldGenerationConfig`, `AiFactDefinition`, `AiModelDefinition`. +- **Rule evaluation** – tree‑based conditions (`AiCondition`, `AiRangeCondition`) and selector (`AiFieldGenerationSelector`). +- **Fact extraction** – produce deterministic `label: count` blocks via `AiFactExtractor`. +- **Provider orchestration** – factory (`AiGenerationProviderFactory`) creates mock or JNI providers. +- **JNI integration** – `LlamaCppJniAiGenerationProvider` loads `LlamaModel`, calls `chatCompleteText`, parses responses, and records throughput. +- **Mocking & calibration** – deterministic `MockAiGenerationProvider` and timing holder (`AiGenerationTimings`). + +#### Key units +- `AiFieldGenerationConfig` – rule definition with condition, model key, prompt key, priority, fallbacks, oversize strategy, fact counters. +- `AiConditionEvaluator` – validates and evaluates condition trees against `AiFileContext`. +- `AiFactExtractor` – generates fact blocks from regex counters in a file. +- `AiModelDefinitionSupport` – maps model keys to fully‑configured `AiGenerationConfig`. +- `AiGenerationProviderFactory` – builds `AiGenerationProvider` instances (`mock`, `llamacpp-jni`). +- `LlamaCppJniAiGenerationProvider` – JNI‑backed provider that loads `LlamaModel`, runs `chatCompleteText`, parses responses, and records per‑token throughput. +- `MockAiGenerationProvider` – deterministic summary generator with synthetic timings. +- `AiCompletionParser` – removes internal chain‑of‑thought blocks from Gemma‑4 completions. +- `AiGenerationTimings` – immutable holder of generated text, token counts, and throughput metrics. + +#### Data flow +1. **Configuration** – Maven XML → `AiFieldGenerationConfig`, `AiFactDefinition`, `AiModelDefinition`. +2. **Setup** – Fact counters injected via `AiFactDefinitionSupport`; model configs built by `AiModelDefinitionSupport`. +3. **Runtime per file** + - Build `AiFileContext`. + - `AiFieldGenerationSelector` + `AiConditionEvaluator` pick the best rule. + - If facts required, `AiFactExtractor` generates fact block. + - `AiGenerationProviderFactory` supplies the appropriate provider. + - Provider runs inference → raw completion. + - `AiCompletionParser` cleans output. + - `AiGenerationTimings` records metrics. +4. **Result** – Cleaned AI completion returned to plugin; timings optionally used for calibration. + +#### Dependencies +- Internal: `AiPromptSupport`, `Java8CompatibilityHelper`, `ConvertToRecord`, Lombok (`@ToString`), `org.jspecify.annotations.Nullable`. +- External: Maven plugin framework; native `net.ladenthin.llama` bindings (`LlamaModel`, `InferenceParameters`, `ChatResponseParser`); Java standard libraries (`java.time`, `java.util.regex`, `java.nio.file.Path`). + +#### Cross-cutting +- **Immutability & thread safety** – configuration POJOs and timing records are immutable; provider factories are stateless. +- **Validation & error handling** – centralized in `AiConditionEvaluator` and `AiFieldGenerationSelector`; `AiCompletionParser` throws `IOException` for malformed responses. +- **Configuration normalization** – `LlamaCppJniConfig` turns nullable lists into immutable empty lists; all fields are final. +- **Consistent response parsing** – `AiCompletionParser` ensures all providers return the same cleaned text format. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/package.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/package.ai.md new file mode 100644 index 0000000..f005eb6 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/java/package.ai.md @@ -0,0 +1,58 @@ +### main/java +- H: 1.0 +- C: E34B0133 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:33:25Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: package +- F: [net/](net/package.ai.md) +--- +> A Maven plugin that selects an appropriate LlamaCPP model for each source file, runs inference via JNI, parses the completion, and records timing metrics for AI‑based code insights. + +#### Purpose +- Convert Maven XML rules into immutable configuration objects. +- Evaluate source files against these rules to choose an AI model. +- Execute model inference via JNI, clean the output, and capture performance data. + +#### Responsibilities +- **Configuration** – parse XML into `AiFieldGenerationConfig`, `AiFactDefinition`, `AiModelDefinition`. +- **Rule evaluation** – tree‑based conditions (`AiCondition`, `AiRangeCondition`) and selector (`AiFieldGenerationSelector`). +- **Fact extraction** – deterministic `label: count` blocks via `AiFactExtractor`. +- **Provider orchestration** – factory (`AiGenerationProviderFactory`) creates mock or JNI providers. +- **JNI integration** – `LlamaCppJniAiGenerationProvider` loads `LlamaModel`, calls `chatCompleteText`, parses responses, and records throughput. +- **Mocking & calibration** – deterministic `MockAiGenerationProvider` and timing holder (`AiGenerationTimings`). + +#### Key units +- `AiFieldGenerationConfig` – rule definition with condition, model key, prompt key, priority, fallbacks, oversize strategy, fact counters. +- `AiConditionEvaluator` – validates and evaluates condition trees against `AiFileContext`. +- `AiFactExtractor` – generates fact blocks from regex counters in a file. +- `AiModelDefinitionSupport` – maps model keys to fully‑configured `AiGenerationConfig`. +- `AiGenerationProviderFactory` – builds `AiGenerationProvider` instances (`mock`, `llamacpp-jni`). +- `LlamaCppJniAiGenerationProvider` – JNI‑backed provider that loads `LlamaModel`, runs `chatCompleteText`, parses responses, and records per‑token throughput. +- `MockAiGenerationProvider` – deterministic summary generator with synthetic timings. +- `AiCompletionParser` – removes internal chain‑of‑thought blocks from Gemma‑4 completions. +- `AiGenerationTimings` – immutable holder of generated text, token counts, and throughput metrics. + +#### Data flow +1. Maven XML → `AiFieldGenerationConfig`, `AiFactDefinition`, `AiModelDefinition`. +2. Fact counters injected via `AiFactDefinitionSupport`; model configs built by `AiModelDefinitionSupport`. +3. For each source file: + - Build `AiFileContext`. + - `AiFieldGenerationSelector` + `AiConditionEvaluator` pick the best rule. + - If facts required, `AiFactExtractor` generates fact block. + - `AiGenerationProviderFactory` supplies the appropriate provider. + - Provider runs inference → raw completion. + - `AiCompletionParser` cleans output. + - `AiGenerationTimings` records metrics. +4. Cleaned AI completion returned to plugin; timings optionally used for calibration. + +#### Dependencies +- Internal: `AiPromptSupport`, `Java8CompatibilityHelper`, `ConvertToRecord`, Lombok (`@ToString`), `org.jspecify.annotations.Nullable`. +- External: Maven plugin framework; native `net.ladenthin.llama` bindings (`LlamaModel`, `InferenceParameters`, `ChatResponseParser`); Java standard libraries (`java.time`, `java.util.regex`, `java.nio.file.Path`). + +#### Cross-cutting +- **Immutability & thread safety** – configuration POJOs and timing records are immutable; provider factories are stateless. +- **Validation & error handling** – centralized in `AiConditionEvaluator` and `AiFieldGenerationSelector`; `AiCompletionParser` throws `IOException` for malformed responses. +- **Configuration normalization** – `LlamaCppJniConfig` turns nullable lists into immutable empty lists; all fields are final. +- **Consistent response parsing** – `AiCompletionParser` ensures all providers return the same cleaned text format. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/package.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/package.ai.md new file mode 100644 index 0000000..79f759e --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/main/package.ai.md @@ -0,0 +1,58 @@ +### main +- H: 1.0 +- C: 1886955F +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:35:02Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: package +- F: [java/](java/package.ai.md) +--- +> A Maven plugin that automatically selects and runs LlamaCPP models on Java source files, parses their completions, and captures detailed performance metrics for AI‑driven code insights. + +#### Purpose +- Convert Maven XML rule sets into immutable configuration objects. +- Evaluate each source file against these rules to select an appropriate LlamaCPP model. +- Execute inference via JNI, clean the raw output, and record timing data. + +#### Responsibilities +- **Configuration** – parse XML into `AiFieldGenerationConfig`, `AiFactDefinition`, `AiModelDefinition`. +- **Rule evaluation** – tree‑based conditions (`AiCondition`, `AiRangeCondition`) and selector (`AiFieldGenerationSelector`). +- **Fact extraction** – deterministic `label: count` blocks via `AiFactExtractor`. +- **Provider orchestration** – factory (`AiGenerationProviderFactory`) creates mock or JNI providers. +- **JNI integration** – `LlamaCppJniAiGenerationProvider` loads `LlamaModel`, calls `chatCompleteText`, parses responses, and records throughput. +- **Mocking & calibration** – deterministic `MockAiGenerationProvider` and timing holder (`AiGenerationTimings`). + +#### Key units +- `AiFieldGenerationConfig` – rule definition with condition, model key, prompt key, priority, fallbacks, oversize strategy, fact counters. +- `AiConditionEvaluator` – validates and evaluates condition trees against `AiFileContext`. +- `AiFactExtractor` – generates fact blocks from regex counters in a file. +- `AiModelDefinitionSupport` – maps model keys to fully‑configured `AiGenerationConfig`. +- `AiGenerationProviderFactory` – builds `AiGenerationProvider` instances (`mock`, `llamacpp-jni`). +- `LlamaCppJniAiGenerationProvider` – JNI‑backed provider that loads `LlamaModel`, runs `chatCompleteText`, parses responses, and records per‑token throughput. +- `MockAiGenerationProvider` – deterministic summary generator with synthetic timings. +- `AiCompletionParser` – removes internal chain‑of‑thought blocks from Gemma‑4 completions. +- `AiGenerationTimings` – immutable holder of generated text, token counts, and throughput metrics. + +#### Data flow +1. Maven XML → `AiFieldGenerationConfig`, `AiFactDefinition`, `AiModelDefinition`. +2. Fact counters injected via `AiFactDefinitionSupport`; model configs built by `AiModelDefinitionSupport`. +3. For each source file: + - Build `AiFileContext`. + - `AiFieldGenerationSelector` + `AiConditionEvaluator` pick the best rule. + - If facts required, `AiFactExtractor` generates fact block. + - `AiGenerationProviderFactory` supplies the appropriate provider. + - Provider runs inference → raw completion. + - `AiCompletionParser` cleans output. + - `AiGenerationTimings` records metrics. +4. Cleaned AI completion returned to plugin; timings optionally used for calibration. + +#### Dependencies +- Internal: `AiPromptSupport`, `Java8CompatibilityHelper`, `ConvertToRecord`, Lombok (`@ToString`), `org.jspecify.annotations.Nullable`. +- External: Maven plugin framework; native `net.ladenthin.llama` bindings (`LlamaModel`, `InferenceParameters`, `ChatResponseParser`); Java standard libraries (`java.time`, `java.util.regex`, `java.nio.file.Path`). + +#### Cross-cutting +- **Immutability & thread safety** – configuration POJOs and timing records are immutable; provider factories are stateless. +- **Validation & error handling** – centralized in `AiConditionEvaluator` and `AiFieldGenerationSelector`; `AiCompletionParser` throws `IOException` for malformed responses. +- **Configuration normalization** – `LlamaCppJniConfig` turns nullable lists into immutable empty lists; all fields are final. +- **Consistent response parsing** – `AiCompletionParser` ensures all providers return the same cleaned text format. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/package.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/package.ai.md new file mode 100644 index 0000000..b6d5bf7 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/package.ai.md @@ -0,0 +1,58 @@ +### ai +- H: 1.0 +- C: 193DCE8A +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:36:37Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: package +- F: [main/](main/package.ai.md) +--- +> A Maven plugin that selects and runs LlamaCPP models on Java source files, parses their completions, and records detailed performance metrics for AI‑driven code insights. + +#### Purpose +- Parse Maven XML rule sets into immutable configuration objects. +- Evaluate source files against these rules to choose a LlamaCPP model. +- Execute inference via JNI, clean raw output, and capture timing data. + +#### Responsibilities +- **Configuration** – XML → `AiFieldGenerationConfig`, `AiFactDefinition`, `AiModelDefinition`. +- **Rule evaluation** – tree‑based `AiCondition`/`AiRangeCondition` and selector `AiFieldGenerationSelector`. +- **Fact extraction** – deterministic `label: count` blocks via `AiFactExtractor`. +- **Provider orchestration** – factory `AiGenerationProviderFactory` creates mock or JNI providers. +- **JNI integration** – `LlamaCppJniAiGenerationProvider` loads `LlamaModel`, runs `chatCompleteText`, parses responses, records throughput. +- **Mocking & calibration** – deterministic `MockAiGenerationProvider` and timing holder `AiGenerationTimings`. + +#### Key units +- `AiFieldGenerationConfig` – rule definition with condition, model key, prompt key, priority, fallbacks, oversize strategy, fact counters. +- `AiConditionEvaluator` – validates and evaluates condition trees against `AiFileContext`. +- `AiFactExtractor` – generates fact blocks from regex counters in a file. +- `AiModelDefinitionSupport` – maps model keys to fully‑configured `AiGenerationConfig`. +- `AiGenerationProviderFactory` – builds `AiGenerationProvider` instances (`mock`, `llamacpp-jni`). +- `LlamaCppJniAiGenerationProvider` – JNI‑backed provider that loads `LlamaModel`, runs `chatCompleteText`, parses responses, and records per‑token throughput. +- `MockAiGenerationProvider` – deterministic summary generator with synthetic timings. +- `AiCompletionParser` – removes internal chain‑of‑thought blocks from Gemma‑4 completions. +- `AiGenerationTimings` – immutable holder of generated text, token counts, and throughput metrics. + +#### Data flow +1. Maven XML → `AiFieldGenerationConfig`, `AiFactDefinition`, `AiModelDefinition`. +2. Fact counters injected via `AiFactDefinitionSupport`; model configs built by `AiModelDefinitionSupport`. +3. For each source file: + - Build `AiFileContext`. + - `AiFieldGenerationSelector` + `AiConditionEvaluator` pick the best rule. + - If facts required, `AiFactExtractor` generates fact block. + - `AiGenerationProviderFactory` supplies the appropriate provider. + - Provider runs inference → raw completion. + - `AiCompletionParser` cleans output. + - `AiGenerationTimings` records metrics. +4. Cleaned AI completion returned to plugin; timings optionally used for calibration. + +#### Dependencies +- Internal: `AiPromptSupport`, `Java8CompatibilityHelper`, `ConvertToRecord`, Lombok (`@ToString`), `org.jspecify.annotations.Nullable`. +- External: Maven plugin framework; native `net.ladenthin.llama` bindings (`LlamaModel`, `InferenceParameters`, `ChatResponseParser`); Java standard libraries (`java.time`, `java.util.regex`, `java.nio.file.Path`). + +#### Cross-cutting +- **Immutability & thread safety** – configuration POJOs and timing records are immutable; provider factories are stateless. +- **Validation & error handling** – centralized in `AiConditionEvaluator` and `AiFieldGenerationSelector`; `AiCompletionParser` throws `IOException` for malformed responses. +- **Configuration normalization** – `LlamaCppJniConfig` turns nullable lists into immutable empty lists; all fields are final. +- **Consistent response parsing** – `AiCompletionParser` ensures all providers return the same cleaned text format. diff --git a/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/project.ai.md b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/project.ai.md new file mode 100644 index 0000000..e8260a8 --- /dev/null +++ b/docs/ai-index-benchmark/outputs/ai__granite4-h-small__v1/project.ai.md @@ -0,0 +1,35 @@ +### llamacpp-ai-index-maven-plugin +- H: 1.0 +- C: BFEC59A9 +- D: 2026-07-02T19:31:59Z +- T: 2026-07-02T22:38:26Z +- G: 1.0.3-SNAPSHOT +- A: 0.0.0 +- X: project +- F: [main/java/net/ladenthin/maven/llamacpp/aiindex/config](main/java/net/ladenthin/maven/llamacpp/aiindex/config/package.ai.md) +- F: [main/java/net/ladenthin/maven/llamacpp/aiindex](main/java/net/ladenthin/maven/llamacpp/aiindex/package.ai.md) +- F: [main/java/net/ladenthin/maven/llamacpp/aiindex/provider](main/java/net/ladenthin/maven/llamacpp/aiindex/provider/package.ai.md) +- F: [main/java/net/ladenthin/maven/llamacpp](main/java/net/ladenthin/maven/llamacpp/package.ai.md) +- F: [main/java/net/ladenthin/maven](main/java/net/ladenthin/maven/package.ai.md) +- F: [main/java/net/ladenthin](main/java/net/ladenthin/package.ai.md) +- F: [main/java/net](main/java/net/package.ai.md) +- F: [main/java](main/java/package.ai.md) +- F: [main](main/package.ai.md) +- F: [.](package.ai.md) +--- +> Project index of llamacpp-ai-index-maven-plugin: one line per package; leads here, clickable links in the header F list. + +#### Overview +The llamacpp‑ai‑index‑maven‑plugin provides a Maven‑centric framework for AI‑driven code insights. It analyses Java source files, applies declarative rules to select an appropriate LlamaCPP model, and runs inference via JNI while extracting deterministic facts that drive prompt construction. A pluggable provider layer exposes local llama.cpp bindings, a deterministic mock, and utilities for parsing responses, recording timing metrics, and building providers from configuration. The plugin aggregates these components to automatically generate clean AI completions and capture detailed performance metrics for each source file. + +#### Packages +- main/java/net/ladenthin/maven/llamacpp/aiindex/config — A Maven plugin configuration library that models AI‑generation rules, file‑matching conditions, fact extraction, and runtime AI settings for the LlamaCPP indexer. +- main/java/net/ladenthin/maven/llamacpp/aiindex — A Maven plugin that indexes source files for AI‑generation, routing each file to a suitable LlamaCPP model based on declarative rules and extracting deterministic facts to drive prompt construction. +- main/java/net/ladenthin/maven/llamacpp/aiindex/provider — Provides a pluggable AI generation engine for Maven AI‑index, exposing local llama.cpp bindings and a deterministic mock, along with utilities to parse responses, record timing metrics, and build providers from configuration. +- main/java/net/ladenthin/maven/llamacpp — A Maven plugin that analyses Java source files, selects a suitable LlamaCPP model based on declarative rules, extracts deterministic facts, runs inference via JNI, and returns cleaned AI completions with timing data. +- main/java/net/ladenthin/maven — A Maven plugin that automatically selects and runs a LlamaCPP model to generate AI‑based code insights, returning clean completions and timing metrics. +- main/java/net/ladenthin — A Maven plugin that selects and runs a LlamaCPP model to generate AI‑based code insights, returning clean completions and timing metrics. +- main/java/net — A Maven plugin that selects a suitable LlamaCPP model for each source file, runs inference via JNI, parses the completion, and records timing metrics for AI‑based code insights. +- main/java — A Maven plugin that selects an appropriate LlamaCPP model for each source file, runs inference via JNI, parses the completion, and records timing metrics for AI‑based code insights. +- main — A Maven plugin that automatically selects and runs LlamaCPP models on Java source files, parses their completions, and captures detailed performance metrics for AI‑driven code insights. +- . — A Maven plugin that selects and runs LlamaCPP models on Java source files, parses their completions, and records detailed performance metrics for AI‑driven code insights. diff --git a/docs/ai-index-benchmark/tools/agentic-5models-cpu.tsv b/docs/ai-index-benchmark/tools/agentic-5models-cpu.tsv new file mode 100644 index 0000000..d41a2a5 --- /dev/null +++ b/docs/ai-index-benchmark/tools/agentic-5models-cpu.tsv @@ -0,0 +1,16 @@ +model ctx_target prompt_n load_s ttft_ms prefill_tps decode_tps tool_ok notes +granite-4.0-h-tiny-Q4_K_M.gguf 512 740 6 6029 122.7 9.0 YES total=8.256894s +granite-4.0-h-tiny-Q4_K_M.gguf 3072 3308 6 19283 171.6 9.5 YES total=21.405980s +granite-4.0-h-tiny-Q4_K_M.gguf 16384 16076 6 46108 348.7 8.0 YES total=48.629940s +gpt-oss-20b-mxfp4.gguf 512 679 8 30276 22.4 6.9 YES total=39.284626s +gpt-oss-20b-mxfp4.gguf 3072 3247 8 18776 172.9 5.0 YES total=31.235231s +gpt-oss-20b-mxfp4.gguf 16384 16015 8 100832 158.8 3.2 YES total=113.287090s +deepseek-coder-7b-instruct-v1.5-Q8_0.gguf 512 696 14 18866 36.9 4.7 NO total=44.510874s +deepseek-coder-7b-instruct-v1.5-Q8_0.gguf 3072 3915 14 69579 56.3 3.5 NO total=104.303962s +Qwen2.5-Coder-14B-Instruct-Q6_K.gguf 512 770 19 32044 24.0 3.0 TEXT total=42.433354s +Qwen2.5-Coder-14B-Instruct-Q6_K.gguf 3072 3882 19 108356 35.8 2.5 TEXT total=120.694763s +Qwen2.5-Coder-14B-Instruct-Q6_K.gguf 16384 NA 19 NA NA NA ERR {'code': 400, 'message': 'request (20906 tokens) exceeds the +Qwen2.5-Coder-32B-Instruct-Q4_K_M.gguf 512 770 24 44639 17.2 1.9 TEXT total=56.522518s +Qwen2.5-Coder-32B-Instruct-Q4_K_M.gguf 3072 3882 24 112945 34.4 1.6 TEXT total=127.614789s +Qwen2.5-Coder-32B-Instruct-Q4_K_M.gguf 16384 NA 24 NA NA NA ERR {'code': 400, 'message': 'request (20906 tokens) exceeds the +CPU CTX BENCH DONE diff --git a/docs/ai-index-benchmark/tools/agentic-5models-cpu.tsv.license b/docs/ai-index-benchmark/tools/agentic-5models-cpu.tsv.license new file mode 100644 index 0000000..ac8b117 --- /dev/null +++ b/docs/ai-index-benchmark/tools/agentic-5models-cpu.tsv.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2026 Bernard Ladenthin + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/ai-index-benchmark/tools/agentic-bench.sh b/docs/ai-index-benchmark/tools/agentic-bench.sh new file mode 100644 index 0000000..5cd87c6 --- /dev/null +++ b/docs/ai-index-benchmark/tools/agentic-bench.sh @@ -0,0 +1,55 @@ +#!/usr/bin/env bash +# SPDX-FileCopyrightText: 2026 Bernard Ladenthin +# +# SPDX-License-Identifier: Apache-2.0 +# +# Agentic reaction-time bench for local GGUF models via llama-server (tool-calling). +# Usage: agentic_bench.sh [model2.gguf ...] +set -uo pipefail +LS="/c/Users/berna/AppData/Local/Microsoft/WinGet/Packages/ggml.llamacpp_Microsoft.Winget.Source_8wekyb3d8bbwe/llama-server.exe" +MODELDIR="X:/Modelle" +PORT=8090 +HERE="$(dirname "$0")" +OUT="$1"; shift +export PATH="/c/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v13.3/bin:/c/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v13.3/bin/x64:$PATH" +printf "model\tload_s\tttft_ms\tprefill_tps\tdecode_tps\ttool_ok\tnotes\n" > "$OUT" + +EXPECT="run_tests" +REQ='{"messages":[{"role":"user","content":"Run the unit tests for the module named auth, then tell me you are done. Use the available tool."}],"tools":[{"type":"function","function":{"name":"run_tests","description":"Run unit tests for a given module and return pass/fail","parameters":{"type":"object","properties":{"module":{"type":"string","description":"the module name to test"}},"required":["module"]}}}],"tool_choice":"auto","temperature":0,"max_tokens":200,"cache_prompt":false}' + +try_model() { # model ngl -> sets READY/LOAD_S, leaves server running if ready + local mpath="$1" ngl="$2" log="$3" + taskkill //F //IM llama-server.exe >/dev/null 2>&1; sleep 1 + "$LS" -m "$mpath" --host 127.0.0.1 --port $PORT -c 4096 -ngl $ngl --jinja --no-webui > "$log" 2>&1 & + local t0=$(date +%s); READY=0 + for i in $(seq 1 240); do + curl -s "http://127.0.0.1:$PORT/health" 2>/dev/null | grep -qi '"status":"ok"' && { READY=1; break; } + grep -qiE "error loading|failed to fit|out of memory|unable to load|abort" "$log" 2>/dev/null && break + sleep 1 + done + LOAD_S=$(( $(date +%s) - t0 )) +} + +for MODEL in "$@"; do + MPATH="$MODELDIR/$MODEL" + if [ ! -f "$MPATH" ]; then printf "%s\tNA\tNA\tNA\tNA\tNA\tmissing-file\n" "$MODEL" >> "$OUT"; continue; fi + SZ=$(stat -c%s "$MPATH") + USED_NGL=0 + if [ "$SZ" -lt 7000000000 ]; then + try_model "$MPATH" 999 "$HERE/srv-$MODEL.log"; USED_NGL=999 + if [ "$READY" != 1 ]; then # GPU didn't fit -> CPU fallback + try_model "$MPATH" 0 "$HERE/srv-$MODEL.log"; USED_NGL=0 + fi + else + try_model "$MPATH" 0 "$HERE/srv-$MODEL.log"; USED_NGL=0 + fi + if [ "$READY" = 1 ]; then + curl -s "http://127.0.0.1:$PORT/v1/chat/completions" -H "Content-Type: application/json" -d "$REQ" >/dev/null 2>&1 # warmup + resp=$(curl -s -w $'\nTOTAL:%{time_total}' "http://127.0.0.1:$PORT/v1/chat/completions" -H "Content-Type: application/json" -d "$REQ" 2>/dev/null) + printf '%s' "$resp" | python "$HERE/parse_agentic.py" "$MODEL(ngl=$USED_NGL)" "$LOAD_S" "$EXPECT" >> "$OUT" + else + printf "%s\t%s\tNA\tNA\tNA\tNA\tload-failed\n" "$MODEL(ngl=$USED_NGL)" "$LOAD_S" >> "$OUT" + fi + taskkill //F //IM llama-server.exe >/dev/null 2>&1; sleep 2 +done +echo "AGENTIC BENCH DONE" >> "$OUT" diff --git a/docs/ai-index-benchmark/tools/agentic-cpu-ctx.sh b/docs/ai-index-benchmark/tools/agentic-cpu-ctx.sh new file mode 100644 index 0000000..235c6b5 --- /dev/null +++ b/docs/ai-index-benchmark/tools/agentic-cpu-ctx.sh @@ -0,0 +1,57 @@ +#!/usr/bin/env bash +# SPDX-FileCopyrightText: 2026 Bernard Ladenthin +# +# SPDX-License-Identifier: Apache-2.0 +# +# CPU agentic reaction-time vs context-fill, for a fixed model set. Loads each model ONCE, +# then measures a tool-call at several context sizes. +# Usage: agentic_cpu_ctx.sh [ ...] +set -uo pipefail +LS="/c/Users/berna/AppData/Local/Microsoft/WinGet/Packages/ggml.llamacpp_Microsoft.Winget.Source_8wekyb3d8bbwe/llama-server.exe" +MODELDIR="X:/Modelle"; PORT=8090; HERE="$(dirname "$0")" +OUT="$1"; shift +EXPECT="run_tests" +FILL_LEVELS="${FILL_LEVELS:-512 3072 16384}" # override via env for finer sweeps +printf "model\tctx_target\tprompt_n\tload_s\tttft_ms\tprefill_tps\tdecode_tps\ttool_ok\tnotes\n" > "$OUT" + +build_req() { # target_tokens -> writes $HERE/req.json (filler code ~target tokens, then the tool task) + python - "$1" <<'PY' > "$HERE/req.json" +import sys, json +target = int(sys.argv[1]) +line = " public final int f%d = compute(a%d, b%d) + offset; // context filler line %d\n" +buf, i, s, approx = [], 0, 0, int(target * 3.4) +while s < approx: + ln = line % (i, i, i, i); buf.append(ln); s += len(ln); i += 1 +user = ("// Large Java source under review:\n" + "".join(buf) + + "\n\nNow: run the unit tests for the module named auth, then say you are done. Use the available tool.") +req = {"messages":[{"role":"user","content":user}], + "tools":[{"type":"function","function":{"name":"run_tests","description":"Run unit tests for a given module","parameters":{"type":"object","properties":{"module":{"type":"string"}},"required":["module"]}}}], + "tool_choice":"auto","temperature":0,"max_tokens":120,"cache_prompt":False} +print(json.dumps(req)) +PY +} + +for ENTRY in "$@"; do + MODEL="${ENTRY%%:*}"; MAXC="${ENTRY##*:}" + MPATH="$MODELDIR/$MODEL" + [ -f "$MPATH" ] || { printf "%s\tNA\tNA\tNA\tNA\tNA\tNA\tNA\tmissing\n" "$MODEL" >> "$OUT"; continue; } + CTX=$MAXC; [ "$CTX" -gt 17408 ] && CTX=17408 # cap allocation + taskkill //F //IM llama-server.exe >/dev/null 2>&1; sleep 1 + t0=$(date +%s); ready=0 + "$LS" -m "$MPATH" --host 127.0.0.1 --port $PORT -c $CTX -ngl ${NGL:-0} ${DEVICE:-} --jinja --no-webui > "$HERE/srv-$MODEL.log" 2>&1 & + for i in $(seq 1 300); do + curl -s "http://127.0.0.1:$PORT/health" 2>/dev/null | grep -qi '"status":"ok"' && { ready=1; break; } + grep -qiE "error loading|failed to fit|out of memory|abort" "$HERE/srv-$MODEL.log" 2>/dev/null && break + sleep 1 + done + LOAD_S=$(( $(date +%s) - t0 )) + if [ "$ready" != 1 ]; then printf "%s\tNA\tNA\t%s\tNA\tNA\tNA\tNA\tload-failed\n" "$MODEL" "$LOAD_S" >> "$OUT"; taskkill //F //IM llama-server.exe >/dev/null 2>&1; continue; fi + for LVL in $FILL_LEVELS; do + [ "$LVL" -gt $((CTX - 300)) ] && continue + build_req "$LVL" + resp=$(curl -s -w $'\nTOTAL:%{time_total}' "http://127.0.0.1:$PORT/v1/chat/completions" -H "Content-Type: application/json" -d @"$HERE/req.json" 2>/dev/null) + printf '%s' "$resp" | python "$HERE/parse_ctx.py" "$MODEL" "$LVL" "$LOAD_S" "$EXPECT" >> "$OUT" + done + taskkill //F //IM llama-server.exe >/dev/null 2>&1; sleep 2 +done +echo "CPU CTX BENCH DONE" >> "$OUT" diff --git a/docs/ai-index-benchmark/tools/agentic-gptoss-vulkan-gpu.tsv b/docs/ai-index-benchmark/tools/agentic-gptoss-vulkan-gpu.tsv new file mode 100644 index 0000000..cbe3178 --- /dev/null +++ b/docs/ai-index-benchmark/tools/agentic-gptoss-vulkan-gpu.tsv @@ -0,0 +1,8 @@ +model ctx_target prompt_n load_s ttft_ms prefill_tps decode_tps tool_ok notes +gpt-oss-20b-mxfp4.gguf 512 679 9 8548 79.4 9.7 YES total=14.927341s +gpt-oss-20b-mxfp4.gguf 2048 2239 9 11489 194.9 10.3 YES total=17.054640s +gpt-oss-20b-mxfp4.gguf 4096 4231 9 17991 235.2 10.3 YES total=21.968893s +gpt-oss-20b-mxfp4.gguf 8192 8143 9 34454 236.3 8.8 YES total=39.136789s +gpt-oss-20b-mxfp4.gguf 12288 12079 9 57485 210.1 7.5 YES total=62.994654s +gpt-oss-20b-mxfp4.gguf 16384 16015 9 80680 198.5 6.6 YES total=86.744817s +CPU CTX BENCH DONE diff --git a/docs/ai-index-benchmark/tools/agentic-gptoss-vulkan-gpu.tsv.license b/docs/ai-index-benchmark/tools/agentic-gptoss-vulkan-gpu.tsv.license new file mode 100644 index 0000000..ac8b117 --- /dev/null +++ b/docs/ai-index-benchmark/tools/agentic-gptoss-vulkan-gpu.tsv.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2026 Bernard Ladenthin + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/ai-index-benchmark/tools/agentic-htiny-vs-gptoss-cpu.tsv b/docs/ai-index-benchmark/tools/agentic-htiny-vs-gptoss-cpu.tsv new file mode 100644 index 0000000..55b5139 --- /dev/null +++ b/docs/ai-index-benchmark/tools/agentic-htiny-vs-gptoss-cpu.tsv @@ -0,0 +1,14 @@ +model ctx_target prompt_n load_s ttft_ms prefill_tps decode_tps tool_ok notes +granite-4.0-h-tiny-Q4_K_M.gguf 512 740 7 5745 128.8 10.2 YES total=7.717564s +granite-4.0-h-tiny-Q4_K_M.gguf 2048 2300 7 8231 279.4 10.7 YES total=10.108102s +granite-4.0-h-tiny-Q4_K_M.gguf 4096 4292 7 12767 336.2 10.0 YES total=14.778657s +granite-4.0-h-tiny-Q4_K_M.gguf 8192 8204 7 23160 354.2 9.7 YES total=25.246700s +granite-4.0-h-tiny-Q4_K_M.gguf 12288 12140 7 33353 364.0 9.5 YES total=35.495100s +granite-4.0-h-tiny-Q4_K_M.gguf 16384 16076 7 43887 366.3 9.0 YES total=46.147984s +gpt-oss-20b-mxfp4.gguf 512 679 14 10196 66.6 7.1 YES total=18.995332s +gpt-oss-20b-mxfp4.gguf 2048 2239 14 13410 167.0 6.3 YES total=22.485719s +gpt-oss-20b-mxfp4.gguf 4096 4231 14 21033 201.2 6.1 YES total=27.775887s +gpt-oss-20b-mxfp4.gguf 8192 8143 14 40143 202.8 5.0 YES total=48.335635s +gpt-oss-20b-mxfp4.gguf 12288 12079 14 67437 179.1 3.8 YES total=78.135913s +gpt-oss-20b-mxfp4.gguf 16384 16015 14 92994 172.2 3.5 YES total=104.321550s +CPU CTX BENCH DONE diff --git a/docs/ai-index-benchmark/tools/agentic-htiny-vs-gptoss-cpu.tsv.license b/docs/ai-index-benchmark/tools/agentic-htiny-vs-gptoss-cpu.tsv.license new file mode 100644 index 0000000..ac8b117 --- /dev/null +++ b/docs/ai-index-benchmark/tools/agentic-htiny-vs-gptoss-cpu.tsv.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2026 Bernard Ladenthin + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/ai-index-benchmark/tools/agentic-htiny-vulkan-gpu.tsv b/docs/ai-index-benchmark/tools/agentic-htiny-vulkan-gpu.tsv new file mode 100644 index 0000000..23d599e --- /dev/null +++ b/docs/ai-index-benchmark/tools/agentic-htiny-vulkan-gpu.tsv @@ -0,0 +1,8 @@ +model ctx_target prompt_n load_s ttft_ms prefill_tps decode_tps tool_ok notes +granite-4.0-h-tiny-Q4_K_M.gguf 512 740 5 487 1520.8 120.1 YES total=0.667318s +granite-4.0-h-tiny-Q4_K_M.gguf 2048 2300 5 865 2660.3 120.5 YES total=1.045918s +granite-4.0-h-tiny-Q4_K_M.gguf 4096 4292 5 1462 2935.9 123.4 YES total=1.641884s +granite-4.0-h-tiny-Q4_K_M.gguf 8192 8204 5 2642 3105.7 118.2 YES total=2.832818s +granite-4.0-h-tiny-Q4_K_M.gguf 12288 12140 5 3887 3123.4 118.8 YES total=4.081778s +granite-4.0-h-tiny-Q4_K_M.gguf 16384 16076 5 5160 3115.3 112.2 YES total=5.370496s +CPU CTX BENCH DONE diff --git a/docs/ai-index-benchmark/tools/agentic-htiny-vulkan-gpu.tsv.license b/docs/ai-index-benchmark/tools/agentic-htiny-vulkan-gpu.tsv.license new file mode 100644 index 0000000..ac8b117 --- /dev/null +++ b/docs/ai-index-benchmark/tools/agentic-htiny-vulkan-gpu.tsv.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2026 Bernard Ladenthin + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/ai-index-benchmark/tools/calibrate-bench-pom.xml b/docs/ai-index-benchmark/tools/calibrate-bench-pom.xml new file mode 100644 index 0000000..d8554c6 --- /dev/null +++ b/docs/ai-index-benchmark/tools/calibrate-bench-pom.xml @@ -0,0 +1,25 @@ + +4.0.0 + benchbench1pom + + X:/Modelle/granite-4.0-h-small-UD-Q4_K_XL.gguf + 163840 + 0.04 + + + net.ladenthinllamacpp-ai-index-maven-plugin1.0.3-SNAPSHOT + net.ladenthinllama5.0.4cuda13-windows-x86-64 + + llamacpp-jni + p + m${bench.model} + ${bench.ctx}${bench.ngl}256 + ${bench.temp}8${bench.cpt} + 1.000.01.0${bench.effort} + javapm + .java + diff --git a/docs/ai-index-benchmark/tools/context-scaling-sweep.tsv b/docs/ai-index-benchmark/tools/context-scaling-sweep.tsv new file mode 100644 index 0000000..6bed141 --- /dev/null +++ b/docs/ai-index-benchmark/tools/context-scaling-sweep.tsv @@ -0,0 +1,19 @@ +hsmall 2048 75 17.02 +hsmall 2048 760 137.09 +hsmall 2048 1349 169.11 +gptoss 2048 137 76.35 +gptoss 2048 538 473.13 +gptoss 2048 956 605.13 +hsmall 4096 75 19.30 +hsmall 4096 1691 170.84 +hsmall 4096 3021 198.21 +gptoss 4096 137 89.34 +gptoss 4096 1241 558.10 +gptoss 4096 2210 592.39 +hsmall 8192 75 19.31 +hsmall 8192 3553 202.99 +hsmall 8192 6365 205.59 +gptoss 8192 137 77.79 +gptoss 8192 2628 287.19 +gptoss 8192 4718 226.06 +SWEEP DONE diff --git a/docs/ai-index-benchmark/tools/context-scaling-sweep.tsv.license b/docs/ai-index-benchmark/tools/context-scaling-sweep.tsv.license new file mode 100644 index 0000000..ac8b117 --- /dev/null +++ b/docs/ai-index-benchmark/tools/context-scaling-sweep.tsv.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2026 Bernard Ladenthin + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/ai-index-benchmark/tools/parse-agentic-ctx.py b/docs/ai-index-benchmark/tools/parse-agentic-ctx.py new file mode 100644 index 0000000..deda171 --- /dev/null +++ b/docs/ai-index-benchmark/tools/parse-agentic-ctx.py @@ -0,0 +1,36 @@ +# SPDX-FileCopyrightText: 2026 Bernard Ladenthin +# +# SPDX-License-Identifier: Apache-2.0 +import sys, json, re +model, ctx_target, load_s, expect_fn = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4] +raw = sys.stdin.read() +total = "NA" +m = re.search(r"TOTAL:([0-9.]+)", raw) +if m: total = m.group(1) +raw = re.sub(r"\nTOTAL:[0-9.]+", "", raw) + +def out(pn, ttft, ptps, dtps, ok, notes): + print(f"{model}\t{ctx_target}\t{pn}\t{load_s}\t{ttft}\t{ptps}\t{dtps}\t{ok}\t{notes}") + +try: + d = json.loads(raw) +except Exception: + out("NA","NA","NA","NA","ERR", "bad-json/"+raw[:40].replace(chr(9)," ").replace(chr(10)," ")); sys.exit() +if isinstance(d, dict) and d.get("error"): + out("NA","NA","NA","NA","ERR", str(d["error"])[:60]); sys.exit() + +msg = (d.get("choices") or [{}])[0].get("message", {}) +tcs = msg.get("tool_calls") or [] +fn = tcs[0]["function"]["name"] if tcs else None +content = msg.get("content") or "" +if fn == expect_fn: ok = "YES" +elif fn: ok = "WRONG:" + fn +elif expect_fn in content: ok = "TEXT" +else: ok = "NO" + +t = d.get("timings") or {} +pn = t.get("prompt_n", "NA") +ttft = round(t["prompt_ms"]) if "prompt_ms" in t else (round(float(total)*1000) if total != "NA" else "NA") +ptps = round(t["prompt_per_second"], 1) if t.get("prompt_per_second") else "NA" +dtps = round(t["predicted_per_second"], 1) if t.get("predicted_per_second") else "NA" +out(pn, ttft, ptps, dtps, ok, f"total={total}s") diff --git a/docs/ai-index-benchmark/tools/parse-agentic.py b/docs/ai-index-benchmark/tools/parse-agentic.py new file mode 100644 index 0000000..243bbe0 --- /dev/null +++ b/docs/ai-index-benchmark/tools/parse-agentic.py @@ -0,0 +1,47 @@ +# SPDX-FileCopyrightText: 2026 Bernard Ladenthin +# +# SPDX-License-Identifier: Apache-2.0 +import sys, json, re + +model = sys.argv[1]; load_s = sys.argv[2]; expect_fn = sys.argv[3] +raw = sys.stdin.read() +total = "NA" +m = re.search(r"TOTAL:([0-9.]+)", raw) +if m: total = m.group(1) +raw = re.sub(r"\nTOTAL:[0-9.]+", "", raw) + +def out(ttft, ptps, dtps, ok, notes): + print(f"{model}\t{load_s}\t{ttft}\t{ptps}\t{dtps}\t{ok}\t{notes}") + +try: + d = json.loads(raw) +except Exception: + out("NA","NA","NA","ERR", "bad-json/"+raw[:40].replace("\t"," ").replace("\n"," ")) + sys.exit() + +if isinstance(d, dict) and d.get("error"): + out("NA","NA","NA","ERR", str(d["error"])[:50]) + sys.exit() + +msg = (d.get("choices") or [{}])[0].get("message", {}) +tcs = msg.get("tool_calls") or [] +fn = tcs[0]["function"]["name"] if tcs else None +args = tcs[0]["function"].get("arguments") if tcs else None +# some models emit the call as text instead of native tool_calls -> detect fallback +content = msg.get("content") or "" +text_call = expect_fn in content if content else False +if fn == expect_fn: + ok = "YES" +elif fn: + ok = "WRONG-FN:" + fn +elif text_call: + ok = "TEXT" # emitted call as prose, not native tool_calls +else: + ok = "NO" + +t = d.get("timings") or {} +ttft = round(t["prompt_ms"]) if "prompt_ms" in t else (round(float(total)*1000) if total!="NA" else "NA") +ptps = round(t["prompt_per_second"],1) if t.get("prompt_per_second") else "NA" +dtps = round(t["predicted_per_second"],1) if t.get("predicted_per_second") else "NA" +notes = f"args={args}" if args else (f"total={total}s") +out(ttft, ptps, dtps, ok, notes[:60]) diff --git a/docs/ai-index-benchmark/tools/plot-context-curves.py b/docs/ai-index-benchmark/tools/plot-context-curves.py new file mode 100644 index 0000000..1ff0bfa --- /dev/null +++ b/docs/ai-index-benchmark/tools/plot-context-curves.py @@ -0,0 +1,52 @@ +# SPDX-FileCopyrightText: 2026 Bernard Ladenthin +# +# SPDX-License-Identifier: Apache-2.0 +import sys, csv +import matplotlib +matplotlib.use("Agg") +import matplotlib.pyplot as plt + +tsv, outpng = sys.argv[1], sys.argv[2] +rows = [r for r in csv.DictReader(open(tsv), delimiter="\t") + if (r.get("prompt_n") or "").isdigit() and (r.get("ttft_ms") or "").lstrip("-").isdigit()] + +series = {} +for r in rows: + series.setdefault(r["model"], []).append(( + int(r["prompt_n"]), + int(r["ttft_ms"]) / 1000.0, + float(r["prefill_tps"]) if r["prefill_tps"] not in ("NA", "") else None, + )) +for m in series: + series[m].sort() + +label = { + "granite-4.0-h-tiny-Q4_K_M.gguf": "granite-4.0-h-tiny (1B-active, HYBRID/Mamba)", + "gpt-oss-20b-mxfp4.gguf": "gpt-oss-20b (3.6B-active, Transformer)", +} +color = {"granite-4.0-h-tiny-Q4_K_M.gguf": "#2e7d32", "gpt-oss-20b-mxfp4.gguf": "#c62828"} + +fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(13, 5.2)) +for m, pts in series.items(): + xs = [p[0] for p in pts] + ax1.plot(xs, [p[1] for p in pts], "o-", color=color.get(m), label=label.get(m, m), linewidth=2, markersize=6) + pf = [(p[0], p[2]) for p in pts if p[2] is not None] + if pf: + ax2.plot([p[0] for p in pf], [p[1] for p in pf], "o-", color=color.get(m), label=label.get(m, m), linewidth=2, markersize=6) + +ax1.set_title("Reaction time (TTFT) vs. context — CPU (Ryzen 7 5800H)", fontsize=12, weight="bold") +ax1.set_xlabel("Context in window (tokens) -> agent loads more files") +ax1.set_ylabel("Time to first action (seconds)") +ax1.grid(True, alpha=0.3); ax1.legend(fontsize=9) +ax1.axhline(y=5, color="gray", ls=":", alpha=0.6) +ax1.text(ax1.get_xlim()[1]*0.02, 5.3, "~5s: still tolerable", fontsize=8, color="gray") + +ax2.set_title("Prefill speed vs. context — CPU", fontsize=12, weight="bold") +ax2.set_xlabel("Context in window (tokens)") +ax2.set_ylabel("Prefill (tokens/second) — higher is better") +ax2.grid(True, alpha=0.3); ax2.legend(fontsize=9) + +fig.suptitle("Agentic with growing context: which model wins when? (CPU)", fontsize=13, weight="bold") +fig.tight_layout(rect=[0, 0, 1, 0.96]) +fig.savefig(outpng, dpi=130) +print("wrote", outpng) diff --git a/docs/ai-index-benchmark/tools/plot-cpu-vs-gpu-curves.py b/docs/ai-index-benchmark/tools/plot-cpu-vs-gpu-curves.py new file mode 100644 index 0000000..7b08123 --- /dev/null +++ b/docs/ai-index-benchmark/tools/plot-cpu-vs-gpu-curves.py @@ -0,0 +1,55 @@ +# SPDX-FileCopyrightText: 2026 Bernard Ladenthin +# +# SPDX-License-Identifier: Apache-2.0 +import sys, csv +import matplotlib +matplotlib.use("Agg") +import matplotlib.pyplot as plt + +cpu_tsv, htiny_vk, gptoss_vk, outpng = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4] + +def load(path, model_filter=None): + pts = [] + try: + for r in csv.DictReader(open(path), delimiter="\t"): + if (r.get("prompt_n") or "").isdigit() and (r.get("ttft_ms") or "").lstrip("-").isdigit(): + if model_filter and r["model"] != model_filter: + continue + pf = r.get("prefill_tps") + pts.append((int(r["prompt_n"]), int(r["ttft_ms"]) / 1000.0, + float(pf) if pf not in ("NA", "", None) else None)) + except FileNotFoundError: + pass + return sorted(pts) + +HT = "granite-4.0-h-tiny-Q4_K_M.gguf" +GO = "gpt-oss-20b-mxfp4.gguf" +series = [ + ("granite-h-tiny . GPU (Vulkan/3070)", load(htiny_vk, HT), "#2e7d32", "-", 2.4, "o"), + ("granite-h-tiny . CPU", load(cpu_tsv, HT), "#2e7d32", "--", 1.6, "o"), + ("gpt-oss-20b . GPU (Vulkan, partial)", load(gptoss_vk, GO), "#c62828", "-", 2.4, "s"), + ("gpt-oss-20b . CPU", load(cpu_tsv, GO), "#c62828", "--", 1.6, "s"), +] + +fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(13.5, 5.4)) +for name, pts, col, ls, lw, mk in series: + if not pts: continue + xs = [p[0] for p in pts] + ax1.plot(xs, [p[1] for p in pts], marker=mk, ls=ls, color=col, lw=lw, ms=6, label=name) + pf = [(p[0], p[2]) for p in pts if p[2] is not None] + if pf: + ax2.plot([p[0] for p in pf], [p[1] for p in pf], marker=mk, ls=ls, color=col, lw=lw, ms=6, label=name) + +for ax in (ax1, ax2): + ax.grid(True, alpha=0.3); ax.legend(fontsize=8.5) + ax.set_xlabel("Context in window (tokens) -> agent loads more files") +ax1.set_title("Reaction time (TTFT) vs. context", fontsize=12, weight="bold") +ax1.set_ylabel("Time to first action (seconds)") +ax1.axhline(y=1, color="gray", ls=":", alpha=0.6) +ax2.set_title("Prefill speed vs. context", fontsize=12, weight="bold") +ax2.set_ylabel("Prefill (tokens/second) - higher is better") + +fig.suptitle("granite-h-tiny vs gpt-oss-20b - CPU vs Vulkan GPU (RTX 3070 8GB, no CUDA)", fontsize=13, weight="bold") +fig.tight_layout(rect=[0, 0, 1, 0.95]) +fig.savefig(outpng, dpi=130) +print("wrote", outpng) diff --git a/pom.xml b/pom.xml index 27f196d..1ba6a22 100644 --- a/pom.xml +++ b/pom.xml @@ -1687,6 +1687,23 @@ SPDX-License-Identifier: Apache-2.0 0 1.0 + + + EXP-Granite-4.0-H-Small + X:/Modelle/granite-4.0-h-small-UD-Q4_K_XL.gguf + 16384 + 1536 + 0.0 + 8 + 4 + true + 1.0 + 0 + 1.0 + EXP-Qwen3-4B-Instruct-2507 X:/Modelle/Qwen3-4B-Instruct-2507-Q4_K_M.gguf