AI Worker and Hyperion Boundaries

Artemis builds one WAR. AI Worker and Hyperion are feature packages in the main source tree, like Build Agent and LocalCI. They are not Gradle subprojects.

Package ownership

Package	Responsibility
aiworker.api, aiworker.dto, aiworker.domain	Provider-neutral execution contracts, identities, capabilities and wire messages
aiworker.config, aiworker.service	Provider transport, sandbox, supervisor, and core-side coordination
aiworker.web.admin	Infrastructure status for administrators
hyperion.service.worker	Conditional Hyperion workload and typed translation
hyperion.service.worker.toolchain.javagradle	Java (Gradle and Maven) authoring and independent verification
Other hyperion packages	Instructor access, exercise state, persistence and review

aiworker must not import Hyperion. Its portable contracts must not import Spring services, Docker, the database or distributed state. A workload may use SandboxApi and WorkloadApi; it must not reach into the generic worker supervisor. Core-side Hyperion uses the AiWorkerApi facade to claim work and receive results.

One artifact, two process roles

The normal ArtemisApp entry point starts either process role. With only prod,aiworker, it uses the normal application component scan and profile conditions to load AI Worker services and the selected workload. Worker-only conditions keep server modules disabled, including when their feature flags are inherited. It starts no HTTP server and excludes database auto-configuration. It rejects a combined core/LocalCI/LocalVC/Build Agent profile and HTTP override. The worker VM must also block access to core database and repository services. The selected Hazelcast or Redis client still starts through the shared distributed-data provider.

The worker runs a workload only when artemis.aiworker.workload selects it. Hyperion selects hyperion-generation; other values do not activate its authoring services. Each worker identity advertises one versioned workload capability and one qualified sandbox image. The worker and core use separate provider credentials. A heartbeat reaches the shared DistributedDataProvider, so any core node can see capacity. A job stays fenced to its claimed worker incarnation and execution UUID. The worker calls the configured LLM provider directly; core does not proxy those calls.

Add a workload

1. Define bounded typed input and output in the owning feature. Set a schema version.
2. Implement WorkloadApi in that feature. Validate the assignment and keep domain data out of the generic worker envelope.
3. Gate its services on aiworker and the selected workload. Register its worker configuration in Spring Boot auto-configuration imports.
4. Keep authorization and durable writes on core. Use AiWorkerApi for claims and results; use SandboxApi for isolated execution.
5. Test codec bounds, cancellation, duplicate delivery, lost renewals, stale results, and startup with core services absent. Qualify the exact sandbox image with a real build before enabling it.

Only the Java Hyperion toolchain (java-gradle, which builds Gradle and Maven exercises) is qualified. A fake adapter in tests does not establish support for another language.

Checks

./gradlew compileJava compileTestJava spotlessCheck checkstyleMain checkstyleTest -x webapp
./gradlew test -PincludeArchitectureTests --tests '*ArchitectureTest' -x webapp
./gradlew test --tests 'de.tum.cit.aet.artemis.aiworker.*' --tests 'de.tum.cit.aet.artemis.hyperion.service.worker.*' -x webapp

The architecture tests enforce package ownership, root-project conventions and portable contracts. Docker-backed tests require a qualified immutable image; a skipped test does not qualify an image. See AI Worker operations for deployment and recovery.

Core integration boundaries

The standalone worker does not own course authorization, exercise persistence or student grading. The following integrations remain in their existing modules because those modules own the operation being protected. The deployment-wide generation setting activates mutation protection; shared parser and snapshot APIs remain available without it. All writer nodes must use the same setting.

Owner	Required integration	Scope and cost
Programming and LocalVC	Reserve an exercise before an authoring write or HTTP/SSH push; release the exact reservation afterwards.	Protects course-exercise writes when generation is enabled consistently on every core/LocalVC writer, even if the writer has no local model or worker services. A crashed writer can require manual recovery.
LocalVC	Expose branch-specific checkout and expected-head Git operations.	Hyperion uses a fresh temporary checkout for each operation. Ordinary checkout coordination is unchanged; no additional lock is added to normal reads or pulls.
LocalCI	Execute post-save synchronization builds without networking or exercise-provided environment variables; retain this policy on retry.	The restricted entry point is separate. Ordinary builds retain their existing configuration. CI implementations without this capability reject the restricted request.
LocalCI	Resolve wrapper assignment types to the existing test-repository build template.	A wrapper in the assignment does not change the test harness. Plain Maven/Gradle and black-box template names remain unchanged.
Build agent	Keep LocalCI's JUnit parser in the build-agent layer.	Hyperion uses its own JUnitReportParser. LocalCI keeps its separate production parser in the build-agent layer; parity tests compare test names, skips and failures.
Exercise	Reserve course programming templates during participation creation.	Prevents participation creation from observing a partially saved course exercise when generation is enabled. Exam programming variants are not supported; student-exam assignment is unchanged.
Core distributed data	Provide conditional writes, expiry renewal and process identities through all supported providers.	Callers must not assume that local, Hazelcast and Redis membership or expiry events are identical. Unknown coordination state rejects protected writes.
Core WebSocket security	Authorize AI subscriptions and reject direct sends to server-owned topics.	Client sends are limited to mapped commands, with participation-owner or exercise-editor checks where needed.
Exercise versioning and LLM accounting	Use existing storage for version snapshots and usage.	No schema migration is required. Shared pricing and accounting stay unchanged. Hyperion owns explicit-price and cache accounting, then writes through the existing usage service.

Hyperion's generic-API oracle uses the existing testClass[...] structural-test naming convention. LocalCI does not need a Hyperion-specific test-name exception.

Client ownership

The client follows the same feature-folder and standalone-component convention as Iris. There is no additional Angular NgModule.

• app/hyperion/variants owns the AI variant wizard and entry button.
• app/hyperion/code-editor owns the editor's AI action controls.
• app/hyperion/editor, assessment, problem-statement and quiz own their AI actions, services and dialogs.
• app/hyperion/review owns the adaptation dialog.
• app/hyperion/exercise-generation, activity-tray and admin own generation progress, activity and administration.
• app/hyperion/shared contains generation-specific stage and status views, not application-wide design-system APIs.

Course pages, the navbar and the ordinary editor compose these components. They do not own the AI dialogs. Generated-document typography is scoped to the sanitized Hyperion markdown view; it does not change global code or prose colors. Blocked actions use native disabled controls and a visible explanation rather than a new shared button-disabling API.

The shared TUM AET UI extension is limited to opt-in tab-content preservation. Artifact review uses it to retain file expansion and scroll state across tab changes. Its default remains to destroy inactive content; preserved inactive panels are hidden and inert. No generation-specific stepper, status, empty-state, skeleton or prose API is added to TUM AET UI.