World Annals

A world-building engine for writers and creators. Think of it as a personal, structured wiki for fictional (or historical) worlds — where characters, events, and dates are linked together through explicit relationships rather than freeform notes.

The core idea: instead of loosely connected markdown files, every entity lives in a relational database with enforced links. Characters are tied to events they participated in, events have dates, and traversing these connections is built into the data model itself.

Motivation

This is a learning project for SQL and SQLAlchemy 2.0, and a personal tool for organizing writing elements — characters, events, timelines — in a way that makes relationships between them first-class citizens rather than afterthoughts.

Current State

Early development. The data model is in place, test data can be populated, but there is no CLI or UI yet.

Development Status

⚠️ Early Development - Data Model May Change

This project is in its initial development phase. The data model and schema are subject to significant changes as the project evolves:

• Database schema may be modified - existing tables could be restructured
• Entity relationships might change - many-to-many associations could be refined
• New entity types may be added - additional model types could be introduced
• Migration strategy TBD - data migration approach will be determined as needed

If you're using this project, expect breaking changes to the database structure in future versions.

What exists

• SQLAlchemy 2.0 ORM models with typed mappings
• SQLite database for local storage
• Test data population script with historical figures and events

Data Model

Three core entities connected through foreign keys and a many-to-many association:

Character ──born_date──→ Date
Character ──death_date─→ Date
Event ──occurrence_date─→ Date (optional)
Character ←──many-to-many──→ Event

Character — name, role, birth/death locations (optional) and dates (optional) Event — name, description, date (optional), and involved characters Date — year (required), month and day (optional), supporting partial dates

Setup

Requires Python 3.13+ and Poetry.

poetry install

Usage

Create the database and tables:

poetry run python src/world_annals/main.py

Populate with test data (historical figures and events):

poetry run python src/world_annals/simul.py

Tech Stack

• Python 3.13
• SQLAlchemy 2.0 — ORM with declarative typed mappings
• SQLite — local file-based database
• Poetry — dependency management
• pytest — testing (planned)
• mypy — type checking