From a692cd935d89a387bbab09020390283d02b0d5f4 Mon Sep 17 00:00:00 2001 From: Caroline Nordbrandt Date: Fri, 8 May 2026 14:12:22 +0200 Subject: [PATCH] Enhance documentation for chat-related classes and services --- .../RestClientConfiguration.java | 11 +++++ .../projectbifrost/domain/ChatMessage.java | 15 ++++--- .../dto/OpenRouterRequestDTO.java | 9 ++++ .../dto/OpenRouterResponseDTO.java | 8 ++++ .../projectbifrost/dto/Personality.java | 4 ++ .../exception/GlobalExceptionHandler.java | 7 +++ .../projectbifrost/service/ChatService.java | 43 ++++++++++++++++--- 7 files changed, 84 insertions(+), 13 deletions(-) diff --git a/src/main/java/org/example/projectbifrost/configuration/RestClientConfiguration.java b/src/main/java/org/example/projectbifrost/configuration/RestClientConfiguration.java index e0812f8..1e106ee 100644 --- a/src/main/java/org/example/projectbifrost/configuration/RestClientConfiguration.java +++ b/src/main/java/org/example/projectbifrost/configuration/RestClientConfiguration.java @@ -10,6 +10,17 @@ import java.net.URI; +/** + * Configuration class for setting up the RestClient bean used to interact with the OpenRouter service. + * Integrates resilient methods to enable fault tolerance when communicating with the API. + * + * This configuration retrieves API properties such as the base URL and API key from the application's + * externalized configuration and injects them as properties. The RestClient is configured with an HTTP client + * that disables automatic retries and includes default headers required for authentication and proper content type. + * + * An instance of the RestClient.Builder is autowired and used to construct the RestClient based on the provided + * configuration properties. + */ @Configuration @EnableResilientMethods public class RestClientConfiguration { diff --git a/src/main/java/org/example/projectbifrost/domain/ChatMessage.java b/src/main/java/org/example/projectbifrost/domain/ChatMessage.java index 1a72518..268884e 100644 --- a/src/main/java/org/example/projectbifrost/domain/ChatMessage.java +++ b/src/main/java/org/example/projectbifrost/domain/ChatMessage.java @@ -5,14 +5,17 @@ import java.time.LocalDateTime; + /** - * Represents a chat message in a conversation. - * This class encapsulates the details of a single message, including its role, content, - * and the timestamp at which it was created. + * Represents a chat message within a chat session. + * + * This class encapsulates the details of a message exchanged + * during a chat session, including its role (e.g., "user", "assistant"), + * the message content, the sender's name, and the timestamp + * of when the message was created. Instances of this class + * are typically used and managed in the context of a {@link ChatSession}. * - * The role typically signifies the sender's identity (e.g., user, system, assistant), - * while the message contains the text content of the chat. - * The timestamp indicates when the message was generated. + * The timestamp is automatically generated at the time of message creation. */ @Getter @Setter diff --git a/src/main/java/org/example/projectbifrost/dto/OpenRouterRequestDTO.java b/src/main/java/org/example/projectbifrost/dto/OpenRouterRequestDTO.java index 25272a8..699d56c 100644 --- a/src/main/java/org/example/projectbifrost/dto/OpenRouterRequestDTO.java +++ b/src/main/java/org/example/projectbifrost/dto/OpenRouterRequestDTO.java @@ -2,6 +2,15 @@ import java.util.List; +/** + * A data transfer object representing a request to interact with the OpenRouter API. + * This DTO encapsulates the model to be used and a list of message exchanges. + * + * @param model The specific model to use for generating responses, typically representing + * the desired large language model or OpenRouter configuration. + * @param messages A list of message exchanges that define the context of the interaction. + * Each message contains a role (e.g., "user" or "assistant") and the message content. + */ public record OpenRouterRequestDTO(String model, List messages) { public record Message(String role, String content) { diff --git a/src/main/java/org/example/projectbifrost/dto/OpenRouterResponseDTO.java b/src/main/java/org/example/projectbifrost/dto/OpenRouterResponseDTO.java index 656093f..76221c3 100644 --- a/src/main/java/org/example/projectbifrost/dto/OpenRouterResponseDTO.java +++ b/src/main/java/org/example/projectbifrost/dto/OpenRouterResponseDTO.java @@ -2,6 +2,14 @@ import java.util.List; +/** + * A data transfer object representing a response from the OpenRouter API. + * This DTO encapsulates the choices returned by the API, where each choice + * contains a message representing a specific response. + * + * @param choices A list of choices provided in the response. Each choice contains + * a message with the content generated by the OpenRouter API. + */ public record OpenRouterResponseDTO(List choices) { public record Choice(Message message) {} public record Message(String content){} diff --git a/src/main/java/org/example/projectbifrost/dto/Personality.java b/src/main/java/org/example/projectbifrost/dto/Personality.java index 22a6bd0..c44522b 100644 --- a/src/main/java/org/example/projectbifrost/dto/Personality.java +++ b/src/main/java/org/example/projectbifrost/dto/Personality.java @@ -3,6 +3,10 @@ import lombok.AllArgsConstructor; import lombok.Getter; +/** + * Enum representing various personalities inspired by Norse mythology for use in chat interactions. + * Each personality encapsulates a unique prompt that guides the tone and style of responses. + */ @Getter @AllArgsConstructor public enum Personality { diff --git a/src/main/java/org/example/projectbifrost/exception/GlobalExceptionHandler.java b/src/main/java/org/example/projectbifrost/exception/GlobalExceptionHandler.java index 5d1f2ec..10e0187 100644 --- a/src/main/java/org/example/projectbifrost/exception/GlobalExceptionHandler.java +++ b/src/main/java/org/example/projectbifrost/exception/GlobalExceptionHandler.java @@ -12,6 +12,13 @@ import java.time.Instant; +/** + * Global exception handler for managing and translating exceptions into client-friendly responses. + * + * This class contains multiple exception handler methods that map specific types of exceptions + * to appropriate HTTP response statuses and error messages. It provides a centralized approach + * to exception handling for the application, ensuring consistent and informative API responses. + */ @ControllerAdvice @Slf4j //Structured logging public class GlobalExceptionHandler { diff --git a/src/main/java/org/example/projectbifrost/service/ChatService.java b/src/main/java/org/example/projectbifrost/service/ChatService.java index 313c199..49523db 100644 --- a/src/main/java/org/example/projectbifrost/service/ChatService.java +++ b/src/main/java/org/example/projectbifrost/service/ChatService.java @@ -19,6 +19,11 @@ import java.util.ArrayList; import java.util.List; +/** + * Service class responsible for managing chat interactions with a Large Language Model (LLM). + * This class handles the processing and storage of chat sessions, sending requests to the + * LLM API, and managing fallback mechanisms in case of service unavailability. + */ @Slf4j @Service public class ChatService { @@ -35,15 +40,17 @@ public ChatService(ChatSessionStorage chatSessionStorage, RestClient restClient) } + /** - * Sends a chat request to a large language model (LLM) using the supplied chat request data. - * The method manages the chat session, compiles the request for the LLM, and processes the response. - * It also maintains the history of chat messages within the session. + * Handles the process of interacting with a Large Language Model (LLM) by sending user input and + * contextual information, and receiving the model's response. The method also manages the storage + * of chat history for the associated session, ensuring that each conversation is tracked effectively. * - * @param dto the {@link ChatRequestDTO} containing the user message, chat session ID, and personality configuration. - * @return the response from the LLM as a string. - * @throws InvalidLLMResponseException if an error occurs during communication with the LLM, - * or if the LLM response is empty or malformed. + * @param dto an instance of {@link ChatRequestDTO} containing the session identifier, user message, + * and personality settings for the chat interaction. + * @return the response generated by the LLM as a string. + * @throws RetryableHttpException if the LLM service is unavailable or if circuit breaker fallback + * is triggered. */ public String chatWithLLM(ChatRequestDTO dto) { ChatSession chatSession = chatSessionStorage.getOrCreateChatSession(dto.sessionId()); @@ -70,6 +77,17 @@ public String chatWithLLM(ChatRequestDTO dto) { } + /** + * Sends a list of formatted messages and model information to a Large Language Model (LLM) + * API endpoint and retrieves the response, handling retries and circuit breaker mechanisms + * for improved robustness in case of transient failures. + * + * @param apiMessages a list of {@link OpenRouterRequestDTO.Message} objects representing the + * messages and contextual input to be sent to the LLM. + * @return the content of the response message generated by the LLM as a string. + * @throws RetryableHttpException if the LLM service returns a retryable HTTP status code (e.g., 429, 500). + * @throws InvalidLLMResponseException if the LLM returns an invalid or empty response. + */ @CircuitBreaker(name = "chatService", fallbackMethod = "fallback") //Break stream of tries if too many failures, and call fallback method @Retry(name = "chatService") //Try again if fails, up to max-attempts @@ -99,6 +117,17 @@ public String fetchResponseFromLLM(List apiMessage } + /** + * Handles the fallback mechanism for the circuit breaker. This method is triggered when + * the circuit breaker is open, indicating that the dependent service is currently unavailable + * or under excessive load. Logs the exception and throws a {@link RetryableHttpException} to + * signal that the operation can be retried later. + * + * @param e the exception that caused the fallback to be triggered. + * @return this method does not return a value as it always throws a {@link RetryableHttpException}. + * @throws RetryableHttpException indicating that the upstream service is unavailable and the + * operation should be retried at a later time. + */ public String fallback(Exception e) { // Circuit breaker is open - throw exception so it doesn't pollute chat history log.warn("Circuit breaker fallback triggered for LLM call. Cause: {}", e.getMessage(), e);