From 208c63cf70fca290a17dcad9e52899cffb91e67a Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 26 Jun 2026 06:42:10 +0000 Subject: [PATCH 1/2] docs: align README and CLAUDE.md with the current single-body .ai.md format MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The .ai.md header carries only deterministic metadata (h,c,d,t,g,a,x) and all AI content now lives in one markdown body — there is no s/k field and no separate keyword extraction. Correct the stale docs to match the code: - README example output: drop the non-existent `- K:` header line and the `#### ` body shape; show the real header field order (incl. `- A:`), the `---` separator, and the blockquote-lead + `####` sections produced by the `file-body` prompt (AiMdHeaderCodec.write / AiMdDocumentCodec.write). - README prompt system: replace the file-summary/file-keywords/ package-summary/package-keywords list with the real `file-body` / `package-body` keys and how they are wired via promptDefinitions / fieldGenerations. - README: fix the keyword-extraction feature bullet and rename the `llamaMaxTokens` parameter to the real `llamaMaxOutputTokens`. - CLAUDE.md: replace "(with s/k filled)", "summary/keywords fields" and "fields (s, k)" with single-body wording. Docs-only; no production code touched. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01RvxJko6xiCx83LxKgj92mH --- CLAUDE.md | 10 +++++----- README.md | 32 +++++++++++++++++++++----------- 2 files changed, 26 insertions(+), 16 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index dc36e57..a3461e3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -124,12 +124,12 @@ The plugin operates in two logical phases: **Phase 1 — File Indexing & Summarization** ``` -[Source .java files] → SourceFileIndexer → [*.java.ai.md files (with s/k filled)] +[Source .java files] → SourceFileIndexer → [*.java.ai.md files (deterministic header + AI body)] ``` **Phase 2 — Package Aggregation & Summarization** ``` -[*.java.ai.md files] → PackageIndexer → [package.ai.md files (with s/k filled)] +[*.java.ai.md files] → PackageIndexer → [package.ai.md files (deterministic header + AI body)] ``` ### Key Components @@ -203,8 +203,8 @@ the header machine-parseable without AI involvement (see | Goal | Description | |---|---| -| `ai-index:generate` | Phase 1: index source files and fill AI summary/keywords fields | -| `ai-index:aggregate-packages` | Phase 2: aggregate package index files and fill AI summary/keywords fields | +| `ai-index:generate` | Phase 1: index source files and fill the AI-generated document body | +| `ai-index:aggregate-packages` | Phase 2: aggregate package index files and fill the AI-generated document body | ### Key Parameters (`GenerateMojo`) @@ -326,7 +326,7 @@ See [`../workspace/workflows/pull-request-workflow.md`](../workspace/workflows/p ## Key Design Principles 1. **Local-first** — all AI inference runs locally via llama.cpp; no cloud API calls, no data leaves the machine. -2. **Deterministic indexing** — same source produces the same `.ai.md` skeleton; only AI-generated fields (`s`, `k`) vary. +2. **Deterministic indexing** — same source produces the same `.ai.md` skeleton (deterministic header); only the AI-generated body varies. 3. **Incremental updates** — files with existing summaries are skipped unless `force=true`; checksums detect source changes. 4. **Unified indexing and summarization** — each indexer (`SourceFileIndexer`, `PackageIndexer`) both creates the `.ai.md` skeleton and fills in AI fields in a single pass; no separate summarization step is needed. 5. **Provider abstraction** — AI backends are pluggable through `AiGenerationProvider`; mock provider enables fully deterministic tests. diff --git a/README.md b/README.md index 4d56359..f245c4b 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,7 @@ A Maven plugin for generating hierarchical, AI-readable documentation of source 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 +- Weave searchable type, API and domain names into every summary - Aggregate summaries at package level - Uses local models via llama.cpp (no cloud dependency) - Incremental updates (skips unchanged files) @@ -100,10 +100,20 @@ The plugin runs in two phases. - D: 2026-03-15T23:31:52Z - T: 2026-03-19T18:13:31Z - G: 1.0.0 +- A: 0.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. +--- +> Immutable value type pairing a deterministic metadata header with the AI-generated markdown body of one .ai.md document. + +#### Purpose +- Hold one parsed `.ai.md` document as an `AiMdHeader` plus its markdown body. + +#### Type +- record-shaped value class (Java); marked `@ConvertToRecord`. + +#### Public API +- `header() -> AiMdHeader` — the document's metadata header. +- `body() -> String` — the AI-generated markdown body. ``` ## Requirements - Java 8+ (production code targets Java 8; CI builds on Java 8 via temurin) @@ -146,16 +156,16 @@ Key parameters: - generationProvider: AI backend (`llamacpp-jni`) - llamaModelPath: path to GGUF model - llamaContextSize: context window -- llamaMaxTokens: output token limit +- llamaMaxOutputTokens: 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. +Prompts are defined in the plugin configuration (``) and referenced by key +from ``. The self-test profile defines two: +- `file-body` — summarizes a single source file +- `package-body` — synthesizes a package summary from the already-generated file summaries +Each summary begins with a one-sentence blockquote lead, followed by structured `####` sections. +Prompts are optimized to avoid code blocks, formatter artifacts, and empty outputs, and to produce structured markdown. ## Output Structure ``` src/site/ai/ From 72040daad8c3e07328546c02b9d9da3dd5768246 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 26 Jun 2026 06:48:17 +0000 Subject: [PATCH 2/2] docs(README): rewrite Configuration to the real aiDefinitions/fieldGenerations setup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The old "Configuration" section showed a `` minimal setup with `ai.index.model.path` — a property nothing in the code or POM reads — and hid that `` is mandatory (SourceFileIndexer/PackageIndexer throw IllegalArgumentException when it is absent). Replace it with the actual, working mechanism, verified against the ai-index-selftest profile in pom.xml: - Explain the three building blocks: (models by key), (templates by key, two %s placeholders), and (per goal: promptKey -> aiDefinitionKey, required). - Provide a complete, runnable example with both executions bound to generate-resources / process-resources (matching the self-test profile). - Rework the "Plugin Configuration" parameter list: drop the misleading top-level llama* model parameters (a non-functional fallback — model params come from ), add fileExtensions/force/skip/aiDefinitions/ promptDefinitions/fieldGenerations with their real defaults. Docs-only; no production code touched. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01RvxJko6xiCx83LxKgj92mH --- README.md | 116 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 101 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index f245c4b..b86f1a6 100644 --- a/README.md +++ b/README.md @@ -133,12 +133,95 @@ It is published on Maven Central and resolves automatically — no manual instal ``` ## Configuration -Minimal setup in POM: -``` - - /path/to/model.gguf - ${project.basedir}/src/site/ai - +The plugin is configured from three building blocks, declared on the plugin inside +``: + +1. **``** — define each GGUF model once (path + sampling parameters), each with a ``. +2. **``** — define each prompt template once, each with a ``. A template takes + two `%s` placeholders: the file/package name and the source (or, for packages, the child summaries). +3. **``** — per goal, map one `` to one ``. This is + **required**: a goal with no field generation fails fast. + +```xml + + net.ladenthin + llamacpp-ai-index-maven-plugin + 1.0.0 + + + + + src/main/java/com/example + + + llamacpp-jni + + + + + coder + /path/to/model.gguf + 32768 + 1536 + 0.7 + 8 + + + + + + + file-body + + + + package-body + + + + + + + + + ai-generate + generate-resources + generate + + + + file-body + coder + + + + + + ai-aggregate-packages + process-resources + aggregate-packages + + + + package-body + coder + + + + + + ``` ## Usage Run AI index generation: @@ -150,15 +233,18 @@ 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 -- llamaMaxOutputTokens: output token limit -- llamaTemperature: sampling temperature -- llamaThreads: CPU threads +Run-level parameters (set in ``): +- `outputDirectory` — target directory for `.ai.md` files (default: `${project.basedir}/src/site/ai`) +- `subtrees` — source directories to index, relative to the project base dir (default: `src/main/java`) +- `fileExtensions` — file extensions to index (default: `.java`) +- `generationProvider` — AI backend: `mock` (default) or `llamacpp-jni` +- `force` — regenerate even when a body already exists (default: `false`) +- `skip` — skip the goal entirely (default: `false`) +- `aiDefinitions` / `promptDefinitions` — named models / prompt templates, referenced by key +- `fieldGenerations` — per goal: which `promptKey` runs with which `aiDefinitionKey` (**required**) + +Per-model parameters — model path, context size, output tokens, temperature, top-p / top-k, +repeat penalty, threads — live inside each ``, not as top-level parameters. ## Prompt System Prompts are defined in the plugin configuration (``) and referenced by key from ``. The self-test profile defines two: