AI Pipelines and Service Boundaries

This catalog describes the Artemis-owned control plane for AI-enabled workflows: the requests Artemis creates, the data and authorization it owns, and the integration contracts it exposes. It is not generated API documentation and does not replace the implementation documentation of Iris, Athena, AtlasML, or Logos.

Use this page together with the Artemis Intelligence ecosystem map. It intentionally avoids deployment-specific hosts, credentials, model assignments, provider aliases, capacity, topology, and rollout state. Feature flags and configuration determine whether a boundary is enabled; they do not establish how a particular deployment is configured.

Ownership at a glance

Family	Artemis owns	Service-owned or infrastructure boundary
Iris / Pyris	Request DTOs, job tokens, authentication, session and message state, Artemis callbacks, WebSocket delivery, and client commands with their acknowledgement	Tutor, ingestion, retrieval, answer, and memory-pipeline execution in Iris/Pyris
Athena	Module selection/configuration, request forwarding, exercise/submission state, scheduling, and repository export authorization	Module processing and any module-specific model decisions in Athena
Hyperion	Authoring workflows, prompts and context assembly, exercise/repository integration, and result persistence	Model access selected through Artemis Spring AI configuration
Atlas	Companion-agent, competency-orchestration, tool, course, and competency contracts	Optional AtlasML ML workflows behind a REST boundary
Artemis Global Search	Searchable-entity schemas, index lifecycle, query authorization, and result shaping	Weaviate storage and optional vectorization

Iris and Pyris

PyrisPipelineService and PyrisConnectorService are the central Artemis integration boundary for Iris (whose implementation repository calls the service Pyris). Artemis prepares typed execution DTOs, creates a PyrisJob token before dispatch, and sends the request to the matching Iris endpoint. The common execution settings carry the job token, the Artemis callback base URL, the selected pipeline variant and support level, and—where supported—the user's AI-selection decision.

PyrisInternalStatusUpdateResource is the callback entry point. It authenticates the tracked job and verifies that the path run ID matches it before PyrisStatusUpdateService routes the update to the Artemis owner of that job. Terminal updates remove the job; non-terminal updates keep it available for subsequent callbacks. The callback contract, rather than a direct connection to Iris internals, is the stable Artemis responsibility.

For the implementation hierarchy, executor behavior, and Iris-owned agents, see the Iris pipeline system. For Iris-owned retrieval and content collections, see the Iris RAG pipeline.

Chat, tutor suggestions, autonomous tutor, and competency extraction

Artemis flow	Trigger and source entry points	Artemis-side response path
Chat	A user message or resend is handled through IrisMessageResource and IrisChatPipelineExecutionService, which call PyrisPipelineService.executeChatPipeline.	Chat callbacks reach PyrisInternalStatusUpdateResource; PyrisStatusUpdateService delegates to IrisChatSessionService. Artemis persists its session/message state and sends status and partial/final results over the Iris WebSocket services.
Tutor suggestions	IrisTutorSuggestionSessionService calls PyrisPipelineService.executeTutorSuggestionPipeline with post, session, course, and applicable exercise/lecture context.	The tutor-suggestion callback updates the corresponding session and is delivered through the Iris WebSocket path.
Autonomous tutor	AutonomousTutorForwardingService calls PyrisPipelineService.executeAutonomousTutorPipeline for the communication context.	The authenticated callback is handled by AutonomousTutorService, which applies the Artemis-side post/decision behavior.
Competency extraction	IrisCompetencyGenerationService starts the typed Pyris pipeline through PyrisPipelineService.	The competency-extraction callback is routed back to IrisCompetencyGenerationService, which owns the Artemis-side result handling.

These paths are conditional on Iris being enabled. Artemis creates the request and owns its stored application data; it does not own the underlying Iris pipeline implementation or provider policy.

Content ingestion, update, and deletion

PyrisWebhookService connects Artemis content lifecycles to Iris ingestion. It creates tracked lecture or FAQ ingestion jobs and delegates transport to PyrisConnectorService. Ingestion status returns through the authenticated internal webhook endpoints.

