promptukit 0.1.1__tar.gz

promptukit-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joseph Kasprzyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

promptukit-0.1.1/PKG-INFO

@@ -0,0 +1,317 @@
+Metadata-Version: 2.4
+Name: promptukit
+Version: 0.1.1
+Summary: Utilities for building question banks and generating exam documents.
+License: MIT
+License-File: LICENSE
+Keywords: questions,exams,education,pdf,question-bank
+Author: Joseph Kasprzyk
+Author-email: jkasprzyk@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Education
+Requires-Dist: build (>=1.4.3,<2.0.0)
+Requires-Dist: reportlab (>=4.4.10,<5.0.0)
+Requires-Dist: twine (>=6.2.0,<7.0.0)
+Project-URL: Homepage, https://github.com/jrkasprzyk/promptukit
+Project-URL: Repository, https://github.com/jrkasprzyk/promptukit
+Description-Content-Type: text/markdown
+
+PromptuKit
+=========
+
+Small utilities for working with trivia question banks.
+
+Getting started (Poetry)
+------------------------
+
+1. Install Poetry (if you don't have it).
+
+   ```bash
+   pip install --user poetry
+   ```
+
+2. Create the virtual environment and install dependencies:
+
+   ```bash
+   poetry install
+   ```
+
+3. Run the CLI tools via Poetry:
+
+   ```bash
+   poetry run promptukit-add-trivia
+   poetry run promptukit-extract-trivia --help
+   poetry run promptukit-validate-trivia
+   ```
+
+Activating the virtualenv
+-------------------------
+
+If Poetry is configured to create an in-project virtualenv, it will be placed in a `.venv` folder at the repository root. Activate that environment from the project root using the command for your shell:
+
+PowerShell (Windows):
+
+```powershell
+Update README to reflect new CLI names and module paths.
+
+PromptuKit
+==========
+
+Utilities for building and managing multiple-choice question banks and
+generating exam PDFs.
+
+Getting started (Poetry)
+------------------------
+
+1. Install Poetry (if you don't have it):
+
+   ```bash
+   pip install --user poetry
+   ```
+
+2. Create the virtual environment and install dependencies:
+
+   ```bash
+   poetry install
+   ```
+
+3. Run the CLI tools via Poetry (console scripts / entry points):
+
+   ```bash
+   poetry run add-question
+   poetry run extract-question --help
+   poetry run validate-question
+   poetry run question-bank --help
+   ```
+
+Activating the virtualenv
+-------------------------
+
+If Poetry is configured to create an in-project virtualenv, it will be
+placed in a `.venv` folder at the repository root. Activate that
+environment from the project root using the command for your shell.
+
+PowerShell (Windows):
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+If script execution is blocked, temporarily allow it then activate:
+
+```powershell
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
+.\.venv\Scripts\Activate.ps1
+```
+
+Command Prompt (cmd.exe):
+
+```cmd
+.\.venv\Scripts\activate.bat
+```
+
+Git Bash / MSYS (Windows):
+
+```bash
+source .venv/Scripts/activate
+```
+
+macOS / Linux (POSIX):
+
+```bash
+source .venv/bin/activate
+```
+
+Alternatives (no manual activation required):
+
+```bash
+# Run a single command inside the virtualenv without activating it
+poetry run <cmd>    # e.g. poetry run pytest
+```
+
+Poetry 2.x note:
+
+- The `poetry shell` command (which previously spawned a new shell) is not
+  installed by default in Poetry 2.0+. You can either use
+  `poetry env activate` (then evaluate the printed activation command in
+  your shell) or install the shell plugin to restore `poetry shell`.
+
+Notes
+-----
+- The package entry points are defined in `pyproject.toml` under
+  `[tool.poetry.scripts]` and map console script names to the
+  `main()` functions in the modules under the `promptukit` package.
+
+Usage Examples
+--------------
+
+Quick (Poetry):
+
+```bash
+poetry run add-question
+poetry run extract-question --list-categories
+poetry run validate-question
+poetry run question-bank extract --help
+```
+
+Extracting data:
+
+```bash
+# List categories and available fields
+poetry run extract-question --list-categories
+
+# Print prompt and answer fields for the 'music' category
+poetry run extract-question --file content/question_banks/block-doku-questions.json --category music --fields prompt,answer
+
+# Interactive picker
+poetry run extract-question -i
+```
+
+Add questions:
+
+```bash
+# Interactive add
+poetry run add-question
+
+# Batch mode
+poetry run add-question --batch new_questions.json content/question_banks/mybank.json
+```
+
+Validate a trivia file:
+
+```bash
+# Validate the default question bank
+poetry run validate-question
+
+# Validate a specific file
+poetry run validate-question content/question_banks/block-doku-questions.json
+```
+
+Manage files with `question-bank` (create/copy/extract):
+
+```bash
+# Create a new template JSON file
+poetry run question-bank create --dest content/question_banks/new.json --categories music,film-and-tv
+
+# Copy an existing file
+poetry run question-bank copy --src content/question_banks/block-doku-questions.json --dest content/question_banks/backup.json
+
+# Extract a subset (easy music questions)
+poetry run question-bank extract --src content/question_banks/block-doku-questions.json --dest content/question_banks/music_easy.json --categories music --difficulty easy
+
+# Interactive extract
+poetry run question-bank extract -i --src content/question_banks/block-doku-questions.json --dest content/question_banks/pick.json
+```
+
+Alternative: run modules with `python -m` when not using Poetry:
+
+```bash
+python -m promptukit.questions.add_question
+python -m promptukit.questions.extract_question --help
+python -m promptukit.questions.question_bank create --dest content/question_banks/new.json
+```
+
+Create exam PDF
+---------------
+
+The `create_exam.py` script can generate a printable exam PDF. It accepts
+an external JSON question bank so you can build exams from your existing
+`content/question_banks/` files.
+
+Usage (from the repository root):
+
+```bash
+# Use the built-in hard-coded exam
+python -m promptukit.exams.create_exam
+
+# Load questions from a JSON bank and write a PDF
+python -m promptukit.exams.create_exam -q content/question_banks/block-doku-questions.json -o cven4333_from_json.pdf
+
+# With Poetry (runs the module inside the virtualenv)
+poetry run python -m promptukit.exams.create_exam -q content/question_banks/block-doku-questions.json -o cven4333_from_json.pdf
+```
+
+Supported JSON formats
+----------------------
+
+- Top-level `sections` (preferred):
+
+  ```json
+  {
+     "sections": [
+        {
+           "title": "Section title",
+           "questions": [ { "prompt": "...", "choices": ["...", "..."] }, ... ]
+        }
+     ]
+  }
+  ```
+
+- `categories` is an alias for `sections` and is also accepted.
+
+- Flat list of questions (top-level array) or top-level object with `questions` array:
+
+  ```json
+  {
+     "questions": [ { "prompt": "...", "choices": ["...", "..."], "category": "Section title" }, ... ]
+  }
+  ```
+
+- Question objects support multiple common field names: `prompt`, `q`, `question`, or `text` for the question text; `choices` or `answers` for the answer options; optional `category` to group flat lists into sections.
+
+- If choices are not already labeled (for example "Oceans" instead of "A) Oceans"), the script will prefix them with `A)`, `B)`, etc. Prompts without a leading number will be auto-numbered sequentially.
+
+Example files
+-------------
+
+- Example section-based bank: [content/question_banks/example_sections.json](content/question_banks/example_sections.json)
+- JSON Schema describing accepted layouts: [content/question_banks/question_schema.json](content/question_banks/question_schema.json)
+
+Behavior notes
+--------------
+
+- If no `-q/--questions` file is provided to the exam generator, the script
+  falls back to the built-in hard-coded 60-question exam and preserves its
+  original 8-section breakdown.
+- When you provide a section-based JSON file the PDF's section headings will
+  be taken from each section's `title` (or `name` / `label` if present). When
+  you provide a flat list with `category` fields, the loader will group
+  questions by category to build sections automatically.
+
+Running Tests
+-------------
+
+The test suite lives under `dev/checks`. The file
+`dev/checks/test_question_tool.py` contains unit tests that exercise the
+question-bank helpers and CLI-style interfaces.
+
+Run the tests:
+
+Using Poetry (recommended):
+
+```bash
+poetry install
+poetry run pytest -q
+```
+
+Or run a single file directly:
+
+```bash
+poetry run pytest dev/checks/test_question_tool.py -q
+```
+
+Notes:
+
+- Tests use pytest's `tmp_path` fixture and do not modify your repository files.
+
+

promptukit-0.1.1/README.md

@@ -0,0 +1,288 @@
+PromptuKit
+=========
+
+Small utilities for working with trivia question banks.
+
+Getting started (Poetry)
+------------------------
+
+1. Install Poetry (if you don't have it).
+
+   ```bash
+   pip install --user poetry
+   ```
+
+2. Create the virtual environment and install dependencies:
+
+   ```bash
+   poetry install
+   ```
+
+3. Run the CLI tools via Poetry:
+
+   ```bash
+   poetry run promptukit-add-trivia
+   poetry run promptukit-extract-trivia --help
+   poetry run promptukit-validate-trivia
+   ```
+
+Activating the virtualenv
+-------------------------
+
+If Poetry is configured to create an in-project virtualenv, it will be placed in a `.venv` folder at the repository root. Activate that environment from the project root using the command for your shell:
+
+PowerShell (Windows):
+
+```powershell
+Update README to reflect new CLI names and module paths.
+
+PromptuKit
+==========
+
+Utilities for building and managing multiple-choice question banks and
+generating exam PDFs.
+
+Getting started (Poetry)
+------------------------
+
+1. Install Poetry (if you don't have it):
+
+   ```bash
+   pip install --user poetry
+   ```
+
+2. Create the virtual environment and install dependencies:
+
+   ```bash
+   poetry install
+   ```
+
+3. Run the CLI tools via Poetry (console scripts / entry points):
+
+   ```bash
+   poetry run add-question
+   poetry run extract-question --help
+   poetry run validate-question
+   poetry run question-bank --help
+   ```
+
+Activating the virtualenv
+-------------------------
+
+If Poetry is configured to create an in-project virtualenv, it will be
+placed in a `.venv` folder at the repository root. Activate that
+environment from the project root using the command for your shell.
+
+PowerShell (Windows):
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+If script execution is blocked, temporarily allow it then activate:
+
+```powershell
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
+.\.venv\Scripts\Activate.ps1
+```
+
+Command Prompt (cmd.exe):
+
+```cmd
+.\.venv\Scripts\activate.bat
+```
+
+Git Bash / MSYS (Windows):
+
+```bash
+source .venv/Scripts/activate
+```
+
+macOS / Linux (POSIX):
+
+```bash
+source .venv/bin/activate
+```
+
+Alternatives (no manual activation required):
+
+```bash
+# Run a single command inside the virtualenv without activating it
+poetry run <cmd>    # e.g. poetry run pytest
+```
+
+Poetry 2.x note:
+
+- The `poetry shell` command (which previously spawned a new shell) is not
+  installed by default in Poetry 2.0+. You can either use
+  `poetry env activate` (then evaluate the printed activation command in
+  your shell) or install the shell plugin to restore `poetry shell`.
+
+Notes
+-----
+- The package entry points are defined in `pyproject.toml` under
+  `[tool.poetry.scripts]` and map console script names to the
+  `main()` functions in the modules under the `promptukit` package.
+
+Usage Examples
+--------------
+
+Quick (Poetry):
+
+```bash
+poetry run add-question
+poetry run extract-question --list-categories
+poetry run validate-question
+poetry run question-bank extract --help
+```
+
+Extracting data:
+
+```bash
+# List categories and available fields
+poetry run extract-question --list-categories
+
+# Print prompt and answer fields for the 'music' category
+poetry run extract-question --file content/question_banks/block-doku-questions.json --category music --fields prompt,answer
+
+# Interactive picker
+poetry run extract-question -i
+```
+
+Add questions:
+
+```bash
+# Interactive add
+poetry run add-question
+
+# Batch mode
+poetry run add-question --batch new_questions.json content/question_banks/mybank.json
+```
+
+Validate a trivia file:
+
+```bash
+# Validate the default question bank
+poetry run validate-question
+
+# Validate a specific file
+poetry run validate-question content/question_banks/block-doku-questions.json
+```
+
+Manage files with `question-bank` (create/copy/extract):
+
+```bash
+# Create a new template JSON file
+poetry run question-bank create --dest content/question_banks/new.json --categories music,film-and-tv
+
+# Copy an existing file
+poetry run question-bank copy --src content/question_banks/block-doku-questions.json --dest content/question_banks/backup.json
+
+# Extract a subset (easy music questions)
+poetry run question-bank extract --src content/question_banks/block-doku-questions.json --dest content/question_banks/music_easy.json --categories music --difficulty easy
+
+# Interactive extract
+poetry run question-bank extract -i --src content/question_banks/block-doku-questions.json --dest content/question_banks/pick.json
+```
+
+Alternative: run modules with `python -m` when not using Poetry:
+
+```bash
+python -m promptukit.questions.add_question
+python -m promptukit.questions.extract_question --help
+python -m promptukit.questions.question_bank create --dest content/question_banks/new.json
+```
+
+Create exam PDF
+---------------
+
+The `create_exam.py` script can generate a printable exam PDF. It accepts
+an external JSON question bank so you can build exams from your existing
+`content/question_banks/` files.
+
+Usage (from the repository root):
+
+```bash
+# Use the built-in hard-coded exam
+python -m promptukit.exams.create_exam
+
+# Load questions from a JSON bank and write a PDF
+python -m promptukit.exams.create_exam -q content/question_banks/block-doku-questions.json -o cven4333_from_json.pdf
+
+# With Poetry (runs the module inside the virtualenv)
+poetry run python -m promptukit.exams.create_exam -q content/question_banks/block-doku-questions.json -o cven4333_from_json.pdf
+```
+
+Supported JSON formats
+----------------------
+
+- Top-level `sections` (preferred):
+
+  ```json
+  {
+     "sections": [
+        {
+           "title": "Section title",
+           "questions": [ { "prompt": "...", "choices": ["...", "..."] }, ... ]
+        }
+     ]
+  }
+  ```
+
+- `categories` is an alias for `sections` and is also accepted.
+
+- Flat list of questions (top-level array) or top-level object with `questions` array:
+
+  ```json
+  {
+     "questions": [ { "prompt": "...", "choices": ["...", "..."], "category": "Section title" }, ... ]
+  }
+  ```
+
+- Question objects support multiple common field names: `prompt`, `q`, `question`, or `text` for the question text; `choices` or `answers` for the answer options; optional `category` to group flat lists into sections.
+
+- If choices are not already labeled (for example "Oceans" instead of "A) Oceans"), the script will prefix them with `A)`, `B)`, etc. Prompts without a leading number will be auto-numbered sequentially.
+
+Example files
+-------------
+
+- Example section-based bank: [content/question_banks/example_sections.json](content/question_banks/example_sections.json)
+- JSON Schema describing accepted layouts: [content/question_banks/question_schema.json](content/question_banks/question_schema.json)
+
+Behavior notes
+--------------
+
+- If no `-q/--questions` file is provided to the exam generator, the script
+  falls back to the built-in hard-coded 60-question exam and preserves its
+  original 8-section breakdown.
+- When you provide a section-based JSON file the PDF's section headings will
+  be taken from each section's `title` (or `name` / `label` if present). When
+  you provide a flat list with `category` fields, the loader will group
+  questions by category to build sections automatically.
+
+Running Tests
+-------------
+
+The test suite lives under `dev/checks`. The file
+`dev/checks/test_question_tool.py` contains unit tests that exercise the
+question-bank helpers and CLI-style interfaces.
+
+Run the tests:
+
+Using Poetry (recommended):
+
+```bash
+poetry install
+poetry run pytest -q
+```
+
+Or run a single file directly:
+
+```bash
+poetry run pytest dev/checks/test_question_tool.py -q
+```
+
+Notes:
+
+- Tests use pytest's `tmp_path` fixture and do not modify your repository files.
+

promptukit-0.1.1/promptukit/__init__.py

@@ -0,0 +1,18 @@
+"""promptukit — utilities for building question banks and exam documents."""
+
+from promptukit.utils.cli_helpers import load, save, pick, confirm
+from promptukit import questions, exams, utils
+
+__all__ = [
+    # subpackages
+    "questions",
+    "exams",
+    "utils",
+    # flat re-exports from utils
+    "load",
+    "save",
+    "pick",
+    "confirm",
+]
+
+__version__ = "0.1.0"

promptukit-0.1.1/promptukit/exams/__init__.py

@@ -0,0 +1,7 @@
+"""Tools for generating exam documents."""
+
+from promptukit.exams import create_exam
+
+__all__ = [
+    "create_exam",
+]