Build:

Coverage:

Quality:

Security:

Package:

License:

Community:

llamacpp-ai-index-maven-plugin

A Maven plugin for generating hierarchical, AI-readable documentation of source code projects using local llama.cpp-compatible models. It creates structured .ai.md files per source file and aggregates them into package-level summaries for fast semantic navigation and retrieval.

Features

• Generate AI summaries for Java source files
• Extract keyword metadata for search and indexing
• Aggregate summaries at package level
• Uses local models via llama.cpp (no cloud dependency)
• Incremental updates (skips unchanged files)
• Optimized for AI-assisted code understanding

How It Works

The plugin runs in two phases.

1. File Generation (generate)

• Scans configured source directories
• Creates .ai.md files per source file
• Each file contains metadata header and markdown summary

2. Package Aggregation (aggregate-packages)

• Traverses generated .ai.md files
• Builds hierarchical package summaries
• Produces package.ai.md files

Example Output

### AiMdDocument.java
- H: 1.0
- C: A48CED8C
- D: 2026-03-15T23:31:52Z
- T: 2026-03-19T18:13:31Z
- G: 1.0.0
- X: file
- K: AiMdDocument, AiMdHeader, record, metadata, markdown
#### AiMdDocument.java
Represents a document consisting of a structured metadata header and a markdown body. Ensures non-null invariants and encapsulates AI-generated content.

Requirements

• Java 8+ (production code targets Java 8; CI builds on Java 8 via temurin)
• Maven 3.6.3+
• Local GGUF model (llama.cpp compatible)

Dependency

The plugin depends on net.ladenthin:llama, the Java/JNI binding for llama.cpp. It is published on Maven Central and resolves automatically — no manual installation required.

<dependency>
    <groupId>net.ladenthin</groupId>
    <artifactId>llama</artifactId>
    <version>5.0.2</version>
</dependency>

Configuration

Minimal setup in POM:

<properties>
    <ai.index.model.path>/path/to/model.gguf</ai.index.model.path>
    <ai.index.output.directory>${project.basedir}/src/site/ai</ai.index.output.directory>
</properties>

Usage

Run AI index generation:

mvn clean install -Pai-index-selftest

With native llama tests:

mvn clean install -Pai-index-selftest -DrunNativeLlamaTests=true

Plugin Configuration

Key parameters:

• outputDirectory: target directory for .ai.md files
• subtrees: source directories to index
• generationProvider: AI backend (llamacpp-jni)
• llamaModelPath: path to GGUF model
• llamaContextSize: context window
• llamaMaxTokens: output token limit
• llamaTemperature: sampling temperature
• llamaThreads: CPU threads

Prompt System

The plugin uses configurable prompts:

• file-summary
• file-keywords
• package-summary
• package-keywords Prompts are optimized to avoid code blocks, formatter artifacts, empty outputs, and produce structured markdown.

Output Structure

src/site/ai/
└── main/
    └── java/
        └── com/
            └── example/
                ├── MyClass.java.ai.md
                ├── AnotherClass.java.ai.md
                └── package.ai.md

Design Principles

• Deterministic metadata (hash-based change detection)
• Separation of concerns (header = metadata, body = summary)
• AI-friendly structure (predictable and hierarchical)
• Local-first (no external APIs required)

Known Limitations

• Model output may require normalization (handled in code)
• Large models increase runtime
• Output quality depends on chosen model

TODO

• Expand PIT mutation-testing scope. PIT is wired in pom.xml and runs on every CI build with <mutationThreshold>100</mutationThreshold>, but <targetClasses> is currently narrowed to a single class (AiCompletionParser). The intent is to exercise the wiring and gate against regressions on that single class today; widen <targetClasses> incrementally as additional classes reach mutation-test parity (i.e., add tests until 100% mutation coverage holds on the candidate class, then add it to the list). Final target: <param>net.ladenthin.maven.llamacpp.aiindex.*</param> matching the streambuffer pattern.

Recommended Models

• Qwen2.5 Coder (balanced quality and speed)
• Smaller instruct models for faster indexing

Development

⚠️ DO NOT UPGRADE jqwik past 1.9.3. jqwik 1.10.0 added an anti-AI prompt-injection string to test stdout; the 1.10.1 user guide states the library "is not meant to be used by any 'AI' coding agents at all." 1.9.3 is the last pre-disclosure release and is the pinned version. See CLAUDE.md section "jqwik prompt-injection in test output" for the full context.

Run full build:

mvn clean install

Skip AI generation:

mvn clean install -DaiIndex.skip=true

License

Apache License 2.0

---

🍺 Beer-driven architectural review (2026-05-26)

Sometimes you spend two beers debating "architektonisch" vs "architekturiell" and the only conclusion is: ship the code anyway. Cheers!