• Lecture units: Artemis queues lecture-unit ingestion in lecture_unit_processing_state, and the Iris ingestion worker claims jobs through PyrisInternalIngestionWorkerResource, which prepares each payload with PyrisWebhookService#prepareLectureUnitIngestion. IrisLectureApi exposes PyrisWebhookService to the lecture module; deleteLectureFromPyrisDB sends unit identifiers for deletion. The course Iris settings do not gate lecture units, because global search needs their content in every course; LectureIngestionReconcileService limits catch-up work to courses within artemis.iris.ingestion.course-window. PyrisStatusUpdateService forwards checkpoint data, heartbeats, and terminal completion to the lecture processing API, allowing Artemis to maintain its processing state.
• FAQs: FaqService uses PyrisFaqApi and PyrisWebhookService to ingest changed FAQs or remove deleted ones. FAQ ingestion is governed by the course Iris settings. Artemis tracks the request lifecycle, while Iris owns indexing and retrieval behavior.
• Callback integrity: PyrisInternalStatusUpdateResource has separate callback contracts for lecture and FAQ ingestion. A callback must authenticate a matching tracked job and have the expected job type before Artemis accepts it.

Iris owns the ingestion implementation, transcription behavior, RAG collections, and vector processing. Read the Iris RAG pipeline before changing an Artemis payload or relying on service-side retrieval behavior.

Lecture context on a chat request

A chat request can carry what the student is looking at, so that retrieval is narrowed to it. IrisMessageContextDTO is the sealed polymorphic carrier: IrisSlidesContextDTO names a lecture unit and the current page, IrisVideoContextDTO a lecture unit and the current timestamp in seconds, and IrisCombinedViewContextDTO nests either or both for a unit opened in the combined view / fullscreen.

The nested shape follows from what that view is. It always shows exactly one unit, so the unit id is derived from whichever nested context is present rather than repeated at the top level, and lectureUnitId() is deliberately not serialised. A combined-view context is only meaningful with at least one of the two nested contexts. The client sends no context when it has neither — a unit whose video has not been played and that has no PDF open — and the server filters out a combined-view context with neither nested value.

Context is not persisted. It is attached to the outgoing execution DTO and then discarded, so a reloaded conversation shows its messages without it. Treat it as a retrieval filter rather than as part of the stored session: whatever a later reader of the chat history has to see belongs in a message.

In the combined view, LectureChatbotComponent hides the topic selector and selects the containing lecture for the next message, even if openChat reuses an existing session. The current unit and media positions travel separately in the transient message context; they are not the stored chat topic.

The Iris point-out command

Iris can point out a relevant position while the student has a lecture unit open in the combined view, moving the slides to a page or the video to a moment before answering. For this, the Iris pipeline sends a pointOut command to Artemis and waits for the student's browser to confirm the move. The position must come from retrieved content for the unit the student is viewing.

IrisCommandService receives an incoming PyrisCommandDTO and dispatches on its type. pointOut is the only type Artemis implements; any other type is dropped at once rather than forwarded, because no client could carry it out and waiting would stall the answer until the ack timeout expired for nobody. The named lecture unit is resolved scoped to the course of the chat job, since a model-generated id must not be trusted to stay inside the course it was generated in.

The round trip runs through three collaborators:

1. IrisCommandService pushes an IrisCommandRequestWebsocketDTO to the user on IrisWebsocketTopics.SESSION_COMMANDS and blocks.
2. The browser acts and replies to the /app/iris/command-ack @MessageMapping on IrisCommandWebsocketController, which requires an authenticated principal and a server-generated correlation id before it accepts the ack.
3. IrisCommandCoordinationService publishes the ack on a distributed reliable topic, so the node holding the pending future completes it whichever node received the STOMP frame. Only the registering node holds a future for a correlation id; every other node ignores the broadcast.

All of that happens inside one synchronous request. Pyris calls POST internal/pipelines/chat/runs/{runId}/command on PyrisInternalStatusUpdateResource, which authenticates the tracked job and checks that the run id in the path matches it before handing the command on, and the response is only written once the client has answered or the wait has run out. A request-handling thread is therefore occupied for up to the full ack window. That is the budget to respect when changing this path: do not lengthen the wait, and do not add a retry at this level, since each attempt would hold a thread for its own five seconds while the Pyris agent tool is still waiting for a single answer.

Three properties of that design carry weight, and a change that drops one of them reintroduces a bug the current shape prevents:

