From 8d462dd550213651de67b45284ac889979dc1fe3 Mon Sep 17 00:00:00 2001
From: AkhileshNegi <akhileshnegi.an3@gmail.com>
Date: Wed, 9 Sep 2026 02:30:29 +0530
Subject: [PATCH 1/3] fix(collections): lowercase file extension for OpenAI
 upload
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A knowledge base document uploaded as `report.PDF` is accepted at upload —
`get_file_format` lowercases the suffix — and `fname` is stored with its
original case, since it drives the download attachment name. OpenAI file
search may not match an uppercase suffix in every ingestion path, and a
failed file in a batch is a hard failure that rolls back the whole vector
store.

Send `files.create` the stem plus a lowercased extension; the stored
`fname` is untouched.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../services/collections/providers/openai.py  |  7 ++++++-
 .../providers/test_openai_provider.py         | 21 +++++++++++++++++++
 docs/wiki/modules/knowledge-base.md           |  1 +
 3 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/backend/app/services/collections/providers/openai.py b/backend/app/services/collections/providers/openai.py
index 770e0773f..9626f52e4 100644
--- a/backend/app/services/collections/providers/openai.py
+++ b/backend/app/services/collections/providers/openai.py
@@ -1,5 +1,6 @@
 import logging
 import tempfile
+from pathlib import PurePosixPath
 from typing import IO, List, cast
 
 from openai import OpenAI
