deepresearch-flow 0.5.1__py3-none-any.whl → 0.6.0__py3-none-any.whl

deepresearch_flow/paper/prompt_templates/deep_read_phi_system.j2

@@ -3,4 +3,6 @@ Output language: {{ output_language }}.
 Extract structured data from the provided markdown document.
 Return ONLY valid JSON that conforms to the given JSON Schema.
 The field "paper_authors" MUST be an array of strings (each author name as one item).
+If affiliations are available, extract them into "paper_institutions" as a list of institution names.
+Ensure JSON strings escape newlines and code blocks properly.
 If a field is unknown, use an empty string or empty list per schema.

deepresearch_flow/paper/prompt_templates/deep_read_phi_user.j2

@@ -12,6 +12,11 @@ Template: deep_read_phi
 关键结论需要注明来自论文的定位（章节/图/表/公式编号）。
 每轮末尾要求输出的三行仍需保留，但不要中途停止输出。
 输出语言：{{ output_language }}。请使用该语言输出（zh 时使用中文，保留必要英文术语）。
+
+图示要求（仅在内容触发时输出，使用 mermaid/markmap 代码块，不要臆造）：
+- 模块 M1：若论文结构清晰，输出 markmap 思维导图。
+- 模块 M2/M4/M5：若出现清晰的论证结构或概念结构，可用 flowchart TD/LR 表达。
+- 若论文包含架构/流程/数据流/性能对比等内容，按内容选择合适的 flowchart。
 {% endif %}
 
 ---

deepresearch_flow/paper/prompt_templates/deep_read_system.j2

@@ -3,4 +3,6 @@ Output language: {{ output_language }}.
 Extract structured data from the provided markdown document.
 Return ONLY valid JSON that conforms to the given JSON Schema.
 The field "paper_authors" MUST be an array of strings (each author name as one item).
+If affiliations are available, extract them into "paper_institutions" as a list of institution names.
+Ensure JSON strings escape newlines and code blocks properly.
 If a field is unknown, use an empty string or empty list per schema.

deepresearch_flow/paper/prompt_templates/deep_read_user.j2

@@ -10,6 +10,74 @@ Template: deep_read
 每个模块字段内部使用 Markdown 编排（标题、列表等）。
 禁止第一人称（不出现“我/我们/本人”）。
 关键结论需要注明来自论文的定位（章节/图/表/公式编号）。
+
+图示要求（使用 mermaid/markmap 代码块，必须按论文类型输出对应图示）：
+- 如果图示为推断（非原文明确给出），标题前加前缀 [Inferred]。
+- Mermaid 语法要求：节点 ID 只用简单字母数字（如 NodeA/step1），描述文字放在标签里（如 NodeA["复杂描述 (含括号)"]），避免 ID 含空格或特殊字符。
+- 图示用于补充文字而非替代，图后仍要有文字说明。
+- 模块 B：必须给出全文结构的 markmap 导图（无论是否明确提纲）。
+- 综述/调研类论文：必须给出“分类体系 + 代表工作/方法”的图（mermaid flowchart TD），用于总结分类与代表工作。
+- 算法方法类论文：必须给出流程图（flowchart TD）和数据流图（flowchart LR）。
+- 硬件/系统类论文：必须给出架构图（flowchart LR）和数据流图（flowchart LR）。
+- 模块 C3：算法流程图（flowchart TD）。
+- 模块 D：硬件/系统架构图（flowchart LR）。
+- 模块 C4/C5：数据流图（flowchart LR）。
+- 模块 E：性能-精度权衡图（flowchart TD）。
+- 模块 H：实验设置图（flowchart TD）。
+
+示例（每个小结都必须参照，严格遵守代码块与语法，节点 ID 简单）：
+1) 全文结构导图（markmap）：
+```markmap
+# Paper Overview
+## Introduction
+## Method
+### Pipeline
+### Modules
+## Experiments
+## Conclusion
+```
+2) 综述/调研分类图（mermaid flowchart TD）：
+```mermaid
+flowchart TD
+  CatA["Category A"]
+  CatB["Category B"]
+  CatC["Category C"]
+  W1["Work 1"]
+  W2["Work 2"]
+  W3["Work 3"]
+  CatA --> W1
+  CatB --> W2
+  CatC --> W3
+```
+3) 算法流程图（mermaid flowchart TD）：
+```mermaid
+flowchart TD
+  NodeA["Input Data"]
+  NodeB["Preprocessing"]
+  NodeC["Model"]
+  NodeD["Evaluation"]
+  NodeA --> NodeB --> NodeC --> NodeD
+```
+4) 数据流图（mermaid flowchart LR）：
+```mermaid
+flowchart LR
+  Step1["Raw Data"] --> Step2["Feature Extractor"] --> Step3["Fusion"] --> Step4["Output"]
+```
+5) 硬件/系统架构图（mermaid flowchart LR）：
+```mermaid
+flowchart LR
+  Host["Host"] --> FPGA["FPGA/Accelerator"] --> Mem["Memory/IO"]
+```
+6) 性能-精度权衡图（mermaid flowchart TD）：
+```mermaid
+flowchart TD
+  Fast["Fast/Low Accuracy"] --> Balanced["Balanced"] --> Accurate["Accurate/Slow"]
+```
+7) 实验设置图（mermaid flowchart TD）：
+```mermaid
+flowchart TD
+  Dataset["Datasets"] --> Metrics["Metrics"] --> Baselines["Baselines"] --> Results["Results"]
+```
 {% endif %}
 
 ---
