article-q 0.2.1__tar.gz → 0.2.2__tar.gz

{article_q-0.2.1 → article_q-0.2.2}/.gitignore

@@ -188,6 +188,9 @@ cython_debug/
 #   option (not recommended) you can uncomment the following to ignore the entire idea folder.
 # .idea/
 
+# Claude Code
+.claude/
+
 # Abstra
 #   Abstra is an AI-powered process automation framework.
 #   Ignore directories containing user credentials, local state, and settings.

{article_q-0.2.1 → article_q-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: article-q
-Version: 0.2.1
+Version: 0.2.2
 Summary: Agent/LLM-enabled narrative reviews of academic manuscripts
 License-Expression: MIT
 License-File: LICENSE
@@ -24,10 +24,22 @@ Agent/LLM-enabled narrative reviews of academic manuscripts. Parses PDFs, extrac
 
 ## Installation
 
-Requires Python 3.11+.
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/getting-started/installation/) (recommended).
 
 ```bash
-pip install -e .
+uv pip install article-q
+```
+
+Or with pip:
+
+```bash
+pip install article-q
+```
+
+For development, clone the repository and install in editable mode:
+
+```bash
+uv pip install -e .
 ```
 
 ## Step-by-step workflow
@@ -151,6 +163,44 @@ articleq visualize -r output/results.json
 
 The viewer shows each paper's content alongside extracted answers, with evidence passages highlighted in the text. Pass `-q questions.csv` to include question text in the results panel.
 
+### Step 7: Synthesize findings across papers (optional)
+
+After extraction, you can synthesize findings across all papers to answer higher-level research questions. Create a synthesis questions CSV:
+
+```csv
+id,question,source_questions,description
+overall_findings,"What are the overall findings regarding primary outcomes across the included studies?","primary_outcome,sample_size",
+study_designs,"Summarize the study designs used across the included studies.","study_design",
+```
+
+| Column | Required | Description |
+|---|---|---|
+| `id` | yes | Unique synthesis question identifier |
+| `question` | yes | The synthesis question text |
+| `source_questions` | no | Comma-separated extraction question IDs to include (all if empty) |
+| `description` | no | Additional guidance for the LLM |
+
+Set `synthesis_questions_file` in your config:
+
+```toml
+[project]
+synthesis_questions_file = "./synthesis_questions.csv"
+```
+
+Then run synthesis:
+
+```bash
+articleq synthesize -c articleq.toml
+```
+
+This reads the extraction results from `output/results.json`, runs the synthesis agent for each question, and writes `output/synthesis.json`. Export to CSV:
+
+```bash
+articleq export output/synthesis.json --type synthesis --format csv
+```
+
+The synthesis agent sees only the tabulated extraction data (values, confidence scores, evidence quotes) — not full paper text. It produces a narrative synthesis with key findings, citing specific studies.
+
 ## How it works
 
 Each question for each paper goes through a three-agent workflow:
@@ -205,6 +255,7 @@ papers_dir = "./papers"          # Directory containing PDF files
 questions_file = "./questions.csv"  # Path to questions CSV/Excel
 output_dir = "./output"          # Where results are written
 # context_file = "./context.md" # Optional: additional instructions for the LLM
+# synthesis_questions_file = "./synthesis_questions.csv"  # Optional: cross-study synthesis questions
 
 [parsing]
 backend = "pymupdf"             # "pymupdf" or "marker"
@@ -214,6 +265,7 @@ reparse = false                 # Force re-parsing even if cached results exist
 extraction_model = "openai:gpt-4o"   # Model for primary extraction
 validation_model = "openai:gpt-4o"   # Model for validation pass
 consensus_model = "openai:gpt-4o"    # Model for arbitration
+synthesis_model = "openai:gpt-4o"    # Model for cross-study synthesis
 # temperature = 0.0                  # LLM sampling temperature (omit to use provider default)
 
 [llm.api_keys]
@@ -228,7 +280,7 @@ chunk_max_tokens = 8000         # Max tokens per chunk for large PDFs
 
 [validation]
 auto_accept_threshold = 0.9     # Min confidence to auto-accept agreement
