Semantic Evaluation

Use the Simple function ${semantic('evaluationName')} or a semantic-language expression ref:evaluationName. Both return the operation’s typed value, preserve the body, and publish the detailed SemanticResult in the CamelSemanticResult exchange property. Every occurrence invokes the expert; there is no implicit result caching. Retain a value in a Camel variable when it must be reused without another call.

Switch consumes scalar results. Classification returns a Set<String>, including an empty set when no labels apply. Use collections in predicates, for example ${semantic('categories')} contains 'privacy'; labels are not numeric scores. The category and the meaning of a Boolean verdict must come from the selected expert’s contract. A negative detection does not establish general safety or grant authorization.

A specialised moderation expert can accept a map containing a user prompt, an assistant response, and supporting documents. Camel evaluates the state selector and passes that same object unchanged. It does not flatten a conversation into text, create prompts, or impose a universal conversation schema. The expert validates the content and must not modify the original state.

For an application-provided moderation expert with operations response_safety and categories:

Here policy is an illustrative nested expert parameter. The expert owns both its interpretation and any threshold filtering. The body might be a map with prompt, response and documents keys. A missing required response fails before inference; malformed provider output and operational failures follow normal Camel error handling, rather than becoming benign decisions.

Java uses the same declaration model and validation path:

XML uses explicit typed values. A parameter and a map entry each contain exactly one value: string, number, boolean, null, list or map. Null is supported inside nested maps and lists when permitted by the expert. Top-level parameters must have their declared type; omit a parameter to request the expert’s omission behaviour.

YAML declarations are registered after all resources in the load operation have prepared their beans and before routes are constructed. This applies both at startup and on reload, so an expert bean and its evaluations can be introduced together, including in separate resources of the same load operation. XML declaration loading follows the same preparation order; Java helpers validate when register() is called.

Use the fluent helper from camel-semantic inside an ordinary RouteBuilder:

Call .end().evaluation("anotherName") to add another evaluation to the group, then .register() once to validate and install the entire group atomically. Register before creating expressions that refer to these names. When adding builders to a running context, add the builder declaring shared evaluations before builders whose routes reference them.

Use .type("boolean") with optional .threshold(0.8), .uncertainty(0.1) and .uncertaintyPolicy("non-match") for boolean evaluations. Use .type("score") and successive .level("description") calls for ordered score levels. Applications can also register immutable SemanticEvaluation definitions using SemanticEvaluations.get(context).replace(source, evaluations). On a running context, replacement definitions are validated before publication. If validation fails, the previous definitions remain available. The public get(name) and get(names) methods always read published definitions, including calls made from an expert’s validation callback.

Each Java resource owns one group. Register all of its evaluations together; registering again replaces that resource’s previous group. Reloading a Java resource without the helper removes its declarations. Embedded builders without a resource receive distinct generated source keys. The helper reserves "java:" + resource.getLocation() as the resource source key; passing that key and an empty map to replace removes the resource’s evaluations.

The XML extension belongs to camel-semantic. Include camel-semantic and XML DSL (camel-xml-io-dsl). Camel discovers the extension automatically at startup: use ordinary *.xml files without registering a loader or changing the Camel core model. XML documents without semantic declarations are handled by the standard XML loader, including its bean and route configuration support. XML loaders registered by the application before route resource discovery retain precedence over automatic discovery. Loader discovery is refreshed when the context starts or routes are reloaded. Filenames may contain dots, such as my.tickets.xml. Routes retain their original resource locations and line numbers for debugging and error messages.

Both layouts are supported. To keep declarations alongside routes, use tickets.xml:

To share declarations across route files, use a standalone evaluations.xml:

Load this together with ordinary *.xml, Java or YAML route resources that use ref:department. For example, with Camel Main, set camel.main.routes-include-pattern=classpath:evaluations.xml,classpath:routes.xml. Declarations are registered before consuming routes are configured. Reload replaces the source’s evaluations; removing the semantic block, using an empty block, or deleting the resource removes obsolete definitions. XML source keys are the resource locations.

The combined format supports a routes root with one optional semantic block and ordinary route elements. The standalone format uses a semantic root. Namespace-free documents are supported, as are documents consistently using http://camel.apache.org/schema/semantic, http://camel.apache.org/schema/xml-io, or http://camel.apache.org/schema/spring. A semantic block can also declare xmlns="http://camel.apache.org/schema/semantic" inside a standard routes document; its evaluation elements inherit that namespace. The extension detects the declaration block or semantic root namespace automatically.

