Semantic Evaluation

Add org.apache.camel:camel-semantic and a provider, such as TypeSafe AI (camel-typesafe-ai), using the same Camel version. The provider owns credentials, model selection, request timeout, concurrency limits and transport resources. TypeSafe AI uses camel.component.typesafe-ai.* settings even when a route contains no TypeSafe AI endpoint.

An expert is a configured semantic evaluator, implemented by SemanticAdapter. It is not an autonomous agent. Each named evaluation can select a registry bean using expert. Without that field, camel.language.semantic.default-expert=myExpert selects the default bean. The existing camel.language.semantic.adapter=myAdapter setting remains supported as the default when default-expert is absent; it also accepts a fully qualified implementation class name.

Without either default, Camel selects the sole eligible registered instance or advertised adapter. Registry aliases for one instance count once. A registered instance supersedes discovery of its implementation class, including advertised superclasses of registered subclasses. Differently configured instances remain distinct candidates. No eligible expert, or multiple candidates, is an initialization error listing the candidates. Unknown explicit names and invalid defaults fail without fallback. Selection never uses the evaluation’s result type: two boolean experts can evaluate entirely different properties. Use plain names without #bean: or #class: prefixes. Registry lookup takes precedence over class resolution. Class selection uses Camel’s class resolver and injector. Created adapters are registered as camelSemanticAdapter and managed by the context. A collision at that name is an error. Referenced beans retain their existing lifecycle owner.

Camel Main and Camel JBang bind camel.language.semantic.adapter, camel.language.semantic.default-expert and camel.language.semantic.default-state to the language. Embedded applications can resolve SemanticLanguage from the context and call setDefaultExpert, setAdapter and setDefaultState before route setup. The catalog describes the generic language expression model; it does not provide a dedicated semantic Spring Boot configuration class. Configure the language bean explicitly in Spring Boot until generic-language starter configuration is available.

An expert is a registry bean implementing SemanticAdapter, annotated with @SemanticExpert. The class annotation defines its operations. Each operation declares its accepted input shapes, parameters, result type and meaning, and any optional probabilities or confidence. A configured instance cannot redefine this contract. Endpoint addresses, credentials and model deployment settings remain bean configuration, separate from evaluation parameters.

Register the beans with Camel Main or Camel JBang, for example:

SecurityExpert below is an illustrative application-provided expert exposing injection and classify; these names and its taxonomy are defined by that expert. The instruction-driven decisions bean uses the TypeSafe AI component configuration.

The block supplies default expert and state values; individual evaluations can override them. Evaluation names belong to the application, while operation names belong to the expert. type: choice is shorthand for the expert operation named choice; it does not let the route change an operation’s result type. Specify exactly one of operation and type. Declaring an evaluation does not execute it.

parameters can contain strings, booleans, numbers, nested maps and lists. Camel copies them into immutable declarations. Java, YAML and XML builders resolve property placeholders in string parameter values, including nested list and map values; map keys stay literal. Resolved strings remain strings. For numeric parameters, including values inside nested maps or lists, use an explicit numeric value after placeholder resolution. YAML accepts !number "{{limit:0.8}}", XML accepts <number>{{limit:0.8}}</number>, and Java accepts Double.valueOf(getContext().resolvePropertyPlaceholders("{{limit:0.8}}")) as a parameter value. These forms work for any parameter name and expert. The threshold and uncertainty shorthand options also accept numeric placeholders. Direct SemanticEvaluation construction takes already resolved parameter values and requires no Camel context. Omitted parameters stay absent: their behaviour belongs to the expert, and Camel does not insert threshold or confidence defaults. Parameter contracts use String, Boolean, Number, Map and List data shapes. Use Number with integer = true for whole-number parameters; do not use JVM numeric wrapper classes such as Integer in a contract. A provider consumes numeric values through Number across all DSLs.

For example, a nested expert policy can externalise its cutoff without converting string labels:

String parameters, including prompts, use Camel property placeholder escaping for literal braces. For example, YAML instructions: 'Explain \{{example\}}' gives the expert Explain {{example}}. In Java, use .parameter("instructions", "Explain \\{{example\\}}") for the same literal text.

