Iris: Add context awareness (#598)

Co-authored-by: Benjamin Schmitz <benjamin.schmitz@tum.de>

Author: vivienxr

iris/src/iris/domain/chat/chat_pipeline_execution_dto.py

@@ -1,9 +1,13 @@
 from typing import List, Optional
 
-from pydantic import Field
+from pydantic import Field, model_validator
 
 from iris.common.pyris_message import PyrisMessage
 from iris.domain.data.course_dto import CourseDTO
+from iris.domain.data.lecture_context_dto import (
+    CombinedViewContextDTO,
+    LectureContextDTO,
+)
 from iris.domain.data.lecture_dto import PyrisLectureDTO
 from iris.domain.data.metrics.student_metrics_dto import StudentMetricsDTO
 from iris.domain.data.programming_exercise_dto import ProgrammingExerciseDTO
@@ -34,7 +38,27 @@ class ChatPipelineExecutionDTO(PipelineExecutionDTO):
     text_exercise: Optional[TextExerciseDTO] = Field(alias="textExercise", default=None)
     lecture: Optional[PyrisLectureDTO] = None
     lecture_unit_id: Optional[int] = Field(alias="lectureUnitId", default=None)
+    context: Optional[List[LectureContextDTO]] = Field(
+        default=None,
+        description="Optional array of context objects (video/slides/combinedView) the student is currently viewing",
+    )
     programming_exercise_submission: Optional[ProgrammingSubmissionDTO] = Field(
         alias="programmingExerciseSubmission", default=None
     )
     text_exercise_submission: str = Field(alias="textExerciseSubmission", default="")
+
+    @model_validator(mode="after")
+    def extract_lecture_unit_id_from_combined_view_context(self):
+        """Extract lectureUnitId from a combinedView context if present.
+
+        This populates the lecture_unit_id field from the combinedView context's
+        nested slides/video objects, which is used for RAG filtering to scope
+        retrieval to the specific lecture unit.
+        """
+        # Only extract if lecture_unit_id is not already set
+        if self.lecture_unit_id is None and self.context:
+            for ctx in self.context:
+                if isinstance(ctx, CombinedViewContextDTO):
+                    self.lecture_unit_id = ctx.lecture_unit_id
+                    break
+        return self

iris/src/iris/domain/data/lecture_context_dto.py

@@ -0,0 +1,68 @@
+from typing import Literal, Optional, Union
+
+from pydantic import BaseModel, Field
+
+
+class VideoContextDTO(BaseModel):
+    """Context about a video lecture unit the student is currently viewing.
+
+    Sent from Artemis as part of the optional context array.
+    """
+
+    type: Literal["video"]
+    lecture_unit_id: int = Field(alias="lectureUnitId", gt=0)
+    timestamp: float = Field(ge=0)  # in seconds
+
+    class Config:
+        populate_by_name = True  # Allow both snake_case and camelCase
+
+
+class SlidesContextDTO(BaseModel):
+    """Context about a slides/PDF lecture unit the student is currently viewing.
+
+    Sent from Artemis as part of the optional context array.
+    """
+
+    type: Literal["slides"]
+    lecture_unit_id: int = Field(alias="lectureUnitId", gt=0)
+    page: int = Field(ge=1)  # PDF pages start at 1
+
+    class Config:
+        populate_by_name = True  # Allow both snake_case and camelCase
+
+
+class CombinedViewContextDTO(BaseModel):
+    """Context indicating the student is viewing a lecture unit in the combined
+    view.
+
+    Sent from Artemis as part of the optional context array. It nests an optional
+    ``slides`` and an optional ``video`` object describing the student's current
+    position; at least one of them is always present. Used for RAG filtering to
+    scope retrieval to the specific lecture unit.
+    """
+
+    type: Literal["combinedView"]
+    slides: Optional[SlidesContextDTO] = None
+    video: Optional[VideoContextDTO] = None
+
+    class Config:
+        populate_by_name = True  # Allow both snake_case and camelCase
+
+    @property
+    def lecture_unit_id(self) -> Optional[int]:
+        """Derive the lecture unit id from the nested slides/video objects.
+
+        Prefers ``slides.lecture_unit_id`` and falls back to
+        ``video.lecture_unit_id``. Returns ``None`` only in the (unexpected)
+        case where neither nested object is present.
+        """
+        if self.slides is not None:
+            return self.slides.lecture_unit_id
+        if self.video is not None:
+            return self.video.lecture_unit_id
+        return None
+
+
+# Union type for all structured context types
+# pylint: disable=invalid-name
+LectureContextDTO = Union[VideoContextDTO, SlidesContextDTO, CombinedViewContextDTO]