These extensions do not validate against Camel’s standard core XSDs. Automatic discovery applies to Camel’s route resource loader; it does not extend Spring’s XML application-context parser or direct JAXB unmarshalling.

For boolean evaluations, threshold, uncertainty and uncertaintyPolicy are optional evaluation attributes. For score evaluations, replace the named criterion elements with ordered level elements, such as <level>Routine</level><level>Urgent</level><level>Critical</level>.

The numeric threshold and uncertainty options accept property placeholders in all three DSLs. For example, Java accepts .threshold("{{semantic.threshold:0.5}}"), and XML accepts threshold="{{semantic.threshold:0.5}}". Values are resolved and validated when declarations are registered.

Java and XML declarations use the same context-wide registry, validation, defaults and adapters as YAML. They do not require camel-yaml-dsl. Their evaluations can also be selected together using refs:name1,name2, as described below.

Evaluation declarations live outside Camel’s core route model. Generic model exports and runtime route dumps such as camel.main.dumpRoutes=yaml contain only routes; keep declarations separately and load them before reloading an exported route.

The MCP route conversion tool rejects Java or YAML inputs containing semantic declarations because a generic route export would lose those declarations. Convert the routes separately. Extended XML documents must also be separated into declarations and ordinary routes before using the generic converter.

A evaluation’s optional state Simple expression overrides camel.language.semantic.default-state, whose default is ${body}. Selectors are compiled before evaluation; selected strings, maps and lists are passed as data and are never evaluated recursively. A missing selected header fails instead of falling back to the body. A selector must be nonblank before property placeholders are resolved. A placeholder that resolves to an empty string retains the existing Simple behavior: it selects an empty string as state. Invalid Simple syntax fails. The original message is preserved. CamelSemanticResult contains the latest successful normalized result and is cleared before each evaluation, including one that fails.

State must be a string, map or list. For byte arrays or stream bodies, explicitly select $\{bodyAs(String)}. Enable stream caching before evaluating a stream when later processors also need to read it. Unsupported state types fail instead of being implicitly converted.

YAML declarations are provided by camel-semantic through the YAML deserializer resolver SPI. Include both camel-semantic and camel-yaml-dsl when using them. The YAML DSL does not pull in semantic evaluation, and Java applications using camel-semantic do not pull in the YAML DSL.

Storing the category before Choice performs one semantic evaluation each time execution reaches that Set Header or Set Property step. The branches compare the stored result without calling the provider again. Place that step inside a loop when the decision must be refreshed on each iteration. Nested decisions can use separate properties to retain their own results. Boolean evaluations can also be used directly as ordinary when predicates. These patterns use the existing EIP model and work with the Java, XML and YAML DSLs.

For Aggregate and other Java APIs accepting an Expression, use new LanguageExpression("semantic", "ref:department") from org.apache.camel.model.language. For example, group messages with that expression and a GroupedBodyAggregationStrategy, using completionSize(10) and completionTimeout(5000) to bound the group. Include a trusted tenant or case identifier in the correlation key when messages must remain isolated.

A completion predicate can be obtained with context.resolveLanguage("semantic").createPredicate("ref:actionable"). The aggregation strategy must first put the accumulated conversation in the selected state. Use completionPredicate(predicate).completionSize(10) to retain a deterministic size limit.

Classify once, then map the stored label to destinations supplied by the route author:

A loop must have a finite budget in addition to its semantic predicate. Combine the predicate with a check of CamelLoopIndex, and let the loop body update the selected state. Each new iteration evaluates the current content. For example, a predicate can first check that exchange.getProperty(Exchange.LOOP_INDEX, 0, Integer.class) < 5 and then call the boolean semantic predicate, before loopDoWhile invokes a refinement processor.

For sorting, evaluate ref:urgency once for each item and build a list containing each item and its score. Use .sort(body(), Comparator.comparingDouble(ScoredItem::score)) with that stored score. The comparator must not call the provider: sorting can compare an item multiple times and in an implementation-dependent order.

A boolean evaluation can supply the retryWhile predicate for an exception clause. Ask whether another attempt is worthwhile using the current failure and selected request context. Restrict this to operations that are safe to retry.

Declare a boolean evaluation named retryable with state: $\{exchangeProperty.retryState}. In this example, the request body is a string. onExceptionOccurred prepares the state before the retry predicate runs; onRedelivery runs later and is too late for this purpose. Include only the failure details needed by the evaluation, excluding credentials and sensitive data.

The counter starts at one when deciding the first redelivery. This permits at most three redeliveries after the initial attempt. Each failure refreshes the selected state; redelivery restarts at the failed processor, not at the beginning of the route. A negative decision or an exhausted budget sends the message to direct:escalate through normal exception handling.

