[
https://issues.apache.org/jira/browse/CAMEL-24871?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Claus Ibsen updated CAMEL-24871:
--------------------------------
Fix Version/s: 4.23.0
> 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
> Fix For: 4.23.0
>
>
> 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)
