Metadata-Version: 2.4
Name: StoryForge
Version: 0.0.2
Summary: A TUI app that generates short stories and AI images from prompts using a language model.
Author: wom
License-Expression: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-genai>=1.23.0
Requires-Dist: pillow>=11.2.1
Requires-Dist: textual[syntax]>=0.54.1
Requires-Dist: textual-dev>=0.00.1
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: platformdirs>=4.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.2.0; extra == "dev"
Requires-Dist: ruff>=0.12.1; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: pre-commit>=3.6.0; extra == "dev"
Requires-Dist: pip>=25.1.1; extra == "dev"
Dynamic: license-file

# StoryForge

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

## 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

### 1. Get a Gemini API Key

Visit [Google AI Studio](https://aistudio.google.com/) to get your free Gemini API key.

### 2. Set Environment Variable

```bash
export GEMINI_API_KEY=your_api_key_here
```

Add this to your shell profile (`.bashrc`, `.zshrc`, etc.) to make it permanent.

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