app.py

from __future__ import annotations

import os
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, Sequence

from flask import Flask, jsonify, redirect, render_template, request, session, url_for

from game_logic import (
    DESTRUCTION_ZONE_SIZE,
    calculate_board_size,
    count_remaining_words,
    initialize_game_state,
    resolve_turn,
)
from game_logic_blocks import (
    BLOCKS_COMBO_THRESHOLD,
    initialize_blocks_state,
    occupied_neighbors,
    occupied_word_indices,
    resolve_blocks_turn,
    serialize_blocks_grid,
)
from game_logic_restriction import (
    RestrictionRule,
    initialize_restriction_state,
    load_restriction_rules,
    local_rule_supported,
    resolve_restriction_turn,
    validate_clue_locally,
)
from llm_client import (
    BlocksCandidate,
    BlocksPrimaryChoiceResult,
    BlocksCandidateScore,
    BlocksCandidateScoringResult,
    build_ranker_from_env,
    format_startup_probe_message,
    normalize_word,
    run_startup_probe,
)
from persistence import BestRunSummary, RunStore, build_run_store
from settings import Settings, get_settings

SETTINGS = get_settings()
BASE_DIR = SETTINGS.base_dir
ASSETS_DIR = SETTINGS.assets_dir
DEFAULT_VOCAB_FILE = SETTINGS.default_vocab_file
RESTRICTION_RULES_FILE = SETTINGS.restriction_rules_file
CONFIGURED_VOCAB_FILE = SETTINGS.configured_vocab_file
SELECTED_PACK_SESSION_KEY = "selected_pack_id"
SELECTED_MODE_SESSION_KEY = "selected_mode_id"
ACTIVE_LLM_PROVIDER = SETTINGS.semantris_llm_provider

MODE_IDS = {
    "iteration": "iteration",
    "restriction": "restriction",
    "blocks": "blocks",
}

MODE_PAGE_ENDPOINTS = {
    MODE_IDS["iteration"]: "iteration_mode",
    MODE_IDS["restriction"]: "restriction_mode",
    MODE_IDS["blocks"]: "blocks_mode",
}
BLOCKS_PRIMARY_BATCH_SIZE = 8
BLOCKS_SCORING_BATCH_SIZE = 6

app = Flask(__name__)
app.secret_key = SETTINGS.flask_secret_key or os.urandom(24)
RUN_STORE = build_run_store(SETTINGS)


def _env_flag(name: str) -> bool:
    if name == "SEMANTRIS_DEBUG_BLOCKS_LLM":
        return SETTINGS.semantris_debug_blocks_llm
    return os.getenv(name, "0").strip().lower() in {"1", "true", "yes", "on"}


def _emit_blocks_app_debug_trace(label: str, payload: Any) -> None:
    if not _env_flag("SEMANTRIS_DEBUG_BLOCKS_LLM"):
        return

    print(f"[Blocks App Debug] {label}={payload}", flush=True)


@dataclass
class BlocksLlmAggregate:
    latency_ms: int = 0
    providers: list[str] = field(default_factory=list)
    used_fallback: bool = False
    warnings: list[str] = field(default_factory=list)

    def record(self, result: Any) -> None:
        self.latency_ms += max(0, int(getattr(result, "latency_ms", 0) or 0))

        provider = getattr(result, "provider", None)
        if isinstance(provider, str) and provider and provider not in self.providers:
            self.providers.append(provider)

        if bool(getattr(result, "used_fallback", False)):
            self.used_fallback = True

        warning = getattr(result, "warning", None)
        if isinstance(warning, str) and warning and warning not in self.warnings:
            self.warnings.append(warning)

    @property
    def provider_label(self) -> str | None:
        return _combine_provider_labels(*self.providers)

    @property
    def warning_text(self) -> str | None:
        return _join_warnings(*self.warnings)