Camel validates recognised parameter names, required values, types and declared constraints. The expert checks operation-specific combinations and compatibility with its bean configuration. Startup validates all declarations, including unused evaluations, without inference. Route resource replacements also validate before publication, retaining previous declarations on failure. The low-level SemanticEvaluations.replace(String, Map) API also validates new and changed unused declarations before publishing them on a started context.

The shorthand fields and Java convenience methods below target instruction-driven operations named boolean, choice and score. Their fields become expert parameters and are validated by the selected expert. TypeSafe AI implements these operations and requires nonblank instructions. All operations use the same evaluation declaration syntax; specialised operations supply their expert-owned parameters as shown above.

The YAML DSL supports declarations alongside routes, including declarations after their use:

Names are context-wide. Duplicate declarations across resources and unknown references fail. Reloading a resource replaces its complete set of evaluations, including removing declarations no longer present. Development-mode route reload also removes definitions from deleted or renamed files before parsing replacements. This replacement does not make the surrounding route reload transactional. Existing expressions resolve the current definition on their next evaluation. Reload validates the candidate declaration snapshot for initialized expressions before publishing it, including expert capabilities, boolean predicate types, Simple state selectors, and compatible batch selectors across resources. Failed validation leaves the previous declarations available. Startup validates unused declarations as well. Resource reload validates new and changed declarations before publishing them, including unused evaluations. Removed declarations remain removable; an expression that still references a removed name fails when evaluated. Validation registrations are weakly held: the registry does not keep expressions or their providers alive. Constraints can remain until an unused expression is garbage-collected; stopping a route does not necessarily release an expression that is still referenced elsewhere. Loading declarations does not perform inference or start provider resources for validation.

For evaluations using expert or default-expert, the registry bean is resolved when the expression is compiled. Rebinding that name does not update already compiled expressions. After replacing the bean, recreate the consuming routes or expressions, or reload their evaluation declarations so the expressions compile against the replacement bean.

Only boolean evaluations can be predicates. A category string is never implicitly a boolean. A direct semantic predicate rejects other result types at initialization. Simple’s bare or negated ${semantic('name')} predicate rejects them before inference when it is matched; comparisons and membership tests can consume their typed values. Decision policy is expert-owned. Camel never derives a Boolean from probability or applies a second threshold to the expert’s returned value. The TypeSafe AI adapter uses an inclusive Boolean probability threshold (default 0.5). A nonzero uncertainty defines an inclusive band around that threshold. fail (the default) raises an error within the band; non-match returns false. Its Choice results must name a supplied criterion, and its scores range from zero to the last rubric index and may be fractional. Other experts declare their own policy parameters, labels and score ranges in their contracts.

Probabilities, provider confidence and selected values are separate. Missing optional fields remain absent. Results can retain provider/model identity and usage metadata. These fields do not imply equivalent quality or calibration when switching providers. Timeouts, malformed answers and unsupported capabilities are errors, distinct from valid negative decisions or unmatched Choice results.

Use refs:name1,name2 to evaluate independent evaluations against the same selected state. The expression returns a map of normalized decisions keyed by evaluation name. For example, using the declarations above:

The same expression works through the generic language integration in YAML and XML. For example, replace the route above with:

A result might contain actionable → true, department → "billing" and urgency → 1.2. Reading the stored map does not invoke the provider again. Each evaluation retains its own expert-owned threshold and uncertainty policy. There is no implicit AND/OR: batch expressions, including a batch containing one boolean evaluation, cannot be used as predicates.

CamelSemanticResults holds an immutable map of the detailed SemanticResult objects, keyed by the same names. These retain available probabilities, confidence and provider metadata. CamelSemanticResult remains the single-evaluation diagnostic property for ref:name. Both diagnostic properties are cleared before every semantic evaluation; a batch publishes its decisions and diagnostics only after every answer passes validation. Missing, extra or invalid answers, operational failures and an uncertainty policy of fail fail the entire evaluation through Camel error handling. A valid negative decision or uncertainty handled by non-match remains a normal false result. A route property assigned by Set Property is owned by the route; clear it explicitly before reevaluation if an error handler could otherwise reuse a decision from an earlier attempt.

Batch references are comma-separated names with surrounding whitespace removed. Empty, duplicate and unknown references are rejected. There is no quoting or escaping in this syntax: names containing commas or leading/trailing whitespace require a single ref:name evaluation. Existing single references are unchanged.

