Academic Review Simulator v2.0

A modern web application that simulates the academic peer review process using AI. Built with FastAPI backend and React frontend, powered by EDSL (Expected Parrot Data Science Library).

Features

• AI-Powered Reviews: Generate realistic referee reports using multiple AI models
• Complete Review Process: Includes referee reports, author responses, and referee rebuttals
• Modern Architecture: FastAPI backend with React frontend
• EDSL Integration: Seamless authentication with Expected Parrot
• Real-time Progress: Live updates during the review generation process
• Secure File Upload: Support for PDF papers up to 16MB
• Download Results: Complete review packages as ZIP files

Architecture

Backend (FastAPI)

• FastAPI: Modern, fast web framework for Python APIs
• SQLAlchemy: Database ORM with SQLite/PostgreSQL support
• JWT Authentication: Secure user authentication
• EDSL Integration: AI-powered academic review generation
• File Upload: Secure PDF handling with validation

Frontend (React)

• React 18: Modern React with hooks and context
• Material-UI: Professional, responsive UI components
• React Router: Client-side routing
• Axios: HTTP client for API communication
• Dark Theme: Academic-focused dark theme

Prerequisites

• Python 3.11+
• Node.js 18+
• EDSL API Key from Expected Parrot

Quick Start

1. Install Dependencies

Backend:

# Python dependencies are already installed via uv/pip

Frontend:

cd frontend
npm install

2. Environment Setup

Create a .env file in the root directory:

# Database (optional, defaults to SQLite)
DATABASE_URL=sqlite:///./academic_review.db

# JWT Secret (change in production)
SECRET_KEY=your-secret-key-change-in-production

# Session secret (optional)
SESSION_SECRET=your-session-secret

3. Start the Application

Option 1: Start Both Services

Backend (Terminal 1):

python start_backend.py

Frontend (Terminal 2):

chmod +x start_frontend.sh
./start_frontend.sh

Option 2: Individual Services

Backend only:

cd backend
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Frontend only:

cd frontend
npm run dev

4. Access the Application

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs

Usage

1. Create Account

• Visit http://localhost:3000
• Click "Get Started" or "Login"
• Register with username, email, and password
• Optionally add your EDSL API key during registration

2. EDSL Authentication

• After logging in, navigate to "EDSL Settings" in the user menu
• Enter your Expected Parrot API key
• The system will validate your key and enable AI processing

3. Upload Paper

• Click "Upload Paper" in the navigation
• Provide a title for your paper
• Upload a PDF file (max 16MB)
• Click "Start Review Process"

4. Review Process

• Monitor real-time progress through three stages:
  1. Referee Reports (1-2 minutes)
  2. Author Response (1-2 minutes)
  3. Referee Rebuttals (1 minute)

5. View Results

• Once completed, view the comprehensive review package
• Download all results as a ZIP file
• Access individual sections (reports, responses, rebuttals)

API Endpoints

Authentication

• POST /api/auth/register - User registration
• POST /api/auth/login - User login
• GET /api/auth/me - Get current user info
• POST /api/edsl/authenticate - EDSL API key validation

Paper Processing

• POST /api/papers/upload - Upload academic paper
• POST /api/reviews/{id}/start - Start review process
• GET /api/reviews/{id}/status - Get review status
• GET /api/reviews/{id} - Get review results
• GET /api/reviews/{id}/download - Download results ZIP
• GET /api/reviews - List user sessions

Database Models

User

• id, username, email
• password_hash, edsl_api_key
• created_at

ReviewSession

• id, title, paper_filename, paper_path
• status, processing_stage
• referee_reports, author_response, referee_rebuttals
• created_at, completed_at
• user_id (foreign key)

EDSL Integration

The application uses EDSL to create AI agents that simulate:

1. Three Referee Agents:

   • Dr. Sarah Mitchell (Econometrics, Stanford)
   • Prof. James Thompson (Macroeconomics, MIT)
   • Dr. Elena Rodriguez (Development Economics, UC Berkeley)

2. Author Agent: Responds to referee concerns professionally

3. Review Process:

   • Comprehensive referee reports with methodology assessment
   • Professional author responses addressing all concerns
   • Referee rebuttals evaluating author responses

Configuration

Environment Variables

• DATABASE_URL: Database connection string
• SECRET_KEY: JWT token secret key
• SESSION_SECRET: Session encryption key
• EXPECTED_PARROT_API_KEY: Global EDSL API key (optional)

File Uploads

• Maximum file size: 16MB
• Supported formats: PDF only
• Storage: Local filesystem (uploads directory)

Development

Project Structure

academic-review-simulator/
├── backend/
│   ├── main.py              # FastAPI application
│   ├── models.py            # Database models
│   ├── schemas.py           # Pydantic schemas
│   ├── auth.py              # Authentication logic
│   ├── database.py          # Database configuration
│   └── edsl_service.py      # EDSL integration
├── frontend/
│   ├── src/
│   │   ├── components/      # React components
│   │   ├── pages/           # Page components
│   │   ├── contexts/        # React contexts
│   │   └── services/        # API services
│   ├── package.json
│   └── vite.config.js
├── uploads/                 # File storage
└── start_backend.py         # Backend startup script

Adding Features

1. Backend: Add new endpoints in main.py, models in models.py
2. Frontend: Create components in src/components/, pages in src/pages/
3. EDSL: Modify agents and questions in edsl_service.py

Deployment

Production Considerations

1. Database: Use PostgreSQL instead of SQLite
2. Security: Change default secret keys
3. File Storage: Consider cloud storage for uploads
4. HTTPS: Enable SSL/TLS in production
5. Environment: Use production WSGI server

Docker Deployment (Optional)

Create Dockerfile for backend and frontend, use docker-compose for orchestration.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Check the Expected Parrot documentation
• Review EDSL examples and tutorials
• Submit issues on GitHub

---

Academic Review Simulator v2.0 - Transforming academic peer review through AI simulation.