Adaptive learning: Atlas Companion Tools Integration

src/main/java/de/tum/cit/aet/artemis/atlas/config/AtlasAgentToolConfig.java

@@ -0,0 +1,35 @@
+package de.tum.cit.aet.artemis.atlas.config;
+
+import org.springframework.ai.tool.ToolCallbackProvider;
+import org.springframework.ai.tool.method.MethodToolCallbackProvider;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Conditional;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Lazy;
+
+import de.tum.cit.aet.artemis.atlas.service.AtlasAgentToolsService;
+
+/**
+ * Configuration for Atlas Agent tools integration with Spring AI.
+ * This class registers the @Tool-annotated methods from AtlasAgentToolsService
+ * so that Spring AI can discover and use them for function calling.
+ */
+@Lazy
+@Configuration
+@Conditional(AtlasEnabled.class)
+public class AtlasAgentToolConfig {
+
+    /**
+     * Registers the tools found on the AtlasAgentToolsService bean.
+     * MethodToolCallbackProvider discovers @Tool-annotated methods on the provided instances
+     * and makes them available for Spring AI's tool calling system.
+     *
+     * @param toolsService the service containing @Tool-annotated methods
+     * @return ToolCallbackProvider that exposes the tools to Spring AI
+     */
+    @Bean
+    public ToolCallbackProvider atlasToolCallbackProvider(AtlasAgentToolsService toolsService) {
+        // MethodToolCallbackProvider discovers @Tool-annotated methods on the provided instances
+        return MethodToolCallbackProvider.builder().toolObjects(toolsService).build();
+    }
+}

src/main/java/de/tum/cit/aet/artemis/atlas/dto/AtlasAgentChatResponseDTO.java

@@ -20,7 +20,9 @@ public record AtlasAgentChatResponseDTO(
 
         @NotNull ZonedDateTime timestamp,
 
-        boolean success
+        Boolean success,
+
+        Boolean competenciesModified
 
 ) {
 }

src/main/java/de/tum/cit/aet/artemis/atlas/dto/ChatHistoryMessageDTO.java

@@ -0,0 +1,19 @@
+package de.tum.cit.aet.artemis.atlas.dto;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+
+/**
+ * DTO for chat history messages retrieved from ChatMemory.
+ */
+@JsonInclude(JsonInclude.Include.NON_EMPTY)
+public record ChatHistoryMessageDTO(
+
+        @NotNull @NotBlank String role,
+
+        @NotNull @NotBlank String content
+
+) {
+}

src/main/java/de/tum/cit/aet/artemis/atlas/service/AgentChatResult.java

@@ -0,0 +1,8 @@
+package de.tum.cit.aet.artemis.atlas.service;
+
+/**
+ * Internal result object for Atlas Agent chat processing.
+ * Contains the response message and whether competencies were modified.
+ */
+public record AgentChatResult(String message, boolean competenciesModified) {
+}

src/main/java/de/tum/cit/aet/artemis/atlas/service/AtlasAgentService.java

@@ -7,6 +7,7 @@
 import org.slf4j.LoggerFactory;
 import org.springframework.ai.azure.openai.AzureOpenAiChatOptions;
 import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.tool.ToolCallbackProvider;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.context.annotation.Conditional;
 import org.springframework.context.annotation.Lazy;