If the retry predicate throws (such as a provider timeout, or a malformed or uncertain result), Camel logs the evaluation failure at WARN level and regards the predicate as false. The message is not redelivered and is sent to direct:escalate through normal exception handling, the same as for a negative decision. The original exception is kept as the caught exception, with the evaluation failure attached as a suppressed exception. To tell an evaluation failure apart from a negative decision in the escalation route, check getSuppressed() of the Exchange.EXCEPTION_CAUGHT exception. Bound provider timeouts as well as the retry count.

Use a semantic evaluation for an additional check such as "Does this proposed action serve the approved task?" after normal identity, permission and tenant checks have succeeded. The semantic decision must not grant permissions that those checks denied.

For example, declare this evaluation alongside routes:

The selected state should contain the approved task and the proposed action. Obtain the approved task from trusted application state; do not let the proposed action redefine it. Treat the proposed action as untrusted input: its text can attempt to steer the provider (prompt injection). A positive semantic decision must never override the application’s authorization checks. In this example, direct:checkPermissions performs the application’s existing authorization and rejects unauthorized requests before semantic evaluation:

A negative decision raises normal validation failure. With this evaluation’s fail policy, an uncertain decision raises an evaluation error. Timeouts and malformed responses also fail, and none of these outcomes should execute the protected action. Failure handling may reject the request or send it for human review; do not use continued(true) to resume at the action. The example’s threshold is a decision policy, not an accuracy guarantee.

This pattern uses Validate and existing authorization services. It does not add a semantic AuthorizationPolicy implementation or replace a component’s internal guardrail interfaces.

Evaluation records describe what the expert reported. They do not assert that a route allowed, blocked, quarantined or otherwise acted on a message. Record that action explicitly at the point where the route applies its policy, using SemanticAuditDecision as a normal Camel processor/bean, or SemanticAudit.get(context).decision(…​) in Java.

The processor uses the latest invocation’s CamelSemanticAuditReferences exchange property for its evidence IDs. A batch supplies the IDs of its observed members. An expert disabled for both audit and observation supplies no reference. Save and combine those IDs explicitly if a decision uses earlier invocations; set the processor’s evidenceProperty to that exchange property. A Java caller can supply an empty list for a decision with no supporting evaluation. Explicit decisions are captured whenever the global default or at least one expert override enables auditing. Thus enabled: false with security: {enabled: true} retains both security evaluations and route decisions, including decisions without evidence. Expert overrides filter evaluation records; they do not select which application’s actions are recorded. Disabling the global default and all expert overrides disables decision capture. decisionsEnabled reports this effective state. A reference may therefore point to an evaluation not retained by a particular backend; the inspector displays it as unavailable.

A decision records the application’s declared action, not successful execution of a later tool call. The immutable record is never updated by a later route branch.

SemanticAuditSink accepts immutable SemanticAuditRecord objects. Register custom sinks as Camel beans and list their bean names in sinks. SemanticAuditReader is a separate capability with bounded query and get operations; write-only sinks need not implement it. Choose the reader bean explicitly with reader. The built-in memory reader requires memory in sinks, otherwise configuration fails rather than displaying an unfed history. Readers can override getAll(List<String>) to fetch up to 100 linked evidence records with one backend query; the console calls it once per selected record. The default implementation delegates to get, and the memory implementation scans its bounded history once. Missing IDs remain visibly unavailable. The reserved backend names are memory and log:

The supported backend APIs are SemanticAuditSink, SemanticAuditReader, SemanticAuditRecord, SemanticAuditQuery and SemanticAuditPage. Record maps use a validated, bounded version-1 serialization schema; typed timestamp, duration and evidence accessors avoid backend casts. query.matches(record) provides exact case-sensitive AND filtering with an inclusive timestamp boundary. Record field order is preserved for structured logging. Classes in org.apache.camel.semantic.internal are runtime plumbing, not a supported integration API. Routes use SemanticAuditDecision or SemanticAudit and its documented REFERENCES property; observers use SemanticObserver.

The context starts and stops its configured backends. A single worker dispatches each accepted record to the sinks in configuration order. queueCapacity defaults to 1000 (range 1 to 100000). A full queue drops the new record and increments dropped; backend append failures increment that sink’s error counter and do not change inference or route decisions. An append failure does not prevent trying the remaining sinks. A slow sink delays this dispatcher, so sink implementations must bound I/O and honor interruption. Shutdown allows five seconds to drain, then cancels queued work and counts it as dropped. Delivery can be partial and process failure can lose queued records.

