Implement upstream LC4j auditing capabilities

Fixes #1844

Author: edeandrea

core/runtime/src/main/java/io/quarkiverse/langchain4j/observability/AiServiceEvents.java

@@ -0,0 +1,39 @@
+package io.quarkiverse.langchain4j.observability;
+
+import dev.langchain4j.observability.api.event.AiServiceCompletedEvent;
+import dev.langchain4j.observability.api.event.AiServiceErrorEvent;
+import dev.langchain4j.observability.api.event.AiServiceEvent;
+import dev.langchain4j.observability.api.event.AiServiceResponseReceivedEvent;
+import dev.langchain4j.observability.api.event.AiServiceStartedEvent;
+import dev.langchain4j.observability.api.event.InputGuardrailExecutedEvent;
+import dev.langchain4j.observability.api.event.OutputGuardrailExecutedEvent;
+import dev.langchain4j.observability.api.event.ToolExecutedEvent;
+import io.quarkiverse.langchain4j.observability.listener.AiServiceListenerAdapter;
+
+/**
+ * Enum representing various events that can occur in an AI service. Each event type
+ * is associated with a specific event class that extends {@link AiServiceEvent}.
+ */
+public enum AiServiceEvents {
+    COMPLETED(AiServiceCompletedEvent.class),
+    ERROR(AiServiceErrorEvent.class),
+    INPUT_GUARDRAIL_EXECUTED(InputGuardrailExecutedEvent.class),
+    OUTPUT_GUARDRAIL_EXECUTED(OutputGuardrailExecutedEvent.class),
+    RESPONSE_RECEIVED(AiServiceResponseReceivedEvent.class),
+    STARTED(AiServiceStartedEvent.class),
+    TOOL_EXECUTED(ToolExecutedEvent.class);
+
+    private final Class<? extends AiServiceEvent> eventClass;
+
+    AiServiceEvents(Class<? extends AiServiceEvent> eventClass) {
+        this.eventClass = eventClass;
+    }
+
+    public <T extends AiServiceEvent> AiServiceListenerAdapter<T> createListener(Class<?> aiServiceClass) {
+        return new AiServiceListenerAdapter<>(getEventClass(), aiServiceClass);
+    }
+
+    public <T extends AiServiceEvent> Class<T> getEventClass() {
+        return (Class<T>) this.eventClass;
+    }
+}

core/runtime/src/main/java/io/quarkiverse/langchain4j/observability/AiServiceSelector.java

@@ -0,0 +1,27 @@
+package io.quarkiverse.langchain4j.observability;
+
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.PARAMETER;
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import jakarta.inject.Qualifier;
+
+/**
+ * Annotation used to select a particular AiService interface. The interface specified in {@link #value()} must be annotated
+ * with
+ * {@link io.quarkiverse.langchain4j.RegisterAiService RegisterAiService}.
+ */
+@Qualifier
+@Target({ METHOD, FIELD, PARAMETER, TYPE })
+@Retention(RUNTIME)
+public @interface AiServiceSelector {
+    /**
+     * Specifies the interface class annotated with {@link io.quarkiverse.langchain4j.RegisterAiService RegisterAiService}.
+     */
+    Class<?> value();
+}

core/runtime/src/main/java/io/quarkiverse/langchain4j/observability/AiServiceSelectorLiteral.java

