Metadata-Version: 2.4
Name: chronicle-forge
Version: 0.4.1
Summary: A history-creation RPG / reincarnation roguelite / AI-assisted world simulation.
License: MIT
Project-URL: Homepage, https://github.com/shoebill-dev27/chronicle-forge
Project-URL: Repository, https://github.com/shoebill-dev27/chronicle-forge
Keywords: roguelite,rpg,simulation,history,terminal-game
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Games/Entertainment :: Role-Playing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Provides-Extra: ai
Requires-Dist: anthropic>=0.40; extra == "ai"
Dynamic: license-file

# Chronicle Forge

A history-creation RPG / reincarnation roguelite / AI-assisted world simulation.

You are the world's only reincarnator. When you die you reincarnate, but the
world keeps running: NPCs, factions, and history continue. Your goal is not to
save the world — it is to intervene in history and witness how your choices
shape the future. The core experience is the traceable causal link between what
you did and the history that resulted: *"my actions created this history."*

The world lives for a fixed span (200 years in production, 40 in dev/CI). On
reaching the limit the game produces a Chronicle and an Ending classification.

## Play now — one line, nothing to install

```bash
uvx chronicle-forge play --seed 42
```

That's the interactive game: pick a choice each season, die, reincarnate, and watch
the history you caused unfold. (No [uv](https://docs.astral.sh/uv/)? Then
`pipx install chronicle-forge` or `pip install chronicle-forge`, and run
`chronicle-forge play --seed 42`.)

No API key is required — the simulation is rules-only and fully deterministic by
default. The optional AI narration (`pip install "chronicle-forge[ai]"`) only adds
prose; it never changes world state.

## Quickstart — the one-way path

```bash
# 1) generate & witness a full world, deterministically, and save it
#    (drop --auto to make the choices yourself)
chronicle-forge play --seed 42 --auto --save run.recipe

# 2) explore the history your world produced (the P10–P14 read-model lenses)
chronicle-forge explore run.recipe                 # human-readable Markdown
chronicle-forge explore run.recipe --format json   # the stable read-model JSON

# 3) share it — a recipe replays byte-for-byte for anyone
chronicle-forge share run.recipe --export run.md
chronicle-forge play --replay run.recipe           # reproduces the exact transcript
```

The **recipe is the save**: a seed plus the ordered inputs. Because the engine is
byte-deterministic, a recipe reconstructs its world (and transcript) exactly, on any
machine, forever — that is the basis of both replay and sharing.

## Example world (seed 42) — see it in 5 minutes

A complete, reproducible world generated by `simulate_world(42)` — rules-only, no AI:

| Lives | Events | Heritage | Ending |
|---|---|---|---|
| 3 | 77 | 8 | Theocratic Age |

> A warrior's life seeds a school of thought; a merchant's life turns it into an
> institution; a priest's life carries it to a faith — and the world ends in a
> Theocratic Age you can trace, event by event, back to the very first life.

**[Open the demo bundle → `docs/examples/seed42/`](docs/examples/seed42/)** — start
with [`story.md`](docs/examples/seed42/story.md) (each life traced
Life → Seeds → Events → Heritage → Ending), then
[`chronicle.md`](docs/examples/seed42/chronicle.md) ("Why this Ending"),
[`heritage.md`](docs/examples/seed42/heritage.md), and the
[`causal.dot`](docs/examples/seed42/causal.dot) graph.

Regenerate the demo bundle anytime:

```bash
python -m chronicle_forge.reporting 42
```

## Architecture

**Rules own truth, AI owns prose** — state transitions are deterministic; the LLM
only narrates and makes a few bounded decisions. The layers, from the frozen core
outward:

- **Engine** — deterministic world generation, the causal-link core, the micro
  loop (a life) and macro loop (death → time-skip → history → reincarnation), all
  reproducible from the seed.
- **Persistence** — a run is a `Recipe` (seed + inputs); version-gated replay
  reconstructs the world byte-for-byte.
- **Read-model lenses (P10–P14)** — id-free, structured, hashable projections of a
  finished world: Observatory, WorldView, Narrative, Character, and Timeline.
- **Application Layer (`chronicle_forge.app`, P15)** — the single integration
  boundary that composes the above into `play → save → explore → share`.
- **CLI (`chronicle-forge`)** — a thin wrapper over the Application Layer; it parses
  arguments and renders output, and holds no game logic.

The full, design-locked specification lives in
[`docs/design.md`](docs/design.md); the roadmap to v1.0 is in
[`docs/design_release_roadmap.md`](docs/design_release_roadmap.md).

## Determinism

A seed + recipe reproduces a world — and its transcript — byte-for-byte. Everything
non-deterministic (AI prose, when enabled) is a **non-canonical side-channel**: it is
never recorded into a save and never participates in replay.

## Development

```bash
pip install -e ".[dev]"   # editable install with pytest + black
pytest                    # runs the suite, including the frozen golden assertions
black src tests           # format
```

Copy `.env.example` to `.env` for the (optional) AI call sites; the core simulation
runs rules-only without any API key.

## License

MIT — see [LICENSE](LICENSE).
