Metadata-Version: 2.4
Name: paperwrite-ai
Version: 0.1.0
Summary: Multi-Agent Academic Paper Writing System powered by LLMs
Author-email: Welkinchan11 <1533582957@qq.com>
License: MIT
Project-URL: Homepage, https://github.com/Welkinchan11/paperwrite-ai
Project-URL: Repository, https://github.com/Welkinchan11/paperwrite-ai
Project-URL: Bug Tracker, https://github.com/Welkinchan11/paperwrite-ai/issues
Keywords: academic-writing,multi-agent,llm,paper-generation,latex,rag,ai-agents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Classifier: Framework :: FastAPI
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.30.0
Requires-Dist: websockets>=12.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: pydantic-settings>=2.5.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: litellm>=1.48.0
Requires-Dist: langchain>=0.3.0
Requires-Dist: langchain-community>=0.3.0
Requires-Dist: langchain-chroma>=0.2.0
Requires-Dist: chromadb>=0.5.0
Requires-Dist: sentence-transformers>=3.0.0
Requires-Dist: matplotlib>=3.9.0
Requires-Dist: graphviz>=0.20.3
Requires-Dist: Pillow>=10.4.0
Requires-Dist: tavily-python>=0.5.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: jinja2>=3.1.4
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: aiosqlite>=0.20.0
Dynamic: license-file

# PaperWrite AI - Multi-Agent Academic Paper Writing System

A multi-agent system that generates publication-ready academic papers from a research topic and outline. Specialized AI agents collaborate through a DAG-based pipeline to research, write, review, and compile LaTeX papers.

## Architecture

```
                    +-------------------+
                    |   Web Frontend    |  (Next.js + React)
                    |  localhost:3000   |
                    +--------+----------+
                             | REST + WebSocket
                    +--------v----------+
                    |   FastAPI Backend  |  (Python, localhost:8000)
                    +--------+----------+
                             |
              +--------------+--------------+
              |                             |
     +--------v--------+          +--------v--------+
     |   Orchestrator   |          |   Memory System  |
     | TaskGraph (DAG)  |          | Short-term: JSON |
     | Event Bus        |          | Long-term: SQLite|
     | Dispatcher       |          +-----------------+
     +--------+---------+
              |
   +----------+----------+----------+----------+
   |          |          |          |          |
+--v--+  +---v---+  +---v---+  +---v---+  +--v--+
|Task |  |Know-  |  |Method |  |Experi-|  |Writ-|
|Dist.|  |ledge  |  |Constr.|  |ment   |  |er   |
|Agent|  |Search |  |Agent  |  |Agent  |  |Agent|
+-----+  +-------+  +-------+  +-------+  +-----+
              |
         +----v----+
         | ChromaDB |  (RAG - Vector Store)
         +---------+

   +----------+----------+----------+
   |          |          |          |
+--v--+  +---v---+  +---v---+  +--v------+
|Rev- |  |Image  |  |Table  |  |Reference|
|iewer|  |Constr.|  |Constr.|  |Agent    |
|Agent|  |Agent  |  |Agent  |  +---------+
+-----+  +-------+  +-------+
```

## Agents

| Agent | Responsibility | Self-Review |
|-------|---------------|-------------|
| **Task Distribution** | Decomposes topic into a detailed per-section writing plan | - |
| **Knowledge Search** | Web search + RAG indexing into ChromaDB | - |
| **Method Construction** | Proposes novel research method | Logic, soundness, novelty, completeness |
| **Experiment Construction** | Designs experiments with [PLACEHOLDER] data | Reproducibility, metrics, baselines |
| **Writer** | Produces LaTeX sections, handles revisions, final compilation | - |
| **Reviewer** | 3-persona voting (pass if 2/3 score >= 4) | Writing, method, feasibility, reproducibility |
| **Image Constructor** | Flowcharts (Graphviz) + charts (Matplotlib) | Text, fonts, formatting |
| **Table Constructor** | LaTeX tables with booktabs | - |
| **Reference** | BibTeX generation + existence verification | Format, completeness, duplicates |

