Support file uploads via response payload and prioritize over params["files"]

Adds `_resolve_submission` to handle responses containing code and file specifications in `"code"` and `"files"` keys. Updates `evaluation.py` to normalize and prioritize file sources from the response payload over `params["files"]`. Enhances tests to validate this logic. Updates documentation to reflect the new behavior.

Author: m-messer

CLAUDE.md

@@ -17,7 +17,7 @@ All source lives in `evaluation_function/`:
 ### Evaluation pipeline (`evaluation.py`)
 
 1. Run AST security check on student code
-2. If `params["files"]` is set, download the listed S3 objects once into a per-request working directory (see `s3_files.py`), used as the subprocess `cwd` for every run in this request
+2. Resolve the submission into `(code, file_specs)` via `_resolve_submission`: the response may be a bare code string, or a `{"code", "files"}` object (or JSON string of one) as sent by the LF web client's upload widget. If `file_specs` (from `response["files"]`, else `params["files"]`) is non-empty, download the listed objects once into a per-request working directory (see `s3_files.py`), used as the subprocess `cwd` for every run in this request
 3. Dispatch by `params["mode"]` (required):
    - **`demo`**: execute code with no stdin; return stdout/plots as `output` feedback (no pass/fail)
    - **`io_test`**: for each test in `params["tests"]`, execute with `test["input"]` as stdin and compare stdout against `test["expected_output"]`; upload matplotlib plots on pass or fail
@@ -108,6 +108,17 @@ All source lives in `evaluation_function/`:
         {"url": "https://.../helper.py?X-Amz-Signature=...", "name": "helper.py"},
     ]
 }
