[
https://issues.apache.org/jira/browse/CAMEL-25714?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Claus Ibsen updated CAMEL-25714:
--------------------------------
Fix Version/s: 4.25.0
(was: 4.24.0)
> camel-jbang-mcp - camel_catalog_doc: a summary for each doc section, so an
> agent can tell which section to read
> ---------------------------------------------------------------------------------------------------------------
>
> Key: CAMEL-25714
> URL: https://issues.apache.org/jira/browse/CAMEL-25714
> Project: Camel
> Issue Type: Improvement
> Components: camel-jbang-mcp
> Reporter: Claus Ibsen
> Priority: Major
> Fix For: 4.25.0
>
>
> CAMEL-25541 gave the component answer of {{camel_catalog_doc}} the titles of
> the page sections ({{sections}}), and {{docPage=<section title>}} returns one
> section. An agent has to pick a section from its title alone, and many titles
> say little about what the section holds: the doc pages under {{components/}}
> (590) have about 5,000 {{==}} to {{====}} headings, and the most common
> titles are *Usage* (311 pages) and *Examples* (244). Usage is often the
> catch-all that holds what decides correctness, such as the mail
> {{useHeader*}} options.
> h3. Proposal
> * Let an AI go over every section of the doc pages and write a one-line
> summary of what the section holds, stored in the .adoc as a named attribute
> on the line above the heading:
> {code}
> [summary="TLS for imaps, pop3s and smtps: sslContextParameters, or JavaMail
> properties for STARTTLS"]
> === SSL support
> {code}
> ** Asciidoctor keeps an unknown named attribute on the section and renders
> nothing, so the website does not change.
> ** It sets no id, so the generated id ({{_ssl_support}}) and the xrefs to it
> keep working, unlike an explicit anchor before the heading.
> ** It moves with the heading when a section is renamed or moved, and it
> reaches the catalog copy of the page that {{camel_catalog_doc}} reads.
> ** One line, in double quotes (summaries have commas); a quote inside is
> written as backslash and quote.
> * {{camel_catalog_doc}} returns the summary with each section title. When a
> section has no summary, the first sentence of its text is the fallback.
> * Keep the summaries true: store a short hash of the section text with the
> summary (for example {{summary-hash=...}}), so a changed section can be told
> from an unchanged one and only the changed ones are summarized again.
> * A report, from a script or a goal of the camel-package-maven-plugin: per
> page and in total, how many sections have no summary and how many summaries
> are stale (the section text no longer matches the hash). It tells how far the
> AI pass has got and which sections it should do next. It reports and does not
> fail the build, so a doc fix does not break it.
> h3. Also
> * Return the parent of each section (the list is flat today: _Using the JSSE
> Configuration Utility_ does not say it is part of _SSL support_) and its
> size, so an agent knows what a {{docPage}} call will cost.
> * Fit the 16,000 character cap of the answer: 40 sections with a 100
> character summary are 4,000 characters, so the summaries may go only with the
> sections that rank first, or come from a table of contents call.
> * Rank the sections by the agent's question, not only by a substring of
> {{optionsFilter}}.
> * Small fixes: 28 headings use the closing form ({{=== Legacy ===}}) and the
> title keeps the trailing equal signs; 13 titles keep the doctitle attribute
> unresolved ("doctitle components").
> * Measure the effect with the agent benchmark: does the agent pick the
> section with the xslt header parameters, the mail {{useHeader*}} options, or
> {{camel.server.*}} for platform-http.
> Start with the component pages; the EIP, language, data format and user
> manual pages can follow.
> _Claude Code on behalf of davsclaus_
--
This message was sent by Atlassian Jira
(v10.3.26#10030026)