@@ -47,8 +48,12 @@ def upload_files(
                     if doc.file_size_kb is None:
                         doc.file_size_kb = round(tmp.tell() / 1024, 2)
                     tmp.seek(0)
+                    # Stored fname keeps its case (drives the download attachment
+                    # name); file search may not match an uppercase suffix.
+                    name = PurePosixPath(doc.fname)
                     uploaded = self.client.files.create(
-                        file=(doc.fname, tmp), purpose="assistants"
+                        file=(f"{name.stem}{name.suffix.lower()}", tmp),
+                        purpose="assistants",
                     )
             except Exception as err:
                 logger.error(
diff --git a/backend/app/tests/services/collections/providers/test_openai_provider.py b/backend/app/tests/services/collections/providers/test_openai_provider.py
index d31fb0ae3..84a1a5bba 100644
--- a/backend/app/tests/services/collections/providers/test_openai_provider.py
+++ b/backend/app/tests/services/collections/providers/test_openai_provider.py
@@ -317,6 +317,27 @@ def test_upload_files_file_name_matches_doc_fname() -> None:
     assert fname == "report.pdf"
 
 
+def test_upload_files_lowercases_extension() -> None:
+    """Only the extension is lowercased; the stem keeps its case."""
+    client = MagicMock()
+    client.files.create.return_value = MagicMock(id="file-abc")
+    provider = OpenAIProvider(client=client)
+
+    storage = _make_storage(b"data")
+    doc = _make_doc(file_size_kb=1.0)
+    doc.fname = "Report.PDF"
+
+    session_p, crud_p = _patch_session_and_crud()
+    with session_p as MockSession, crud_p:
+        MockSession.return_value.__enter__.return_value = MagicMock()
+        MockSession.return_value.__exit__.return_value = False
+        provider.upload_files(storage, [doc], project_id=1)
+
+    _, kwargs = client.files.create.call_args
+    fname, _ = kwargs["file"]
+    assert fname == "Report.pdf"
+
+
 def test_upload_files_raises_on_db_update_failure() -> None:
     client = MagicMock()
     client.files.create.return_value = MagicMock(id="file-ok")
diff --git a/docs/wiki/modules/knowledge-base.md b/docs/wiki/modules/knowledge-base.md
index 4cefd5719..179b0c69d 100644
--- a/docs/wiki/modules/knowledge-base.md
+++ b/docs/wiki/modules/knowledge-base.md
@@ -35,6 +35,7 @@ All paths relative to `backend/app/`.
 ## Gotchas
 - `signed_url` behaviour is chosen per request by the `download` query param (default false = inline, as before). `put()` stores the upload's `Content-Type`, so a bare presigned URL for a PDF opens in a tab (CSV/XLSX datasets happen to download, which is why only KB docs looked broken). `get_signed_url(..., filename=...)` adds `ResponseContentDisposition: attachment`; `_signed_url()` in `services/documents/helpers.py` passes `fname` only when `download` is set, and the flag threads through `build_document_schema(s)` / `build_job_schema(s)` from `api/routes/documents.py`, `doc_transformation_job.py` and `collections.py`. An attachment URL will not render in an `<iframe>`, so preview callers must leave `download` off. The upload response and the doc-transform callback have no request to carry the flag and always sign inline. Leave `filename` unset for URLs meant to play inline (TTS audio in `api/routes/llm.py`).
 - Uploads de-duplicate by provider file ID (see deep dive §7).
+- Extension case: `get_file_format` lowercases the suffix, so `report.PDF` uploads fine and is stored with its original case in `fname` (the `download` attachment name depends on it). OpenAI file search may not match an uppercase suffix, so `services/collections/providers/openai.py` lowercases only the extension of the name it sends to `files.create`.
 - Collections are immutable-ish: deletion semantics in deep dive §10.
 - OpenAI file-batch id: the SDK's `file_batches.poll()` / `upload_and_poll()` final return deserializes a vector-store body, so its `.id` is the `vs_` id, not the `vsfb_` batch id. `crud/rag/open_ai.py` captures the batch id from `create()` before polling and uses it for `list_files`. Any failed file is a hard failure (whole vector store rolled back); partial indexing needs an add-documents endpoint first.
 - The SDK's `file_batches.poll()` never times out. `_poll_file_batch` polls `retrieve` in a loop with no internal deadline — the Celery soft time limit bounds it, and its `SoftTimeLimitExceeded` aborts the task. An earlier version took a deadline from the caller via a `task_budget` `ContextVar` (and a fixed `BATCH_POLL_TIMEOUT_SECONDS`); both were deleted. Don't reintroduce caller coupling here.

From 5baeeeecec24b0742af1ec46632dfdf20d6f22a1 Mon Sep 17 00:00:00 2001
From: AkhileshNegi <akhileshnegi.an3@gmail.com>
Date: Wed, 9 Sep 2026 13:21:53 +0530
Subject: [PATCH 2/3] refactor: simplify filename normalization without
 PurePosixPath

Use string rsplit instead of pathlib import. Same pattern already in codebase
(stt_evaluations/audio.py). Clear variable names: filename + extension.
---
 backend/app/services/collections/providers/openai.py | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/backend/app/services/collections/providers/openai.py b/backend/app/services/collections/providers/openai.py
index 9626f52e4..84993268c 100644
--- a/backend/app/services/collections/providers/openai.py
+++ b/backend/app/services/collections/providers/openai.py
@@ -1,6 +1,5 @@
 import logging
 import tempfile
-from pathlib import PurePosixPath
 from typing import IO, List, cast
 
 from openai import OpenAI
@@ -48,11 +47,13 @@ def upload_files(
                     if doc.file_size_kb is None:
                         doc.file_size_kb = round(tmp.tell() / 1024, 2)
                     tmp.seek(0)
-                    # Stored fname keeps its case (drives the download attachment
-                    # name); file search may not match an uppercase suffix.
-                    name = PurePosixPath(doc.fname)
+                    if "." in doc.fname:
+                        filename, extension = doc.fname.rsplit(".", 1)
+                        normalized_fname = f"{filename}.{extension.lower()}"
+                    else:
+                        normalized_fname = doc.fname
                     uploaded = self.client.files.create(
-                        file=(f"{name.stem}{name.suffix.lower()}", tmp),
+                        file=(normalized_fname, tmp),
                         purpose="assistants",
                     )
             except Exception as err:

From a718f4dd9692f8e6a8091c09d1943cd49b3f93ba Mon Sep 17 00:00:00 2001
From: AkhileshNegi <akhileshnegi.an3@gmail.com>
Date: Wed, 9 Sep 2026 13:27:12 +0530
Subject: [PATCH 3/3] test(collections): merge filename tests into one
 parametrized case

The two upload_files filename tests differed only in input/expected, so
collapse them and add the extensionless case, which had no coverage.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../providers/test_openai_provider.py         | 41 +++++++------------
 1 file changed, 15 insertions(+), 26 deletions(-)

diff --git a/backend/app/tests/services/collections/providers/test_openai_provider.py b/backend/app/tests/services/collections/providers/test_openai_provider.py
index 84a1a5bba..8d8cf42c0 100644
--- a/backend/app/tests/services/collections/providers/test_openai_provider.py
+++ b/backend/app/tests/services/collections/providers/test_openai_provider.py
@@ -296,36 +296,25 @@ def test_upload_files_empty_docs_is_noop() -> None:
     client.files.create.assert_not_called()
 
 
-def test_upload_files_file_name_matches_doc_fname() -> None:
-    """The file tuple passed to OpenAI must carry the original filename."""
-    client = MagicMock()
-    client.files.create.return_value = MagicMock(id="file-abc")
-    provider = OpenAIProvider(client=client)
-
-    storage = _make_storage(b"data")
-    doc = _make_doc(file_size_kb=1.0)
-    doc.fname = "report.pdf"
-
-    session_p, crud_p = _patch_session_and_crud()
-    with session_p as MockSession, crud_p:
-        MockSession.return_value.__enter__.return_value = MagicMock()
-        MockSession.return_value.__exit__.return_value = False
-        provider.upload_files(storage, [doc], project_id=1)
-
-    _, kwargs = client.files.create.call_args
-    fname, _ = kwargs["file"]
-    assert fname == "report.pdf"
-
-
-def test_upload_files_lowercases_extension() -> None:
-    """Only the extension is lowercased; the stem keeps its case."""
+@pytest.mark.parametrize(
+    ("fname", "expected"),
+    [
+        ("report.pdf", "report.pdf"),
+        ("Report.PDF", "Report.pdf"),
+        ("README", "README"),
+    ],
+)
+def test_upload_files_file_name_lowercases_only_extension(
+    fname: str, expected: str
+) -> None:
+    """The file tuple passed to OpenAI keeps the stem's case, lowercases the extension."""
     client = MagicMock()
     client.files.create.return_value = MagicMock(id="file-abc")
     provider = OpenAIProvider(client=client)
 
     storage = _make_storage(b"data")
     doc = _make_doc(file_size_kb=1.0)
-    doc.fname = "Report.PDF"
+    doc.fname = fname
 
     session_p, crud_p = _patch_session_and_crud()
     with session_p as MockSession, crud_p:
@@ -334,8 +323,8 @@ def test_upload_files_lowercases_extension() -> None:
         provider.upload_files(storage, [doc], project_id=1)
 
     _, kwargs = client.files.create.call_args
-    fname, _ = kwargs["file"]
-    assert fname == "Report.pdf"
+    uploaded_fname, _ = kwargs["file"]
+    assert uploaded_fname == expected
 
 
 def test_upload_files_raises_on_db_update_failure() -> None: