DailyStories Generator
A Python library for generating children's storybooks using Google's Gemini AI.
Installation
# From PyPI
pip install dailystories-generator
# Or with uv
uv pip install dailystories-generator
Building and Publishing
Build
./build.sh
This creates distribution files in dist/ directory.
Publish to PyPI
- Get a PyPI API token from https://pypi.org/manage/account/token/
- Set the token:
export PYPI_TOKEN="pypi-your-token-here"
- Publish:
./publish.sh
The publish script will automatically build the package before publishing.
Quick Test
# Set your API key
export GOOGLE_API_KEY="your-gemini-api-key-here"
# Run a simple test
uv run python test.py
# Or test outline-only (faster)
uv run python test.py --outline-only
# Or test without images (faster)
uv run python test.py --no-images
Usage
from dailystories_generator import StoryGenerator, GenerationRequest, UpdateType
async def on_update(update):
print(f"Update: {update.type}")
if update.type == UpdateType.PAGE_COMPLETE:
print(f"Page {update.data['page_number']} completed")
generator = StoryGenerator(gemini_api_key="your-api-key")
request = GenerationRequest(
title="The Adventure Begins",
summary="A tale of courage and friendship",
num_pages=10,
child_name="Alex",
child_age=6,
language="English",
illustration_style="watercolor",
generate_images=True,
)
story = await generator.generate(request, on_update=on_update)
print(f"Story generated with {len(story.pages)} pages")
Features
- Async story generation with Gemini AI
- Optional image generation
- Support for multiple reference images
- Type-safe with full type annotations
- Callback-based progress updates
- Prompt optimization system for iterative improvement
Prompt Optimization
The library includes a powerful prompt optimization system that automatically improves story generation prompts through iterative evaluation and feedback.
Modes
- outline - Optimizes story structure and outline generation
- pages - Optimizes page text generation
- images - Optimizes image generation prompts for child resemblance and story accuracy
How It Works
- Generate story content (outline, pages, or images)
- Evaluate quality with LLM scoring (1-5 scale with explanations)
- Improve prompts based on evaluation feedback
- Validate that all template placeholders are preserved
- Track scores in CSV for analysis
- Repeat for N iterations
Evaluation Categories
Text modes (outline/pages) evaluate on:
- creativity - Originality and imaginativeness
- age_appropriateness - Suitable content and vocabulary for target age
- coherence - Logical flow and narrative consistency
- engagement - How captivating for young readers
- language_quality - Grammar and writing style
- plot_structure - Clear beginning/middle/end
- character_development - Growth and relatability
- character_introduction - How well characters are established
- emotional_resonance - Emotional depth and impact
- pacing - Story rhythm and transitions
- tone_consistency - Maintaining age-appropriate tone
Images mode evaluates on:
- child_resemblance - How well the character matches the reference photo (hair, face, clothing, accessories)
- story_capture (cover) - How well the cover represents the story theme
- page_content_accuracy (pages) - How well illustrations depict the page text
- style_consistency (pages) - Artistic consistency and character appearance across pages
Running Optimization
# Set your API key
export GOOGLE_API_KEY="your-gemini-api-key-here"
# Optimize the outline prompt (50 iterations)
uv run python optimize_prompts.py --mode outline --iterations 50 \
--child-name Ludwig --child-age 6 \
--title "The Magical Adventure" \
--summary "A child discovers magic and goes on an adventure" \
--language Norwegian
# Optimize the page generation prompt (20 iterations)
uv run python optimize_prompts.py --mode pages --iterations 20 \
--child-name Emma --child-age 7 \
--num-pages 5 \
--language English
# Optimize image generation prompts (10 iterations)
uv run python optimize_prompts.py --mode images --iterations 10 \
--reference-image photo.png \
--child-name Ludwig --child-age 6 \
--num-pages 5
Command Line Options
--mode- Type of prompt to optimize:outline,pages, orimages(required)--iterations- Number of optimization iterations (default: 10)--reference-image- Path to reference photo of child (required forimagesmode)--child-name- Child's name for test story (default: Alex)--child-age- Child's age for test story (default: 6)--title- Story title (default: The Magical Adventure)--summary- Story theme/summary--num-pages- Number of pages (default: 5)--language- Story language (default: English)--illustration-style- Illustration style for images mode (default: colorful watercolor illustration)
Output
The optimization system produces:
-
Updated prompt templates in
prompt_templates/- Text modes:
story_outline_prompt.txt,story_page_prompt.txt - Images mode:
cover_image_reference_prompt.txt,page_image_reference_prompt.txt
- Text modes:
-
Statistics CSV with scores over time:
- Text modes:
statistics.csv - Images mode:
image_statistics.csv
- Text modes:
-
Detailed logs with evaluation explanations and improvement suggestions:
- Text modes:
optimization.log - Images mode:
image_optimization.log
- Text modes:
Analyzing Results
Use the statistics.csv file to plot score trajectories over iterations:
import pandas as pd
import matplotlib.pyplot as plt
df = pd.read_csv('statistics.csv')
df_outline = df[df['mode'] == 'outline']
# Plot trajectory for each category
for category in ['creativity', 'engagement', 'coherence']:
plt.plot(df_outline['iteration'], df_outline[category], label=category)
plt.xlabel('Iteration')
plt.ylabel('Score (1-5)')
plt.legend()
plt.title('Prompt Optimization Progress')
plt.show()
Automatic Retry on Placeholder Loss
The system automatically validates that all template placeholders (e.g., {child_name}, {story_so_far}) are preserved during optimization. If the LLM forgets a placeholder, it receives clear feedback and retries up to 5 times before failing.
This ensures the system can run autonomously for hours without manual intervention.
Metadata
Release files for dailystories-generator 0.2.11
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| dailystories_generator-0.2.11.tar.gz | 38.6 kB | Without provenance | Details for dailystories_generator-0.2.11.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| dailystories_generator-0.2.11-py3-none-any.whl | Python 3 | none | any | Details for dailystories_generator-0.2.11-py3-none-any.whl |
Total release size: 74.0 kB
Release files / dailystories_generator-0.2.11.tar.gz
| Download URL | dailystories_generator-0.2.11.tar.gz |
|---|---|
| Size | 38.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
44f8eb2a094bd9298180848bf6c71e5108d51e6eb841a1e3dca42b4241945eba
|
|
BLAKE2b-256 checksum How to use checksums |
78a35708bb4f7608b3724b604c41799508dc5ccf746dfdf63e7c370cdcbab765
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.7.19
|
Release files / dailystories_generator-0.2.11-py3-none-any.whl
| Download URL | dailystories_generator-0.2.11-py3-none-any.whl |
|---|---|
| Size | 35.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
76f70c5e3657f5b848c6a8b866fce8fb713858a04fd843a32a70e9f5d183fef9
|
|
BLAKE2b-256 checksum How to use checksums |
931284147fe851fa83f580d8ca92338e9a174d7f832367041a29c6ee6b44a3dc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.7.19
|
Security for dailystories-generator 0.2.11
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.