# QuizGen: AI-Powered Question Generation Tool
*Effortlessly create AI-generated quizzes from your educational content.*
QuizGen is a Python-based tool that generates quiz questions from educational materials using state-of-the-art AI models. It's designed for educators, course creators, and developers looking to automate question creation from textbooks, lecture notes, and other learning resources, saving time and enhancing the learning experience. With QuizGen, you can streamline quiz creation for online courses, exam preparation, and interactive learning tools like Anki.
The tool processes content, extracts key concepts, generates relevant questions, and outputs them in formats suitable for e-learning platforms, such as Anki.
## Key Features
- **Automatic concept extraction**: Identifies key concepts from provided educational content.
- **AI-powered question generation**: Uses advanced AI models to create high-quality, diverse quiz questions.
- **Question similarity reduction**: Reduces redundancy in generated questions by comparing embeddings.
- **Anki integration**: Easily import generated questions into Anki for flashcard-based learning.
- **Extensible and customizable**: Modify templates and fine-tune the output to suit specific educational needs.
## Installation
Before you begin, ensure you have:
- Python 3.10 or later installed.
- An OpenAI API key (available from [OpenAI](https://platform.openai.com/signup)).
- Anki with AnkiConnect installed if you plan to use the Anki import feature.
### PyPI Installation
The easiest way to install QuizGen is via pip:
```bash
pip install quizgen-ai
```
### Development Setup
If you want to contribute or modify the tool, follow these steps:
1. Clone the repository:
```bash
git clone https://github.com/kdunee/quizgen.git
cd quizgen
```
1. Install Poetry (if not already installed):
```bash
curl -sSL https://install.python-poetry.org | python3 -
```
1. Install the project dependencies:
```bash
poetry install
```
1. Set up your OpenAI API key as an environment variable:
```bash
export OPENAI_API_KEY=your_api_key_here
```
### Troubleshooting
- **Python version issues**: Ensure your Python version is 3.10+ by running `python --version`.
- **Poetry installation**: If you encounter issues with Poetry, refer to the [official Poetry documentation](https://python-poetry.org/docs/).
- For additional help, check the [OpenAI documentation](https://platform.openai.com/docs).
## Workflow
Here's the typical workflow for using QuizGen:
1. **Generate Questions:** Use the `generate` command to create questions from your source material. This outputs JSON files.
2. **Convert to CSV (Optional):** If needed, use the `convert` command to convert the JSON files to CSV.
3. **Generate Embeddings:** Use the `embeddings` command to create embeddings from the JSON questions. This is necessary for the next step.
4. **Thin Out Questions (Optional):** Use the `thin` command with the CSV and embeddings to reduce similar questions.
5. **Import to Anki (Optional):** Use the `anki` command with the CSV files to import your questions into Anki.
## Usage
QuizGen provides a unified command-line interface (CLI) to access all its functionalities. Here's how you can use it:
```bash
quizgen <command> [options]
```
**Available Commands:**
- **generate:** Generate questions from educational content.
```bash
# Generate questions from a single chapter:
quizgen generate --chapter-path path/to/chapter.md --title "Course Title" --output path/to/output.json
# Generate questions in batch mode:
quizgen generate --batch --input-dir path/to/source/files --output-dir path/to/output/json --title "Course Title"
```
- **convert:** Convert questions from JSON to CSV format.
```bash
# Convert questions to CSV:
quizgen convert --batch --input-dir path/to/json/files --output-dir path/to/csv/output
```
- **embeddings:** Generate embeddings for question comparison.
```bash
# Generate embeddings:
quizgen embeddings --batch --input-dir path/to/json/files --output-dir path/to/embeddings/output
```
- **thin:** Reduce similar questions using embeddings.
```bash
# Thin out questions:
quizgen thin --csv-dir path/to/csv/files --embeddings-dir path/to/embeddings --output-dir path/to/output --T 10
```
- **anki:** Import questions into Anki.
```bash
# Import to Anki:
quizgen anki --input-dir path/to/csv/files --root-deck-name "Root Deck Name"
```
## Model Selection
QuizGen allows you to select specific AI models for different stages of the question generation process. This can be useful for experimenting with different models or fine-tuning the output to your needs.
The following model selection arguments are available:
- `--concept-model`: Specifies the model used for concept extraction. Default is `gpt-4o-mini-2024-07-18`.
- `--questions-model`: Specifies the model used for question generation. Default is `gpt-4o-2024-08-06`.
- `--embedding-model`: Specifies the model used for generating embeddings. Default is `text-embedding-3-small`.
These arguments can be used with both single chapter and batch commands. For example:
```bash
# Generate questions using a specific model:
quizgen generate --chapter-path path/to/chapter.md --title "Course Title" --output path/to/output.json --questions-model gpt-4
# Generate embeddings using a specific model:
quizgen embeddings --batch --input-dir path/to/json/files --output-dir path/to/embeddings/output --embedding-model text-embedding-ada-002
```
## Example Anki Decks
Check out these example Anki decks generated using QuizGen:
- **Gradle Flashcards:** This deck is based on the official Gradle User Manual (October 2024) and covers a wide range of topics related to the Gradle build tool.
- [Download the Anki deck](https://ankiweb.net/shared/info/1572773429)
- **Go Language Specification (October 2024)** - This deck is based on The Go Programming Language Specification.
- [Download the Anki deck](https://ankiweb.net/shared/info/383266601)
## Contributing
Contributions are welcome! Here's how you can contribute:
1. Fork the repository.
1. Create a new branch (`git checkout -b feature-branch`).
1. Install the project using Poetry: `poetry install`
1. Make your changes.
1. Submit a Pull Request with a description of your changes.
For bug reports or feature requests, please open an issue on GitHub. Ensure that your contributions follow the coding guidelines.
## License
This project is licensed under the MIT License. See the `LICENSE` file for more details.
Raw data
{
"_id": null,
"home_page": "https://github.com/kdunee/quizgen",
"name": "quizgen-ai",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "ai, quiz, anki, llm",
"author": "Kosma Dunikowski",
"author_email": "kosmadunikowski@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/64/e0/9ee15970c39ba8bd9dab19ad931f8696881ac9273978f4e5e6766c8dc5bc/quizgen_ai-1.0.2.tar.gz",
"platform": null,
"description": "# QuizGen: AI-Powered Question Generation Tool\n\n*Effortlessly create AI-generated quizzes from your educational content.*\n\nQuizGen is a Python-based tool that generates quiz questions from educational materials using state-of-the-art AI models. It's designed for educators, course creators, and developers looking to automate question creation from textbooks, lecture notes, and other learning resources, saving time and enhancing the learning experience. With QuizGen, you can streamline quiz creation for online courses, exam preparation, and interactive learning tools like Anki.\n\nThe tool processes content, extracts key concepts, generates relevant questions, and outputs them in formats suitable for e-learning platforms, such as Anki.\n\n## Key Features\n\n- **Automatic concept extraction**: Identifies key concepts from provided educational content.\n- **AI-powered question generation**: Uses advanced AI models to create high-quality, diverse quiz questions.\n- **Question similarity reduction**: Reduces redundancy in generated questions by comparing embeddings.\n- **Anki integration**: Easily import generated questions into Anki for flashcard-based learning.\n- **Extensible and customizable**: Modify templates and fine-tune the output to suit specific educational needs.\n\n## Installation\n\nBefore you begin, ensure you have:\n\n- Python 3.10 or later installed.\n- An OpenAI API key (available from [OpenAI](https://platform.openai.com/signup)).\n- Anki with AnkiConnect installed if you plan to use the Anki import feature.\n\n### PyPI Installation\n\nThe easiest way to install QuizGen is via pip:\n\n```bash\npip install quizgen-ai\n```\n\n### Development Setup\n\nIf you want to contribute or modify the tool, follow these steps:\n\n1. Clone the repository:\n\n ```bash\n git clone https://github.com/kdunee/quizgen.git\n cd quizgen\n ```\n\n1. Install Poetry (if not already installed):\n\n ```bash\n curl -sSL https://install.python-poetry.org | python3 -\n ```\n\n1. Install the project dependencies:\n\n ```bash\n poetry install\n ```\n\n1. Set up your OpenAI API key as an environment variable:\n\n ```bash\n export OPENAI_API_KEY=your_api_key_here\n ```\n\n### Troubleshooting\n\n- **Python version issues**: Ensure your Python version is 3.10+ by running `python --version`.\n- **Poetry installation**: If you encounter issues with Poetry, refer to the [official Poetry documentation](https://python-poetry.org/docs/).\n- For additional help, check the [OpenAI documentation](https://platform.openai.com/docs).\n\n## Workflow\n\nHere's the typical workflow for using QuizGen:\n\n1. **Generate Questions:** Use the `generate` command to create questions from your source material. This outputs JSON files.\n2. **Convert to CSV (Optional):** If needed, use the `convert` command to convert the JSON files to CSV.\n3. **Generate Embeddings:** Use the `embeddings` command to create embeddings from the JSON questions. This is necessary for the next step.\n4. **Thin Out Questions (Optional):** Use the `thin` command with the CSV and embeddings to reduce similar questions.\n5. **Import to Anki (Optional):** Use the `anki` command with the CSV files to import your questions into Anki.\n\n## Usage\n\nQuizGen provides a unified command-line interface (CLI) to access all its functionalities. Here's how you can use it:\n\n```bash\nquizgen <command> [options]\n```\n\n**Available Commands:**\n\n- **generate:** Generate questions from educational content.\n\n ```bash\n # Generate questions from a single chapter:\n quizgen generate --chapter-path path/to/chapter.md --title \"Course Title\" --output path/to/output.json\n\n # Generate questions in batch mode:\n quizgen generate --batch --input-dir path/to/source/files --output-dir path/to/output/json --title \"Course Title\"\n ```\n\n- **convert:** Convert questions from JSON to CSV format.\n\n ```bash\n # Convert questions to CSV:\n quizgen convert --batch --input-dir path/to/json/files --output-dir path/to/csv/output\n ```\n\n- **embeddings:** Generate embeddings for question comparison.\n\n ```bash\n # Generate embeddings:\n quizgen embeddings --batch --input-dir path/to/json/files --output-dir path/to/embeddings/output\n ```\n\n- **thin:** Reduce similar questions using embeddings.\n\n ```bash\n # Thin out questions:\n quizgen thin --csv-dir path/to/csv/files --embeddings-dir path/to/embeddings --output-dir path/to/output --T 10 \n ```\n\n- **anki:** Import questions into Anki.\n\n ```bash\n # Import to Anki:\n quizgen anki --input-dir path/to/csv/files --root-deck-name \"Root Deck Name\" \n ```\n\n## Model Selection\n\nQuizGen allows you to select specific AI models for different stages of the question generation process. This can be useful for experimenting with different models or fine-tuning the output to your needs.\n\nThe following model selection arguments are available:\n\n- `--concept-model`: Specifies the model used for concept extraction. Default is `gpt-4o-mini-2024-07-18`.\n- `--questions-model`: Specifies the model used for question generation. Default is `gpt-4o-2024-08-06`.\n- `--embedding-model`: Specifies the model used for generating embeddings. Default is `text-embedding-3-small`.\n\nThese arguments can be used with both single chapter and batch commands. For example:\n\n```bash\n# Generate questions using a specific model:\nquizgen generate --chapter-path path/to/chapter.md --title \"Course Title\" --output path/to/output.json --questions-model gpt-4\n\n# Generate embeddings using a specific model:\nquizgen embeddings --batch --input-dir path/to/json/files --output-dir path/to/embeddings/output --embedding-model text-embedding-ada-002\n```\n\n## Example Anki Decks\n\nCheck out these example Anki decks generated using QuizGen:\n\n- **Gradle Flashcards:** This deck is based on the official Gradle User Manual (October 2024) and covers a wide range of topics related to the Gradle build tool.\n - [Download the Anki deck](https://ankiweb.net/shared/info/1572773429)\n- **Go Language Specification (October 2024)** - This deck is based on The Go Programming Language Specification.\n - [Download the Anki deck](https://ankiweb.net/shared/info/383266601)\n\n## Contributing\n\nContributions are welcome! Here's how you can contribute:\n\n1. Fork the repository.\n1. Create a new branch (`git checkout -b feature-branch`).\n1. Install the project using Poetry: `poetry install`\n1. Make your changes.\n1. Submit a Pull Request with a description of your changes.\n\nFor bug reports or feature requests, please open an issue on GitHub. Ensure that your contributions follow the coding guidelines.\n\n## License\n\nThis project is licensed under the MIT License. See the `LICENSE` file for more details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "AI-Powered Question Generation Tool",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/kdunee/quizgen",
"Repository": "https://github.com/kdunee/quizgen"
},
"split_keywords": [
"ai",
" quiz",
" anki",
" llm"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ede174947c123d87c30201ac9c721c2d1989c2ba6d4eea7cd2bb616e2ea98101",
"md5": "044102828b43f1cbf8f11c4555e13a39",
"sha256": "b1ba8a546ce6b99a242c811ce43a9ccf202321e0beefcd45cd946f67389e5a8d"
},
"downloads": -1,
"filename": "quizgen_ai-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "044102828b43f1cbf8f11c4555e13a39",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 14531,
"upload_time": "2024-10-13T06:00:37",
"upload_time_iso_8601": "2024-10-13T06:00:37.866256Z",
"url": "https://files.pythonhosted.org/packages/ed/e1/74947c123d87c30201ac9c721c2d1989c2ba6d4eea7cd2bb616e2ea98101/quizgen_ai-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "64e09ee15970c39ba8bd9dab19ad931f8696881ac9273978f4e5e6766c8dc5bc",
"md5": "b6482dd69be031c728c086b827187de5",
"sha256": "ed1f9441496bfa61fba95153e6a087bd99faf0abcff6c7325a61a59dc07e2512"
},
"downloads": -1,
"filename": "quizgen_ai-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "b6482dd69be031c728c086b827187de5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 12202,
"upload_time": "2024-10-13T06:00:39",
"upload_time_iso_8601": "2024-10-13T06:00:39.633102Z",
"url": "https://files.pythonhosted.org/packages/64/e0/9ee15970c39ba8bd9dab19ad931f8696881ac9273978f4e5e6766c8dc5bc/quizgen_ai-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-13 06:00:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kdunee",
"github_project": "quizgen",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "openai",
"specs": [
[
"==",
"1.47.1"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
"==",
"1.5.2"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"2.1.2"
]
]
},
{
"name": "tqdm",
"specs": [
[
"==",
"4.66.5"
]
]
}
],
"lcname": "quizgen-ai"
}
JSON
