An AI-powered application for creating personalized, illustrated storybooks for young children.

Storyteller helps parents and older children collaboratively create custom storybooks for younger children (pre-reading to primary school age). The application runs entirely locally without internet connectivity after installation, ensuring privacy and offline availability.

• Interactive Story Creation - AI guides authors through the storytelling process, prompting for details, filling narrative gaps, and maintaining story structure
• AI-Generated Illustrations - Create engaging, child-appropriate illustrations using local image generation
• Fully Offline - All AI processing happens locally on your machine
• Export to Print - Generate print-ready PDF storybooks

Rather than generating entire stories from a single prompt, Storyteller emphasizes an interactive creation process where:

• The AI asks guiding questions about characters, settings, and plot
• Authors maintain creative control while receiving assistance
• Stories develop through collaborative dialogue
• The final product reflects the author's vision, enhanced by AI

• macOS with Apple Silicon (M1/M2/M3/M4)
• 32GB RAM (recommended)
• 50GB free disk space (for AI models)

• Python 3.10+
• macOS 13.0+ (Ventura or later)

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/hherb/storyteller.git
cd storyteller

# Install dependencies (creates venv automatically)
uv sync

The first run will download required AI models (~25-35GB total):

• Image generation model (FLUX via MFLUX): ~12-23GB
• Language model (via Ollama): ~8-14GB

storyteller/
├── src/storyteller/          # Main application package
│   ├── core/                 # Story engine, book management, export
│   ├── ui/                   # Flet-based GUI components
│   └── generation/           # AI text and image generation
├── tests/                    # Test suite
├── prototypes/               # Experimental code and evaluations
│   └── mflux_test/          # Image generation quality testing
├── docs/                     # Documentation
│   ├── user/                # End-user guides
│   ├── developers/          # Developer documentation
│   ├── llm/                 # AI assistant reference
│   └── planning/            # Roadmaps and technical decisions
├── CLAUDE.md                # AI assistant guidelines
└── pyproject.toml           # Project configuration

🚧 Early Development - This project is in the prototyping phase.

• Project structure and configuration
• MFLUX image generation prototype
• LLM integration for story guidance
• Flet GUI implementation
• Story engine and page management
• PDF export functionality
• macOS installer packaging

Test image generation quality:

cd prototypes/mflux_test
uv sync

# Generate test images
uv run python generate_test_images.py --test-suite

# Generate single image
uv run python generate_test_images.py --prompt "A friendly bear in the forest" --output bear.png

(Coming soon)

# Start the Storyteller application
python -m storyteller

Contributions are welcome! Please read our development guidelines in CLAUDE.md for code style and architecture decisions.

# Install with all development dependencies
uv sync --all-extras

# Run tests
uv run pytest

# Run linting
uv run ruff check src/

# Type checking
uv run mypy src/

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

• Black Forest Labs for FLUX image generation models
• Apple MLX Team for the MLX framework
• MFLUX Contributors for the Apple Silicon port
• Flet Team for the Python UI framework