## Pipeline Flow

```
1. User Input -> Task Distribution Agent (creates writing plan)
2. Knowledge Search Agent (web search -> ChromaDB indexing)
3. Method Construction Agent (proposes method with self-review)
4. Experiment Construction Agent (designs experiments with self-review)
5. Writer Agent (produces LaTeX sections)
6. Image + Table Constructor Agents (figures and tables)
7. Reviewer Agent (3 reviewers vote, revision loop if needed)
8. Reference Agent (BibTeX generation + verification)
9. Writer Agent (final assembly + LaTeX compilation -> PDF)
```

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Frontend | Next.js 14 (App Router), React, TypeScript, Tailwind CSS |
| Backend | Python, FastAPI, asyncio |
| LLM | LiteLLM (supports GPT-4, Claude, Gemini, DeepSeek) |
| RAG | ChromaDB + LangChain + sentence-transformers |
| Memory | SQLite (long-term) + JSON files (short-term) |
| Figures | Matplotlib (charts) + Graphviz (diagrams) |
| LaTeX | pdflatex / latexmk (IEEE conference template) |
| Real-time | WebSocket (FastAPI -> React) |
| State | Zustand (frontend store) |

## Prerequisites

- Python 3.10+
- Node.js 18+
- pdflatex (texlive): `sudo apt-get install texlive-full` or `brew install --cask mactex`
- Graphviz: `sudo apt-get install graphviz` or `brew install graphviz`
- At least one LLM API key (OpenAI, Anthropic, Google, or DeepSeek)
- Tavily API key (for web search, optional but recommended)

## Quick Start

### 1. Clone and Setup

```bash
cd paperWrite
chmod +x setup.sh
./setup.sh
```

### 2. Configure API Keys

Edit `.env` with your API keys:

```env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AI...
DEEPSEEK_API_KEY=sk-...
TAVILY_API_KEY=tvly-...
DEFAULT_MODEL=gpt-4o
```

### 3. Start Backend

```bash
cd backend
source venv/bin/activate
uvicorn main:app --reload --port 8000
```

### 4. Start Frontend

```bash
cd frontend
npm run dev
```

### 5. Open the UI

Navigate to **http://localhost:3000**

## Usage

1. Click **"New Project"**
2. Enter your research topic (e.g., "LLM-Based Fuzzing for PLC Compilers")
3. Configure the outline (pre-filled with standard sections, editable)
4. Select template (IEEE Conference, ACM, etc.) and page count
5. Enter API keys for the LLM providers you want to use
6. Click **"Create Project"** then **"Start Pipeline"**
7. Monitor real-time progress via the dashboard (WebSocket updates)
8. Download the compiled PDF when complete

## Project Structure

