gnodet-bot commented on code in PR #27714: URL: https://github.com/apache/camel/pull/27714#discussion_r4246679311
########## docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc: ########## @@ -0,0 +1,43 @@ += Apache Camel 4.x Upgrade Guide + +This document is for helping you upgrade your Apache Camel application +from Camel 4.x to 4.y. For example, if you are upgrading Camel 4.0 to 4.2, then you should follow the guides +from both 4.0 to 4.1 and 4.1 to 4.2. + +[NOTE] +==== +https://github.com/apache/camel-upgrade-recipes/[The Camel Upgrade Recipes project] provides automated assistance for some common migration tasks. +Note that manual migration is still required. +See the xref:camel-upgrade-recipes-tool.adoc[documentation] page for details. +==== + +== Upgrading Camel 4.23 to 4.24 + +=== camel-openai, camel-ai-tool - AI events now use CamelEvent.Type.Ai + +The events fired by the AI components now share a common contract, `org.apache.camel.ai.AiEvent` (a Review Comment: ⚠️ **Inaccurate description of AiEvent:** `AiEvent` extends `CamelEvent` directly — it is **not** a `CamelEvent.ExchangeEvent`. Only the nested `AiEvent.ExchangeAiEvent` sub-interface extends `ExchangeEvent`. This sentence currently reads: > `org.apache.camel.ai.AiEvent` (a `CamelEvent.ExchangeEvent` of the new `CamelEvent.Type.Ai`) Suggested correction: ```suggestion The events fired by the AI components now share a common contract, `org.apache.camel.ai.AiEvent` (a `CamelEvent` of the new `CamelEvent.Type.Ai`), instead of each being a component-specific ``` ########## docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc: ########## @@ -0,0 +1,43 @@ += Apache Camel 4.x Upgrade Guide + +This document is for helping you upgrade your Apache Camel application +from Camel 4.x to 4.y. For example, if you are upgrading Camel 4.0 to 4.2, then you should follow the guides +from both 4.0 to 4.1 and 4.1 to 4.2. + +[NOTE] +==== +https://github.com/apache/camel-upgrade-recipes/[The Camel Upgrade Recipes project] provides automated assistance for some common migration tasks. +Note that manual migration is still required. +See the xref:camel-upgrade-recipes-tool.adoc[documentation] page for details. +==== + +== Upgrading Camel 4.23 to 4.24 + +=== camel-openai, camel-ai-tool - AI events now use CamelEvent.Type.Ai + +The events fired by the AI components now share a common contract, `org.apache.camel.ai.AiEvent` (a +`CamelEvent.ExchangeEvent` of the new `CamelEvent.Type.Ai`), instead of each being a component-specific +`CamelEvent.Type.Custom` event. This lets an `EventNotifier` recognise AI activity — and route it to metrics or +tracing — by type and by the `AiEvent` sub-interfaces, without depending on an AI component. + +The events shipped in 4.23.0 are affected: + +* `camel-ai-tool`: `AiToolAuthorizationDeniedEvent` now implements `AiEvent.ToolCallDeniedEvent`; +* `camel-openai`: `OpenAIAgenticLoopStartedEvent`, `OpenAIAgenticToolCallExecutedEvent` and + `OpenAIAgenticLoopCompletedEvent` now implement `AiEvent.AgentLoopStartedEvent`, `AiEvent.ToolCallExecutedEvent` + and `AiEvent.AgentLoopCompletedEvent`. + +Their `getType()` now returns `CamelEvent.Type.Ai` rather than `CamelEvent.Type.Custom`, and they are now +`CamelEvent.ExchangeEvent` instances. An `EventNotifier` that recognised these events by Review Comment: ⚠️ **Incorrect generalisation:** Not all AI events are `CamelEvent.ExchangeEvent` instances — only those implementing `AiEvent.ExchangeAiEvent`. The root `AiEvent` has no exchange. The current events in camel-openai and camel-ai-tool all happen to implement `ExchangeAiEvent`, but the paragraph should not state it as a universal rule. ```suggestion Their `getType()` now returns `CamelEvent.Type.Ai` rather than `CamelEvent.Type.Custom`, and the exchange-bearing ones now implement `AiEvent.ExchangeAiEvent` (which extends `CamelEvent.ExchangeEvent`). An `EventNotifier` that recognised these events by ``` ########## docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc: ########## @@ -0,0 +1,43 @@ += Apache Camel 4.x Upgrade Guide + +This document is for helping you upgrade your Apache Camel application +from Camel 4.x to 4.y. For example, if you are upgrading Camel 4.0 to 4.2, then you should follow the guides +from both 4.0 to 4.1 and 4.1 to 4.2. + +[NOTE] +==== +https://github.com/apache/camel-upgrade-recipes/[The Camel Upgrade Recipes project] provides automated assistance for some common migration tasks. +Note that manual migration is still required. +See the xref:camel-upgrade-recipes-tool.adoc[documentation] page for details. +==== + +== Upgrading Camel 4.23 to 4.24 + +=== camel-openai, camel-ai-tool - AI events now use CamelEvent.Type.Ai + +The events fired by the AI components now share a common contract, `org.apache.camel.ai.AiEvent` (a +`CamelEvent.ExchangeEvent` of the new `CamelEvent.Type.Ai`), instead of each being a component-specific +`CamelEvent.Type.Custom` event. This lets an `EventNotifier` recognise AI activity — and route it to metrics or +tracing — by type and by the `AiEvent` sub-interfaces, without depending on an AI component. + +The events shipped in 4.23.0 are affected: + +* `camel-ai-tool`: `AiToolAuthorizationDeniedEvent` now implements `AiEvent.ToolCallDeniedEvent`; +* `camel-openai`: `OpenAIAgenticLoopStartedEvent`, `OpenAIAgenticToolCallExecutedEvent` and + `OpenAIAgenticLoopCompletedEvent` now implement `AiEvent.AgentLoopStartedEvent`, `AiEvent.ToolCallExecutedEvent` + and `AiEvent.AgentLoopCompletedEvent`. + +Their `getType()` now returns `CamelEvent.Type.Ai` rather than `CamelEvent.Type.Custom`, and they are now +`CamelEvent.ExchangeEvent` instances. An `EventNotifier` that recognised these events by +`event.getType() == CamelEvent.Type.Custom` must match on `CamelEvent.Type.Ai` instead, or — preferably — +on `event instanceof org.apache.camel.ai.AiEvent` (or one of its sub-interfaces), which no longer requires a +dependency on the AI component. The concrete event classes and all their accessors are unchanged, so code that +references them directly is not affected. + +Because an `AiEvent` is now a `CamelEvent.ExchangeEvent`, a notifier that filters on `instanceof ExchangeEvent` Review Comment: ⚠️ **Stale statement:** `AiEvent` itself is not a `CamelEvent.ExchangeEvent` — `AiEvent` extends `CamelEvent` directly. This paragraph should refer to `AiEvent.ExchangeAiEvent` instead. ```suggestion Because `AiEvent.ExchangeAiEvent` (the exchange-bearing AI event sub-interface) extends `CamelEvent.ExchangeEvent`, a notifier that filters on `instanceof ExchangeEvent` ``` ########## core/camel-api/src/main/java/org/apache/camel/spi/EventNotifier.java: ########## @@ -133,6 +133,24 @@ public interface EventNotifier { /** Set whether to ignore step events. */ void setIgnoreStepEvents(boolean ignoreStepEvents); + /** + * Whether to ignore AI events (see {@link org.apache.camel.ai.AiEvent}). AI events are their own category and are + * not affected by {@link #isIgnoreExchangeEvents()} even though an {@code AiEvent} is an exchange event. Review Comment: ⚠️ **Stale Javadoc:** `AiEvent` is not an exchange event — `AiEvent` extends `CamelEvent` directly. Only `AiEvent.ExchangeAiEvent` extends `ExchangeEvent`. Since the existing AI event concrete classes all implement `ExchangeAiEvent`, the practical note about `ignoreExchangeEvents` not dropping AI events is valid, but the rationale should be precise. ```suggestion * Whether to ignore AI events (see {@link org.apache.camel.ai.AiEvent}). AI events are their own category and are * not affected by {@link #isIgnoreExchangeEvents()} even though exchange-bearing AI events * ({@link org.apache.camel.ai.AiEvent.ExchangeAiEvent}) extend {@link org.apache.camel.spi.CamelEvent.ExchangeEvent}. ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