All selected evaluations must use the same effective Simple state selector, after applying camel.language.semantic.default-state and resolving property placeholders. Selectors must match exactly; different expressions that happen to return equal values are not interchangeable. The selector is evaluated once per batch. Missing or unsupported state fails before inference. One snapshot of the evaluation definitions is used throughout each batch, including validation and decision policies; the next evaluation sees replacements from resource reload. Evaluations that need a previous answer require separate evaluations.

SemanticAdapter.evaluateBatch(Map<String, SemanticEvaluation>, Object) has a default implementation that invokes the existing single-evaluation method sequentially, preserving experts that do not implement a provider-specific batch optimisation. Evaluations are grouped by the resolved expert instance, and each group is passed to that instance’s batch method. Two instances of the same class remain separate groups. Each group must return exactly its assigned names. Camel validates the complete combined result before publishing decisions or diagnostics, preserving the original reference order.

TypeSafe AI sends its group in one HTTP request using the component’s existing timeout and concurrency limits. A batch spanning experts can make multiple inference requests. No results are cached or combined across exchanges.

Use language("semantic", "ref:name") wherever an expression or boolean predicate is accepted.

Destination mappings belong to trusted route configuration; provider output should select known labels rather than supply unrestricted endpoint URIs. Expressions reevaluate on each invocation. There is no implicit exchange-wide inference cache. Store results explicitly when reuse is intended, and reevaluate after relevant input changes.

Read SemanticCapabilities.from(MyExpert.class) to inspect a contract without constructing an expert, loading a model or contacting a service. The runtime uses the same cached class contract. The returned operation and parameter maps, supported labels and input shapes are immutable.

For example, an expert can declare a fixed detection operation:

Each operation declares a result type and its meaning. Score operations document their scale and can declare numeric bounds. Choice and classification operations can declare a fixed label set; an instruction-driven expert validates its application-supplied vocabulary itself. Optional probability, per-label probability and confidence fields must declare their meaning. Camel does not manufacture confidence from a verdict, nor require optional information on every response. It rejects information the contract did not declare, malformed numeric values, wrong result types and results outside declared common constraints.

An expert applies explicitly requested policy exactly once, either in its service or its adapter. It preserves service defaults when parameters are absent. If requested policy needs unavailable confidence or probability, the expert rejects the declaration when known statically, or fails that evaluation when the absence is response-dependent. It must not silently ignore the request. Uncertain outcomes use an operation’s documented values or an error; Camel has no universal uncertainty sentinel. Classification filtering, including per-label thresholds, also belongs to the expert. TypeSafe AI’s uncertaintyPolicy supports fail or non-match; other experts need not support that vocabulary.

Generated expert descriptors, expert-specific offline validation and Catalog API extensions are separate work. This contract does not add a new Camel Catalog model.

Implement org.apache.camel.semantic.SemanticAdapter. Advertise the implementation in META-INF/services/org/apache/camel/semantic-adapter using Camel’s FactoryFinder format:

Camel components can generate this descriptor with @JdkService("semantic-adapter"). Discovery checks the declarations for ambiguity before resolving the implementation through FactoryFinder. Repeated declarations of the same class are accepted; different classes require explicit selection. Only the selected adapter is constructed, through Camel’s Injector. Explicit bean or class selection also works when packaging does not expose discovery resources.

The language checks the static operation contract and then calls validate for operation-specific parameter combinations and bean configuration before traffic. validateInput checks detailed message requirements before evaluation. All input checks in a batch run before any expert is invoked. evaluate returns a typed SemanticResult after applying the expert’s policy. A probability-only Boolean result is invalid: the expert must supply its Boolean verdict. Providers should also validate when their SPI is called directly. evaluate must be thread-safe, bound time and resource consumption, honor interruption and propagate operational failures without disclosing input or credentials. Implement CamelContextAware for context injection and Camel Service interfaces when the adapter owns resources. Created service adapters are stopped and shut down by Camel; registry references are not started or stopped again by the language. Provider-specific component services remain under normal Camel lifecycle management.

For TypeSafe AI, boolean, choice and score map to Noul, Choice and Score respectively. The adapter reuses the component endpoint’s managed HTTP client, including timeout, concurrency and cancellation. Routine integration tests use deterministic adapters and local HTTP fixtures; they do not establish a model’s classification quality.

The Semantic Evaluation language supports the following options which are listed below.