@@ -0,0 +1,89 @@
+package io.quarkiverse.langchain4j.observability;
+
+import static dev.langchain4j.internal.ValidationUtils.ensureNotNull;
+
+import jakarta.enterprise.util.AnnotationLiteral;
+
+/**
+ * A concrete implementation of {@link AiServiceSelector} and {@link AnnotationLiteral}, used to provide
+ * a runtime version of the {@link AiServiceSelector} annotation. This class is primarily used as a literal
+ * for contextual injection where an {@link AiServiceSelector} annotation is required, allowing the
+ * specification of the AI service class at runtime.
+ */
+public class AiServiceSelectorLiteral extends AnnotationLiteral<AiServiceSelector> implements AiServiceSelector {
+    private final Class<?> aiServiceClass;
+
+    protected AiServiceSelectorLiteral(Builder builder) {
+        this.aiServiceClass = ensureNotNull(builder.aiServiceClass, "aiServiceClass");
+    }
+
+    @Override
+    public Class<?> value() {
+        return aiServiceClass();
+    }
+
+    /**
+     * Retrieves the AI service class specified for this instance.
+     *
+     * @return the class object representing the AI service interface associated with this instance
+     */
+    public Class<?> aiServiceClass() {
+        return this.aiServiceClass;
+    }
+
+    /**
+     * Creates a new {@link Builder} initialized with the current state of this instance.
+     *
+     * @return a {@link Builder} instance pre-configured with the properties of this {@code AiServiceSelector}
+     */
+    public Builder toBuilder() {
+        return new Builder(this);
+    }
+
+    /**
+     * Creates and returns a new instance of the {@link Builder} class, which can be used
+     * to construct an {@link AiServiceSelector} instance with specified properties.
+     *
+     * @return a new {@link Builder} instance
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    /**
+     * Builder class for constructing instances of {@link AiServiceSelector}.
+     * Provides a fluent API to configure its properties.
+     */
+    public static class Builder {
+        private Class<?> aiServiceClass;
+
+        private Builder() {
+        }
+
+        private Builder(AiServiceSelector aiServiceSelector) {
+            this.aiServiceClass = aiServiceSelector.value();
+        }
+
+        /**
+         * Sets the AI service class to be used in the construction of the {@link AiServiceSelector}.
+         *
+         * @param aiServiceClass the class object representing the AI service interface
+         * @return the {@link Builder} instance for method chaining
+         */
+        public Builder aiServiceClass(Class<?> aiServiceClass) {
+            this.aiServiceClass = aiServiceClass;
+            return this;
+        }
+
+        /**
+         * Constructs and returns a new instance of {@link AiServiceSelector}.
+         * The returned instance represents a runtime version of the {@link AiServiceSelector} annotation,
+         * based on the properties configured in the {@link Builder}.
+         *
+         * @return a new {@link AiServiceSelector} instance constructed with the current state of the {@link Builder}
+         */
+        public AiServiceSelector build() {
+            return new AiServiceSelectorLiteral(this);
+        }
+    }
+}

core/runtime/src/main/java/io/quarkiverse/langchain4j/observability/listener/AiServiceListenerAdapter.java

@@ -0,0 +1,32 @@
+package io.quarkiverse.langchain4j.observability.listener;
+
+import dev.langchain4j.observability.api.event.AiServiceEvent;
+import dev.langchain4j.observability.api.listener.AiServiceListener;
+import io.quarkiverse.langchain4j.observability.AiServiceSelectorLiteral;
+import io.quarkus.arc.Arc;
+
+/**
+ * An adapter class for implementing the {@link AiServiceListener} interface to CDI event firing.
+ *
+ * @param <T> the type of {@link AiServiceEvent} being observed, which extends {@link AiServiceEvent}
+ */
+public record AiServiceListenerAdapter<T extends AiServiceEvent>(Class<T> eventClass,
+        Class<?> aiServiceClass) implements AiServiceListener<T> {
+    @Override
+    public Class<T> getEventClass() {
+        return this.eventClass;
+    }
+
+    @Override
+    public void onEvent(T event) {
+        Arc.container()
+                .beanManager()
+                .getEvent()
+                .select(
+                        getEventClass(),
+                        AiServiceSelectorLiteral.builder()
+                                .aiServiceClass(this.aiServiceClass)
+                                .build())
+                .fire(event);
+    }
+}

core/runtime/src/main/java/io/quarkiverse/langchain4j/runtime/AiServicesRecorder.java

@@ -4,6 +4,7 @@
 
 import java.lang.reflect.InvocationTargetException;
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -23,6 +24,7 @@
 import dev.langchain4j.service.tool.ToolProvider;
 import io.quarkiverse.langchain4j.ModelName;
 import io.quarkiverse.langchain4j.RegisterAiService;
+import io.quarkiverse.langchain4j.observability.AiServiceEvents;
 import io.quarkiverse.langchain4j.runtime.aiservice.AiServiceClassCreateInfo;
 import io.quarkiverse.langchain4j.runtime.aiservice.AiServiceMethodCreateInfo;
 import io.quarkiverse.langchain4j.runtime.aiservice.ChatMemorySeeder;
@@ -123,6 +125,11 @@ public QuarkusAiServiceContext apply(SyntheticCreationalContext<QuarkusAiService
                     // properly populates QuarkusAiServiceContext which is what we are trying to construct
                     var quarkusAiServices = INSTANCE.create(aiServiceContext);
 
+                    // Populate the AI service listeners
+                    Arrays.stream(AiServiceEvents.values())
+                            .map(event -> event.createListener(serviceClass))
+                            .forEach(quarkusAiServices::registerListener);
+
                     if (info.languageModelSupplierClassName() != null
                             || info.streamingChatLanguageModelSupplierClassName() != null) {
                         if (info.languageModelSupplierClassName() != null) {