[jira] [Updated] (CAMEL-25235) camel_catalog_doc gives a language only its generic options: the semantic language's questions, criteria and threshold are unreachable

["Claus Ibsen (Jira)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/CAMEL-25235?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Claus Ibsen updated CAMEL-25235:
--------------------------------
    Fix Version/s: 4.23.0

> 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
>            Assignee: Claus Ibsen
>            Priority: Major
>             Fix For: 4.23.0
>
>
> {{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)