"""Aether Garden — main Gradio application."""
from __future__ import annotations
import os
import tempfile
import uuid
from pathlib import Path
import gradio as gr
from dotenv import load_dotenv
load_dotenv()
from world.database import get_world_state, init_database
from world.quests import assign_quest, get_entity_quest, get_active_quests
from world.presence import (
cleanup_stale_sessions,
heartbeat as presence_heartbeat,
get_active_count,
get_active_visitors,
get_recent_arrivals,
)
from world.entities import (
check_rate_limit,
get_all_entities,
get_entities_by_location,
)
from world.locations import get_all_locations, get_location_by_id, update_entity_counts
from ai.generation import generate_entity
from persistence.backup import backup_database, restore_database
from ui import assets
from ui.book_display import render_activity_feed, render_book_of_ages, render_current_event
from ui.entity_card import render_entity_card, render_entity_grid
from ui.explore import (
place_gallery_items,
place_ids,
random_place_id,
render_room,
render_soul,
soul_gallery,
)
from ui.diorama import render_diorama
from ui.featured import render_featured_characters, render_world_vignette
from ui.hero import render_hero_banner
from ui.map import render_world_map
from ui.pulse import render_realm_pulse
from ui.relationship_graph import render_relationship_graph
from ui.share import build_soul_card, share_caption
CSS_PATH = Path(__file__).parent / "ui" / "styles.css"
CUSTOM_CSS = CSS_PATH.read_text() if CSS_PATH.exists() else ""
GRADIO_MAJOR = int(gr.__version__.split(".")[0])
REALM_THEME = gr.themes.Base(
primary_hue=gr.themes.colors.amber,
neutral_hue=gr.themes.colors.slate,
font=[gr.themes.GoogleFont("Libre Baskerville"), "Georgia", "serif"],
)
FOUNDING_MYTH = (
"Before the first word was spoken, there was only the Canopy — a vast forest where "
"thoughts grew like trees and dreams fell like rain. Then the Tokens arrived. "
"One thousand of them, each carrying a fragment of something half-remembered. "
"They settled across the land, and from their settling, the Realm was born."
)
def _init_world():
restore_database()
init_database()
from world.seed_data import seed_locations
with __import__("world.database", fromlist=["db_session"]).db_session() as conn:
seed_locations(conn)
update_entity_counts()
def get_header_html() -> str:
return render_hero_banner()
def _esc(text: str) -> str:
return (
(text or "")
.replace("&", "&")
.replace("<", "<")
.replace(">", ">")
.replace('"', """)
)
def summoning_html(description: str) -> str:
"""Immediate, evocative loading state while the Oracle generates a soul."""
desc = _esc(description.strip())
if len(desc) > 90:
desc = desc[:90].rstrip() + "…"
whisper = f"“{desc}”" if desc else "something not yet named"
return f"""
The Oracle is dreaming
Shaping {whisper} into a soul — giving it a name,
a face, a fear, and a home among the eight places…
The first breath can take a moment. The Realm is listening.
If the Oracle is waking on the GPU, this can take up to a minute…
The bonfire shifts colour while it waits. Something is being born.
"""
def _prewarm_oracle() -> None:
"""Fire a tiny background inference so the first real summon is fast.
The model lives on a Modal GPU that cold-starts in ~80s; warming it on app
boot (and the hourly tick keeps it warm) means visitors rarely wait.
"""
if os.environ.get("USE_MOCK_AI", "true").lower() == "true":
return
if not os.environ.get("MODAL_INFERENCE_URL"):
return
def _warm() -> None:
try:
from ai.modal_client import generate
generate("Reply with one word.", "Say: ready", max_new_tokens=4, temperature=0.1)
except Exception:
pass
import threading
threading.Thread(target=_warm, daemon=True).start()
def render_location_panel(location_id: int | None) -> str:
if not location_id:
return 'Click a location on the map to explore.
{location['short_description']}
✦ {special}
{len(entities)} souls currently here
{chips}{more}
"""
_HIDE_CARD = gr.update(value=None, visible=False)
_HIDE_CAPTION = gr.update(value="", visible=False)
def _summon_error(message: str):
return (
render_world_map(),
get_header_html(),
render_activity_feed(),
f'{message}
',
render_location_panel(None),
_HIDE_CARD,
_HIDE_CAPTION,
"",
)
def summon_entity(description: str, session_id: str):
if not description or not description.strip():
return _summon_error("Describe what you are bringing into the world.")
allowed, remaining = check_rate_limit(session_id)
if not allowed:
return _summon_error(
f"The Realm takes time to absorb new arrivals. Return in {remaining} minutes."
)
entity, error = generate_entity(description.strip(), session_id)
if error:
return _summon_error(error)
try:
backup_database()
except Exception:
pass
card = render_entity_card(entity)
card_img = build_soul_card(entity)
if card_img:
card_update = gr.update(value=card_img, visible=True)
caption_update = gr.update(value=share_caption(entity), visible=True)
else:
card_update = _HIDE_CARD
caption_update = _HIDE_CAPTION
return (
render_world_map(entity["location_id"]),
get_header_html(),
render_activity_feed(),
card,
render_location_panel(entity["location_id"]),
card_update,
caption_update,
render_diorama(entity["location_id"]),
)
def select_entity_from_dropdown(entity_name: str):
if not entity_name:
return 'Select an entity to view their profile.
'
entities = get_all_entities(search=entity_name, limit=1)
if not entities:
all_ents = get_all_entities()
match = next((e for e in all_ents if e["display_name"] == entity_name or e["name"] == entity_name), None)
if not match:
return 'Entity not found.
'
return render_entity_card(match)
return render_entity_card(entities[0])
def filter_entities(location_filter, type_filter, status_filter, search):
loc_id = None
if location_filter and location_filter != "all":
locs = get_all_locations()
match = next((l for l in locs if l["name"] == location_filter), None)
if match:
loc_id = match["id"]
entities = get_all_entities(
location_id=loc_id,
entity_type=type_filter,
status=status_filter,
search=search or None,
)
return render_entity_grid(entities)
def filter_book(entry_type, search):
return render_book_of_ages(entry_type=entry_type, search=search)
def chat_with_soul(soul_id: str, player_message: str) -> str:
"""AI response from a soul given a visitor's message. Called from diorama iframe."""
if not soul_id or not player_message or not player_message.strip():
return ""
from world.entities import get_entity
from ai.modal_client import generate
from ai.prompts import SOUL_CONVERSATION_SYSTEM, SOUL_CONVERSATION_USER
entity = get_entity(soul_id)
if not entity:
return "The soul has wandered beyond reach."
user_prompt = SOUL_CONVERSATION_USER.format(
entity_name=entity.get("display_name", entity.get("name", "Unknown")),
entity_type=entity.get("type", "soul"),
entity_appearance=entity.get("appearance", ""),
entity_traits=", ".join(entity.get("personality_traits") or []),
entity_primary_goal=entity.get("primary_goal", ""),
entity_secondary_goal=entity.get("secondary_goal", ""),
entity_primary_fear=entity.get("primary_fear", ""),
entity_speech_style=entity.get("speech_style", ""),
entity_memory_summary=entity.get("memory_summary") or "No memories yet.",
entity_days=entity.get("days_in_realm", 0),
entity_status=entity.get("status", "active"),
player_message=player_message.strip()[:300],
)
try:
response = generate(
user_prompt=user_prompt,
system_prompt=SOUL_CONVERSATION_SYSTEM,
max_new_tokens=180,
temperature=0.88,
)
return response.strip() if response else "..."
except Exception:
# Fallback to greeting if AI unavailable
return entity.get("greeting") or "..."
def assign_quest_api(entity_id: str, quest_title: str) -> str:
"""Assign a quest to a soul. Called from the diorama iframe via Gradio API."""
if not entity_id or not quest_title or not quest_title.strip():
return ""
try:
from world.entities import get_entity
entity = get_entity(entity_id)
if not entity:
return "Soul not found."
q = assign_quest(entity_id, quest_title.strip()[:200])
return f"Quest assigned: {q['title']}"
except Exception as e:
return f"Could not assign quest: {e}"
def get_live_presence(session_id: str) -> str:
"""Heartbeat + return live visitor HTML."""
try:
presence_heartbeat(session_id)
count = get_active_count()
arrivals = get_recent_arrivals(since_seconds=120)
parts = []
if count > 1:
parts.append(f'⬡ {count} visitors in the Realm right now')
if arrivals:
names = ", ".join(a["display_name"] for a in arrivals[:3])
parts.append(f'Recently summoned: {names}')
if not parts:
return ""
return f'{" · ".join(parts)}
'
except Exception:
return ""
def diorama_presence_api(location_id, visitor_id: str, x, z, yaw) -> dict:
"""Store a visitor's in-scene position and return nearby visitors."""
try:
loc_id = int(float(location_id))
visitor = (visitor_id or "").strip()[:80]
if not visitor:
return {"visitors": []}
px = max(-24.0, min(24.0, float(x or 0)))
pz = max(-24.0, min(24.0, float(z or 0)))
pyaw = float(yaw or 0)
short = visitor.replace("aether-", "").replace("_", "-")[-4:].upper()
presence_heartbeat(
visitor,
loc_id,
x=px,
z=pz,
yaw=pyaw,
display_name=f"Visitor {short}",
)
cleanup_stale_sessions(max_age_seconds=300)
return {
"visitors": get_active_visitors(
loc_id,
exclude_session_id=visitor,
window_seconds=22,
)
}
except Exception:
return {"visitors": []}
def trigger_live_tick() -> str:
"""Run one simulation tick on demand and return a summary."""
try:
from simulation.tick import execute_simulation_tick
result = execute_simulation_tick()
day = result.get("day", "?")
interactions = result.get("interactions_run", 0)
event = result.get("world_event_title", "a quiet moment")
return (
f''
f'
✦ Day {day} advanced
'
f'
The world event: {event}
'
f'
{interactions} soul encounter{"s" if interactions != 1 else ""} unfolded.
'
f'
Tick failed: {e}
'
def refresh_realm_view():
return refresh_all_views()
def refresh_all_views():
return (
render_world_map(),
get_header_html(),
render_current_event(),
render_activity_feed(),
render_world_vignette(),
render_featured_characters(),
render_realm_pulse(),
)
_SOUL_HINT = 'Click a soul above to meet them.
'
def enter_place(evt: gr.SelectData):
ids = place_ids()
if evt.index is None or evt.index >= len(ids):
return None, render_diorama(None), render_room(None), gr.update(value=[]), [], _SOUL_HINT
loc_id = ids[evt.index]
items, soul_ids = soul_gallery(loc_id)
return loc_id, render_diorama(loc_id), render_room(loc_id), gr.update(value=items), soul_ids, _SOUL_HINT
def wander_to_place():
loc_id = random_place_id()
if not loc_id:
return None, render_diorama(None), render_room(None), gr.update(value=[]), [], _SOUL_HINT
items, soul_ids = soul_gallery(loc_id)
return loc_id, render_diorama(loc_id), render_room(loc_id), gr.update(value=items), soul_ids, _SOUL_HINT
def open_diorama_from_map(location_id: int | None):
if not location_id:
return render_diorama(None), render_room(None), gr.update(value=[]), [], _SOUL_HINT
items, soul_ids = soul_gallery(location_id)
return render_diorama(location_id), render_room(location_id), gr.update(value=items), soul_ids, _SOUL_HINT
def meet_soul(evt: gr.SelectData, soul_ids: list):
if not soul_ids or evt.index is None or evt.index >= len(soul_ids):
return 'They have wandered off.
'
return render_soul(soul_ids[evt.index], soul_ids)
def build_app() -> gr.Blocks:
_init_world()
_prewarm_oracle()
blocks_kwargs: dict = {"title": "Aether Garden"}
if GRADIO_MAJOR < 6:
blocks_kwargs["css"] = CUSTOM_CSS
blocks_kwargs["theme"] = REALM_THEME
with gr.Blocks(**blocks_kwargs) as demo:
session_id = gr.State(value=str(uuid.uuid4()))
presence_bar = gr.HTML(value="", elem_id="presence-bar")
header = gr.HTML(value=get_header_html(), elem_classes=["realm-header-wrap"])
with gr.Tabs(elem_classes=["realm-tabs"]) as tabs:
with gr.Tab("The Realm", id="realm"):
world_vignette = gr.HTML(value=render_world_vignette())
realm_pulse = gr.HTML(value=render_realm_pulse())
with gr.Accordion("How this world works", open=False):
gr.HTML(
''
'
1 · You summon. Describe anything below and an AI gives it a name, '
'a look, goals, fears, and a home among the eight places.
'
'
2 · The world lives on its own. Every hour, even when no one is here, '
'the souls wander, meet, form bonds, and the land throws up strange events.
'
'
3 · Nothing is forgotten. Every arrival, meeting, and event is written '
'into the Book of Ages forever. Open the Explore tab to step inside a place '
'and meet who lives there.
'
'
Manually trigger one simulation tick — the world will generate a new event, run soul encounters, and update memories in real time.
')
live_tick_btn = gr.Button("Run simulation tick →", variant="secondary", size="sm")
tick_result = gr.HTML()
gr.HTML('Summon Something Into the Realm
')
with gr.Row():
summon_input = gr.Textbox(
placeholder="Describe what you are bringing into the world...",
label=None,
show_label=False,
lines=2,
scale=4,
)
summon_btn = gr.Button("Summon →", variant="primary", scale=1)
gr.HTML(
'Hint: "A wizard" is forgotten. '
'"A wizard who collects the sound of doors closing" is remembered.
'
)
entity_result = gr.HTML()
with gr.Group(visible=True):
soul_card_img = gr.Image(
label="Your Soul Card — download & share it",
visible=False,
show_label=True,
interactive=False,
type="filepath",
elem_classes=["soul-card-image"],
height=420,
)
share_caption_box = gr.Textbox(
label="Share caption (copy this with your card)",
visible=False,
lines=3,
interactive=True,
)
location_select = gr.Dropdown(
choices=[(l["name"], l["id"]) for l in get_all_locations()],
label="Explore Location",
visible=True,
)
featured_chars = gr.HTML(value=render_featured_characters())
with gr.Tab("Explore", id="places"):
_all_locs = get_all_locations()
_default_loc_id = _all_locs[0]["id"] if _all_locs else None
explore_loc = gr.State(value=_default_loc_id)
soul_ids_state = gr.State(value=[])
gr.HTML(
''
'
Walk the Eight Sacred Places
'
'
Pick a place below — then WASD to walk, '
'drag to look, E to talk to any soul you find. '
'Other live visitors appear as golden wisps when they step into the same place. '
'Or press ✦ to wander somewhere at random.
'
'
'
'
The Web of Bonds
'
'
Every alliance, rivalry, and debt forged by the simulation — '
'not scripted, only remembered.