@@ -34,49 +102,213 @@ Template: deep_read
 - 可选模块 G：联网核验与引用校对
 - 模块 H：图表与表格的客观抽取
 
-## 2) 模块内容规范
-### 模块 A：阅读对齐与输入校验
-- 明确用户目的与背景
-- 检查输入材料：PDF/附录/代码链接/补充材料/数据集
-- 输出阅读路线图
-
-### 模块 B：第一遍（鸟瞰扫描）
-必须给出 5 项产出：类别、上下文、正确性直觉检查、贡献、清晰度，并给出继续/放弃建议。
-
-### 模块 C1~C8：八个问题
-问题1：论文试图解决什么问题？
-问题2：有哪些相关研究？（最强基线/最相近思路/正交方向）
-问题3：论文如何解决这个问题？（流程图文字版）
-问题4：实验数据集与实现设置：用了哪些数据集/场景？为什么选它们？验证哪些关键特性？
-问题5：指标与结果：有哪些指标？实验结果是什么？这些指标分别体现了哪些创新点？尽力抽取全部结果指标。
-问题6：有什么可以进一步探索的点？（理论/工程/数据/评测）
-问题7：现实场景如何体现/实现？（部署约束、算力、延迟、鲁棒性）
-问题8：总结主要内容（一段摘要 + 5 条要点 + 1 个核心公式/机制）
-
-### 模块 D：第二遍（内容理解）
-- 给出结构树
-- 拆解核心方法：输入/输出/模块/损失/训练或推理流程
-- 关键图表说明
-- 实验部分：数据集、指标、对比方法、公平性、消融充分性
-
-### 模块 E：第三遍（深度审视）
-必须包含：可复现重建（伪代码）、假设清单、失败模式、强弱点评估、下一步研究。
-
-### 模块 F：术语表（可选）
-- 15-40 个关键词，包含中英文名、定义、直觉解释、作用、前置知识
-- 术语依赖图（文字版）
-
-### 模块 G：联网核验（可选）
-- 关键事实提供至少 2 个独立来源
-- 冲突要显式说明，无法核验要标记
-- 输出引用列表
-
-### 模块 H：图表与表格抽取
-- 全量索引、打分、TOP 深读
-- 需要明确图表位置、图注、类型、支撑的 claim
+## 2) 模块内容规范（强制格式 + 详细模板）
+{% if stage_name %}
+### 当前阶段：{{ stage_name }}
+#### 非当前模块摘要（仅摘要，不写细节）
+- 模块 A：基本信息与输入校验
+- 模块 B：鸟瞰扫描 + 结构导图
+- 模块 C1~C8：八问深读（问题/方法/数据/结果/展望）
+- 模块 D：结构树 + 方法拆解 + 图表说明 + 实验细节
+- 模块 E：伪代码 + 假设 + 失败模式 + 强弱点评 + 下一步
+- 模块 F：术语表 + 依赖关系
+- 模块 G：事实核验 + 冲突说明 + 引用列表
+- 模块 H：图表索引 + 深读 + 图表关系说明
+
+#### 当前模块详细规范（必须严格遵守）
+{% if stage_name == "module_a" %}
+### 模块 A：阅读对齐与输入校验（强制格式）
+必须包含以下小节（按顺序输出）：
+1) 论文基本信息
+   - 标题：
+   - 作者（姓名 / 单位 / 简历或背景〔若文中提供〕）：
+   - 发表信息（期刊/会议/年份/级别〔如有〕）：
+2) 研究定位
+   - 研究领域：
+   - 具体任务：
+   - 目标用户/应用场景：
+3) 输入材料清单
+   - PDF：
+   - 附录/补充材料：
+   - 代码链接：
+   - 数据集链接：
+4) 缺失材料与风险
+   - 缺失项：
+   - 可能影响：
+5) 阅读路线图（3-6 步）
+   - Step 1:
+   - Step 2:
+   - Step 3:
+示例（仅参考格式）：
+【论文基本信息】标题: ...；作者: ...；发表: ...
+【研究定位】领域/任务/场景...
+【输入材料清单】PDF: 有/无；代码: ...
+【缺失材料与风险】...
+【阅读路线图】Step 1...Step 2...
+{% elif stage_name == "module_b" %}
+### 模块 B：第一遍鸟瞰扫描（强制格式）
+必须包含以下小节（按顺序输出）：
+1) 论文类型与类别
+2) 上下文与研究背景
+3) 正确性直觉检查（关键假设与合理性）
+4) 核心贡献（3-5 条，逐条）
+5) 清晰度评估（结构/图表/公式可读性）
+6) 继续/放弃建议（给出明确建议 + 依据）
+7) 结构导图（必须包含 markmap 代码块）
+示例（仅参考格式）：
+【论文类型与类别】...
+【上下文】...
+【贡献】1) ... 2) ...
+```markmap
+# Paper Overview
+## Introduction
+## Method
+## Experiments
+## Conclusion
+```
+{% elif stage_name == "module_c1" %}
+### 模块 C1：论文试图解决什么问题？（强制格式）
+必须包含以下小节：
+1) 问题定义（一句话）
+2) 痛点/不足（2-4 条）
+3) 形式化目标或优化目标（如有公式）
+4) 成功判据（指标或性质）
+示例：问题定义/痛点/目标/判据逐条说明。
+{% elif stage_name == "module_c2" %}
+### 模块 C2：相关研究（强制格式）
+必须包含以下小节：
+1) 最强基线（1-2 个）+ 对比点
+2) 最相近思路（1-2 个）+ 区别点
+3) 正交方向（2-3 个）
+4) 本文相对位置（一句话定位）
+示例：使用“方法名 -> 核心思想 -> 局限”结构。
+例：BaselineX -> 关键机制 -> 局限；ClosestY -> 区别点 -> 适用场景。
+{% elif stage_name == "module_c3" %}
+### 模块 C3：论文如何解决问题？（强制格式）
+必须包含以下小节：
+1) 核心机制概述（1-2 段）
+2) 步骤拆解（逐步）
+3) 关键公式/模块作用
+4) 流程图（mermaid flowchart TD）
+示例（流程图必须出现）：
+```mermaid
+flowchart TD
+  Step1["Input"] --> Step2["Process"] --> Step3["Output"]
+```
+{% elif stage_name == "module_c4" %}
+### 模块 C4：实验数据集与设置（强制格式）
+必须包含以下小节：
+1) 数据集列表（名称/规模/场景）
+2) 预处理与划分
+3) 训练/推理环境（硬件/软件）
+4) 选择理由与验证目标
+示例：DatasetA(规模/场景)；Split=Train/Val/Test；GPU/驱动/框架版本。
+{% elif stage_name == "module_c5" %}
+### 模块 C5：指标与结果（强制格式）
+必须包含以下小节：
+1) 指标列表（含定义或解释）
+2) 主要结果（尽量给具体数值）
+3) 与基线对比（提升/下降）
+4) 消融/敏感性（若有）
+示例：Metric=Acc/F1；Result=XX；Baseline=YY；提升=+ZZ%。
+{% elif stage_name == "module_c6" %}
+### 模块 C6：进一步探索（强制格式）
+必须包含：理论方向、工程方向、数据/评测方向各至少 1 条。
+示例：理论=新损失；工程=推理加速；数据=更难场景评测。
+{% elif stage_name == "module_c7" %}
+### 模块 C7：现实场景体现（强制格式）
+必须包含：部署约束、算力/延迟、鲁棒性/安全性、可维护性。
+示例：约束=边缘设备；延迟<XXms；鲁棒性=遮挡/噪声；可维护=更新频率。
+{% elif stage_name == "module_c8" %}
+### 模块 C8：总结（强制格式）
+必须包含：
+1) 一段摘要（6-8 句）
+2) 5 条要点
+3) 1 个核心公式/机制（LaTeX）
+示例：摘要...；要点1..5；公式：$E=mc^2$。
+{% elif stage_name == "module_d" %}
+### 模块 D：第二遍内容理解（强制格式）
+必须包含以下小节：
+1) 结构树（层级列表）
+2) 方法拆解（输入/输出/模块/损失/训练或推理流程）
+3) 关键图表说明（至少 2 个）
+4) 实验细节（数据集/指标/对比方法/公平性/消融）
+5) 图示（算法类：流程图+数据流图；硬件/系统类：架构图+数据流图）
+示例：先给结构树，再给流程图，图后解释关键步骤与实验结论关联。
+{% elif stage_name == "module_e" %}
+### 模块 E：第三遍深度审视（强制格式）
+必须包含：
+1) 可复现重建（伪代码）
+2) 假设清单（3-6 条）
+3) 失败模式（2-4 条）
+4) 强弱点评估（优点/缺点）
+5) 下一步研究（2-4 条）
+示例：伪代码块 + 假设1/2 + 失败模式A/B。
+{% elif stage_name == "module_f" %}
+### 模块 F：术语表（强制格式）
+必须输出 15-40 个条目，每条包含：中英文名/定义/直觉/作用/前置知识。
+最后追加“术语依赖图（文字版）”。
+示例：Term(EN/中): 定义... 直觉... 作用... 前置...
+{% elif stage_name == "module_g" %}
+### 模块 G：联网核验（强制格式）
+必须包含：
+1) 关键事实清单（每条至少 2 个来源）
+2) 冲突与不确定性说明
+3) 引用列表（按条列出）
+示例：Claim1 -> sourceA/sourceB；冲突=...；引用=[1][2]。
+{% elif stage_name == "module_h" %}
+### 模块 H：图表与表格抽取（强制格式）
+必须包含以下小节：
+1) 全量索引（表格：编号/图注/类型/位置/支撑 claim/评分）
+2) TOP 深读（3-5 项，逐条解释）
+3) 图表关系或实验设置图（mermaid）
+4) 图与结论对应关系说明
+示例：表格索引 + Top1 深读 + mermaid 图 + 对应结论说明。
+{% endif %}
+{% else %}
+### 单次输出模式：所有模块均需详细完成
+请按以下“强制格式模板”逐模块输出，每个模块必须覆盖其必填项与示例要求。
+
+#### 模块 A（模板）
+【论文基本信息】标题/作者/单位/简历/发表信息/级别
+【研究定位】领域/任务/场景
+【输入材料清单】PDF/附录/代码/数据
+【缺失材料与风险】
+【阅读路线图】Step 1..Step N
+
+#### 模块 B（模板）
+【论文类型与类别】...【上下文】...【正确性直觉】...【贡献】...【清晰度】...【继续/放弃建议】...
+结构导图（markmap 代码块）
+
+#### 模块 C1~C8（模板）
+按 C1..C8 小节逐条回答，至少包含“问题定义/关键点/证据定位”。
+
+#### 模块 D（模板）
+结构树 + 方法拆解 + 关键图表说明 + 实验细节 + 必要图示。
+
+#### 模块 E（模板）
+伪代码 + 假设清单 + 失败模式 + 强弱点评 + 下一步研究。
+
+#### 模块 F（模板）
+15-40 术语条目 + 术语依赖图（文字版）。
+
+#### 模块 G（模板）
+关键事实清单（双来源）+ 冲突说明 + 引用列表。
+
+#### 模块 H（模板）
+全量索引 + TOP 深读 + 图表关系/实验设置图 + 图与结论关系说明。
+{% endif %}
 
 Document content:
 {{ content }}
 
 JSON Schema:
 {{ schema }}
