🏛️ FWMA — Full-Workflow Multi-Agent Literature Review

AI Parliament-driven end-to-end systematic literature review automation.

FWMA automates systematic literature review end-to-end, using an AI Parliament — a structured multi-agent debate — to evaluate papers with transparent, auditable justifications.

(Pronounced "Foo-mah" /fú mǎ/)

Flesh is Weak, Machine Ascension. Go to sleep. Let FWMA read 100+ papers overnight and hand you a fully structured, comprehensive research report by morning.

Will FWMA replace researchers?

No. FWMA is designed to be a tireless research assistant. It helps researchers conduct literature reviews much more comprehensively and rapidly, handling the heavy lifting of reading and screening so you can focus on actual scientific innovation.

Skip Reading This — It's the Age of AI

Just paste this into any LLM or agent and let it explain + set you up:

Read this README and the linked docs to understand what FWMA does and how to
set it up. Then help me configure API keys and run my first literature review:
https://raw.githubusercontent.com/JinchengGao-Infty/FWMA/refs/heads/main/README.md

Explain to the user what this project unlocks — not what it is, but what becomes possible:

Every researcher can now run a full systematic literature review — from search to scored report — in minutes instead of weeks. FWMA crawls OpenAlex, arXiv, and OpenReview, screens papers with AI, downloads PDFs, then runs an AI Parliament (Chair + 2 expert Members) that debates each paper across multiple rounds before scoring it 0-5. The final output is a structured research report.

It's not just another paper summarizer. The AI Parliament pattern means every verdict comes with a transparent debate log — you can see exactly why a paper scored 4/5, what the engineering expert praised, and what the theory expert criticized. This is auditable AI-assisted research.

Setup:

1. git clone https://github.com/JinchengGao-Infty/FWMA.git && cd FWMA && pip install -e . (or pip install -e '.[mcp]' for MCP support)
2. Set API keys: export GEMINI_API_KEY=... ANTHROPIC_API_KEY=... OPENAI_API_KEY=...
3. Or configure ~/.config/fwma/config.toml with custom endpoints and models
4. Test it: fwma suggest "your research topic"
5. Run it: fwma run research.toml

MCP: Add "fwma": {"command": "fwma-mcp"} to your Claude Desktop config. 14 tools available — AI agents can run entire literature reviews autonomously.

Docs: See Architecture for system design, MCP Integration for agent setup.

Features

• Multi-source crawling — OpenAlex, arXiv, OpenReview with unified format and deduplication
• AI screening — LLM-powered relevance filtering (high / medium / low)
• PDF download — Multi-strategy fallback (direct → Unpaywall → DOI → browser)
• AI Parliament review — Chair + 2 Members structured debate, multi-round voting, scored verdicts (0-5)
• Report generation — Synthesize all reviews into Markdown/JSON research reports
• Writing review — Multi-agent feedback on your own manuscripts
• PDF vision extraction — Tables, figures, formulas via vision models
• Citation checking — Verify citation reasonability in LaTeX manuscripts
• Retry & rate limiting — Exponential backoff with automatic retry on 429/500/timeout
• Resume support — Every pipeline step is resumable from where it left off

Quick Start

git clone https://github.com/JinchengGao-Infty/FWMA.git
cd FWMA
pip install -e .

# Set API keys (supports any OpenAI-compatible endpoint)
export GEMINI_API_KEY=your-key
export ANTHROPIC_API_KEY=your-key
export OPENAI_API_KEY=your-key

# Let AI suggest a search strategy
fwma suggest "transformer applications in seismology"

# Run the full pipeline
fwma run research.toml

AI Parliament

The core innovation. Three AI models debate each paper:

┌─────────────────────────────────────────┐
│              🏛️ AI Parliament            │
│                                         │
│  👨‍⚖️ Chair (Gemini 3.1 Pro)              │
│  Opens debate, summarizes, final score  │
│                                         │
│  🔧 Member 1 (Claude Opus 4.6)          │
│  Engineering: architecture, efficiency, │
│  reproducibility, deployment            │
│                                         │
│  📐 Member 2 (GPT-5.2)                  │
│  Theory: math rigor, novelty,           │
│  methodology, generalization            │
│                                         │
│  Flow: Chair opens → M1 argues →        │
│  M2 responds → Chair summarizes →       │
│  ... (up to 5 rounds) → Vote → Score    │
└─────────────────────────────────────────┘

Each review produces:

• Score (0-5) with recommendation
• Debate log — full transcript of the multi-agent discussion
• Key points and application ideas

MCP Integration (for AI Agents)

