gformify

Turn your PDFs into Google Forms, instantly.

gformify is a personal project born out of a desire to help friends save time. It automates the tedious process of manually converting PDF exams and quizzes into interactive Google Forms.

Whether you're a teacher, a student organizing study groups, or just someone who needs to digitize a quiz, this tool handles the heavy lifting so you can focus on what matters.

Key Features

• OCR Support: Extracts text from scanned PDFs and images using Tesseract.
• Automated Parsing: Intelligently identifies questions, multiple-choice options, and logic.
• Quiz Mode: Automatically marks correct answers and adds feedback/explanations for grading.
• Bulk Processing: Handles dozens of questions in seconds.
• Modular Design: Use it as a CLI tool, a Python library, or a REST API.

Getting Started

Prerequisites

• Python 3.13+
• uv (for dependency management) or pip
• Tesseract OCR installed on your system (brew install tesseract on macOS)
• Google Cloud Project with Forms API and Drive API enabled.

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/gformify.git
   cd gformify

2. Install dependencies:

   uv sync
   # Or with pip: pip install -r requirements.txt

3. Setup Google Cloud Credentials:

   • Create a project in Google Cloud Console.
   • Enable Google Forms API and Google Drive API.
   • Create an OAuth 2.0 Client ID (Desktop App).
   • Download the JSON file and save it as .secrets/client_secret_...json (update .env or pass path).

Usage

1. Command Line Interface (CLI)

Run the full pipeline to convert a PDF directly to a Google Form:

uv run -m src.cli data/input/mock_exam.pdf --title "My Quiz Title"

2. REST API Service

Start the local API server to upload PDFs programmatically:

1. Install API dependencies:

   uv add fastapi uvicorn python-multipart

2. Start the server:

   uv run uvicorn src.api.main:app --reload

3. Open API Docs: Go to http://127.0.0.1:8000/docs to test the endpoint.

   Error Responses:

   • 400 Bad Request: Corrupt or unreadable PDF.
   • 422 Unprocessable Entity: Valid PDF but zero questions found.
   • 502 Bad Gateway: Output integration failed (e.g., Google Forms API).
   • 503 Service Unavailable: AI Processing failed (e.g., Rate limit, Content Safety).

3. Python Library

You can import the core modules in your own scripts:

from src.core.extractor import PDFExtractor
from src.core.parser import QuizParser

extractor = PDFExtractor()
raw_text = extractor.extract_content("exam.pdf")

parser = QuizParser()
quiz_data = parser.parse_text(raw_text)
print(quiz_data)

Project Structure

src/
├── core/                  # Pure Logic (No CLI/API dependencies)
│   ├── extractor.py       # PDF & OCR Handling
│   ├── parser.py          # Regex Parsing Logic
│   └── cleaner.py         # AI Cleaning Logic
│
├── adapters/              # External Integrations
│   └── google_forms.py    # Google Forms API Wrapper
│
├── api/                   # Web Service
│   └── main.py            # FastAPI Application
│
└── cli.py                 # Command Line Interface (Entry Point)

Contributing

Contributions are welcome! This is a community-driven tool to help everyone save time.

License

This project is open source.