Skip to main content

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

  1. Get a PyPI API token from https://pypi.org/manage/account/token/
  2. Set the token:
    export PYPI_TOKEN="pypi-your-token-here"
    
  3. 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

  1. outline - Optimizes story structure and outline generation
  2. pages - Optimizes page text generation
  3. images - Optimizes image generation prompts for child resemblance and story accuracy

How It Works

  1. Generate story content (outline, pages, or images)
  2. Evaluate quality with LLM scoring (1-5 scale with explanations)
  3. Improve prompts based on evaluation feedback
  4. Validate that all template placeholders are preserved
  5. Track scores in CSV for analysis
  6. 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, or images (required)
  • --iterations - Number of optimization iterations (default: 10)
  • --reference-image - Path to reference photo of child (required for images mode)
  • --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:

  1. 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
  2. Statistics CSV with scores over time:

    • Text modes: statistics.csv
    • Images mode: image_statistics.csv
  3. Detailed logs with evaluation explanations and improvement suggestions:

    • Text modes: optimization.log
    • Images mode: image_optimization.log

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)

Source distribution for dailystories-generator 0.2.11
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)

Table of built distributions (wheels) for dailystories-generator 0.2.11
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page