Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: preserve conversation archive order for turns with attachments (#14768)

oobaboogabb89072db96c
diff --git a/studio/backend/core/rag/conversation_archive.py b/studio/backend/core/rag/conversation_archive.py
index cd10b2cdda8..6ee7ee4dfd7 100644
--- a/studio/backend/core/rag/conversation_archive.py
+++ b/studio/backend/core/rag/conversation_archive.py
@@ -1131,6 +1131,30 @@ def _flushes_local_pair(part: dict) -> bool:
return part.get("result") is not None
+def _with_attachments(message: dict):
+ """Content plus attachments, as `collectTextParts` (chat-adapter.ts) sends it; else the turn takes `_fallback_ordinal`."""
+ content = message.get("content")
+ attachments = message.get("attachments")
+ if not isinstance(attachments, list) or str(message.get("role") or "") == "assistant":
+ return content
+ attached = [
+ part
+ for attachment in attachments
+ if isinstance(attachment, dict)
+ and attachment.get("mcpToolOnly") is not True
+ and isinstance(attachment.get("content"), list)
+ for part in attachment["content"]
+ if isinstance(part, dict) and part.get("type") in ("text", "image")
+ ]
+ if not attached:
+ return content
+ if isinstance(content, list):
+ return [*content, *attached]
+ if isinstance(content, str) and content:
+ return [{"type": "text", "text": content}, *attached]
+ return attached
+
+
def _as_wire(messages: list[dict], sanitise_assistant: bool = True) -> list[dict]:
"""Persisted chat rows in the shape the inference layer sends them.
@@ -1158,7 +1182,7 @@ def _as_wire(messages: list[dict], sanitise_assistant: bool = True) -> list[dict
"""
wire: list[dict] = []
for message in messages:
- content = message.get("content")
+ content = _with_attachments(message)
parts = content if isinstance(content, list) else None
# Reasoning is not content: the serializer never puts it in `content`, but `_probe_text` renders any part with
# a `text` field, so forwarding the stored list put a model's thinking inline and the turn matched no
@@ -1267,6 +1291,23 @@ def _as_wire(messages: list[dict], sanitise_assistant: bool = True) -> list[dict
return wire
+# `withSandboxAttachmentPaths` (sandbox-attachments.ts) path notes, as `checkpoint._ATTACHMENT` matches them.
+_SANDBOX_NOTE = re.compile(
+ r"^\[[^\n]*(?: is saved at \.unsloth_attachments/[0-9a-f]{12}/[^\n]* in the python tool's working directory"
+ r"|: its text is below, so answer from it\. For calculations, the python tool has the file at "
+ r"path = \"\.unsloth_attachments/[0-9a-f]{12}/)[^\n]*\]$",
+ re.MULTILINE,
+)
+
+
+def _seat_text(message: dict) -> str:
+ """The seat-matching probe minus python path notes, which only the request carries."""
+ text = _probe_text(message)
+ if str(message.get("role") or "") == "user":
+ text = _SANDBOX_NOTE.sub("", text)
+ return _normalise_cased(text)
+
+
def _fallback_ordinal(conn, scope: str, positions: Optional[list[list[str]]]) -> int:
"""Where a turn that matched no seat goes: past the archive AND past the transcript.
@@ -1312,11 +1353,7 @@ def _transcript_positions(thread_id: str, branch = None) -> Optional[list[str]]:
# Grouped with the evictor's own grouper, so a position is a TURN's index, which is what the ordinal is compared
# against.
wire = _as_wire(_active_chain(messages, branch))
- return [
- [_normalise_cased(_probe_text(message)) for message in group]
- for group in group_turns(wire)
- if group
- ]
+ return [[_seat_text(message) for message in group] for group in group_turns(wire) if group]
def _occurrences(positions: Optional[list[list[str]]], group: list[dict]) -> list[int]:
@@ -1338,7 +1375,7 @@ def _occurrences(positions: Optional[list[list[str]]], group: list[dict]) -> lis
"""
if not positions or not group:
return []
- texts = [_normalise_cased(_probe_text(message)) for message in group]
+ texts = [_seat_text(message) for message in group]
if not texts or not texts[0]:
return []
calls = [bool(message.get("tool_calls")) for message in group]
@@ -1475,9 +1512,7 @@ def _live_positions(live: Optional[list[dict]]) -> Optional[list[list[str]]]:
except Exception:
return None
positions = [
- [_normalise_cased(_probe_text(message)) for message in group]
- for group in group_turns(_as_wire(live))
- if group
+ [_seat_text(message) for message in group] for group in group_turns(_as_wire(live)) if group
]
return positions or None
diff --git a/studio/backend/tests/test_conversation_archive.py b/studio/backend/tests/test_conversation_archive.py
index 12d3983e20c..781ec3c60a5 100644
--- a/studio/backend/tests/test_conversation_archive.py
+++ b/studio/backend/tests/test_conversation_archive.py
@@ -2593,6 +2593,220 @@ def test_an_out_of_order_eviction_still_numbers_turns_in_conversation_order(conn
assert text.index("standing instruction") < text.index("middle turn") < text.index("final turn")
+_REPORT = "[PDF: report.pdf]\nThe service listens on port 8080."
+_REPORT_SHA = "0123456789ab" + "0" * 52
+_REPORT_NOTE = (
+ "[report.pdf: its text is below, so answer from it. For calculations, the python tool has the "
+ 'file at path = ".unsloth_attachments/0123456789ab/report.pdf"; fitz.open(path)]'
+)
+_BOOK_PLACEHOLDER = "[book.epub: only the python tool can read this file]"
+_BOOK_NOTE = (
+ "[book.epub is saved at .unsloth_attachments/0123456789ab/book.epub in the python tool's "
+ 'working directory; open it with fitz.open(path), where path = ".unsloth_attachments/0123456789ab/book.epub"]'
+)
+
+
+def _document(name, text):
+ """An attached file as the frontend stores it: apart from the typed words."""
+ return {
+ "id": f"att-{name}",
+ "type": "document",
+ "name": name,
+ "contentType": "text/plain",
+ "content": [{"type": "text", "text": text}],
+ "status": {"type": "complete"},
+ "original": {"sha256": _REPORT_SHA, "sizeBytes": 10},
+ }
+
+
+def _save_rows(thread_id, rows):
+ """Persist (role, typed text, attachments) rows in the shape the frontend stores them."""
+ from storage import studio_db
+
+ studio_db.upsert_chat_thread(
+ {
+ "id": thread_id,
+ "title": "t",
+ "modelType": "base",
+ "modelId": "local-model",
+ "createdAt": 1,
+ }
+ )
+ stored = []
+ for index, (role, text, attachments) in enumerate(rows):
+ row = {
+ "id": f"{thread_id}-{index}",
+ "threadId": thread_id,
+ "parentId": f"{thread_id}-{index - 1}" if index else None,
+ "role": role,
+ "content": [{"type": "text", "text": text}],
+ "createdAt": index + 2,
+ }
+ if attachments:
+ row["attachments"] = attachments
+ stored.append(row)
+ studio_db.sync_chat_messages(thread_id, stored, prune_missing = True)
+
+
+def _ordinals_by_text(conn, thread_id = THREAD):
+ scope = store.conversation_archive_scope(thread_id)
+ return {
+ row["text"]: row["archive_ordinal"]
+ for row in conn.execute(
+ "SELECT d.archive_ordinal, c.text FROM documents d JOIN chunks c ON c.document_id = d.id "
+ "WHERE d.scope = ? ORDER BY d.archive_ordinal",
+ (scope,),
+ ).fetchall()
+ }
+
+
+def _report_then_correction(sent_report):
+ """A turn sent with a document, a later correction, then a newer turn. Returns the wire messages."""
+ _save_rows(
+ THREAD,
+ [
+ ("user", "Here is the deployment report.", [_document("report.pdf", _REPORT)]),
+ ("assistant", "Noted, the service listens on port 8080.", None),
+ ("user", "Correction: the service now listens on port 9090.", None),
+ ("assistant", "Updated, the port is 9090.", None),
+ ("user", "Unrelated: what do pelicans eat?", None),
+ ],
+ )
+ return [
+ {"role": "user", "content": f"Here is the deployment report.\n{sent_report}"},
+ {"role": "assistant", "content": "Noted, the service listens on port 8080."},
+ {"role": "user", "content": "Correction: the service now listens on port 9090."},
+ {"role": "assistant", "content": "Updated, the port is 9090."},
+ {"role": "user", "content": "Unrelated: what do pelicans eat?"},
+ ]
+
+
+ "sent_report",
+ [_REPORT, f"{_REPORT_NOTE}\n{_REPORT}"],
+ ids = ["python-off", "python-on"],
+)
+def test_a_turn_sent_with_an_attachment_keeps_its_place(conn, sent_report):
+ """The stored row keeps the document under `attachments` while the request inlines it (after the python
+ tool's path note when that is on). Read without them, the turn took the fallback ordinal and came back
+ as the latest turn, superseding the correction that followed it."""
+ wire = _report_then_correction(sent_report)
+
+ assert conversation_archive.archive_turns(THREAD, wire[:4], live = wire[4:]) == 2
+
+ ordinals = _ordinals_by_text(conn)
+ assert sorted(ordinals.values()) == [0, 1]
+ assert ordinals[next(text for text in ordinals if "8080" in text)] == 0
+ found = conversation_archive.recall(
+ THREAD, "which port does the service listen on", top_k = 4, branch_messages = wire
+ )
+ assert found is not None
+ text = found[0]
+ assert 'turn="1"' in text and 'turn="2"' in text
+ assert text.index("port 8080") < text.index("port 9090")
+
+
+def test_a_tool_only_attachment_keeps_its_place_with_the_python_tool_on(conn):
+ """The other note form: a file the python tool alone can read is sent as its path note and placeholder."""
+ _save_rows(
+ THREAD,
+ [
+ ("user", "Summarise chapter one.", [_document("book.epub", _BOOK_PLACEHOLDER)]),
+ ("assistant", "Chapter one is about pelicans.", None),
+ ("user", "And chapter two?", None),
+ ("assistant", "Chapter two is about herons.", None),
+ ("user", "Thanks.", None),
+ ],
+ )
+ wire = [
+ {"role": "user", "content": f"Summarise chapter one.\n{_BOOK_NOTE}\n{_BOOK_PLACEHOLDER}"},
+ {"role": "assistant", "content": "Chapter one is about pelicans."},
+ {"role": "user", "content": "And chapter two?"},
+ {"role": "assistant", "content": "Chapter two is about herons."},
+ ]
+
+ conversation_archive.archive_turns(THREAD, wire)
+
+ ordinals = _ordinals_by_text(conn)
+ assert ordinals[next(text for text in ordinals if "pelicans" in text)] == 0
+ assert ordinals[next(text for text in ordinals if "herons" in text)] == 1
+
+
+def test_an_attachment_turn_numbered_past_the_end_converges_on_the_next_compaction(conn):
+ """Archives written before the fold hold the attachment turn after every later one; the next eviction
+ of that turn moves it back to its seat."""
+ wire = _report_then_correction(_REPORT)
+ conversation_archive.archive_turns(THREAD, wire[:4], live = wire[4:])
+ scope = store.conversation_archive_scope(THREAD)
+ conn.execute(
+ "UPDATE documents SET archive_ordinal = 7 WHERE scope = ? AND archive_ordinal = 0", (scope,)
+ )
+ conn.commit()
+
+ assert conversation_archive.archive_turns(THREAD, wire[:4], live = wire[4:]) == 0
+
+ assert sorted(_ordinals_by_text(conn).values()) == [0, 1]
+
+
+def test_recall_without_a_request_branch_keeps_an_attachment_turn(conn):
+ """The branch filter's stored-transcript fallback reads the same rows: without the attachment text,
+ the archived turn looked rolled back and no query could return it. Studio always passes its branch,
+ so this covers other callers only, and only without the python tool's notes."""
+ wire = _report_then_correction(_REPORT)
+ conversation_archive.archive_turns(THREAD, wire[:4], live = wire[4:])
+
+ found = conversation_archive.recall(THREAD, "deployment report port 8080", top_k = 4)
+
+ assert found is not None
+ assert "The service listens on port 8080." in found[0]
+
+
+def test_stored_attachments_are_projected_the_way_the_client_sends_them():
+ image = {"type": "image", "image": "data:image/png;base64,AAAA"}
+ rows = [
+ {
+ "role": "user",
+ "content": [{"type": "text", "text": "typed"}],
+ "attachments": [
+ _document("a.md", "first file"),
+ {"id": "i", "type": "image", "name": "p.png", "content": [image]},
+ {"id": "t", "type": "image", "mcpToolOnly": True, "content": [image]},
+ _document("b.md", "second file"),
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [{"type": "text", "text": "reply"}],
+ "attachments": [_document("c.md", "not sent as text")],
+ },
+ {"role": "user", "content": [{"type": "text", "text": "plain"}]},
+ ]
+
+ wire = conversation_archive._as_wire(rows)
+
+ assert wire[0]["content"] == [
+ {"type": "text", "text": "typed"},
+ {"type": "text", "text": "first file"},
+ image,
+ {"type": "text", "text": "second file"},
+ ]
+ assert conversation_archive._probe_text(wire[0]) == "typed\nfirst file\nsecond file"
+ assert wire[1]["content"] == [{"type": "text", "text": "reply"}]
+ assert wire[2]["content"] is rows[2]["content"]
+
+
+def test_seat_text_drops_only_the_python_tool_path_notes():
+ live = {"role": "user", "content": f"typed\n{_REPORT_NOTE}\n{_REPORT}"}
+ quoted = {"role": "assistant", "content": f"typed\n{_REPORT_NOTE}"}
+ lookalike = {"role": "user", "content": "[report.pdf: its text is below, so answer from it.]"}
+
+ assert conversation_archive._seat_text(live) == conversation_archive._seat_text(
+ {"role": "user", "content": f"typed\n{_REPORT}"}
+ )
+ assert "its text is below" in conversation_archive._seat_text(quoted)
+ assert "its text is below" in conversation_archive._seat_text(lookalike)
+
+
def test_two_turns_that_start_the_same_do_not_take_each_others_places(conn):
"""Turns sharing a first message must match on the whole turn, or each takes the other's seat."""
first = _turn("continue ZQXVARA123", "the first continuation, about ducks")