Exercises: WIP Enable Variants Generation with AI

openapi/openapi.yaml

@@ -709,6 +709,63 @@ paths:
           content:
             application/json:
               schema: {$ref: '#/components/schemas/ConsistencyCheckResponse'}
+  /api/hyperion/exercises/{exerciseId}/generate-variant:
+    post:
+      tags: [hyperion-exercise-variant]
+      operationId: generateVariant
+      parameters:
+      - name: exerciseId
+        in: path
+        required: true
+        schema: {type: integer, format: int64}
+      requestBody:
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/VariantGenerationRequest'}
+        required: true
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/VariantJobStart'}
+  /api/hyperion/variant-jobs:
+    get:
+      tags: [hyperion-exercise-variant]
+      operationId: getJobsOfCurrentUser
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: array
+                items: {$ref: '#/components/schemas/VariantJob'}
+  /api/hyperion/variant-jobs/{jobId}:
+    get:
+      tags: [hyperion-exercise-variant]
+      operationId: getJobDetail
+      parameters:
+      - name: jobId
+        in: path
+        required: true
+        schema: {type: string}
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/VariantJobDetail'}
+    delete:
+      tags: [hyperion-exercise-variant]
+      operationId: cancelJob
+      parameters:
+      - name: jobId
+        in: path
+        required: true
+        schema: {type: string}
+      responses:
+        '200': {description: OK}
   /api/hyperion/courses/{courseId}/assessment-criteria/generate:
     post:
       tags: [hyperion-assessment-criteria-generation]
@@ -3005,3 +3062,93 @@ components:
         userPrompt: {type: string, description: User prompt for global refinement,
           maxLength: 1000, minLength: 1}
       required: [problemStatementText, userPrompt]
+    VariantJob:
+      type: object
+      properties:
+        jobId: {type: string}
+        sourceExerciseId: {type: integer, format: int64}
+        courseId: {type: integer, format: int64}
+        sourceExerciseTitle: {type: string}
+        exerciseType:
+          type: string
+          enum: [text, programming, modeling, file-upload, quiz]
+        phase:
+          type: string
+          enum: [ANALYZING, PLANNING, PROVISIONING, TRANSFORMING, VERIFYING, REPAIRING,
+            FINALIZING, COMPLETED, DRAFT_WITH_WARNINGS, FAILED, CANCELLED]
+        failedInPhase:
+          type: string
+          enum: [ANALYZING, PLANNING, PROVISIONING, TRANSFORMING, VERIFYING, REPAIRING,
+            FINALIZING, COMPLETED, DRAFT_WITH_WARNINGS, FAILED, CANCELLED]
+        failureDetail: {type: string}
+        instructorSummary: {type: string}
+        attempt: {type: integer, format: int32}
+        maxAttempts: {type: integer, format: int32}
+        variantExerciseId: {type: integer, format: int64}
+        variantExerciseTitle: {type: string}
+        request: {$ref: '#/components/schemas/VariantGenerationRequest'}
+        warnings:
+          type: array
+          items: {type: string}
+        totalTokensUsed: {type: integer, format: int64}
+        startedAt: {type: string, format: date-time}
+        finishedAt: {type: string, format: date-time}
+    VariantJobStart:
+      type: object
+      properties:
+        jobId: {type: string}
+    CreateExerciseVariantGroup:
+      type: object
+      properties:
+        title: {type: string, minLength: 1}
+        maxPoints: {type: number, format: double}
+        releaseDate: {type: string, format: date-time}
+        startDate: {type: string, format: date-time}
+        dueDate: {type: string, format: date-time}
+        assessmentDueDate: {type: string, format: date-time}
+        exampleSolutionPublicationDate: {type: string, format: date-time}
+        buildAndTestStudentSubmissionsAfterDueDate: {type: string, format: date-time}
+      required: [title]
+    VariantPlacement:
+      type: object
+      properties:
+        type:
+          type: string
+          enum: [EXISTING_GROUP, NEW_GROUP, STANDALONE, SAME_EXAM_GROUP]
+        existingGroupId:
+          type: [integer, 'null']
+          format: int64
+        newGroup: {$ref: '#/components/schemas/CreateExerciseVariantGroup'}
+    VariantJobDetail:
+      type: object
+      properties:
+        job: {$ref: '#/components/schemas/VariantJob'}
+        stepOutputs:
+          type: object
+          additionalProperties:
+            type: array
+            items: {$ref: '#/components/schemas/StepOutput'}
+        request: {$ref: '#/components/schemas/VariantGenerationRequest'}
+    StepOutput:
+      type: object
+      properties:
+        summary: {type: string}
+        detail: {type: string}
+    VariantGenerationRequest:
+      type: object
+      properties:
+        targetDifficulty:
+          type: [string, 'null']
+          enum: [EASY, MEDIUM, HARD]
+        domainText:
+          type: [string, 'null']
+          maxLength: 2000
+          minLength: 0
+        narrativeStyle:
+          type: [string, 'null']
+          enum: [TECHNICAL, REALISTIC, CREATIVE, IMAGINATIVE]
+        additionalInstructions:
+          type: [string, 'null']
+          maxLength: 2000
+          minLength: 0
+        placement: {$ref: '#/components/schemas/VariantPlacement'}

