[
https://issues.apache.org/jira/browse/CAMEL-25138?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Luigi De Masi updated CAMEL-25138:
----------------------------------
Description:
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:
{noformat}
- 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
{noformat}
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]._
was:
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]._
> 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: camel-ai, dsl
> Reporter: Luigi De Masi
> Assignee: Luigi De Masi
> Priority: Major
>
> 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:
> {noformat}
> - 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
> {noformat}
> 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)