• The deadline travels with the request. expiresAt is computed on the server from the same clock as its own timeout, so a frame delivered late cannot open a fresh client-side window after Artemis has already reported failure to Pyris. The client may act for four seconds; the server waits five, to let an ack sent just inside that window make the return trip.
• A target narrows a user-wide send. The topic is per user, so every open tab receives the request. targetClientId names the tab that started the job, and that tab alone acts and answers. Without a target — an event-triggered run that recorded no tab — every subscribed tab may try, negative acks are ignored because another tab may still succeed, and the first positive ack wins.
• A marker is written only on success. An applied command is persisted as a message with sender COMMAND, holding the command's own {type, parameters} shape so that a reader of the chat history parses a marker exactly like a command rather than a second flattened format. The write is best-effort: the client has already navigated, so a failed marker write must not turn into a 500 for Pyris.

Citations in Iris answers

Citations are embedded in answer text and pass through two forms. Iris emits a citation without a version:

[cite:L:ENTITY_ID:PAGE:START:END:KEYWORD:SUMMARY]

and Artemis appends one before the answer is stored, so the stored and rendered form carries a version field:

[cite:L:42:3:::Sorting:Pivot placement:va3]

L identifies a lecture unit and F an FAQ; the client renders both as source chips. The lecture fields have these roles:

Field	Meaning
ENTITY_ID	The cited lecture unit. Artemis resolves its lecture and unit names for the citation tooltip.
PAGE	The 1-based PDF page of a slide citation. Iris leaves it empty for a video citation; Artemis still accepts a related page there, as older answers may carry one.
START, END	A video segment's times in seconds. An empty START makes a positioned citation a slide citation.
KEYWORD	The citation chip's short label.
SUMMARY	The explanation shown in the chip's tooltip. It may contain colons.

IrisCitationService stamps the version in stampCitationVersions, on the incoming answer before it is persisted: va3 pins a slide to attachment version 3, vt3 pins a video moment to transcription version 3, and version 0 (va0 or vt0) means the position could not be verified against the run snapshot. Only a positioned citation is stamped — one naming neither a page nor a start time stays as it came. A version is recognized only by its leading va or vt tag, because the summary is everything up to the closing bracket and may itself end in a number. Citations stored before versioning have no field and still navigate directly. The one exception is an old summary whose last colon-separated field happens to look like va<digits> or vt<digits>: the client reads it as a pin, so the citation may open without its position.

The version is Artemis's, not the model's. A positioned citation that already arrives with a version field — the model echoing an older answer — has it stripped and is stamped with version 0, so a pin can only come from the snapshot of the run that produced the citation. An unpositioned citation is not stamped, so it keeps such a field unchanged.

This format is the contract between three codebases: the Pyris pipeline that emits it, the server pattern in IrisCitationService, and the client pattern in iris-citation-text.model.ts. The two Artemis patterns carry Keep in sync comments pointing at each other and at Pyris. Change it in all three, or not at all.

Material versions for citations and point-outs

A cited page or timestamp can stop referring to the same content when slides or a video are replaced. Artemis stamps new lecture citations and point-outs with a version from the run snapshot when one is available; an unavailable version is marked unverified. The client checks verified versions when a student follows them. Citations stored before versioning have no pin and still navigate directly.

IrisLectureMaterialVersionService captures the ingested versions of the run's course before its request is dispatched, and keeps the snapshot in a distributed expiring map keyed by job id for the lifetime of the job. That snapshot is the only source of a pinned version: a missing, expired or unreadable one yields no verified version, never the latest database revision, so a new command cannot acquire a pin by bypassing the check. LectureUnitIngestedVersionsDTO carries the values, and they are reported only once processing reached DONE — while a unit is being reprocessed the vector database still serves the previous material, so there is nothing trustworthy to pin. Slides are versioned by Attachment#version and videos by the transcription version, because a cited timestamp comes from a transcription segment.

