This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new 6e8008a2dbf7 CAMEL-26946: camel-jbang - the readme tool of the AI
panel gives the AI-written summary only when asked for, and says so (#29891)
6e8008a2dbf7 is described below
commit 6e8008a2dbf7ea0e0b104a02d58a14a2f70b6ee0
Author: Claus Ibsen <[email protected]>
AuthorDate: Sat Nov 14 08:50:32 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 (#29891)
The readme tool of the AI panel (tui_get_readme) no longer answers with the
AI-written camel-summary.md when an integration has no README. A local model
repeated a mistake from that text as a fact.
- Without a README the tool answers with the facts derived from the route
sources as they are now: entry points, routes, flows between routes, error
handling and external systems, with "aiWritten": false.
- aiSummary=true returns camel-summary.md with "aiWritten": true, the model
and date that wrote it, and "upToDate": false when the routes changed since.
- With a README nothing changes. A project with neither a README nor a
summary now gets the facts instead of "No README found".
- The answer moves to ReadmeTool, as TuiToolRegistry is at the size limit
of SourceSizeTest.
Co-Authored-By: Claude Opus 5.5 <[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");
}
}