This is an automated email from the ASF dual-hosted git repository. davsclaus pushed a commit to branch CAMEL-26946-readme-ai-summary in repository https://gitbox.apache.org/repos/asf/camel.git
commit d1828f09125f6ecb94619c067d46dbc009e1624a Author: Claus Ibsen <[email protected]> AuthorDate: Fri Nov 13 23:44:17 2026 +0100 CAMEL-26946: camel-jbang - the readme tool of the AI panel gives the AI-written summary only when asked for, and says so Without a README, tui_get_readme answered with camel-summary.md, whose overview, capabilities, steps and route texts an AI wrote, often the same model a minute before. A note said so, but a local model in a benchmark repeated a mistake of that text as a fact (an app "validating the orders" when nothing in it validates). Now, without a README, the tool answers with the facts derived from the route sources as they are now (entry points, routes, flows, error handling, external systems), with aiWritten false. aiSummary=true gives camel-summary.md instead, with aiWritten true, the model and the date that wrote it, and upToDate false when the routes changed since. With a README nothing changes. The answer moves to a class of its own, ReadmeTool, as TuiToolRegistry is at the size limit of SourceSizeTest. The tool text is shorter than before, so the prompt prefix of every tool mode is about 10 tokens smaller. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Claus Ibsen <[email protected]> --- .../core/commands/tui/IntegrationSummaryDoc.java | 18 ++++ .../dsl/jbang/core/commands/tui/McpFacade.java | 25 +---- .../dsl/jbang/core/commands/tui/ReadmeTool.java | 114 +++++++++++++++++++++ .../core/commands/tui/TuiToolDefinitions.java | 11 +- .../jbang/core/commands/tui/TuiToolRegistry.java | 24 +---- .../core/commands/tui/ReadmeToolSummaryTest.java | 100 +++++++++++++++--- 6 files changed, 225 insertions(+), 67 deletions(-) diff --git a/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/IntegrationSummaryDoc.java b/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/IntegrationSummaryDoc.java index e6bf92f7fdbb..243c068640ae 100644 --- a/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/IntegrationSummaryDoc.java +++ b/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/IntegrationSummaryDoc.java @@ -90,6 +90,24 @@ final class IntegrationSummaryDoc { return new Doc("Integration summary ยท " + name + " (not saved)", forViewing(facts)); } + /** + * The facts of a project derived from its route sources as they are now, with nothing an AI wrote: what the readme + * tool of the AI panel gives when there is no README (CAMEL-26946). Null when there is no project or it has no + * routes. + */ + static String facts(Path dir) { + if (dir == null) { + return null; + } + ProjectOverview.Overview overview = ProjectOverview.analyze(dir, ProjectOverviewAssist.catalog()); + if (overview.flows().isEmpty()) { + return null; + } + return forViewing(IntegrationSummary.render(overview, null, null, null, null) + .replace("> Derived from the route sources. No AI-assisted sections yet.", + "> Derived from the route sources.")); + } + /** * The markdown for the viewer: without the comments that fence the AI sections and carry the header (they are for * tools), and with the routes table as a list, since the viewer gives table columns equal widths and would cut off diff --git a/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/McpFacade.java b/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/McpFacade.java index 617338fc226b..e0b9fcf597c7 100644 --- a/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/McpFacade.java +++ b/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/McpFacade.java @@ -42,7 +42,6 @@ import dev.tamboui.tui.event.KeyEvent; import dev.tamboui.tui.event.KeyModifiers; import dev.tamboui.widgets.tabs.TabsState; import org.apache.camel.dsl.jbang.core.commands.ai.AuthoringTools; -import org.apache.camel.dsl.jbang.core.commands.ai.IntegrationSummary; import org.apache.camel.dsl.jbang.core.commands.ai.SourceValidator; import org.apache.camel.dsl.jbang.core.commands.ai.ToolConfirms; import org.apache.camel.dsl.jbang.core.commands.ai.ToolExecutionException; @@ -1117,29 +1116,11 @@ class McpFacade { } /** - * The integration summary of an integration's project (CAMEL-25143), as the readme tool answers it when there is no - * README: the view without the tool comments, and whether it still matches the routes. Null when the project has - * none. + * The source directory of an integration's project (of the selected integration when no name is given), or null. */ - JsonObject getIntegrationSummary(String name) { + Path getSourceDirectory(String name) { IntegrationInfo target = findIntegration(name); - Path dir = target != null ? FilesBrowser.resolveSourceDirectory(target) : null; - if (dir == null || !Files.isRegularFile(dir.resolve(IntegrationSummary.FILE_NAME))) { - return null; - } - IntegrationSummaryDoc.Doc doc = IntegrationSummaryDoc.load(dir); - if (doc == null) { - return null; - } - JsonObject result = new JsonObject(); - result.put("file", IntegrationSummary.FILE_NAME); - result.put("content", doc.markdown()); - result.put("note", "The sections and route texts marked " + IntegrationSummary.AI_MARK - + " were written by an AI: say so when you repeat them; the rest is derived from the sources"); - if (doc.title().contains("out of date")) { - result.put("upToDate", false); - } - return result; + return target != null ? FilesBrowser.resolveSourceDirectory(target) : null; } /** The pid of the integration, or else the infra service, with the given name (alias) or pid. */ diff --git a/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/ReadmeTool.java b/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/ReadmeTool.java new file mode 100644 index 000000000000..e20c9eae70be --- /dev/null +++ b/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/ReadmeTool.java @@ -0,0 +1,114 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.camel.dsl.jbang.core.commands.tui; + +import java.nio.file.Files; +import java.nio.file.Path; + +import org.apache.camel.dsl.jbang.core.commands.ai.IntegrationSummary; +import org.apache.camel.util.json.JsonObject; +import org.apache.camel.util.json.Jsoner; + +/** + * What the readme tool of the AI panel ({@code tui_get_readme}) answers. The README of an integration; without one, the + * facts derived from its route sources, so a question about what the integration does starts from them instead of + * reading every file (CAMEL-25143). The project's integration summary, partly written by an AI, only when it is asked + * for, and saying so: a model takes back what an AI wrote there as facts, mistakes included (CAMEL-26946). + */ +final class ReadmeTool { + + private ReadmeTool() { + } + + static String answer(McpFacade facade, String name, boolean aiSummary) { + JsonObject readme = facade.getReadme(name); + Path dir = facade.getSourceDirectory(name); + if (readme == null) { + JsonObject summary = aiSummary ? aiSummary(dir) : null; + if (summary != null) { + return Jsoner.serialize(summary); + } + JsonObject facts = facts(dir); + if (facts != null) { + if (aiSummary) { + facts.put("note", "There is no " + IntegrationSummary.FILE_NAME + + " yet: /overview in the AI panel writes one"); + } + return Jsoner.serialize(facts); + } + return name != null + ? "No README found for integration '" + name + "'" + : "No README found for the selected integration"; + } + JsonObject result = new JsonObject(); + String content = readme.getString("content"); + result.put("file", readme.getStringOrDefault("file", "README")); + result.put("content", content != null ? content : ""); + if (dir != null && Files.isRegularFile(dir.resolve(IntegrationSummary.FILE_NAME))) { + result.put("alsoSee", IntegrationSummary.FILE_NAME + ": an AI-assisted summary of the project (camel_get_files)"); + } + return Jsoner.serialize(result); + } + + /** + * The project's integration summary: the view without the tool comments, whether an AI wrote parts of it and which + * model, and whether those parts still match the routes. Null when the project has none. + */ + static JsonObject aiSummary(Path dir) { + IntegrationSummary.Summary summary = IntegrationSummary.read(dir); + IntegrationSummaryDoc.Doc doc = summary != null ? IntegrationSummaryDoc.load(dir) : null; + if (doc == null) { + return null; + } + boolean aiWritten = !summary.ai().isEmpty(); + JsonObject result = new JsonObject(); + result.put("file", IntegrationSummary.FILE_NAME); + result.put("aiWritten", aiWritten); + if (aiWritten) { + if (summary.model() != null) { + result.put("model", summary.model()); + } + if (summary.date() != null) { + result.put("date", summary.date()); + } + result.put("note", "The sections and route texts marked " + IntegrationSummary.AI_MARK + + " were written by an AI and may be wrong: check them against the route sources, and say" + + " so when you repeat them; the rest is derived from the sources"); + } + result.put("content", doc.markdown()); + if (doc.title().contains("out of date")) { + result.put("upToDate", false); + } + return result; + } + + /** + * The facts of the project derived from its route sources as they are now: entry points, routes, flows, error + * handling and external systems, with nothing an AI wrote. Null when the project has no routes. + */ + static JsonObject facts(Path dir) { + String facts = IntegrationSummaryDoc.facts(dir); + if (facts == null) { + return null; + } + JsonObject result = new JsonObject(); + result.put("source", "the route sources"); + result.put("aiWritten", false); + result.put("content", facts); + return result; + } +} diff --git a/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/TuiToolDefinitions.java b/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/TuiToolDefinitions.java index 56ea1f700c96..cac1f7426bc3 100644 --- a/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/TuiToolDefinitions.java +++ b/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/TuiToolDefinitions.java @@ -483,12 +483,11 @@ final class TuiToolDefinitions { List.of("section")), r::callToggleTraceDisplay)); tools.add(tool(toolDef( "tui_get_readme", - "Returns the README/documentation content from a running integration, or its project's " - + "integration summary when there is no README. " - + "Useful for understanding what the integration does, its configuration, and usage. " - + "If no name is provided, returns the README for the currently selected integration.", - Map.of("name", propDef("string", - "Integration name. If omitted, uses the currently selected integration."))), + "The README of an integration; without one, the facts derived from its route sources, or with " + + "aiSummary=true camel-summary.md, partly AI-written (aiWritten).", + Map.of("name", propDef("string", "Integration name (default: the selected one)"), + "aiSummary", propDef("boolean", + "Without a README, camel-summary.md instead of the facts; only when the user asks"))), r::callGetReadme, READ_ONLY, CORE)); tools.add(tool(toolDef( "tui_infra", diff --git a/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/TuiToolRegistry.java b/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/TuiToolRegistry.java index 8d7183cfa62b..599e236d871a 100644 --- a/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/TuiToolRegistry.java +++ b/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/TuiToolRegistry.java @@ -38,7 +38,6 @@ import dev.tamboui.style.Style; import dev.tamboui.text.Line; import dev.tamboui.text.Span; import org.apache.camel.catalog.CamelCatalog; -import org.apache.camel.dsl.jbang.core.commands.ai.IntegrationSummary; import org.apache.camel.dsl.jbang.core.commands.ai.ToolConfirms; import org.apache.camel.dsl.jbang.core.commands.ai.ToolContext; import org.apache.camel.dsl.jbang.core.commands.ai.ToolDescriptor; @@ -1466,27 +1465,8 @@ class TuiToolRegistry { } String callGetReadme(Map<String, Object> args) { - String name = args.get("name") instanceof String s ? s : null; - JsonObject response = facade.getReadme(name); - JsonObject summary = facade.getIntegrationSummary(name); - if (response == null) { - // the project's generated README: an overview, capabilities and route texts, partly AI-assisted - if (summary != null) { - return Jsoner.serialize(summary); - } - return name != null - ? "No README found for integration '" + name + "'" - : "No README found for the selected integration"; - } - JsonObject result = new JsonObject(); - String content = response.getString("content"); - String file = response.getStringOrDefault("file", "README"); - result.put("file", file); - result.put("content", content != null ? content : ""); - if (summary != null) { - result.put("alsoSee", IntegrationSummary.FILE_NAME + ": an AI-assisted summary of the project (camel_get_files)"); - } - return Jsoner.serialize(result); + return ReadmeTool.answer(facade, args.get("name") instanceof String s ? s : null, + args.get("aiSummary") instanceof Boolean b && b); } private String callControl(Map<String, Object> args) { diff --git a/dsl/camel-jbang/camel-jbang-plugin-tui/src/test/java/org/apache/camel/dsl/jbang/core/commands/tui/ReadmeToolSummaryTest.java b/dsl/camel-jbang/camel-jbang-plugin-tui/src/test/java/org/apache/camel/dsl/jbang/core/commands/tui/ReadmeToolSummaryTest.java index 1abfce9d3793..83998ee62e16 100644 --- a/dsl/camel-jbang/camel-jbang-plugin-tui/src/test/java/org/apache/camel/dsl/jbang/core/commands/tui/ReadmeToolSummaryTest.java +++ b/dsl/camel-jbang/camel-jbang-plugin-tui/src/test/java/org/apache/camel/dsl/jbang/core/commands/tui/ReadmeToolSummaryTest.java @@ -27,14 +27,18 @@ import java.util.concurrent.atomic.AtomicReference; import org.apache.camel.catalog.DefaultCamelCatalog; import org.apache.camel.dsl.jbang.core.commands.ai.IntegrationSummary; import org.apache.camel.dsl.jbang.core.commands.ai.ProjectOverview; +import org.apache.camel.util.json.JsonObject; +import org.apache.camel.util.json.Jsoner; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.io.TempDir; -import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.assertj.core.api.Assertions.assertThat; /** - * The AI panel's readme tool gives the project's integration summary when there is no README, so a question about what - * the integration does starts from it instead of reading every file (CAMEL-25143). + * The AI panel's readme tool when there is no README: the facts derived from the route sources, so a question about + * what the integration does starts from them instead of reading every file (CAMEL-25143), and the project's summary, + * partly written by an AI, only when asked for and saying so, as a model takes back what an AI wrote there as facts + * (CAMEL-26946). */ class ReadmeToolSummaryTest { @@ -52,27 +56,89 @@ class ReadmeToolSummaryTest { return new TuiToolRegistry(facade); } - @Test - void summaryWhenThereIsNoReadme() throws Exception { + private void route(String uri) throws Exception { Files.writeString(project.resolve("orders.camel.yaml"), """ - route: id: orders from: - uri: timer:tick + uri: %s steps: - to: log:orders - """, StandardCharsets.UTF_8); - TuiToolRegistry registry = registry(); - assertTrue(registry.execute("tui_get_readme", new HashMap<>(Map.of("name", "shop"))).startsWith("No README found"), - "no summary yet: nothing to give"); + """.formatted(uri), StandardCharsets.UTF_8); + } + private void summary(String overview) throws Exception { ProjectOverview.Overview o = ProjectOverview.analyze(project, new DefaultCamelCatalog()); - IntegrationSummary.write(o, new IntegrationSummary.AiContent("Ticks orders.", List.of(), Map.of()), - o.fingerprint(), "m"); - String answer = registry.execute("tui_get_readme", new HashMap<>(Map.of("name", "shop"))); - assertTrue(answer.contains(IntegrationSummary.FILE_NAME), answer); - assertTrue(answer.contains("Ticks orders."), answer); - assertTrue(answer.contains("were written by an AI"), answer); - assertTrue(!answer.contains("ai:begin"), "tool comments left out: " + answer); + IntegrationSummary.write(o, new IntegrationSummary.AiContent(overview, List.of(), Map.of()), o.fingerprint(), "m"); + } + + private String readme(boolean aiSummary) throws Exception { + Map<String, Object> args = new HashMap<>(Map.of("name", "shop")); + if (aiSummary) { + args.put("aiSummary", true); + } + return registry().execute("tui_get_readme", args); + } + + private JsonObject readmeJson(boolean aiSummary) throws Exception { + return (JsonObject) Jsoner.deserialize(readme(aiSummary)); + } + + @Test + void factsFromTheSourcesWhenThereIsNoReadme() throws Exception { + route("timer:tick"); + + JsonObject answer = readmeJson(false); + assertThat(answer.getBoolean("aiWritten")).as(answer.toJson()).isFalse(); + assertThat(answer.getString("content")).contains("Derived from the route sources", "timer:tick"); + } + + @Test + void theAiSummaryOnlyWhenAskedForAndSayingSo() throws Exception { + route("timer:tick"); + summary("Ticks orders."); + + JsonObject facts = readmeJson(false); + assertThat(facts.getBoolean("aiWritten")).as(facts.toJson()).isFalse(); + assertThat(facts.getString("content")).as("what the AI wrote is left out") + .contains("timer:tick").doesNotContain("Ticks orders."); + + JsonObject ai = readmeJson(true); + assertThat(ai.getBoolean("aiWritten")).as(ai.toJson()).isTrue(); + assertThat(ai.getString("file")).isEqualTo(IntegrationSummary.FILE_NAME); + assertThat(ai.getString("model")).isEqualTo("m"); + assertThat(ai.getString("note")).contains("were written by an AI"); + assertThat(ai.getString("content")).as("tool comments left out") + .contains("Ticks orders.").doesNotContain("ai:begin"); + assertThat(ai).doesNotContainKey("upToDate"); + } + + @Test + void theFactsFollowTheSourcesAfterTheSummaryWasWritten() throws Exception { + route("timer:tick"); + summary("Ticks orders."); + route("timer:clock"); + + JsonObject facts = readmeJson(false); + assertThat(facts.getString("content")).contains("timer:clock").doesNotContain("timer:tick"); + + JsonObject ai = readmeJson(true); + assertThat(ai.getBoolean("upToDate")).as("the AI wrote its part for the routes before").isFalse(); + } + + @Test + void askingForTheAiSummaryWhenThereIsNone() throws Exception { + route("timer:tick"); + + JsonObject answer = readmeJson(true); + assertThat(answer.getBoolean("aiWritten")).as(answer.toJson()).isFalse(); + assertThat(answer.getString("note")).contains("There is no " + IntegrationSummary.FILE_NAME); + assertThat(answer.getString("content")).contains("timer:tick"); + } + + @Test + void noReadmeAndNoRoutes() throws Exception { + assertThat(readme(false)).startsWith("No README found"); + assertThat(readme(true)).startsWith("No README found"); } }
