# 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** - Experimental (coming soon)
## 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
## Installation
### Recommended: Using uv
```bash
uv tool install StoryForge
```
If you don't have uv:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### Alternative: Using pipx
```bash
pipx install StoryForge
```
If you don't have pipx:
```bash
# 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](https://aistudio.google.com/) to get your free Gemini API key
2. Set the environment variable:
```bash
export GEMINI_API_KEY=your_api_key_here
```
### OpenAI
1. Get your API key from [OpenAI Platform](https://platform.openai.com/api-keys)
2. Set the environment variable:
```bash
export OPENAI_API_KEY=your_api_key_here
```
### Anthropic (Experimental)
1. Get your API key from [Anthropic Console](https://console.anthropic.com/)
2. Set the environment variable:
```bash
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:
```bash
# 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
```bash
storyforge "Tell me a story about a robot learning to make friends"
```
### Generate Just an Image
```bash
storyforge image "A friendly robot in a colorful playground"
```
### Interactive Mode
```bash
storyforge tui
```
### Advanced Options
```bash
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`
- **Tone**: `gentle`, `exciting`, `silly`, `heartwarming`, `magical`
- **Theme**: `courage`, `kindness`, `teamwork`, `problem_solving`, `creativity`
- **Image Style**: `chibi`, `realistic`, `cartoon`, `watercolor`, `sketch`
## Tab Completion
Enable tab completion for easier CLI usage:
```bash
storyforge --install-completion
```
Or manually for bash/zsh:
```bash
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`](DEV.md).
## License
MIT License - see [`LICENSE`](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "StoryForge",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ai, stories, children, cli, gemini, image-generation, text-generation, tui, storytelling, terminal",
"author": "wom",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/aa/e0/83aba27dbe835ca72049ed1a26025a27bc551ef338569977839f9758e6c7/storyforge-0.0.3.tar.gz",
"platform": null,
"description": "# StoryForge\n\nStoryForge 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.\n\n## Supported AI Backends\n\n- **Google Gemini** - Fully supported for story and image generation\n- **OpenAI** - Fully supported for story and image generation\n- **Anthropic** - Experimental (coming soon)\n\n## Features\n\n- \ud83d\udcd6 Generate custom children's stories from simple prompts\n- \ud83c\udfa8 Create AI illustrations with multiple art styles (chibi, realistic, cartoon, watercolor, sketch)\n- \u2699\ufe0f Flexible story customization (age range, length, tone, theme, learning focus)\n- \ud83d\udcbe Save stories and images with organized output directories\n- \ud83d\udda5\ufe0f Interactive terminal interface or direct CLI usage\n- \ud83d\udcda Context system for character consistency across stories\n\n## Installation\n\n### Recommended: Using uv\n\n```bash\nuv tool install StoryForge\n```\n\nIf you don't have uv:\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n### Alternative: Using pipx\n\n```bash\npipx install StoryForge\n```\n\nIf you don't have pipx:\n\n```bash\n# macOS: brew install pipx\n# Ubuntu/Debian: sudo apt install pipx\n# Or: pip install pipx\n```\n\n## Setup\n\nChoose one of the supported AI backends and configure the corresponding API key:\n\n### Google Gemini\n\n1. Visit [Google AI Studio](https://aistudio.google.com/) to get your free Gemini API key\n2. Set the environment variable:\n\n```bash\nexport GEMINI_API_KEY=your_api_key_here\n```\n\n### OpenAI\n\n1. Get your API key from [OpenAI Platform](https://platform.openai.com/api-keys)\n2. Set the environment variable:\n\n```bash\nexport OPENAI_API_KEY=your_api_key_here\n```\n\n### Anthropic (Experimental)\n\n1. Get your API key from [Anthropic Console](https://console.anthropic.com/)\n2. Set the environment variable:\n\n```bash\nexport ANTHROPIC_API_KEY=your_api_key_here\n```\n\n### Environment Variables\n\n| Variable | Backend | Status | Description |\n|----------|---------|---------|-------------|\n| `GEMINI_API_KEY` | Google Gemini | \u2705 Fully Supported | Required for Gemini backend |\n| `OPENAI_API_KEY` | OpenAI | \u2705 Fully Supported | Required for OpenAI backend |\n| `ANTHROPIC_API_KEY` | Anthropic | \ud83e\uddea Experimental | Required for Anthropic backend (coming soon) |\n| `LLM_BACKEND` | All | Optional | Force specific backend (`gemini`, `openai`, `anthropic`) |\n\n**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.\n\nAdd environment variables to your shell profile (`.bashrc`, `.zshrc`, etc.) to make them permanent:\n\n```bash\n# Example for Gemini\necho 'export GEMINI_API_KEY=your_api_key_here' >> ~/.bashrc\nsource ~/.bashrc\n\n# Example for OpenAI\necho 'export OPENAI_API_KEY=your_api_key_here' >> ~/.bashrc\nsource ~/.bashrc\n```\n\n## Usage\n\n### Basic Story Generation\n\n```bash\nstoryforge \"Tell me a story about a robot learning to make friends\"\n```\n\n### Generate Just an Image\n\n```bash\nstoryforge image \"A friendly robot in a colorful playground\"\n```\n\n### Interactive Mode\n\n```bash\nstoryforge tui\n```\n\n### Advanced Options\n\n```bash\nstoryforge \"A brave mouse goes on an adventure\" \\\n --age-range preschool \\\n --length short \\\n --tone exciting \\\n --image-style cartoon \\\n --output-dir my_story\n```\n\n#### Available Options\n\n- **Age Range**: `toddler`, `preschool`, `early_reader`, `middle_grade`\n- **Length**: `flash`, `short`, `medium`, `bedtime`\n- **Style**: `adventure`, `comedy`, `fantasy`, `fairy_tale`, `friendship`\n- **Tone**: `gentle`, `exciting`, `silly`, `heartwarming`, `magical`\n- **Theme**: `courage`, `kindness`, `teamwork`, `problem_solving`, `creativity`\n- **Image Style**: `chibi`, `realistic`, `cartoon`, `watercolor`, `sketch`\n\n## Tab Completion\n\nEnable tab completion for easier CLI usage:\n\n```bash\nstoryforge --install-completion\n```\n\nOr manually for bash/zsh:\n\n```bash\neval \"$(storyforge --show-completion)\"\n```\n\n## Output\n\nStoryForge creates timestamped directories containing:\n- `story.txt` - The generated story\n- `*.png` - AI-generated illustrations\n- Organized by creation date/time\n\n## Development\n\nFor development setup, testing, and contributing guidelines, see [`DEV.md`](DEV.md).\n\n## License\n\nMIT License - see [`LICENSE`](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "A TUI app that generates short stories and AI images from prompts using a language model.",
"version": "0.0.3",
"project_urls": {
"Bug Tracker": "https://github.com/wom/StoryForge/issues",
"Documentation": "https://github.com/wom/StoryForge#readme",
"Homepage": "https://github.com/wom/StoryForge",
"Repository": "https://github.com/wom/StoryForge"
},
"split_keywords": [
"ai",
" stories",
" children",
" cli",
" gemini",
" image-generation",
" text-generation",
" tui",
" storytelling",
" terminal"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cc24c9b56ed0c7f6684a8d41687f730d35ff3b4568532a72d61c57c1013d512b",
"md5": "7ddf5c1e4ce45c7c66c8317266a188f9",
"sha256": "cc3bde43490ba07cda4688993f0eef9e6ec968e434cdaf1bfb124d0d3fc5ef48"
},
"downloads": -1,
"filename": "storyforge-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7ddf5c1e4ce45c7c66c8317266a188f9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 27382,
"upload_time": "2025-08-14T05:43:04",
"upload_time_iso_8601": "2025-08-14T05:43:04.065082Z",
"url": "https://files.pythonhosted.org/packages/cc/24/c9b56ed0c7f6684a8d41687f730d35ff3b4568532a72d61c57c1013d512b/storyforge-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "aae083aba27dbe835ca72049ed1a26025a27bc551ef338569977839f9758e6c7",
"md5": "f1f438d7be65a12d16755d8c9a592146",
"sha256": "9b5cdbf35cfde1bf3ba5942a079dbac7432b9e7b0217325d3b047e39bdf662f7"
},
"downloads": -1,
"filename": "storyforge-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "f1f438d7be65a12d16755d8c9a592146",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 33097,
"upload_time": "2025-08-14T05:43:05",
"upload_time_iso_8601": "2025-08-14T05:43:05.406559Z",
"url": "https://files.pythonhosted.org/packages/aa/e0/83aba27dbe835ca72049ed1a26025a27bc551ef338569977839f9758e6c7/storyforge-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-14 05:43:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wom",
"github_project": "StoryForge",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "storyforge"
}
JSON
