Metadata-Version: 2.4
Name: quizmd
Version: 2.0.2
Summary: Run markdown quizzes in the terminal
Author: QuizMD Maintainers
License-Expression: MIT
Keywords: quiz,markdown,education,cli
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENCE.md
License-File: LICENSE
Requires-Dist: rich==13.7.0
Requires-Dist: prompt_toolkit==3.0.36
Requires-Dist: wcwidth==0.2.13
Dynamic: license-file

# quizmd

`quizmd` runs markdown-based quizzes in the terminal with timers, single/multiple choice support, and answer export.

## Install

Install the tool directly from GitHub:

```bash
pip install "git+https://github.com/steliosot/quizmd.git"
```

For a reproducible install, pin a release tag:

```bash
pip install "git+https://github.com/steliosot/quizmd.git@v2.0.2"
```

Then check the CLI:

```bash
quizmd --version
```

If you already installed it and want the latest updates:

```bash
pip install --upgrade --force-reinstall "git+https://github.com/steliosot/quizmd.git"
```

Add it to `requirements.txt` if you want teammates/students to install from GitHub:

```txt
git+https://github.com/steliosot/quizmd.git
```

## Install vs Examples

- `pip install ...` installs the `quizmd` command.
- `git clone ...` downloads this repository so you can use the bundled example quizzes.

## Run a Quiz

If you want the bundled examples, clone the repo:

```bash
git clone https://github.com/steliosot/quizmd.git
cd quizmd
quizmd quizzes/harry-potter-quiz.md
```

Validate quiz files without running the interactive UI:

```bash
quizmd --validate quizzes/harry-potter-quiz.md
```

Validate and run an essay quiz:

```bash
quizmd --validate essays/requirements-txt-essay.md
export GEMINI_API_KEY="your_key_here"
quizmd essays/requirements-txt-essay.md
```

Optional AI settings for essay mode:

```bash
quizmd --ai-provider gemini --ai-model gemini-flash-latest --ai-timeout 30 essays/requirements-txt-essay.md
```

`--ai-timeout` must be greater than zero.

Security notes:
- Never hardcode or commit API keys in source control.
- Use environment variables (`GEMINI_API_KEY`) only.
- If a key is exposed, rotate/revoke it immediately.

Privacy note:
- Essay answers are only saved if you choose `y` at the save prompt.
- Choose `n` to keep answers out of local `answers/` files.

Theme options for better readability on light or dark terminals:

```bash
quizmd --theme auto quizzes/harry-potter-quiz.md
quizmd --theme light quizzes/harry-potter-quiz.md
quizmd --theme dark quizzes/harry-potter-quiz.md
```

## Windows Setup Notes

Create and activate a virtual environment on Windows:

```powershell
python -m venv .venv
.venv\Scripts\activate
```

Install and run:

```powershell
pip install "git+https://github.com/steliosot/quizmd.git"
quizmd --version
quizmd --validate .\quizzes\harry-potter-quiz.md
quizmd .\quizzes\harry-potter-quiz.md
```

## Example Quizzes Included (No LLM Needed)

- `quizzes/harry-potter-quiz.md`
- `quizzes/world-geography-quiz.md`
- `quizzes/python-basics-quiz.md`
- `quizzes/math-foundations-quiz.md`
- `quizzes/history-and-civics-quiz.md`
- `quizzes/general-science-quiz.md`

## Essay Examples (LLM-Based)

Essay files are separate and use Gemini evaluation:
- `essays/requirements-txt-essay.md`
- `essays/venv-essay.md`
- `essays/pinned-versions-essay.md`

MCQ quizzes in `quizzes/` do not call LLMs and do not need `GEMINI_API_KEY`.

## Simple Quiz Example

Create a file named `my-quiz.md`:

```markdown
# My First Quiz

## Question 1
What is 2 + 2?

- 3
- 4
- 5

Answer: 2
Type: single
Time: 20
Explanation: 2 + 2 is 4.
```

Run it:

```bash
quizmd --validate my-quiz.md
quizmd my-quiz.md
```

## Guide: How to Create a Quiz

1. Start with a single `#` quiz title.
2. Add each question as a `##` block.
3. Put the question text on the next line.
4. Add answer options using `- ` bullet lines.
5. Add required fields:
   - `Answer:` (1-based indexes, comma-separated for multiple)
   - `Type:` (`single` or `multiple`)
6. Add optional fields:
   - `Time:` positive integer seconds
   - `Explanation:` any text
7. Run `quizmd --validate your-quiz.md` before sharing.

## Quiz File Rules

- Each question must start with `##`.
- Text outside the title and `##` blocks is rejected.
- `Answer:` is required and must be valid indexes.
- `Type:` is required and must be `single` or `multiple`.
- Duplicate answers like `Answer: 2,2` are rejected.
- `Time:` (if present) must be greater than zero.

## Common Validation Errors

- `missing required field(s): options`
- `missing required field(s): answer`
- `missing required field(s): type`
- `duplicate answer indexes`
- `unsupported question type`
- `unexpected content outside question blocks`
- `no valid questions found`

## Student End-to-End Check (Clean Environment)

Use these exact steps before class to confirm everything works:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install "git+https://github.com/steliosot/quizmd.git"
quizmd --version
git clone https://github.com/steliosot/quizmd.git
cd quizmd
quizmd --validate quizzes/harry-potter-quiz.md
quizmd quizzes/harry-potter-quiz.md
```

## Development

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m unittest discover -s tests -q
```

## Releases

- Release tags are immutable.
- Never retag an existing version.
- Publish a new tag for every release (`v2.0.3`, `v2.0.4`, ...).
- See [CHANGELOG.md](CHANGELOG.md) and [RELEASE.md](RELEASE.md).
- PyPI publishing is configured via GitHub Trusted Publishing in `.github/workflows/release.yml`.

## Community

- Contributing guide: [CONTRIBUTING.md](CONTRIBUTING.md)
- Code of Conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
- Security policy: [SECURITY.md](SECURITY.md)
- License: [LICENSE](LICENSE)