+
+# files in the response payload (how the LF web client sends uploads)
+# When the response area has a file-upload widget, the client delivers the
+# submission as {"code": ..., "files": [...]} (sometimes as a JSON string of
+# that object), with each file entry itself possibly a JSON string.
+# evaluation_function unpacks this: response["code"] becomes the student
+# code, response["files"] becomes the file list. Files in the response take
+# precedence over params["files"], which stays as a fallback. Entry shape is
+# the same {"url", "name"} as params["files"].
+{"code": "print(open('data.csv').read())",
+ "files": [{"url": "https://.../data.csv?...", "name": "data.csv"}]}
 ```
 
 ### Security model (`preview.py`)

evaluation_function/evaluation.py

@@ -322,37 +322,86 @@ def _evaluate_unit(response: str, test_code: str, result: Result, files_dir: str
     return result
 
 
+def _coerce_file_specs(raw: Any) -> list:
+    """Normalise a raw files value into a list of {url, name} dicts.
+
+    Entries may already be dicts, or JSON-encoded strings — the LF web
+    client currently serialises each upload entry to a string.
+    """
+    if not isinstance(raw, (list, tuple)):
+        return []
+    specs = []
+    for entry in raw:
+        if isinstance(entry, str):
+            try:
+                entry = json.loads(entry)
+            except (ValueError, TypeError):
+                continue
+        if isinstance(entry, dict):
+            specs.append(entry)
+    return specs
+
+
+def _resolve_submission(response: Any, params: Params) -> tuple[str, list]:
+    """Split the submission into (code, file_specs).
+
+    When file upload is enabled, the LF web client delivers the response
+    payload as {"code": ..., "files": [...]} (sometimes as a JSON string of
+    that object) rather than a bare code string. Files listed in the
+    response take precedence; params["files"] is the fallback.
+    """
+    payload = response
+    if isinstance(payload, str):
+        try:
+            parsed = json.loads(payload)
+        except (ValueError, TypeError):
+            parsed = None
+        if isinstance(parsed, dict) and ("code" in parsed or "files" in parsed):
+            payload = parsed
+
+    if isinstance(payload, dict):
+        code = payload.get("code") or ""
+        response_files = _coerce_file_specs(payload.get("files"))
+    else:
+        code = payload if isinstance(payload, str) else str(payload)
+        response_files = []
+
+    file_specs = response_files or _coerce_file_specs(params.get("files"))
+    return str(code), file_specs
+
+
 def evaluation_function(response: Any, answer: Any, params: Params) -> Result:
     result = Result()
     mode = params.get("mode")
     if mode not in ("demo", "io_test", "unit_test"):
         result.add_feedback("error", f"Unknown or missing mode: {mode!r}. Expected 'demo', 'io_test', or 'unit_test'.")
         return result
 
+    code, file_specs = _resolve_submission(response, params)
+
     files_dir = None
     try:
         file_warnings: list[str] = []
-        file_specs = params.get("files")
         if file_specs:
             files_dir = tempfile.mkdtemp()
             file_warnings = download_files(file_specs, files_dir)
 
         if mode == "demo":
-            result = _evaluate_demo(str(response), result, files_dir)
+            result = _evaluate_demo(code, result, files_dir)
         elif mode == "io_test":
             ans = str(answer) if params.get("use_answer_as_expected_output") else ""
-            result = _evaluate_io(str(response), params.get("tests", []), result, answer=ans, files_dir=files_dir)
+            result = _evaluate_io(code, params.get("tests", []), result, answer=ans, files_dir=files_dir)
         else:
             test_code = str(answer) if params.get("use_answer_as_test_code") else params.get("test_code", "")
-            result = _evaluate_unit(str(response), test_code, result, files_dir=files_dir)
+            result = _evaluate_unit(code, test_code, result, files_dir=files_dir)
 
         for warning in file_warnings:
             result.add_feedback("error", warning)
 
         pep8_param = params.get("pep8_feedback")
         if pep8_param:
             select = pep8_param if isinstance(pep8_param, list) else _PEP8_SELECT
-            violations = _check_pep8(str(response), select)
+            violations = _check_pep8(code, select)
             if violations:
                 body = "Style suggestions (PEP8):\n" + "\n".join(f"- {v}" for v in violations)
             else:

evaluation_function/evaluation_test.py

@@ -1,3 +1,4 @@
+import json
 import os
 import tempfile
 import unittest
@@ -392,6 +393,92 @@ def test_legacy_filename_key_does_not_crash(self):
         self.assertIn("missing", result["feedback"].lower())
 
 
+class TestFilesInResponsePayload(unittest.TestCase):
+    """The LF web client delivers uploads inside the response payload as
+    {"code": ..., "files": [...]} rather than in params["files"]."""
+
+    @patch("evaluation_function.evaluation.download_files")
+    def test_response_dict_with_code_and_files(self, mock_download):
+        mock_download.side_effect = _stub_download({"data.csv": "1,2,3"})
+        response = {
+            "code": "print(open('data.csv').read())",
+            "files": [{"url": "https://example.com/k", "name": "data.csv"}],
+        }
+        result = evaluation_function(response, None, {"mode": "demo"}).to_dict()
+
+        self.assertIn("1,2,3", result["feedback"])
+        mock_download.assert_called_once()
+        passed_specs = mock_download.call_args[0][0]
+        self.assertEqual(passed_specs, [{"url": "https://example.com/k", "name": "data.csv"}])
+
+    @patch("evaluation_function.evaluation.download_files")
+    def test_response_dict_file_entries_are_json_strings(self, mock_download):
+        mock_download.side_effect = _stub_download({"data.csv": "42"})
+        response = {
+            "code": "print(open('data.csv').read())",
+            "files": [json.dumps({"url": "https://example.com/k", "name": "data.csv"})],
+        }
+        result = evaluation_function(response, None, {"mode": "demo"}).to_dict()
+
+        self.assertIn("42", result["feedback"])
+        passed_specs = mock_download.call_args[0][0]
+        self.assertEqual(passed_specs, [{"url": "https://example.com/k", "name": "data.csv"}])
+
+    @patch("evaluation_function.evaluation.download_files")
+    def test_response_is_json_string_of_payload(self, mock_download):
+        mock_download.side_effect = _stub_download({"data.csv": "7"})
+        response = json.dumps({
+            "code": "print(open('data.csv').read())",
+            "files": [{"url": "https://example.com/k", "name": "data.csv"}],
+        })
+        result = evaluation_function(response, None, {"mode": "demo"}).to_dict()
+
+        self.assertIn("7", result["feedback"])
+        mock_download.assert_called_once()
+
+    @patch("evaluation_function.evaluation.download_files")
+    def test_unit_test_mode_reads_files_from_response(self, mock_download):
+        mock_download.side_effect = _stub_download({"data.csv": "x"})
+        response = {
+            "code": "",
+            "files": [{"url": "https://example.com/k", "name": "data.csv"}],
+        }
+        params = {
+            "mode": "unit_test",
+            "test_code": "import os\ndef test_present():\n    assert os.path.isfile('data.csv')\n",
+        }
+        result = evaluation_function(response, None, params).to_dict()
+
+        self.assertTrue(result["is_correct"])
+        self.assertIn("1/1 tests passed", result["feedback"])
+
+    @patch("evaluation_function.evaluation.download_files")
+    def test_plain_string_response_still_uses_params_files(self, mock_download):
+        mock_download.side_effect = _stub_download({"data.csv": "9"})
+        params = {"mode": "demo", "files": [{"url": "https://example.com/k", "name": "data.csv"}]}
+        result = evaluation_function("print(open('data.csv').read())", None, params).to_dict()
+
+        self.assertIn("9", result["feedback"])
+
+    @patch("evaluation_function.evaluation.download_files")
+    def test_response_files_take_precedence_over_params_files(self, mock_download):
+        mock_download.side_effect = _stub_download({"data.csv": "from_response"})
+        response = {
+            "code": "print(open('data.csv').read())",
+            "files": [{"url": "https://example.com/response", "name": "data.csv"}],
+        }
+        params = {"mode": "demo", "files": [{"url": "https://example.com/params", "name": "other.csv"}]}
+        evaluation_function(response, None, params)
+
+        passed_specs = mock_download.call_args[0][0]
+        self.assertEqual(passed_specs, [{"url": "https://example.com/response", "name": "data.csv"}])
+
+    def test_response_dict_without_files_no_download(self):
+        with patch("evaluation_function.evaluation.download_files") as mock_download:
+            evaluation_function({"code": "print('hi')"}, None, {"mode": "demo"})
+            mock_download.assert_not_called()
+
+
 class TestUnexpectedExceptionHandling(unittest.TestCase):
 
     @patch("evaluation_function.evaluation._run_code")