run-e2e-tests-local-fast.sh

@@ -58,6 +58,17 @@ IRIS_ARTEMIS_CALLBACK_URL="${IRIS_ARTEMIS_CALLBACK_URL:-http://host.docker.inter
 # The Iris-enabled seed course whose course-level Iris settings get turned on.
 IRIS_COURSE_ID="${IRIS_COURSE_ID:-9022}"
 
+# Hyperion (AI exercise-variant generation) e2e support: when RUN_HYPERION=true the
+# runner starts a deterministic OpenAI-compatible mock LLM (a bare Python process, see
+# src/test/playwright/support/hyperion-mock-llm/) and enables Hyperion on the Artemis
+# server pointed at it via spring.ai.openai.*. Unlike Iris, Hyperion talks to the LLM
+# directly through Spring AI, so no microservice is needed — just the mock. Off by
+# default so normal runs are unaffected. Run the variant suite with:
+#     RUN_HYPERION=true ./run-e2e-tests-local-fast.sh --filter "Variant"
+RUN_HYPERION="${RUN_HYPERION:-false}"
+HYPERION_MOCK_LLM_SCRIPT="src/test/playwright/support/hyperion-mock-llm/mock_llm.py"
+HYPERION_MOCK_LLM_PORT="${HYPERION_MOCK_LLM_PORT:-8090}"
+
 while [[ $# -gt 0 ]]; do
     case $1 in
         --stop) STOP=true; shift ;;
@@ -189,6 +200,15 @@ if [ "$STOP" = true ]; then
         docker compose -f "$IRIS_STACK_COMPOSE" down -v 2>/dev/null || true
     fi
 
+    # Stop the Hyperion mock LLM if it is running (bare Python process)
+    if [ -f "$LOCAL_DIR/hyperion-mock-llm.pid" ]; then
+        MOCK_PID=$(cat "$LOCAL_DIR/hyperion-mock-llm.pid")
+        if kill -0 "$MOCK_PID" 2>/dev/null; then
+            echo "Stopping Hyperion mock LLM (PID $MOCK_PID)..."
+            kill_tree "$MOCK_PID"
+        fi
+    fi
+
     # Stop Postgres
     echo "Stopping Postgres..."
     docker compose --env-file .env -f "$COMPOSE_FILE" down -v 2>/dev/null || true
@@ -337,6 +357,51 @@ if [ "$SKIP_SERVER" = false ]; then
         export ARTEMIS_IRIS_SECRETTOKEN="${IRIS_SECRET_TOKEN}"
     fi
 
+    # Optional: start the deterministic mock LLM and enable Hyperion on the server.
+    # Hyperion enablement (artemis.hyperion.enabled=true) also makes management/info
+    # activeModuleFeatures include "hyperion", which the variant e2e suite probes to
+    # decide whether to run. The mock speaks the OpenAI Chat Completions API; Spring AI's
+    # OpenAI client points at it via spring.ai.openai.base-url (note the /v1 suffix — the
+    # SDK appends /chat/completions itself).
+    if [ "$RUN_HYPERION" = true ]; then
+        echo -e "${BLUE}Hyperion enabled (RUN_HYPERION=true): starting the mock LLM on port ${HYPERION_MOCK_LLM_PORT}...${NC}"
+        # Kill any stale listener on the mock's port from a previous attempt.
+        STALE_MOCK=$(lsof -nP -iTCP:"${HYPERION_MOCK_LLM_PORT}" -sTCP:LISTEN 2>/dev/null | awk 'NR>1 {print $2}' | sort -u)
+        for pid in $STALE_MOCK; do
+            echo -e "${YELLOW}Killing stale process on port ${HYPERION_MOCK_LLM_PORT} (PID $pid)...${NC}"
+            kill_tree "$pid"
+        done
+        MOCK_LLM_PORT="${HYPERION_MOCK_LLM_PORT}" python3 "$HYPERION_MOCK_LLM_SCRIPT" > "$LOCAL_DIR/hyperion-mock-llm.log" 2>&1 &
+        MOCK_LLM_PID=$!
+        echo "$MOCK_LLM_PID" > "$LOCAL_DIR/hyperion-mock-llm.pid"
+        # Wait for the mock to accept connections before the server boots against it.
+        MOCK_READY=false
+        for _ in $(seq 1 20); do
+            if curl -sf "http://localhost:${HYPERION_MOCK_LLM_PORT}/health" >/dev/null 2>&1; then
+                MOCK_READY=true
+                break
+            fi
+            sleep 0.5
+        done
+        if [ "$MOCK_READY" = true ]; then
+            echo -e "${GREEN}Mock LLM is listening (PID $MOCK_LLM_PID).${NC}"
+        else
+            # Continuing would enable Hyperion and point Spring AI at a dead port, so the variant suite would
+            # fail later with connection errors that say nothing about the real cause.
+            echo -e "${RED}ERROR: mock LLM did not become ready; aborting instead of running Hyperion against a dead endpoint.${NC}"
+            if kill -0 "$MOCK_LLM_PID" 2>/dev/null; then
+                kill_tree "$MOCK_LLM_PID"
+            fi
+            rm -f "$LOCAL_DIR/hyperion-mock-llm.pid"
+            exit 1
+        fi
+        export ARTEMIS_HYPERION_ENABLED="true"
+        export SPRING_AI_OPENAI_BASE_URL="http://localhost:${HYPERION_MOCK_LLM_PORT}/v1"
+        export SPRING_AI_OPENAI_API_KEY="dummy-key"
+        export SPRING_AI_OPENAI_MICROSOFT_FOUNDRY="false"
+        export SPRING_AI_OPENAI_CHAT_MODEL="mock-model"
+    fi
+
     # Server environment variables
     export SPRING_PROFILES_ACTIVE="artemis,scheduling,localvc,localci,buildagent,core,dev"
     export SPRING_DATASOURCE_URL="jdbc:postgresql://localhost:5432/Artemis?sslmode=disable"

src/main/java/de/tum/cit/aet/artemis/exercise/dto/CreateExerciseVariantGroupDTO.java

@@ -1,5 +1,6 @@
 package de.tum.cit.aet.artemis.exercise.dto;
 
+import java.io.Serializable;
 import java.time.ZonedDateTime;
 
 import jakarta.validation.constraints.NotBlank;
@@ -15,10 +16,14 @@
 /**
  * Payload for creating a new {@link ExerciseVariantGroup}. The owning course is taken from the request path, not the
  * body, and is immutable afterwards.
+ *
+ * Serializable because it is embedded — via the variant-generation request's placement — in the Hazelcast-distributed
+ * {@code VariantJob} record.
  */
 @JsonInclude(JsonInclude.Include.NON_EMPTY)
 public record CreateExerciseVariantGroupDTO(@NotBlank @Size(max = 255) String title, @Nullable @PositiveOrZero Double maxPoints, @Nullable ZonedDateTime releaseDate,
-        @Nullable ZonedDateTime startDate, @Nullable ZonedDateTime dueDate, @Nullable ZonedDateTime assessmentDueDate, @Nullable ZonedDateTime exampleSolutionPublicationDate) {
+        @Nullable ZonedDateTime startDate, @Nullable ZonedDateTime dueDate, @Nullable ZonedDateTime assessmentDueDate, @Nullable ZonedDateTime exampleSolutionPublicationDate)
+        implements Serializable {
 
     /**
      * Converts this DTO into a new, unsaved {@link ExerciseVariantGroup} entity.

src/main/java/de/tum/cit/aet/artemis/exercise/service/ExerciseVariantGroupService.java

@@ -20,6 +20,8 @@
 
 import de.tum.cit.aet.artemis.core.exception.BadRequestAlertException;
 import de.tum.cit.aet.artemis.core.service.messaging.InstanceMessageSendService;
+import de.tum.cit.aet.artemis.course.domain.Course;
+import de.tum.cit.aet.artemis.course.repository.CourseRepository;
 import de.tum.cit.aet.artemis.exercise.domain.Exercise;
 import de.tum.cit.aet.artemis.exercise.domain.ExerciseVariantGroup;
 import de.tum.cit.aet.artemis.exercise.repository.ExerciseRepository;
@@ -34,10 +36,12 @@
 import de.tum.cit.aet.artemis.text.domain.TextExercise;
 
 /**
- * Keeps an {@link ExerciseVariantGroup} and its members on one shared timeline: joining adopts the group's dates, editing
- * the group pushes them onto every member. Programming members use a dedicated flow that also recomputes the build-and-test
- * date and reschedules build/test jobs. Group edits run the same post-save work a member's own update endpoint would, so a
- * group edit is never a weaker operation — see {@link #runPostTimelineUpdateSideEffects}.
+ * Creates and keeps an {@link ExerciseVariantGroup} and its members on one shared timeline. Group creation is shared by
+ * the {@link de.tum.cit.aet.artemis.exercise.web.ExerciseVariantGroupResource} and the AI variant-generation finalizer, so
+ * both place exercises into groups without duplicating the logic. Joining a group adopts its dates, and editing the
+ * group's dates pushes them onto every member. Programming members use a dedicated flow that also recomputes the
+ * build-and-test date and reschedules build/test jobs. Group edits run the same post-save work a member's own update
+ * endpoint would, so a group edit is never a weaker operation — see {@link #runPostTimelineUpdateSideEffects}.
  */
 @Profile(PROFILE_CORE)
 @Lazy
@@ -50,6 +54,8 @@ public class ExerciseVariantGroupService {
 
     private final ExerciseRepository exerciseRepository;
 
+    private final CourseRepository courseRepository;
+
     private final ProgrammingExerciseCreationUpdateService programmingExerciseCreationUpdateService;
 
     private final ParticipationRepository participationRepository;
@@ -64,12 +70,13 @@ public class ExerciseVariantGroupService {
 
     private final Optional<SlideApi> slideApi;
 
-    public ExerciseVariantGroupService(ExerciseVariantGroupRepository exerciseVariantGroupRepository, ExerciseRepository exerciseRepository,
+    public ExerciseVariantGroupService(ExerciseVariantGroupRepository exerciseVariantGroupRepository, ExerciseRepository exerciseRepository, CourseRepository courseRepository,
             ProgrammingExerciseCreationUpdateService programmingExerciseCreationUpdateService, ParticipationRepository participationRepository, ExerciseService exerciseService,
             ExerciseVersionService exerciseVersionService, InstanceMessageSendService instanceMessageSendService, QuizExerciseService quizExerciseService,
             Optional<SlideApi> slideApi) {
         this.exerciseVariantGroupRepository = exerciseVariantGroupRepository;
         this.exerciseRepository = exerciseRepository;
+        this.courseRepository = courseRepository;
         this.programmingExerciseCreationUpdateService = programmingExerciseCreationUpdateService;
         this.participationRepository = participationRepository;
         this.exerciseService = exerciseService;
@@ -79,6 +86,26 @@ public ExerciseVariantGroupService(ExerciseVariantGroupRepository exerciseVarian
         this.slideApi = slideApi;
     }
 
+    /**
+     * Creates a new variant group and attaches it to the given course.
+     *
+     * @param courseId the id of the course that will own the group
+     * @param group    the new, unsaved group entity
+     * @return the persisted group
+     */
+    public ExerciseVariantGroup createGroup(Long courseId, ExerciseVariantGroup group) {
+        group.validateDates();
+        // The course owns the unidirectional collection (the course_id FK lives on this table but is managed from the
+        // Course side). Persist the group first so it gets an id, then attach it so the course_id FK is written. Not
+        // wrapped in a transaction (this codebase avoids service-level @Transactional); validation runs before the
+        // first save, so a failure between the two can only leave an orphan, course-less group no course query sees.
+        group = exerciseVariantGroupRepository.save(group);
+        Course course = courseRepository.findWithEagerExerciseVariantGroupsByIdElseThrow(courseId);
+        course.addExerciseVariantGroup(group);
+        courseRepository.save(course);
+        return group;
+    }
+
     /**
      * Applies the group's timeline to every member and persists both. All members are validated before anything is saved
      * (a timeline valid at group level can still be rejected by a member), so an invalid request mutates nothing.

src/main/java/de/tum/cit/aet/artemis/exercise/web/ExerciseVariantGroupResource.java

@@ -103,15 +103,8 @@ public ExerciseVariantGroupResource(CourseRepository courseRepository, ExerciseV
     public ResponseEntity<ExerciseVariantGroupDTO> createExerciseVariantGroup(@Valid @RequestBody CreateExerciseVariantGroupDTO createDTO, @PathVariable Long courseId)
             throws URISyntaxException {
         log.debug("REST request to create ExerciseVariantGroup in course {} : {}", courseId, createDTO);
-        ExerciseVariantGroup group = createDTO.toEntity();
-        group.validateDates();
-        // The course owns the unidirectional collection, so save the group first to get an id, then attach it to write the
-        // course_id FK. Not transactional (this codebase avoids service-level @Transactional); a failure between the two
-        // saves can only leave an orphan, course-less group that no course-scoped query ever sees.
-        group = exerciseVariantGroupRepository.save(group);
-        Course course = courseRepository.findWithEagerExerciseVariantGroupsByIdElseThrow(courseId);
-        course.addExerciseVariantGroup(group);
-        courseRepository.save(course);
+        // Group creation and course attachment live in the service, shared with the AI variant-generation finalizer.
+        ExerciseVariantGroup group = exerciseVariantGroupService.createGroup(courseId, createDTO.toEntity());
         return ResponseEntity.created(new URI("/api/exercise/courses/" + courseId + "/exercise-variant-groups/" + group.getId())).body(new ExerciseVariantGroupDTO(group));
     }