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 storygenerator 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.

How It Works

  1. Generate story content (outline or pages)
  2. Evaluate across 11 quality categories (1-5 scale with explanations)
  3. Improve the prompt based on evaluation feedback
  4. Validate that all template placeholders are preserved
  5. Track scores in statistics.csv for analysis
  6. Repeat for N iterations

Evaluation Categories

The system evaluates generated content 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

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

Command Line Options

  • --mode - Type of prompt to optimize: outline or pages (required)
  • --iterations - Number of optimization iterations (default: 10)
  • --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)

Output

The optimization system produces:

  1. Updated prompt templates in prompt_templates/

    • story_outline_prompt.txt
    • story_page_prompt.txt
  2. Statistics CSV (statistics.csv) with columns:

    • timestamp, mode, iteration, prompt_version
    • All 11 category scores (1-5)
    • average_score
  3. Console output showing:

    • Current iteration progress
    • Evaluation scores per category
    • Improvement suggestions
    • Placeholder validation results

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 storygenerator 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for storygenerator 0.1.1
File Size Uploaded Provenance Actions
storygenerator-0.1.1.tar.gz 26.2 kB Without provenance Details for storygenerator-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for storygenerator 0.1.1
File Interpreter ABI Platform Actions
storygenerator-0.1.1-py3-none-any.whl Python 3 none any Details for storygenerator-0.1.1-py3-none-any.whl

Total release size: 50.4 kB

Release files / storygenerator-0.1.1.tar.gz

Download URL storygenerator-0.1.1.tar.gz
Size 26.2 kB
Tags Source
SHA-256 checksum
How to use checksums
18e61f1ec0cbad91d11f0894c00cb0c537827acc7a04b47267dd1b498793c42a
BLAKE2b-256 checksum
How to use checksums
bfecd8536bbb1703c4de2b10d3c8ee29de702583a540a3221c6bf53428a61b22
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.7.19

Release files / storygenerator-0.1.1-py3-none-any.whl

Download URL storygenerator-0.1.1-py3-none-any.whl
Size 24.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7462194c3b5d62b49825f4cf1ff7a30974866101a69191f685c82d5f7f19a13c
BLAKE2b-256 checksum
How to use checksums
7a23f6d9f1391b30e4f5f1dc9bb8d2efb90473cfa0ce6b01e9e22abbf679770d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.7.19

Security for storygenerator 0.1.1

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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

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