Claus Ibsen created CAMEL-25235:
-----------------------------------
Summary: camel_catalog_doc gives a language only its generic
options: the semantic language's questions, criteria and threshold are
unreachable
Key: CAMEL-25235
URL: https://issues.apache.org/jira/browse/CAMEL-25235
Project: Camel
Issue Type: Improvement
Components: camel-jbang
Reporter: Claus Ibsen
{{camel_catalog_doc}} carries the start of a component's documentation since
CAMEL-25040, because an option list can only say what can be set and syntax
that is not an option is invisible in it. That change was scoped to components.
Languages and data formats were left out, and the new Semantic Evaluation
language shows what that costs.
h3. What a model asking about it gets today
{{camel_catalog_doc(name=semantic, kind=language)}} returns the title, the
description, the Maven coordinates, {{since}}, {{supportLevel}} -- and the
generic expression-language options:
{noformat}
options: id, language, expression (+2 omitted)
{noformat}
That is all. The answer does not contain the words {{question}},
{{instructions}}, {{threshold}} or {{criteria}}: everything a route actually
has to write. Nor does it say that a provider artifact is required alongside
{{camel-semantic}}, which is the first thing that goes wrong.
{{includeDoc=true}} returns the whole page, 29406 characters, which has all of
it. But it is off by default and an author who does not already know the answer
has no reason to ask for it -- exactly the position CAMEL-25040 describes.
h3. What the first section would give it
The page opens with precisely what is missing, in a few hundred characters:
that boolean questions produce decisions, choice questions category strings and
score questions numbers on an ordered rubric; that calls are synchronous and
may block; that a provider artifact must be added beside {{camel-semantic}} and
that no provider, or two, is an error; and then the YAML shape of a named
question:
{code:yaml}
- semantic:
question:
department:
type: choice
instructions: Which department should handle this message?
criteria:
billing: Invoices, payments and refunds
{code}
A worked example of the whole pattern, including {{threshold}} and reading the
result back through {{${variable.decisions[...]}}}, is in
https://zinebbendhiba.com/posts/system-one-models-in-java-camel-s-semantic-language-and-langchain4j-s-decision-api/
-- useful as a check on whether the excerpt carries enough to write the route.
h3. Suggested change
# Extend the documentation excerpt of CAMEL-25040 to languages and data
formats. {{languageDoc}} and {{dataFormatDoc}} in {{CatalogDocs}} already take
the page; they need the same {{docExcerpt}} treatment and the same
{{documentation}} / {{documentationHint}} fields as {{componentDoc}}. The
budget may want to be larger than a component's 1400 characters for a language
whose configuration is all prose.
# A Preview language is where this matters most, because there is no training
data to fall back on. Worth a pass over the other recent ones for the same gap.
# {{camel_catalog_sample}} has no sample for {{semantic}}. A named-question
declaration plus one route reading the decision would be the most useful single
thing to add, since the declaration sits beside the routes rather than inside
one and that shape is not guessable from the option list.
h3. Why now
The language is new in 4.23 and Preview, and has just been written up publicly,
so people will try it this week. The content exists and is good; it simply is
not reachable from the answer the tools give.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