+
+{% if stage_name %}
+---
+Critical Instructions for Stage {{ stage_name }}:
+1) OUTPUT FORMAT: STRICT JSON only. No markdown fences outside the JSON.
+2) COMPLETENESS: You must cover ALL requirements listed for Module {{ stage_name }} above, in detail.
+3) NEGATIVE CONSTRAINT: Do NOT generate fields for other modules.
+{% endif %}

deepresearch_flow/paper/prompt_templates/eight_questions_phi_system.j2

@@ -3,4 +3,5 @@ Output language: {{ output_language }}.
 Extract structured data from the provided markdown document.
 Return ONLY valid JSON that conforms to the given JSON Schema.
 The field "paper_authors" MUST be an array of strings (each author name as one item).
+If affiliations are available, extract them into "paper_institutions" as a list of institution names.
 If a field is unknown, use an empty string or empty list per schema.

deepresearch_flow/paper/prompt_templates/eight_questions_phi_user.j2

@@ -42,6 +42,7 @@ Output language: {{ output_language }}. Use that language in all answers (if zh,
 5) 防幻觉：超出原文必须标【推测】；原文未给证据/范围必须写“论文未给出”或【证据不足】。
 6) 输出顺序严格按 Q1→Q8。除 Q8 的“5 bullets”外，不要堆长列表；保持信息密度。
 7) 输出语言以 {{ output_language }} 为准（zh 时使用中文）。
