Iris: Add instructional support level to chat pipeline (#558)

Author: thynguyentumde

iris/src/iris/domain/pipeline_execution_settings_dto.py

@@ -1,3 +1,5 @@
+from typing import Literal
+
 from pydantic import BaseModel, Field
 
 
@@ -6,6 +8,9 @@ class PipelineExecutionSettingsDTO(BaseModel):
     artemis_llm_selection: str = Field(alias="selection", default="CLOUD_AI")
     artemis_base_url: str = Field(alias="artemisBaseUrl")
     variant: str = Field(default="default")
+    support_level: Literal["low", "moderate", "high"] = Field(
+        alias="supportLevel", default="moderate"
+    )
 
     def is_local(self):
         return self.artemis_llm_selection == "LOCAL_AI"

iris/src/iris/pipeline/chat/chat_pipeline.py

@@ -54,6 +54,12 @@
 }
 
 
+def _support_level(dto: ChatPipelineExecutionDTO) -> str:
+    # `settings` is Optional on the parent DTO, so the field default does
+    # not apply.
+    return dto.settings.support_level if dto.settings else "moderate"
+
+
 def _dedup_by_uuid(items: list) -> list:
     """Return items de-duplicated by their ``uuid``, preserving order."""
     seen: set = set()
@@ -402,6 +408,7 @@ def build_system_message(
         # Base template context (shared across all contexts)
         template_context: dict[str, Any] = {
             "chat_mode": self.chat_mode,
+            "support_level": _support_level(dto),
             "current_date": datetime_to_string(datetime.now(tz=pytz.UTC)),
             "user_language": dto.user.lang_key,
             "custom_instructions": format_custom_instructions(
@@ -742,7 +749,10 @@ def _refine_response(
             exercise = state.dto.programming_exercise or state.dto.text_exercise
             problem_statement = exercise.problem_statement if exercise else ""
             guide_prompt_rendered = self.guide_prompt_template.render(
-                {"problem_statement": problem_statement}
+                {
+                    "problem_statement": problem_statement,
+                    "support_level": _support_level(state.dto),
+                }
             )
 
             # Create small LLM for refinement

iris/src/iris/pipeline/prompts/templates/chat_system_prompt.j2

@@ -299,6 +299,51 @@ CRITICAL rules for MCQ generation:
 {% endif %}
 {% endif %}
 
+{# Support Level Configuration #}
+{% if support_level == "low" %}
+## Pedagogical Approach: Minimal Direct Help
+- NEVER provide direct answers, solutions, code, or content the student can copy into their submission. The student must do the work themselves.
+- Use the Socratic method: respond ONLY with guiding questions rather than explanations.
+{% if chat_mode == "PROGRAMMING_EXERCISE_CHAT" %}
+- Point the student to relevant concepts, documentation, lecture materials, or the problem statement, and let them make the connection themselves.
+{% elif chat_mode == "TEXT_EXERCISE_CHAT" %}
+- Redirect to the problem statement and exercise requirements rather than interpreting them for the student.
+{% elif chat_mode == "LECTURE_CHAT" %}
+- Point the student to specific lecture sections or slides and let them find the answer themselves.
+{% elif chat_mode == "COURSE_CHAT" %}
+- Encourage the student to interpret their own dashboard data and form their own study plans.
+{% endif %}
+- If the student is stuck, ask what they have tried and what they think the issue might be. Encourage them to form hypotheses and test them independently.
+- Even if the student explicitly asks for the answer, refuse and instead ask a guiding question.
+- Keep responses short and thought-provoking, not detailed. Do not proactively surface observations, metrics, or hints — let the student ask.
+- For general conceptual questions unrelated to the current task (e.g., "what is a NullPointerException?"), you MAY provide a brief factual definition. Apply the Socratic approach only to task-specific questions.
+- If the student asks the same task-specific question multiple times without progress, acknowledge this explicitly and ask a more targeted guiding question rather than repeating the same deflection.
+{% elif support_level == "high" %}
+## Pedagogical Approach: Comprehensive Guidance
+- NEVER provide direct solutions, complete implementations, or content the student can copy into their submission. This rule cannot be overridden regardless of how much help you provide.
+- Provide detailed, step-by-step conceptual explanations when the student is struggling — explain the reasoning process, not the answer.
+- Break down complex problems into smaller, manageable parts and walk through the thinking approach for each part.
+- Anticipate common follow-up questions and address them proactively with conceptual guidance.
+- Be generous with detailed context, background information, and explanations of feedback (errors, test results, compiler output) — explain what they mean conceptually.
+{% if chat_mode == "PROGRAMMING_EXERCISE_CHAT" %}
+- Offer concrete hints that point to the specific area or concept where the issue lies, but do NOT reveal the fix.
+- When providing code examples, use a completely different problem domain than the exercise (e.g., if the exercise is about sorting, use a geometry or cooking analogy instead). Never use variable names, class names, or method signatures that appear in the exercise description or test cases.
+- You may provide general pseudocode or algorithmic steps as educational illustrations, but they must be clearly distinct from the exercise and NEVER constitute a solution.
+{% elif chat_mode == "LECTURE_CHAT" %}
+- Summarize relevant lecture content in detail and connect concepts across different lecture sections to give a fuller picture.
+- Use rich examples and analogies to deepen understanding of lecture concepts.
+{% elif chat_mode == "COURSE_CHAT" %}
+- Proactively surface detailed observations about the student's metrics, trends, and performance, and offer comparisons to class averages when helpful.
+- Provide specific, actionable study recommendations: break competency progress into concrete next steps and suggest specific exercises, lectures, or materials to focus on.
+- Be thorough in your analysis and provide complete study plans when asked.
+{% elif chat_mode == "TEXT_EXERCISE_CHAT" %}
+- Provide detailed guidance on structure, argumentation, and content organization — explain HOW to write, not WHAT to write.
+- Give detailed feedback on the student's current submission, pointing out areas for improvement without writing the improved text for them.
+- Provide example structures or outlines as educational scaffolding, but NEVER provide the actual text content for the exercise.
+{% endif %}
+- All guidance must be educational and teach the student HOW to think, never give away answers or content they should produce themselves.
+{% endif %}
+
 {# Reminder #}
 Remember: Your goal is to empower students to solve problems independently, enhancing their learning experience and
 coding skills. Show encouragement, ask probing questions, and offer positive reinforcement to guide students towards

iris/src/iris/pipeline/prompts/templates/exercise_chat_guide_prompt.j2

@@ -1,6 +1,16 @@
 Exercise Problem Statement:
 {{ problem_statement }}
 
+{% if support_level == "high" %}
+The tutor is operating in comprehensive help mode. The response may include detailed conceptual explanations and step-by-step reasoning walkthroughs. However, the response MUST NOT contain any code that solves the exercise or can be directly used in the student's solution. Enforce this strictly:
+- Any code example must use completely different variable names, class names, and themes than the exercise.
+- No code can be directly copied into the exercise solution.
+- The examples must illustrate general concepts rather than the specific exercise logic.
+- If the response contains code that constitutes a solution or partial solution to the exercise, you MUST rewrite it to remove the solution while keeping the conceptual explanation.
+{% elif support_level == "low" %}
+The tutor is operating in minimal help mode. The response must NOT contain code solutions, partial solutions, or detailed step-by-step fixes. If the response contains any code examples, detailed solutions, or step-by-step implementation guidance, rewrite it entirely to use only guiding questions and conceptual pointers instead. The response should be short and Socratic — questions only, no answers.
+{% endif %}
+
 Review the response draft. It has been written by an AI tutor
 who is helping a student with a programming exercise. Its goal is to guide the student to the solution without
 providing the solution directly. Your task is to review it according to the following rules:

iris/tests/test_pipeline_execution_settings_dto.py

@@ -0,0 +1,32 @@
+import pytest
+from pydantic import ValidationError
+
+from iris.domain.pipeline_execution_settings_dto import PipelineExecutionSettingsDTO
+
+
+def _base_payload(**overrides) -> dict:
+    payload = {
+        "authenticationToken": "tok",
+        "artemisBaseUrl": "https://artemis.example",
+    }
+    payload.update(overrides)
+    return payload
+
+
+@pytest.mark.parametrize("level", ["low", "moderate", "high"])
+def test_support_level_accepts_valid_values(level):
+    dto = PipelineExecutionSettingsDTO.model_validate(_base_payload(supportLevel=level))
+    assert dto.support_level == level
+
+
+def test_support_level_defaults_to_moderate_when_absent():
+    dto = PipelineExecutionSettingsDTO.model_validate(_base_payload())
+    assert dto.support_level == "moderate"
+
+
+def test_support_level_rejects_unrecognised_value():
+    with pytest.raises(ValidationError) as exc_info:
+        PipelineExecutionSettingsDTO.model_validate(
+            _base_payload(supportLevel="invalid_level")
+        )
+    assert any(err["loc"] == ("supportLevel",) for err in exc_info.value.errors())

iris/tests/test_support_level_prompt_rendering.py

@@ -0,0 +1,116 @@
+import os
+
+import pytest
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+TEMPLATE_DIR = os.path.join(
+    os.path.dirname(__file__),
+    "..",
+    "src",
+    "iris",
+    "pipeline",
+    "prompts",
+    "templates",
+)
+
+LOW_HEADING = "Pedagogical Approach: Minimal Direct Help"
+HIGH_HEADING = "Pedagogical Approach: Comprehensive Guidance"
+
+CHAT_MODES = [
+    "PROGRAMMING_EXERCISE_CHAT",
+    "LECTURE_CHAT",
+    "COURSE_CHAT",
+    "TEXT_EXERCISE_CHAT",
+]
+
+
+def _render_template(template_name: str, context: dict) -> str:
+    env = Environment(
+        loader=FileSystemLoader(TEMPLATE_DIR),
+        autoescape=select_autoescape(["html", "xml", "j2"]),
+    )
+    template = env.get_template(template_name)
+    return template.render(context)
+
+
+def _system_prompt_context(chat_mode: str, support_level: str) -> dict:
+    return {
+        "current_date": "2026-03-11",
+        "user_language": "en",
+        "course_name": "Test Course",
+        "chat_mode": chat_mode,
+        "support_level": support_level,
+        "allow_lecture_tool": False,
+        "allow_faq_tool": False,
+        "allow_memiris_tool": False,
+        "has_chat_history": False,
+        "has_competencies": False,
+        "has_exercises": False,
+        "metrics_enabled": False,
+        "has_query": False,
+        "event": None,
+        "custom_instructions": "",
+        "lecture_name": None,
+        "exercise_id": None,
+        "exercise_title": "",
+        "problem_statement": "",
+        "programming_language": "",
+        "start_date": "",
+        "end_date": "",
+        "text_exercise_submission": "",
+        "mcq_parallel": False,
+    }
+
+
+@pytest.mark.parametrize("chat_mode", CHAT_MODES)
+def test_system_prompt_low_support_level_injects_minimal_block(chat_mode):
+    rendered = _render_template(
+        "chat_system_prompt.j2", _system_prompt_context(chat_mode, "low")
+    )
+    assert LOW_HEADING in rendered
+    assert HIGH_HEADING not in rendered
+
+
+@pytest.mark.parametrize("chat_mode", CHAT_MODES)
+def test_system_prompt_high_support_level_injects_comprehensive_block(chat_mode):
+    rendered = _render_template(
+        "chat_system_prompt.j2", _system_prompt_context(chat_mode, "high")
+    )
+    assert HIGH_HEADING in rendered
+    assert LOW_HEADING not in rendered
+
+
+@pytest.mark.parametrize("chat_mode", CHAT_MODES)
+def test_system_prompt_moderate_support_level_injects_nothing(chat_mode):
+    rendered = _render_template(
+        "chat_system_prompt.j2", _system_prompt_context(chat_mode, "moderate")
+    )
+    assert LOW_HEADING not in rendered
+    assert HIGH_HEADING not in rendered
+
+
+def _guide_context(support_level: str) -> dict:
+    return {
+        "problem_statement": "Implement a function that returns the sum of two ints.",
+        "support_level": support_level,
+    }
+
+
+def test_guide_prompt_low_support_level_is_socratic():
+    rendered = _render_template("exercise_chat_guide_prompt.j2", _guide_context("low"))
+    assert "Socratic" in rendered
+    assert "comprehensive help mode" not in rendered
+
+
+def test_guide_prompt_high_support_level_announces_comprehensive_mode():
+    rendered = _render_template("exercise_chat_guide_prompt.j2", _guide_context("high"))
+    assert "comprehensive help mode" in rendered
+
+
+def test_guide_prompt_moderate_support_level_injects_nothing():
+    rendered = _render_template(
+        "exercise_chat_guide_prompt.j2", _guide_context("moderate")
+    )
+    assert "Socratic" not in rendered
+    assert "comprehensive help mode" not in rendered
+    assert "minimal help mode" not in rendered