FortuneForge

FortuneForge is an offline desktop application for generating fortune-cookie messages and exporting selected fortunes as text or printable PDF slips.

Version 1.0.0 provides English fortune content across four moods, a selectable preview workflow, reproducible generation with optional seeds, UTF-8 text export and A4 PDF export.

Features

• Four moods: Humorous, Optimistic, Pessimistic and Ominous
• Batch generation: Generate from 1 to 500 fortunes at a time
• Optional seed: Use an integer seed for repeatable generation
• Selectable preview: Review generated fortunes, select or deselect individual entries and apply the selection before export
• TXT export: Save the current preview as a UTF-8 .txt file
• Printable PDF export: Generate A4 PDF sheets with fortune slips and cutting boundaries
• Offline operation: Fortune generation and export do not require an internet connection
• Bundled font: PDF output uses the included Noto Sans font

Language support: FortuneForge v1.0.0 includes English fortune content only. Turkish and Polish content are planned for v2.0.

Requirements

• Python 3.12 or later
• Tkinter support in the Python installation

FortuneForge uses ReportLab for PDF generation.

Installation

Clone the repository and enter the project directory:

git clone https://github.com/SKR-35/Fortune-Forge.git
cd Fortune-Forge

Create and activate a virtual environment if desired, then install FortuneForge with its development dependencies:

pip install -e ".[dev]"

This installs the application together with pytest and Ruff for development and validation.

Release Package

Pre-built release packages are available from the GitHub Releases page.

For a standard installation, download the .whl file for the desired version and install it with:

python -m pip install fortuneforge-1.0.0-py3-none-any.whl

The source distribution (.tar.gz) is also provided with each release.

Running FortuneForge

Launch the application as a Python module:

python -m fortuneforge.app

After installation, the console entry point is also available:

fortuneforge

Usage

1. Launch FortuneForge.

2. Choose one of the four available moods.

3. Enter a quantity from 1 to 500.

4. Optionally enter an integer seed.

5. Select Generate.

6. Review the generated fortunes in the preview.

7. Select or deselect individual fortunes as needed.

8. Select Apply Selection to keep only the chosen fortunes in the current preview.

9. Export the current preview as either:

   • a UTF-8 text file with Export TXT or
   • a printable A4 PDF with Export PDF.

Changing the generation controls does not modify the current preview until a new batch is successfully generated.

Seeded generation

Leaving the seed field blank produces an unseeded batch.

Providing an integer seed makes generation repeatable for the same application version, content, mood, quantity and seed. For example:

Mood: Optimistic
Quantity: 20
Seed: 42

PDF Output

PDF export is designed for printing fortune slips on A4 paper.

The exporter uses ReportLab and the bundled NotoSans-Regular.ttf font. Fortunes are laid out in bordered slips that can be cut after printing. Generated fortune candidates are checked against the PDF layout so that selected content fits the configured slip dimensions.

The bundled Noto Sans font is distributed under the SIL Open Font License 1.1.

Development

Install the project with development dependencies:

pip install -e ".[dev]"

Run the test suite:

pytest

Run Ruff:

ruff check .

Check formatting:

ruff format --check .

The project targets Python 3.12 for Ruff.

Continuous Integration

GitHub Actions runs the project quality checks on pushes and pull requests using Python 3.12 and 3.14

The CI workflow:

Install project and development dependencies
→ Check formatting with Ruff
→ Run Ruff linting
→ Run pytest

v1.0.0 Scope

FortuneForge 1.0.0 intentionally has a focused scope:

• English fortune content
• Humorous, Optimistic, Pessimistic and Ominous moods
• Desktop GUI generation workflow
• Selectable preview
• Batch quantities from 1 to 500
• Optional seeded generation
• UTF-8 TXT export
• Printable A4 PDF export
• Offline operation

Turkish and Polish fortune content are planned for v2.0 and are not supported as selectable content in v1.0.0.

Technology

• Python 3.12+
• Tkinter
• ReportLab
• pytest
• Ruff
• GitHub Actions

License

FortuneForge is licensed under the Apache License 2.0.

The bundled Noto Sans font is separately licensed under the SIL Open Font License 1.1.