Hyperion: Add AI code generation assistance for template, solution, and tests repositories

docs/admin/setup/hyperion.rst

@@ -75,7 +75,54 @@ Verifying the integration
 3. Run a consistency check to ensure the LLM call succeeds. Inspect the server logs for ``Hyperion`` entries
    if the request fails; misconfigured credentials and missing network egress are the most common causes.
 
-Operational considerations
+Code Generation Process
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Hyperion can automatically generate complete programming exercise repositories (solution, template, and test code)
+using a structured AI-driven approach. The generation process consists of a 4-step pipeline with iterative 
+improvement based on compilation feedback.
+
+4-Step Generation Pipeline
+""""""""""""""""""""""""""
+
+Each repository component follows a systematic generation process:
+
+1. **Solution Planning**: Creates a high-level algorithmic approach and identifies key components needed
+2. **File Structure Definition**: Organizes the code into appropriate files and packages 
+3. **Class and Method Headers**: Generates class definitions, method signatures, and documentation
+4. **Core Logic Implementation**: Produces the complete functional implementation
+
+Iterative Compilation Feedback
+"""""""""""""""""""""""""""""""
+
+For each repository component, Hyperion automatically:
+
+- Generates code using the 4-step pipeline
+- Commits changes and triggers a CI build  
+- Waits for compilation results
+- If compilation fails, uses build logs as feedback for the next iteration
+- Retries up to 3 times (default value) per component, incorporating error messages to improve the code
+- Stores the final generated code in the repository, even if compilation ultimately fails
+
+This feedback loop enables Hyperion to self-correct common issues like syntax errors, missing imports, 
+or incorrect API usage.
+
+Cost Considerations
+"""""""""""""""""""
+
+Average code generation costs depend on the LLM model and number of components (solution, template, or test repository):
+
+**Per Component Costs** (with up to 3 iterations):
+
+- **GPT-5**: ~$0.05 per repository component
+- **GPT-5-mini**: ~$0.01 per repository component
+
+**Full Assignment Costs** (solution + template + test repositories):
+
+- **GPT-5**: ~$0.15 total
+- **GPT-5-mini**: ~$0.03 total
+
+Operational considerations 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - **Cost control:** Define usage policies and rate limits with your provider. Hyperion requests can process the

openapi/openapi.yaml

@@ -183,6 +183,26 @@ paths:
           content:
             application/json:
               schema: {$ref: '#/components/schemas/ProblemStatementRewriteResponse'}
+  /api/hyperion/programming-exercises/{exerciseId}/generate-code:
+    post:
+      tags: [hyperion-code-generation]
+      operationId: generateCode
+      parameters:
+      - name: exerciseId
+        in: path
+        required: true
+        schema: {type: integer, format: int64}
+      requestBody:
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/CodeGenerationRequestDTO'}
+        required: true
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/CodeGenerationResultDTO'}
   /api/tutorialgroup/tutorial-groups/{tutorialGroupId}/title:
     get:
       tags: [tutorial-group]
@@ -478,3 +498,23 @@ components:
         registrationNumber: {type: string}
         firstName: {type: string}
         lastName: {type: string}
+    CodeGenerationRequestDTO:
+      type: object
+      description: Request DTO for code generation
+      properties:
+        repositoryType:
+          type: string
+          description: Type of repository to generate code for
+          enum: [TEMPLATE, SOLUTION, TESTS]
+          example: SOLUTION
+    CodeGenerationResultDTO:
+      type: object
+      description: Response DTO for code generation result
+      properties:
+        success: {type: boolean, description: Whether the code generation was successful,
+          example: true}
+        message: {type: string, description: Result message describing the outcome,
+          example: Solution code generated successfully and compiles without errors.}
+        attempts: {type: integer, format: int32, description: Number of generation
+            attempts made, example: 1}
+      required: [success, message, attempts]

package.json

@@ -153,7 +153,8 @@
         "stylelint-config-standard": "39.0.0",
         "stylelint-config-standard-scss": "16.0.0",
         "stylelint-scss": "6.12.1",