-always_validate_categories = ["primary_outcome"]  # Always run full 3-agent flow for these
+always_validate_questions = ["primary_outcome"]  # Always run full 3-agent flow for these
 ```
 
 ## Additional topics
@@ -258,7 +310,8 @@ output/
 │       ├── study_smith_2020_img1.png
 │       ├── study_smith_2020_img2.png
 │       └── study_jones_2021_img1.png
-└── results.json
+├── results.json
+└── synthesis.json          # (after running synthesize)
 ```
 
 ### Context file
@@ -387,7 +440,8 @@ articleq run -c CONFIG [--reparse]    Run the full pipeline (parse + extract)
 articleq parse -c CONFIG [--reparse]  Parse PDFs and save as markdown (no LLM calls)
 articleq rebuild -c CONFIG            Rebuild markdown and JSON from edited blocks
 articleq extract -c CONFIG            Run LLM extraction on pre-parsed papers
-articleq export RESULTS [--format csv|excel] [-o PATH]   Export to CSV/Excel
+articleq synthesize -c CONFIG         Synthesize findings across papers
+articleq export RESULTS [--format csv|excel] [-o PATH] [--type extraction|synthesis]   Export to CSV/Excel
 articleq eval RESULTS EXPECTED [-q QUESTIONS] [--judge-model MODEL] [-c CONFIG]   Evaluate against ground truth
 articleq visualize -r RESULTS [-o PATH] [-q QUESTIONS]   Generate HTML evidence viewer
 articleq visualize --parsed-dir DIR [-o PATH]            Preview parsed papers (no results)

{article_q-0.2.1 → article_q-0.2.2}/README.md

@@ -4,10 +4,22 @@ Agent/LLM-enabled narrative reviews of academic manuscripts. Parses PDFs, extrac
 
 ## Installation
 
-Requires Python 3.11+.
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/getting-started/installation/) (recommended).
 
 ```bash
-pip install -e .
+uv pip install article-q
+```
+
+Or with pip:
+
+```bash
+pip install article-q
+```
+
+For development, clone the repository and install in editable mode:
+
+```bash
+uv pip install -e .
 ```
 
 ## Step-by-step workflow
@@ -131,6 +143,44 @@ articleq visualize -r output/results.json
 
 The viewer shows each paper's content alongside extracted answers, with evidence passages highlighted in the text. Pass `-q questions.csv` to include question text in the results panel.
 
+### Step 7: Synthesize findings across papers (optional)
+
+After extraction, you can synthesize findings across all papers to answer higher-level research questions. Create a synthesis questions CSV:
+
+```csv
+id,question,source_questions,description
+overall_findings,"What are the overall findings regarding primary outcomes across the included studies?","primary_outcome,sample_size",
+study_designs,"Summarize the study designs used across the included studies.","study_design",
+```
+
+| Column | Required | Description |
+|---|---|---|
+| `id` | yes | Unique synthesis question identifier |
+| `question` | yes | The synthesis question text |
+| `source_questions` | no | Comma-separated extraction question IDs to include (all if empty) |
+| `description` | no | Additional guidance for the LLM |
+
+Set `synthesis_questions_file` in your config:
+
+```toml
+[project]
+synthesis_questions_file = "./synthesis_questions.csv"
+```
+
+Then run synthesis:
+
+```bash
+articleq synthesize -c articleq.toml
+```
+
+This reads the extraction results from `output/results.json`, runs the synthesis agent for each question, and writes `output/synthesis.json`. Export to CSV:
+
+```bash
+articleq export output/synthesis.json --type synthesis --format csv
+```
+
+The synthesis agent sees only the tabulated extraction data (values, confidence scores, evidence quotes) — not full paper text. It produces a narrative synthesis with key findings, citing specific studies.
+
 ## How it works
 
 Each question for each paper goes through a three-agent workflow:
@@ -185,6 +235,7 @@ papers_dir = "./papers"          # Directory containing PDF files
 questions_file = "./questions.csv"  # Path to questions CSV/Excel
 output_dir = "./output"          # Where results are written
 # context_file = "./context.md" # Optional: additional instructions for the LLM
+# synthesis_questions_file = "./synthesis_questions.csv"  # Optional: cross-study synthesis questions
 
 [parsing]
 backend = "pymupdf"             # "pymupdf" or "marker"
@@ -194,6 +245,7 @@ reparse = false                 # Force re-parsing even if cached results exist
 extraction_model = "openai:gpt-4o"   # Model for primary extraction
 validation_model = "openai:gpt-4o"   # Model for validation pass
 consensus_model = "openai:gpt-4o"    # Model for arbitration
