Metadata-Version: 2.4
Name: df-storyteller
Version: 0.2.0
Summary: Dwarf Fortress storytelling assistant — turns game events into narrative stories
License-Expression: MIT
Keywords: dwarf-fortress,dfhack,storytelling,ai,llm,narrative
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: pydantic>=2.0
Requires-Dist: anthropic>=0.40
Requires-Dist: openai>=1.50
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0; python_version < "3.12"
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn[standard]>=0.32
Requires-Dist: python-multipart>=0.0.9
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-mock>=3.12; extra == "dev"
Dynamic: license-file

# df-storyteller

A storytelling companion for [Dwarf Fortress](https://store.steampowered.com/app/975370/Dwarf_Fortress/). Captures game events, dwarf personalities, and world history through [DFHack](https://dfhack.org/), then generates AI-written narratives grounded in your actual gameplay.

![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue)
![License](https://img.shields.io/badge/license-MIT-green)

> **[Full Documentation on the Wiki](https://github.com/Been012/df-storyteller/wiki)**

## Features

### Narrative Generation
- **Fortress Chronicles** — Seasonal narratives tracking what's changing in your fortress
- **Dwarf Diaries** — First-person journal entries shaped by personality, beliefs, and stress
- **Character Biographies** — Dated entries that evolve as dwarves change over time
- **Death Eulogies** — Memorial narratives for fallen dwarves
- **Battle Reports** — Dramatic combat accounts written by survivors or the fortress chronicler
- **Epic Sagas** — World history narratives from legends data
- **Fortress Gazette** — A dwarven newspaper with five sections, written by the fortress's best writer

### Quest System
- **AI-Generated Quests** — Based on your actual fortress state, grounded in real DF mechanics
- **Narrative-Driven** — Quests that drive the story (character arcs, threats, faith, ambition)
- **Difficulty Tiers** — Easy, Medium, Hard, Legendary
- **Completion Narratives** — AI writes how the quest was fulfilled, feeds into future chronicles

### Visualization & Data
- **Relationship Web** — Interactive force-directed graph of fortress connections
- **Pantheon** — Deity worship chart with sphere descriptions from legends
- **Combat Log** — Blow-by-blow fight details with siege grouping
- **Chat Log** — Dwarf conversations with AI social summaries
- **Lore Browser** — Searchable world history with hover tooltips (kill counts, battle forces, relationships)
- **Live Event Feed** — Real-time game events via WebSocket

## Screenshots

### Chronicle
![Chronicle](docs/screenshots/Chronicle.png)

### Dwarves
![Dwarves](docs/screenshots/dwarves.png)

### Relationship Web
![Relationship Web](docs/screenshots/relationship_web.png)

### Pantheon
![Pantheon](docs/screenshots/Pantheon.png)

### Events
![Events](docs/screenshots/events.png)

### Lore
![Lore](docs/screenshots/legends.png)

### Quests
![Quests](docs/screenshots/quests.png)

### Gazette
![Gazette](docs/screenshots/gazette.png)

## Quick Start

```bash
# Install
git clone https://github.com/Been012/df-storyteller.git
cd df-storyteller
pip install -e .

# Configure (one time)
python -m df_storyteller init

# In DFHack console (first time per fortress)
storyteller-begin

# Launch web UI
python -m df_storyteller serve
```

## Requirements

- **Dwarf Fortress** v50.x (Steam / DF Premium) — tested with v50.14
- **DFHack** v50.14-r1+ (Steam Workshop or [dfhack.org](https://dfhack.org/))
- **Python 3.11+**
- **An LLM provider** (one of):
  - [Ollama](https://ollama.com/) — free, runs locally, no API key needed (supports thinking models)
  - [Anthropic Claude](https://console.anthropic.com/) — API key required
  - [OpenAI](https://platform.openai.com/) — API key required

> **Note:** This tool uses DF Premium (Steam) APIs. Classic DF (pre-Steam) is not supported — some DFHack fields like `unit.relations` don't exist in the Steam version. We use `histfig_links` on historical figures instead.

## Tech Stack

- **Backend**: Python 3.11+, FastAPI, Pydantic v2
- **Frontend**: Jinja2 templates, vanilla CSS/JS (no build step)
- **Game integration**: DFHack Lua scripts
- **LLM**: Anthropic SDK, OpenAI SDK, Ollama REST API (with thinking model support)
- **All narratives grounded in DF mechanics** — the AI knows squad sizes, siege thresholds, temple values, what players can and cannot control

## Documentation

See the **[Wiki](https://github.com/Been012/df-storyteller/wiki)** for:
- [Installation & Setup](https://github.com/Been012/df-storyteller/wiki/Installation)
- [Architecture](https://github.com/Been012/df-storyteller/wiki/Architecture)
- [Configuration](https://github.com/Been012/df-storyteller/wiki/Configuration)
- [LLM Integration](https://github.com/Been012/df-storyteller/wiki/LLM-Integration)
- Feature guides for every tab

## Note

This tool is designed to run **locally on your machine** (localhost). It is not intended to be exposed to the internet or run on a public server. API keys are stored in your local config file at `~/.df-storyteller/config.toml`.

## License

MIT
