narrAItor

narrAItor is an AI narration backend for Skyrim. It combines a live event stream from the game with a DuckDB state database, LanceDB hybrid search over a UESP wiki dump, model-initiated tool calls, and Inworld TTS 2 voice-over to produce context-aware narration that can respond to what is happening in-game.

narraitor-b8b00b07126947b38adeb2c6e7f285c6.mp4

narraitor-94c61c2cca9842dd9d718ddbeaa7935a.mp4

Setup

This project targets Python 3.14 and uses uv.

uv sync --dev

Secrets are read from environment variables. Keep non-secret service settings in TOML.

Build The RAG Database

Fetch the UESP MediaWiki dump:

uv run narraitor-uesp fetch

Create or update the LanceDB/DuckDB retrieval database:

uv run narraitor-uesp build-rag `
  --dump data\raw\uesp\uespwiki-2026-05-03-current.xml.bz2 `
  --duckdb-path data\indexes\narraitor.duckdb `
  --lance-dir data\indexes\lance `
  --device cuda `
  --max-sequence-length 3072 `
  --model-batch-size 128 `
  --insert-batch-size 2048

build-rag parses the dump, chunks wiki pages, embeds chunks with Qwen, inserts them into LanceDB, and builds the retrieval indexes:

• vector index for embedding search
• FTS/BM25 index for lexical search
• backlink lookup index for document references

By default reruns are incremental and skip existing pages/chunks. Use --reset when you want to rebuild the storage from scratch.

For a quick smoke build:

uv run narraitor-uesp build-rag --limit 100 --reset

Verify the database with a retrieval query:

uv run narraitor-storage search "Whiterun dragons" --mode hybrid --limit 5

Configure The Backend

Create your local backend config from the example:

Copy-Item config\agent.example.toml config\agent.toml

Edit config\agent.toml for local paths, model settings, retrieval limits, and voiceover settings. Keep API keys in your environment or local env file, not in the TOML.

Run The Backend

Start the FastAPI narrator service:

uv run narraitor-agent `
  --host 127.0.0.1 `
  --port 8787 `
  --config config\agent.toml `
  --log-level INFO

The backend serves the agent UI at http://127.0.0.1:8787/.

Development Checks

uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pyright