-        "typescript": "5.9.3",
+        "ts-morph": "27.0.0",
+        "typescript": "5.9.2",
         "typescript-eslint": "8.45.0"
     },
     "engines": {

src/main/java/de/tum/cit/aet/artemis/buildagent/service/BuildJobContainerService.java

@@ -450,13 +450,37 @@ private void addDirectory(String containerId, String directoryName, boolean crea
     }
 
     private void copyToContainer(Path sourcePath, String containerId) {
-        try (final var uploadStream = new ByteArrayInputStream(createTarArchive(sourcePath).toByteArray());
-                final var copyToContainerCommand = buildAgentConfiguration.getDockerClient().copyArchiveToContainerCmd(containerId)
-                        .withRemotePath(LOCAL_CI_DOCKER_CONTAINER_WORKING_DIRECTORY).withTarInputStream(uploadStream)) {
-            copyToContainerCommand.exec();
-        }
-        catch (IOException e) {
-            throw new LocalCIException("Could not copy to container " + containerId, e);
+        final int maxRetries = 3;
+        final long retryDelayMs = 1000;
+
+        /*
+         * Retry mechanism is essential for Docker container operations due to potential transient failures:
+         * - Docker daemon may be temporarily overloaded or unresponsive
+         * - Network connectivity issues between client and Docker daemon
+         * - Container filesystem may be temporarily locked or busy
+         * - Resource contention during concurrent build operations
+         * This improves reliability in CI/CD environments where multiple builds run simultaneously.
+         */
+        for (int attempt = 1; attempt <= maxRetries; attempt++) {
+            try (final var uploadStream = new ByteArrayInputStream(createTarArchive(sourcePath).toByteArray());
+                    final var copyToContainerCommand = buildAgentConfiguration.getDockerClient().copyArchiveToContainerCmd(containerId)
+                            .withRemotePath(LOCAL_CI_DOCKER_CONTAINER_WORKING_DIRECTORY).withTarInputStream(uploadStream)) {
+                copyToContainerCommand.exec();
+                return;
+            }
+            catch (Exception e) {
+                if (attempt == maxRetries) {
+                    throw new LocalCIException("Could not copy to container " + containerId + " after " + maxRetries + " attempts", e);
+                }
+                log.warn("Attempt {} failed to copy to container {}: {}. Retrying in {} ms...", attempt, containerId, e.getMessage(), retryDelayMs);
+                try {
+                    Thread.sleep(retryDelayMs);
+                }
+                catch (InterruptedException ie) {
+                    Thread.currentThread().interrupt();
+                    throw new LocalCIException("Interrupted while retrying copy to container " + containerId, ie);
+                }
+            }
         }
     }
 

src/main/java/de/tum/cit/aet/artemis/hyperion/dto/ArtifactLocationDTO.java

@@ -13,7 +13,7 @@
 @Schema(description = "Location information for artifacts")
 public record ArtifactLocationDTO(
 
-        @NotNull @Schema(description = "Type of artifact", example = "PROBLEM_STATEMENT") ArtifactType type,
+        @NotNull @Schema(description = "Type of artifact", example = "PROBLEM_STATEMENT") ArtifactTypeDTO type,
 
         @NotNull @Schema(description = "Path to file, empty or problem_statement.md for problem statement", example = "src/main/java/Main.java") String filePath,
 

src/main/java/de/tum/cit/aet/artemis/hyperion/dto/ArtifactTypeDTO.java

@@ -0,0 +1,29 @@
+package de.tum.cit.aet.artemis.hyperion.dto;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonValue;
+
+/**
+ * Enum for artifact types in consistency checks.
+ */
+@JsonInclude(JsonInclude.Include.NON_EMPTY)
+public enum ArtifactTypeDTO {
+
+    PROBLEM_STATEMENT("PROBLEM_STATEMENT"), TEMPLATE_REPOSITORY("TEMPLATE_REPOSITORY"), SOLUTION_REPOSITORY("SOLUTION_REPOSITORY"), TESTS_REPOSITORY("TESTS_REPOSITORY");
+
+    private final String value;
+
+    ArtifactTypeDTO(String value) {
+        this.value = value;
+    }
+
+    @JsonValue
+    public String getValue() {
+        return value;
+    }
+
+    @Override
+    public String toString() {
+        return value;
+    }
+}

src/main/java/de/tum/cit/aet/artemis/hyperion/dto/CodeGenerationRequestDTO.java

@@ -0,0 +1,15 @@
+package de.tum.cit.aet.artemis.hyperion.dto;
+
+import jakarta.validation.constraints.NotNull;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+
+import de.tum.cit.aet.artemis.programming.domain.RepositoryType;
+
+/**
+ * DTO for requesting code generation for a programming exercise.
+ * Contains the repository type to determine which generation strategy to use.
+ */
+@JsonInclude(JsonInclude.Include.NON_EMPTY)
+public record CodeGenerationRequestDTO(@NotNull RepositoryType repositoryType) {
+}

src/main/java/de/tum/cit/aet/artemis/hyperion/dto/CodeGenerationResponseDTO.java

@@ -0,0 +1,30 @@
+package de.tum.cit.aet.artemis.hyperion.dto;
+
+import java.util.List;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+
+/**
+ * DTO for internal code generation response.
+ * Contains the generated content from AI service calls.
+ */
+@JsonInclude(JsonInclude.Include.NON_EMPTY)
+public record CodeGenerationResponseDTO(
+        /**
+         * The solution plan as a string
+         */
+        String solutionPlan,
+
+        /**
+         * List of generated files with path and content
+         */
+        List<GeneratedFileDTO> files) {
+
+    public String getSolutionPlan() {
+        return solutionPlan;
+    }
+
+    public List<GeneratedFileDTO> getFiles() {
+        return files;
+    }
+}

src/main/java/de/tum/cit/aet/artemis/hyperion/dto/CodeGenerationResultDTO.java

@@ -0,0 +1,25 @@
+package de.tum.cit.aet.artemis.hyperion.dto;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+
+/**
+ * DTO for REST API code generation result.
+ * Contains the result of the code generation and compilation process.
+ */
+@JsonInclude(JsonInclude.Include.NON_EMPTY)
+public record CodeGenerationResultDTO(
+        /**
+         * Whether the code generation and compilation was successful
+         */
+        boolean success,
+
+        /**
+         * Descriptive message about the generation result
+         */
+        String message,
+
+        /**
+         * Number of attempts made during the generation process
+         */
+        int attempts) {
+}