Response Augmentation

// Package: io.quarkiverse.langchain4j.response
/**
 * Configure response augmentation for AI service methods.
 * EXPERIMENTAL: API may change in future versions.
 */
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Experimental("Response augmentation is experimental and may change")
public @interface ResponseAugmenter {
    /**
     * AiResponseAugmenter implementation class.
     * CDI bean will be instantiated and used to augment responses.
     */
    Class<? extends AiResponseAugmenter<?>> value();
}

import io.quarkiverse.langchain4j.RegisterAiService;
import io.quarkiverse.langchain4j.response.ResponseAugmenter;
import io.smallrye.mutiny.Multi;

@RegisterAiService
public interface Assistant {

    @ResponseAugmenter(FormatAugmenter.class)
    String chat(String message);

    @ResponseAugmenter(StreamingFormatAugmenter.class)
    Multi<String> chatStreaming(String message);
}

// Package: io.quarkiverse.langchain4j.response
/**
 * Interface for augmenting AI responses.
 * Supports both regular and streaming responses.
 * EXPERIMENTAL: API may change in future versions.
 *
 * @param <T> Response type
 */
@Experimental("Response augmentation is experimental and may change")
public interface AiResponseAugmenter<T> {

    /**
     * Augment a regular (non-streaming) response.
     * Default implementation returns response unchanged.
     *
     * @param response The original response from the AI model
     * @param params Parameters including user message, memory, and RAG context
     * @return The augmented response
     */
    default T augment(T response, ResponseAugmenterParams params) {
        return response;
    }

    /**
     * Augment a streaming response.
     * Default implementation returns stream unchanged.
     *
     * @param stream The original streaming response from the AI model
     * @param params Parameters including user message, memory, and RAG context
     * @return The augmented streaming response
     */
    default Multi<T> augment(Multi<T> stream, ResponseAugmenterParams params) {
        return stream;
    }
}

import io.quarkiverse.langchain4j.response.AiResponseAugmenter;
import io.quarkiverse.langchain4j.response.ResponseAugmenterParams;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class MarkdownAugmenter implements AiResponseAugmenter<String> {

    @Override
    public String augment(String response, ResponseAugmenterParams params) {
        // Add markdown formatting
        return "**AI Response:**\n\n" + response + "\n\n---\nPowered by AI";
    }

    @Override
    public Multi<String> augment(Multi<String> stream, ResponseAugmenterParams params) {
        // Add markdown header and footer to streaming response
        return Multi.createFrom().concat(
            Multi.createFrom().item("**AI Response:**\n\n"),
            stream,
            Multi.createFrom().item("\n\n---\nPowered by AI")
        );
    }
}

// Package: io.quarkiverse.langchain4j.response
/**
 * Parameters passed to response augmenters.
 * Provides access to original user message, chat memory, RAG results, and template variables.
 */
public record ResponseAugmenterParams(
    UserMessage userMessage,
    ChatMemory memory,
    AugmentationResult augmentationResult,
    String userMessageTemplate,
    Map<String, Object> variables
) {
    /**
     * @param userMessage The original user message
     * @param memory The chat memory (may be null)
     * @param augmentationResult RAG augmentation result (may be null)
     * @param userMessageTemplate Original message template before variable substitution
     * @param variables Template variables used in message
     */
}