[
https://issues.apache.org/jira/browse/CAMEL-24708?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Claus Ibsen updated CAMEL-24708:
--------------------------------
Description:
Add a compact API reference for the core Camel classes a route author's Java or
Groovy code touches, shipped in camel-catalog and exposed through the
camel-jbang-mcp tools (camel_catalog_doc with kind=api, or a camel_catalog_api
tool), so that an AI assistant, in particular a small local model, can look the
API up before writing code instead of guessing.
Evidence (benchmark of AI-assisted route authoring against camel-jbang-mcp,
2026-09-13, 18 runs with a local 35B model): 7 of the 109 defects found were
the model not knowing the Camel API rather than the DSL: oldExchange is null on
the first aggregation call, ${body.type} on a Map body, a bean with several
methods and no method name, a bean name used as a Groovy variable, a
two-parameter bean method called with only the body, exchange.setHeader(...)
called on the Exchange, the Groovy script variables. Each cost one to three
correction rounds; the answer was put into an error message every time, a tool
would give it up front.
What it should return: not the javadoc, a card per class with one line per
method and the one-line usage a route author needs, about 60 lines in total
(2-3k tokens):
- Exchange: getMessage() (getIn() is its alias), getProperty/setProperty,
getVariable, getContext, getException, isFailed; "the body and headers are on
the message"
- Message: getBody(Class), setBody, getHeader(name, Class), setHeader,
getHeaders, removeHeader
- CamelContext: getRegistry, createProducerTemplate, resolveLanguage; Registry:
lookupByName, lookupByNameAndType, bind
- Processor, AggregationStrategy (with the first-call rule: oldExchange ==
null, return newExchange), Predicate, Expression
- the Groovy script variables (exchange, message, body, headers, variables,
exchangeProperties, camelContext, request, log) and how to reach a registry
bean from a script
- a short "Camel 4 changes" block for models trained on older Camel (no
getOut(), header constants, getMessage())
Source: a curated list of about ten classes in camel-catalog, generated at
build from the javadoc of the real methods so it cannot drift, plus a
hand-written "common mistakes" block per class. Stored next to the bean
metadata (org/apache/camel/catalog/api/*.json), so any tool and IDE can use it.
Frontier models mostly know this API and will rarely call the tool, which costs
nothing; they do get Camel-version details wrong, which the Camel 4 block
addresses. For a local model it is the missing piece for anything with a Java
or Groovy bean. The validator messages of CAMEL-24698/CAMEL-24703 can then
point to the tool instead of restating the API.
was:
Add a compact API reference for the core Camel classes a route author's Java or
Groovy code touches, shipped in camel-catalog and exposed through the
camel-jbang-mcp / camel tui tools (camel_catalog_doc with kind=api, or a
camel_catalog_api tool), so that an AI assistant, in particular a small local
model, can look the API up before writing code instead of guessing.
Evidence (benchmark of AI-assisted route authoring against camel-jbang-mcp,
2026-09-13, 18 runs with a local 35B model): 7 of the 109 defects found were
the model not knowing the Camel API rather than the DSL: oldExchange is null on
the first aggregation call, ${body.type} on a Map body, a bean with several
methods and no method name, a bean name used as a Groovy variable, a
two-parameter bean method called with only the body, exchange.setHeader(...)
called on the Exchange, the Groovy script variables. Each cost one to three
correction rounds; the answer was put into an error message every time, a tool
would give it up front.
What it should return: not the javadoc, a card per class with one line per
method and the one-line usage a route author needs, about 60 lines in total
(2-3k tokens):
- Exchange: getMessage() (getIn() is its alias), getProperty/setProperty,
getVariable, getContext, getException, isFailed; "the body and headers are on
the message"
- Message: getBody(Class), setBody, getHeader(name, Class), setHeader,
getHeaders, removeHeader
- CamelContext: getRegistry, createProducerTemplate, resolveLanguage; Registry:
lookupByName, lookupByNameAndType, bind
- Processor, AggregationStrategy (with the first-call rule: oldExchange ==
null, return newExchange), Predicate, Expression
- the Groovy script variables (exchange, message, body, headers, variables,
exchangeProperties, camelContext, request, log) and how to reach a registry
bean from a script
- a short "Camel 4 changes" block for models trained on older Camel (no
getOut(), header constants, getMessage())
Source: a curated list of about ten classes in camel-catalog, generated at
build from the javadoc of the real methods so it cannot drift, plus a
hand-written "common mistakes" block per class. Stored next to the bean
metadata (org/apache/camel/catalog/api/*.json), so any tool and IDE can use it.
Frontier models mostly know this API and will rarely call the tool, which costs
nothing; they do get Camel-version details wrong, which the Camel 4 block
addresses. For a local model it is the missing piece for anything with a Java
or Groovy bean. The validator messages of CAMEL-24698/CAMEL-24703 can then
point to the tool instead of restating the API.
> camel-catalog - a compact API reference of the core classes (Exchange,
> Message, CamelContext, Registry, AggregationStrategy...) for AI assistants,
> exposed as a catalog tool
> ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
>
> Key: CAMEL-24708
> URL: https://issues.apache.org/jira/browse/CAMEL-24708
> Project: Camel
> Issue Type: Improvement
> Components: camel-catalog, camel-jbang
> Reporter: Claus Ibsen
> Priority: Major
>
> Add a compact API reference for the core Camel classes a route author's Java
> or Groovy code touches, shipped in camel-catalog and exposed through the
> camel-jbang-mcp tools (camel_catalog_doc with kind=api, or a
> camel_catalog_api tool), so that an AI assistant, in particular a small local
> model, can look the API up before writing code instead of guessing.
> Evidence (benchmark of AI-assisted route authoring against camel-jbang-mcp,
> 2026-09-13, 18 runs with a local 35B model): 7 of the 109 defects found were
> the model not knowing the Camel API rather than the DSL: oldExchange is null
> on the first aggregation call, ${body.type} on a Map body, a bean with
> several methods and no method name, a bean name used as a Groovy variable, a
> two-parameter bean method called with only the body, exchange.setHeader(...)
> called on the Exchange, the Groovy script variables. Each cost one to three
> correction rounds; the answer was put into an error message every time, a
> tool would give it up front.
> What it should return: not the javadoc, a card per class with one line per
> method and the one-line usage a route author needs, about 60 lines in total
> (2-3k tokens):
> - Exchange: getMessage() (getIn() is its alias), getProperty/setProperty,
> getVariable, getContext, getException, isFailed; "the body and headers are on
> the message"
> - Message: getBody(Class), setBody, getHeader(name, Class), setHeader,
> getHeaders, removeHeader
> - CamelContext: getRegistry, createProducerTemplate, resolveLanguage;
> Registry: lookupByName, lookupByNameAndType, bind
> - Processor, AggregationStrategy (with the first-call rule: oldExchange ==
> null, return newExchange), Predicate, Expression
> - the Groovy script variables (exchange, message, body, headers, variables,
> exchangeProperties, camelContext, request, log) and how to reach a registry
> bean from a script
> - a short "Camel 4 changes" block for models trained on older Camel (no
> getOut(), header constants, getMessage())
> Source: a curated list of about ten classes in camel-catalog, generated at
> build from the javadoc of the real methods so it cannot drift, plus a
> hand-written "common mistakes" block per class. Stored next to the bean
> metadata (org/apache/camel/catalog/api/*.json), so any tool and IDE can use
> it.
> Frontier models mostly know this API and will rarely call the tool, which
> costs nothing; they do get Camel-version details wrong, which the Camel 4
> block addresses. For a local model it is the missing piece for anything with
> a Java or Groovy bean. The validator messages of CAMEL-24698/CAMEL-24703 can
> then point to the tool instead of restating the API.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
