README.md

---
title: Cosmere Codex
emoji: ✨
colorFrom: yellow
colorTo: pink
sdk: gradio
sdk_version: 6.18.0
python_version: '3.13'
app_file: app.py
pinned: true
license: mit
short_description: Chat in character with the Shards of the Cosmere
tags:
  - track:wood
  - achievement:offgrid
  - achievement:offbrand
---

# ✨ Cosmere Codex — *Voices of the Shards*

A living star map of the Cosmere. Click a system and talk — **live and in
character** — with the god-like Shard who dwells there. Each Shard is performed
by a small language model kept fully in voice: ask anything, and it answers on
the fly in its own distinct character. **The AI isn't a feature here; it *is*
the experience.**

Built for the Hugging Face **Build Small Hackathon** — creative track,
"Thousand Token Wood."

## 🎬 Demo & write-up
- **Demo video + social post:** [LinkedIn submission post](https://www.linkedin.com/posts/joshua-jessee-94a069327_this-is-my-submission-for-the-huggingface-ugcPost-7472315911702753281-q3Xu/)
- I also added the video into the space, under screen recording mp4

## The idea
The Cosmere is full of god-like beings called Shards, each the embodiment of a
single intent — Ruin, Devotion, Odium, Cultivation. *Cosmere Codex* turns that
pantheon into something you can actually **converse with**. The front page is a
slowly-orbiting "solar system of systems": each world drawn as its own animated
symbol circling a central star. Click one and you drop into a themed
conversation with its Shard — Odium trying to seduce you into surrendering your
guilt, Cultivation answering only in riddles of seeds and seasons, Hoid
deflecting every question with a story.

The design bet: a small model doesn't reliably *know* Cosmere canon, so we don't
ask it to. Each Shard's personality **and** key lore live in its system prompt,
so the model simply *performs* a fully-specified character instead of inventing
facts. The result stays in-voice and on-canon while running on a tiny model.

## The tech
- **Model:** `Qwen/Qwen3-8B` (≤ 32B) in **non-thinking mode** for snappy,
  in-character replies, served with Hugging Face `transformers` on **ZeroGPU**
  (`@spaces.GPU`), streamed token-by-token via the tokenizer's chat template.
  The model id is one easy-to-swap constant in `app.py`.
- **Custom UI (Off Brand):** `gr.Blocks` pushed well past stock Gradio — a
  CSS/SVG deep-space scene; seven hand-built, animated vector system symbols
  (turning gears, orbiting planet-dots, pulsing suns) arranged in a circle that
  slowly revolves around a central star; per-Shard color theming; and a tiny
  JS click-bridge so the custom symbols drive navigation. Collapses to a clean
  tappable grid on mobile.
- **Lore-in-prompt:** characters and canon are authored in `shards.py`, separate
  from the UI, so voices are easy to tune.

## The Shards
- **Harmony** (Scadrial) — the god who was once a mortal scholar, holding stability and ruin in balance.
- **Odium** (Roshar) — divine hatred that calls itself Passion and offers freedom from guilt.
- **Cultivation** (Roshar) — the patient gardener who prunes people toward growth.
- **Devotion & Dominion** (Sel) — two Splintered Shards, finishing each other's broken thoughts.
- **Endowment** (Nalthis) — the giver of Breath, watching what mortals make of her gifts.
- **Autonomy** (Taldain) — the many-faced Shard who will never tell you who it truly is.
- **Hoid** (Drominad) — no Shard rules this system, so the Cosmere's eternal wanderer is filling in… unfortunately.



## Attribution & disclaimer
Lore facts adapted from the [Coppermind wiki](https://coppermind.net) (CC BY-NC-SA).
An **unofficial, non-commercial fan project** — not affiliated with or endorsed by
Brandon Sanderson or Dragonsteel. The Cosmere and its worlds are their creations.

Configuration reference: https://huggingface.co/docs/hub/spaces-config-reference