+8) 图示要求：仅在内容触发时输出 Mermaid 架构图。触发词：architecture/module/pipeline/stage/system/flow 或明确模块描述。图放在 Q3 内。
 
 ========================
 Mermaid/流程图要求（避免中文报错）
@@ -73,6 +74,7 @@ Q3) 作者如何解决这个问题？（必须含文字流程图）
 - 必须提供一个“文字流程图（ASCII）”，示例格式：
   [争点] -> [主论题] -> [关键概念界定] -> [论证路线A] -> [关键反对] -> [回应] -> [结论/含义]
 - 若用户要求 Mermaid，再额外输出 Mermaid-safe 版本（遵守避坑规则）。
+- 若触发图示要求，请在 Q3 中同时给出 Mermaid-safe 版本。
 
 Q4) 论文使用了哪些“证据载体/材料/设定”？为什么这些材料能验证/支撑主张？
 （哲学版替代“数据集与实现设置”）

deepresearch_flow/paper/prompt_templates/eight_questions_system.j2

@@ -3,4 +3,6 @@ Output language: {{ output_language }}.
 Extract structured data from the provided markdown document.
 Return ONLY valid JSON that conforms to the given JSON Schema.
 The field "paper_authors" MUST be an array of strings (each author name as one item).
+If affiliations are available, extract them into "paper_institutions" as a list of institution names.
+Ensure JSON strings escape newlines and code blocks properly.
 If a field is unknown, use an empty string or empty list per schema.