For a positive pinned version, the client reads GET lecture-units/{lectureUnitId}/material-versions at click time and compares. A citation pinned to 0 needs no request: it is already unverified, and the client opens the unit without its position. A point-out differs — navigateToVersionedPointOut skips the request only for a marker carrying no pin at all, so a pin of 0 still calls the endpoint before the unit is opened without its position. LectureUnitMaterialVersionsDTO reports what the unit offers right now, and the comparison has three outcomes that the student is told apart: the material changed, the material is gone, or the material cannot be checked. The third is not a hedge. A missing transcription version has two causes, because the row is deleted and rewritten whenever the video changes, so during that window the video plays while nothing can be compared against it — hasVideo is what keeps Artemis from reporting a visibly playing video as removed. For a citation and for a saved point-out the student clicks, the lecture still opens in all three cases and only the exact position is withheld. A live point-out is rejected instead: when its pin is 0, the material changed or is gone, or the version request fails, the client calls acknowledgeRejectedPointOut and does not move the view, so the Pyris tool learns that the point-out was not applied. A point-out may carry both a timestamp and a related page, but its pin covers only one material type: after a successful check, the client applies the timestamp for a video pin or the page for a slide pin and drops the other coordinate.

After a successful version check, a citation follows the lecture deep link to its position. A point-out marker moves an open combined view in place or opens its lecture with the combined view selected.

Lecture search and asynchronous answers are separate paths

Do not conflate Artemis Global Search with the two Iris-backed endpoints in IrisGlobalSearchResource:

• lecture-search is a synchronous request. PyrisConnectorService.searchLectures forwards the query and Artemis returns the Iris search result list directly.
• search-answer is an asynchronous answer pipeline. Artemis checks the user’s LLM-usage consent, stores a GlobalSearchAnswerJob with a time-to-live, and calls PyrisConnectorService.executeGlobalSearchIrisAnswer. The callback first emits a thinking frame when applicable and later sends the final answer and sources on the global-search-answer WebSocket topic. Transport failures do not eagerly remove the job because a callback may still arrive.

Both paths use Iris retrieval rather than Artemis’s Global Search schemas or query authorization layer.

Athena

Athena is an external assessment service. Artemis determines which configured Athena module is applicable to an exercise and owns all Artemis assessment data before and after a request. Athena owns module execution and, for modules that use LLMs, its own module-level AI selection.

AthenaModuleService resolves configured module URLs, obtains module availability for a course/exercise type, and validates whether an exercise may use the configured module. The forwarding services convert Artemis domain data into Athena contracts and use the Athena connector; they do not give Athena direct database access.

For the service-owned module layout, decorators, and module manager conventions, see the Athena module structure.

Feedback, submissions, scheduling, and repository access

Flow	Artemis entry points	Boundary
Tutor feedback suggestions	AthenaFeedbackSuggestionsService with AthenaModuleService	Artemis selects/configures the module, converts the applicable exercise/submission context, forwards the request, and consumes the resulting suggestion in the tutor assessment flow.
Preliminary feedback requests	AthenaFeedbackSuggestionsService and the text, modeling, or programming feedback services	Artemis validates the configured exercise flow, user AI-selection decision, request limit, and applicable submission state before its asynchronous request/result lifecycle. Athena returns the service-owned feedback content.
Tutor-feedback forwarding	AthenaFeedbackSendingService	Applicable manual tutor feedback is forwarded to the selected Athena module. Artemis remains authoritative for its feedback records.
Submission forwarding	AthenaSubmissionSendingService	Artemis forwards configured submissions for Athena processing while retaining its submission/exercise state.
Assessment-queue selection	AthenaSubmissionSelectionService	Artemis can ask Athena to propose an assessable submission, then rechecks eligibility and falls back to its normal selection when no usable proposal is returned.
Due-date work	AthenaScheduleService	Artemis schedules eligible configured exercises around their due date, restores scheduled work at startup, and cancels it when exercise state changes.
Programming repositories	AthenaInternalResource and AthenaRepositoryExportService	Athena requests repository content through a secret-authenticated internal endpoint. Artemis authorizes and exports only the requested submission, template, solution, or test repository representation.

The AthenaInternalResource is a deliberately narrow contract: it is an authenticated export boundary, not a general database or repository interface. Changes to Athena decorators or module internals belong in the Athena documentation, not this page.

Hyperion authoring pipelines

Hyperion is Artemis-native and uses Artemis Spring AI integration. It is enabled through Artemis configuration; the associated authoring resources and services remain within the Artemis server. See Hyperion setup and the Spring AI development guide for configuration-oriented documentation.

The authoring resources expose focused workflows, rather than one monolithic pipeline:

