Luigi De Masi created CAMEL-25138:
-------------------------------------
Summary: camel-semantic: Add question declarations to Java and XML
DSLs
Key: CAMEL-25138
URL: https://issues.apache.org/jira/browse/CAMEL-25138
Project: Camel
Issue Type: Improvement
Components: dsl, camel-ai
Reporter: Luigi De Masi
h2. Problem
Named semantic questions can be declared directly alongside routes in YAML
using {{semantic.question}}. Java applications can construct
{{SemanticQuestion}} objects and register them through
{{SemanticQuestions.get(context).replace(source, questions)}}, but there is no
fluent question-declaration DSL. XML has no native question-declaration element
and needs definitions registered separately through Java or loaded YAML.
Semantic evaluation itself already works in Java, XML and YAML through the
generic {{semantic}} language, including {{ref:name}} and the
{{refs:name1,name2}} batching added by CAMEL-25049. The missing capability is
defining the named questions directly in Java and XML DSL applications.
h2. Requested improvement
Add fluent Java DSL declarations and native XML DSL declarations equivalent to
the existing YAML form. Route authors should be able to define questions
alongside their routes without companion YAML files or manual construction and
registration of runtime question objects.
For example, support Java and XML equivalents of this existing YAML definition:
{code:yaml}
- semantic:
question:
department:
type: choice
state: ${header.myState}
instructions: Which department should handle this message?
criteria:
billing: Invoices, payments, and refunds
technical: Bugs, outages, and technical problems
other: Everything else
{code}
The declarations should populate the same context-wide named-question registry
and remain provider-independent. Existing routes should consume these
definitions through the existing semantic language integration. Exact Java
builder names and XML element structure can be agreed during implementation.
h2. Acceptance criteria
# Java DSL applications can declare named questions fluently during route
configuration, and XML DSL applications can declare them through native XML
elements loaded with their routes.
# Both forms support the existing boolean, choice and score definitions:
instructions, optional Simple state selector, named criteria or ordered score
levels, and the applicable boolean threshold and uncertainty policy. Defaults
and validation match YAML.
# Questions declared in either DSL work with existing {{ref:name}} and
{{refs:name1,name2}} expressions and the existing adapter SPI. State selection,
decision policies, batch restrictions and result diagnostics retain their
current semantics.
# Definitions are registered before route references are initialized. Loading
declarations does not perform inference. Invalid definitions, duplicate names
and unknown references produce useful errors. Preserve context-wide naming and
source replacement/removal semantics for supported resource reload paths.
# Existing YAML declarations and programmatic registration remain compatible.
Java and XML applications can use the new declarations without a YAML DSL
dependency; provider-specific syntax or a mandatory TypeSafe AI dependency is
not required.
# Add tests that load actual Java and XML declarations and evaluate boolean,
choice and score questions, including a mixed batch and state selected from a
header. Use deterministic adapters, cover invalid declarations and
duplicate/unknown names, and verify applicable reload behavior. Compare
equivalent definitions across DSLs.
# Document complete Java and XML equivalents of the YAML example and their
single-question and batch usage. Regenerate affected schemas, tooling metadata
and catalog documentation.
h2. Implementation references
*
{{components/camel-ai/camel-semantic/src/main/java/org/apache/camel/semantic/SemanticQuestion.java}}
*
{{components/camel-ai/camel-semantic/src/main/java/org/apache/camel/semantic/SemanticQuestions.java}}
*
{{components/camel-ai/camel-semantic/src/main/java/org/apache/camel/semantic/yaml/SemanticDefinitionDeserializer.java}}
* {{components/camel-ai/camel-semantic/src/main/docs/semantic-language.adoc}}
* {{TypeSafeAiSemanticAdapterTest.xmlBatchUsesGenericLanguageAndReusesResults}}
currently registers questions in Java and evaluates them from XML; it does not
provide native XML question declarations.
h2. Related work
* CAMEL-24977: provider-independent semantic evaluation and YAML question
declarations.
* CAMEL-25049: batching multiple named questions.
* [Merged batch implementation, PR
#26985|https://github.com/apache/camel/pull/26985]
_AI-generated by Codex via /oss-create-issue on behalf of
[luigidemasi|https://github.com/luigidemasi]._
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