@@ -29,37 +30,55 @@ public class AtlasAgentService {
 
     private final AtlasPromptTemplateService templateService;
 
-    public AtlasAgentService(@Autowired(required = false) ChatClient chatClient, AtlasPromptTemplateService templateService) {
+    private final ToolCallbackProvider toolCallbackProvider;
+
+    public AtlasAgentService(@Autowired(required = false) ChatClient chatClient, AtlasPromptTemplateService templateService,
+            @Autowired(required = false) ToolCallbackProvider toolCallbackProvider) {
         this.chatClient = chatClient;
         this.templateService = templateService;
+        this.toolCallbackProvider = toolCallbackProvider;
     }
 
     /**
-     * Process a chat message for the given course and return AI response.
+     * Process a chat message for the given course and return AI response with modification status.
+     * Detects competency modifications by checking if the response contains specific keywords.
      *
-     * @param message  The user's message
-     * @param courseId The course ID for context
-     * @return AI response
+     * @param message   The user's message
+     * @param courseId  The course ID for context
+     * @param sessionId The session ID (TODO: will be used for another PR for Memory implementation including db migration)
+     * @return Result containing the AI response and competency modification flag
      */
-    public CompletableFuture<String> processChatMessage(String message, Long courseId) {
+    public CompletableFuture<AgentChatResult> processChatMessage(String message, Long courseId, String sessionId) {
         try {
-            log.debug("Processing chat message for course {} (messageLength={} chars)", courseId, message.length());
-
             // Load system prompt from external template
             String resourcePath = "/prompts/atlas/agent_system_prompt.st";
             Map<String, String> variables = Map.of(); // No variables needed for this template
             String systemPrompt = templateService.render(resourcePath, variables);
 
-            String response = chatClient.prompt().system(systemPrompt).user(String.format("Course ID: %d\n\n%s", courseId, message))
-                    .options(AzureOpenAiChatOptions.builder().temperature(1.0).build()).call().content();
+            var options = AzureOpenAiChatOptions.builder().deploymentName("gpt-4o").temperature(1.0).build();
+            log.info("Atlas Agent using deployment name: {} for course {} with session {}", options.getDeploymentName(), courseId, sessionId);
+
+            var promptSpec = chatClient.prompt().system(systemPrompt).user(String.format("Course ID: %d\n\n%s", courseId, message)).options(options);
+
+            // Add tools
+            if (toolCallbackProvider != null) {
+                promptSpec = promptSpec.toolCallbacks(toolCallbackProvider);
+            }
+
+            String response = promptSpec.call().content();
+
+            // if response mentions creation/modification, set flag
+            boolean competenciesModified = response != null && (response.toLowerCase().contains("created") || response.toLowerCase().contains("successfully created")
+                    || response.toLowerCase().contains("competency titled"));
 
-            log.info("Successfully processed chat message for course {}", courseId);
-            return CompletableFuture.completedFuture(response != null && !response.trim().isEmpty() ? response : "I apologize, but I couldn't generate a response.");
+            log.info("Successfully processed chat message for course {} with session {} (competenciesModified={})", courseId, sessionId, competenciesModified);
+            String finalResponse = response != null && !response.trim().isEmpty() ? response : "I apologize, but I couldn't generate a response.";
+            return CompletableFuture.completedFuture(new AgentChatResult(finalResponse, competenciesModified));
 
         }
         catch (Exception e) {
-            log.error("Error processing chat message for course {}: {}", courseId, e.getMessage(), e);
-            return CompletableFuture.completedFuture("I apologize, but I'm having trouble processing your request right now. Please try again later.");
+            log.error("Error processing chat message for course {} with session {}: {}", courseId, sessionId, e.getMessage(), e);
+            return CompletableFuture.completedFuture(new AgentChatResult("I apologize, but I'm having trouble processing your request right now. Please try again later.", false));
         }
     }
 

src/main/java/de/tum/cit/aet/artemis/atlas/service/AtlasAgentToolsService.java

@@ -0,0 +1,228 @@
+package de.tum.cit.aet.artemis.atlas.service;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.ai.tool.annotation.Tool;
+import org.springframework.ai.tool.annotation.ToolParam;
+import org.springframework.context.annotation.Conditional;
+import org.springframework.context.annotation.Lazy;
+import org.springframework.stereotype.Service;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import de.tum.cit.aet.artemis.atlas.config.AtlasEnabled;
+import de.tum.cit.aet.artemis.atlas.domain.competency.Competency;
+import de.tum.cit.aet.artemis.atlas.domain.competency.CompetencyTaxonomy;
+import de.tum.cit.aet.artemis.atlas.repository.CompetencyRepository;
+import de.tum.cit.aet.artemis.core.domain.Course;
+import de.tum.cit.aet.artemis.core.repository.CourseRepository;
+import de.tum.cit.aet.artemis.exercise.domain.Exercise;
+import de.tum.cit.aet.artemis.exercise.repository.ExerciseRepository;
+
+/**
+ * Service providing tools for the Atlas Agent using Spring AI's @Tool annotation.
+ */
+@Lazy
+@Service
+@Conditional(AtlasEnabled.class)
+public class AtlasAgentToolsService {
+
+    private static final Logger log = LoggerFactory.getLogger(AtlasAgentToolsService.class);
+
+    private final ObjectMapper objectMapper;
+
+    private final CompetencyRepository competencyRepository;
+
+    private final CourseRepository courseRepository;
+
+    private final ExerciseRepository exerciseRepository;
+
+    public AtlasAgentToolsService(ObjectMapper objectMapper, CompetencyRepository competencyRepository, CourseRepository courseRepository, ExerciseRepository exerciseRepository) {
+        this.objectMapper = objectMapper;
+        this.competencyRepository = competencyRepository;
+        this.courseRepository = courseRepository;
+        this.exerciseRepository = exerciseRepository;
+    }
+
+    /**
+     * Tool for getting course competencies.
+     *
+     * @param courseId the course ID
+     * @return JSON representation of competencies
+     */
+    @Tool(description = "Get all competencies for a course")
+    public String getCourseCompetencies(@ToolParam(description = "the ID of the course") Long courseId) {
+        try {
+            Optional<Course> courseOpt = courseRepository.findById(courseId);
+            if (courseOpt.isEmpty()) {
+                return toJson(Map.of("error", "Course not found with ID: " + courseId));
+            }
+
+            Set<Competency> competencies = competencyRepository.findAllByCourseId(courseId);
+
+            // Build competency list using Jackson
+            var competencyList = competencies.stream().map(competency -> {
+                Map<String, Object> compData = new LinkedHashMap<>();
+                compData.put("id", competency.getId());
+                compData.put("title", competency.getTitle());
+                compData.put("description", competency.getDescription());
+                compData.put("taxonomy", competency.getTaxonomy() != null ? competency.getTaxonomy().toString() : "");
+                return compData;
+            }).toList();
+
+            Map<String, Object> response = new LinkedHashMap<>();
+            response.put("courseId", courseId);
+            response.put("competencies", competencyList);
+
+            return toJson(response);
+        }
+        catch (Exception e) {
+            log.error("Error getting course competencies for course {}: {}", courseId, e.getMessage(), e);
+            return toJson(Map.of("error", "Failed to retrieve competencies: " + e.getMessage()));
+        }
+    }
+
+    /**
+     * Tool for creating a new competency in a course.
+     *
+     * @param courseId      the course ID
+     * @param title         the competency title
+     * @param description   the competency description
+     * @param taxonomyLevel the taxonomy level (REMEMBER, UNDERSTAND, APPLY, ANALYZE, EVALUATE, CREATE)
+     * @return JSON response indicating success or error
+     */
+    @Tool(description = "Create a new competency for a course")
+    public String createCompetency(@ToolParam(description = "the ID of the course") Long courseId, @ToolParam(description = "the title of the competency") String title,
+            @ToolParam(description = "the description of the competency") String description,
+            @ToolParam(description = "the taxonomy level (REMEMBER, UNDERSTAND, APPLY, ANALYZE, EVALUATE, CREATE)") String taxonomyLevel) {
+        try {
+            Optional<Course> courseOpt = courseRepository.findById(courseId);
+            if (courseOpt.isEmpty()) {
+                return toJson(Map.of("error", "Course not found with ID: " + courseId));
+            }
+
+            Course course = courseOpt.get();
+            Competency competency = new Competency();
+            competency.setTitle(title);
+            competency.setDescription(description);
+            competency.setCourse(course);
+
+            if (taxonomyLevel != null && !taxonomyLevel.isEmpty()) {
+                try {
+                    CompetencyTaxonomy taxonomy = CompetencyTaxonomy.valueOf(taxonomyLevel.toUpperCase());
+                    competency.setTaxonomy(taxonomy);
+                }
+                catch (IllegalArgumentException e) {
+                    log.warn("Invalid taxonomy level '{}', using default", taxonomyLevel);
+                }
+            }
+
+            Competency savedCompetency = competencyRepository.save(competency);
+
+            // Build response using Jackson
+            Map<String, Object> competencyData = new LinkedHashMap<>();
+            competencyData.put("id", savedCompetency.getId());
+            competencyData.put("title", savedCompetency.getTitle());
+            competencyData.put("description", savedCompetency.getDescription());
+            competencyData.put("taxonomy", savedCompetency.getTaxonomy() != null ? savedCompetency.getTaxonomy().toString() : "");
+            competencyData.put("courseId", courseId);
+
+            Map<String, Object> response = new LinkedHashMap<>();
+            response.put("success", true);
+            response.put("competency", competencyData);
+
+            return toJson(response);
+        }
+        catch (Exception e) {
+            log.error("Error creating competency for course {}: {}", courseId, e.getMessage(), e);
+            return toJson(Map.of("error", "Failed to create competency: " + e.getMessage()));
+        }
+    }
+
+    /**
+     * Tool for getting course description.
+     *
+     * @param courseId the course ID
+     * @return the course description or empty string if not found
+     */
+    @Tool(description = "Get the description of a course")
+    public String getCourseDescription(@ToolParam(description = "the ID of the course") Long courseId) {
+        try {
+            Optional<Course> courseOpt = courseRepository.findById(courseId);
+            if (courseOpt.isEmpty()) {
+                return "";
+            }
+
+            Course course = courseOpt.get();
+            String description = course.getDescription();
+            return description != null ? description : "";
+        }
+        catch (Exception e) {
+            log.error("Error getting course description for course {}: {}", courseId, e.getMessage(), e);
+            return "";
+        }
+    }
+
+    /**
+     * Tool for getting exercises for a course.
+     *
+     * @param courseId the course ID
+     * @return JSON representation of exercises
+     */
+    @Tool(description = "List exercises for a course")
+    public String getExercisesListed(@ToolParam(description = "the ID of the course") Long courseId) {
+        try {
+            Optional<Course> courseOpt = courseRepository.findById(courseId);
+            if (courseOpt.isEmpty()) {
+                return toJson(Map.of("error", "Course not found with ID: " + courseId));
+            }
+
+            // NOTE: adapt to your ExerciseRepository method
+            Set<Exercise> exercises = exerciseRepository.findByCourseIds(Set.of(courseId));
+
+            // Build exercise list using Jackson
+            var exerciseList = exercises.stream().map(exercise -> {
+                Map<String, Object> exerciseData = new LinkedHashMap<>();
+                exerciseData.put("id", exercise.getId());
+                exerciseData.put("title", exercise.getTitle());
+                exerciseData.put("type", exercise.getClass().getSimpleName());
+                exerciseData.put("maxPoints", exercise.getMaxPoints() != null ? exercise.getMaxPoints() : 0);
+                exerciseData.put("releaseDate", exercise.getReleaseDate() != null ? exercise.getReleaseDate().toString() : "");
+                exerciseData.put("dueDate", exercise.getDueDate() != null ? exercise.getDueDate().toString() : "");
+                return exerciseData;
+            }).toList();
+
+            Map<String, Object> response = new LinkedHashMap<>();
+            response.put("courseId", courseId);
+            response.put("exercises", exerciseList);
+
+            return toJson(response);
+        }
+        catch (Exception e) {
+            log.error("Error getting exercises for course {}: {}", courseId, e.getMessage(), e);
+            return toJson(Map.of("error", "Failed to retrieve exercises: " + e.getMessage()));
+        }
+    }
+
+    /**
+     * Convert object to JSON using Jackson ObjectMapper.
+     *
+     * @param object the object to serialize
+     * @return JSON string representation
+     */
+    private String toJson(Object object) {
+        try {
+            return objectMapper.writeValueAsString(object);
+        }
+        catch (JsonProcessingException e) {
+            log.error("Failed to serialize object to JSON: {}", e.getMessage(), e);
+            return "{\"error\": \"Failed to serialize response\"}";
+        }
+    }
+}