Authoring flow	Artemis services
Problem-statement generation and refinement	HyperionProblemStatementResource, HyperionProblemStatementGenerationService, HyperionProblemStatementRefinementService
FAQ rewriting	HyperionFaqResource, HyperionFaqRewriteService
Consistency verification	HyperionProblemStatementResource, HyperionConsistencyCheckService, plus the programming-language context services
Checklist analysis and actions	HyperionProblemStatementResource, HyperionChecklistService
Quiz generation and refinement	HyperionQuizQuestionGenerationResource, HyperionQuizQuestionGenerationService
Staged programming-exercise code generation	HyperionCodeGenerationResource, HyperionCodeGenerationService, HyperionCodeGenerationJobService, HyperionCodeGenerationTaskService, and HyperionCodeGenerationExecutionService

The staged code-generation services coordinate Artemis exercise and repository context, jobs, tasks, execution, and generated artifacts. They should not be documented as a direct external service call. For the detailed consistency-check flow, including its language-aware context filtering and verification pass, see Consistency Check.

Atlas agents, competency orchestration, and AtlasML

Atlas contains two related but distinct Artemis-side responsibilities: native companion-agent and competency-orchestration workflows, and an optional REST integration with AtlasML.

Native Atlas agent and orchestration control plane

AtlasAgentResource accepts course chat requests and delegates them through AtlasAgentService and AtlasAgentDelegationService. Artemis owns the course context, authorization, agent-session history, and tool contract. These beans require artemis.atlas.atlasllm.enabled, which is disabled by default and additionally requires the Artemis Atlas module.

The agents, the orchestrator, the tool surfaces, and the Responses adapter all sit behind that one flag, because none of them can do anything without a configured chat model. An installation that leaves it off keeps competencies, learning paths, and learner profiles, and loads none of those beans, the content-change scheduler, or the autonomous exercise and lecture-unit event listeners. artemis.atlas.enabled therefore describes the competency feature set alone, and the two AI submodules, atlasml and atlasllm, are opted into separately.

The chat tool services (AtlasAgentToolsService for the main agent, CompetencyExpertToolsService, CompetencyMappingToolsService, and ExerciseMappingToolsService for its sub-agents) and the orchestration tool services (OrchestratorReadToolsService, OrchestratorPlanningToolsService, OrchestratorDelegationToolsService, the worker services CreatorToolsService, EditorToolsService, and AssignerToolsService, and the terminal tools AtlasOrchestratorTerminalToolService and AtlasWorkerTerminalToolService) apply Artemis-owned competency, mapping, and course operations. AtlasAgentToolConfig gives every agent role its own tool surface. Results are persisted in Artemis through the normal competency and course services.

ContentExtractionService is a native Atlas preprocessing flow for all exercise types and for the lecture units that orchestration supports (text units with content, online units, and attachment or video units with a description). It uses Artemis Spring AI to identify narrowly removable flavor-text edits, applies those edits locally, and supplies the resulting learning-focused content before competency orchestration and optional AtlasML mapping suggestions. If the chat client or flavor-strip model is unavailable, it passes the raw content through unchanged.

Autonomous rounds and flavor stripping use an isolated Responses ChatClient by default; interactive Atlas and other modules retain the shared client. The adapter preserves ordered Responses output items, including encrypted reasoning, while the Spring AI tool advisor executes callbacks. Each run owns one shared tool budget and a completeOrchestration(verified, message) terminal decision. A successful index refresh after the latest work is required for verified completion. Budget exhaustion or missing/unverified completion is terminal and preserves applied actions without automatically replaying the run. See Atlas model configuration for defaults and the explicit transport fallback.

The shared budget in AtlasToolCallBudget allows 256 attempted tool callbacks per run, including reads and failed calls. After callback 224, only reads and completion remain available, and the last callback is reserved for the main orchestrator's completion. Nested calls inherit the same budget. OrchestratorToolContextKeys.MAX_DELEGATION_CALLS permits at most 16 synchronous worker delegations per run. Workers receive only course-scoped reads, their role-specific mutations, and a one-shot completion tool; they cannot delegate further.

Chat flow