FWMA works as an MCP server, letting AI agents (Claude, Cursor, etc.) run literature reviews autonomously.

git clone https://github.com/JinchengGao-Infty/FWMA.git
cd FWMA
pip install -e '.[mcp]'

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "fwma": {
      "command": "fwma-mcp"
    }
  }
}

MCP Tools

Long-running tools (download, review, report, writing_review) return a job_id immediately. Poll with job_status until status becomes succeeded or failed.

CLI Reference

fwma suggest <requirement>          # AI search strategy suggestion
fwma run <config.toml>              # Full pipeline from config
fwma crawl <config.toml>            # Crawl papers
fwma screen --run-dir <dir>         # AI screening
fwma download --run-dir <dir>       # Download PDFs
fwma review --run-dir <dir>         # AI Parliament review
fwma report --run-dir <dir>         # Generate report
fwma writing-review <pdf>           # Manuscript writing review
fwma tools pdf-vision <pdf>         # PDF visual extraction
fwma tools citation-check <tex>     # Citation checking
fwma mcp                            # Start MCP server

Architecture

┌─────────────────────────────────────────────┐
│              User / AI Agent                │
├──────────────────┬──────────────────────────┤
│    CLI (typer)   │   MCP Server (fastmcp)   │  ← Thin adapters
├──────────────────┴──────────────────────────┤
│              Core Library                    │
│  ┌─────────┐ ┌──────────┐ ┌──────────────┐ │
│  │Crawlers │ │Screening │ │  Parliament   │ │
│  │OpenAlex │ │   AI     │ │ Chair + 2    │ │
│  │arXiv    │ │ filtering│ │ Members      │ │
│  │OpenRev. │ │          │ │ Multi-round  │ │
│  └─────────┘ └──────────┘ └──────────────┘ │
│  ┌─────────┐ ┌──────────┐ ┌──────────────┐ │
│  │Download │ │  Report  │ │  LLM Client  │ │
│  │Multi-   │ │  MD/JSON │ │ Claude/Gemini│ │
│  │strategy │ │ synthesis│ │ GPT/OpenAI   │ │
│  └─────────┘ └──────────┘ └──────────────┘ │
│  ┌──────────────────────────────────────┐   │
│  │  Tools: pdf-vision, citation-check  │   │
│  └──────────────────────────────────────┘   │
├─────────────────────────────────────────────┤
│         Data Layer (JSON + PDF files)       │
│         runs/<run_id>/crawl/screen/...      │
└─────────────────────────────────────────────┘

Pipeline Flow

suggest → crawl → screen → download → review → report
   │         │        │         │         │        │
   │    OpenAlex   AI filter  Multi-   Parliament  Markdown
   │    arXiv     high/med   strategy  debate     /JSON
   │    OpenRev.  /low       fallback  (5 rounds)
   │
   └─ AI generates search config from natural language

Each step is resumable — if interrupted, re-running picks up where it left off.

Configuration

Default Models

API Keys (.env or environment variables)

GEMINI_API_KEY=your-gemini-key
ANTHROPIC_API_KEY=your-anthropic-key
OPENAI_API_KEY=your-openai-key

# Custom API endpoints (optional, for self-hosted or enterprise deployments)
# GEMINI_BASE_URL=https://generativelanguage.googleapis.com
# ANTHROPIC_BASE_URL=https://api.anthropic.com
# OPENAI_BASE_URL=https://api.openai.com/v1

Global defaults (~/.config/fwma/config.toml)

[models]
screener = "openai/gpt-5.2"
chair = "gemini/gemini-3.1-pro-low"
member1 = "anthropic/claude-opus-4-6"
member2 = "openai/gpt-5.2"
report = "gemini/gemini-3.1-pro-high"

[defaults]
language = "zh"
openalex_mailto = "you@example.com"

Research config (research.toml)

[research]
name = "my-research"
requirement = "Find recent papers on transformer applications in seismology"

[[sources]]
type = "openalex"
keywords = ["transformer", "seismology"]
year_from = 2022
limit = 200

[[sources]]
type = "arxiv"
categories = ["physics.geo-ph", "cs.LG"]
keywords = ["seismic", "deep learning"]
limit = 100

Supported LLM Providers

• Google Gemini (native API)
• Anthropic Claude (native API)
• OpenAI GPT (native API)
• Any OpenAI-compatible endpoint (Ollama, vLLM, etc.)

Model format: provider/model-name (e.g., anthropic/claude-opus-4-6, gemini/gemini-3-flash)

Why FWMA?

Contributing

Contributions welcome! Please open an issue first to discuss what you'd like to change.

License

Apache-2.0