# CrackQuiz - AI-Powered Quiz Generator

## Product Overview

CrackQuiz is a privacy-first quiz generation platform that transforms documents (PDF, Markdown, Text) into interactive quizzes using AI. All document processing happens locally in your browser—your data never leaves your device.

### Key Features

- **Document Upload (100% Private)**: Upload PDFs, Markdown, or text files. AI extracts content locally in your browser with zero server upload.
- **Multi-LLM Support**: Choose your AI provider:
  - Local models (WebLLM) for complete privacy
  - Mistral AI (Le Chat)
  - OpenAI (GPT-4, GPT-4o)
  - Groq (Llama)
  - OpenRouter (multiple models)
- **CLI Tool**: Install via `npm install -g crackquiz` or `brew install crackquiz` for terminal-based quiz creation
- **Multi-language Support**: Full internationalization (English, French, Arabic) with RTL support
- **Rich Content**: LaTeX math equations, code syntax highlighting (10+ languages), Markdown formatting, Mermaid diagrams
- **Privacy-First Architecture**: No server-side data processing, all AI generation happens client-side or via user-provided API keys

### Installation

**Web App**: https://crack-quiz.vercel.app  
**CLI (npm)**: `npm install -g crackquiz`  
**CLI (Homebrew)**: `brew install crackquiz`

---

# CrackQuiz JSON Schema Documentation

This document describes the JSON structure for importing quizzes into CrackQuiz.

## Quiz Creation Methods

CrackQuiz supports multiple ways to create quizzes:

1. **Upload JSON** - Import a pre-formatted quiz file (see schema below)
2. **Paste JSON** - Directly paste quiz JSON data
3. **Upload Documents (100% Private)** - Upload PDF, TXT, or MD files to extract text for AI quiz generation
   - All document processing happens in your browser
   - Your data never leaves your device
   - Supported formats: PDF, Plain Text (.txt), Markdown (.md)
   - Maximum file size: 10MB
4. **AI Generate** - Paste notes or text to generate quizzes with local AI

## Overview
Your JSON file must follow this exact structure to be successfully imported.

## Schema Template
```json
{
  "version": "1.0",
  "metadata": {
    "title": "Quiz Title",
    "description": "Description of the quiz",
    "timeLimit": 300,
    "shuffleQuestions": true,
    "shuffleOptions": true
  },
  "questions": [
    {
      "id": "q1",
      "type": "single",
      "question": "Question text here?",
      "options": [
        {
          "id": "a",
          "text": "Option A",
          "explanation": "Why this option is correct/incorrect."
        },
        {
          "id": "b",
          "text": "Option B",
          "explanation": "Explain this choice."
        }
      ],
      "correctAnswer": "a",
      "explanation": "Why A is correct."
    },
    {
      "id": "q2",
      "type": "multiple",
      "question": "Select all that apply",
      "options": [
        { "id": "a", "text": "Correct 1" },
        { "id": "b", "text": "Wrong 1" },
        { "id": "c", "text": "Correct 2" }
      ],
      "correctAnswer": ["a", "c"],
      "explanation": "Explanation here."
    },
    {
      "id": "q3",
      "type": "coding",
      "language": "python",
      "question": "Write a function that reverses a string",
      "starterCode": "def reverse_string(s):\\n    pass",
      "solution": "def reverse_string(s):\\n    return s[::-1]",
      "explanation": "Use Python slicing [::-1] to reverse."
    }
  ]
}
```

## Field Details

### Metadata
- `version`: Must be "1.0" (required)
- `title`: String, required
- `description`: String, optional
- `timeLimit`: Integer (seconds), optional. 0 for no limit
- `shuffleQuestions`: Boolean, optional. Randomize question order
- `shuffleOptions`: Boolean, optional. Randomize answer choices

### Questions

#### Common Fields (All Question Types)
- `id`: Unique string identifier (required)
- `type`: Question type - "single", "multiple", or "coding" (required)
- `question`: The question text (required)
- `explanation`: Optional text shown after answering
- `tags`: Optional array of strings for categorization

#### Options Structure (for "single" and "multiple" types)
- `id`: Unique string identifier within question (required)
- `text`: The option text, supports Markdown (required)
- `explanation`: Optional explanation for why this specific option is correct or incorrect

**Note**: You can provide explanations for individual options AND/OR a general question explanation. Use option explanations to address specific misconceptions.

#### Type: "single" (Single Choice)
- `options`: Array of `{ "id": "...", "text": "..." }` (required)
- `correctAnswer`: String matching one option ID (required)

#### Type: "multiple" (Multiple Choice)
- `options`: Array of `{ "id": "...", "text": "..." }` (required)
- `correctAnswer`: Array of strings matching option IDs (required)

#### Type: "coding" (Code Writing)
- `language`: "python" | "javascript" | "typescript" | "java" | "cpp" | "dart" | "bash" | "plaintext" | "html" | "mermaid" | "tsx" (required)
- `starterCode`: String, pre-filled code template (optional)
- `solution`: String, reference solution (required)
- `testCases`: Optional array of test cases:
  - `description`: Test case description
  - `input`: Input example
  - `expectedOutput`: Expected output
- `evaluationCriteria`: Optional array of strings (e.g., ["correctness", "efficiency"])
- `hint`: Optional hint text
- `rule`: Optional grammar rule context (for plaintext/language learning)

### Content Formatting
All text fields support:
- **Markdown** - Code blocks (\`\`\`python ... \`\`\`), bold, italic, lists
- **LaTeX** - Math expressions enclosed in `$ ... $` or `$$ ... $$`
- **Mermaid** - Diagrams in \`\`\`mermaid ... \`\`\` blocks
- **UTF-8** - Full Unicode support (Arabic, Chinese, emojis, etc.)