[
https://issues.apache.org/jira/browse/CAMEL-24871?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Luigi De Masi updated CAMEL-24871:
----------------------------------
Description:
h2. Motivation
Add a general-purpose {{camel-jev}} component for TypeSafe AI's Jev decision
API, together with reusable semantic predicate support in the same module.
Evaluate how Jev's primitives can participate in Camel EIPs, including using
Jev Choice to drive Camel's Choice EIP and assessing other suitable patterns.
The component should expose Jev's structured decision capabilities to Camel
routes: Noul for yes/no propositions, Choice for selecting among predefined
options, and Score for evaluation against descriptive ordered levels. A
semantic predicate is one use of this integration and should work wherever
Camel accepts a {{Predicate}}, including {{when}}, {{filter}}, {{validate}},
{{loopDoWhile}}, and conditional interception or error handling.
h2. Component scope
Provide a producer endpoint that submits caller-selected text or structured
state and one or more typed questions to the Jev HTTP API. Support all three
question types, including mixed batches sharing the same state, and expose
structured answers with the fields supplied by the API: probabilities and
confidence where applicable, selected choices or scores, model identity, and
usage information.
The producer and predicate support should share client/configuration and
lifecycle handling within {{camel-jev}}. Configure credentials, API endpoint,
model selection/version pinning, and bounded request timeouts using Camel
conventions. Mark credentials as secrets. Define the producer's input/output
mapping and document how routes can retain their original message when they
also need the evaluation result.
The endpoint URI, option names, and public DSL syntax should be agreed during
implementation. A new module would fit under {{components/camel-ai}}, with the
required build, catalog, generated metadata, and documentation registration.
h2. Reusable predicate support
Provide an adapter implementing Camel's standard {{Predicate}} contract. Its
primary operation is a Jev Noul question: evaluate a proposition such as "Does
this message request a refund?" against selected exchange data, then map the
returned probability to a boolean using an explicit threshold.
* Accept a question and optional yes/no criteria, along with explicit state
selection and threshold configuration.
* Preserve the message body and make the raw evaluation result available for
routes that need to inspect uncertainty.
* Define the uncertainty policy explicitly; an optional uncertainty band may
produce a non-match or an exception according to configuration. Noul returns a
probability, not a separate confidence field.
* Support normal predicate composition and existing predicate consumers without
requiring a Choice-specific API or a change to Camel's core Predicate contract.
* Decide whether a Camel Language adapter should expose the predicate through
existing Java/XML/YAML DSL mechanisms; reuse Camel's existing extension points
and keep the final public syntax open for design review.
For example, the same refund-request predicate could select a handler using
{{when(predicate)}}, admit messages using {{filter(predicate)}}, or enforce a
semantic requirement using {{validate(predicate)}}. Choice is one example, not
the boundary of the feature.
h2. Evaluate Jev Choice with Camel Choice
Investigate a single Jev Choice question over a route-author-defined set of
categories, followed by routing to the corresponding Camel branch. Evaluate a
producer call followed by ordinary branch predicates first, and determine
whether an optional adapter would improve usability.
This differs from independent Noul predicates: Camel's existing Choice selects
the first matching {{when}}, whereas Jev Choice compares the supplied
categories and selects one. Preserve existing first-match semantics and make
best-category classification an explicit opt-in integration pattern.
The evaluation should cover category/branch mapping, overlapping or incomplete
categories, an explicit "none/other" category where appropriate, and thresholds
on the returned probabilities/confidence. Define when an uncertain or unmatched
result reaches {{otherwise}}. Service failures remain errors, not business
fallbacks. Model-selected labels must map to destinations defined by the route
author.
h2. Evaluate other EIPs
Assess suitable integration points and document where each primitive adds value:
|| EIP || Candidate Jev usage ||
| Filter / Validate | Noul-based semantic admission or validation, with
explicit uncertainty behavior. |
| Dynamic Router | Choice among configured next destinations, including an
explicit stop outcome; assess termination and repeated-call cost. |
| Recipient List | Batched Noul questions or Scores for selecting multiple
configured recipients. A single Jev Choice selects only one category and does
not implement multi-recipient selection by itself. |
| Aggregator | A semantic completion predicate over selected aggregate state;
assess re-evaluation, growing context, and interaction with bounded
size/timeout completion. |
| Content Enricher | Score or Choice to rank/select known enrichment
candidates, with deterministic code obtaining and merging the selected data. |
For each candidate, record the existing Camel extension point, result mapping,
EIP semantics, uncertainty/failure behavior, request count, latency, and cost.
Use representative examples to assess decision quality and fallback frequency.
Distinguish cases covered by composing the producer/predicate with existing
EIPs from cases that warrant an additional adapter. This is a feasibility
evaluation, not a requirement to modify every listed EIP. Keep arithmetic,
ordering, and other exact operations in ordinary code.
h2. Evaluation semantics
{{Predicate.matches(Exchange)}} is synchronous. A predicate performing a remote
evaluation blocks the evaluating thread until the request completes; document
that constraint and enforce bounded timeouts. The producer provides an explicit
evaluation step when routes need to batch questions before branching or reuse
results.
Result reuse must be explicit and scoped to the evaluated state, questions, and
model. In loops or retries, relevant exchange state may change and require a
fresh evaluation. Do not silently reuse stale results or infer batching from
unrelated predicate invocations. Predicate instances must satisfy Camel's
thread-safety and lifecycle contract.
Preserve the semantics of each predicate consumer: Choice remains first-match,
Filter handles non-matches normally, Validate fails on a non-match, and loops
re-evaluate their condition. Document remote-call frequency and latency
implications for loops/retries and state requirements for any startup-time
predicate evaluation.
Timeouts, API errors, and invalid or missing answers must propagate as failures
rather than silently becoming false or an ordinary business fallback. Typed
output does not guarantee a correct decision; document uncertainty handling and
model limitations. Keep submitted state explicit rather than forwarding the
entire exchange by default. Downstream route logic remains responsible for
business actions and authorization.
h2. Acceptance criteria
* A {{camel-jev}} producer supports Choice, Score, Noul, and mixed-question
requests, with documented request/response mapping.
* Reusable Jev predicate support in the same module works independently of
Choice, with examples for at least {{when}}, {{filter}}, and {{validate}}.
* A worked evaluation of Jev Choice driving Camel Choice documents
category/branch mapping, uncertainty and {{otherwise}} behavior, and the
distinction from independent first-match predicates.
* An assessment of other candidate EIPs records feasible integration patterns,
unsuitable cases, and the evidence/tradeoffs supporting any proposed adapters.
* Tests using a stubbed HTTP service cover all primitive mappings,
batching/request counts, threshold boundaries, uncertainty handling, predicate
body preservation, and timeout/error/invalid-response behavior.
* Tests cover repeated predicate evaluation after relevant state changes and
any optional result-reuse path; results must not leak across exchanges.
* Documentation covers configuration, credentials, model selection, synchronous
predicate evaluation, and repeated evaluation in loops/retries. Tests do not
require live credentials.
* Required module registration, catalog metadata, generated files, and
component documentation are included.
h2. References
* [Jev introduction|https://docs.typesafe.ai/introduction]
* [Question primitives|https://docs.typesafe.ai/primitives]
* [Noul probability semantics|https://docs.typesafe.ai/primitives/noul]
* [HTTP API|https://docs.typesafe.ai/api]
* [Model limitations|https://docs.typesafe.ai/model-jaggedness/jev-1.13]
* Camel {{core/camel-api/src/main/java/org/apache/camel/Predicate.java}}
* Camel {{core/camel-api/src/main/java/org/apache/camel/spi/Language.java}}
* Camel
{{core/camel-core-model/src/main/java/org/apache/camel/model/ProcessorDefinition.java}}
_AI-generated by Codex on behalf of luigidemasi._
was:
h2. Motivation
Support semantic conditions in Camel's Choice EIP using Jev, TypeSafe AI's
decision model. A route author should be able to express a condition such as
"Does this message request a refund?" and use the result in
{{choice().when().otherwise()}} with an explicit probability threshold.
Jev's Noul primitive evaluates a yes/no proposition against supplied text or
structured state and returns a probability between 0 and 1. It does not return
a separate confidence field. This maps naturally to a Camel predicate once the
route author defines the threshold and how to handle uncertainty.
h2. Proposed behavior
Provide reusable Jev evaluation and predicate support, with the public DSL and
module placement to be agreed during design. The integration should allow route
authors to:
* Select the message body or explicitly chosen exchange data as the state, and
configure the question and optional yes/no criteria.
* Configure the model, credentials, request timeout, and probability threshold;
allow pinning a model version.
* Retain the probability on the exchange so the route can distinguish a
positive match, a negative result, and an uncertain result while preserving the
original message body.
* Evaluate multiple independent questions in one request when they share the
same state, then reuse their results in successive predicates.
* Route timeouts, API errors, and invalid or missing results through Camel's
error handling. These failures must not silently become a false predicate or
ordinary business fallback.
h2. Example routing behavior
For a refund-request question, an illustrative policy is:
* {{p >= 0.9}}: route to the refund-request handler.
* {{p <= 0.1}}: route to the normal handler.
* Otherwise: route to review or another configured fallback.
These thresholds are examples to validate against the application's data, not
universal defaults. The predicate classifies intent; downstream code remains
responsible for deciding and authorizing any business action.
h2. Design considerations
{{Predicate.matches(Exchange)}} is synchronous. Making an HTTP call directly
from each predicate would block the evaluating thread and could introduce
successive remote calls when several {{when}} branches are checked. A preferred
starting point is a Jev evaluation step before the choice, followed by
predicates reading exchange-scoped results. Any direct predicate facade should
document its blocking behavior and avoid implying automatic batching of
independent predicate invocations.
Preserve the Choice EIP's existing first-match behavior: when several
independent predicates match, branch order determines which handler runs.
Asking one Jev Choice question for the best category is a different operation
and should not silently replace that behavior. No change to Camel's core
Predicate contract is proposed.
Typed responses do not guarantee correct classifications. Document uncertainty
handling and the model's limitations, including sensitivity to irrelevant or
adversarial message content. Keep the submitted state explicit rather than
forwarding the entire exchange by default.
h2. Acceptance criteria
* A documented example routes messages through {{choice/when/otherwise}} using
Jev results, including an uncertainty branch.
* Automated tests with a stubbed HTTP service cover threshold boundaries,
uncertain results, overlapping matches and first-match priority, body
preservation, and timeout/error/invalid-response handling.
* Multiple questions can share one evaluation request and their results can be
reused without a remote call per branch.
* Documentation describes synchronous predicate constraints, model selection,
credentials, timeouts, and error handling. Tests do not require live
credentials.
h2. References
* [Jev introduction|https://docs.typesafe.ai/introduction]
* [Noul primitive and probability
semantics|https://docs.typesafe.ai/primitives/noul]
* [HTTP API|https://docs.typesafe.ai/api]
* [Model limitations|https://docs.typesafe.ai/model-jaggedness/jev-1.13]
* Camel {{core/camel-api/src/main/java/org/apache/camel/Predicate.java}}
* Camel
{{core/camel-core-processor/src/main/java/org/apache/camel/processor/ChoiceProcessor.java}}
_AI-generated by Codex on behalf of luigidemasi._
Summary: Add camel-jev component and evaluate semantic EIP integration
(was: Add Jev-backed semantic predicates for the Choice EIP)
> Add camel-jev component and evaluate semantic EIP integration
> -------------------------------------------------------------
>
> Key: CAMEL-24871
> URL: https://issues.apache.org/jira/browse/CAMEL-24871
> Project: Camel
> Issue Type: New Feature
> Components: camel-ai, eip
> Reporter: Luigi De Masi
> Assignee: Luigi De Masi
> Priority: Major
>
> h2. Motivation
> Add a general-purpose {{camel-jev}} component for TypeSafe AI's Jev decision
> API, together with reusable semantic predicate support in the same module.
> Evaluate how Jev's primitives can participate in Camel EIPs, including using
> Jev Choice to drive Camel's Choice EIP and assessing other suitable patterns.
> The component should expose Jev's structured decision capabilities to Camel
> routes: Noul for yes/no propositions, Choice for selecting among predefined
> options, and Score for evaluation against descriptive ordered levels. A
> semantic predicate is one use of this integration and should work wherever
> Camel accepts a {{Predicate}}, including {{when}}, {{filter}}, {{validate}},
> {{loopDoWhile}}, and conditional interception or error handling.
> h2. Component scope
> Provide a producer endpoint that submits caller-selected text or structured
> state and one or more typed questions to the Jev HTTP API. Support all three
> question types, including mixed batches sharing the same state, and expose
> structured answers with the fields supplied by the API: probabilities and
> confidence where applicable, selected choices or scores, model identity, and
> usage information.
> The producer and predicate support should share client/configuration and
> lifecycle handling within {{camel-jev}}. Configure credentials, API endpoint,
> model selection/version pinning, and bounded request timeouts using Camel
> conventions. Mark credentials as secrets. Define the producer's input/output
> mapping and document how routes can retain their original message when they
> also need the evaluation result.
> The endpoint URI, option names, and public DSL syntax should be agreed during
> implementation. A new module would fit under {{components/camel-ai}}, with
> the required build, catalog, generated metadata, and documentation
> registration.
> h2. Reusable predicate support
> Provide an adapter implementing Camel's standard {{Predicate}} contract. Its
> primary operation is a Jev Noul question: evaluate a proposition such as
> "Does this message request a refund?" against selected exchange data, then
> map the returned probability to a boolean using an explicit threshold.
> * Accept a question and optional yes/no criteria, along with explicit state
> selection and threshold configuration.
> * Preserve the message body and make the raw evaluation result available for
> routes that need to inspect uncertainty.
> * Define the uncertainty policy explicitly; an optional uncertainty band may
> produce a non-match or an exception according to configuration. Noul returns
> a probability, not a separate confidence field.
> * Support normal predicate composition and existing predicate consumers
> without requiring a Choice-specific API or a change to Camel's core Predicate
> contract.
> * Decide whether a Camel Language adapter should expose the predicate through
> existing Java/XML/YAML DSL mechanisms; reuse Camel's existing extension
> points and keep the final public syntax open for design review.
> For example, the same refund-request predicate could select a handler using
> {{when(predicate)}}, admit messages using {{filter(predicate)}}, or enforce a
> semantic requirement using {{validate(predicate)}}. Choice is one example,
> not the boundary of the feature.
> h2. Evaluate Jev Choice with Camel Choice
> Investigate a single Jev Choice question over a route-author-defined set of
> categories, followed by routing to the corresponding Camel branch. Evaluate a
> producer call followed by ordinary branch predicates first, and determine
> whether an optional adapter would improve usability.
> This differs from independent Noul predicates: Camel's existing Choice
> selects the first matching {{when}}, whereas Jev Choice compares the supplied
> categories and selects one. Preserve existing first-match semantics and make
> best-category classification an explicit opt-in integration pattern.
> The evaluation should cover category/branch mapping, overlapping or
> incomplete categories, an explicit "none/other" category where appropriate,
> and thresholds on the returned probabilities/confidence. Define when an
> uncertain or unmatched result reaches {{otherwise}}. Service failures remain
> errors, not business fallbacks. Model-selected labels must map to
> destinations defined by the route author.
> h2. Evaluate other EIPs
> Assess suitable integration points and document where each primitive adds
> value:
> || EIP || Candidate Jev usage ||
> | Filter / Validate | Noul-based semantic admission or validation, with
> explicit uncertainty behavior. |
> | Dynamic Router | Choice among configured next destinations, including an
> explicit stop outcome; assess termination and repeated-call cost. |
> | Recipient List | Batched Noul questions or Scores for selecting multiple
> configured recipients. A single Jev Choice selects only one category and does
> not implement multi-recipient selection by itself. |
> | Aggregator | A semantic completion predicate over selected aggregate state;
> assess re-evaluation, growing context, and interaction with bounded
> size/timeout completion. |
> | Content Enricher | Score or Choice to rank/select known enrichment
> candidates, with deterministic code obtaining and merging the selected data. |
> For each candidate, record the existing Camel extension point, result
> mapping, EIP semantics, uncertainty/failure behavior, request count, latency,
> and cost. Use representative examples to assess decision quality and fallback
> frequency. Distinguish cases covered by composing the producer/predicate with
> existing EIPs from cases that warrant an additional adapter. This is a
> feasibility evaluation, not a requirement to modify every listed EIP. Keep
> arithmetic, ordering, and other exact operations in ordinary code.
> h2. Evaluation semantics
> {{Predicate.matches(Exchange)}} is synchronous. A predicate performing a
> remote evaluation blocks the evaluating thread until the request completes;
> document that constraint and enforce bounded timeouts. The producer provides
> an explicit evaluation step when routes need to batch questions before
> branching or reuse results.
> Result reuse must be explicit and scoped to the evaluated state, questions,
> and model. In loops or retries, relevant exchange state may change and
> require a fresh evaluation. Do not silently reuse stale results or infer
> batching from unrelated predicate invocations. Predicate instances must
> satisfy Camel's thread-safety and lifecycle contract.
> Preserve the semantics of each predicate consumer: Choice remains
> first-match, Filter handles non-matches normally, Validate fails on a
> non-match, and loops re-evaluate their condition. Document remote-call
> frequency and latency implications for loops/retries and state requirements
> for any startup-time predicate evaluation.
> Timeouts, API errors, and invalid or missing answers must propagate as
> failures rather than silently becoming false or an ordinary business
> fallback. Typed output does not guarantee a correct decision; document
> uncertainty handling and model limitations. Keep submitted state explicit
> rather than forwarding the entire exchange by default. Downstream route logic
> remains responsible for business actions and authorization.
> h2. Acceptance criteria
> * A {{camel-jev}} producer supports Choice, Score, Noul, and mixed-question
> requests, with documented request/response mapping.
> * Reusable Jev predicate support in the same module works independently of
> Choice, with examples for at least {{when}}, {{filter}}, and {{validate}}.
> * A worked evaluation of Jev Choice driving Camel Choice documents
> category/branch mapping, uncertainty and {{otherwise}} behavior, and the
> distinction from independent first-match predicates.
> * An assessment of other candidate EIPs records feasible integration
> patterns, unsuitable cases, and the evidence/tradeoffs supporting any
> proposed adapters.
> * Tests using a stubbed HTTP service cover all primitive mappings,
> batching/request counts, threshold boundaries, uncertainty handling,
> predicate body preservation, and timeout/error/invalid-response behavior.
> * Tests cover repeated predicate evaluation after relevant state changes and
> any optional result-reuse path; results must not leak across exchanges.
> * Documentation covers configuration, credentials, model selection,
> synchronous predicate evaluation, and repeated evaluation in loops/retries.
> Tests do not require live credentials.
> * Required module registration, catalog metadata, generated files, and
> component documentation are included.
> h2. References
> * [Jev introduction|https://docs.typesafe.ai/introduction]
> * [Question primitives|https://docs.typesafe.ai/primitives]
> * [Noul probability semantics|https://docs.typesafe.ai/primitives/noul]
> * [HTTP API|https://docs.typesafe.ai/api]
> * [Model limitations|https://docs.typesafe.ai/model-jaggedness/jev-1.13]
> * Camel {{core/camel-api/src/main/java/org/apache/camel/Predicate.java}}
> * Camel {{core/camel-api/src/main/java/org/apache/camel/spi/Language.java}}
> * Camel
> {{core/camel-core-model/src/main/java/org/apache/camel/model/ProcessorDefinition.java}}
> _AI-generated by Codex on behalf of luigidemasi._
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
