Metadata-Version: 2.4
Name: storytelling
Version: 0.2.9
Summary: AI-powered narrative generation system implementing Software 3.0 methodology - The Soul of Your Story's Blueprint
Author-email: JGWill <jgwill@example.com>
Maintainer: JGWill
License: MIT
Project-URL: Homepage, https://github.com/jgwill/storytelling
Project-URL: Repository, https://github.com/jgwill/storytelling
Project-URL: Documentation, https://github.com/jgwill/storytelling/blob/main/README.md
Project-URL: Issues, https://github.com/jgwill/storytelling/issues
Keywords: narrative-generation,ai-writing,software-3.0,creative-writing,story-generation,langchain,langgraph,rag,llm,ollama,interactive-storytelling,worldbuilding
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Games/Entertainment
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: langchain>=0.1.0
Requires-Dist: langgraph>=0.0.40
Requires-Dist: langchain-community>=0.0.20
Requires-Dist: langchain-openai>=0.0.8
Requires-Dist: langchain-ollama>=0.0.1
Requires-Dist: faiss-cpu>=1.7.4
Requires-Dist: termcolor>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0
Provides-Extra: local-ml
Requires-Dist: sentence-transformers>=2.2.2; extra == "local-ml"
Requires-Dist: langchain-huggingface>=0.0.1; extra == "local-ml"
Provides-Extra: google
Requires-Dist: langchain-google-genai>=0.0.6; extra == "google"
Provides-Extra: cloud
Requires-Dist: langfuse>=2.0.0; extra == "cloud"
Requires-Dist: openai>=1.0.0; extra == "cloud"
Provides-Extra: rag
Requires-Dist: unstructured>=0.13.0; extra == "rag"
Requires-Dist: langchain-text-splitters>=0.0.1; extra == "rag"
Provides-Extra: enhanced
Requires-Dist: storytelling[cloud,rag]; extra == "enhanced"
Requires-Dist: beautifulsoup4>=4.12.0; extra == "enhanced"
Requires-Dist: html2text>=2020.1.16; extra == "enhanced"
Requires-Dist: requests>=2.31.0; extra == "enhanced"
Provides-Extra: web
Requires-Dist: requests>=2.31.0; extra == "web"
Requires-Dist: beautifulsoup4>=4.12.0; extra == "web"
Requires-Dist: html2text>=2020.1.16; extra == "web"
Provides-Extra: mcp
Requires-Dist: requests>=2.31.0; extra == "mcp"
Provides-Extra: iaip
Requires-Dist: pyyaml>=6.0.0; extra == "iaip"
Requires-Dist: storytelling[enhanced,mcp]; extra == "iaip"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=6.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"
Requires-Dist: myst-parser>=1.0.0; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Requires-Dist: pytest-mock>=3.0; extra == "test"
Provides-Extra: all
Requires-Dist: storytelling[cloud,enhanced,google,iaip,local-ml,mcp,web]; extra == "all"
Provides-Extra: complete
Requires-Dist: storytelling[all]; extra == "complete"
Dynamic: license-file

# Storytelling: Turn Your Ideas Into Complete Narratives

Transform a simple story idea into a fully-written, multi-chapter narrative. **WillWrite** is an AI-powered storytelling partner that handles the heavy lifting—outline generation, chapter planning, scene development, and revision—so you can focus on your creative vision.

## What It Does

**Create complete stories in minutes.** You provide a story prompt. The system generates:

- A structured outline with plot, characters, and themes
- Individual chapters with detailed chapter outlines
- Four polished scenes per chapter
- Multiple revision passes for consistency and quality
- Session persistence—pause and resume anytime

**Powered by advanced AI orchestration.** Built on LangGraph and LangChain with multi-LLM provider support, knowledge-base integration, and intelligent retrieval-augmented generation (RAG).

## Getting Started

### Installation

```bash
# Basic installation
pip install storytelling

# With full features (web fetching, local embeddings, cloud logging)
pip install storytelling[all]
```

### Your First Story

```bash
# Create a prompt file
echo "A detective discovers a mysterious library" > my_prompt.txt

# Generate your story
storytelling --prompt my_prompt.txt --output my_story.md
```

Your completed story appears in `my_story.md`.

### Using Your Own LLMs

```bash
# With local Ollama
storytelling --prompt prompt.txt \
  --initial-outline-model "ollama://mistral@localhost:11434"

# With Google Gemini
storytelling --prompt prompt.txt \
  --initial-outline-model "google://gemini-2.5-flash"
```

## Key Features

**Flexible AI Providers**
- Google (Gemini, PaLM)
- Ollama (local models)
- OpenRouter (community models)
- Custom endpoints

**Knowledge-Aware Generation**
- Integrate your own knowledge bases
- Web content retrieval
- Semantic context enhancement
- Consistent worldbuilding

**Session Management**
- Pause and resume at any stage
- Checkpoint-based recovery
- Narrative branching
- Full generation history

**Production Ready**
- Comprehensive logging with Langfuse
- Type-safe with Pydantic
- Configurable for various use cases
- Extensible architecture

## Command Line

```bash
storytelling --help                    # See all options
storytelling --prompt file.txt         # Generate story
storytelling --list-sessions           # See your past sessions
storytelling --resume <session-id>     # Continue a session
```

## Documentation

- **Full Setup Guide**: See `scripts/init.sh` for environment setup
- **Architecture**: Check `rispecs/` directory for detailed specifications
- **Specifications**: `RISPECS.md` contains implementation architecture
- **Prompts & Models**: `rispecs/Prompts.md` and `rispecs/LLM_Provider_Specification.md`

## Development

```bash
# Setup development environment
./scripts/init.sh

# Run tests
make test

# Check code quality
make lint

# Build and release
make release-check
```

## License

CC0-1.0 License - See [LICENSE](LICENSE)