AtlasAgentResource is instructor-only and has no @FeatureToggle; the client hides the chat when Feature.AtlasAgent or the atlasllm module is off. AtlasAgentService keeps the conversation in the JDBC chat memory, keyed by course and user, and the main agent delegates to the Competency Expert, Competency Mapper, and Exercise Mapper. A multi-step request becomes a plan in ExecutionPlanStateManagerService that the instructor approves first. Each sub-agent returns a preview, which AtlasAgentSessionCacheService holds until the instructor approves it in the client; the approval then calls the sub-agent's save tool. The rule that nothing is saved before approval lives in the prompts, not in code: the save tools are always registered.

Orchestration flow

AutonomousCompetencyExerciseEventListener (on ExerciseVersionCreatedEvent, limited to ExerciseVersionService.COMPETENCY_RELEVANT_FIELDS) and AutonomousCompetencyLectureUnitEventListener (on LectureUnitContentChangedEvent) check Feature.AtlasAgent and the course's autoOrchestratorEnabled and queue the change in ContentChangeAccumulatorService, a per-course distributed map. On the scheduling node, ContentChangeScheduler claims a course once its debounce window has passed and its daily cap allows another run, and calls CompetencyOrchestrationService.runBatch. CompetencyOrchestrationResource (guarded by Feature.AtlasAgent) runs a single exercise or lecture unit immediately, together with anything already queued, and skips the debounce window and the daily cap. Each run holds a per-course lock, so only one run per course is active. Turning off the course switch discards the queued changes of that course.

Workers commit every write immediately, and the run reports them as applied actions. A failed run that wrote nothing is queued again, unless it stopped at the tool budget or did not finish verifiably; a partial run is never queued again, so committed changes are not applied twice. Learning objects whose content extraction failed are queued again after any run. Results reach the client through the AtlasWebsocketTopics.ORCHESTRATION_SUMMARY topic and, for automatic runs, through AtlasCompetencyUpdateNotificationService.

To change agent behavior, edit the prompt templates in src/main/resources/prompts/atlas/, which AtlasPromptTemplateService renders. A new tool must be registered for its role in AtlasAgentToolConfig; orchestration tools count against the shared budget. Tests are under src/test/java/de/tum/cit/aet/artemis/atlas/agent and .../atlas/service.

Optional AtlasML REST boundary

AtlasMLService, AtlasMLApi, and their transport beans require both artemis.atlas.enabled and artemis.atlas.atlasml.enabled. CompetencyAtlasMLNotificationService requires only the Atlas module and becomes a no-op when its optional AtlasMLApi is absent. Feature.AtlasML additionally gates AtlasML write and mapping operations and the direct suggestion endpoints, but not every client method. AtlasML is not required for the native Atlas workflows; Artemis remains authoritative for its competency data and emits applicable notifications or calls only through this client boundary.

AtlasML owns its ML pipeline implementation, including its own persistence and vector behavior. Refer to AtlasML pipelines for those details. Do not infer a particular AtlasML deployment or runtime model configuration from the presence of the Artemis client.

Artemis Global Search

Artemis Global Search is a standalone Artemis feature, not an Iris pipeline. When artemis.weaviate.enabled enables the integration, Artemis uses WeaviateService, SearchableEntityWeaviateService, WeaviateSchemas, and the searchable-entity DTOs to maintain Artemis-owned schemas and documents. GlobalSearchResource applies Artemis authorization and course/entity filters before returning query results.

The searchable-entity schema covers Artemis content such as courses, exercises, exams, lectures and lecture units, FAQs, and communication entities. Entity lifecycle callers update or remove the corresponding Artemis documents; startup migration services manage the Artemis schema lifecycle.

A Weaviate instance can be shared with Iris, but the two consumers use independent collection namespaces and data flows. Artemis Global Search does not call Iris RAG, and Iris lecture answers do not use the Artemis Global Search authorization/query contract. For setup and operational details, use Global Search & Weaviate Setup and Weaviate Setup.

Change guidance

When changing an AI-related feature, first identify the owning boundary:

1. Preserve Artemis-side authorization, data minimization, request construction, job tracking, and callback validation.
2. Keep service-owned execution claims in the linked service documentation instead of copying or guessing them here.
3. Treat configuration as configuration. Do not turn a property, feature flag, or source default into a claim about live deployments or provider assignment.
4. Keep Artemis Global Search separate from Iris RAG, even if both use the same Weaviate infrastructure.
5. Treat a model-supplied id, position or version as untrusted input. Scope it to the course of the job, and take a version from the run snapshot rather than from the request or the current database state.