Add REST API, HTML UI, and tests

- Characters REST endpoints: list / detail (with memory counts by
scope and type) / create (202 + BackgroundTasks) / delete
(soft, rejects presets) / browse memories (paginated, filterable
by scope and type)
- Plain HTML UI via Jinja2 + Tailwind CDN:
/ character grid
/characters/new create form with slider inputs
/characters/{id} detail page with style bars, counts, sample
memories per type; auto-refresh via meta tag
while state = generating_memories
- FastAPI lifespan wires logging, DB, and idempotent preset seeding
- Tests:
style helper bucket boundaries + shape
memory schema validation (valence range, enums, strip/dedup)
memory generator mocked (happy path, LLM failure, too-few guard)
preset seeding idempotency
opt-in live LLM test (pytest.mark.live; skipped unless
RUN_LIVE_LLM_TESTS=1 and real GEMINI_API_KEY present)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

app/api/characters.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Query, status
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.db import get_session
+from app.memory.crud import counts_by_scope, counts_by_type, list_for_character
+from app.models.character import Character, CharacterState
+from app.models.memory import MemoryScope, MemoryType
+from app.schemas.character import (
+    CharacterCreate,
+    CharacterDetail,
+    CharacterRead,
+    CharacterSummary,
+    MemoryCountsByScope,
+    MemoryCountsByType,
+)
+from app.schemas.memory import MemoryRead
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/characters", tags=["characters"])
+
+
+def _run_generation_bg(character_id: str) -> None:
+    from app.characters.memory_generator import generate_and_store
+
+    try:
+        generate_and_store(character_id)
+    except Exception:
+        logger.exception("Memory generation failed for %s", character_id)
+
+
+@router.get("", response_model=list[CharacterSummary])
+def list_characters(session: Session = Depends(get_session)) -> list[CharacterSummary]:
+    rows = session.execute(
+        select(Character).where(Character.deleted_at.is_(None)).order_by(Character.created_at.desc())
+    ).scalars()
+    return [CharacterSummary.model_validate(c) for c in rows]
+
+
+@router.get("/{character_id}", response_model=CharacterDetail)
+def get_character(character_id: str, session: Session = Depends(get_session)) -> CharacterDetail:
+    character = session.get(Character, character_id)
+    if character is None or character.deleted_at is not None:
+        raise HTTPException(status_code=404, detail="Character not found")
+
+    scope_counts = counts_by_scope(session, character_id=character_id)
+    type_counts = counts_by_type(session, character_id=character_id)
+
+    detail = CharacterDetail.model_validate(character).model_copy(
+        update={
+            "memory_count": sum(scope_counts.values()),
+            "memory_counts_by_scope": MemoryCountsByScope(**scope_counts),
+            "memory_counts_by_type": MemoryCountsByType(**type_counts),
+        }
+    )
+    return detail
+
+
+@router.post("", response_model=CharacterRead, status_code=status.HTTP_202_ACCEPTED)
+def create_character(
+    payload: CharacterCreate,
+    background: BackgroundTasks,
+    session: Session = Depends(get_session),
+) -> CharacterRead:
+    character = Character(
+        name=payload.name,
+        short_description=payload.short_description,
+        backstory=payload.backstory,
+        avatar_emoji=payload.avatar_emoji,
+        aggression=payload.aggression,
+        risk_tolerance=payload.risk_tolerance,
+        patience=payload.patience,
+        trash_talk=payload.trash_talk,
+        target_elo=payload.target_elo,
+        adaptive=payload.adaptive,
+        opening_preferences=list(payload.opening_preferences),
+        voice_descriptor=payload.voice_descriptor,
+        quirks=payload.quirks,
+        state=CharacterState.GENERATING_MEMORIES,
+        memory_generation_started_at=datetime.utcnow(),
+        is_preset=False,
+    )
+    session.add(character)
+    session.commit()
+    session.refresh(character)
+
+    background.add_task(_run_generation_bg, character.id)
+    return CharacterRead.model_validate(character)
+
+
+@router.get("/{character_id}/memories", response_model=dict)
+def list_memories(
+    character_id: str,
+    scope: MemoryScope | None = None,
+    type: MemoryType | None = None,
+    offset: int = Query(0, ge=0),
+    limit: int = Query(50, ge=1, le=200),
+    session: Session = Depends(get_session),
+) -> dict:
+    character = session.get(Character, character_id)
+    if character is None or character.deleted_at is not None:
+        raise HTTPException(status_code=404, detail="Character not found")
+
+    rows, total = list_for_character(
+        session,
+        character_id=character_id,
+        scope=scope,
+        type_=type,
+        offset=offset,
+        limit=limit,
+    )
+    return {
+        "total": total,
+        "offset": offset,
+        "limit": limit,
+        "items": [MemoryRead.model_validate(r).model_dump(mode="json") for r in rows],
+    }
+
+
+@router.delete("/{character_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_character(character_id: str, session: Session = Depends(get_session)) -> None:
+    character = session.get(Character, character_id)
+    if character is None or character.deleted_at is not None:
+        raise HTTPException(status_code=404, detail="Character not found")
+    if character.is_preset:
+        raise HTTPException(status_code=403, detail="Preset characters cannot be deleted")
+    character.deleted_at = datetime.utcnow()
+    session.commit()

app/main.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from app.api.characters import router as characters_api
+from app.characters.seed import seed_presets
+from app.config import get_settings
+from app.db import init_db
+from app.logging_config import configure_logging
+from app.web.routes import router as web_router
+
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    configure_logging()
+    init_db()
+
+    settings = get_settings()
+    # Only kick off preset memory generation if the API key is present — the app
+    # should still come up locally without one so people can inspect the UI.
+    run_gen = bool(settings.gemini_api_key)
+    results = seed_presets(run_generation=run_gen)
+    created = [k for k, v in results.items() if v]
+    if created:
+        logger.info("Seeded new presets: %s", created)
+    if not run_gen:
+        logger.warning(
+            "GEMINI_API_KEY is not set — presets were seeded but memory generation is skipped."
+        )
+    yield
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(title="Metropolis Chess Club", lifespan=lifespan)
+    app.include_router(characters_api)
+    app.include_router(web_router)
+    return app
+
+
+app = create_app()

app/web/routes.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from fastapi import APIRouter, BackgroundTasks, Depends, Form, HTTPException, Request
+from fastapi.responses import HTMLResponse, RedirectResponse
+from fastapi.templating import Jinja2Templates
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.characters.openings import OPENINGS
+from app.characters.style import style_to_prompt_fragments
+from app.db import get_session
+from app.memory.crud import counts_by_scope, counts_by_type, list_for_character
+from app.models.character import Character, CharacterState
+from app.schemas.character import CharacterCreate
+
+_TEMPLATE_DIR = Path(__file__).parent / "templates"
+templates = Jinja2Templates(directory=str(_TEMPLATE_DIR))
+
+router = APIRouter(tags=["web"])
+
+
+def _run_generation_bg(character_id: str) -> None:
+    import logging
+
+    from app.characters.memory_generator import generate_and_store
+
+    try:
+        generate_and_store(character_id)
+    except Exception:
+        logging.getLogger(__name__).exception(
+            "Memory generation failed for %s", character_id
+        )
+
+
+@router.get("/", response_class=HTMLResponse)
+def index(request: Request, session: Session = Depends(get_session)) -> HTMLResponse:
+    chars = list(
+        session.execute(
+            select(Character)
+            .where(Character.deleted_at.is_(None))
+            .order_by(Character.is_preset.desc(), Character.created_at.desc())
+        ).scalars()
+    )
+    return templates.TemplateResponse(
+        request, "index.html", {"characters": chars}
+    )
+
+
+@router.get("/characters/new", response_class=HTMLResponse)
+def new_character_form(request: Request) -> HTMLResponse:
+    return templates.TemplateResponse(
+        request,
+        "new.html",
+        {"openings": OPENINGS},
+    )
+
+
+@router.post("/characters/new")
+def create_character_html(
+    request: Request,
+    background: BackgroundTasks,
+    name: str = Form(...),
+    short_description: str = Form(""),
+    backstory: str = Form(""),
+    avatar_emoji: str = Form("♟️"),
+    aggression: int = Form(5),
+    risk_tolerance: int = Form(5),
+    patience: int = Form(5),
+    trash_talk: int = Form(5),
+    target_elo: int = Form(1400),
+    adaptive: str = Form(""),
+    opening_preferences: list[str] = Form(default=[]),
+    voice_descriptor: str = Form(""),
+    quirks: str = Form(""),
+    session: Session = Depends(get_session),
+) -> RedirectResponse:
+    payload = CharacterCreate(
+        name=name,
+        short_description=short_description,
+        backstory=backstory,
+        avatar_emoji=avatar_emoji or "♟️",
+        aggression=aggression,
+        risk_tolerance=risk_tolerance,
+        patience=patience,
+        trash_talk=trash_talk,
+        target_elo=target_elo,
+        adaptive=bool(adaptive),
+        opening_preferences=opening_preferences,
+        voice_descriptor=voice_descriptor,
+        quirks=quirks,
+    )
+    character = Character(
+        name=payload.name,
+        short_description=payload.short_description,
+        backstory=payload.backstory,
+        avatar_emoji=payload.avatar_emoji,
+        aggression=payload.aggression,
+        risk_tolerance=payload.risk_tolerance,
+        patience=payload.patience,
+        trash_talk=payload.trash_talk,
+        target_elo=payload.target_elo,
+        adaptive=payload.adaptive,
+        opening_preferences=list(payload.opening_preferences),
+        voice_descriptor=payload.voice_descriptor,
+        quirks=payload.quirks,
+        state=CharacterState.GENERATING_MEMORIES,
+        memory_generation_started_at=datetime.utcnow(),
+        is_preset=False,
+    )
+    session.add(character)
+    session.commit()
+    session.refresh(character)
+    background.add_task(_run_generation_bg, character.id)
+
+    return RedirectResponse(url=f"/characters/{character.id}", status_code=303)
+
+
+@router.get("/characters/{character_id}", response_class=HTMLResponse)
+def character_detail(
+    request: Request,
+    character_id: str,
+    session: Session = Depends(get_session),
+) -> HTMLResponse:
+    character = session.get(Character, character_id)
+    if character is None or character.deleted_at is not None:
+        raise HTTPException(status_code=404, detail="Character not found")
+
+    scope_counts = counts_by_scope(session, character_id=character_id)
+    type_counts = counts_by_type(session, character_id=character_id)
+    fragments = style_to_prompt_fragments(character)
+
+    # Sample a handful of memories grouped by type for a quick tour.
+    samples_by_type: dict[str, list] = {}
+    for type_value in type_counts:
+        from app.models.memory import MemoryType as MT
+
+        try:
+            mt = MT(type_value)
+        except ValueError:
+            continue
+        rows, _ = list_for_character(
+            session, character_id=character_id, type_=mt, offset=0, limit=3
+        )
+        samples_by_type[type_value] = rows
+
+    return templates.TemplateResponse(
+        request,
+        "detail.html",
+        {
+            "character": character,
+            "scope_counts": scope_counts,
+            "type_counts": type_counts,
+            "total_memories": sum(scope_counts.values()),
+            "fragments": fragments,
+            "samples_by_type": samples_by_type,
+            "is_generating": character.state == CharacterState.GENERATING_MEMORIES,
+            "is_failed": character.state == CharacterState.GENERATION_FAILED,
+        },
+    )

app/web/templates/base.html

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>{% block title %}Metropolis Chess Club{% endblock %}</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  {% block head_extra %}{% endblock %}
+</head>
+<body class="min-h-screen bg-neutral-950 text-neutral-100">
+  <header class="border-b border-neutral-800 bg-neutral-900/60 backdrop-blur">
+    <div class="max-w-6xl mx-auto px-6 py-4 flex items-center justify-between">
+      <a href="/" class="text-xl font-semibold tracking-wide">
+        <span class="mr-2">♟</span>Metropolis Chess Club
+      </a>
+      <nav class="text-sm text-neutral-300 space-x-4">
+        <a href="/" class="hover:text-white">Characters</a>
+        <a href="/characters/new" class="rounded bg-emerald-500 px-3 py-1.5 font-medium text-neutral-900 hover:bg-emerald-400">
+          + New character
+        </a>
+      </nav>
+    </div>
+  </header>
+  <main class="max-w-6xl mx-auto px-6 py-8">
+    {% block content %}{% endblock %}
+  </main>
+  <footer class="max-w-6xl mx-auto px-6 py-8 text-center text-xs text-neutral-500">
+    Phase 1 — characters &amp; memories only. Gameplay arrives in Phase 2.
+  </footer>
+</body>
+</html>

app/web/templates/detail.html

@@ -0,0 +1,138 @@
+{% extends "base.html" %}
+
+{% block title %}{{ character.name }} — Metropolis Chess Club{% endblock %}
+
+{% block head_extra %}
+{% if is_generating %}
+<meta http-equiv="refresh" content="4" />
+{% endif %}
+{% endblock %}
+
+{% block content %}
+<div class="flex items-start gap-6">
+  <div class="text-6xl">{{ character.avatar_emoji or "♟" }}</div>
+  <div class="flex-1">
+    <div class="flex items-center gap-3">
+      <h1 class="text-3xl font-semibold">{{ character.name }}</h1>
+      {% if character.is_preset %}
+      <span class="text-[10px] uppercase tracking-wider bg-neutral-800 text-neutral-300 rounded px-1.5 py-0.5">Preset</span>
+      {% endif %}
+      {% if is_generating %}
+      <span class="text-xs bg-amber-900/60 text-amber-200 rounded px-2 py-0.5 animate-pulse">Generating memories…</span>
+      {% elif is_failed %}
+      <span class="text-xs bg-rose-900/60 text-rose-200 rounded px-2 py-0.5">Generation failed</span>
+      {% else %}
+      <span class="text-xs bg-emerald-900/60 text-emerald-200 rounded px-2 py-0.5">Ready</span>
+      {% endif %}
+    </div>
+    <p class="text-neutral-300 mt-1">{{ character.short_description }}</p>
+    <div class="mt-3 text-sm text-neutral-400">
+      <span>Target {{ character.target_elo }} Elo</span>
+      {% if character.adaptive %} · <span>adaptive</span>{% endif %}
+      {% if character.voice_descriptor %} · <span class="italic">{{ character.voice_descriptor }}</span>{% endif %}
+    </div>
+  </div>
+</div>
+
+{% if is_failed and character.memory_generation_error %}
+<div class="mt-6 rounded border border-rose-900/80 bg-rose-950/40 p-4 text-sm text-rose-200">
+  <div class="font-semibold mb-1">Memory generation failed</div>
+  <code class="text-xs">{{ character.memory_generation_error }}</code>
+</div>
+{% endif %}
+
+<section class="mt-8 grid grid-cols-1 md:grid-cols-2 gap-6">
+  <div class="rounded border border-neutral-800 bg-neutral-900 p-5">
+    <h2 class="text-sm uppercase tracking-wider text-neutral-400 mb-3">Style</h2>
+    <dl class="space-y-2 text-sm">
+      {% for key, val in [
+        ("Aggression", character.aggression),
+        ("Risk tolerance", character.risk_tolerance),
+        ("Patience", character.patience),
+        ("Trash talk", character.trash_talk),
+      ] %}
+      <div class="flex items-center gap-3">
+        <dt class="w-32 text-neutral-400">{{ key }}</dt>
+        <dd class="flex-1">
+          <div class="h-2 bg-neutral-800 rounded overflow-hidden">
+            <div class="h-full bg-emerald-500" style="width: {{ val * 10 }}%"></div>
+          </div>
+        </dd>
+        <dd class="w-6 text-right text-neutral-300">{{ val }}</dd>
+      </div>
+      {% endfor %}
+    </dl>
+    <h3 class="mt-5 text-sm uppercase tracking-wider text-neutral-400 mb-2">Prompt fragments</h3>
+    <ul class="text-xs text-neutral-300 space-y-1">
+      <li><span class="text-neutral-500">aggression:</span> {{ fragments.aggression }}</li>
+      <li><span class="text-neutral-500">risk:</span> {{ fragments.risk_tolerance }}</li>
+      <li><span class="text-neutral-500">patience:</span> {{ fragments.patience }}</li>
+      <li><span class="text-neutral-500">talk:</span> {{ fragments.trash_talk }}</li>
+    </ul>
+  </div>
+
+  <div class="rounded border border-neutral-800 bg-neutral-900 p-5">
+    <h2 class="text-sm uppercase tracking-wider text-neutral-400 mb-3">Memory summary</h2>
+    <div class="text-3xl font-semibold">{{ total_memories }}</div>
+    <div class="text-xs text-neutral-500 mb-4">memories total</div>
+    <div class="grid grid-cols-2 gap-2 text-xs">
+      {% for scope, n in scope_counts.items() %}
+      <div class="flex justify-between rounded bg-neutral-800/60 px-2 py-1">
+        <span class="text-neutral-400">{{ scope }}</span><span>{{ n }}</span>
+      </div>
+      {% endfor %}
+    </div>
+    <div class="mt-3 grid grid-cols-2 gap-2 text-xs">
+      {% for typ, n in type_counts.items() %}
+      <div class="flex justify-between rounded bg-neutral-800/60 px-2 py-1">
+        <span class="text-neutral-400">{{ typ }}</span><span>{{ n }}</span>
+      </div>
+      {% endfor %}
+    </div>
+    {% if character.opening_preferences %}
+    <h3 class="mt-5 text-sm uppercase tracking-wider text-neutral-400 mb-2">Openings</h3>
+    <ul class="text-xs text-neutral-300 space-y-0.5">
+      {% for op in character.opening_preferences %}
+      <li>· {{ op }}</li>
+      {% endfor %}
+    </ul>
+    {% endif %}
+  </div>
+</section>
+
+<section class="mt-8 rounded border border-neutral-800 bg-neutral-900 p-5">
+  <h2 class="text-sm uppercase tracking-wider text-neutral-400 mb-3">Backstory</h2>
+  <p class="text-sm text-neutral-200 whitespace-pre-wrap leading-relaxed">{{ character.backstory }}</p>
+  {% if character.quirks %}
+  <h3 class="mt-5 text-sm uppercase tracking-wider text-neutral-400 mb-2">Quirks</h3>
+  <p class="text-sm text-neutral-300">{{ character.quirks }}</p>
+  {% endif %}
+</section>
+
+{% if samples_by_type %}
+<section class="mt-8">
+  <h2 class="text-sm uppercase tracking-wider text-neutral-400 mb-3">Sample memories</h2>
+  <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+    {% for typ, memories in samples_by_type.items() %}
+    <div class="rounded border border-neutral-800 bg-neutral-900 p-5">
+      <div class="flex items-center justify-between mb-3">
+        <div class="text-xs uppercase tracking-wider text-neutral-400">{{ typ }}</div>
+        <div class="text-xs text-neutral-500">{{ type_counts.get(typ, 0) }} total</div>
+      </div>
+      <ul class="space-y-3">
+        {% for m in memories %}
+        <li class="text-sm text-neutral-200">
+          <div class="leading-relaxed">{{ m.narrative_text }}</div>
+          <div class="mt-1 text-xs text-neutral-500">
+            valence {{ "%.2f"|format(m.emotional_valence) }} ·
+            {% for t in m.triggers[:5] %}<span class="inline-block bg-neutral-800 text-neutral-300 rounded px-1.5 py-0.5 mr-1">{{ t }}</span>{% endfor %}
+          </div>
+        </li>
+        {% endfor %}
+      </ul>
+    </div>
+    {% endfor %}
+  </div>
+</section>
+{% endif %}
+{% endblock %}

app/web/templates/index.html

@@ -0,0 +1,44 @@
+{% extends "base.html" %}
+
+{% block content %}
+<div class="flex items-end justify-between mb-6">
+  <div>
+    <h1 class="text-2xl font-semibold">Characters</h1>
+    <p class="text-sm text-neutral-400">Pick one to inspect, or create your own opponent.</p>
+  </div>
+</div>
+
+<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
+  {% for c in characters %}
+  <a href="/characters/{{ c.id }}" class="group rounded-xl border border-neutral-800 bg-neutral-900 hover:border-neutral-600 hover:bg-neutral-800/60 transition p-5 block">
+    <div class="flex items-start justify-between">
+      <div class="text-3xl">{{ c.avatar_emoji or "♟" }}</div>
+      <div class="flex items-center gap-2">
+        {% if c.is_preset %}
+        <span class="text-[10px] uppercase tracking-wider bg-neutral-800 text-neutral-300 rounded px-1.5 py-0.5">Preset</span>
+        {% endif %}
+        {% if c.state.value == "generating_memories" %}
+        <span class="text-[10px] uppercase tracking-wider bg-amber-900/60 text-amber-200 rounded px-1.5 py-0.5">Generating…</span>
+        {% elif c.state.value == "generation_failed" %}
+        <span class="text-[10px] uppercase tracking-wider bg-rose-900/60 text-rose-200 rounded px-1.5 py-0.5">Failed</span>
+        {% else %}
+        <span class="text-[10px] uppercase tracking-wider bg-emerald-900/60 text-emerald-200 rounded px-1.5 py-0.5">Ready</span>
+        {% endif %}
+      </div>
+    </div>
+    <div class="mt-3">
+      <div class="text-lg font-semibold group-hover:text-white">{{ c.name }}</div>
+      <div class="text-sm text-neutral-400 mt-1 line-clamp-3">{{ c.short_description }}</div>
+    </div>
+    <div class="mt-4 flex items-center justify-between text-xs text-neutral-500">
+      <span>Target {{ c.target_elo }} Elo{% if c.adaptive %} · adaptive{% endif %}</span>
+      <span>agg {{ c.aggression }} · risk {{ c.risk_tolerance }} · pat {{ c.patience }} · talk {{ c.trash_talk }}</span>
+    </div>
+  </a>
+  {% else %}
+  <div class="col-span-full text-center py-12 text-neutral-500">
+    No characters yet. <a href="/characters/new" class="text-emerald-400 hover:underline">Create one.</a>
+  </div>
+  {% endfor %}
+</div>
+{% endblock %}

app/web/templates/new.html

@@ -0,0 +1,94 @@
+{% extends "base.html" %}
+
+{% block title %}New character — Metropolis Chess Club{% endblock %}
+
+{% block content %}
+<h1 class="text-2xl font-semibold mb-1">New character</h1>
+<p class="text-sm text-neutral-400 mb-6">
+  We'll generate their memories from the backstory in the background. Takes ~30–60s.
+</p>
+
+<form method="post" action="/characters/new" class="space-y-6 max-w-3xl">
+
+  <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
+    <div class="md:col-span-2">
+      <label class="block text-sm mb-1">Name</label>
+      <input required name="name" class="w-full rounded bg-neutral-900 border border-neutral-800 px-3 py-2" />
+    </div>
+    <div>
+      <label class="block text-sm mb-1">Avatar emoji</label>
+      <input name="avatar_emoji" maxlength="4" value="♟" class="w-full rounded bg-neutral-900 border border-neutral-800 px-3 py-2" />
+    </div>
+  </div>
+
+  <div>
+    <label class="block text-sm mb-1">Short description</label>
+    <input name="short_description" maxlength="280" class="w-full rounded bg-neutral-900 border border-neutral-800 px-3 py-2" />
+    <p class="text-xs text-neutral-500 mt-1">Shown on character cards. Keep it punchy.</p>
+  </div>
+
+  <div>
+    <label class="block text-sm mb-1">Backstory</label>
+    <textarea name="backstory" rows="8" class="w-full rounded bg-neutral-900 border border-neutral-800 px-3 py-2" placeholder="Where did they come from? Who taught them? What shaped their style?"></textarea>
+    <p class="text-xs text-neutral-500 mt-1">Feeds memory generation. More specific = richer memories.</p>
+  </div>
+
+  <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+    <div>
+      <label class="block text-sm mb-1">Voice / tone</label>
+      <input name="voice_descriptor" maxlength="280" placeholder="e.g. gruff Russian grandmaster" class="w-full rounded bg-neutral-900 border border-neutral-800 px-3 py-2" />
+    </div>
+    <div>
+      <label class="block text-sm mb-1">Quirks</label>
+      <input name="quirks" placeholder="habits, sayings, small tells" class="w-full rounded bg-neutral-900 border border-neutral-800 px-3 py-2" />
+    </div>
+  </div>
+
+  <fieldset class="space-y-3 rounded border border-neutral-800 p-4">
+    <legend class="px-2 text-sm text-neutral-300">Style sliders (1–10)</legend>
+    {% for key, label in [
+      ("aggression", "Aggression"),
+      ("risk_tolerance", "Risk tolerance"),
+      ("patience", "Patience"),
+      ("trash_talk", "Trash talk"),
+    ] %}
+    <div class="flex items-center gap-4">
+      <label class="text-sm w-32">{{ label }}</label>
+      <input type="range" min="1" max="10" value="5" name="{{ key }}"
+             oninput="this.nextElementSibling.value = this.value"
+             class="flex-1 accent-emerald-400" />
+      <output class="text-sm w-6 text-right text-neutral-300">5</output>
+    </div>
+    {% endfor %}
+  </fieldset>
+
+  <fieldset class="space-y-3 rounded border border-neutral-800 p-4">
+    <legend class="px-2 text-sm text-neutral-300">Skill</legend>
+    <div class="flex items-center gap-4">
+      <label class="text-sm w-32">Target Elo</label>
+      <input type="number" min="600" max="2600" step="50" value="1400" name="target_elo" class="w-32 rounded bg-neutral-900 border border-neutral-800 px-3 py-2" />
+      <label class="text-sm flex items-center gap-2 ml-6">
+        <input type="checkbox" name="adaptive" value="1" class="accent-emerald-400" />
+        Adaptive (use target_elo as floor)
+      </label>
+    </div>
+  </fieldset>
+
+  <div>
+    <label class="block text-sm mb-1">Opening preferences</label>
+    <select name="opening_preferences" multiple size="10" class="w-full rounded bg-neutral-900 border border-neutral-800 px-3 py-2 text-sm">
+      {% for op in openings %}
+      <option value="{{ op.name }}">{{ op.eco }} — {{ op.name }} ({{ op.group }})</option>
+      {% endfor %}
+    </select>
+    <p class="text-xs text-neutral-500 mt-1">Ctrl/Cmd-click to pick multiple.</p>
+  </div>
+
+  <div class="pt-2">
+    <button class="rounded bg-emerald-500 px-5 py-2 font-medium text-neutral-900 hover:bg-emerald-400">
+      Create character
+    </button>
+    <a href="/" class="ml-3 text-sm text-neutral-400 hover:text-white">Cancel</a>
+  </div>
+</form>
+{% endblock %}

tests/conftest.py

@@ -0,0 +1,49 @@
+"""Test-suite bootstrap.
+
+Runs BEFORE any `app.*` module is imported so the env vars pick up the
+test database. Without this, `app.db` would grab the production SQLite
+URL at import time.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+_TMP_DIR = Path(tempfile.mkdtemp(prefix="metropolis_tests_"))
+_TEST_DB_PATH = _TMP_DIR / "test.db"
+
+os.environ.setdefault("DATABASE_URL", f"sqlite:///{_TEST_DB_PATH.as_posix()}")
+os.environ.setdefault("GEMINI_API_KEY", "test-key-not-real")
+os.environ.setdefault("LOG_DIR", str(_TMP_DIR / "logs"))
+
+import pytest  # noqa: E402
+from sqlalchemy import delete  # noqa: E402
+
+from app.db import SessionLocal, engine, init_db  # noqa: E402
+from app.models.character import Character  # noqa: E402
+from app.models.memory import Memory  # noqa: E402
+
+
+@pytest.fixture(scope="session", autouse=True)
+def _bootstrap_db() -> None:
+    init_db()
+
+
+@pytest.fixture(autouse=True)
+def _clean_tables():
+    """Wipe every row before each test for deterministic state."""
+    with engine.begin() as conn:
+        conn.execute(delete(Memory))
+        conn.execute(delete(Character))
+    yield
+
+
+@pytest.fixture
+def db_session():
+    session = SessionLocal()
+    try:
+        yield session
+    finally:
+        session.close()

tests/test_live_llm.py

@@ -0,0 +1,90 @@
+"""Opt-in test that hits the real Gemini API.
+
+Only runs when BOTH:
+  - env var RUN_LIVE_LLM_TESTS=1
+  - a real GEMINI_API_KEY is present (not the test placeholder)
+
+Run it with:
+    RUN_LIVE_LLM_TESTS=1 GEMINI_API_KEY=... pytest -m live
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+from sqlalchemy import select
+
+from app.characters.memory_generator import generate_and_store
+from app.config import get_settings
+from app.db import SessionLocal
+from app.models.character import Character, CharacterState
+from app.models.memory import Memory, MemoryScope, MemoryType
+
+pytestmark = pytest.mark.live
+
+
+def _should_skip() -> tuple[bool, str]:
+    if os.environ.get("RUN_LIVE_LLM_TESTS") != "1":
+        return True, "RUN_LIVE_LLM_TESTS not set"
+    key = os.environ.get("GEMINI_API_KEY", "")
+    if not key or key == "test-key-not-real":
+        return True, "real GEMINI_API_KEY not present"
+    return False, ""
+
+
+def test_live_generation_produces_valid_memories():
+    skip, reason = _should_skip()
+    if skip:
+        pytest.skip(reason)
+
+    # The lru_cache in get_settings + get_llm_client may be holding the
+    # test-time API key. Refresh them against the current environment.
+    from app.config import get_settings as _s
+    from app.llm.client import get_llm_client as _c
+
+    _s.cache_clear()
+    _c.cache_clear()
+
+    settings = get_settings()
+
+    with SessionLocal() as s:
+        char = Character(
+            name="Anja Berg",
+            short_description="A quiet Norwegian endgame specialist",
+            backstory=(
+                "Grew up in Trondheim. Learned from her uncle, a retired engineer "
+                "who played correspondence chess. Spent her twenties studying Capablanca games."
+            ),
+            aggression=3,
+            risk_tolerance=4,
+            patience=9,
+            trash_talk=2,
+            target_elo=2200,
+            adaptive=False,
+            opening_preferences=["Catalan Opening", "English Opening"],
+            voice_descriptor="calm, precise Scandinavian English",
+            quirks="writes notes in tiny handwriting between games",
+            state=CharacterState.GENERATING_MEMORIES,
+            is_preset=False,
+        )
+        s.add(char)
+        s.commit()
+        character_id = char.id
+
+    count = generate_and_store(character_id)
+    assert settings.memory_gen_min // 2 <= count <= settings.memory_gen_max + 10
+
+    with SessionLocal() as s:
+        char = s.get(Character, character_id)
+        assert char.state == CharacterState.READY
+        rows = list(s.execute(select(Memory).where(Memory.character_id == character_id)).scalars())
+
+    assert len(rows) == count
+    for m in rows:
+        assert isinstance(m.scope, MemoryScope)
+        assert isinstance(m.type, MemoryType)
+        assert -1.0 <= m.emotional_valence <= 1.0
+        assert m.narrative_text and len(m.narrative_text) >= 20
+        assert isinstance(m.triggers, list) and m.triggers
+        assert isinstance(m.relevance_tags, list) and m.relevance_tags

tests/test_memory_generator.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from sqlalchemy import select
+
+from app.characters.memory_generator import GeneratedMemory, build_prompt, generate_and_store
+from app.db import SessionLocal
+from app.models.character import Character, CharacterState
+from app.models.memory import Memory, MemoryScope, MemoryType
+
+
+class FakeLLMClient:
+    """Duck-typed stand-in for `LLMClient` used in tests."""
+
+    def __init__(self, memories: list[GeneratedMemory] | Exception):
+        self._result = memories
+
+    def generate_structured(self, **kwargs):
+        if isinstance(self._result, Exception):
+            raise self._result
+        return self._result
+
+
+def _make_character(session) -> str:
+    char = Character(
+        name="Test Character",
+        short_description="A test",
+        backstory="Born in a test. Lived in a test. Died in a test.",
+        aggression=6,
+        risk_tolerance=6,
+        patience=5,
+        trash_talk=4,
+        target_elo=1600,
+        adaptive=False,
+        opening_preferences=["Ruy Lopez", "Sicilian Najdorf"],
+        voice_descriptor="test voice",
+        quirks="never blinks",
+        state=CharacterState.GENERATING_MEMORIES,
+    )
+    session.add(char)
+    session.commit()
+    return char.id
+
+
+def _fake_memories(n: int = 30) -> list[GeneratedMemory]:
+    out: list[GeneratedMemory] = []
+    types = list(MemoryType)
+    for i in range(n):
+        out.append(
+            GeneratedMemory(
+                scope=MemoryScope.CHARACTER_LORE,
+                type=types[i % len(types)],
+                emotional_valence=(i % 5 - 2) / 2.0,  # spread -1..1
+                triggers=[f"trigger_{i}", f"alt_{i}"],
+                narrative_text=f"This is the {i}-th fake memory. It has enough length to pass validation.",
+                relevance_tags=[f"tag_{i % 3}"],
+            )
+        )
+    return out
+
+
+def test_build_prompt_contains_character_details():
+    char = Character(
+        name="Vera",
+        short_description="quiet",
+        backstory="a long backstory here",
+        aggression=9,
+        risk_tolerance=2,
+        patience=3,
+        trash_talk=1,
+        target_elo=2000,
+        adaptive=True,
+        opening_preferences=["Ruy Lopez"],
+        voice_descriptor="calm",
+        quirks="hums",
+    )
+    prompt = build_prompt(char, target=40, minimum=30, maximum=50)
+    assert "Vera" in prompt
+    assert "a long backstory here" in prompt
+    assert "Ruy Lopez" in prompt
+    assert "2000" in prompt
+    assert "adapts" in prompt.lower()  # adaptive line
+
+
+def test_generate_and_store_persists_and_marks_ready():
+    with SessionLocal() as s:
+        character_id = _make_character(s)
+
+    fake = FakeLLMClient(_fake_memories(30))
+    count = generate_and_store(character_id, client=fake)
+    assert count == 30
+
+    with SessionLocal() as s:
+        char = s.get(Character, character_id)
+        assert char is not None
+        assert char.state == CharacterState.READY
+        assert char.memory_generation_error is None
+
+        memories = list(s.execute(select(Memory).where(Memory.character_id == character_id)).scalars())
+        assert len(memories) == 30
+        # Spread check — we should see multiple distinct types.
+        assert len({m.type for m in memories}) >= 4
+
+
+def test_generate_and_store_failure_marks_character_failed():
+    with SessionLocal() as s:
+        character_id = _make_character(s)
+
+    fake = FakeLLMClient(RuntimeError("fake Gemini outage"))
+    import pytest
+
+    with pytest.raises(RuntimeError):
+        generate_and_store(character_id, client=fake)
+
+    with SessionLocal() as s:
+        char = s.get(Character, character_id)
+        assert char is not None
+        assert char.state == CharacterState.GENERATION_FAILED
+        assert char.memory_generation_error is not None
+        assert "fake Gemini outage" in char.memory_generation_error
+
+
+def test_generate_and_store_rejects_too_few():
+    """If the LLM returns a suspiciously tiny batch, we fail the character."""
+    with SessionLocal() as s:
+        character_id = _make_character(s)
+
+    fake = FakeLLMClient(_fake_memories(3))  # below min//2
+    import pytest
+
+    with pytest.raises(Exception):
+        generate_and_store(character_id, client=fake)
+
+    with SessionLocal() as s:
+        char = s.get(Character, character_id)
+        assert char.state == CharacterState.GENERATION_FAILED

tests/test_memory_schema.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from app.models.memory import MemoryScope, MemoryType
+from app.schemas.memory import MemoryCreate
+
+
+def _valid_payload(**overrides) -> dict:
+    payload: dict = dict(
+        scope=MemoryScope.CHARACTER_LORE,
+        type=MemoryType.FORMATIVE,
+        emotional_valence=0.0,
+        triggers=["grandfather", "Minsk"],
+        narrative_text="I remember my grandfather teaching me in a cold room.",
+        relevance_tags=["childhood"],
+    )
+    payload.update(overrides)
+    return payload
+
+
+def test_valid_payload_parses():
+    m = MemoryCreate(**_valid_payload())
+    assert m.narrative_text.startswith("I remember")
+    assert m.scope == MemoryScope.CHARACTER_LORE
+    assert m.type == MemoryType.FORMATIVE
+
+
+def test_rejects_out_of_range_valence():
+    with pytest.raises(ValidationError):
+        MemoryCreate(**_valid_payload(emotional_valence=1.5))
+    with pytest.raises(ValidationError):
+        MemoryCreate(**_valid_payload(emotional_valence=-1.5))
+
+
+def test_rejects_invalid_enum():
+    with pytest.raises(ValidationError):
+        MemoryCreate(**_valid_payload(scope="not_a_scope"))
+    with pytest.raises(ValidationError):
+        MemoryCreate(**_valid_payload(type="not_a_type"))
+
+
+def test_rejects_empty_narrative():
+    with pytest.raises(ValidationError):
+        MemoryCreate(**_valid_payload(narrative_text=""))
+
+
+def test_triggers_stripped_and_deduped():
+    m = MemoryCreate(**_valid_payload(triggers=["  Sicilian ", "sicilian", "Najdorf", ""]))
+    assert m.triggers == ["Sicilian", "Najdorf"]
+
+
+def test_accepts_enum_values_as_strings():
+    m = MemoryCreate(**_valid_payload(scope="character_lore", type="opinion"))
+    assert m.scope == MemoryScope.CHARACTER_LORE
+    assert m.type == MemoryType.OPINION

tests/test_preset_seeding.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from sqlalchemy import select
+
+from app.characters.presets import PRESETS
+from app.characters.seed import seed_presets
+from app.db import SessionLocal
+from app.models.character import Character
+
+
+def test_seed_presets_creates_all():
+    results = seed_presets(run_generation=False)
+    assert set(results.keys()) == {p.preset_key for p in PRESETS}
+    assert all(v is True for v in results.values())
+
+    with SessionLocal() as s:
+        rows = list(s.execute(select(Character)).scalars())
+        assert len(rows) == len(PRESETS)
+        preset_keys = {r.preset_key for r in rows}
+        assert preset_keys == {p.preset_key for p in PRESETS}
+        assert all(r.is_preset for r in rows)
+
+
+def test_seed_presets_is_idempotent():
+    seed_presets(run_generation=False)
+    first_ids = {}
+    with SessionLocal() as s:
+        for r in s.execute(select(Character)).scalars():
+            first_ids[r.preset_key] = r.id
+
+    results2 = seed_presets(run_generation=False)
+    assert all(v is False for v in results2.values())
+
+    with SessionLocal() as s:
+        rows = list(s.execute(select(Character)).scalars())
+        assert len(rows) == len(PRESETS)
+        for r in rows:
+            assert r.id == first_ids[r.preset_key]
+
+
+def test_seed_presets_skips_generation_when_disabled():
+    seed_presets(run_generation=False)
+    with SessionLocal() as s:
+        rows = list(s.execute(select(Character)).scalars())
+        for r in rows:
+            # Nothing persisted yet — seed ran without generation.
+            assert len(list(r.memories)) == 0

tests/test_style.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from app.characters.style import StyleFragments, style_summary_line, style_to_prompt_fragments
+from app.models.character import Character
+
+
+def _char(**overrides) -> Character:
+    defaults: dict = dict(
+        name="Test",
+        aggression=5,
+        risk_tolerance=5,
+        patience=5,
+        trash_talk=5,
+        target_elo=1500,
+    )
+    defaults.update(overrides)
+    return Character(**defaults)
+
+
+def test_fragments_shape_is_stable():
+    frags = style_to_prompt_fragments(_char())
+    assert set(frags.keys()) == set(StyleFragments.__annotations__.keys())
+    for v in frags.values():
+        assert isinstance(v, str) and v
+
+
+def test_low_mid_high_buckets_produce_distinct_aggression_fragments():
+    low = style_to_prompt_fragments(_char(aggression=1))["aggression"]
+    mid = style_to_prompt_fragments(_char(aggression=5))["aggression"]
+    high = style_to_prompt_fragments(_char(aggression=10))["aggression"]
+    assert low != mid != high
+    assert low != high
+
+
+def test_bucket_boundaries():
+    # 3 is low, 4 is mid; 7 is mid, 8 is high. This encodes the mapping so a
+    # future edit doesn't silently shift the buckets.
+    assert (
+        style_to_prompt_fragments(_char(aggression=3))["aggression"]
+        == style_to_prompt_fragments(_char(aggression=1))["aggression"]
+    )
+    assert (
+        style_to_prompt_fragments(_char(aggression=4))["aggression"]
+        == style_to_prompt_fragments(_char(aggression=7))["aggression"]
+    )
+    assert (
+        style_to_prompt_fragments(_char(aggression=8))["aggression"]
+        == style_to_prompt_fragments(_char(aggression=10))["aggression"]
+    )
+
+
+def test_summary_line_uses_character_name():
+    line = style_summary_line(_char(name="Vera"))
+    assert line.startswith("Vera ")
+    assert line.endswith(".")
+
+
+def test_each_slider_changes_only_its_own_fragment():
+    base = style_to_prompt_fragments(_char())
+    with_high_patience = style_to_prompt_fragments(_char(patience=10))
+
+    assert with_high_patience["patience"] != base["patience"]
+    assert with_high_patience["aggression"] == base["aggression"]
+    assert with_high_patience["risk_tolerance"] == base["risk_tolerance"]
+    assert with_high_patience["trash_talk"] == base["trash_talk"]