```
paperWrite/
├── backend/
│   ├── main.py              # FastAPI entry point
│   ├── config.py             # Settings (pydantic-settings)
│   ├── database.py           # SQLite schema + async connection
│   ├── api/
│   │   ├── projects.py       # Project CRUD + pipeline start
│   │   ├── papers.py         # PDF download, LaTeX source
│   │   └── websocket.py      # Real-time event streaming
│   ├── agents/
│   │   ├── base.py           # BaseAgent (LLM, memory, self-review)
│   │   ├── task_distribution.py
│   │   ├── knowledge_search.py
│   │   ├── method_construction.py
│   │   ├── experiment_construction.py
│   │   ├── reviewer.py       # 3-persona voting system
│   │   ├── writer.py         # LaTeX generation + revision
│   │   ├── image_constructor.py
│   │   ├── table_constructor.py
│   │   └── reference.py
│   ├── orchestrator/
│   │   ├── task_graph.py     # DAG-based task management
│   │   ├── dispatcher.py     # Concurrent task execution
│   │   ├── pipeline.py       # End-to-end pipeline controller
│   │   └── events.py         # Async pub/sub event bus
│   ├── memory/
│   │   ├── short_term.py     # JSON conversation context
│   │   ├── long_term.py      # SQLite persistent memory
│   │   └── manager.py        # Unified memory interface
│   ├── rag/
│   │   ├── indexer.py        # ChromaDB document indexing
│   │   ├── retriever.py      # Semantic retrieval
│   │   └── embeddings.py     # sentence-transformers config
│   ├── tools/
│   │   ├── llm_client.py     # LiteLLM wrapper (multi-provider)
│   │   ├── web_search.py     # Tavily web search
│   │   ├── latex_compiler.py # pdflatex compilation pipeline
│   │   ├── matplotlib_gen.py # Chart generation
│   │   └── graphviz_gen.py   # Diagram generation
│   ├── templates/
│   │   └── ieee_conference/  # LaTeX template + Jinja2
│   └── storage/              # Runtime data (gitignored)
├── frontend/
│   ├── src/
│   │   ├── app/              # Next.js App Router pages
│   │   ├── components/       # React components
│   │   ├── hooks/            # Custom hooks (WebSocket)
│   │   ├── lib/              # API client, types, store
│   │   └── styles/           # Tailwind + custom CSS
│   └── package.json
├── .env.example
├── setup.sh
└── README.md
```

## Key Design Decisions

### Multi-LLM via LiteLLM
All LLM calls go through a single `LLMClient` wrapper backed by LiteLLM. Supports GPT-4, Claude, Gemini, DeepSeek with automatic routing. Users can assign different models to different agents.

### DAG-Based Task Graph
Tasks are organized in a directed acyclic graph with dependencies. The dispatcher executes ready tasks concurrently (up to 5 parallel) using asyncio semaphores. Failed tasks retry up to 3 times.

### 3-Persona Reviewer Voting
Three independent reviewer personas (writing quality, method logic, feasibility) each score 1-5 on four criteria. Pass requires >50% (2/3) to give overall >= 4.0. Failed reviews trigger revision cycles (max 3).

### Self-Review Loops
Method, Experiment, Image, and Reference agents self-review their output against predefined criteria. Each agent iterates up to 3 times: generate -> review -> revise -> re-review.

### RAG with ChromaDB
Web search results are chunked (1000 chars, 200 overlap) and indexed into ChromaDB using sentence-transformers embeddings. Agents retrieve relevant context when writing sections.

### Per-Agent Memory
- **Short-term**: JSON files storing conversation context per agent per session
- **Long-term**: SQLite storing persistent knowledge, task history, and feedback

### Real-time UI
WebSocket connection streams agent status, logs, task progress, and review results from backend to frontend in real-time. Zustand store manages client-side state.

## Supported LLM Providers

| Provider | Model Examples | API Key Variable |
|----------|---------------|-----------------|
| OpenAI | gpt-4o, gpt-4-turbo | OPENAI_API_KEY |
| Anthropic | claude-sonnet-4-20250514, claude-opus-4-20250514 | ANTHROPIC_API_KEY |
| Google | gemini-pro, gemini-1.5-pro | GOOGLE_API_KEY |
| DeepSeek | deepseek-chat, deepseek-coder | DEEPSEEK_API_KEY |

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | /api/health | Health check |
| POST | /api/projects | Create new project |
| GET | /api/projects | List all projects |
| GET | /api/projects/{id} | Get project details |
| POST | /api/projects/{id}/start | Start pipeline |
| DELETE | /api/projects/{id} | Delete project |
| GET | /api/projects/{id}/pdf | Download PDF |
| GET | /api/projects/{id}/latex | Get LaTeX source |
| POST | /api/projects/{id}/compile | Recompile |
| WS | /ws/{id} | Real-time events |

## Database Schema

SQLite tables: `projects`, `tasks`, `task_dependencies`, `agent_knowledge`, `reviews`, `agent_logs`

## License

MIT
