Bodhisattva Challenge Illustration Generator

Tooling that turns daily Bodhisattva Challenge verse/practice text into finished social-media post images: batch-generates line-art illustrations with Gemini, then composes them with text into branded 1080x1920 posts (English, Tibetan, and Hindi).

Owner(s)

• @ngawangtrinley
• @mikkokotila
• @evanyerburgh

Table of contents

Project description • Who this project is for • Project dependencies • Instructions for use • Contributing guidelines • How to get help • Terms of use

---

Project description

This project automates production of the daily Bodhisattva Challenge posts for @WeBuddhist. It has three stages, each a standalone CLI script under src/illustration_generator/:

1. generate_illustrations.py — Parses a folder of day_NN_sharable_image_text.md files (verse of the day in English, Tibetan, and Hindi), matches each day to its Tibetan and English day-plan files to pull in the daily "challenge" (practice + explanation), and submits a batch job to Gemini 3 Pro Image to generate one combined line-art illustration per day (Tibetan verse as the primary text, other languages as context), saving each with a transparent background as data/illustrations/Day<N>-ch<C>.png.
2. compose_challenge_post.py — Composes a single-language (English) daily "challenge" post: title, bold practice, illustration, left-aligned verse with right-aligned verse id citation, and the @WeBuddhist handle, rendered onto a background template.
3. compose_multilang_post.py — Composes the same style of post in three languages (English, Tibetan, Hindi) from one day_NN_sharable_image_text.md file containing all three language sections, producing one image per language under data/output/<language>/day{N}.png.
4. generate_preview_post.py — Generates an alternate "preview" post layout (verse + explanation + bottom-anchored illustration) matching a reference template, with an optional --compare mode to measure pixel difference against a reference image.

Who this project is for

This project is intended for the OpenPecha/WeBuddhist team producing the daily Bodhisattva Challenge social media content, who want to generate illustrations and compose branded post images from markdown source text.

Project dependencies

Before using this project, ensure you have:

• Python >= 3.8 (Tibetan/Hindi text uses list[str]/str | None syntax, so 3.10+ recommended)
• A Gemini API key (set as the GEMINI_KEY environment variable) for generate_illustrations.py
• Pillow built with libraqm for correct Tibetan/Devanagari text shaping (used by compose_multilang_post.py). Verify with:

  python -c "import PIL.features as f; print(f.check('raqm'))"

• Bundled fonts under src/illustration_generator/fonts/ (already included in the repo)

Instructions for use

Install

pip install -e .
# or with dev/test dependencies
pip install -e ".[dev]"

Configure

Export your Gemini API key (only required for generate_illustrations.py):

export GEMINI_KEY="your-api-key-here"

generate_illustrations.py also reads the daily "challenge" (practice + explanation) from two vault folders outside this repo. Defaults point at the bodhisattvacharyavatara-rails Obsidian vault; override with environment variables if your checkout lives elsewhere:

export DALAI_LAMA_PLANS_DIR="/path/to/bodhisattvacharyavatara-rails/3-TRANSFORMATIONS/Plans/Dalai Lama"
export EN_CHALLENGE_DAYS_DIR="/path/to/bodhisattvacharyavatara-rails/3-TRANSFORMATIONS/Plans/the-bodhisattva-challenge/en/Days"

Run

1. Generate illustrations from a Sharable-Images folder:

python -m illustration_generator.generate_illustrations path/to/Sharable-Images

Processes every day_NN_sharable_image_text.md file in the folder. For each day it: reads the verse of the day (English/Tibetan/Hindi), locates the matching Tibetan and English day-plan files by day + chapter number to pull in that day's practice + explanation, and generates one combined illustration per day, saved to data/illustrations/Day<N>-ch<C>.png with a transparent background. Days whose output file already exists are skipped.

2. Compose a single-language challenge post:

# from a daily folder containing a 06_July.md and one illustration PNG
python -m illustration_generator.compose_challenge_post path/to/06_July_folder

# or pass files explicitly
python -m illustration_generator.compose_challenge_post path/to/06_July.md path/to/illustration.png

3. Compose multi-language (English/Tibetan/Hindi) posts:

python -m illustration_generator.compose_multilang_post \
  path/to/day_20_sharable_image_text.md \
  path/to/illustration_or_dir \
  --output path/to/output_dir

Outputs output_dir/english/day20.png, output_dir/tibetan/day20.png, and output_dir/hindi/day20.png (default output dir is data/output/).

4. Generate a preview-style post:

python -m illustration_generator.generate_preview_post path/to/06_July_folder
# optionally compare against a reference image
python -m illustration_generator.generate_preview_post path/to/06_July_folder --compare data/17.jpg

Troubleshoot

Issue	Solution
GEMINI_KEY environment variable not set	Export GEMINI_KEY with a valid Gemini API key before running generate_illustrations.py.
Tibetan/Devanagari text renders incorrectly (no stacking/conjuncts)	Rebuild Pillow with libraqm support; verify with the snippet in Project dependencies.
No date markdown file like 06_July.md found / Multiple date markdown files found	Ensure the target folder has exactly one markdown file matching the expected naming pattern.
Missing required field(s) when parsing markdown	Confirm the markdown file has the expected headings (e.g. Practice of the day, Verse of the day, Verse id).

Contributing guidelines

If you'd like to help out, check out our contributing guidelines.

How to get help

• File an issue.
• Email us at openpecha[at]gmail.com.
• Join our discord.

Terms of use

This project is licensed under the MIT License.