+synthesis_model = "openai:gpt-4o"    # Model for cross-study synthesis
 # temperature = 0.0                  # LLM sampling temperature (omit to use provider default)
 
 [llm.api_keys]
@@ -208,7 +260,7 @@ chunk_max_tokens = 8000         # Max tokens per chunk for large PDFs
 
 [validation]
 auto_accept_threshold = 0.9     # Min confidence to auto-accept agreement
-always_validate_categories = ["primary_outcome"]  # Always run full 3-agent flow for these
+always_validate_questions = ["primary_outcome"]  # Always run full 3-agent flow for these
 ```
 
 ## Additional topics
@@ -238,7 +290,8 @@ output/
 │       ├── study_smith_2020_img1.png
 │       ├── study_smith_2020_img2.png
 │       └── study_jones_2021_img1.png
-└── results.json
+├── results.json
+└── synthesis.json          # (after running synthesize)
 ```
 
 ### Context file
@@ -367,7 +420,8 @@ articleq run -c CONFIG [--reparse]    Run the full pipeline (parse + extract)
 articleq parse -c CONFIG [--reparse]  Parse PDFs and save as markdown (no LLM calls)
 articleq rebuild -c CONFIG            Rebuild markdown and JSON from edited blocks
 articleq extract -c CONFIG            Run LLM extraction on pre-parsed papers
-articleq export RESULTS [--format csv|excel] [-o PATH]   Export to CSV/Excel
+articleq synthesize -c CONFIG         Synthesize findings across papers
+articleq export RESULTS [--format csv|excel] [-o PATH] [--type extraction|synthesis]   Export to CSV/Excel
 articleq eval RESULTS EXPECTED [-q QUESTIONS] [--judge-model MODEL] [-c CONFIG]   Evaluate against ground truth
 articleq visualize -r RESULTS [-o PATH] [-q QUESTIONS]   Generate HTML evidence viewer
 articleq visualize --parsed-dir DIR [-o PATH]            Preview parsed papers (no results)

{article_q-0.2.1 → article_q-0.2.2}/articleq.example.toml

@@ -4,6 +4,7 @@ papers_dir = "./papers"
 questions_file = "./questions.csv"
 output_dir = "./output"
 context_file = "./context.md"
+# synthesis_questions_file = "./synthesis_questions.csv"
 
 [parsing]
 backend = "pymupdf"  # or "marker"
@@ -12,6 +13,7 @@ backend = "pymupdf"  # or "marker"
 extraction_model = "openai:gpt-4o"
 validation_model = "openai:gpt-4o"
 consensus_model = "openai:gpt-4o"
+synthesis_model = "openai:gpt-4o"
 
 [llm.api_keys]
 openai = "${OPENAI_API_KEY}"
@@ -25,4 +27,4 @@ chunk_max_tokens = 8000
 
 [validation]
 auto_accept_threshold = 0.9
-always_validate_categories = ["primary_outcome"]
+always_validate_questions = ["primary_outcome"]

