初始化
This commit is contained in:
1 parent
34474bd5fc
commit
b638b541d0
3008 files changed
+837699
No files matched your search
+19
@@ -0,0 +1,19 @@
|
||||
"""Deep Research runners — one per research mode.
|
||||
|
||||
Each runner maps a :class:`~deerflow.agents.deep_research.types.DeepResearchRequest`
|
||||
to a concrete research pipeline using the injected :class:`AdapterBundle`.
|
||||
Runners never touch the network, filesystem, or ``app.*`` directly — they call
|
||||
only the adapters.
|
||||
|
||||
The detailed and deep runners use the same adapter boundary as the basic
|
||||
runner, so they do not add a model/search runtime dependency.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from deerflow.agents.deep_research.runners.basic import BasicRunner
|
||||
from deerflow.agents.deep_research.runners.deep import DeepRunner
|
||||
from deerflow.agents.deep_research.runners.detailed import DetailedRunner
|
||||
from deerflow.agents.deep_research.runners.multi_agent import MultiAgentRunner
|
||||
|
||||
__all__ = ["BasicRunner", "DeepRunner", "DetailedRunner", "MultiAgentRunner"]
|
||||
+1362
File diff suppressed because it is too large.
Load diff
+462
@@ -0,0 +1,462 @@
|
||||
"""Recursive deep-research runner adapted from GPT Researcher's DeepResearchSkill.
|
||||
|
||||
The original skill expands search goals by breadth, extracts learnings from each
|
||||
branch, and recursively investigates follow-up questions with a smaller width.
|
||||
This module keeps those mechanics but routes all search/model work through the
|
||||
DeerFlow adapter bundle. A deterministic query budget is reserved before any
|
||||
branch runs, so recursive fan-out cannot exceed the persisted job configuration.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import json
|
||||
from dataclasses import dataclass
|
||||
from typing import TYPE_CHECKING, Any
|
||||
|
||||
from pydantic import BaseModel, Field
|
||||
|
||||
from deerflow.agents.deep_research.adapters.material import dedupe_materials
|
||||
from deerflow.agents.deep_research.cancellation import ResearchCancelled
|
||||
from deerflow.agents.deep_research.retrieval import (
|
||||
format_direction_lines,
|
||||
normalize_retrieval_directions,
|
||||
queries_from_retrieval_directions,
|
||||
)
|
||||
from deerflow.agents.deep_research.runners.basic import (
|
||||
_SYSTEM,
|
||||
BasicRunner,
|
||||
_format_context,
|
||||
ensure_reference_section,
|
||||
)
|
||||
from deerflow.agents.deep_research.runners.images import generate_report_images
|
||||
from deerflow.agents.deep_research.types import DeepResearchRequest, DeepResearchResult, ResearchMaterial
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from deerflow.agents.deep_research.types import AdapterBundle
|
||||
|
||||
|
||||
class ResearchBranch(BaseModel):
|
||||
query: str
|
||||
research_goal: str = ""
|
||||
|
||||
|
||||
class ResearchBranches(BaseModel):
|
||||
branches: list[ResearchBranch] = Field(default_factory=list)
|
||||
|
||||
|
||||
class ResearchLearnings(BaseModel):
|
||||
learnings: list[str] = Field(default_factory=list)
|
||||
follow_up_questions: list[str] = Field(default_factory=list)
|
||||
|
||||
|
||||
_BRANCH_PROMPT = """Research topic: {query}
|
||||
|
||||
Generate at most {breadth} independent search branches. Each branch must include
|
||||
a concrete search query and a one-sentence research goal. Return JSON only:
|
||||
{{"branches": [{{"query": "...", "research_goal": "..."}}]}}.
|
||||
"""
|
||||
|
||||
_DIRECTED_BRANCH_PROMPT = """Research topic: {query}
|
||||
|
||||
The user named these retrieval directions. Use them only as facets for splitting
|
||||
search terms — do not use the direction labels themselves as queries (they often
|
||||
return no results):
|
||||
{directions}
|
||||
|
||||
Generate at most {breadth} independent search branches covering those directions.
|
||||
Each branch must include a concrete, retrievable search query (entities, dates,
|
||||
places, synonyms) and a one-sentence research goal. Do not invent branches
|
||||
outside the listed directions. Return JSON only:
|
||||
{{"branches": [{{"query": "...", "research_goal": "..."}}]}}.
|
||||
"""
|
||||
|
||||
_LEARNING_PROMPT = """Research objective: {goal}
|
||||
|
||||
Extract concise, evidence-grounded learnings from the materials. Then propose
|
||||
follow-up questions that would reduce the most important uncertainty. Return
|
||||
JSON only: {{"learnings": ["..."], "follow_up_questions": ["..."]}}.
|
||||
|
||||
Materials:
|
||||
{context}
|
||||
"""
|
||||
|
||||
|
||||
def calculate_query_budget(breadth: int, depth: int) -> int:
|
||||
"""Return the maximum number of searches reachable by recursive expansion.
|
||||
|
||||
A depth level creates ``width`` branches per existing branch. Each next
|
||||
level halves the width (with a floor of one), mirroring GPT Researcher's
|
||||
``new_breadth=breadth // 2`` expansion while remaining bounded for
|
||||
DeerFlow's small default budgets.
|
||||
"""
|
||||
width = max(1, breadth)
|
||||
nodes = 1
|
||||
total = 0
|
||||
for _ in range(max(1, depth)):
|
||||
total += nodes * width
|
||||
nodes *= width
|
||||
width = max(1, width // 2)
|
||||
return total
|
||||
|
||||
|
||||
@dataclass
|
||||
class _Budget:
|
||||
remaining: int
|
||||
lock: asyncio.Lock
|
||||
|
||||
async def take(self) -> bool:
|
||||
async with self.lock:
|
||||
if self.remaining <= 0:
|
||||
return False
|
||||
self.remaining -= 1
|
||||
return True
|
||||
|
||||
|
||||
class DeepRunner(BasicRunner):
|
||||
"""Run bounded recursive research and synthesize a final cited report."""
|
||||
|
||||
async def run(
|
||||
self,
|
||||
request: DeepResearchRequest,
|
||||
adapters: AdapterBundle,
|
||||
cancellation=None,
|
||||
) -> DeepResearchResult:
|
||||
config = request.config
|
||||
events = adapters.events
|
||||
all_materials: list[ResearchMaterial] = []
|
||||
learnings: list[str] = []
|
||||
materials_lock = asyncio.Lock()
|
||||
learnings_lock = asyncio.Lock()
|
||||
budget = _Budget(calculate_query_budget(config.deep_breadth, config.deep_depth), asyncio.Lock())
|
||||
model_semaphore = asyncio.Semaphore(max(1, config.max_concurrency))
|
||||
|
||||
try:
|
||||
await events.emit(
|
||||
"phase_changed",
|
||||
phase="planning",
|
||||
payload={"from": "initializing", "to": "planning"},
|
||||
)
|
||||
self._raise_if_cancelled(cancellation)
|
||||
roots = await self._generate_branches(
|
||||
adapters.llm,
|
||||
request.query,
|
||||
config.deep_breadth,
|
||||
retrieval_directions=config.retrieval_directions,
|
||||
)
|
||||
if not roots:
|
||||
roots = [ResearchBranch(query=request.query, research_goal=request.query)]
|
||||
plan = {
|
||||
"branches": [branch.model_dump() for branch in roots],
|
||||
"deepBreadth": config.deep_breadth,
|
||||
"deepDepth": config.deep_depth,
|
||||
"queryBudget": budget.remaining,
|
||||
}
|
||||
await events.emit("plan_created", phase="planning", payload={"plan": plan, "subtopics": []})
|
||||
|
||||
await events.emit(
|
||||
"phase_changed",
|
||||
phase="deepening",
|
||||
payload={"from": "planning", "to": "deepening"},
|
||||
)
|
||||
await asyncio.gather(
|
||||
*[
|
||||
self._research_branch(
|
||||
branch=branch,
|
||||
depth_remaining=config.deep_depth,
|
||||
branch_width=config.deep_breadth,
|
||||
path=str(index + 1),
|
||||
request=request,
|
||||
adapters=adapters,
|
||||
cancellation=cancellation,
|
||||
model_semaphore=model_semaphore,
|
||||
budget=budget,
|
||||
all_materials=all_materials,
|
||||
materials_lock=materials_lock,
|
||||
learnings=learnings,
|
||||
learnings_lock=learnings_lock,
|
||||
)
|
||||
for index, branch in enumerate(roots)
|
||||
]
|
||||
)
|
||||
self._raise_if_cancelled(cancellation)
|
||||
|
||||
await events.emit(
|
||||
"phase_changed",
|
||||
phase="curating",
|
||||
payload={"from": "deepening", "to": "curating"},
|
||||
)
|
||||
deduped = dedupe_materials(all_materials)
|
||||
if not deduped:
|
||||
return await self._no_materials_result(request, adapters, plan)
|
||||
selected_ids = [material.id for material in deduped]
|
||||
await events.emit(
|
||||
"sources_curated",
|
||||
phase="curating",
|
||||
payload={"selectedIds": selected_ids, "removedIds": [], "reason": "deduped_recursive"},
|
||||
)
|
||||
|
||||
await events.emit(
|
||||
"phase_changed",
|
||||
phase="compressing",
|
||||
payload={"from": "curating", "to": "compressing"},
|
||||
)
|
||||
adapters.context.set_materials(deduped)
|
||||
context_list = await adapters.context.async_get_context(
|
||||
request.query,
|
||||
max_results=min(len(deduped), config.max_search_results_per_query * 2),
|
||||
)
|
||||
if not context_list:
|
||||
context_list = [
|
||||
material.to_context_dict()
|
||||
for material in deduped[: min(len(deduped), config.max_search_results_per_query * 2)]
|
||||
]
|
||||
await events.emit(
|
||||
"warning",
|
||||
phase="compressing",
|
||||
payload={
|
||||
"code": "context_fallback",
|
||||
"message": "材料压缩未返回上下文,已直接使用已收集素材撰写报告",
|
||||
"recoverable": True,
|
||||
"sourceCount": len(deduped),
|
||||
"diagnostic": {
|
||||
"stage": "compressing",
|
||||
"outcome": "empty_context",
|
||||
"sourceCount": len(deduped),
|
||||
},
|
||||
},
|
||||
)
|
||||
material_context = _format_context(context_list, deduped)
|
||||
learning_context = "\n".join(f"- {learning}" for learning in dict.fromkeys(learnings))
|
||||
context_text = f"## Recursive research learnings\n{learning_context}\n\n## Source materials\n{material_context}" if learning_context else material_context
|
||||
await events.emit(
|
||||
"context_compressed",
|
||||
phase="compressing",
|
||||
payload={"sourceCount": len(context_list), "learningCount": len(learnings)},
|
||||
)
|
||||
|
||||
await events.emit(
|
||||
"phase_changed",
|
||||
phase="writing",
|
||||
payload={"from": "compressing", "to": "writing"},
|
||||
)
|
||||
self._raise_if_cancelled(cancellation)
|
||||
report_md = await self._generate_report(
|
||||
adapters.llm,
|
||||
request,
|
||||
context_text,
|
||||
events,
|
||||
cancellation,
|
||||
source_count=len(deduped),
|
||||
)
|
||||
report_md, image_paths = await generate_report_images(request, adapters, report_md, cancellation)
|
||||
# Ensure before _write_artifacts so the artifact AND the returned
|
||||
# report_markdown (persisted by the executor) both carry it.
|
||||
report_md = ensure_reference_section(report_md, context_list, deduped)
|
||||
await self._write_artifacts(adapters, report_md, deduped, plan)
|
||||
await events.emit(
|
||||
"report_completed",
|
||||
phase="writing",
|
||||
payload={"reportVersion": 1, "sourceCount": len(deduped)},
|
||||
)
|
||||
await events.emit(
|
||||
"artifact_created",
|
||||
phase="exporting",
|
||||
payload={"format": "markdown", "name": "report.md"},
|
||||
)
|
||||
return DeepResearchResult(
|
||||
report_markdown=report_md,
|
||||
source_ids=selected_ids,
|
||||
artifact_paths={
|
||||
"report.md": "report.md",
|
||||
"sources.json": "sources.json",
|
||||
**image_paths,
|
||||
},
|
||||
usage=adapters.llm.usage_totals,
|
||||
plan=plan,
|
||||
)
|
||||
except ResearchCancelled:
|
||||
await events.emit(
|
||||
"warning",
|
||||
phase="deepening",
|
||||
payload={"code": "cancelled", "message": "Research job cancelled", "recoverable": False},
|
||||
)
|
||||
raise
|
||||
|
||||
async def _research_branch(
|
||||
self,
|
||||
*,
|
||||
branch: ResearchBranch,
|
||||
depth_remaining: int,
|
||||
branch_width: int,
|
||||
path: str,
|
||||
request: DeepResearchRequest,
|
||||
adapters: AdapterBundle,
|
||||
cancellation,
|
||||
model_semaphore: asyncio.Semaphore,
|
||||
budget: _Budget,
|
||||
all_materials: list[ResearchMaterial],
|
||||
materials_lock: asyncio.Lock,
|
||||
learnings: list[str],
|
||||
learnings_lock: asyncio.Lock,
|
||||
) -> None:
|
||||
self._raise_if_cancelled(cancellation)
|
||||
if not await budget.take():
|
||||
await adapters.events.emit(
|
||||
"warning",
|
||||
phase="deepening",
|
||||
payload={"code": "deep_budget_exhausted", "message": "Recursive query budget exhausted", "recoverable": True},
|
||||
)
|
||||
return
|
||||
await adapters.events.emit(
|
||||
"deep_branch_started",
|
||||
phase="deepening",
|
||||
payload={"path": path, "query": branch.query, "goal": branch.research_goal, "depthRemaining": depth_remaining},
|
||||
)
|
||||
try:
|
||||
materials = await self._search_one(
|
||||
adapters.materials,
|
||||
branch.query,
|
||||
request.config,
|
||||
request,
|
||||
cancellation,
|
||||
adapters.events,
|
||||
)
|
||||
except ResearchCancelled:
|
||||
raise
|
||||
except Exception as exc: # noqa: BLE001 - one branch must not abort all research
|
||||
await adapters.events.emit(
|
||||
"warning",
|
||||
phase="deepening",
|
||||
payload={"code": "deep_branch_search_failed", "message": str(exc), "recoverable": True},
|
||||
)
|
||||
materials = []
|
||||
async with materials_lock:
|
||||
all_materials.extend(materials)
|
||||
|
||||
branch_learnings: list[str] = []
|
||||
follow_ups: list[str] = []
|
||||
if materials:
|
||||
deduped_materials = dedupe_materials(materials)
|
||||
context = _format_context(
|
||||
[material.to_context_dict() for material in deduped_materials],
|
||||
deduped_materials,
|
||||
)
|
||||
async with model_semaphore:
|
||||
extraction = await self._extract_learnings(adapters.llm, branch.research_goal or branch.query, context)
|
||||
branch_learnings = extraction.learnings
|
||||
follow_ups = extraction.follow_up_questions
|
||||
async with learnings_lock:
|
||||
learnings.extend(branch_learnings)
|
||||
|
||||
await adapters.events.emit(
|
||||
"deep_branch_completed",
|
||||
phase="deepening",
|
||||
payload={
|
||||
"path": path,
|
||||
"query": branch.query,
|
||||
"resultCount": len(materials),
|
||||
"learningCount": len(branch_learnings),
|
||||
"nextQuestionCount": len(follow_ups),
|
||||
},
|
||||
)
|
||||
self._raise_if_cancelled(cancellation)
|
||||
if depth_remaining <= 1 or not follow_ups:
|
||||
return
|
||||
|
||||
next_width = max(1, branch_width // 2)
|
||||
await asyncio.gather(
|
||||
*[
|
||||
self._research_branch(
|
||||
branch=ResearchBranch(query=question, research_goal=question),
|
||||
depth_remaining=depth_remaining - 1,
|
||||
branch_width=next_width,
|
||||
path=f"{path}.{index + 1}",
|
||||
request=request,
|
||||
adapters=adapters,
|
||||
cancellation=cancellation,
|
||||
model_semaphore=model_semaphore,
|
||||
budget=budget,
|
||||
all_materials=all_materials,
|
||||
materials_lock=materials_lock,
|
||||
learnings=learnings,
|
||||
learnings_lock=learnings_lock,
|
||||
)
|
||||
for index, question in enumerate(follow_ups[:next_width])
|
||||
if question.strip()
|
||||
]
|
||||
)
|
||||
|
||||
async def _generate_branches(
|
||||
self,
|
||||
llm,
|
||||
query: str,
|
||||
breadth: int,
|
||||
retrieval_directions: list[str] | None = None,
|
||||
) -> list[ResearchBranch]:
|
||||
dirs = normalize_retrieval_directions(retrieval_directions)
|
||||
prompt = (
|
||||
_DIRECTED_BRANCH_PROMPT.format(
|
||||
query=query, breadth=breadth, directions=format_direction_lines(dirs)
|
||||
)
|
||||
if dirs
|
||||
else _BRANCH_PROMPT.format(query=query, breadth=breadth)
|
||||
)
|
||||
result = await llm.complete(
|
||||
model_role="strategic",
|
||||
messages=[
|
||||
{"role": "system", "content": _SYSTEM},
|
||||
{"role": "user", "content": prompt},
|
||||
],
|
||||
response_schema=ResearchBranches,
|
||||
operation="generate_deep_queries",
|
||||
)
|
||||
branches = result.structured.branches if result.structured else []
|
||||
seen: set[str] = set()
|
||||
output: list[ResearchBranch] = []
|
||||
for branch in branches:
|
||||
query_text = branch.query.strip()
|
||||
if not query_text or query_text in seen:
|
||||
continue
|
||||
seen.add(query_text)
|
||||
output.append(ResearchBranch(query=query_text, research_goal=branch.research_goal.strip()))
|
||||
if len(output) >= breadth:
|
||||
break
|
||||
if output:
|
||||
return output
|
||||
fallback = queries_from_retrieval_directions(query, dirs)
|
||||
return [ResearchBranch(query=item, research_goal=item) for item in fallback[:breadth]]
|
||||
|
||||
async def _extract_learnings(self, llm, goal: str, context: str) -> ResearchLearnings:
|
||||
result = await llm.complete(
|
||||
model_role="fast",
|
||||
messages=[
|
||||
{"role": "system", "content": _SYSTEM},
|
||||
{"role": "user", "content": _LEARNING_PROMPT.format(goal=goal, context=context)},
|
||||
],
|
||||
response_schema=ResearchLearnings,
|
||||
operation="extract_research_learnings",
|
||||
)
|
||||
return result.structured if result.structured else ResearchLearnings()
|
||||
|
||||
async def _write_artifacts(
|
||||
self,
|
||||
adapters: AdapterBundle,
|
||||
report_md: str,
|
||||
materials: list[ResearchMaterial],
|
||||
plan: dict[str, Any],
|
||||
) -> None:
|
||||
await adapters.artifacts.write_text("report.md", report_md)
|
||||
await adapters.artifacts.write_text("sources.json", json.dumps([material.to_context_dict() for material in materials], ensure_ascii=False, indent=2))
|
||||
await adapters.artifacts.write_text("research-plan.json", json.dumps(plan, ensure_ascii=False, indent=2))
|
||||
|
||||
async def _no_materials_result(self, request: DeepResearchRequest, adapters: AdapterBundle, plan: dict[str, Any]) -> DeepResearchResult:
|
||||
return await super()._no_materials_result(request, adapters, plan)
|
||||
|
||||
@staticmethod
|
||||
def _raise_if_cancelled(cancellation) -> None:
|
||||
if cancellation:
|
||||
cancellation.raise_if_cancelled()
|
||||
|
||||
|
||||
__all__ = ["DeepRunner", "ResearchBranch", "ResearchBranches", "ResearchLearnings", "calculate_query_budget"]
|
||||
+502
@@ -0,0 +1,502 @@
|
||||
"""Detailed-report runner adapted from GPT Researcher's subtopic workflow.
|
||||
|
||||
The upstream ``DetailedReport`` flow plans a set of subtopics, researches each
|
||||
one, writes independently usable sections, then assembles an introduction and
|
||||
conclusion. This adaptation deliberately retains that control flow while using
|
||||
only DeerFlow's injected adapters for models, materials, events, and artifacts.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import json
|
||||
import logging
|
||||
from typing import TYPE_CHECKING, Any
|
||||
|
||||
from pydantic import BaseModel, Field
|
||||
|
||||
from deerflow.agents.deep_research.adapters.material import dedupe_materials
|
||||
from deerflow.agents.deep_research.cancellation import ResearchCancelled
|
||||
from deerflow.agents.deep_research.runners.basic import (
|
||||
_SYSTEM,
|
||||
BasicRunner,
|
||||
_format_context,
|
||||
ensure_outline_preamble,
|
||||
ensure_reference_section,
|
||||
extract_outline_sections,
|
||||
)
|
||||
from deerflow.agents.deep_research.runners.images import generate_report_images
|
||||
from deerflow.agents.deep_research.types import DeepResearchRequest, DeepResearchResult, ResearchMaterial
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from deerflow.agents.deep_research.types import AdapterBundle
|
||||
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class DetailedSubtopics(BaseModel):
|
||||
"""The bounded section plan for a detailed report."""
|
||||
|
||||
subtopics: list[str] = Field(default_factory=list)
|
||||
|
||||
|
||||
_SUBTOPIC_PROMPT = """Research topic: {query}
|
||||
|
||||
Create at most {count} mutually exclusive report sections. Cover the most
|
||||
decision-useful dimensions of the topic and make each section title concise.
|
||||
Return JSON only: {{"subtopics": ["section one", "section two"]}}.
|
||||
"""
|
||||
|
||||
_SECTION_PROMPT = """Write the Markdown section titled "{topic}" for a report on
|
||||
"{query}". Use only the supplied evidence, distinguish facts from inference,
|
||||
and cite evidence with [N]. Output the section body only; do not repeat a #
|
||||
title.
|
||||
|
||||
Evidence:
|
||||
{context}
|
||||
"""
|
||||
|
||||
_INTRODUCTION_PROMPT = """Write a concise Markdown introduction for a detailed
|
||||
research report about "{query}". State scope and method without inventing facts.
|
||||
The report sections are: {sections}. Output prose only.
|
||||
"""
|
||||
|
||||
_CONCLUSION_PROMPT = """Write a concise Markdown conclusion for a detailed
|
||||
research report about "{query}". Synthesize only the supplied section findings;
|
||||
note important uncertainty where appropriate. Output prose only.
|
||||
|
||||
Section findings:
|
||||
{sections}
|
||||
"""
|
||||
|
||||
|
||||
def _confirmed_requirements(value: str | None) -> str:
|
||||
if not value:
|
||||
return ""
|
||||
return f"\n\nConfirmed user generation requirements:\n<user-report-requirements>\n{value}\n</user-report-requirements>"
|
||||
|
||||
|
||||
class DetailedRunner(BasicRunner):
|
||||
"""Plan, research, and write bounded subtopic sections in parallel."""
|
||||
|
||||
async def run(
|
||||
self,
|
||||
request: DeepResearchRequest,
|
||||
adapters: AdapterBundle,
|
||||
cancellation=None,
|
||||
) -> DeepResearchResult:
|
||||
config = request.config
|
||||
events = adapters.events
|
||||
|
||||
try:
|
||||
await events.emit(
|
||||
"phase_changed",
|
||||
phase="planning",
|
||||
payload={"from": "initializing", "to": "planning"},
|
||||
)
|
||||
self._raise_if_cancelled(cancellation)
|
||||
|
||||
subtopics = extract_outline_sections(
|
||||
config.custom_outline,
|
||||
config.max_subtopics,
|
||||
structure_mode=config.structure_mode,
|
||||
)
|
||||
if not subtopics:
|
||||
subtopics = await self._generate_subtopics(adapters.llm, request.query, config.max_subtopics, events)
|
||||
if not subtopics:
|
||||
subtopics = [request.query]
|
||||
plan = {"subtopics": subtopics, "queries": []}
|
||||
await events.emit(
|
||||
"plan_created",
|
||||
phase="planning",
|
||||
payload={"plan": plan, "subtopics": subtopics},
|
||||
)
|
||||
|
||||
await events.emit(
|
||||
"phase_changed",
|
||||
phase="collecting",
|
||||
payload={"from": "planning", "to": "collecting"},
|
||||
)
|
||||
semaphore = asyncio.Semaphore(max(1, config.max_concurrency))
|
||||
topic_results = await asyncio.gather(
|
||||
*[
|
||||
self._research_subtopic(
|
||||
topic,
|
||||
request,
|
||||
adapters,
|
||||
semaphore,
|
||||
cancellation,
|
||||
)
|
||||
for topic in subtopics
|
||||
],
|
||||
return_exceptions=True,
|
||||
)
|
||||
self._raise_if_cancelled(cancellation)
|
||||
|
||||
materials_by_topic: dict[str, list[ResearchMaterial]] = {topic: [] for topic in subtopics}
|
||||
all_materials: list[ResearchMaterial] = []
|
||||
for result in topic_results:
|
||||
if isinstance(result, ResearchCancelled):
|
||||
raise result
|
||||
if isinstance(result, Exception):
|
||||
await events.emit(
|
||||
"warning",
|
||||
phase="collecting",
|
||||
payload={"code": "subtopic_failed", "message": str(result), "recoverable": True},
|
||||
)
|
||||
continue
|
||||
topic, materials = result
|
||||
materials_by_topic[topic] = materials
|
||||
all_materials.extend(materials)
|
||||
|
||||
await events.emit(
|
||||
"phase_changed",
|
||||
phase="curating",
|
||||
payload={"from": "collecting", "to": "curating"},
|
||||
)
|
||||
self._raise_if_cancelled(cancellation)
|
||||
deduped = dedupe_materials(all_materials)
|
||||
if not deduped:
|
||||
return await self._no_materials_result(request, adapters, plan)
|
||||
|
||||
selected_ids = [material.id for material in deduped]
|
||||
await events.emit(
|
||||
"sources_curated",
|
||||
phase="curating",
|
||||
payload={"selectedIds": selected_ids, "removedIds": [], "reason": "deduped"},
|
||||
)
|
||||
|
||||
await events.emit(
|
||||
"phase_changed",
|
||||
phase="compressing",
|
||||
payload={"from": "curating", "to": "compressing"},
|
||||
)
|
||||
adapters.context.set_materials(deduped)
|
||||
global_context = await adapters.context.async_get_context(
|
||||
request.query,
|
||||
max_results=min(len(deduped), config.max_search_results_per_query * 2),
|
||||
)
|
||||
if not global_context:
|
||||
global_context = [
|
||||
material.to_context_dict()
|
||||
for material in deduped[: min(len(deduped), config.max_search_results_per_query * 2)]
|
||||
]
|
||||
await events.emit(
|
||||
"warning",
|
||||
phase="compressing",
|
||||
payload={
|
||||
"code": "context_fallback",
|
||||
"message": "材料压缩未返回上下文,已直接使用已收集素材撰写报告",
|
||||
"recoverable": True,
|
||||
"sourceCount": len(deduped),
|
||||
"diagnostic": {
|
||||
"stage": "compressing",
|
||||
"outcome": "empty_context",
|
||||
"sourceCount": len(deduped),
|
||||
},
|
||||
},
|
||||
)
|
||||
await events.emit(
|
||||
"context_compressed",
|
||||
phase="compressing",
|
||||
payload={"sourceCount": len(global_context)},
|
||||
)
|
||||
|
||||
await events.emit(
|
||||
"phase_changed",
|
||||
phase="writing",
|
||||
payload={"from": "compressing", "to": "writing"},
|
||||
)
|
||||
self._raise_if_cancelled(cancellation)
|
||||
if config.structure_mode == "fixed":
|
||||
introduction = ""
|
||||
writing_semaphore = asyncio.Semaphore(max(1, config.max_concurrency))
|
||||
section_results = await asyncio.gather(
|
||||
*[
|
||||
self._write_section(
|
||||
topic,
|
||||
materials_by_topic.get(topic) or deduped,
|
||||
request,
|
||||
adapters,
|
||||
writing_semaphore,
|
||||
cancellation,
|
||||
index,
|
||||
)
|
||||
for index, topic in enumerate(subtopics)
|
||||
]
|
||||
)
|
||||
self._raise_if_cancelled(cancellation)
|
||||
conclusion = ""
|
||||
else:
|
||||
introduction = await self._write_introduction(adapters.llm, request, adapters.events, subtopics)
|
||||
writing_semaphore = asyncio.Semaphore(max(1, config.max_concurrency))
|
||||
section_results = await asyncio.gather(
|
||||
*[
|
||||
self._write_section(
|
||||
topic,
|
||||
materials_by_topic.get(topic) or deduped,
|
||||
request,
|
||||
adapters,
|
||||
writing_semaphore,
|
||||
cancellation,
|
||||
index,
|
||||
)
|
||||
for index, topic in enumerate(subtopics)
|
||||
]
|
||||
)
|
||||
self._raise_if_cancelled(cancellation)
|
||||
conclusion = await self._write_conclusion(adapters.llm, request, adapters.events, section_results)
|
||||
|
||||
report_md = self._assemble_report(
|
||||
request.query,
|
||||
introduction,
|
||||
subtopics,
|
||||
section_results,
|
||||
conclusion,
|
||||
outline=request.config.custom_outline,
|
||||
structure_mode=request.config.structure_mode,
|
||||
)
|
||||
report_md, image_paths = await generate_report_images(request, adapters, report_md, cancellation)
|
||||
# Sections cite with per-topic local numbering that cannot be
|
||||
# mapped to the global list, so list every source instead of
|
||||
# filtering by [N]. Ensured here so the artifact AND the returned
|
||||
# report_markdown (persisted by the executor) both carry it.
|
||||
report_md = ensure_reference_section(report_md, global_context, deduped, filter_by_citations=False)
|
||||
await self._write_artifacts(adapters, report_md, deduped, plan)
|
||||
await events.emit(
|
||||
"report_completed",
|
||||
phase="writing",
|
||||
payload={"reportVersion": 1, "sourceCount": len(deduped)},
|
||||
)
|
||||
await events.emit(
|
||||
"artifact_created",
|
||||
phase="exporting",
|
||||
payload={"format": "markdown", "name": "report.md"},
|
||||
)
|
||||
return DeepResearchResult(
|
||||
report_markdown=report_md,
|
||||
source_ids=selected_ids,
|
||||
artifact_paths={
|
||||
"report.md": "report.md",
|
||||
"sources.json": "sources.json",
|
||||
**image_paths,
|
||||
},
|
||||
usage=adapters.llm.usage_totals,
|
||||
plan=plan,
|
||||
)
|
||||
except ResearchCancelled:
|
||||
await events.emit(
|
||||
"warning",
|
||||
phase="writing",
|
||||
payload={"code": "cancelled", "message": "Research job cancelled", "recoverable": False},
|
||||
)
|
||||
raise
|
||||
|
||||
async def _generate_subtopics(self, llm, query: str, max_subtopics: int, events) -> list[str]:
|
||||
try:
|
||||
result = await llm.complete(
|
||||
model_role="strategic",
|
||||
messages=[
|
||||
{"role": "system", "content": _SYSTEM},
|
||||
{"role": "user", "content": _SUBTOPIC_PROMPT.format(query=query, count=max_subtopics)},
|
||||
],
|
||||
response_schema=DetailedSubtopics,
|
||||
operation="generate_detailed_subtopics",
|
||||
)
|
||||
except ResearchCancelled:
|
||||
raise
|
||||
except Exception:
|
||||
logger.warning("detailed runner: subtopic planning failed; using original topic", exc_info=True)
|
||||
await events.emit(
|
||||
"warning",
|
||||
phase="planning",
|
||||
payload={
|
||||
"code": "subtopic_planning_fallback",
|
||||
"message": "研究范围规划超时或失败,已直接使用研究课题继续检索。",
|
||||
"recoverable": True,
|
||||
},
|
||||
)
|
||||
return []
|
||||
raw = result.structured.subtopics if result.structured else []
|
||||
seen: set[str] = set()
|
||||
subtopics: list[str] = []
|
||||
for item in raw:
|
||||
title = item.strip()
|
||||
if not title or title in seen:
|
||||
continue
|
||||
seen.add(title)
|
||||
subtopics.append(title)
|
||||
if len(subtopics) >= max_subtopics:
|
||||
break
|
||||
return subtopics
|
||||
|
||||
async def _research_subtopic(
|
||||
self,
|
||||
topic: str,
|
||||
request: DeepResearchRequest,
|
||||
adapters: AdapterBundle,
|
||||
semaphore: asyncio.Semaphore,
|
||||
cancellation,
|
||||
) -> tuple[str, list[ResearchMaterial]]:
|
||||
self._raise_if_cancelled(cancellation)
|
||||
async with semaphore:
|
||||
queries = await self._generate_queries(
|
||||
adapters.llm,
|
||||
topic,
|
||||
request.config.max_iterations,
|
||||
cancellation,
|
||||
events=adapters.events,
|
||||
phase="collecting",
|
||||
retrieval_directions=request.config.retrieval_directions,
|
||||
)
|
||||
ordered_queries = list(dict.fromkeys([*queries, topic]))[: request.config.max_iterations + 1]
|
||||
# The generated terms are useful user-facing progress, not internal
|
||||
# reasoning. Persist them before dispatching the parallel searches so
|
||||
# an SSE reconnect can faithfully replay the fan-out.
|
||||
await adapters.events.emit(
|
||||
"queries_planned",
|
||||
phase="collecting",
|
||||
payload={"parentTopic": topic, "queries": ordered_queries},
|
||||
)
|
||||
materials: list[ResearchMaterial] = []
|
||||
for query in ordered_queries:
|
||||
try:
|
||||
materials.extend(
|
||||
await self._search_one(
|
||||
adapters.materials,
|
||||
query,
|
||||
request.config,
|
||||
request,
|
||||
cancellation,
|
||||
adapters.events,
|
||||
)
|
||||
)
|
||||
except ResearchCancelled:
|
||||
raise
|
||||
except Exception as exc: # noqa: BLE001 - one failed term must not abort the topic
|
||||
logger.warning("detailed runner: subtopic search failed: %s", exc)
|
||||
await adapters.events.emit(
|
||||
"warning",
|
||||
phase="collecting",
|
||||
payload={"code": "search_failed", "message": str(exc), "recoverable": True},
|
||||
)
|
||||
return topic, materials
|
||||
|
||||
async def _write_introduction(self, llm, request: DeepResearchRequest, events, subtopics: list[str]) -> str:
|
||||
from deerflow.agents.deep_research.runners.report_stream import ReportChunkEmitter
|
||||
|
||||
emitter = ReportChunkEmitter(events, target="introduction")
|
||||
result = await llm.stream_complete(
|
||||
model_role="smart",
|
||||
messages=[
|
||||
{"role": "system", "content": _SYSTEM},
|
||||
{
|
||||
"role": "user",
|
||||
"content": _INTRODUCTION_PROMPT.format(query=request.query, sections=", ".join(subtopics))
|
||||
+ _confirmed_requirements(request.config.report_instruction),
|
||||
},
|
||||
],
|
||||
operation="write_detailed_introduction",
|
||||
on_delta=emitter.add,
|
||||
on_reasoning=emitter.add_thinking,
|
||||
)
|
||||
await emitter.flush()
|
||||
return result.text
|
||||
|
||||
async def _write_section(
|
||||
self,
|
||||
topic: str,
|
||||
materials: list[ResearchMaterial],
|
||||
request: DeepResearchRequest,
|
||||
adapters: AdapterBundle,
|
||||
semaphore: asyncio.Semaphore,
|
||||
cancellation,
|
||||
index: int,
|
||||
) -> str:
|
||||
from deerflow.agents.deep_research.runners.report_stream import ReportChunkEmitter
|
||||
|
||||
async with semaphore:
|
||||
self._raise_if_cancelled(cancellation)
|
||||
deduped_materials = dedupe_materials(materials)
|
||||
context = _format_context(
|
||||
[material.to_context_dict() for material in deduped_materials],
|
||||
deduped_materials,
|
||||
)
|
||||
emitter = ReportChunkEmitter(adapters.events, target=f"section:{index}")
|
||||
result = await adapters.llm.stream_complete(
|
||||
model_role="smart",
|
||||
messages=[
|
||||
{"role": "system", "content": _SYSTEM},
|
||||
{
|
||||
"role": "user",
|
||||
"content": _SECTION_PROMPT.format(query=request.query, topic=topic, context=context)
|
||||
+ _confirmed_requirements(request.config.report_instruction),
|
||||
},
|
||||
],
|
||||
operation="write_detailed_section",
|
||||
on_delta=emitter.add,
|
||||
on_reasoning=emitter.add_thinking,
|
||||
)
|
||||
await emitter.flush()
|
||||
return result.text
|
||||
|
||||
async def _write_conclusion(self, llm, request: DeepResearchRequest, events, sections: list[str]) -> str:
|
||||
from deerflow.agents.deep_research.runners.report_stream import ReportChunkEmitter
|
||||
|
||||
emitter = ReportChunkEmitter(events, target="conclusion")
|
||||
result = await llm.stream_complete(
|
||||
model_role="smart",
|
||||
messages=[
|
||||
{"role": "system", "content": _SYSTEM},
|
||||
{
|
||||
"role": "user",
|
||||
"content": _CONCLUSION_PROMPT.format(query=request.query, sections="\n\n".join(sections))
|
||||
+ _confirmed_requirements(request.config.report_instruction),
|
||||
},
|
||||
],
|
||||
operation="write_detailed_conclusion",
|
||||
on_delta=emitter.add,
|
||||
on_reasoning=emitter.add_thinking,
|
||||
)
|
||||
await emitter.flush()
|
||||
return result.text
|
||||
async def _write_artifacts(
|
||||
self,
|
||||
adapters: AdapterBundle,
|
||||
report_md: str,
|
||||
materials: list[ResearchMaterial],
|
||||
plan: dict[str, Any],
|
||||
) -> None:
|
||||
await adapters.artifacts.write_text("report.md", report_md)
|
||||
await adapters.artifacts.write_text("sources.json", json.dumps([material.to_context_dict() for material in materials], ensure_ascii=False, indent=2))
|
||||
await adapters.artifacts.write_text("research-plan.json", json.dumps(plan, ensure_ascii=False, indent=2))
|
||||
|
||||
async def _no_materials_result(self, request: DeepResearchRequest, adapters: AdapterBundle, plan: dict[str, Any]) -> DeepResearchResult:
|
||||
return await super()._no_materials_result(request, adapters, plan)
|
||||
|
||||
@staticmethod
|
||||
def _assemble_report(
|
||||
query: str,
|
||||
introduction: str,
|
||||
subtopics: list[str],
|
||||
sections: list[str],
|
||||
conclusion: str,
|
||||
outline: str | None = None,
|
||||
structure_mode: str = "adaptive",
|
||||
) -> str:
|
||||
section_md = "\n\n".join(f"## {topic}\n\n{body}" for topic, body in zip(subtopics, sections, strict=True))
|
||||
if structure_mode == "fixed":
|
||||
report = section_md + "\n"
|
||||
else:
|
||||
toc = "\n".join(f"- {topic}" for topic in subtopics)
|
||||
report = f"# {query}\n\n## 摘要\n\n{introduction}\n\n## 目录\n\n{toc}\n\n{section_md}\n\n## 结论\n\n{conclusion}\n"
|
||||
return ensure_outline_preamble(report, outline, query)
|
||||
|
||||
@staticmethod
|
||||
def _raise_if_cancelled(cancellation) -> None:
|
||||
if cancellation:
|
||||
cancellation.raise_if_cancelled()
|
||||
|
||||
|
||||
__all__ = ["DetailedRunner", "DetailedSubtopics"]
|
||||
+180
@@ -0,0 +1,180 @@
|
||||
"""Shared optional report-illustration step for every research runner.
|
||||
|
||||
This module is intentionally independent of any particular runner. A basic,
|
||||
detailed, recursive or multi-agent report receives the same bounded, best-effort
|
||||
image behavior after its Markdown draft is complete and before ``report.md`` is
|
||||
written. Image failures emit warnings and never discard an otherwise valid
|
||||
research report.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
from deerflow.agents.deep_research.adapters.image import ImageGenerationError
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from deerflow.agents.deep_research.types import AdapterBundle, DeepResearchRequest
|
||||
|
||||
|
||||
_HEADING_RE = re.compile(r"^##\s+(.+?)\s*$", re.MULTILINE)
|
||||
_EXTENSIONS = {
|
||||
"image/png": "png",
|
||||
"image/jpeg": "jpg",
|
||||
"image/webp": "webp",
|
||||
}
|
||||
|
||||
|
||||
async def generate_report_images(
|
||||
request: DeepResearchRequest,
|
||||
adapters: AdapterBundle,
|
||||
report_markdown: str,
|
||||
cancellation=None,
|
||||
) -> tuple[str, dict[str, str]]:
|
||||
"""Generate bounded section illustrations and inject protected references.
|
||||
|
||||
The generated Markdown uses a private ``deep-research://`` URI. The React
|
||||
report renderer maps it to an authenticated session-artifact endpoint, so
|
||||
image paths never expose the hidden runtime-thread id or an external model
|
||||
provider URL.
|
||||
"""
|
||||
if not request.config.generate_images:
|
||||
return report_markdown, {}
|
||||
if adapters.images is None:
|
||||
await adapters.events.emit(
|
||||
"warning",
|
||||
phase="illustrating",
|
||||
payload={
|
||||
"code": "image_provider_unavailable",
|
||||
"message": "当前部署未配置图片生成服务,已跳过报告配图",
|
||||
"recoverable": True,
|
||||
},
|
||||
)
|
||||
return report_markdown, {}
|
||||
|
||||
sections = _report_sections(report_markdown, request.query, request.config.max_generated_images)
|
||||
if not sections:
|
||||
return report_markdown, {}
|
||||
|
||||
await adapters.events.emit(
|
||||
"phase_changed",
|
||||
phase="illustrating",
|
||||
payload={"from": "writing", "to": "illustrating"},
|
||||
)
|
||||
image_paths: dict[str, str] = {}
|
||||
amended_report = report_markdown
|
||||
total = len(sections)
|
||||
|
||||
for position, section in enumerate(sections, 1):
|
||||
if cancellation is not None:
|
||||
cancellation.raise_if_cancelled()
|
||||
prompt = _image_prompt(request.query, section)
|
||||
await adapters.events.emit(
|
||||
"image_generation_started",
|
||||
phase="illustrating",
|
||||
payload={"section": section, "position": position, "total": total},
|
||||
)
|
||||
try:
|
||||
generated = await adapters.images.generate(
|
||||
prompt,
|
||||
section_id=section,
|
||||
user_id=request.user_id,
|
||||
)
|
||||
if not generated:
|
||||
raise ImageGenerationError("图片生成服务未返回图片")
|
||||
data = generated.get("data")
|
||||
if not isinstance(data, bytes) or not data:
|
||||
raise ImageGenerationError("图片生成服务未返回可保存的图片数据")
|
||||
mime_type = str(generated.get("mime_type") or "image/png").lower()
|
||||
extension = _EXTENSIONS.get(mime_type, "png")
|
||||
name = f"research-image-{position:02d}.{extension}"
|
||||
await adapters.artifacts.write_bytes(name, data)
|
||||
alt = _clean_alt(str(generated.get("alt") or f"{section}配图"))
|
||||
amended_report = _insert_image(amended_report, section, alt, name)
|
||||
image_paths[name] = name
|
||||
await adapters.events.emit(
|
||||
"image_generated",
|
||||
phase="illustrating",
|
||||
payload={
|
||||
"section": section,
|
||||
"position": position,
|
||||
"total": total,
|
||||
"name": name,
|
||||
"alt": alt,
|
||||
},
|
||||
)
|
||||
except ImageGenerationError as exc:
|
||||
await adapters.events.emit(
|
||||
"warning",
|
||||
phase="illustrating",
|
||||
payload={
|
||||
"code": "image_generation_failed",
|
||||
"message": str(exc),
|
||||
"recoverable": True,
|
||||
"section": section,
|
||||
"position": position,
|
||||
"total": total,
|
||||
},
|
||||
)
|
||||
except Exception: # noqa: BLE001
|
||||
# Third-party image APIs and artifact storage must never turn a
|
||||
# completed text report into a failed job. Keep internal details
|
||||
# out of the browser event stream.
|
||||
await adapters.events.emit(
|
||||
"warning",
|
||||
phase="illustrating",
|
||||
payload={
|
||||
"code": "image_generation_failed",
|
||||
"message": "报告配图生成失败,已继续保留文字报告",
|
||||
"recoverable": True,
|
||||
"section": section,
|
||||
"position": position,
|
||||
"total": total,
|
||||
},
|
||||
)
|
||||
|
||||
await adapters.events.emit(
|
||||
"phase_changed",
|
||||
phase="exporting",
|
||||
payload={"from": "illustrating", "to": "exporting"},
|
||||
)
|
||||
return amended_report, image_paths
|
||||
|
||||
|
||||
def _report_sections(report_markdown: str, query: str, maximum: int) -> list[str]:
|
||||
seen: set[str] = set()
|
||||
sections: list[str] = []
|
||||
for match in _HEADING_RE.finditer(report_markdown):
|
||||
section = _clean_heading(match.group(1))
|
||||
if section and section not in seen:
|
||||
seen.add(section)
|
||||
sections.append(section)
|
||||
if len(sections) >= maximum:
|
||||
return sections
|
||||
return sections or [_clean_heading(query) or "研究主题"]
|
||||
|
||||
|
||||
def _image_prompt(query: str, section: str) -> str:
|
||||
return (
|
||||
f"为一份中文专业研究报告生成一张信息性配图。研究主题:{_clean_heading(query)}。对应章节:{section}。画面应当客观、简洁、适合商务报告;使用抽象示意、数据视觉化或场景插画表达主题。不要在图片中放置可读文字、品牌标志、水印或人物肖像。"
|
||||
)
|
||||
|
||||
|
||||
def _insert_image(report: str, section: str, alt: str, name: str) -> str:
|
||||
marker = f"## {section}"
|
||||
image = f"\n\n\n"
|
||||
if marker in report:
|
||||
return report.replace(marker, f"{marker}{image}", 1)
|
||||
return f"{report.rstrip()}{image}"
|
||||
|
||||
|
||||
def _clean_heading(value: str) -> str:
|
||||
return " ".join(value.replace("\r", " ").replace("\n", " ").split())[:160]
|
||||
|
||||
|
||||
def _clean_alt(value: str) -> str:
|
||||
return _clean_heading(value).replace("[", "").replace("]", "") or "研究报告配图"
|
||||
|
||||
|
||||
__all__ = ["generate_report_images"]
|
||||
+449
@@ -0,0 +1,449 @@
|
||||
"""LangGraph 1.x multi-agent research runner with durable plan review.
|
||||
|
||||
The workflow adapts GPT Researcher's editor/researcher/writer/reviewer shape:
|
||||
an editor plans sections, researchers collect evidence, a writer drafts the
|
||||
report, and a reviewer can request a bounded revision loop. Human plan review
|
||||
is durable at the runner/executor boundary: a first execution raises
|
||||
``ResearchAwaitingInput`` after persisting its plan; a resumed job rebuilds the
|
||||
same graph from the persisted plan and action payload.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import json
|
||||
import uuid
|
||||
from typing import TYPE_CHECKING, Any, TypedDict
|
||||
|
||||
from langgraph.graph import END, START, StateGraph
|
||||
from pydantic import BaseModel, Field
|
||||
|
||||
from deerflow.agents.deep_research.adapters.material import dedupe_materials
|
||||
from deerflow.agents.deep_research.cancellation import ResearchAwaitingInput, ResearchCancelled
|
||||
from deerflow.agents.deep_research.runners.basic import (
|
||||
_SYSTEM,
|
||||
BasicRunner,
|
||||
_format_context,
|
||||
ensure_reference_section,
|
||||
extract_outline_sections,
|
||||
)
|
||||
from deerflow.agents.deep_research.runners.images import generate_report_images
|
||||
from deerflow.agents.deep_research.types import DeepResearchRequest, DeepResearchResult, ResearchMaterial
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from deerflow.agents.deep_research.types import AdapterBundle
|
||||
|
||||
|
||||
class MultiAgentPlan(BaseModel):
|
||||
sections: list[str] = Field(default_factory=list)
|
||||
|
||||
|
||||
class ReviewVerdict(BaseModel):
|
||||
approved: bool = True
|
||||
revision_notes: str = ""
|
||||
|
||||
|
||||
class _MultiAgentState(TypedDict, total=False):
|
||||
plan: dict[str, Any]
|
||||
materials: list[ResearchMaterial]
|
||||
report: str
|
||||
review: dict[str, Any]
|
||||
revision_count: int
|
||||
context_list: list[dict[str, Any]]
|
||||
|
||||
|
||||
_PLAN_PROMPT = """Research topic: {query}
|
||||
|
||||
Act as the research editor. Produce at most {count} focused sections for a
|
||||
multi-agent report. Each section must describe a different decision-relevant
|
||||
dimension. Return JSON only: {{"sections": ["...", "..."]}}.
|
||||
"""
|
||||
|
||||
_REVIEW_PROMPT = """Review this research report for unsupported claims, missing
|
||||
citations, and material contradictions. Approve it when it is publishable;
|
||||
otherwise provide concise revision notes. Return JSON only:
|
||||
{{"approved": true, "revision_notes": ""}}.
|
||||
|
||||
Report:
|
||||
{report}
|
||||
"""
|
||||
|
||||
_REVISE_PROMPT = """Revise the research report using the reviewer notes. Retain
|
||||
valid citations, do not invent facts or sources, and return the full Markdown
|
||||
report only.
|
||||
|
||||
Reviewer notes:
|
||||
{notes}
|
||||
|
||||
Report:
|
||||
{report}
|
||||
"""
|
||||
|
||||
|
||||
class MultiAgentRunner(BasicRunner):
|
||||
"""Run a LangGraph editor/researcher/writer/reviewer workflow."""
|
||||
|
||||
async def run(
|
||||
self,
|
||||
request: DeepResearchRequest,
|
||||
adapters: AdapterBundle,
|
||||
cancellation=None,
|
||||
) -> DeepResearchResult:
|
||||
await adapters.events.emit(
|
||||
"phase_changed",
|
||||
phase="planning",
|
||||
payload={"from": "initializing", "to": "planning"},
|
||||
)
|
||||
self._raise_if_cancelled(cancellation)
|
||||
|
||||
plan = await self._resolve_plan(request, adapters, cancellation)
|
||||
if not request.interrupted_plan:
|
||||
interrupt_id = f"plan-review-{uuid.uuid4().hex[:12]}"
|
||||
await adapters.events.emit(
|
||||
"plan_created",
|
||||
phase="planning",
|
||||
payload={"plan": plan, "subtopics": plan["sections"]},
|
||||
)
|
||||
await adapters.events.emit(
|
||||
"awaiting_input",
|
||||
phase="planning",
|
||||
payload={
|
||||
"interruptId": interrupt_id,
|
||||
"kind": "plan_review",
|
||||
"plan": plan,
|
||||
"allowedActions": ["approve", "revise", "cancel"],
|
||||
},
|
||||
)
|
||||
raise ResearchAwaitingInput(interrupt_id, plan)
|
||||
|
||||
graph = self._build_graph(request, adapters, cancellation)
|
||||
initial_state: _MultiAgentState = {"plan": plan, "revision_count": 0}
|
||||
state = await graph.ainvoke(initial_state)
|
||||
materials = dedupe_materials(state.get("materials") or [])
|
||||
report_md = str(state.get("report") or "")
|
||||
if not materials or not report_md:
|
||||
return await self._no_materials_result(request, adapters, plan)
|
||||
|
||||
report_md, image_paths = await generate_report_images(request, adapters, report_md, cancellation)
|
||||
report_md = ensure_reference_section(report_md, state.get("context_list") or [], materials)
|
||||
await adapters.artifacts.write_text("report.md", report_md)
|
||||
await adapters.artifacts.write_text(
|
||||
"sources.json",
|
||||
json.dumps([material.to_context_dict() for material in materials], ensure_ascii=False, indent=2),
|
||||
)
|
||||
await adapters.artifacts.write_text("research-plan.json", json.dumps(plan, ensure_ascii=False, indent=2))
|
||||
await adapters.events.emit(
|
||||
"report_completed",
|
||||
phase="writing",
|
||||
payload={"reportVersion": 1, "sourceCount": len(materials)},
|
||||
)
|
||||
await adapters.events.emit(
|
||||
"artifact_created",
|
||||
phase="exporting",
|
||||
payload={"format": "markdown", "name": "report.md"},
|
||||
)
|
||||
return DeepResearchResult(
|
||||
report_markdown=report_md,
|
||||
source_ids=[material.id for material in materials],
|
||||
artifact_paths={
|
||||
"report.md": "report.md",
|
||||
"sources.json": "sources.json",
|
||||
**image_paths,
|
||||
},
|
||||
usage=adapters.llm.usage_totals,
|
||||
plan=plan,
|
||||
)
|
||||
|
||||
async def _resolve_plan(self, request: DeepResearchRequest, adapters: AdapterBundle, cancellation) -> dict[str, Any]:
|
||||
if request.interrupted_plan:
|
||||
plan = dict(request.interrupted_plan)
|
||||
action = str(request.resume_payload.get("action") or "approve")
|
||||
if action == "cancel":
|
||||
raise ResearchCancelled("plan review cancelled")
|
||||
if action == "revise":
|
||||
feedback = str((request.resume_payload.get("payload") or {}).get("feedback") or "")
|
||||
plan = await self._revise_plan(adapters.llm, request.query, plan, feedback)
|
||||
await adapters.events.emit(
|
||||
"plan_created",
|
||||
phase="planning",
|
||||
payload={"plan": plan, "subtopics": plan.get("sections", []), "resumed": True},
|
||||
)
|
||||
return plan
|
||||
|
||||
outline_sections = extract_outline_sections(
|
||||
request.config.custom_outline,
|
||||
request.config.max_subtopics,
|
||||
structure_mode=request.config.structure_mode,
|
||||
)
|
||||
if outline_sections:
|
||||
return {"sections": outline_sections}
|
||||
|
||||
try:
|
||||
result = await adapters.llm.complete(
|
||||
model_role="strategic",
|
||||
messages=[
|
||||
{"role": "system", "content": _SYSTEM},
|
||||
{
|
||||
"role": "user",
|
||||
"content": _PLAN_PROMPT.format(query=request.query, count=request.config.max_subtopics),
|
||||
},
|
||||
],
|
||||
response_schema=MultiAgentPlan,
|
||||
operation="generate_multi_agent_plan",
|
||||
)
|
||||
except ResearchCancelled:
|
||||
raise
|
||||
except Exception:
|
||||
await adapters.events.emit(
|
||||
"warning",
|
||||
phase="planning",
|
||||
payload={
|
||||
"code": "multi_agent_plan_fallback",
|
||||
"message": "研究计划生成超时或失败,已使用原始课题作为研究范围。",
|
||||
"recoverable": True,
|
||||
},
|
||||
)
|
||||
return {"sections": [request.query]}
|
||||
sections = result.structured.sections if result.structured else []
|
||||
normalised = self._normalise_sections(sections, request.config.max_subtopics)
|
||||
return {"sections": normalised or [request.query]}
|
||||
|
||||
async def _revise_plan(self, llm, query: str, plan: dict[str, Any], feedback: str) -> dict[str, Any]:
|
||||
prompt = f'Research topic: {query}\nExisting plan: {json.dumps(plan, ensure_ascii=False)}\nHuman feedback: {feedback}\nReturn JSON only: {{"sections": ["..."]}}.'
|
||||
result = await llm.complete(
|
||||
model_role="strategic",
|
||||
messages=[{"role": "system", "content": _SYSTEM}, {"role": "user", "content": prompt}],
|
||||
response_schema=MultiAgentPlan,
|
||||
operation="revise_multi_agent_plan",
|
||||
)
|
||||
sections = result.structured.sections if result.structured else []
|
||||
normalised = self._normalise_sections(sections, len(plan.get("sections") or []) or 1)
|
||||
return {"sections": normalised or list(plan.get("sections") or [query])}
|
||||
|
||||
def _build_graph(self, request: DeepResearchRequest, adapters: AdapterBundle, cancellation):
|
||||
model_semaphore = asyncio.Semaphore(max(1, request.config.max_concurrency))
|
||||
|
||||
async def research_node(state: _MultiAgentState) -> dict[str, Any]:
|
||||
await adapters.events.emit(
|
||||
"phase_changed",
|
||||
phase="collecting",
|
||||
payload={"from": "planning", "to": "collecting"},
|
||||
)
|
||||
sections = list(state["plan"].get("sections") or [])
|
||||
results = await asyncio.gather(
|
||||
*[self._research_section(section, request, adapters, cancellation, model_semaphore) for section in sections],
|
||||
return_exceptions=True,
|
||||
)
|
||||
materials: list[ResearchMaterial] = []
|
||||
for result in results:
|
||||
if isinstance(result, ResearchCancelled):
|
||||
raise result
|
||||
if isinstance(result, Exception):
|
||||
await adapters.events.emit(
|
||||
"warning",
|
||||
phase="collecting",
|
||||
payload={"code": "multi_agent_researcher_failed", "message": str(result), "recoverable": True},
|
||||
)
|
||||
else:
|
||||
materials.extend(result)
|
||||
return {"materials": materials}
|
||||
|
||||
async def writer_node(state: _MultiAgentState) -> dict[str, Any]:
|
||||
materials = dedupe_materials(state.get("materials") or [])
|
||||
if not materials:
|
||||
return {"report": ""}
|
||||
await adapters.events.emit(
|
||||
"phase_changed",
|
||||
phase="curating",
|
||||
payload={"from": "collecting", "to": "curating"},
|
||||
)
|
||||
await adapters.events.emit(
|
||||
"sources_curated",
|
||||
phase="curating",
|
||||
payload={"selectedIds": [material.id for material in materials], "removedIds": [], "reason": "multi_agent_deduped"},
|
||||
)
|
||||
await adapters.events.emit(
|
||||
"phase_changed",
|
||||
phase="compressing",
|
||||
payload={"from": "curating", "to": "compressing"},
|
||||
)
|
||||
adapters.context.set_materials(materials)
|
||||
context_list = await adapters.context.async_get_context(
|
||||
request.query,
|
||||
max_results=min(len(materials), request.config.max_search_results_per_query * 2),
|
||||
)
|
||||
if not context_list:
|
||||
context_list = [
|
||||
material.to_context_dict()
|
||||
for material in materials[: min(len(materials), request.config.max_search_results_per_query * 2)]
|
||||
]
|
||||
await adapters.events.emit(
|
||||
"warning",
|
||||
phase="compressing",
|
||||
payload={
|
||||
"code": "context_fallback",
|
||||
"message": "材料压缩未返回上下文,已直接使用已收集素材撰写报告",
|
||||
"recoverable": True,
|
||||
"sourceCount": len(materials),
|
||||
"diagnostic": {
|
||||
"stage": "compressing",
|
||||
"outcome": "empty_context",
|
||||
"sourceCount": len(materials),
|
||||
},
|
||||
},
|
||||
)
|
||||
await adapters.events.emit(
|
||||
"phase_changed",
|
||||
phase="writing",
|
||||
payload={"from": "compressing", "to": "writing"},
|
||||
)
|
||||
report = await self._generate_report(
|
||||
adapters.llm,
|
||||
request,
|
||||
_format_context(context_list, materials),
|
||||
adapters.events,
|
||||
cancellation,
|
||||
source_count=len(materials),
|
||||
)
|
||||
# Keep the numbered context around so the runner can append the
|
||||
# deterministic reference section with the same [N] numbers the
|
||||
# writer saw (revise_node rewrites the report but keeps citations).
|
||||
return {"report": report, "context_list": context_list}
|
||||
|
||||
async def reviewer_node(state: _MultiAgentState) -> dict[str, Any]:
|
||||
await adapters.events.emit(
|
||||
"phase_changed",
|
||||
phase="reviewing",
|
||||
payload={"from": "writing", "to": "reviewing"},
|
||||
)
|
||||
async with model_semaphore:
|
||||
result = await adapters.llm.complete(
|
||||
model_role="smart",
|
||||
messages=[
|
||||
{"role": "system", "content": _SYSTEM},
|
||||
{"role": "user", "content": _REVIEW_PROMPT.format(report=state.get("report") or "")},
|
||||
],
|
||||
response_schema=ReviewVerdict,
|
||||
operation="review_multi_agent_report",
|
||||
)
|
||||
verdict = result.structured if result.structured else ReviewVerdict()
|
||||
return {"review": verdict.model_dump()}
|
||||
|
||||
async def revise_node(state: _MultiAgentState) -> dict[str, Any]:
|
||||
review = state.get("review") or {}
|
||||
report_version = int(state.get("revision_count") or 0) + 2
|
||||
await adapters.events.emit(
|
||||
"report_reset",
|
||||
phase="writing",
|
||||
payload={"reportVersion": report_version, "reason": "review_revision"},
|
||||
)
|
||||
from deerflow.agents.deep_research.runners.report_stream import ReportChunkEmitter
|
||||
|
||||
emitter = ReportChunkEmitter(adapters.events, report_version=report_version)
|
||||
async with model_semaphore:
|
||||
result = await adapters.llm.stream_complete(
|
||||
model_role="smart",
|
||||
messages=[
|
||||
{"role": "system", "content": _SYSTEM},
|
||||
{
|
||||
"role": "user",
|
||||
"content": _REVISE_PROMPT.format(notes=review.get("revision_notes") or "", report=state.get("report") or ""),
|
||||
},
|
||||
],
|
||||
operation="revise_multi_agent_report",
|
||||
on_delta=emitter.add,
|
||||
on_reasoning=emitter.add_thinking,
|
||||
)
|
||||
await emitter.flush()
|
||||
return {"report": result.text, "revision_count": int(state.get("revision_count") or 0) + 1}
|
||||
|
||||
def route_review(state: _MultiAgentState) -> str:
|
||||
review = state.get("review") or {}
|
||||
if review.get("approved") or int(state.get("revision_count") or 0) >= request.config.max_revision_loops:
|
||||
return "done"
|
||||
return "revise"
|
||||
|
||||
workflow = StateGraph(_MultiAgentState)
|
||||
workflow.add_node("researcher", research_node)
|
||||
workflow.add_node("writer", writer_node)
|
||||
workflow.add_node("reviewer", reviewer_node)
|
||||
workflow.add_node("reviser", revise_node)
|
||||
workflow.add_edge(START, "researcher")
|
||||
workflow.add_edge("researcher", "writer")
|
||||
workflow.add_edge("writer", "reviewer")
|
||||
workflow.add_conditional_edges("reviewer", route_review, {"done": END, "revise": "reviser"})
|
||||
workflow.add_edge("reviser", "reviewer")
|
||||
return workflow.compile()
|
||||
|
||||
async def _research_section(
|
||||
self,
|
||||
section: str,
|
||||
request: DeepResearchRequest,
|
||||
adapters: AdapterBundle,
|
||||
cancellation,
|
||||
model_semaphore: asyncio.Semaphore,
|
||||
) -> list[ResearchMaterial]:
|
||||
self._raise_if_cancelled(cancellation)
|
||||
async with model_semaphore:
|
||||
queries = await self._generate_queries(
|
||||
adapters.llm,
|
||||
section,
|
||||
request.config.max_iterations,
|
||||
cancellation,
|
||||
events=adapters.events,
|
||||
phase="collecting",
|
||||
retrieval_directions=request.config.retrieval_directions,
|
||||
)
|
||||
ordered_queries = list(dict.fromkeys([*queries, section]))[: request.config.max_iterations + 1]
|
||||
await adapters.events.emit(
|
||||
"queries_planned",
|
||||
phase="collecting",
|
||||
payload={"parentTopic": section, "queries": ordered_queries},
|
||||
)
|
||||
materials: list[ResearchMaterial] = []
|
||||
for query in ordered_queries:
|
||||
try:
|
||||
materials.extend(
|
||||
await self._search_one(
|
||||
adapters.materials,
|
||||
query,
|
||||
request.config,
|
||||
request,
|
||||
cancellation,
|
||||
adapters.events,
|
||||
)
|
||||
)
|
||||
except ResearchCancelled:
|
||||
raise
|
||||
except Exception as exc: # noqa: BLE001 - one failed term must not abort the section
|
||||
await adapters.events.emit(
|
||||
"warning",
|
||||
phase="collecting",
|
||||
payload={"code": "search_failed", "message": str(exc), "recoverable": True},
|
||||
)
|
||||
return materials
|
||||
|
||||
async def _no_materials_result(self, request: DeepResearchRequest, adapters: AdapterBundle, plan: dict[str, Any]) -> DeepResearchResult:
|
||||
return await super()._no_materials_result(request, adapters, plan)
|
||||
|
||||
@staticmethod
|
||||
def _normalise_sections(sections: list[str], max_sections: int) -> list[str]:
|
||||
seen: set[str] = set()
|
||||
result: list[str] = []
|
||||
for section in sections:
|
||||
title = section.strip()
|
||||
if not title or title in seen:
|
||||
continue
|
||||
seen.add(title)
|
||||
result.append(title)
|
||||
if len(result) >= max_sections:
|
||||
break
|
||||
return result
|
||||
|
||||
@staticmethod
|
||||
def _raise_if_cancelled(cancellation) -> None:
|
||||
if cancellation:
|
||||
cancellation.raise_if_cancelled()
|
||||
|
||||
|
||||
__all__ = ["MultiAgentPlan", "MultiAgentRunner", "ReviewVerdict"]
|
||||
+101
@@ -0,0 +1,101 @@
|
||||
"""Small, durable report-delta emitter shared by research runners.
|
||||
|
||||
The event store intentionally persists every emitted event. Sending one event
|
||||
for each provider token would therefore create excessive database writes and
|
||||
make reconnect replay expensive. This helper keeps the first visible delta
|
||||
immediate, then coalesces later deltas into bounded chunks.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from deerflow.agents.deep_research.events import EventSink, ResearchPhase
|
||||
|
||||
|
||||
class ReportChunkEmitter:
|
||||
"""Coalesce model deltas into replayable ``report_chunk`` events."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
events: EventSink,
|
||||
*,
|
||||
target: str = "report",
|
||||
report_version: int = 1,
|
||||
phase: ResearchPhase = "writing",
|
||||
chunk_size: int = 480,
|
||||
) -> None:
|
||||
self._events = events
|
||||
self._target = target
|
||||
self._report_version = report_version
|
||||
self._phase = phase
|
||||
self._chunk_size = chunk_size
|
||||
self._buffer = ""
|
||||
self._sent_first = False
|
||||
self._next_offset = 0
|
||||
self._persisted_offset = 0
|
||||
|
||||
async def add(self, delta: str) -> None:
|
||||
"""Add a provider delta, making the first one visible immediately."""
|
||||
if not delta:
|
||||
return
|
||||
# The sandbox UI receives the native model delta immediately. This is
|
||||
# intentionally non-durable; ``report_chunk`` below remains the
|
||||
# bounded checkpoint used for reconnect replay.
|
||||
await self._events.publish_live(
|
||||
"report_delta",
|
||||
phase=self._phase,
|
||||
payload={
|
||||
"delta": delta,
|
||||
"target": self._target,
|
||||
"reportVersion": self._report_version,
|
||||
"offset": self._next_offset,
|
||||
},
|
||||
)
|
||||
self._next_offset += len(delta)
|
||||
self._buffer += delta
|
||||
if not self._sent_first:
|
||||
first = self._buffer[: self._chunk_size]
|
||||
await self._emit(first)
|
||||
self._buffer = self._buffer[self._chunk_size :]
|
||||
self._sent_first = True
|
||||
while len(self._buffer) >= self._chunk_size:
|
||||
await self._emit(self._buffer[: self._chunk_size])
|
||||
self._buffer = self._buffer[self._chunk_size :]
|
||||
|
||||
async def add_thinking(self, delta: str) -> None:
|
||||
"""Forward reasoning to the live UI without persisting it as report text."""
|
||||
if not delta:
|
||||
return
|
||||
await self._events.publish_live(
|
||||
"report_thinking",
|
||||
phase=self._phase,
|
||||
payload={
|
||||
"delta": delta,
|
||||
"target": self._target,
|
||||
"reportVersion": self._report_version,
|
||||
},
|
||||
)
|
||||
|
||||
async def flush(self) -> None:
|
||||
"""Persist the final tail once the model stream has finished."""
|
||||
if self._buffer:
|
||||
await self._emit(self._buffer)
|
||||
self._buffer = ""
|
||||
|
||||
async def _emit(self, delta: str) -> None:
|
||||
await self._events.emit(
|
||||
"report_chunk",
|
||||
phase=self._phase,
|
||||
payload={
|
||||
"delta": delta,
|
||||
"target": self._target,
|
||||
"reportVersion": self._report_version,
|
||||
"offset": self._persisted_offset,
|
||||
},
|
||||
)
|
||||
self._persisted_offset += len(delta)
|
||||
|
||||
|
||||
__all__ = ["ReportChunkEmitter"]
|
||||
Reference in new issue
Block a user