Returning from append means acceptance according to that backend’s documented contract; it does not universally mean durable commit. The dispatcher does not retry failed writes. Backend-specific retries must retain the event ID. This mode does not guarantee a durable record before a protected side effect. Persistent implementations can reconstruct the versioned immutable snapshot with SemanticAuditRecord.fromMap.

Version 1 records contain UTC occurrence timestamps, unique event and invocation IDs, plus startedAt for evaluations. An evaluation’s timestamp denotes completion; the start observer sees the start occurrence in timestamp, and startedAt stays unchanged in the completed record. Duration uses the monotonic clock. Records also contain category, configured expert reference, operation, definition and execution origin, and available Camel context/exchange/route identifiers. Evaluation records add execution status, duration, a stable reason code, typed result, probability/confidence when present, and the static result meanings captured at invocation time. provider identifies the static expert contract. Optional model and revision are copied only from those exact result metadata keys, only when they are nonblank strings of at most 256 code points without control characters. They are omitted rather than truncated if invalid; provider metadata cannot override the contract’s provider identity. No other result metadata is captured. Adapters should supply the actual producing model and revision when known; absent identity stays absent. Batch members have individual invocation IDs and a shared batch ID. A failed group and groups never executed are distinct. Input validation completes before inference: a member whose input passed but whose sibling failed validation is not_executed. When a provider returns a complete batch, each returned answer is validated and audited independently, even if a sibling answer is invalid. The route still receives a batch failure and no partial result/diagnostic map. A valid answer is evidence of evaluation, not a successful batch or route action. Console cancellation requests are separate records linked to eventual provider completion: request timeout does not prove that native or remote inference stopped. A timeout before an expert is resolved emits no request record because its audit eligibility is not yet known. Declaration failures without an identifiable expert also omit an evaluation record; failures with a known reference follow that expert’s override.

Decision records carry explicit action, operation, target, optional namespace/correlation and policy identifiers, reason code and evidence IDs. They never derive application correlation or tenant identity from arbitrary inbound headers.

The CLI and TUI tables show Camel’s breadcrumbId to connect evaluations with route decisions. Enable camel.main.use-breadcrumb=true in Camel Main, or context.setUseBreadcrumb(true) in Java, to let Camel generate missing breadcrumbs when a route exchange starts. Audit copies the existing Exchange.BREADCRUMB_ID value; it does not generate an ID or fall back to an application correlation or exchange ID. Split exchanges retain the original breadcrumb. Records without a breadcrumb, including direct expert calls, show no value. Only nonblank string IDs of at most 256 code points without control characters are captured; invalid values are omitted without conversion or truncation. Use breadcrumbId in an audit query, or --breadcrumb-id in the CLI, to retrieve records with the same breadcrumb.

Input is omitted by default. Other headers, variables, arbitrary provider metadata and exception messages are never copied automatically. Caller-authored score descriptions are also omitted; static capability meanings remain available. Result and metadata strings are limited to 256 code points, and their collections to 100 entries. An oversized result is represented by resultOmitted: snapshot_limit without changing the evaluation outcome.

Use camel semantic audit my-app to retrieve a table of retained records from the Camel CLI. Add --json for machine-readable output, or --event-id=EVENT_ID to inspect a record and its linked evidence. The CLI uses the same reader, filters and cursors as the console and TUI.

The read-only semantic-audit developer console accepts eventId for a selected record and its evidence, or a bounded page query with limit (1 to 200), cursor, since (UTC ISO-8601), category, action, expert, routeId, breadcrumbId, namespace and correlationId. Cursors belong to their backend and filter. Query responses report evictions, expired cursors, effective settings, delivery errors and dropped records. Backend error messages are replaced with a stable code. Querying does not evaluate a definition or require that an old definition still exists.

The Semantic tab in Camel TUI provides an Audit view with filters, a table and a linked-record inspector. tui_get_audit exposes this history through the TUI MCP server without changing the visible tab, filters, page or selection. Pass eventId alone to inspect a record and its evidence, or the console’s filters, limit and returned cursor to query pages. TUI AI sessions load this tool only for integrations exposing the audit console, in both core and full tool modes. Screen navigation remains an explicit TUI action. r refreshes the current page and g returns to the latest page. Pending refreshes are coalesced, while the latest changed filter/page is queried after the active request finishes. tui_get_table also includes audit rows, filters, selected details, linked evidence and backend status when Audit is selected. The OpenTelemetry status recognizes both Camel OpenTelemetry tracer implementations, including subclasses. It reports the context tracer state; it does not claim that a semantic observer/exporter has been installed.