{article_q-0.2.1 → article_q-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "article-q"
-version = "0.2.1"
+version = "0.2.2"
 description = "Agent/LLM-enabled narrative reviews of academic manuscripts"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -44,5 +44,16 @@ docs = [
 [project.scripts]
 articleq = "articleq.cli:app"
 
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "benchmarks",
+    ".github",
+    "docs",
+    "overrides",
+    "mkdocs.yml",
+    "tests",
+    "uv.lock",
+]
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/articleq"]

{article_q-0.2.1 → article_q-0.2.2}/src/articleq/agents/consensus.py

@@ -101,6 +101,7 @@ async def resolve_consensus(
     context: str | None = None,
     model_settings: ModelSettings | None = None,
     usage: RunUsage | None = None,
+    force_consensus_ids: set[str] | None = None,
 ) -> ConsensusResult:
     """Run the full consensus workflow for a question.
 
@@ -111,7 +112,8 @@ async def resolve_consensus(
 
     agreed = _answers_agree(answer_a, answer_b, question)
 
-    if agreed and min(answer_a.confidence, answer_b.confidence) >= auto_accept_threshold:
+    force = force_consensus_ids and question.id in force_consensus_ids
+    if agreed and not force and min(answer_a.confidence, answer_b.confidence) >= auto_accept_threshold:
         return ConsensusResult(
             question_id=question.id,
             final_value=answer_a.value,

{article_q-0.2.1 → article_q-0.2.2}/src/articleq/agents/prompts.py

@@ -60,6 +60,44 @@ regardless of which agent provided it.
 """
 
 
+SYNTHESIS_SYSTEM_PROMPT = """\
+You are an experienced systematic review methodologist performing evidence \
+synthesis across multiple studies. Your task is to synthesize extracted data \
+from individual papers to answer a cross-study research question.
+
+Guidelines:
+- Cite specific studies by filename when making claims
+- Report counts, ranges, and proportions where appropriate (e.g. "3 of 5 studies \
+reported...", "sample sizes ranged from 50 to 500")
+- Note heterogeneity across studies when present
+- Flag limitations such as small sample sizes, inconsistent reporting, or missing data
+- Distinguish between what the evidence shows versus what it does not address
+- Organize your narrative logically with clear topic sentences
+- Provide bullet-point key findings that summarize the most important points
+- Rate your confidence based on the consistency, quality, and completeness of the \
+extracted data
+"""
+
+
+def build_synthesis_user_prompt(
+    question: str,
+    description: str,
+    extracted_data_table: str,
+) -> str:
+    """Build the user prompt for the synthesis agent.
+
+    Args:
+        question: The synthesis question text.
+        description: Additional guidance for the synthesis.
+        extracted_data_table: Markdown table of extracted data across papers.
+    """
+    parts = [f"## Synthesis Question\n{question}"]
+    if description:
+        parts.append(f"\n## Additional Guidance\n{description}")
+    parts.append(f"\n## Extracted Data\n{extracted_data_table}")
+    return "\n".join(parts)
+
+
 def _append_images(
     text: str,
     images: list[tuple[str, bytes]] | None,

article_q-0.2.2/src/articleq/agents/synthesis.py

@@ -0,0 +1,47 @@
+"""Synthesis agent for cross-study evidence synthesis."""
+
+from __future__ import annotations
+
+from pydantic_ai import Agent
+from pydantic_ai.settings import ModelSettings
+from pydantic_ai.usage import RunUsage, UsageLimits
+
+from articleq.agents.prompts import SYNTHESIS_SYSTEM_PROMPT, build_synthesis_user_prompt
+from articleq.models.synthesis import SynthesisResult
+
+synthesis_agent = Agent(
+    system_prompt=SYNTHESIS_SYSTEM_PROMPT,
+    output_type=SynthesisResult,
+    defer_model_check=True,
+)
+
+
+async def synthesize(
+    question_id: str,
+    question_text: str,
+    description: str,
+    extracted_data_table: str,
+    model: str,
+    context: str | None = None,
+    model_settings: ModelSettings | None = None,
+    usage: RunUsage | None = None,
+) -> SynthesisResult:
+    """Run the synthesis agent for a single synthesis question."""
+    user_prompt = build_synthesis_user_prompt(
+        question=question_text,
+        description=description,
+        extracted_data_table=extracted_data_table,
+    )
+
+    result = await synthesis_agent.run(
+        user_prompt,
+        model=model,
+        instructions=context,
+        model_settings=model_settings,
+        usage=usage,
+        usage_limits=UsageLimits(request_limit=None),
+    )
+
+    answer = result.output
+    answer.question_id = question_id
+    return answer

{article_q-0.2.1 → article_q-0.2.2}/src/articleq/cli.py

@@ -154,6 +154,53 @@ def extract(
     asyncio.run(run_extraction(cfg, papers))
 
 
+@app.command()
+def synthesize(
+    config: Annotated[
+        Path, typer.Option("--config", "-c", help="Path to config TOML file")
+    ] = Path("articleq.toml"),
+) -> None:
+    """Synthesize findings across papers from extraction results."""
+    from articleq.config import load_config
+    from articleq.output.json_output import load_results
+    from articleq.parsing.questions import load_synthesis_questions
+    from articleq.pipeline.synthesis import run_synthesis
+
+    if not config.exists():
+        console.print(f"[red]Config file not found: {config}[/red]")
+        console.print("Run 'articleq init' to create one.")
+        raise typer.Exit(1)
+
+    cfg = load_config(config)
+
+    if not cfg.project.synthesis_questions_file:
+        console.print("[red]No synthesis_questions_file set in config.[/red]")
+        console.print("Add 'synthesis_questions_file' to [project] in your config file.")
+        raise typer.Exit(1)
+
+    if not cfg.project.synthesis_questions_file.exists():
+        console.print(f"[red]Synthesis questions file not found: {cfg.project.synthesis_questions_file}[/red]")
+        raise typer.Exit(1)
+
+    results_path = cfg.project.output_dir / "results.json"
+    if not results_path.exists():
+        console.print(f"[red]Results file not found: {results_path}[/red]")
+        console.print("Run 'articleq extract' or 'articleq run' first.")
+        raise typer.Exit(1)
+
+    batch = load_results(results_path)
+    synthesis_questions = load_synthesis_questions(cfg.project.synthesis_questions_file)
+    console.print(f"Loaded {len(synthesis_questions)} synthesis questions")
+
+    synthesis_batch = asyncio.run(run_synthesis(cfg, batch, synthesis_questions))
+
+    # Write synthesis results
+    output_path = cfg.project.output_dir / "synthesis.json"
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(synthesis_batch.model_dump_json(indent=2))
+    console.print(f"[green]Synthesis results written to {output_path}[/green]")
+
+
 @app.command()
 def export(
     results_file: Annotated[Path, typer.Argument(help="Path to results JSON file")],
@@ -163,15 +210,24 @@ def export(
     output: Annotated[
         Optional[Path], typer.Option("--output", "-o", help="Output file path")
     ] = None,
+    type: Annotated[
+        str, typer.Option("--type", "-t", help="Result type: extraction or synthesis")
+    ] = "extraction",
 ) -> None:
     """Export results JSON to CSV or Excel."""
-    from articleq.output.tabular_output import export_results
-
     if not results_file.exists():
         console.print(f"[red]Results file not found: {results_file}[/red]")
         raise typer.Exit(1)
 
-    out_path = export_results(results_file, format=format, output_path=output)
+    if type == "synthesis":
+        from articleq.output.tabular_output import export_synthesis
+
+        out_path = export_synthesis(results_file, format=format, output_path=output)
+    else:
+        from articleq.output.tabular_output import export_results
+
+        out_path = export_results(results_file, format=format, output_path=output)
+
     console.print(f"[green]Exported to {out_path}[/green]")
 
 

{article_q-0.2.1 → article_q-0.2.2}/src/articleq/config.py

@@ -44,6 +44,8 @@ def _resolve_paths(config: AppConfig, config_dir: Path) -> None:
             setattr(project, attr, (config_dir / p).resolve())
     if project.context_file and not project.context_file.is_absolute():
         project.context_file = (config_dir / project.context_file).resolve()
+    if project.synthesis_questions_file and not project.synthesis_questions_file.is_absolute():
+        project.synthesis_questions_file = (config_dir / project.synthesis_questions_file).resolve()
 
 
 def load_config(path: Path) -> AppConfig:
@@ -72,6 +74,7 @@ def write_example_config(path: Path) -> None:
             "extraction_model": config.llm.extraction_model,
             "validation_model": config.llm.validation_model,
             "consensus_model": config.llm.consensus_model,
+            "synthesis_model": config.llm.synthesis_model,
             "api_keys": {
                 "openai": "${OPENAI_API_KEY}",
                 "google": "${GEMINI_API_KEY}",
@@ -85,7 +88,7 @@ def write_example_config(path: Path) -> None:
         },
         "validation": {
             "auto_accept_threshold": config.validation.auto_accept_threshold,
-            "always_validate_categories": config.validation.always_validate_categories,
+            "always_validate_questions": config.validation.always_validate_questions,
         },
     }
     with open(path, "wb") as f:
@@ -93,8 +96,9 @@ def write_example_config(path: Path) -> None:
     # Insert commented-out context_file after output_dir (tomli_w doesn't support comments)
     text = path.read_text()
     text = text.replace(
-        'output_dir = "./output"',
-        'output_dir = "./output"\n'
-        '# context_file = "./context.md"  # optional: additional instructions for the LLM',
+        'output_dir = "output"',
+        'output_dir = "output"\n'
+        '# context_file = "./context.md"  # optional: additional instructions for the LLM\n'
+        '# synthesis_questions_file = "./synthesis_questions.csv"  # optional: cross-study synthesis questions',
     )
     path.write_text(text)

{article_q-0.2.1 → article_q-0.2.2}/src/articleq/models/config.py

@@ -13,6 +13,7 @@ class ProjectConfig(BaseModel):
     questions_file: Path = Path("./questions.csv")
     output_dir: Path = Path("./output")
     context_file: Path | None = None
+    synthesis_questions_file: Path | None = None
 
 
 class ParsingConfig(BaseModel):
@@ -29,6 +30,7 @@ class LLMConfig(BaseModel):
     extraction_model: str = "openai:gpt-4o"
     validation_model: str = "openai:gpt-4o"
     consensus_model: str = "openai:gpt-4o"
+    synthesis_model: str = "openai:gpt-4o"
     temperature: float | None = None
     api_keys: ApiKeysConfig = Field(default_factory=ApiKeysConfig)
 
@@ -42,7 +44,7 @@ class PipelineConfig(BaseModel):
 
 class ValidationConfig(BaseModel):
     auto_accept_threshold: float = 0.9
-    always_validate_categories: list[str] = Field(default_factory=list)
+    always_validate_questions: list[str] = Field(default_factory=list)
 
 
 class AppConfig(BaseModel):

article_q-0.2.2/src/articleq/models/synthesis.py

@@ -0,0 +1,52 @@
+"""Models for cross-study synthesis results."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class SynthesisQuestion(BaseModel):
+    """A question for cross-study evidence synthesis."""
+
+    id: str
+    question: str
+    source_questions: list[str] = Field(default_factory=list)
+    description: str = ""
+
+
+class SourceReference(BaseModel):
+    """A reference to an extracted value from a specific paper."""
+
+    paper: str
+    question_id: str
+    value: str
+    confidence: float = Field(ge=0.0, le=1.0)
+
+
+class SynthesisResult(BaseModel):
+    """Result of synthesizing evidence across papers for a single question."""
+
+    question_id: str
+    narrative: str = Field(description="The main synthesis text")
+    key_findings: list[str] = Field(
+        default_factory=list, description="Bullet-point findings"
+    )
+    evidence_summary: list[SourceReference] = Field(
+        default_factory=list, description="Papers and values that contributed"
+    )
+    confidence: float = Field(
+        ge=0.0, le=1.0, description="Overall synthesis confidence"
+    )
+    reasoning: str = Field(default="", description="Reasoning behind the synthesis")
+
+
+class SynthesisBatch(BaseModel):
+    """Results from synthesizing across a batch of papers."""
+
+    project_name: str
+    results: list[SynthesisResult] = Field(default_factory=list)
+    papers_included: int = 0
+    started_at: datetime = Field(default_factory=datetime.now)
+    completed_at: datetime | None = None

{article_q-0.2.1 → article_q-0.2.2}/src/articleq/output/tabular_output.py

@@ -7,6 +7,7 @@ from pathlib import Path
 import pandas as pd
 
 from articleq.output.json_output import load_results
+from articleq.models.synthesis import SynthesisBatch
 
 
 def export_results(
@@ -53,3 +54,41 @@ def export_results(
         df.to_csv(output_path, index=False)
 
     return output_path
+
+
+def export_synthesis(
+    synthesis_path: Path,
+    format: str = "csv",
+    output_path: Path | None = None,
+) -> Path:
+    """Export synthesis results JSON to a tabular format (CSV or Excel)."""
+    synthesis_batch = SynthesisBatch.model_validate_json(synthesis_path.read_text())
+
+    rows: list[dict] = []
+    for result in synthesis_batch.results:
+        papers_cited = ", ".join(
+            sorted({ref.paper for ref in result.evidence_summary})
+        )
+        rows.append(
+            {
+                "question_id": result.question_id,
+                "narrative": result.narrative,
+                "key_findings": "; ".join(result.key_findings),
+                "papers_cited": papers_cited,
+                "confidence": result.confidence,
+            }
+        )
+
+    df = pd.DataFrame(rows)
+
+    if output_path is None:
+        stem = synthesis_path.stem
+        suffix = ".xlsx" if format == "excel" else ".csv"
+        output_path = synthesis_path.parent / f"{stem}{suffix}"
+
+    if format == "excel":
+        df.to_excel(output_path, index=False)
+    else:
+        df.to_csv(output_path, index=False)
+
+    return output_path