def _partition_evenly(items: Sequence[Any], max_batch_size: int) -> list[list[Any]]:
    if max_batch_size <= 0:
        raise ValueError("Batch size must be positive.")
    if not items:
        return []

    batch_count = max(1, (len(items) + max_batch_size - 1) // max_batch_size)
    batches: list[list[Any]] = [[] for _ in range(batch_count)]
    for index, item in enumerate(items):
        batches[index % batch_count].append(item)
    return [batch for batch in batches if batch]


def load_vocabulary(vocab_file: Path) -> list[str]:
    if not vocab_file.exists():
        raise FileNotFoundError(f"Vocabulary file not found: {vocab_file}")

    deduped_words: list[str] = []
    seen: set[str] = set()

    with vocab_file.open("r", encoding="utf-8") as handle:
        for raw_line in handle:
            word = raw_line.strip()
            if not word:
                continue

            normalized = normalize_word(word)
            if normalized in seen:
                continue

            seen.add(normalized)
            deduped_words.append(word)

    if not deduped_words:
        raise ValueError(f"Vocabulary file is empty: {vocab_file}")

    return deduped_words


@dataclass(frozen=True)
class VocabularyPack:
    pack_id: str
    file_path: Path
    display_name: str
    words: tuple[str, ...]

    @property
    def word_count(self) -> int:
        return len(self.words)


def build_vocabulary_catalog(assets_dir: Path) -> dict[str, VocabularyPack]:
    catalog: dict[str, VocabularyPack] = {}

    for vocab_file in sorted(assets_dir.glob("*.txt")):
        pack_id = vocab_file.stem
        if pack_id in catalog:
            raise ValueError(f"Duplicate vocabulary pack id: {pack_id}")

        catalog[pack_id] = VocabularyPack(
            pack_id=pack_id,
            file_path=vocab_file,
            display_name=pack_id,
            words=tuple(load_vocabulary(vocab_file)),
        )

    if not catalog:
        raise ValueError(f"No vocabulary packs found in {assets_dir}")

    return catalog


def resolve_default_pack_id(catalog: dict[str, VocabularyPack]) -> str:
    configured_id = CONFIGURED_VOCAB_FILE.stem
    if configured_id in catalog:
        return configured_id

    default_id = DEFAULT_VOCAB_FILE.stem
    if default_id in catalog:
        return default_id

    return next(iter(catalog))


VOCABULARY_CATALOG = build_vocabulary_catalog(ASSETS_DIR)
DEFAULT_VOCAB_PACK_ID = resolve_default_pack_id(VOCABULARY_CATALOG)
RESTRICTION_RULES = load_restriction_rules(RESTRICTION_RULES_FILE)
RESTRICTION_RULES_BY_ID = {rule.rule_id: rule for rule in RESTRICTION_RULES}
RANKER = build_ranker_from_env(provider_name=ACTIVE_LLM_PROVIDER, settings=SETTINGS)


def selected_pack_id_from_session() -> str:
    pack_id = session.get(SELECTED_PACK_SESSION_KEY)
    if isinstance(pack_id, str) and pack_id in VOCABULARY_CATALOG:
        return pack_id

    return DEFAULT_VOCAB_PACK_ID


def selected_mode_id_from_session() -> str:
    mode_id = session.get(SELECTED_MODE_SESSION_KEY)
    if isinstance(mode_id, str) and mode_id in MODE_IDS.values():
        return mode_id
    return MODE_IDS["iteration"]


def get_selected_pack() -> VocabularyPack:
    return VOCABULARY_CATALOG[selected_pack_id_from_session()]


def vocabulary_pack_options() -> list[dict[str, Any]]:
    return [
        {
            "id": pack.pack_id,
            "display_name": pack.display_name,
            "word_count": pack.word_count,
        }
        for pack in VOCABULARY_CATALOG.values()
    ]


def words_for_indices(indices: list[int], vocabulary: tuple[str, ...]) -> list[str]:
    return [vocabulary[index] for index in indices]


def _game_result_for_state(state: dict[str, Any]) -> str | None:
    game_result = state.get("game_result")
    if isinstance(game_result, str):
        return game_result
    if state.get("game_over"):
        return "win"
    return None


def _elapsed_seconds_for_state(state: dict[str, Any]) -> int:
    started_at_ms = int(state.get("started_at_ms", 0) or 0)
    ended_at_ms = int(state.get("ended_at_ms", started_at_ms) or started_at_ms)
    return max(0, round((ended_at_ms - started_at_ms) / 1000))


def _best_run_payload(summary: BestRunSummary | None) -> dict[str, Any] | None:
    if summary is None:
        return None
    return {
        "run_record_id": summary.run_record_id,
        "score": summary.score,
        "turns": summary.turns,
        "elapsed_seconds": summary.elapsed_seconds,
        "created_at": summary.created_at_iso,
    }


def _state_with_persistence_metadata(
    state: dict[str, Any],
    *,
    mode_id: str,
    pack: VocabularyPack,
) -> dict[str, Any]:
    updated_state = dict(state)
    updated_state.setdefault("persisted_run_id", None)
    updated_state.setdefault("persisted_run_is_new_best", False)
    if "best_run_summary" not in updated_state:
        updated_state["best_run_summary"] = _best_run_payload(
            RUN_STORE.best_run_for(mode_id=mode_id, pack_id=pack.pack_id)
        )
    return updated_state


def _persist_completed_run_if_needed(
    state: dict[str, Any],
    *,
    mode_id: str,
    pack: VocabularyPack,
) -> dict[str, Any]:
    updated_state = _state_with_persistence_metadata(state, mode_id=mode_id, pack=pack)
    if not updated_state.get("game_over"):
        return updated_state
    if updated_state.get("persisted_run_id") is not None:
        return updated_state

    recorded = RUN_STORE.record_completed_run(
        mode_id=mode_id,
        pack_id=pack.pack_id,
        vocabulary_name=pack.file_path.name,
        score=int(updated_state.get("score", 0) or 0),
        turns=int(updated_state.get("turn_count", 0) or 0),
        elapsed_seconds=_elapsed_seconds_for_state(updated_state),
        game_result=_game_result_for_state(updated_state) or "win",
        provider_label=updated_state.get("last_provider"),
        used_fallback=bool(updated_state.get("used_fallback", False)),
    )
    updated_state["persisted_run_id"] = recorded.run_record_id
    updated_state["persisted_run_is_new_best"] = recorded.is_new_best
    updated_state["best_run_summary"] = _best_run_payload(recorded.best_run)
    return updated_state


def _persistence_payload(state: dict[str, Any]) -> dict[str, Any]:
    return {
        "run_record_id": state.get("persisted_run_id"),
        "run_saved": state.get("persisted_run_id") is not None,
        "is_new_best": bool(state.get("persisted_run_is_new_best", False)),
        "best_run": state.get("best_run_summary"),
    }


def serialize_iteration_state(state: dict[str, Any], pack: VocabularyPack) -> dict[str, Any]:
    board_words = words_for_indices(state["board_indices"], pack.words)
    target_index = state.get("target_index")
    target_word = pack.words[target_index] if target_index is not None else None
    remaining_words = count_remaining_words(pack.word_count, state["used_mask"])
    danger_zone_size = min(DESTRUCTION_ZONE_SIZE, len(board_words))

    return {
        "mode_id": state.get("mode_id", MODE_IDS["iteration"]),
        "score": state["score"],
        "board": board_words,
        "target_word": target_word,
        "turn_count": state["turn_count"],
        "started_at_ms": state["started_at_ms"],
        "ended_at_ms": state.get("ended_at_ms"),
        "last_latency_ms": state.get("last_latency_ms"),
        "last_provider": state.get("last_provider"),
        "used_fallback": state.get("used_fallback", False),
        "last_warning": state.get("last_warning"),
        "last_clue": state.get("last_clue"),
        "game_over": state.get("game_over", False),
        "game_result": _game_result_for_state(state),
        "vocabulary_name": state["vocabulary_name"],
        "board_goal_size": min(calculate_board_size(state["score"]), pack.word_count),
        "danger_zone_size": danger_zone_size,
        "danger_zone_words": board_words[-danger_zone_size:],
        "remaining_words": remaining_words,
        "seen_words": pack.word_count - remaining_words,
        "total_vocabulary": pack.word_count,
        "run_exhausted": remaining_words == 0,
        "persistence": _persistence_payload(state),
    }


def serialize_restriction_state(state: dict[str, Any], pack: VocabularyPack) -> dict[str, Any]:
    payload = serialize_iteration_state(state, pack)
    active_rule = RESTRICTION_RULES_BY_ID.get(str(state.get("active_rule_id", "")).strip())
    payload.update(
        {
            "mode_id": MODE_IDS["restriction"],
            "strike_count": state.get("strike_count", 0),
            "max_strikes": state.get("max_strikes", 0),
            "active_rule_id": state.get("active_rule_id"),
            "active_rule_name": active_rule.display_name if active_rule else "Unknown rule",
            "active_rule_description": active_rule.description if active_rule else "No rule loaded.",
            "last_rule_passed": state.get("last_rule_passed"),
            "last_rule_reason": state.get("last_rule_reason"),
        }
    )
    return payload


def serialize_blocks_state(state: dict[str, Any], pack: VocabularyPack) -> dict[str, Any]:
    remaining_words = count_remaining_words(pack.word_count, state["used_mask"])
    last_primary_index = state.get("last_primary_index")
    last_scored_cells = []
    for item in state.get("last_scored_cells", []):
        index = item.get("index")
        if index is None:
            continue
        last_scored_cells.append(
            {
                "cell": item.get("cell"),
                "word": pack.words[index],
                "score": item.get("score"),
            }
        )

    return {
        "mode_id": MODE_IDS["blocks"],
        "score": state["score"],
        "turn_count": state["turn_count"],
        "started_at_ms": state["started_at_ms"],
        "ended_at_ms": state.get("ended_at_ms"),
        "last_latency_ms": state.get("last_latency_ms"),
        "last_provider": state.get("last_provider"),
        "used_fallback": state.get("used_fallback", False),
        "last_warning": state.get("last_warning"),
        "last_clue": state.get("last_clue"),
        "game_over": state.get("game_over", False),
        "game_result": _game_result_for_state(state),
        "vocabulary_name": state["vocabulary_name"],
        "remaining_words": remaining_words,
        "seen_words": pack.word_count - remaining_words,
        "total_vocabulary": pack.word_count,
        "grid_width": state["grid_width"],
        "grid_height": state["grid_height"],
        "cells": serialize_blocks_grid(state["grid_indices"], pack.words, state["grid_width"]),
        "target_occupied_cells": state["target_occupied_cells"],
        "last_primary_word": pack.words[last_primary_index] if last_primary_index is not None else None,
        "last_primary_cell": state.get("last_primary_cell"),
        "last_chain_words": words_for_indices(list(state.get("last_chain_indices", [])), pack.words),
        "last_chain_size": state.get("last_chain_size", 0),
        "last_scored_cells": last_scored_cells,
        "persistence": _persistence_payload(state),
    }


def _commit_session_state(pack: VocabularyPack, mode_id: str, state: dict[str, Any]) -> None:
    session.clear()
    session[SELECTED_PACK_SESSION_KEY] = pack.pack_id
    session[SELECTED_MODE_SESSION_KEY] = mode_id
    session.update(state)
    session.modified = True


def initialize_iteration_session(pack: VocabularyPack | None = None) -> dict[str, Any]:
    pack = pack or get_selected_pack()
    state = initialize_game_state(
        vocabulary_size=pack.word_count,
        vocabulary_name=pack.file_path.name,
    )
    state = {
        **state,
        "mode_id": MODE_IDS["iteration"],
        "game_result": None,
    }
    state = _state_with_persistence_metadata(state, mode_id=MODE_IDS["iteration"], pack=pack)
    _commit_session_state(pack, MODE_IDS["iteration"], state)
    return state


def initialize_restriction_session(pack: VocabularyPack | None = None) -> dict[str, Any]:
    pack = pack or get_selected_pack()
    state = initialize_restriction_state(
        vocabulary_size=pack.word_count,
        vocabulary_name=pack.file_path.name,
        rules=RESTRICTION_RULES,
    )
    state = _state_with_persistence_metadata(state, mode_id=MODE_IDS["restriction"], pack=pack)
    _commit_session_state(pack, MODE_IDS["restriction"], state)
    return state


def initialize_blocks_session(pack: VocabularyPack | None = None) -> dict[str, Any]:
    pack = pack or get_selected_pack()
    state = initialize_blocks_state(
        vocabulary_size=pack.word_count,
        vocabulary_name=pack.file_path.name,
    )
    state = _state_with_persistence_metadata(state, mode_id=MODE_IDS["blocks"], pack=pack)
    _commit_session_state(pack, MODE_IDS["blocks"], state)
    return state


def initialize_session(pack: VocabularyPack | None = None) -> dict[str, Any]:
    return initialize_iteration_session(pack)


def _initialize_mode_session(mode_id: str, pack: VocabularyPack | None = None) -> dict[str, Any]:
    if mode_id == MODE_IDS["iteration"]:
        return initialize_iteration_session(pack)
    if mode_id == MODE_IDS["restriction"]:
        return initialize_restriction_session(pack)
    if mode_id == MODE_IDS["blocks"]:
        return initialize_blocks_session(pack)
    raise ValueError(f"Unsupported mode id: {mode_id}")


def _mode_state_matches(
    session_state: dict[str, Any],
    mode_id: str,
    pack: VocabularyPack,
) -> bool:
    if session_state.get(SELECTED_MODE_SESSION_KEY) != mode_id:
        return False
    if session_state.get("mode_id") != mode_id:
        return False
    if session_state.get("vocabulary_name") != pack.file_path.name:
        return False
    if mode_id in {MODE_IDS["iteration"], MODE_IDS["restriction"]}:
        return "board_indices" in session_state
    if mode_id == MODE_IDS["blocks"]:
        return "grid_indices" in session_state
    return False


def _current_mode_state(mode_id: str) -> dict[str, Any]:
    pack = get_selected_pack()
    session_state = dict(session)
    if not _mode_state_matches(session_state, mode_id, pack):
        return _initialize_mode_session(mode_id, pack)
    finalized_state = _persist_completed_run_if_needed(session_state, mode_id=mode_id, pack=pack)
    if finalized_state != session_state:
        _commit_session_state(pack, mode_id, finalized_state)
    return finalized_state


def current_state() -> dict[str, Any]:
    return _current_mode_state(MODE_IDS["iteration"])


def current_iteration_state() -> dict[str, Any]:
    return _current_mode_state(MODE_IDS["iteration"])


def current_restriction_state() -> dict[str, Any]:
    return _current_mode_state(MODE_IDS["restriction"])


def current_blocks_state() -> dict[str, Any]:
    return _current_mode_state(MODE_IDS["blocks"])


def _selected_pack_from_form() -> VocabularyPack | None:
    pack_id = str(request.form.get("vocabulary_pack_id", "")).strip()
    return VOCABULARY_CATALOG.get(pack_id)


def _page_endpoint_for_mode(mode_id: str) -> str:
    return MODE_PAGE_ENDPOINTS.get(mode_id, MODE_PAGE_ENDPOINTS[MODE_IDS["iteration"]])


def _current_target_word(state: dict[str, Any], pack: VocabularyPack) -> str | None:
    target_index = state.get("target_index")
    if target_index is None:
        return None
    return pack.words[target_index]


def _combine_provider_labels(*providers: str | None) -> str | None:
    labels: list[str] = []
    for provider in providers:
        if not provider or provider in labels:
            continue
        labels.append(provider)
    if not labels:
        return None
    if len(labels) == 1:
        return labels[0]
    return "/".join(labels)


def _join_warnings(*warnings: str | None) -> str | None:
    parts: list[str] = []
    for warning in warnings:
        if not warning or warning in parts:
            continue
        parts.append(warning)
    if not parts:
        return None
    return " ".join(parts)


def _build_blocks_candidates(
    cells: Sequence[int],
    grid_indices: Sequence[int | None],
    pack: VocabularyPack,
) -> list[BlocksCandidate]:
    return [
        BlocksCandidate(candidate_id=cell, word=pack.words[word_index])
        for cell in cells
        if (word_index := grid_indices[cell]) is not None
    ]


def _select_blocks_primary_candidate(
    clue: str,
    candidates: Sequence[BlocksCandidate],
) -> BlocksPrimaryChoiceResult:
    if not candidates:
        raise ValueError("Blocks mode requires at least one occupied candidate.")

    if len(candidates) == 1:
        return BlocksPrimaryChoiceResult(
            candidate_id=candidates[0].candidate_id,
            latency_ms=0,
            provider="local-single-candidate",
            used_fallback=False,
            warning=None,
        )

    aggregate = BlocksLlmAggregate()
    round_candidates = list(candidates)
    round_number = 1

    while len(round_candidates) > 1:
        batches = _partition_evenly(round_candidates, BLOCKS_PRIMARY_BATCH_SIZE)
        _emit_blocks_app_debug_trace(
            f"primary_round_{round_number}_batches",
            [[(candidate.candidate_id, candidate.word) for candidate in batch] for batch in batches],
        )

        winners: list[BlocksCandidate] = []
        winner_trace: list[dict[str, Any]] = []
        for batch in batches:
            if len(batch) == 1:
                selected_id = batch[0].candidate_id
                batch_provider = "local-bye"
                batch_used_fallback = False
                batch_warning = None
            else:
                result = RANKER.pick_blocks_primary_candidate(clue, batch)
                aggregate.record(result)
                selected_id = result.candidate_id
                batch_provider = result.provider
                batch_used_fallback = result.used_fallback
                batch_warning = result.warning

            batch_lookup = {candidate.candidate_id: candidate for candidate in batch}
            winner = batch_lookup[selected_id]
            winners.append(winner)
            winner_trace.append(
                {
                    "candidate_id": winner.candidate_id,
                    "word": winner.word,
                    "provider": batch_provider,
                    "used_fallback": batch_used_fallback,
                    "warning": batch_warning,
                }
            )

        _emit_blocks_app_debug_trace(f"primary_round_{round_number}_winners", winner_trace)
        round_candidates = winners
        round_number += 1

    return BlocksPrimaryChoiceResult(
        candidate_id=round_candidates[0].candidate_id,
        latency_ms=aggregate.latency_ms,
        provider=aggregate.provider_label or "local-single-candidate",
        used_fallback=aggregate.used_fallback,
        warning=aggregate.warning_text,
    )


def _score_blocks_frontier(
    clue: str,
    state: dict[str, Any],
    pack: VocabularyPack,
    primary_cell: int,
) -> tuple[dict[int, int], BlocksLlmAggregate]:
    grid_indices = list(state["grid_indices"])
    width = int(state["grid_width"])
    height = int(state["grid_height"])
    aggregate = BlocksLlmAggregate()
    scored_cells: dict[int, int] = {primary_cell: 100}
    expanding_cells = [primary_cell]
    seen_cells: set[int] = {primary_cell}
    wave_number = 1

    while expanding_cells:
        frontier_cells: list[int] = []
        for cell in expanding_cells:
            for neighbor in occupied_neighbors(grid_indices, cell, width, height):
                if neighbor in seen_cells or grid_indices[neighbor] is None:
                    continue
                seen_cells.add(neighbor)
                frontier_cells.append(neighbor)

        if not frontier_cells:
            break

        frontier_cells = sorted(set(frontier_cells))
        frontier_candidates = _build_blocks_candidates(frontier_cells, grid_indices, pack)
        batches = _partition_evenly(frontier_candidates, BLOCKS_SCORING_BATCH_SIZE)
        _emit_blocks_app_debug_trace(
            f"scoring_wave_{wave_number}_batches",
            [[(candidate.candidate_id, candidate.word) for candidate in batch] for batch in batches],
        )

        wave_scores: dict[int, int] = {}
        for batch in batches:
            result = RANKER.score_blocks_candidates(clue, batch)
            aggregate.record(result)
            for item in result.scored_candidates:
                wave_scores[item.candidate_id] = item.score
                scored_cells[item.candidate_id] = item.score

        scored_trace = [
            {
                "candidate_id": cell,
                "word": pack.words[grid_indices[cell]],
                "score": wave_scores[cell],
            }
            for cell in frontier_cells
            if cell in wave_scores and grid_indices[cell] is not None
        ]
        _emit_blocks_app_debug_trace(f"scoring_wave_{wave_number}_scores", scored_trace)

        expanding_cells = [
            cell
            for cell in frontier_cells
            if wave_scores.get(cell, 0) >= BLOCKS_COMBO_THRESHOLD
        ]
        _emit_blocks_app_debug_trace(f"scoring_wave_{wave_number}_advancing", expanding_cells)
        wave_number += 1

    return scored_cells, aggregate


@app.get("/")
def index() -> str:
    return render_template(
        "home.html",
        vocabulary_packs=vocabulary_pack_options(),
        selected_pack_id=selected_pack_id_from_session(),
        selected_mode_id=selected_mode_id_from_session(),
    )


@app.get("/iteration-mode")
def iteration_mode() -> str:
    return render_template("arcade.html")


@app.post("/start-iteration-mode")
def start_iteration_mode() -> Any:
    pack = _selected_pack_from_form()
    if pack is None:
        return ("Unknown vocabulary pack.", 400)

    initialize_iteration_session(pack)
    return redirect(url_for("iteration_mode"))


@app.get("/restriction-mode")
def restriction_mode() -> str:
    return render_template("restriction.html")


@app.post("/start-restriction-mode")
def start_restriction_mode() -> Any:
    pack = _selected_pack_from_form()
    if pack is None:
        return ("Unknown vocabulary pack.", 400)

    initialize_restriction_session(pack)
    return redirect(url_for("restriction_mode"))


@app.get("/blocks-mode")
def blocks_mode() -> str:
    return render_template("blocks.html")


@app.post("/start-blocks-mode")
def start_blocks_mode() -> Any:
    pack = _selected_pack_from_form()
    if pack is None:
        return ("Unknown vocabulary pack.", 400)

    initialize_blocks_session(pack)
    return redirect(url_for("blocks_mode"))


@app.get("/play")
def play() -> Any:
    return redirect(url_for(_page_endpoint_for_mode(selected_mode_id_from_session())))


@app.get("/api/game/state")
def game_state() -> Any:
    state = current_iteration_state()
    pack = get_selected_pack()
    return jsonify({"state": serialize_iteration_state(state, pack)})


@app.post("/api/game/new")
def new_game() -> Any:
    pack = get_selected_pack()
    state = initialize_iteration_session(pack)
    return jsonify(
        {
            "message": "New run started.",
            "state": serialize_iteration_state(state, pack),
        }
    )


@app.post("/api/game/turn")
def game_turn() -> Any:
    state = current_iteration_state()
    pack = get_selected_pack()
    if state.get("game_over"):
        return jsonify({"error": "This run is finished. Start a new game to play again."}), 400

    payload = request.get_json(silent=True) or {}
    clue = str(payload.get("clue", "")).strip()
    if not clue:
        return jsonify({"error": "Enter a clue before submitting."}), 400

    board_indices = state["board_indices"]
    board_words = words_for_indices(board_indices, pack.words)
    board_lookup = {
        normalize_word(word): index
        for index, word in zip(board_indices, board_words)
    }

    ranking = RANKER.rank_words(clue, board_words)
    ranked_indices = [board_lookup[normalize_word(word)] for word in ranking.ranked_words]
    turn = resolve_turn(
        state=state,
        ranked_indices_most_to_least=ranked_indices,
        vocabulary_size=pack.word_count,
    )

    updated_state = {
        **turn.state,
        "mode_id": MODE_IDS["iteration"],
        "last_latency_ms": ranking.latency_ms,
        "last_provider": ranking.provider,
        "used_fallback": ranking.used_fallback,
        "last_warning": ranking.warning,
        "last_clue": clue,
    }
    updated_state = _persist_completed_run_if_needed(
        updated_state,
        mode_id=MODE_IDS["iteration"],
        pack=pack,
    )

    _commit_session_state(pack, MODE_IDS["iteration"], updated_state)

    return jsonify(
        {
            "message": _build_turn_message(
                turn.resolution,
                len(turn.words_removed_indices),
                updated_state,
                pack.word_count,
            ),
            "resolution": turn.resolution,
            "ranked_board": words_for_indices(turn.ranked_board_indices, pack.words),
            "new_board": words_for_indices(turn.new_board_indices, pack.words),
            "words_removed": words_for_indices(turn.words_removed_indices, pack.words),
            "spawned_words": words_for_indices(turn.spawned_indices, pack.words),
            "target_word_before": _current_target_word(state, pack),
            "state": serialize_iteration_state(updated_state, pack),
        }
    )


@app.get("/api/restriction/state")
def restriction_state() -> Any:
    state = current_restriction_state()
    pack = get_selected_pack()
    return jsonify({"state": serialize_restriction_state(state, pack)})


@app.post("/api/restriction/new")
def new_restriction_game() -> Any:
    pack = get_selected_pack()
    state = initialize_restriction_session(pack)
    return jsonify(
        {
            "message": "New restriction run started.",
            "state": serialize_restriction_state(state, pack),
        }
    )


def _active_rule_from_state(state: dict[str, Any]) -> RestrictionRule:
    rule_id = str(state.get("active_rule_id", "")).strip()
    rule = RESTRICTION_RULES_BY_ID.get(rule_id)
    if rule is None:
        raise ValueError(f"Unknown restriction rule id: {rule_id}")
    return rule


@app.post("/api/restriction/turn")
def restriction_turn() -> Any:
    state = current_restriction_state()
    pack = get_selected_pack()
    if state.get("game_over"):
        return jsonify({"error": "This run is finished. Start a new game to play again."}), 400

    payload = request.get_json(silent=True) or {}
    clue = str(payload.get("clue", "")).strip()
    if not clue:
        return jsonify({"error": "Enter a clue before submitting."}), 400

    rule = _active_rule_from_state(state)
    board_indices = state["board_indices"]
    board_words = words_for_indices(board_indices, pack.words)
    board_lookup = {
        normalize_word(word): index
        for index, word in zip(board_indices, board_words)
    }
    target_word_before = _current_target_word(state, pack)

    if local_rule_supported(rule):
        rule_passed, rule_reason = validate_clue_locally(rule, clue)
        if rule_passed:
            ranking = RANKER.rank_words(clue, board_words)
            ranked_indices = [board_lookup[normalize_word(word)] for word in ranking.ranked_words]
            turn = resolve_restriction_turn(
                state=state,
                rule=rule,
                rule_passed=True,
                rule_reason=rule_reason,
                ranked_indices_most_to_least=ranked_indices,
                vocabulary_size=pack.word_count,
                allow_bonus=True,
                rules=RESTRICTION_RULES,
            )
            updated_state = {
                **turn.state,
                "last_latency_ms": ranking.latency_ms,
                "last_provider": ranking.provider,
                "used_fallback": ranking.used_fallback,
                "last_warning": ranking.warning,
                "last_clue": clue,
            }
        else:
            turn = resolve_restriction_turn(
                state=state,
                rule=rule,
                rule_passed=False,
                rule_reason=rule_reason,
                ranked_indices_most_to_least=None,
                vocabulary_size=pack.word_count,
                allow_bonus=False,
                rules=RESTRICTION_RULES,
            )
            updated_state = {
                **turn.state,
                "last_latency_ms": 0,
                "last_provider": "local-rule-validator",
                "used_fallback": False,
                "last_warning": None,
                "last_clue": clue,
            }
    else:
        judgment = RANKER.judge_restricted_clue(rule.description, clue, board_words)
        ranked_indices = None
        if judgment.ranked_words is not None:
            ranked_indices = [board_lookup[normalize_word(word)] for word in judgment.ranked_words]

        turn = resolve_restriction_turn(
            state=state,
            rule=rule,
            rule_passed=judgment.rule_passed,
            rule_reason=judgment.short_reason,
            ranked_indices_most_to_least=ranked_indices,
            vocabulary_size=pack.word_count,
            allow_bonus=judgment.rule_passed and not judgment.used_fallback,
            rules=RESTRICTION_RULES,
        )
        updated_state = {
            **turn.state,
            "last_latency_ms": judgment.latency_ms,
            "last_provider": judgment.provider,
            "used_fallback": judgment.used_fallback,
            "last_warning": judgment.warning,
            "last_clue": clue,
        }

    updated_state = _persist_completed_run_if_needed(
        updated_state,
        mode_id=MODE_IDS["restriction"],
        pack=pack,
    )

    _commit_session_state(pack, MODE_IDS["restriction"], updated_state)

    return jsonify(
        {
            "message": _build_restriction_turn_message(turn, updated_state, pack.word_count),
            "resolution": turn.resolution,
            "rule_passed": bool(updated_state.get("last_rule_passed")),
            "rule_reason": updated_state.get("last_rule_reason"),
            "strike_delta": updated_state.get("strike_count", 0) - state.get("strike_count", 0),
            "bonus_multiplier_applied": turn.bonus_multiplier_applied,
            "ranked_board": (
                words_for_indices(turn.ranked_board_indices, pack.words)
                if turn.ranked_board_indices is not None
                else None
            ),
            "new_board": words_for_indices(turn.new_board_indices, pack.words),
            "words_removed": words_for_indices(turn.words_removed_indices, pack.words),
            "spawned_words": words_for_indices(turn.spawned_indices, pack.words),
            "penalty_words": words_for_indices(turn.penalty_indices, pack.words),
            "target_word_before": target_word_before,
            "state": serialize_restriction_state(updated_state, pack),
        }
    )


@app.get("/api/blocks/state")
def blocks_state() -> Any:
    state = current_blocks_state()
    pack = get_selected_pack()
    return jsonify({"state": serialize_blocks_state(state, pack)})


@app.post("/api/blocks/new")
def new_blocks_game() -> Any:
    pack = get_selected_pack()
    state = initialize_blocks_session(pack)
    return jsonify(
        {
            "message": "New blocks run started.",
            "state": serialize_blocks_state(state, pack),
        }
    )


@app.post("/api/blocks/turn")
def blocks_turn() -> Any:
    state = current_blocks_state()
    pack = get_selected_pack()
    if state.get("game_over"):
        return jsonify({"error": "This run is finished. Start a new game to play again."}), 400

    payload = request.get_json(silent=True) or {}
    clue = str(payload.get("clue", "")).strip()
    if not clue:
        return jsonify({"error": "Enter a clue before submitting."}), 400

    occupied_indices = occupied_word_indices(state["grid_indices"])
    if not occupied_indices:
        return jsonify({"error": "The grid is empty. Start a new game to play again."}), 400

    occupied_candidates = [
        BlocksCandidate(candidate_id=cell, word=pack.words[word_index])
        for cell, word_index in enumerate(state["grid_indices"])
        if word_index is not None
    ]
    _emit_blocks_app_debug_trace(
        "occupied_candidates",
        [(candidate.candidate_id, candidate.word) for candidate in occupied_candidates],
    )

    primary_choice = _select_blocks_primary_candidate(clue, occupied_candidates)
    primary_cell = primary_choice.candidate_id
    _emit_blocks_app_debug_trace(
        "primary_choice",
        {
            "candidate_id": primary_choice.candidate_id,
            "provider": primary_choice.provider,
            "used_fallback": primary_choice.used_fallback,
            "warning": primary_choice.warning,
        },
    )

    scored_cells, scoring_meta = _score_blocks_frontier(clue, state, pack, primary_cell)
    scoring = BlocksCandidateScoringResult(
        scored_candidates=[
            BlocksCandidateScore(candidate_id=cell, score=score)
            for cell, score in sorted(scored_cells.items())
        ],
        latency_ms=scoring_meta.latency_ms,
        provider=scoring_meta.provider_label or "local-frontier-expansion",
        used_fallback=scoring_meta.used_fallback,
        warning=scoring_meta.warning_text,
    )
    scored_cells = {
        item.candidate_id: item.score
        for item in scoring.scored_candidates
    }
    _emit_blocks_app_debug_trace(
        "blocks_scoring_result",
        {
            "provider": scoring.provider,
            "used_fallback": scoring.used_fallback,
            "warning": scoring.warning,
            "scores": [(item.candidate_id, item.score) for item in scoring.scored_candidates],
        },
    )

    turn = resolve_blocks_turn(
        state=state,
        primary_cell=primary_cell,
        scored_cells=scored_cells,
        vocabulary_size=pack.word_count,
    )

    updated_state = {
        **turn.state,
        "last_latency_ms": primary_choice.latency_ms + scoring.latency_ms,
        "last_provider": _combine_provider_labels(primary_choice.provider, scoring.provider),
        "used_fallback": primary_choice.used_fallback or scoring.used_fallback,
        "last_warning": _join_warnings(primary_choice.warning, scoring.warning),
        "last_clue": clue,
    }
    updated_state = _persist_completed_run_if_needed(
        updated_state,
        mode_id=MODE_IDS["blocks"],
        pack=pack,
    )

    _commit_session_state(pack, MODE_IDS["blocks"], updated_state)

    return jsonify(
        {
            "message": _build_blocks_turn_message(turn),
            "resolution": "chain",
            "primary_word": pack.words[turn.primary_index],
            "primary_cell": turn.primary_cell,
            "scored_cells": [
                {
                    "cell": item["cell"],
                    "word": pack.words[item["index"]],
                    "score": item["score"],
                }
                for item in turn.scored_cells
            ],
            "removed_words": words_for_indices(turn.removed_indices, pack.words),
            "removed_cells": turn.removed_cells,
            "spawned_words": words_for_indices(turn.spawned_indices, pack.words),
            "spawned_cells": turn.spawned_cells,
            "state": serialize_blocks_state(updated_state, pack),
        }
    )


def _build_turn_message(
    resolution: str,
    removed_count: int,
    state: dict[str, Any],
    vocabulary_size: int,
) -> str:
    if state.get("game_over"):
        return "Run complete. You cleared the tower."
    if resolution == "hit":
        if state["used_mask"] and count_remaining_words(vocabulary_size, state["used_mask"]) == 0:
            return f"Hit. Removed {removed_count} word(s). Final stretch: no unseen words remain."
        return f"Hit. Removed {removed_count} word(s)."
    return "Miss. Tower reordered."


def _build_restriction_turn_message(
    turn: Any,
    state: dict[str, Any],
    vocabulary_size: int,
) -> str:
    if turn.resolution == "rule_fail":
        strike_count = state.get("strike_count", 0)
        max_strikes = state.get("max_strikes", 0)
        if state.get("game_over"):
            return f"Rule failed. Strike {strike_count} of {max_strikes}. Run over."
        return f"Rule failed. Strike {strike_count} of {max_strikes}."

    if state.get("game_over") and _game_result_for_state(state) == "win":
        return "Rule passed. Run complete. You cleared the tower."

    if turn.resolution == "hit":
        removed_count = len(turn.words_removed_indices)
        bonus_suffix = ""
        if turn.bonus_multiplier_applied > 1.0:
            bonus_suffix = f" with a {turn.bonus_multiplier_applied:g}x bonus"
        if state["used_mask"] and count_remaining_words(vocabulary_size, state["used_mask"]) == 0:
            return (
                f"Rule passed. Hit. Removed {removed_count} word(s){bonus_suffix}. "
                "Final stretch: no unseen words remain."
            )
        return f"Rule passed. Hit. Removed {removed_count} word(s){bonus_suffix}."

    return "Rule passed. Miss. Tower reordered."


def _build_blocks_turn_message(turn: Any) -> str:
    removed_count = len(turn.removed_indices)
    suffix = "word" if removed_count == 1 else "words"
    return f"Chain cleared {removed_count} {suffix} for {turn.score_gain} points."


def should_run_startup_probe(debug_mode: bool) -> bool:
    if os.getenv("SEMANTRIS_SKIP_LLM_STARTUP_PROBE", "1" if SETTINGS.semantris_skip_llm_startup_probe else "0") == "1":
        return False

    if not debug_mode:
        return True

    return os.getenv("WERKZEUG_RUN_MAIN") == "true"


if __name__ == "__main__":
    debug_mode = SETTINGS.flask_debug
    port = SETTINGS.port

    if should_run_startup_probe(debug_mode):
        print(format_startup_probe_message(run_startup_probe(RANKER)), flush=True)

    app.run(debug=debug_mode, port=port)