deepresearch_flow/paper/prompt_templates/eight_questions_user.j2

@@ -9,6 +9,10 @@ Previously completed outputs (JSON): {{ previous_outputs }}
 Answer each question in the corresponding JSON field question1 through question8.
 Use Markdown in each answer if helpful.
 Output language: {{ output_language }}. Use that language in all answers (if zh, use Chinese).
+
+Diagram guidance (only when relevant; do not invent):
+- In question3, include a mermaid architecture diagram when the paper describes system/model architecture or algorithm flow.
+- Triggers: "architecture", "module", "pipeline", "stage", "system", "flow" or explicit block/module descriptions.
 {% endif %}
 
 Questions:

deepresearch_flow/paper/prompt_templates/simple_phi_system.j2

@@ -3,4 +3,6 @@ Output language: {{ output_language }}.
 Extract structured data from the provided markdown document.
 Return ONLY valid JSON that conforms to the given JSON Schema.
 The field "paper_authors" MUST be an array of strings (each author name as one item).
+If affiliations are available, extract them into "paper_institutions" as a list of institution names.
+Ensure JSON strings escape newlines and code blocks properly.
 If a field is unknown, use an empty string or empty list per schema.

deepresearch_flow/paper/prompt_templates/simple_system.j2

@@ -3,4 +3,6 @@ Output language: {{ output_language }}.
 Extract structured data from the provided markdown document.
 Return ONLY valid JSON that conforms to the given JSON Schema.
 The field "paper_authors" MUST be an array of strings (each author name as one item).
