StoryForge 0.0.4

A TUI app that generates short stories and AI images from prompts using a language model.

StoryForge

StoryForge is a command-line tool that generates illustrated children's stories using AI language models. Simply provide a story prompt, and StoryForge will create both a short story and accompanying AI-generated images.

Supported AI Backends

• Google Gemini - Fully supported for story and image generation
• OpenAI - Fully supported for story and image generation
• Anthropic - Supported for story (text) generation only; image generation is not currently supported by this backend

Features

• 📖 Generate custom children's stories from simple prompts
• 🎨 Create AI illustrations with multiple art styles (chibi, realistic, cartoon, watercolor, sketch)
• ⚙️ Flexible story customization (age range, length, tone, theme, learning focus)
• 💾 Save stories and images with organized output directories
• 🖥️ Interactive terminal interface or direct CLI usage
• 📚 Context system for character consistency across stories
• ⏯️ Checkpoint system for resuming interrupted sessions

Configuration

For detailed configuration options, defaults, and examples see the full configuration reference:

• docs/CONFIGURATION.md — field-by-field reference and example config file

You can generate a default config file programmatically with the Config.create_default_config() helper or use the STORYFORGE_CONFIG environment variable to point to a specific config file.

Checkpoint System

StoryForge automatically saves your progress during story generation, allowing you to resume from any point if the process is interrupted or if you want to retry different options.

Resume from Previous Sessions

storyforge --continue

This will show you the last 5 sessions and let you choose:

• For interrupted sessions: Resume from where you left off
• For completed sessions: Choose to:
  • Generate new images with the same story
  • Modify and regenerate the story
  • Save the story as context for future use
  • Start completely over with the same parameters

Checkpoint Storage

Checkpoint files are automatically stored in:

• Linux/macOS: ~/.local/share/StoryForge/checkpoints/
• Windows: %APPDATA%\StoryForge\StoryForge\checkpoints\

The system automatically cleans up old checkpoints, keeping the 15 most recent sessions.

Example Workflow

# Start a story generation
storyforge "A dragon learning to dance"
# If interrupted, resume later with:
storyforge --continue
# Select your session and choose where to resume

Installation

Recommended: Using uv

uv tool install StoryForge

If you don't have uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Alternative: Using pipx

pipx install StoryForge

If you don't have pipx:

# macOS: brew install pipx
# Ubuntu/Debian: sudo apt install pipx
# Or: pip install pipx

Setup

Choose one of the supported AI backends and configure the corresponding API key:

Google Gemini

1. Visit Google AI Studio to get your free Gemini API key
2. Set the environment variable:

export GEMINI_API_KEY=your_api_key_here

OpenAI

1. Get your API key from OpenAI Platform
2. Set the environment variable:

export OPENAI_API_KEY=your_api_key_here

Anthropic (Experimental)

1. Get your API key from Anthropic Console
2. Set the environment variable:

export ANTHROPIC_API_KEY=your_api_key_here

Environment Variables

Variable	Backend	Status	Description
GEMINI_API_KEY	Google Gemini	✅ Fully Supported	Required for Gemini backend
OPENAI_API_KEY	OpenAI	✅ Fully Supported	Required for OpenAI backend
ANTHROPIC_API_KEY	Anthropic	🧪 Experimental	Required for Anthropic backend (coming soon)
LLM_BACKEND	All	Optional	Force specific backend (gemini, openai, anthropic)

Note: StoryForge will automatically detect which backend to use based on available API keys. If multiple keys are set, you can specify which backend to use with the LLM_BACKEND environment variable.

Add environment variables to your shell profile (.bashrc, .zshrc, etc.) to make them permanent:

# Example for Gemini
echo 'export GEMINI_API_KEY=your_api_key_here' >> ~/.bashrc
source ~/.bashrc

# Example for OpenAI
echo 'export OPENAI_API_KEY=your_api_key_here' >> ~/.bashrc
source ~/.bashrc

Usage

Basic Story Generation

storyforge "Tell me a story about a robot learning to make friends"

Interactive prompts

The CLI is interactive and will ask for confirmation and decisions during the run (for images, story refinements, etc.). There is not a separate tui subcommand in this version of the code.

Advanced Options

storyforge "A brave mouse goes on an adventure" \
  --age-range preschool \
  --length short \
  --tone exciting \
  --image-style cartoon \
  --output-dir my_story

Available Options

• Age Range: toddler, preschool, early_reader, middle_grade
• Length: flash, short, medium, bedtime
• Style: adventure, comedy, fantasy, fairy_tale, friendship, random
• Tone: gentle, exciting, silly, heartwarming, magical, random
• Theme: courage, kindness, teamwork, problem_solving, creativity, random
• Image Style: chibi, realistic, cartoon, watercolor, sketch

Tab Completion

Enable tab completion for easier CLI usage:

storyforge --install-completion

Or manually for bash/zsh:

eval "$(storyforge --show-completion)"

Output

StoryForge creates timestamped directories containing:

• story.txt - The generated story
• *.png - AI-generated illustrations
• Organized by creation date/time

Development

For development setup, testing, and contributing guidelines, see DEV.md.

License

MIT License - see LICENSE file for details.