WiseMock

WiseMock is a desktop mock-exam application built for the Introduction to Programming course at Nova SBE. It helps students turn study material or exam files into an interactive timed exam, submit answers, review mistakes, and keep track of performance over time.

The project is implemented in Python with PyQt5 and an embedded HTML frontend. It can run fully offline with a prepared JSON exam, and it can also use Groq AI features to parse documents, generate questions, and review open-ended answers.

Highlights

• Load ready-made WiseMock exam files in JSON format.
• Parse existing .pdf, .docx, and .pptx exams into structured questions with a Groq API key.
• Generate new mock exams from study material.
• Support multiple-choice, fill-in-the-blank, and open-ended questions.
• Run timed exams with optional fullscreen mode, shuffled questions, and shuffled answer options.
• Grade multiple-choice and fill-in-the-blank answers locally.
• Review open-ended answers and produce study feedback with AI when a Groq API key is provided.
• Save performance history locally and export review material.
• Include a complete sample exam so the app can be tested without AI access.

Quick Start

From the project root:

pip install -r requirements.txt
python wiseflow.py

Alternative package entry point:

python -m wisemock

If you are using a virtual environment, create and activate it before installing the requirements.

Test Without a Groq API Key

WiseMock includes a full sample exam at:

examples/sample_exam.json

After launching the app, click Try sample exam on the setup screen, or load the file manually. This sample contains 30 programming questions across four sections and does not require network access or a Groq API key.

This is the recommended reviewer path for quickly checking that the application runs end to end.

Supported Inputs

Input type	Purpose	Groq required
.json	Load a prepared WiseMock exam file, including exams saved from WiseMock with the .exam.json suffix.	No
.pdf	Extract study material or parse an existing exam	Yes for AI parsing/generation
.docx	Extract study material or parse an existing exam	Yes for AI parsing/generation
.pptx	Extract slide material for exam generation	Yes for AI generation

OCR for scanned PDF images is optional and requires Tesseract to be installed on the operating system.

Groq AI Features

A Groq API key unlocks the AI-assisted parts of the application:

• parsing document text into exam JSON;
• generating mock questions from study material;
• reviewing open-ended answers;
• generating study reports after submission.

The app uses Groq through direct HTTP requests, so there is no separate Groq pip package in requirements.txt. Document text and answer content are sent to Groq only when AI features are used.

Getting a Free API Key

1. Create a free account at https://console.groq.com/keys
2. Click "Create API Key" and copy the key (it starts with gsk_).
3. In WiseMock: paste the key in the API Key field on the setup screen, or after submitting an exam click ✨ Activate AI to add it then.
4. The key lives only in memory for the current session — WiseMock never writes it to disk.

Without a key, the app still loads any pre-built JSON exam (including the included sample) and grades multiple-choice and fill-in-the-blank answers locally.

Exam Data Model

WiseMock exams are represented as JSON. A typical exam includes:

• title: exam title shown in the UI;
• questions: flat list used by loading, summaries, grading, and exports;
• sections: optional structured grouping used by the exam display.

Question types:

• mc: multiple-choice question with options and correct_answer;
• fill_blank: fill-in-the-blank question with template, blanks, and correct_answers;
• open: open-ended question with an optional suggested answer for AI review.

See examples/sample_exam.json for a complete working exam file.

Project Structure

.
├── wiseflow.py                 # Compatibility launcher from the project root
├── requirements.txt            # Python dependencies
├── examples/
│   └── sample_exam.json        # Full sample exam for offline testing
└── wisemock/                   # Active application package
    ├── app.py                  # QApplication setup and main window selection
    ├── __main__.py             # Enables: python -m wisemock
    ├── config.py               # Paths, capability flags, optional dependency checks
    ├── api/                    # Groq API request helpers
    ├── assets/                 # HTML frontend, intro page, icons, logo, audio
    ├── core/                   # Extraction, grading, exam JSON loading, history
    ├── export/                 # PDF and exam-file export helpers
    ├── pages/                  # Legacy/fallback PyQt pages
    ├── runtime/                # WebEngine window, JS/Python bridge, runtime exam state
    ├── widgets/                # Legacy/fallback PyQt widgets
    └── workers.py              # Background AI workers

wiseflow.py remains at the root as a convenient launcher and compatibility facade. New code should generally import from the wisemock package directly.

Reviewer Guide

For a quick code review, start with these files:

• wiseflow.py - root launcher and compatibility layer.
• wisemock/app.py - application startup.
• wisemock/runtime/bridge.py - connection between the HTML frontend and Python logic.
• wisemock/runtime/prepare.py - runtime exam preparation, shuffling, and answer normalization.
• wisemock/core/grading.py - local grading logic.
• wisemock/core/extract.py - PDF, DOCX, PPTX, table, and optional OCR text extraction.
• wisemock/workers.py - background Groq workers for parsing, generation, and review.
• wisemock/assets/wisemock_frontend.html - main user interface.

Suggested manual review flow:

1. Install dependencies with pip install -r requirements.txt.
2. Start the app with python wiseflow.py.
3. Click Try sample exam.
4. Start the exam, answer a few questions, submit, and open the review.
5. Optionally add a Groq API key to test AI parsing, generation, and feedback.

Dependencies

Required:

• PyQt5
• PyQtWebEngine

Optional document/OCR support:

• pymupdf for PDF extraction;
• python-docx for DOCX extraction;
• python-pptx for PPTX extraction;
• pytesseract and Pillow for OCR image handling;
• the Tesseract system binary for OCR.

On macOS, Tesseract can be installed with:

brew install tesseract

Runtime Data

Performance history is stored outside the package at:

~/.wiseflow/history.json

This keeps the source tree separate from local user data.

Notes and Limitations

• The included sample exam works without AI or internet access and is the simplest way to test the app end to end.
• Groq-powered parsing, generation, answer review, and study reports can make mistakes, so AI-generated exams and feedback should be reviewed before being used for real study or assessment.
• Groq features require a valid API key, network access, and are subject to provider rate limits and availability.
• Very large, scanned, image-heavy, or poorly formatted documents may take longer to extract or parse, and may require OCR or manual cleanup.
• OCR is best-effort and depends on both Python packages and the system Tesseract installation.