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: keep attached documents in Deep Research reports (#16019)

Nilay7352b62dac15
diff --git a/studio/backend/core/research_runs.py b/studio/backend/core/research_runs.py
index c9c4085d09e..30636664e32 100644
--- a/studio/backend/core/research_runs.py
+++ b/studio/backend/core/research_runs.py
@@ -822,8 +822,25 @@ def _synthesis_evidence_budget(
)
+def _water_fill(lengths: list[int], available: int) -> list[int]:
+ limits = [0] * len(lengths)
+ for position, index in enumerate(sorted(range(len(lengths)), key = lambda i: lengths[i])):
+ limits[index] = min(lengths[index], available // (len(lengths) - position))
+ available -= limits[index]
+ return limits
+
+
+def _truncate_evidence(text: str, limit: int) -> str:
+ suffix = "\n[Evidence truncated]"
+ if len(text) <= limit:
+ return text
+ if limit <= len(suffix):
+ return text[:limit]
+ return text[: limit - len(suffix)].rstrip() + suffix
+
+
def _bounded_synthesis_evidence(
- notes: list[str], max_chars: int = _MAX_SYNTHESIS_EVIDENCE_CHARS
+ notes: list[str | tuple[str, ...]], max_chars: int = _MAX_SYNTHESIS_EVIDENCE_CHARS
) -> str:
if not notes:
return "(none)"
@@ -832,22 +849,31 @@ def _bounded_synthesis_evidence(
# Split evenly: a per-note floor lets early notes eat the budget and drop later steps entirely.
separator = "\n\n"
available = max(0, max_chars - len(separator) * (len(notes) - 1))
- base, remainder = divmod(available, len(notes))
- suffix = "\n[Evidence truncated]"
+ # A (heading, *parts) note pays its heading once and splits the rest of its share across parts.
+ texts = [
+ note if isinstance(note, str) else f"{note[0]}\n" + separator.join(note[1:])
+ for note in notes
+ ]
+ limits = _water_fill([len(text) for text in texts], available)
bounded = []
- for index, note in enumerate(notes):
- limit = base + (1 if index < remainder else 0)
- if len(note) <= limit:
- bounded.append(note)
- elif limit <= len(suffix):
- bounded.append(note[:limit])
- else:
- bounded.append(note[: limit - len(suffix)].rstrip() + suffix)
+ for note, text, limit in zip(notes, texts, limits):
+ parts = [] if isinstance(note, str) else list(note[1:])
+ room = limit - len(text) + sum(map(len, parts))
+ if len(text) <= limit or not parts or room <= 0:
+ bounded.append(_truncate_evidence(text, limit))
+ continue
+ part_limits = _water_fill([len(part) for part in parts], room)
+ bounded.append(
+ f"{note[0]}\n"
+ + separator.join(
+ _truncate_evidence(part, part_limit) for part, part_limit in zip(parts, part_limits)
+ )
+ )
return separator.join(bounded)[:max_chars]
def _fit_synthesis_context(
- notes: list[str],
+ notes: list[str | tuple[str, ...]],
prioritized_payloads: list[dict[str, Any]],
fixed_chars: int = 0,
inference: dict[str, Any] | None = None,
@@ -2286,7 +2312,7 @@ class ResearchSupervisor:
if selected_mcp
else []
)
- notes: list[str] = []
+ notes: list[str | tuple[str, ...]] = []
decision_notes: list[str] = []
research_state: dict[str, Any] = {}
sources: list[dict] = []
@@ -2381,13 +2407,17 @@ class ResearchSupervisor:
if web_evidence or rag_evidence or mcp_evidence:
completed_steps += 1
title = str(step.get("title") or "Recovered research step")
+ heading = f"### {title} ({action})\nInput: {argument}"
notes.append(
- f"### {title} ({action})\nInput: {argument}\nResult:\n{web_evidence}\n\n"
- f"Knowledge base:\n{rag_evidence}{mcp_evidence}"
- )
- decision_notes.append(
- f"### {title} ({action})\nInput: {argument}\nResult:\n{web_evidence}"
+ (
+ heading,
+ f"Result:\n{web_evidence}",
+ f"Knowledge base:\n{rag_evidence}{mcp_evidence}",
+ )
+ if rag_evidence or mcp_evidence
+ else f"{heading}\nResult:\n{web_evidence}"
)
+ decision_notes.append(f"{heading}\nResult:\n{web_evidence}")
start_position = (
max(
@@ -2695,16 +2725,18 @@ class ResearchSupervisor:
mcp_evidence = _mcp_evidence(
[source for source in rag_sources if source.get("kind") == "mcp"]
)
- note = (
- f"### {action['title']} ({action['action']})\n"
- f"Input: {argument}\nResult:\n{result[:12000]}\n\n"
- f"Knowledge base:\n{rag_result[:6000]}{mcp_evidence}"
- )
- notes.append(note)
- decision_notes.append(
- f"### {action['title']} ({action['action']})\n"
- f"Input: {argument}\nResult:\n{result[:12000]}"
+ heading = f"### {action['title']} ({action['action']})\nInput: {argument}"
+ web_part = f"Result:\n{result[:12000]}"
+ rag_part = f"Knowledge base:\n{rag_result[:6000]}{mcp_evidence}"
+ # Text-only replies such as "No matching chunks" stay behind the web results, cut first.
+ notes.append(
+ (heading, web_part, rag_part)
+ if rag_sources
+ else f"{heading}\n{web_part}\n\n{rag_part}"
+ if rag_result
+ else f"{heading}\n{web_part}"
)
+ decision_notes.append(f"{heading}\nResult:\n{result[:12000]}")
clean_result = strip_result_for_model(result, "web_search")
if step_failed:
step_error = _preferred_step_error(step_error, clean_result[:500])
diff --git a/studio/backend/tests/test_research_document_evidence.py b/studio/backend/tests/test_research_document_evidence.py
new file mode 100644
index 00000000000..3a857c0110c
--- /dev/null
+++ b/studio/backend/tests/test_research_document_evidence.py
@@ -0,0 +1,159 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from __future__ import annotations
+
+import asyncio
+import json
+from types import SimpleNamespace
+
+import pytest
+
+from core.inference.tools import RAG_SOURCES_SENTINEL
+from storage import research_runs_db as research_db
+from storage import studio_db
+
+STEPS = 12
+REPORT = "## Findings\n\nThe manual covers it [Document: manual.pdf, p. 1]."
+
+
+def research_home(tmp_path, monkeypatch):
+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path))
+ monkeypatch.setattr(studio_db, "_schema_ready", set())
+ studio_db.upsert_chat_thread(
+ {
+ "id": "thread-1",
+ "title": "Research",
+ "modelType": "base",
+ "modelId": "local-model",
+ "createdAt": 1,
+ }
+ )
+ studio_db.upsert_chat_message(
+ {
+ "id": "user-1",
+ "threadId": "thread-1",
+ "role": "user",
+ "content": [{"type": "text", "text": "how does the pump work?"}],
+ "createdAt": 2,
+ }
+ )
+ return tmp_path
+
+
+def _web_results(step: int) -> str:
+ return "\n\n---\n\n".join(
+ f"Title: Result {step}-{rank}\nURL: https://example.test/{step}/{rank}\n"
+ f"Snippet: web-{step}-{rank} " + "w" * 400
+ for rank in range(5)
+ )
+
+
+def _passage(index: int) -> str:
+ return "d" * 800 + f" manual-fact-{index} " + "d" * 1_200
+
+
+def _knowledge_base_results(step: int) -> str:
+ sources = [
+ {
+ "chunkId": f"chunk-{index}",
+ "documentId": "doc-1",
+ "filename": "manual.pdf",
+ "page": index + 1,
+ "text": _passage(index),
+ }
+ for index in range(step, step + 5)
+ ]
+ text = "\n\n".join(source["text"] for source in sources)
+ return text + RAG_SOURCES_SENTINEL + json.dumps(sources)
+
+
+def _synthesis_prompt(
+ monkeypatch,
+ knowledge_base,
+ context_length = None,
+ query = "pump",
+) -> str:
+ from core import research_runs as worker
+
+ supervisor = worker.ResearchSupervisor(SimpleNamespace(state = SimpleNamespace(server_port = 1)))
+ research_db.create_run(
+ run_id = "run-1",
+ owner_subject = "alice",
+ thread_id = "thread-1",
+ user_message_id = "user-1",
+ assistant_message_id = None,
+ config = {
+ "model": "local-model",
+ "inferenceRequest": {"model": "local-model"},
+ "ragScope": {"thread_id": "thread-1"},
+ "instructions": "",
+ "question": "how does the pump work?",
+ "budgets": {
+ "maxSteps": STEPS,
+ "maxSources": 100,
+ "modelTimeoutSeconds": 900,
+ "toolTimeoutSeconds": 10,
+ },
+ },
+ )
+ planned = research_db.set_plan(
+ "run-1",
+ {
+ "title": "Pump",
+ "steps": [
+ {"title": f"{query} {step}", "query": f"{query} {step}"} for step in range(STEPS)
+ ],
+ },
+ )
+ research_db.approve("run-1", planned["planRevision"], planned["planHash"])
+ searches = {"web_search": 0, "search_knowledge_base": 0}
+
+ def fake_execute_tool(name, arguments, **kwargs):
+ step = searches[name]
+ searches[name] += 1
+ return _web_results(step) if name == "web_search" else knowledge_base(step)
+
+ prompts = []
+
+ async def fake_stream_completion(run, messages, **kwargs):
+ if kwargs.get("phase") == "synthesis":
+ prompts.append(messages[1]["content"])
+ return REPORT, "", "stop", None
+ return "not json", "", "stop", None
+
+ monkeypatch.setattr(worker, "_loaded_context_length", lambda _inf = None: context_length)
+ monkeypatch.setattr(worker, "execute_tool", fake_execute_tool)
+ monkeypatch.setattr(supervisor, "_stream_completion", fake_stream_completion)
+ asyncio.run(supervisor._process(research_db.claim_next(supervisor.worker_id)))
+ assert research_db.get_run("run-1")["status"] == "completed"
+ return prompts[-1]
+
+
+def test_every_step_keeps_its_top_document_passage_in_the_report_prompt(research_home, monkeypatch):
+ prompt = _synthesis_prompt(monkeypatch, _knowledge_base_results)
+
+ assert all(f"manual-fact-{step}" in prompt for step in range(STEPS))
+ assert all(f"web-{step}-0" in prompt for step in range(STEPS))
+
+
+def test_web_results_keep_their_room_when_the_documents_match_nothing(research_home, monkeypatch):
+ prompt = _synthesis_prompt(
+ monkeypatch, lambda _step: "No matching chunks were found in the knowledge base."
+ )
+
+ assert all(f"web-{step}-{rank}" in prompt for step in range(STEPS) for rank in range(5))
+
+
+def test_small_context_keeps_web_results_when_the_documents_match_nothing(
+ research_home, monkeypatch
+):
+ prompt = _synthesis_prompt(
+ monkeypatch,
+ lambda _step: "No matching chunks were found in the knowledge base.",
+ context_length = 8_192,
+ query = "centrifugal pump cooling data sheet maintenance interval seal replacement guide",
+ )
+
+ assert all(f"web-{step}-0" in prompt for step in range(STEPS))