+If affiliations are available, extract them into "paper_institutions" as a list of institution names.
+Ensure JSON strings escape newlines and code blocks properly.
 If a field is unknown, use an empty string or empty list per schema.

deepresearch_flow/paper/prompt_templates/simple_user.j2

@@ -15,6 +15,8 @@ Write a single-paragraph summary that covers:
 - real-world scenarios and constraints
 - the main content summary with one core formula/mechanism
 Output language: {{ output_language }}. Use that language in all answers (if zh, use Chinese).
+
+If affiliations are present, include them in paper_institutions.
 {% endif %}
 
 Document content:

deepresearch_flow/paper/providers/azure_openai.py

@@ -8,6 +8,40 @@ import httpx
 from deepresearch_flow.paper.providers.base import ProviderError
 
 
+def _extract_error_message(response: httpx.Response) -> str:
+    parts: list[str] = []
+    try:
+        data = response.json()
+    except ValueError:
+        data = None
+    if isinstance(data, dict):
+        error = data.get("error")
+        if isinstance(error, dict):
+            for key in ("code", "type", "message"):
+                value = error.get(key)
+                if isinstance(value, str):
+                    value = value.strip()
+                    if value and value not in parts:
+                        parts.append(value)
+        elif isinstance(error, str):
+            value = error.strip()
+            if value and value not in parts:
+                parts.append(value)
+        for key in ("code", "type", "message"):
+            value = data.get(key)
+            if isinstance(value, str):
+                value = value.strip()
+                if value and value not in parts:
+                    parts.append(value)
+    if parts:
+        return " | ".join(parts)
+    text = (response.text or "").strip()
+    if text:
+        return text
+    reason = response.reason_phrase or "HTTP error"
+    return f"{response.status_code} {reason}".strip()
+
+
 async def chat(
     client: httpx.AsyncClient,
     endpoint: str,
@@ -48,12 +82,20 @@ async def chat(
         raise ProviderError(str(exc), retryable=True) from exc
 
     if response.status_code == 429:
-        raise ProviderError(response.text, status_code=429, retryable=True)
+        raise ProviderError(_extract_error_message(response), status_code=429, retryable=True)
     if response.status_code >= 500:
-        raise ProviderError(response.text, status_code=response.status_code, retryable=True)
+        raise ProviderError(
+            _extract_error_message(response),
+            status_code=response.status_code,
+            retryable=True,
+        )
     if response.status_code >= 400:
         structured_error = structured_mode in ("json_schema", "json_object")
-        raise ProviderError(response.text, status_code=response.status_code, structured_error=structured_error)
+        raise ProviderError(
+            _extract_error_message(response),
+            status_code=response.status_code,
+            structured_error=structured_error,
+        )
 
     data = response.json()
     choices = data.get("choices") or []

deepresearch_flow/paper/providers/openai_compatible.py

@@ -8,6 +8,40 @@ import httpx
 from deepresearch_flow.paper.providers.base import ProviderError
 
 
+def _extract_error_message(response: httpx.Response) -> str:
+    parts: list[str] = []
+    try:
+        data = response.json()
+    except ValueError:
+        data = None
+    if isinstance(data, dict):
+        error = data.get("error")
+        if isinstance(error, dict):
+            for key in ("code", "type", "message"):
+                value = error.get(key)
+                if isinstance(value, str):
+                    value = value.strip()
+                    if value and value not in parts:
+                        parts.append(value)
+        elif isinstance(error, str):
+            value = error.strip()
+            if value and value not in parts:
+                parts.append(value)
+        for key in ("code", "type", "message"):
+            value = data.get(key)
+            if isinstance(value, str):
+                value = value.strip()
+                if value and value not in parts:
+                    parts.append(value)
+    if parts:
+        return " | ".join(parts)
+    text = (response.text or "").strip()
+    if text:
+        return text
+    reason = response.reason_phrase or "HTTP error"
+    return f"{response.status_code} {reason}".strip()
+
+
 async def chat(
     client: httpx.AsyncClient,
     base_url: str,
@@ -42,12 +76,20 @@ async def chat(
         raise ProviderError(str(exc), retryable=True) from exc
 
     if response.status_code == 429:
-        raise ProviderError(response.text, status_code=429, retryable=True)
+        raise ProviderError(_extract_error_message(response), status_code=429, retryable=True)
     if response.status_code >= 500:
-        raise ProviderError(response.text, status_code=response.status_code, retryable=True)
+        raise ProviderError(
+            _extract_error_message(response),
+            status_code=response.status_code,
+            retryable=True,
+        )
     if response.status_code >= 400:
         structured_error = structured_mode in ("json_schema", "json_object")
-        raise ProviderError(response.text, status_code=response.status_code, structured_error=structured_error)
+        raise ProviderError(
+            _extract_error_message(response),
+            status_code=response.status_code,
+            structured_error=structured_error,
+        )
 
     data = response.json()
     choices = data.get("choices") or []

deepresearch_flow/paper/schemas/deep_read_phi_schema.json

@@ -25,6 +25,7 @@
     "module_m4": {"type": "string"},
     "module_m5": {"type": "string"},
     "module_m6": {"type": "string"},
+    "paper_institutions": {"type": "array", "items": {"type": "string"}},
     "output_language": {"type": "string"}
   }
 }

deepresearch_flow/paper/schemas/deep_read_schema.json

@@ -41,6 +41,7 @@
     "module_f": {"type": "string"},
     "module_g": {"type": "string"},
     "module_h": {"type": "string"},
+    "paper_institutions": {"type": "array", "items": {"type": "string"}},
     "output_language": {"type": "string"}
   }
 }

deepresearch_flow/paper/schemas/default_paper_schema.json

@@ -40,6 +40,12 @@
     "summary": {
       "type": "string"
     },
+    "paper_institutions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
     "output_language": {
       "type": "string"
     }

deepresearch_flow/paper/schemas/eight_questions_schema.json

@@ -29,6 +29,7 @@
     "question6": {"type": "string"},
     "question7": {"type": "string"},
     "question8": {"type": "string"},
+    "paper_institutions": {"type": "array", "items": {"type": "string"}},
     "output_language": {"type": "string"}
   }
 }

deepresearch_flow/paper/snapshot/__init__.py

@@ -0,0 +1,4 @@
+"""Snapshot build + API utilities for production deployments."""
+
+from __future__ import annotations
+