literature-reader

name	literature-reader
description	Literature deep-reading and deconstruction module. Invokes Gemini multimodal capabilities to deep-read PDF papers, outputs structured Markdown reports, then parses them into JSON for downstream Matrix Engine consumption. User-triggered.
metadata	{"version":"1.0.0","last_updated":"2026-05-29","status":"active"}

⚠️ Mandatory Pre-Execution Loading

Before starting execution, you must first read the following files:

1. Read agents/deep_reader_agent.md — Deep-reading execution agent definition
2. Read agents/paper_cruncher_agent.md — Paper deconstruction agent definition

If any file is not loaded, execution must not begin.

---

⚠️ Prerequisites

This module depends on the PaperReader MCP server. Before use, confirm:

1. MCP server is registered with Claude Code (check if .mcp.json contains paper-reader-cars)
2. Python dependencies are installed: pip install google-genai mcp
3. API Key is configured: cars/config/api_keys.json contains google_ai_studio
4. Network proxy is configured: cars/config/network_config.json

If MCP tools are unavailable, this module cannot execute.

---

Literature Deep-Reading and Deconstruction Module

Batch deep-read PDF papers into structured data for downstream Matrix Engine to generate research matrices.

Core Positioning: This module does not search literature, judge relevance, or engage in Socratic dialogue with users. It does one thing only — convert PDFs into structured JSON.

---

Trigger Conditions

Trigger Method

User-initiated trigger. This module does not run automatically.

Trigger Keywords

• "精读文献" / "读论文" / "解构论文"
• "帮我读 pdfs" / "处理文献"
• "read papers" / "process pdfs"

Pre-Execution Check (Iron Rule)

After triggering, must first check:

Are there .pdf files under workspaces/ProjectX/literature/pdfs/?
(Exclude files in the processed/ subdirectory)

YES → Continue execution
NO  → Inform user "No PDF files to process under pdfs/", terminate

Non-Trigger Scenarios

Scenario	Use Instead
User wants to search for papers	Literature Scout module
User wants to ask questions about a specific paper	Future interactive Q&A feature (not yet implemented)
User wants to generate research matrix	Matrix Engine module

---

Agent Team (2 agents)

#	Agent	Role	Execution Order
1	deep_reader_agent	Invokes MCP tool to deep-read PDF → outputs .md	Execute first
2	paper_cruncher_agent	Parses .md → outputs structured .json	Execute second

---

Orchestration Flow

User triggers "read papers"
     |
=== Pre-Check ===
     |
     +-> Check if there are .pdf files under literature/pdfs/
     |   - Yes → Continue
     |   - No → Inform user, terminate
     |
=== Phase 1: Deep Reading ===
     |
     +-> [deep_reader_agent]
     |   - Invoke MCP tool: deep_read_pdfs(input_dir, output_dir)
     |   - input_dir = workspaces/ProjectX/literature/pdfs/
     |   - output_dir = workspaces/ProjectX/literature/readings/
     |   - Tool internally: deep-read PDF → output .md → move PDF to processed/
     |   - Return execution result (success/failure count)
     |
     +-> Check result
     |   - successful > 0 → Continue to Phase 2
     |   - successful == 0 → Inform user all failed, terminate
     |
=== Phase 2: Deconstruction ===
     |
     +-> [paper_cruncher_agent]
     |   - Read literature/readings/*.md (exclude summary)
     |   - Parse structured content (4 dimensions)
     |   - Output JSON to hypotheses/translated/<paper_name>.json
     |   - Skip if JSON with same name already exists (idempotent)
     |
=== Complete ===
     |
     +-> Report to user:
         - "Deep-read N papers"
         - "Structured JSON output to hypotheses/translated/"
         - "Original deep-reading reports retained in literature/readings/"
         - If failures occurred, list failed file names and reasons

---

Data Flow

literature/pdfs/*.pdf
    ↓ [deep_reader_agent → cruncher.py MCP tool]
literature/readings/*.md (permanently retained)
literature/pdfs/processed/ (processed PDF archive)
    ↓ [paper_cruncher_agent]
hypotheses/translated/*.json (structured output)
    ↓
[downstream] Matrix Engine module

---

Output Directory Structure

workspaces/ProjectX/
├── literature/
│   ├── pdfs/
│   │   ├── processed/          ← Deep-read PDFs archived here
│   │   └── (PDFs to be processed)
│   └── readings/
│       ├── 2506.01334.md       ← Individual deep-reading report (permanently retained)
│       ├── 2301.12345.md
│       └── deep_reading_summary.md  ← Summary report
└── hypotheses/
    └── translated/
        ├── 2506.01334.json     ← Structured JSON (for Matrix Engine)
        └── 2301.12345.json

---

Iron Rules

1. Must not execute when pdfs/ is empty — Must check first
2. Phase 1 must complete before Phase 2 — paper_cruncher_agent must not execute before deep_reader_agent completes
3. readings/*.md must not be deleted — They are the original records of Gemini deep-reading, permanently retained
4. Do not overwrite existing JSON with same name — Idempotency guarantee
5. Single failure does not interrupt overall process — Whether deep-reading or parsing, single failure only logs error, continues processing others

---

Failure Paths

Failure Scenario	Trigger Condition	Recovery Strategy
pdfs/ is empty	No files to process	Inform user, terminate
MCP tool unavailable	cruncher.py not registered	Inform user to check MCP configuration
Gemini API failure	Network/quota/Key issues	Log error, skip that paper, continue
PDF corrupted	Cloud parsing failure	Log error, skip that paper, continue
.md format abnormal	Gemini output does not match expected structure	paper_cruncher_agent fills empty fields, does not interrupt
All PDFs failed	All deep-readings failed	Inform user, do not enter Phase 2

---

Agent File References

Agent	Definition File
deep_reader_agent	agents/deep_reader_agent.md
paper_cruncher_agent	agents/paper_cruncher_agent.md

---

MCP Tool Dependencies

Tool	File	Purpose
deep_read_pdfs(input_dir, output_dir)	tools/cruncher.py	Batch deep-read PDFs

---

Quality Standards

1. Pre-check must be executed — Must not blindly invoke tools when no PDFs exist
2. Execution order cannot be reversed — deep_reader_agent before paper_cruncher_agent
3. Results must be reported to user — Success count, failure count, output paths
4. Idempotency — Multiple runs do not reprocess papers already in processed/ or with existing JSON

---

Output Language

Academic content in deep-reading reports and JSON uses English (consistent with Gemini prompt). User interaction uses the user's language.