Initial commit

.gitignore

@@ -0,0 +1,7 @@
+.env
+.venv/
+.claude/
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/

README.md

@@ -0,0 +1,10 @@
+---
+title: Turnabout Bench
+emoji: "⚖"
+colorFrom: blue
+colorTo: red
+sdk: gradio
+sdk_version: 6.15.2
+app_file: app.py
+pinned: false
+---

app.py

@@ -0,0 +1,377 @@
+#!/usr/bin/env python3
+"""Gradio web UI for Turnabout — Ace Attorney-style agent evaluation environment."""
+
+from __future__ import annotations
+
+import json
+import glob
+import asyncio
+import re as _re
+from pathlib import Path
+
+import gradio as gr
+
+from turnabout.envs.text_env import TextCourtEnv
+from turnabout.i18n import t
+
+CASES_DIR = Path(__file__).parent / "turnabout" / "cases"
+
+
+def list_cases() -> list[str]:
+    return sorted(glob.glob(str(CASES_DIR / "*.json")))
+
+
+def load_case_titles() -> dict[str, str]:
+    titles = {}
+    for path in list_cases():
+        try:
+            with open(path) as f:
+                data = json.load(f)
+            titles[data.get("title", Path(path).stem)] = path
+        except Exception:
+            titles[Path(path).stem] = path
+    return titles
+
+
+class GameSession:
+    def __init__(self):
+        self.env: TextCourtEnv | None = None
+        self.done = False
+        self.lang = "en"
+
+    def start(self, case_path: str, difficulty: str, lang: str) -> str:
+        self.lang = lang
+        self.env = TextCourtEnv(case_path=case_path, difficulty=difficulty, max_steps=200, lang=lang)
+        obs = self.env.reset()
+        self.done = False
+        return obs
+
+    def step(self, action: str) -> tuple[str, float, bool]:
+        if self.env is None or self.done:
+            return t("ui_no_game", self.lang), 0.0, True
+        obs, reward, done, info = self.env.step(action)
+        self.done = done
+        return obs, reward, done
+
+    def get_valid_action_choices(self) -> list[tuple[str, str]]:
+        if self.env is None or self.done:
+            return []
+        valid = self.env.engine.get_valid_actions()
+        return [(a.display(self.lang, self.env.case), str(a)) for a in valid]
+
+    def get_evidence_list(self) -> str:
+        if self.env is None:
+            return t("ui_no_game", self.lang)
+        state = self.env.engine.state
+        if not state or not state.inventory:
+            return t("ui_no_evidence", self.lang)
+        lines = []
+        for i, eid in enumerate(sorted(state.inventory), 1):
+            ev = self.env.case.get_evidence(eid)
+            if ev:
+                desc = ev.detail if ev.detail else ev.description
+                lines.append(f"**{i}. {ev.name}**\n   {desc}")
+        return "\n\n".join(lines)
+
+    def get_status(self) -> str:
+        if self.env is None:
+            return t("ui_no_game", self.lang)
+        state = self.env.engine.state
+        if not state:
+            return t("ui_no_game", self.lang)
+        phase_key = f"phase_{state.phase.value}"
+        phase = t(phase_key, self.lang)
+        penalties = f"{state.penalties}/{self.env.case.court.penalty_limit}"
+        found = len(state.contradictions_found)
+        required = len(self.env.case.court.win_condition.required_contradiction_ids)
+        return (
+            f"**{t('ui_phase', self.lang)}:** {phase}\n\n"
+            f"**{t('ui_penalties', self.lang)}:** {penalties}\n\n"
+            f"**{t('ui_contradictions', self.lang)}:** {found}/{required}\n\n"
+            f"**{t('ui_steps', self.lang)}:** {state.step_count}"
+        )
+
+    def get_metrics_text(self) -> str:
+        if self.env is None:
+            return ""
+        metrics = self.env.get_metrics()
+        return (
+            f"**{t('ui_result', self.lang)}:** {t('ui_won', self.lang) if metrics.won else t('ui_lost', self.lang)}\n\n"
+            f"**{t('ui_contradiction_accuracy', self.lang)}:** {metrics.contradiction_accuracy:.1%}\n\n"
+            f"**{t('ui_evidence_coverage', self.lang)}:** {metrics.evidence_coverage:.1%}\n\n"
+            f"**{t('ui_steps', self.lang)}:** {metrics.total_steps}\n\n"
+            f"**{t('ui_composite_score', self.lang)}:** {metrics.composite_score:.3f}"
+        )
+
+
+session = GameSession()
+
+
+def _msg(role: str, content: str) -> dict:
+    return {"role": role, "content": content}
+
+
+def _lang_code(lang_label: str) -> str:
+    return "zh" if lang_label == "中文" else "en"
+
+
+def on_new_game(case_title: str, difficulty: str, lang_label: str) -> tuple:
+    lang = _lang_code(lang_label)
+    titles = load_case_titles()
+    case_path = titles.get(case_title)
+    if not case_path:
+        cases = list_cases()
+        if not cases:
+            return [_msg("assistant", t("ui_no_cases", lang))], "", "", gr.update(choices=[], value=None), gr.update(interactive=True)
+        case_path = cases[0]
+
+    obs = session.start(case_path, difficulty, lang)
+    history = [_msg("assistant", obs)]
+    choices = session.get_valid_action_choices()
+    return (
+        history,
+        session.get_evidence_list(),
+        session.get_status(),
+        gr.update(choices=choices, value=choices[0][1] if choices else None),
+        gr.update(interactive=True),
+    )
+
+
+def on_execute(action_str: str, chat_history: list, lang_label: str) -> tuple:
+    lang = _lang_code(lang_label)
+    if not action_str:
+        choices = session.get_valid_action_choices()
+        return chat_history, session.get_evidence_list(), session.get_status(), gr.update(choices=choices, value=choices[0][1] if choices else None), gr.update(visible=False), ""
+
+    display_name = action_str
+    choices = session.get_valid_action_choices()
+    for label, val in choices:
+        if val == action_str:
+            display_name = label
+            break
+
+    obs, reward, done = session.step(action_str)
+
+    reward_text = f"\n\n`[{t('ui_reward', lang)}: {reward:+.2f}]`" if reward != 0 else ""
+    response = obs + reward_text
+
+    chat_history = chat_history + [
+        _msg("user", display_name),
+        _msg("assistant", response),
+    ]
+
+    if done:
+        metrics_text = session.get_metrics_text()
+        chat_history = chat_history + [_msg("assistant", f"---\n**{t('ui_game_over', lang)}**\n\n{metrics_text}")]
+        return chat_history, session.get_evidence_list(), session.get_status(), gr.update(choices=[], value=None), gr.update(visible=True), metrics_text
+
+    new_choices = session.get_valid_action_choices()
+    return (
+        chat_history,
+        session.get_evidence_list(),
+        session.get_status(),
+        gr.update(choices=new_choices, value=new_choices[0][1] if new_choices else None),
+        gr.update(visible=False),
+        "",
+    )
+
+
+def on_generate_case(theme: str, gen_difficulty: str, progress=gr.Progress()) -> str:
+    try:
+        from dotenv import load_dotenv
+        load_dotenv()
+    except ImportError:
+        pass
+
+    try:
+        from turnabout.generation.generator import CaseGenerator
+    except ImportError as e:
+        return f"Import error: {e}"
+
+    progress(0.1, desc="Initializing generator...")
+
+    try:
+        generator = CaseGenerator(backend="openai")
+    except Exception as e:
+        return f"Failed to create generator: {e}"
+
+    progress(0.2, desc="Generating case (this may take a minute)...")
+
+    try:
+        case = asyncio.run(generator.generate(
+            theme=theme or None,
+            difficulty=gen_difficulty,
+        ))
+    except Exception as e:
+        return f"Generation failed: {e}"
+
+    progress(0.9, desc="Saving case...")
+
+    slug = _re.sub(r"[^a-z0-9]+", "_", case.title.lower()).strip("_")
+    out_path = CASES_DIR / f"{slug}.json"
+    with open(out_path, "w") as f:
+        json.dump(case.model_dump(), f, indent=2, ensure_ascii=False)
+
+    return f"Case generated successfully!\n\n**{case.title}**\n{case.description}\n\nSaved to: `{out_path.name}`\n\nRefresh the page to see the new case in the Play tab."
+
+
+COMMANDS_HELP_EN = """
+### Investigation Commands
+- `move <location>` — Travel to a location
+- `examine <object>` — Examine an object
+- `talk <person>` — Talk to a character
+- `present <evidence> to <person>` — Show evidence to someone
+- `go to court` — Proceed to court
+
+### Court Commands
+- `press` — Press the witness on current statement
+- `present <evidence>` — Present evidence against current statement
+- `next` / `prev` — Navigate between statements
+"""
+
+COMMANDS_HELP_ZH = """
+### 调查阶段命令
+- `move <地点>` — 前往某地点
+- `examine <物品>` — 调查物品
+- `talk <人物>` — 与人物对话
+- `present <证据> to <人物>` — 向人物出示证据
+- `go to court` — 前往法庭
+
+### 法庭命令
+- `press` — 追问当前证言
+- `present <证据>` — 出示证据反驳当前证言
+- `next` / `prev` — 切换证言
+"""
+
+
+def build_app():
+    case_titles = load_case_titles()
+    case_choices = list(case_titles.keys()) if case_titles else ["No cases found"]
+
+    with gr.Blocks(title="Turnabout Bench") as app:
+        gr.Markdown(t("ui_title", "en"), elem_id="app_title")
+
+        lang_radio = gr.Radio(
+            choices=["English", "中文"],
+            value="English",
+            label="Language / 语言",
+            interactive=True,
+        )
+
+        with gr.Tabs():
+            with gr.Tab("Play", id="play"):
+                with gr.Row():
+                    with gr.Column(scale=3):
+                        chatbot = gr.Chatbot(
+                            label=t("ui_game_label", "en"),
+                            height=480,
+                        )
+                        action_radio = gr.Radio(
+                            choices=[],
+                            label=t("ui_select_action", "en"),
+                            interactive=True,
+                        )
+                        execute_btn = gr.Button(t("ui_execute", "en"), variant="primary")
+
+                    with gr.Column(scale=1):
+                        with gr.Group():
+                            case_dropdown = gr.Dropdown(
+                                choices=case_choices,
+                                value=case_choices[0] if case_choices else None,
+                                label=t("ui_case", "en"),
+                            )
+                            difficulty_radio = gr.Radio(
+                                choices=["easy", "hard"],
+                                value="easy",
+                                label=t("ui_difficulty", "en"),
+                            )
+                            new_game_btn = gr.Button(t("ui_new_game", "en"), variant="primary")
+
+                        status_md = gr.Markdown(
+                            t("ui_click_new_game", "en"),
+                            label=t("ui_status", "en"),
+                        )
+
+                        evidence_md = gr.Markdown(
+                            "",
+                            label=t("ui_evidence", "en"),
+                        )
+
+                        metrics_box = gr.Markdown("", visible=False, label="Final Metrics")
+
+                        with gr.Accordion(t("ui_commands_ref", "en"), open=False):
+                            gr.Markdown(COMMANDS_HELP_EN)
+
+                new_game_btn.click(
+                    fn=on_new_game,
+                    inputs=[case_dropdown, difficulty_radio, lang_radio],
+                    outputs=[chatbot, evidence_md, status_md, action_radio, execute_btn],
+                )
+
+                execute_btn.click(
+                    fn=on_execute,
+                    inputs=[action_radio, chatbot, lang_radio],
+                    outputs=[chatbot, evidence_md, status_md, action_radio, metrics_box, metrics_box],
+                )
+
+            with gr.Tab("Generate Case", id="generate"):
+                gr.Markdown(
+                    "### LLM-Powered Case Generation\n"
+                    "Use the configured LLM gateway to generate new cases automatically."
+                )
+                with gr.Row():
+                    with gr.Column():
+                        theme_input = gr.Textbox(
+                            label=t("ui_theme", "en"),
+                            placeholder="e.g. 'art heist', 'corporate espionage', 'poisoned cake'",
+                        )
+                        gen_difficulty = gr.Radio(
+                            choices=["easy", "hard"],
+                            value="easy",
+                            label=t("ui_difficulty", "en"),
+                        )
+                        generate_btn = gr.Button(t("ui_generate_btn", "en"), variant="primary")
+                    with gr.Column():
+                        gen_output = gr.Markdown(label=t("ui_result", "en"))
+
+                generate_btn.click(
+                    fn=on_generate_case,
+                    inputs=[theme_input, gen_difficulty],
+                    outputs=[gen_output],
+                )
+
+            with gr.Tab("About", id="about"):
+                gr.Markdown("""
+### What is Turnabout Bench?
+
+Turnabout Bench is an interactive evaluation environment for testing agent long-horizon reasoning,
+inspired by the **Ace Attorney** game series.
+
+**Key Features:**
+- **Investigation Phase** (hard mode): Explore locations, collect evidence, talk to witnesses
+- **Court Phase**: Cross-examine witnesses, find contradictions in testimony
+- **Dual Interface**: Text-based for LLM agents, Gymnasium-compatible for RL agents
+- **Evaluation Metrics**: Contradiction accuracy, evidence coverage, step efficiency
+- **LLM Case Generation**: Automatically generate new cases via API
+
+**Usage:**
+```python
+# LLM Agent
+from turnabout.envs.text_env import TextCourtEnv
+env = TextCourtEnv(case_path="...", difficulty="easy")
+obs = env.reset()
+obs, reward, done, info = env.step("present evidence_name")
+
+# RL Agent (Gymnasium)
+import gymnasium as gym
+import turnabout.envs
+env = gym.make("Turnabout-Discrete-v0", case_path="...")
+```
+""")
+
+    return app
+
+
+if __name__ == "__main__":
+    app = build_app()
+    app.launch(share=False)

pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "turnabout"
+version = "0.1.0"
+description = "Ace Attorney-inspired environment for evaluating LLM/RL agent long-horizon reasoning"
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2.0",
+    "gymnasium>=0.29",
+    "numpy>=1.24",
+]
+
+[project.optional-dependencies]
+generation = ["openai>=1.0"]
+agents = ["anthropic>=0.40", "openai>=1.0"]
+ui = ["gradio>=4.0", "python-dotenv>=1.0"]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.21"]
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"

requirements.txt

@@ -0,0 +1,6 @@
+pydantic>=2.0
+gymnasium>=0.29
+numpy>=1.24
+gradio>=6.15
+python-dotenv>=1.0
+openai>=1.0

scripts/evaluate.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""Batch evaluation runner for agents."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from turnabout.agents.random_agent import RandomAgent, run_benchmark
+from turnabout.envs.text_env import TextCourtEnv
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Evaluate agents on Turnabout cases")
+    parser.add_argument(
+        "case",
+        nargs="?",
+        default=str(Path(__file__).parent.parent / "turnabout" / "cases" / "stolen_prototype.json"),
+        help="Path to case JSON file",
+    )
+    parser.add_argument("-d", "--difficulty", choices=["easy", "hard"], default="easy")
+    parser.add_argument("-n", "--episodes", type=int, default=100)
+    parser.add_argument("--agent", choices=["random", "llm"], default="random")
+    parser.add_argument("--seed", type=int, default=42)
+    parser.add_argument("-v", "--verbose", action="store_true")
+    parser.add_argument("-o", "--output", help="Save results to JSON file")
+    args = parser.parse_args()
+
+    print(f"Evaluating {args.agent} agent on {Path(args.case).stem}")
+    print(f"Difficulty: {args.difficulty}, Episodes: {args.episodes}")
+    print()
+
+    if args.agent == "random":
+        results = run_benchmark(
+            case_path=args.case,
+            difficulty=args.difficulty,
+            n_episodes=args.episodes,
+            seed=args.seed,
+            verbose=args.verbose,
+        )
+    elif args.agent == "llm":
+        try:
+            from turnabout.agents.llm_agent import LLMAgent
+        except ImportError as e:
+            print(f"Error: {e}")
+            sys.exit(1)
+
+        agent = LLMAgent()
+        results_list = []
+        for i in range(args.episodes):
+            env = TextCourtEnv(case_path=args.case, difficulty=args.difficulty)
+            result = agent.run_episode(env, verbose=args.verbose and i == 0)
+            results_list.append(result)
+            print(f"  Episode {i + 1}: {'WON' if result['won'] else 'LOST'} "
+                  f"(score={result['composite_score']:.3f})")
+
+        wins = sum(r["won"] for r in results_list)
+        results = {
+            "n_episodes": args.episodes,
+            "win_rate": wins / args.episodes,
+            "avg_reward": sum(r["total_reward"] for r in results_list) / args.episodes,
+            "avg_steps": sum(r["steps"] for r in results_list) / args.episodes,
+            "avg_composite_score": sum(r["composite_score"] for r in results_list) / args.episodes,
+        }
+
+    print("Results:")
+    for k, v in results.items():
+        if isinstance(v, float):
+            print(f"  {k}: {v:.4f}")
+        else:
+            print(f"  {k}: {v}")
+
+    if args.output:
+        with open(args.output, "w") as f:
+            json.dump(results, f, indent=2)
+        print(f"\nSaved to {args.output}")
+
+
+if __name__ == "__main__":
+    main()

scripts/generate_case.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""CLI for LLM-based case generation."""
+
+import argparse
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+
+async def main():
+    parser = argparse.ArgumentParser(description="Generate a new Turnabout case using LLM")
+    parser.add_argument("-t", "--theme", default=None, help="Theme for the case (e.g. 'art heist')")
+    parser.add_argument("-d", "--difficulty", choices=["easy", "hard"], default="easy")
+    parser.add_argument("-m", "--model", default="claude-sonnet-4-6")
+    parser.add_argument("-o", "--output", required=True, help="Output JSON file path")
+    parser.add_argument("--validate-only", help="Only validate an existing case file")
+    args = parser.parse_args()
+
+    if args.validate_only:
+        from turnabout.core.schema import CaseData
+        from turnabout.generation.validator import CaseValidator
+
+        with open(args.validate_only) as f:
+            data = json.load(f)
+        case = CaseData(**data)
+        validator = CaseValidator()
+        report = validator.validate(case)
+        print(f"Valid: {report.is_valid}")
+        for e in report.errors:
+            print(f"  ERROR: {e}")
+        for w in report.warnings:
+            print(f"  WARNING: {w}")
+        return
+
+    try:
+        from turnabout.generation.generator import CaseGenerator
+    except ImportError as e:
+        print(f"Error: {e}")
+        print("Install with: pip install 'turnabout[generation]'")
+        sys.exit(1)
+
+    generator = CaseGenerator(model=args.model)
+    print(f"Generating case (theme={args.theme}, difficulty={args.difficulty})...")
+
+    case = await generator.generate(theme=args.theme, difficulty=args.difficulty)
+
+    with open(args.output, "w") as f:
+        json.dump(case.model_dump(), f, indent=2, ensure_ascii=False)
+
+    print(f"Case saved to {args.output}")
+    print(f"Title: {case.title}")
+    print(f"Characters: {len(case.characters)}")
+    print(f"Evidence: {len(case.evidence)}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

scripts/play_text.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Interactive text CLI for human play-testing."""
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from turnabout.envs.text_env import TextCourtEnv
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Play a Turnabout case interactively")
+    parser.add_argument(
+        "case",
+        nargs="?",
+        default=str(Path(__file__).parent.parent / "turnabout" / "cases" / "stolen_prototype.json"),
+        help="Path to case JSON file",
+    )
+    parser.add_argument(
+        "-d", "--difficulty",
+        choices=["easy", "hard"],
+        default=None,
+        help="Override case difficulty",
+    )
+    args = parser.parse_args()
+
+    env = TextCourtEnv(case_path=args.case, difficulty=args.difficulty)
+
+    print("=" * 60)
+    print("  TURNABOUT - Interactive Court Game")
+    print("=" * 60)
+    print()
+    print(env.system_prompt)
+    print()
+    print("Type 'quit' to exit, 'help' for commands, 'status' for evidence.")
+    print("=" * 60)
+    print()
+
+    obs = env.reset()
+    print(obs)
+
+    while True:
+        print()
+        try:
+            action = input(">> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\nGoodbye!")
+            break
+
+        if not action:
+            continue
+        if action.lower() == "quit":
+            print("Goodbye!")
+            break
+        if action.lower() == "help":
+            print(env.system_prompt)
+            continue
+        if action.lower() == "status":
+            print(env.render())
+            continue
+
+        obs, reward, done, info = env.step(action)
+        print(obs)
+
+        if reward != 0:
+            print(f"  [Reward: {reward:+.2f}]")
+
+        if done:
+            print()
+            print("=" * 60)
+            metrics = env.get_metrics()
+            print(f"  Result: {'WON' if metrics.won else 'LOST'}")
+            print(f"  Steps: {metrics.total_steps}")
+            print(f"  Contradiction Accuracy: {metrics.contradiction_accuracy:.1%}")
+            print(f"  Evidence Coverage: {metrics.evidence_coverage:.1%}")
+            print(f"  Composite Score: {metrics.composite_score:.3f}")
+            print("=" * 60)
+            break
+
+
+if __name__ == "__main__":
+    main()

tests/test_engine.py

@@ -0,0 +1,222 @@
+"""Tests for the core game engine."""
+
+import json
+from pathlib import Path
+
+import pytest
+
+from turnabout.core.actions import Action, ActionType
+from turnabout.core.engine import TurnaboutEngine
+from turnabout.core.schema import CaseData
+from turnabout.core.scoring import MetricsComputer
+from turnabout.core.state import GamePhase
+
+CASES_DIR = Path(__file__).parent.parent / "turnabout" / "cases"
+
+
+@pytest.fixture
+def case():
+    path = CASES_DIR / "stolen_prototype.json"
+    if not path.exists():
+        pytest.skip("stolen_prototype.json not yet created")
+    with open(path) as f:
+        return CaseData(**json.load(f))
+
+
+class TestEasyMode:
+    def test_starts_in_court(self, case):
+        engine = TurnaboutEngine(case, difficulty="easy")
+        state, obs = engine.reset()
+        assert state.phase == GamePhase.COURT_TESTIMONY
+        assert "COURT" in obs
+
+    def test_all_evidence_available(self, case):
+        engine = TurnaboutEngine(case, difficulty="easy")
+        state, _ = engine.reset()
+        assert len(state.inventory) == len(case.evidence)
+
+    def test_advance_to_cross_exam(self, case):
+        engine = TurnaboutEngine(case, difficulty="easy")
+        state, _ = engine.reset()
+        assert state.phase == GamePhase.COURT_TESTIMONY
+
+        state, obs, _, _, _ = engine.step(Action(ActionType.NEXT_STATEMENT))
+        assert state.phase == GamePhase.COURT_CROSS_EXAM
+        assert "CROSS-EXAMINATION" in obs
+
+    def test_press_statement(self, case):
+        engine = TurnaboutEngine(case, difficulty="easy")
+        state, _ = engine.reset()
+        engine.step(Action(ActionType.NEXT_STATEMENT))
+
+        state, obs, _, _, _ = engine.step(Action(ActionType.PRESS, target_id="patrol_1"))
+        assert "HOLD IT" in obs
+        assert "patrol_1" in state.statements_pressed
+
+    def test_correct_contradiction_advances(self, case):
+        engine = TurnaboutEngine(case, difficulty="easy")
+        engine.reset()
+        engine.step(Action(ActionType.NEXT_STATEMENT))
+
+        state, obs, reward, done, info = engine.step(
+            Action(ActionType.PRESENT_EVIDENCE, target_id="patrol_schedule")
+        )
+        assert "OBJECTION" in obs
+        assert reward > 0
+        assert "patrol_1" in state.contradictions_found
+
+    def test_wrong_evidence_gives_penalty(self, case):
+        engine = TurnaboutEngine(case, difficulty="easy")
+        engine.reset()
+        engine.step(Action(ActionType.NEXT_STATEMENT))
+
+        state, obs, reward, done, _ = engine.step(
+            Action(ActionType.PRESENT_EVIDENCE, target_id="incident_report")
+        )
+        assert state.penalties == 1
+        assert reward < 0
+        assert "Penalty" in obs
+
+    def test_too_many_penalties_loses(self, case):
+        engine = TurnaboutEngine(case, difficulty="easy")
+        engine.reset()
+        engine.step(Action(ActionType.NEXT_STATEMENT))
+
+        for _ in range(5):
+            state, obs, _, done, _ = engine.step(
+                Action(ActionType.PRESENT_EVIDENCE, target_id="incident_report")
+            )
+            if done:
+                break
+
+        assert state.phase == GamePhase.VERDICT_LOSE
+        assert done
+        assert "GUILTY" in obs
+
+    def test_full_win_path(self, case):
+        engine = TurnaboutEngine(case, difficulty="easy")
+        engine.reset()
+
+        # Testimony -> cross-exam
+        engine.step(Action(ActionType.NEXT_STATEMENT))
+
+        # Find first contradiction: patrol_schedule vs patrol_1
+        engine.step(Action(ActionType.PRESENT_EVIDENCE, target_id="patrol_schedule"))
+
+        # New testimony starts, advance to cross-exam
+        engine.step(Action(ActionType.NEXT_STATEMENT))
+
+        # Press revised_2 to reveal revised_2b
+        engine.step(Action(ActionType.NEXT_STATEMENT))  # move to stmt index 1 (revised_2)
+        state, obs, _, _, _ = engine.step(Action(ActionType.PRESS, target_id="revised_2"))
+        assert "revised_2b" in state.revealed_statements or "amend" in obs.lower()
+
+        # Navigate to revised_2b and present cloning_device
+        engine.step(Action(ActionType.NEXT_STATEMENT))  # to revised_2b
+        state, obs, _, done, _ = engine.step(
+            Action(ActionType.PRESENT_EVIDENCE, target_id="cloning_device")
+        )
+        assert "OBJECTION" in obs
+        assert "revised_2b" in state.contradictions_found
+
+        # Navigate to revised_3 and present alex_alibi
+        engine.step(Action(ActionType.NEXT_STATEMENT))  # to revised_3
+        state, obs, reward, done, info = engine.step(
+            Action(ActionType.PRESENT_EVIDENCE, target_id="alex_alibi")
+        )
+        assert "OBJECTION" in obs
+        assert done
+        assert state.phase == GamePhase.VERDICT_WIN
+        assert "NOT GUILTY" in obs
+
+
+class TestHardMode:
+    def test_starts_in_investigation(self, case):
+        engine = TurnaboutEngine(case, difficulty="hard")
+        state, obs = engine.reset()
+        assert state.phase == GamePhase.INVESTIGATION
+        assert "INVESTIGATION" in obs
+
+    def test_pre_given_evidence_only(self, case):
+        engine = TurnaboutEngine(case, difficulty="hard")
+        state, _ = engine.reset()
+        pre_given = {e.id for e in case.get_pre_given_evidence()}
+        assert state.inventory == pre_given
+
+    def test_cannot_go_to_court_without_evidence(self, case):
+        engine = TurnaboutEngine(case, difficulty="hard")
+        engine.reset()
+        valid = engine.get_valid_actions()
+        court_action = Action(ActionType.GO_TO_COURT)
+        assert court_action not in valid
+
+    def test_move_between_locations(self, case):
+        engine = TurnaboutEngine(case, difficulty="hard")
+        state, _ = engine.reset()
+        start = state.current_location_id
+
+        # Move to a connected location
+        valid = engine.get_valid_actions()
+        move_actions = [a for a in valid if a.action_type == ActionType.MOVE]
+        assert len(move_actions) > 0
+
+        target = move_actions[0].target_id
+        state, obs, _, _, _ = engine.step(move_actions[0])
+        assert state.current_location_id == target
+
+    def test_examine_finds_evidence(self, case):
+        engine = TurnaboutEngine(case, difficulty="hard")
+        engine.reset()
+
+        # Navigate to security_office and examine filing_cabinet
+        engine.step(Action(ActionType.MOVE, target_id="lab"))
+        engine.step(Action(ActionType.MOVE, target_id="security_office"))
+        state, obs, reward, _, _ = engine.step(
+            Action(ActionType.EXAMINE, target_id="filing_cabinet")
+        )
+        assert "patrol_schedule" in state.inventory
+        assert reward > 0
+
+    def test_talk_grants_evidence(self, case):
+        engine = TurnaboutEngine(case, difficulty="hard")
+        state, _ = engine.reset()
+
+        if state.current_location_id != "detention_center":
+            engine.step(Action(ActionType.MOVE, target_id="detention_center"))
+
+        state, obs, _, _, _ = engine.step(Action(ActionType.TALK, target_id="alex_park"))
+        assert "alex_alibi" in state.inventory
+
+
+class TestMetrics:
+    def test_compute_on_win(self, case):
+        engine = TurnaboutEngine(case, difficulty="easy")
+        mc = MetricsComputer(engine)
+        state, _ = engine.reset()
+
+        engine.step(Action(ActionType.NEXT_STATEMENT))
+        _, _, r, _, _ = engine.step(Action(ActionType.PRESENT_EVIDENCE, target_id="patrol_schedule"))
+        mc.accumulate_reward(r)
+
+        engine.step(Action(ActionType.NEXT_STATEMENT))
+        engine.step(Action(ActionType.NEXT_STATEMENT))
+        _, _, r, _, _ = engine.step(Action(ActionType.PRESS, target_id="revised_2"))
+        mc.accumulate_reward(r)
+
+        engine.step(Action(ActionType.NEXT_STATEMENT))
+        _, _, r, _, _ = engine.step(
+            Action(ActionType.PRESENT_EVIDENCE, target_id="cloning_device")
+        )
+        mc.accumulate_reward(r)
+
+        engine.step(Action(ActionType.NEXT_STATEMENT))
+        _, _, r, done, _ = engine.step(
+            Action(ActionType.PRESENT_EVIDENCE, target_id="alex_alibi")
+        )
+        mc.accumulate_reward(r)
+
+        metrics = mc.compute(engine.state)
+        assert metrics.won
+        assert metrics.contradiction_accuracy == 1.0
+        assert metrics.wrong_presentations == 0
+        assert metrics.contradictions_found == 3

tests/test_gym_env.py

@@ -0,0 +1,106 @@
+"""Tests for the Gymnasium environment wrapper."""
+
+import json
+from pathlib import Path
+
+import gymnasium as gym
+import numpy as np
+import pytest
+
+import turnabout.envs  # noqa: F401 - triggers registration
+from turnabout.envs.gym_env import TurnaboutEnv
+
+CASES_DIR = Path(__file__).parent.parent / "turnabout" / "cases"
+
+
+@pytest.fixture
+def case_path():
+    p = CASES_DIR / "stolen_prototype.json"
+    if not p.exists():
+        pytest.skip("stolen_prototype.json not yet created")
+    return str(p)
+
+
+class TestDiscreteMode:
+    def test_create(self, case_path):
+        env = TurnaboutEnv(case_path=case_path, difficulty="easy", mode="discrete")
+        assert isinstance(env.action_space, gym.spaces.Discrete)
+        assert isinstance(env.observation_space, gym.spaces.Dict)
+
+    def test_reset(self, case_path):
+        env = TurnaboutEnv(case_path=case_path, difficulty="easy", mode="discrete")
+        obs, info = env.reset()
+        assert isinstance(obs, dict)
+        assert "phase" in obs
+        assert "evidence_held" in obs
+        assert isinstance(obs["evidence_held"], np.ndarray)
+
+    def test_action_masks(self, case_path):
+        env = TurnaboutEnv(case_path=case_path, difficulty="easy", mode="discrete")
+        env.reset()
+        mask = env.action_masks()
+        assert isinstance(mask, np.ndarray)
+        assert mask.shape == (env.action_space.n,)
+        assert mask.sum() > 0
+
+    def test_step_with_valid_masked_action(self, case_path):
+        env = TurnaboutEnv(case_path=case_path, difficulty="easy", mode="discrete")
+        env.reset()
+        mask = env.action_masks()
+        valid_idx = np.where(mask == 1)[0]
+        assert len(valid_idx) > 0
+
+        obs, reward, done, truncated, info = env.step(int(valid_idx[0]))
+        assert isinstance(obs, dict)
+        assert isinstance(reward, float)
+        assert isinstance(done, bool)
+        assert isinstance(truncated, bool)
+
+    def test_info_contains_action_mask(self, case_path):
+        env = TurnaboutEnv(case_path=case_path, difficulty="easy", mode="discrete")
+        _, info = env.reset()
+        assert "action_mask" in info
+
+
+class TestTextMode:
+    def test_create(self, case_path):
+        env = TurnaboutEnv(case_path=case_path, difficulty="easy", mode="text")
+        assert isinstance(env.action_space, gym.spaces.Text)
+        assert isinstance(env.observation_space, gym.spaces.Text)
+
+    def test_reset(self, case_path):
+        env = TurnaboutEnv(case_path=case_path, difficulty="easy", mode="text")
+        obs, info = env.reset()
+        assert isinstance(obs, str)
+        assert len(obs) > 0
+
+    def test_step(self, case_path):
+        env = TurnaboutEnv(case_path=case_path, difficulty="easy", mode="text")
+        env.reset()
+        obs, reward, done, truncated, info = env.step("next")
+        assert isinstance(obs, str)
+
+
+class TestGymMake:
+    def test_make_text(self, case_path):
+        env = gym.make("Turnabout-Text-v0", case_path=case_path, difficulty="easy")
+        obs, info = env.reset()
+        assert isinstance(obs, str)
+        env.close()
+
+    def test_make_discrete(self, case_path):
+        env = gym.make("Turnabout-Discrete-v0", case_path=case_path, difficulty="easy")
+        obs, info = env.reset()
+        assert isinstance(obs, dict)
+        env.close()
+
+
+class TestRender:
+    def test_render_ansi(self, case_path):
+        env = TurnaboutEnv(
+            case_path=case_path, difficulty="easy", mode="discrete", render_mode="ansi"
+        )
+        env.reset()
+        text = env.render()
+        assert isinstance(text, str)
+        assert len(text) > 0

tests/test_schema.py

@@ -0,0 +1,244 @@
+"""Tests for the case data schema."""
+
+import json
+from pathlib import Path
+
+import pytest
+from pydantic import ValidationError
+
+from turnabout.core.schema import (
+    CaseData,
+    Character,
+    Contradiction,
+    CourtProceedings,
+    CourtRound,
+    DialogueLine,
+    DialogueTree,
+    EvidenceAcquisition,
+    EvidenceItem,
+    EvidencePresentResponse,
+    Examinable,
+    InvestigationGate,
+    Location,
+    Statement,
+    Testimony,
+    WinCondition,
+)
+
+CASES_DIR = Path(__file__).parent.parent / "turnabout" / "cases"
+
+
+def _make_minimal_case(**overrides) -> dict:
+    base = {
+        "id": "test_001",
+        "title": "Test Case",
+        "difficulty": "easy",
+        "description": "A test case.",
+        "characters": [
+            {"id": "defendant", "name": "D", "description": "d", "role": "defendant"},
+            {"id": "witness1", "name": "W", "description": "w", "role": "witness"},
+        ],
+        "evidence": [
+            {
+                "id": "ev1",
+                "name": "E1",
+                "item_type": "document",
+                "description": "desc",
+                "detail": "detail",
+                "source": "pre_given",
+            }
+        ],
+        "court": {
+            "penalty_limit": 5,
+            "rounds": [
+                {
+                    "witness_id": "witness1",
+                    "order": 0,
+                    "initial_testimony_id": "t1",
+                    "testimonies": [
+                        {
+                            "id": "t1",
+                            "title": "Testimony",
+                            "witness_id": "witness1",
+                            "preamble": "The witness testifies.",
+                            "statements": [
+                                {
+                                    "id": "s1",
+                                    "text": "I saw something.",
+                                    "press_response": "Well...",
+                                    "contradiction": {
+                                        "evidence_id": "ev1",
+                                        "explanation": "This contradicts!",
+                                        "is_primary": True,
+                                    },
+                                }
+                            ],
+                        }
+                    ],
+                }
+            ],
+            "win_condition": {"required_contradiction_ids": ["s1"]},
+        },
+    }
+    base.update(overrides)
+    return base
+
+
+class TestMinimalCase:
+    def test_parse_minimal(self):
+        case = CaseData(**_make_minimal_case())
+        assert case.id == "test_001"
+        assert case.difficulty == "easy"
+        assert len(case.characters) == 2
+        assert len(case.evidence) == 1
+        assert case.court.penalty_limit == 5
+
+    def test_get_character(self):
+        case = CaseData(**_make_minimal_case())
+        assert case.get_character("defendant") is not None
+        assert case.get_character("nonexistent") is None
+
+    def test_get_evidence(self):
+        case = CaseData(**_make_minimal_case())
+        assert case.get_evidence("ev1") is not None
+        assert case.get_evidence("nonexistent") is None
+
+    def test_get_testimony(self):
+        case = CaseData(**_make_minimal_case())
+        assert case.get_testimony("t1") is not None
+        assert case.get_testimony("nonexistent") is None
+
+    def test_get_statement(self):
+        case = CaseData(**_make_minimal_case())
+        s = case.get_statement("s1")
+        assert s is not None
+        assert s.contradiction is not None
+        assert s.contradiction.evidence_id == "ev1"
+
+    def test_pre_given_evidence(self):
+        case = CaseData(**_make_minimal_case())
+        pre = case.get_pre_given_evidence()
+        assert len(pre) == 1
+        assert pre[0].id == "ev1"
+
+    def test_required_contradictions(self):
+        case = CaseData(**_make_minimal_case())
+        stmts = case.get_required_contradiction_statements()
+        assert len(stmts) == 1
+        assert stmts[0].id == "s1"
+
+
+class TestValidation:
+    def test_invalid_difficulty(self):
+        with pytest.raises(ValidationError):
+            CaseData(**_make_minimal_case(difficulty="medium"))
+
+    def test_investigation_evidence_requires_acquisition(self):
+        data = _make_minimal_case()
+        data["evidence"].append(
+            {
+                "id": "ev2",
+                "name": "E2",
+                "item_type": "physical",
+                "description": "d",
+                "detail": "d",
+                "source": "investigation",
+                "acquisition": None,
+            }
+        )
+        with pytest.raises(ValidationError, match="investigation evidence must have acquisition"):
+            CaseData(**data)
+
+    def test_investigation_evidence_with_acquisition_ok(self):
+        data = _make_minimal_case()
+        data["locations"] = [
+            {
+                "id": "loc1",
+                "name": "L1",
+                "description": "d",
+                "examinables": [{"id": "obj1", "name": "O1", "description": "d"}],
+            }
+        ]
+        data["evidence"].append(
+            {
+                "id": "ev2",
+                "name": "E2",
+                "item_type": "physical",
+                "description": "d",
+                "detail": "d",
+                "source": "investigation",
+                "acquisition": {
+                    "method": "examine",
+                    "location_id": "loc1",
+                    "target_id": "obj1",
+                },
+            }
+        )
+        case = CaseData(**data)
+        assert len(case.evidence) == 2
+
+
+class TestStolenPrototype:
+    @pytest.fixture
+    def case(self):
+        path = CASES_DIR / "stolen_prototype.json"
+        if not path.exists():
+            pytest.skip("stolen_prototype.json not yet created")
+        with open(path) as f:
+            data = json.load(f)
+        return CaseData(**data)
+
+    def test_loads(self, case):
+        assert case.id == "stolen_prototype"
+        assert case.title == "The Stolen Prototype"
+
+    def test_characters(self, case):
+        assert len(case.characters) == 5
+        roles = {c.role for c in case.characters}
+        assert "defendant" in roles
+        assert "witness" in roles
+
+    def test_evidence_count(self, case):
+        assert len(case.evidence) == 7
+        pre_given = case.get_pre_given_evidence()
+        assert len(pre_given) == 2
+        investigation = [e for e in case.evidence if e.source == "investigation"]
+        assert len(investigation) == 5
+
+    def test_locations(self, case):
+        assert len(case.locations) == 5
+        hale_office = case.get_location("hale_office")
+        assert hale_office is not None
+        assert not hale_office.available_from_start
+        assert "hale_suspicion" in hale_office.unlock_prerequisites
+
+    def test_court_structure(self, case):
+        assert case.court.penalty_limit == 5
+        assert len(case.court.rounds) == 1
+        rnd = case.court.rounds[0]
+        assert rnd.witness_id == "morrison"
+        assert len(rnd.testimonies) == 2
+
+    def test_win_condition(self, case):
+        wc = case.court.win_condition
+        assert len(wc.required_contradiction_ids) == 3
+        assert "patrol_1" in wc.required_contradiction_ids
+        assert "revised_2b" in wc.required_contradiction_ids
+        assert "revised_3" in wc.required_contradiction_ids
+
+    def test_investigation_gate(self, case):
+        gate = case.investigation_gate
+        assert gate is not None
+        assert len(gate.required_evidence) == 4
+        assert "cloning_device" in gate.required_evidence
+
+    def test_all_contradictions_reference_valid_evidence(self, case):
+        ev_ids = case.get_all_evidence_ids()
+        for rnd in case.court.rounds:
+            for t in rnd.testimonies:
+                for s in t.statements:
+                    if s.contradiction:
+                        assert s.contradiction.evidence_id in ev_ids, (
+                            f"Statement {s.id} contradiction references unknown evidence "
+                            f"{s.contradiction.evidence_id}"
+                        )

tests/test_text_env.py

@@ -0,0 +1,137 @@
+"""Tests for the text environment interface."""
+
+import json
+from pathlib import Path
+
+import pytest
+
+from turnabout.envs.text_env import TextCourtEnv
+
+CASES_DIR = Path(__file__).parent.parent / "turnabout" / "cases"
+
+
+@pytest.fixture
+def case_path():
+    p = CASES_DIR / "stolen_prototype.json"
+    if not p.exists():
+        pytest.skip("stolen_prototype.json not yet created")
+    return str(p)
+
+
+class TestTextEnvEasy:
+    def test_reset(self, case_path):
+        env = TextCourtEnv(case_path=case_path, difficulty="easy")
+        obs = env.reset()
+        assert "COURT" in obs or "TESTIMONY" in obs
+
+    def test_system_prompt(self, case_path):
+        env = TextCourtEnv(case_path=case_path, difficulty="easy")
+        prompt = env.system_prompt
+        assert "defense attorney" in prompt
+        assert "press" in prompt
+
+    def test_step_returns_4_tuple(self, case_path):
+        env = TextCourtEnv(case_path=case_path, difficulty="easy")
+        env.reset()
+        obs, reward, done, info = env.step("next")
+        assert isinstance(obs, str)
+        assert isinstance(reward, float)
+        assert isinstance(done, bool)
+        assert isinstance(info, dict)
+        assert "valid_actions" in info
+
+    def test_invalid_action(self, case_path):
+        env = TextCourtEnv(case_path=case_path, difficulty="easy")
+        env.reset()
+        obs, reward, done, info = env.step("fly to the moon")
+        assert "parse" in info.get("parse_error", "").lower() or "parse_error" in info
+        assert reward < 0
+
+    def test_full_easy_win(self, case_path):
+        env = TextCourtEnv(case_path=case_path, difficulty="easy")
+        env.reset()
+
+        actions = [
+            "next",
+            "present patrol_schedule",
+            "next",
+            "next",
+            "press revised_2",
+            "next",
+            "present cloning_device",
+            "next",
+            "present alex_alibi",
+        ]
+
+        done = False
+        for action in actions:
+            obs, reward, done, info = env.step(action)
+            if done:
+                break
+
+        assert done
+        assert "NOT GUILTY" in obs
+
+        metrics = env.get_metrics()
+        assert metrics.won
+        assert metrics.contradiction_accuracy == 1.0
+
+    def test_max_steps(self, case_path):
+        env = TextCourtEnv(case_path=case_path, difficulty="easy", max_steps=3)
+        env.reset()
+        for _ in range(5):
+            obs, reward, done, info = env.step("next")
+            if done:
+                break
+        assert done
+
+
+class TestTextEnvHard:
+    def test_reset_investigation(self, case_path):
+        env = TextCourtEnv(case_path=case_path, difficulty="hard")
+        obs = env.reset()
+        assert "INVESTIGATION" in obs
+
+    def test_investigate_then_court(self, case_path):
+        env = TextCourtEnv(case_path=case_path, difficulty="hard")
+        env.reset()
+
+        investigation_actions = [
+            "talk alex_park",
+            "move lab",
+            "move security_office",
+            "examine filing_cabinet",
+            "examine monitor_desk",
+            "move lab",
+            "present security_footage to chen",
+            "move main_hallway",
+            "move hale_office",
+            "examine hale_desk",
+            "go to court",
+        ]
+
+        for action in investigation_actions:
+            obs, reward, done, info = env.step(action)
+            assert not done, f"Game ended unexpectedly after '{action}': {obs}"
+
+        assert "COURT" in obs
+
+        court_actions = [
+            "next",
+            "present patrol_schedule",
+            "next",
+            "next",
+            "press revised_2",
+            "next",
+            "present cloning_device",
+            "next",
+            "present alex_alibi",
+        ]
+
+        for action in court_actions:
+            obs, reward, done, info = env.step(action)
+            if done:
+                break
+
+        assert done
+        assert "NOT GUILTY" in obs

tests/test_validator.py

@@ -0,0 +1,863 @@
+"""Tests for the case data validator."""
+
+import json
+from pathlib import Path
+
+import pytest
+
+from turnabout.core.schema import CaseData
+from turnabout.generation.validator import CaseValidator, ValidationReport
+
+CASES_DIR = Path(__file__).parent.parent / "turnabout" / "cases"
+
+
+# ------------------------------------------------------------------
+# Fixtures
+# ------------------------------------------------------------------
+
+
+@pytest.fixture
+def validator():
+    return CaseValidator()
+
+
+@pytest.fixture
+def stolen_prototype():
+    path = CASES_DIR / "stolen_prototype.json"
+    if not path.exists():
+        pytest.skip("stolen_prototype.json not found")
+    with open(path) as f:
+        data = json.load(f)
+    return CaseData(**data)
+
+
+def _make_minimal_case(**overrides) -> dict:
+    """Build a minimal valid case dict for mutation-based tests."""
+    base = {
+        "id": "test_case",
+        "title": "Test Case",
+        "difficulty": "easy",
+        "description": "A test case.",
+        "characters": [
+            {"id": "defendant", "name": "D", "description": "d", "role": "defendant"},
+            {"id": "witness1", "name": "W", "description": "w", "role": "witness"},
+        ],
+        "evidence": [
+            {
+                "id": "ev1",
+                "name": "E1",
+                "item_type": "document",
+                "description": "desc",
+                "detail": "detail",
+                "source": "pre_given",
+            },
+            {
+                "id": "ev2",
+                "name": "E2",
+                "item_type": "document",
+                "description": "desc",
+                "detail": "detail",
+                "source": "pre_given",
+            },
+        ],
+        "court": {
+            "penalty_limit": 5,
+            "rounds": [
+                {
+                    "witness_id": "witness1",
+                    "order": 0,
+                    "initial_testimony_id": "t1",
+                    "testimonies": [
+                        {
+                            "id": "t1",
+                            "title": "Testimony",
+                            "witness_id": "witness1",
+                            "preamble": "The witness testifies.",
+                            "statements": [
+                                {
+                                    "id": "s1",
+                                    "text": "I saw something.",
+                                    "press_response": "Well...",
+                                    "contradiction": {
+                                        "evidence_id": "ev1",
+                                        "explanation": "This contradicts!",
+                                        "is_primary": True,
+                                    },
+                                },
+                                {
+                                    "id": "s2",
+                                    "text": "I was there.",
+                                    "press_response": "Yes...",
+                                    "contradiction": None,
+                                },
+                            ],
+                        }
+                    ],
+                }
+            ],
+            "win_condition": {"required_contradiction_ids": ["s1"]},
+        },
+    }
+    base.update(overrides)
+    return base
+
+
+def _make_minimal_case_data(**overrides) -> CaseData:
+    return CaseData(**_make_minimal_case(**overrides))
+
+
+# ------------------------------------------------------------------
+# Tests: ValidationReport
+# ------------------------------------------------------------------
+
+
+class TestValidationReport:
+    def test_default_is_valid(self):
+        report = ValidationReport()
+        assert report.is_valid is True
+        assert report.errors == []
+        assert report.warnings == []
+
+    def test_add_error_makes_invalid(self):
+        report = ValidationReport()
+        report.add_error("something broke")
+        assert report.is_valid is False
+        assert len(report.errors) == 1
+
+    def test_add_warning_stays_valid(self):
+        report = ValidationReport()
+        report.add_warning("minor issue")
+        assert report.is_valid is True
+        assert len(report.warnings) == 1
+
+
+# ------------------------------------------------------------------
+# Tests: Valid cases
+# ------------------------------------------------------------------
+
+
+class TestValidCases:
+    def test_stolen_prototype_is_valid(self, validator, stolen_prototype):
+        report = validator.validate(stolen_prototype)
+        assert report.is_valid, f"Errors: {report.errors}"
+
+    def test_minimal_case_is_valid(self, validator):
+        case = _make_minimal_case_data()
+        report = validator.validate(case)
+        assert report.is_valid, f"Errors: {report.errors}"
+
+
+# ------------------------------------------------------------------
+# Tests: Reference validation
+# ------------------------------------------------------------------
+
+
+class TestReferenceValidation:
+    def test_bad_location_connection(self, validator):
+        data = _make_minimal_case()
+        data["locations"] = [
+            {
+                "id": "loc1",
+                "name": "L1",
+                "description": "d",
+                "connected_to": ["nonexistent_loc"],
+                "available_from_start": True,
+            }
+        ]
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("nonexistent_loc" in e for e in report.errors)
+
+    def test_bad_character_in_location(self, validator):
+        data = _make_minimal_case()
+        data["locations"] = [
+            {
+                "id": "loc1",
+                "name": "L1",
+                "description": "d",
+                "characters_present": ["ghost_character"],
+                "available_from_start": True,
+            }
+        ]
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("ghost_character" in e for e in report.errors)
+
+    def test_bad_evidence_acquisition_location(self, validator):
+        data = _make_minimal_case()
+        data["locations"] = [
+            {
+                "id": "loc1",
+                "name": "L1",
+                "description": "d",
+                "examinables": [
+                    {"id": "obj1", "name": "O1", "description": "d"}
+                ],
+                "available_from_start": True,
+            }
+        ]
+        data["evidence"].append(
+            {
+                "id": "ev3",
+                "name": "E3",
+                "item_type": "physical",
+                "description": "d",
+                "detail": "d",
+                "source": "investigation",
+                "acquisition": {
+                    "method": "examine",
+                    "location_id": "bad_loc",
+                    "target_id": "obj1",
+                },
+            }
+        )
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("bad_loc" in e for e in report.errors)
+
+    def test_bad_evidence_acquisition_target(self, validator):
+        data = _make_minimal_case()
+        data["locations"] = [
+            {
+                "id": "loc1",
+                "name": "L1",
+                "description": "d",
+                "examinables": [],
+                "available_from_start": True,
+            }
+        ]
+        data["evidence"].append(
+            {
+                "id": "ev3",
+                "name": "E3",
+                "item_type": "physical",
+                "description": "d",
+                "detail": "d",
+                "source": "investigation",
+                "acquisition": {
+                    "method": "examine",
+                    "location_id": "loc1",
+                    "target_id": "bad_target",
+                },
+            }
+        )
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("bad_target" in e for e in report.errors)
+
+    def test_bad_win_condition_statement(self, validator):
+        data = _make_minimal_case()
+        data["court"]["win_condition"]["required_contradiction_ids"] = [
+            "nonexistent_statement"
+        ]
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("nonexistent_statement" in e for e in report.errors)
+
+    def test_bad_dialogue_character(self, validator):
+        data = _make_minimal_case()
+        data["dialogues"] = [
+            {
+                "character_id": "nobody",
+                "lines": [],
+                "present_responses": [],
+            }
+        ]
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("nobody" in e for e in report.errors)
+
+    def test_bad_court_round_witness(self, validator):
+        data = _make_minimal_case()
+        data["court"]["rounds"][0]["witness_id"] = "missing_witness"
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("missing_witness" in e for e in report.errors)
+
+    def test_bad_triggers_testimony(self, validator):
+        data = _make_minimal_case()
+        stmt = data["court"]["rounds"][0]["testimonies"][0]["statements"][0]
+        stmt["contradiction"]["triggers_testimony"] = "phantom_testimony"
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("phantom_testimony" in e for e in report.errors)
+
+    def test_bad_press_reveals_statement(self, validator):
+        data = _make_minimal_case()
+        stmt = data["court"]["rounds"][0]["testimonies"][0]["statements"][0]
+        stmt["press_reveals_statement"] = "ghost_statement"
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("ghost_statement" in e for e in report.errors)
+
+    def test_bad_final_evidence_id(self, validator):
+        data = _make_minimal_case()
+        data["court"]["win_condition"]["final_evidence_id"] = "missing_ev"
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("missing_ev" in e for e in report.errors)
+
+    def test_bad_investigation_gate_evidence(self, validator):
+        data = _make_minimal_case()
+        data["investigation_gate"] = {
+            "required_evidence": ["nonexistent_ev"],
+            "auto_advance": False,
+        }
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("nonexistent_ev" in e for e in report.errors)
+
+    def test_bad_location_unlock_prerequisite(self, validator):
+        data = _make_minimal_case()
+        data["locations"] = [
+            {
+                "id": "loc1",
+                "name": "L1",
+                "description": "d",
+                "available_from_start": True,
+                "connected_to": ["loc2"],
+            },
+            {
+                "id": "loc2",
+                "name": "L2",
+                "description": "d",
+                "available_from_start": False,
+                "unlock_prerequisites": ["fake_ev"],
+                "connected_to": ["loc1"],
+            },
+        ]
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("fake_ev" in e for e in report.errors)
+
+    def test_bad_dialogue_line_grants_evidence(self, validator):
+        data = _make_minimal_case()
+        data["dialogues"] = [
+            {
+                "character_id": "witness1",
+                "lines": [
+                    {
+                        "id": "line1",
+                        "text": "hi",
+                        "grants_evidence": "missing_ev",
+                    }
+                ],
+                "present_responses": [],
+            }
+        ]
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("missing_ev" in e for e in report.errors)
+
+    def test_bad_present_response_evidence(self, validator):
+        data = _make_minimal_case()
+        data["dialogues"] = [
+            {
+                "character_id": "witness1",
+                "lines": [],
+                "present_responses": [
+                    {
+                        "evidence_id": "ghost_ev",
+                        "text": "hmm",
+                    }
+                ],
+            }
+        ]
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("ghost_ev" in e for e in report.errors)
+
+
+# ------------------------------------------------------------------
+# Tests: Contradiction validation
+# ------------------------------------------------------------------
+
+
+class TestContradictionValidation:
+    def test_bad_contradiction_evidence(self, validator):
+        data = _make_minimal_case()
+        stmt = data["court"]["rounds"][0]["testimonies"][0]["statements"][0]
+        stmt["contradiction"]["evidence_id"] = "nonexistent_ev"
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("nonexistent_ev" in e for e in report.errors)
+
+    def test_valid_contradiction_evidence(self, validator):
+        case = _make_minimal_case_data()
+        errors = validator._validate_contradictions(case)
+        assert errors == []
+
+
+# ------------------------------------------------------------------
+# Tests: Solvability validation
+# ------------------------------------------------------------------
+
+
+class TestSolvabilityValidation:
+    def test_win_condition_statement_without_contradiction(self, validator):
+        data = _make_minimal_case()
+        # s2 has no contradiction but we require it in win condition
+        data["court"]["win_condition"]["required_contradiction_ids"] = ["s2"]
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("no contradiction defined" in e for e in report.errors)
+
+    def test_unreachable_testimony_for_win(self, validator):
+        data = _make_minimal_case()
+        # Add a second testimony that is never triggered
+        data["court"]["rounds"][0]["testimonies"].append(
+            {
+                "id": "t2",
+                "title": "Secret Testimony",
+                "witness_id": "witness1",
+                "preamble": "Hidden.",
+                "statements": [
+                    {
+                        "id": "s3",
+                        "text": "Secret statement.",
+                        "press_response": "...",
+                        "contradiction": {
+                            "evidence_id": "ev2",
+                            "explanation": "Objection!",
+                            "is_primary": True,
+                        },
+                    }
+                ],
+            }
+        )
+        # Require s3 which is in unreachable t2
+        data["court"]["win_condition"]["required_contradiction_ids"] = ["s1", "s3"]
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("unreachable" in e.lower() for e in report.errors)
+
+    def test_reachable_testimony_via_trigger(self, validator):
+        """Testimony reachable through triggers_testimony chain should pass."""
+        data = _make_minimal_case()
+        # s1 contradiction triggers t2
+        stmt = data["court"]["rounds"][0]["testimonies"][0]["statements"][0]
+        stmt["contradiction"]["triggers_testimony"] = "t2"
+        data["court"]["rounds"][0]["testimonies"].append(
+            {
+                "id": "t2",
+                "title": "Second Testimony",
+                "witness_id": "witness1",
+                "preamble": "More.",
+                "statements": [
+                    {
+                        "id": "s3",
+                        "text": "Second statement.",
+                        "press_response": "...",
+                        "contradiction": {
+                            "evidence_id": "ev2",
+                            "explanation": "Objection!",
+                            "is_primary": True,
+                        },
+                    }
+                ],
+            }
+        )
+        data["court"]["win_condition"]["required_contradiction_ids"] = ["s1", "s3"]
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert report.is_valid, f"Errors: {report.errors}"
+
+
+# ------------------------------------------------------------------
+# Tests: Reachability validation
+# ------------------------------------------------------------------
+
+
+class TestReachabilityValidation:
+    def test_unreachable_investigation_evidence(self, validator):
+        data = _make_minimal_case()
+        data["locations"] = [
+            {
+                "id": "loc1",
+                "name": "L1",
+                "description": "d",
+                "examinables": [
+                    {"id": "obj1", "name": "O1", "description": "d"}
+                ],
+                "available_from_start": True,
+                "connected_to": ["loc2"],
+            },
+            {
+                "id": "loc2",
+                "name": "L2",
+                "description": "d",
+                "examinables": [
+                    {"id": "obj2", "name": "O2", "description": "d"}
+                ],
+                "available_from_start": False,
+                # Requires ev3 to unlock, but ev3 is IN loc2 -- catch-22
+                "unlock_prerequisites": ["ev3"],
+                "connected_to": ["loc1"],
+            },
+        ]
+        data["evidence"].append(
+            {
+                "id": "ev3",
+                "name": "E3",
+                "item_type": "physical",
+                "description": "d",
+                "detail": "d",
+                "source": "investigation",
+                "acquisition": {
+                    "method": "examine",
+                    "location_id": "loc2",
+                    "target_id": "obj2",
+                },
+            }
+        )
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("unreachable" in e.lower() for e in report.errors)
+
+    def test_reachable_evidence_chain(self, validator):
+        """Evidence obtainable through a prerequisite chain should pass."""
+        data = _make_minimal_case()
+        data["locations"] = [
+            {
+                "id": "loc1",
+                "name": "L1",
+                "description": "d",
+                "examinables": [
+                    {"id": "obj1", "name": "O1", "description": "d"},
+                    {"id": "obj2", "name": "O2", "description": "d"},
+                ],
+                "available_from_start": True,
+            }
+        ]
+        data["evidence"].extend(
+            [
+                {
+                    "id": "ev3",
+                    "name": "E3",
+                    "item_type": "physical",
+                    "description": "d",
+                    "detail": "d",
+                    "source": "investigation",
+                    "acquisition": {
+                        "method": "examine",
+                        "location_id": "loc1",
+                        "target_id": "obj1",
+                        "prerequisites": [],
+                    },
+                },
+                {
+                    "id": "ev4",
+                    "name": "E4",
+                    "item_type": "physical",
+                    "description": "d",
+                    "detail": "d",
+                    "source": "investigation",
+                    "acquisition": {
+                        "method": "examine",
+                        "location_id": "loc1",
+                        "target_id": "obj2",
+                        "prerequisites": ["ev3"],
+                    },
+                },
+            ]
+        )
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert report.is_valid, f"Errors: {report.errors}"
+
+    def test_stolen_prototype_reachable(self, validator, stolen_prototype):
+        """All evidence in stolen_prototype should be reachable."""
+        errors = validator._validate_reachability(stolen_prototype)
+        assert errors == [], f"Reachability errors: {errors}"
+
+    def test_unreachable_gate_evidence(self, validator):
+        """Investigation gate requiring unobtainable evidence should fail."""
+        data = _make_minimal_case()
+        data["locations"] = [
+            {
+                "id": "loc1",
+                "name": "L1",
+                "description": "d",
+                "examinables": [],
+                "available_from_start": True,
+            }
+        ]
+        # ev3 is investigation evidence but has no way to be obtained
+        # (its location does not contain the right examinable)
+        data["evidence"].append(
+            {
+                "id": "ev3",
+                "name": "E3",
+                "item_type": "physical",
+                "description": "d",
+                "detail": "d",
+                "source": "investigation",
+                "acquisition": {
+                    "method": "examine",
+                    "location_id": "loc1",
+                    "target_id": "missing_obj",
+                },
+            }
+        )
+        data["investigation_gate"] = {
+            "required_evidence": ["ev3"],
+            "auto_advance": False,
+        }
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("unreachable" in e.lower() for e in report.errors)
+
+    def test_evidence_from_dialogue(self, validator):
+        """Evidence obtainable via dialogue should be reachable."""
+        data = _make_minimal_case()
+        data["locations"] = [
+            {
+                "id": "loc1",
+                "name": "L1",
+                "description": "d",
+                "characters_present": ["witness1"],
+                "available_from_start": True,
+            }
+        ]
+        data["evidence"].append(
+            {
+                "id": "ev3",
+                "name": "E3",
+                "item_type": "testimony_record",
+                "description": "d",
+                "detail": "d",
+                "source": "investigation",
+                "acquisition": {
+                    "method": "talk",
+                    "location_id": "loc1",
+                    "target_id": "witness1",
+                },
+            }
+        )
+        data["dialogues"] = [
+            {
+                "character_id": "witness1",
+                "lines": [
+                    {
+                        "id": "line1",
+                        "text": "Here is some info.",
+                        "grants_evidence": "ev3",
+                    }
+                ],
+                "present_responses": [],
+            }
+        ]
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert report.is_valid, f"Errors: {report.errors}"
+
+
+# ------------------------------------------------------------------
+# Tests: Deadlock detection
+# ------------------------------------------------------------------
+
+
+class TestDeadlockValidation:
+    def test_circular_evidence_prerequisites(self, validator):
+        data = _make_minimal_case()
+        data["locations"] = [
+            {
+                "id": "loc1",
+                "name": "L1",
+                "description": "d",
+                "examinables": [
+                    {"id": "obj1", "name": "O1", "description": "d"},
+                    {"id": "obj2", "name": "O2", "description": "d"},
+                ],
+                "available_from_start": True,
+            }
+        ]
+        # ev3 requires ev4, ev4 requires ev3 -- circular
+        data["evidence"].extend(
+            [
+                {
+                    "id": "ev3",
+                    "name": "E3",
+                    "item_type": "physical",
+                    "description": "d",
+                    "detail": "d",
+                    "source": "investigation",
+                    "acquisition": {
+                        "method": "examine",
+                        "location_id": "loc1",
+                        "target_id": "obj1",
+                        "prerequisites": ["ev4"],
+                    },
+                },
+                {
+                    "id": "ev4",
+                    "name": "E4",
+                    "item_type": "physical",
+                    "description": "d",
+                    "detail": "d",
+                    "source": "investigation",
+                    "acquisition": {
+                        "method": "examine",
+                        "location_id": "loc1",
+                        "target_id": "obj2",
+                        "prerequisites": ["ev3"],
+                    },
+                },
+            ]
+        )
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("circular" in e.lower() for e in report.errors)
+
+    def test_disconnected_location(self, validator):
+        data = _make_minimal_case()
+        data["locations"] = [
+            {
+                "id": "loc1",
+                "name": "L1",
+                "description": "d",
+                "connected_to": [],
+                "available_from_start": True,
+            },
+            {
+                "id": "loc2",
+                "name": "L2",
+                "description": "d",
+                "connected_to": [],
+                "available_from_start": False,
+                "unlock_prerequisites": [],
+            },
+        ]
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert any("not reachable" in e.lower() for e in report.errors)
+
+    def test_no_deadlocks_in_stolen_prototype(self, validator, stolen_prototype):
+        errors = validator._validate_no_deadlocks(stolen_prototype)
+        assert errors == [], f"Deadlock errors: {errors}"
+
+
+# ------------------------------------------------------------------
+# Tests: Structural warnings
+# ------------------------------------------------------------------
+
+
+class TestStructuralWarnings:
+    def test_no_defendant_warning(self, validator):
+        data = _make_minimal_case()
+        data["characters"] = [
+            {"id": "npc1", "name": "N", "description": "n", "role": "npc"},
+            {"id": "witness1", "name": "W", "description": "w", "role": "witness"},
+        ]
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert any("defendant" in w.lower() for w in report.warnings)
+
+    def test_hard_mode_no_locations_warning(self, validator):
+        data = _make_minimal_case(difficulty="hard")
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert any("locations" in w.lower() for w in report.warnings)
+
+    def test_hard_mode_no_dialogues_warning(self, validator):
+        data = _make_minimal_case(difficulty="hard")
+        data["locations"] = [
+            {
+                "id": "loc1",
+                "name": "L1",
+                "description": "d",
+                "available_from_start": True,
+            }
+        ]
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert any("dialogues" in w.lower() for w in report.warnings)
+
+    def test_hard_mode_no_gate_warning(self, validator):
+        data = _make_minimal_case(difficulty="hard")
+        data["locations"] = [
+            {
+                "id": "loc1",
+                "name": "L1",
+                "description": "d",
+                "available_from_start": True,
+            }
+        ]
+        data["dialogues"] = []
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert any("investigation gate" in w.lower() for w in report.warnings)
+
+    def test_isolated_location_warning(self, validator):
+        data = _make_minimal_case()
+        data["locations"] = [
+            {
+                "id": "loc1",
+                "name": "L1",
+                "description": "d",
+                "connected_to": [],
+                "available_from_start": True,
+            },
+            {
+                "id": "loc2",
+                "name": "L2",
+                "description": "d",
+                "connected_to": [],
+                "available_from_start": True,
+            },
+        ]
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert any("no connections" in w.lower() for w in report.warnings)
+
+
+# ------------------------------------------------------------------
+# Tests: Full validate() integration
+# ------------------------------------------------------------------
+
+
+class TestFullValidation:
+    def test_stolen_prototype_full_validation(self, validator, stolen_prototype):
+        report = validator.validate(stolen_prototype)
+        assert report.is_valid, f"Errors: {report.errors}"
+        # Stolen prototype is a well-formed hard case; expect no warnings
+        # (or at most minor ones)
+
+    def test_multiple_errors_reported(self, validator):
+        """Multiple issues should all be reported."""
+        data = _make_minimal_case()
+        data["court"]["win_condition"]["required_contradiction_ids"] = [
+            "bad_stmt_1",
+            "bad_stmt_2",
+        ]
+        case = CaseData(**data)
+        report = validator.validate(case)
+        assert not report.is_valid
+        assert len(report.errors) >= 2
+
+    def test_clean_minimal_case(self, validator):
+        case = _make_minimal_case_data()
+        report = validator.validate(case)
+        assert report.is_valid
+        assert report.errors == []

turnabout/__init__.py

@@ -0,0 +1,3 @@
+"""Turnabout: Ace Attorney-inspired environment for agent long-horizon reasoning."""
+
+__version__ = "0.1.0"

turnabout/agents/llm_agent.py

@@ -0,0 +1,96 @@
+"""LLM agent baseline using text environment."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from turnabout.envs.text_env import TextCourtEnv
+
+
+class LLMAgent:
+    """Agent that uses an LLM (via Anthropic SDK) to play the game."""
+
+    def __init__(
+        self,
+        client: Any = None,
+        model: str = "claude-sonnet-4-6",
+        max_tokens: int = 512,
+        temperature: float = 0.0,
+    ):
+        if client is None:
+            try:
+                from anthropic import Anthropic
+                client = Anthropic()
+            except ImportError:
+                raise ImportError(
+                    "anthropic package required. Install with: pip install anthropic"
+                )
+        self.client = client
+        self.model = model
+        self.max_tokens = max_tokens
+        self.temperature = temperature
+
+    def run_episode(
+        self, env: TextCourtEnv, verbose: bool = False
+    ) -> dict:
+        obs = env.reset()
+        system = env.system_prompt
+        messages: list[dict] = []
+
+        if verbose:
+            print(obs)
+
+        messages.append({"role": "user", "content": obs})
+
+        total_reward = 0.0
+        done = False
+
+        while not done:
+            response = self.client.messages.create(
+                model=self.model,
+                max_tokens=self.max_tokens,
+                temperature=self.temperature,
+                system=system,
+                messages=messages,
+            )
+
+            action_text = response.content[0].text.strip()
+            action_text = self._extract_action(action_text)
+
+            messages.append({"role": "assistant", "content": action_text})
+
+            obs, reward, done, info = env.step(action_text)
+            total_reward += reward
+
+            if verbose:
+                print(f"\n> {action_text}")
+                print(obs[:300])
+
+            messages.append({"role": "user", "content": obs})
+
+            if len(messages) > 40:
+                messages = messages[:2] + messages[-20:]
+
+        metrics = env.get_metrics()
+        return {
+            "won": metrics.won,
+            "total_reward": total_reward,
+            "steps": metrics.total_steps,
+            "contradiction_accuracy": metrics.contradiction_accuracy,
+            "evidence_coverage": metrics.evidence_coverage,
+            "composite_score": metrics.composite_score,
+        }
+
+    def _extract_action(self, text: str) -> str:
+        """Extract the actual command from LLM output (may include reasoning)."""
+        lines = text.strip().split("\n")
+        for line in reversed(lines):
+            line = line.strip()
+            if line.startswith(">"):
+                return line[1:].strip()
+            if line.startswith("Action:"):
+                return line[7:].strip()
+            if line.startswith("Command:"):
+                return line[8:].strip()
+        return lines[-1].strip()

turnabout/agents/random_agent.py

@@ -0,0 +1,81 @@
+"""Random baseline agent using action masking."""
+
+from __future__ import annotations
+
+import json
+import random
+from pathlib import Path
+
+from turnabout.core.actions import Action
+from turnabout.envs.text_env import TextCourtEnv
+
+
+class RandomAgent:
+    def __init__(self, seed: int | None = None):
+        self.rng = random.Random(seed)
+
+    def run_episode(
+        self, env: TextCourtEnv, verbose: bool = False
+    ) -> dict:
+        obs = env.reset()
+        if verbose:
+            print(obs)
+
+        total_reward = 0.0
+        done = False
+
+        while not done:
+            valid_actions = env.engine.get_valid_actions()
+            if not valid_actions:
+                break
+
+            action = self.rng.choice(valid_actions)
+            state, engine_obs, reward, engine_done, _ = env.engine.step(action)
+            env._step_count += 1
+            env.metrics_computer.accumulate_reward(reward)
+            total_reward += reward
+            done = engine_done or env._step_count >= env.max_steps
+
+            if verbose:
+                print(f"\n> {action}")
+                print(engine_obs[:300])
+
+        metrics = env.get_metrics()
+        return {
+            "won": metrics.won,
+            "total_reward": total_reward,
+            "steps": metrics.total_steps,
+            "contradiction_accuracy": metrics.contradiction_accuracy,
+            "evidence_coverage": metrics.evidence_coverage,
+            "composite_score": metrics.composite_score,
+        }
+
+
+def run_benchmark(
+    case_path: str,
+    difficulty: str = "easy",
+    n_episodes: int = 100,
+    seed: int = 42,
+    verbose: bool = False,
+) -> dict:
+    agent = RandomAgent(seed=seed)
+    results = []
+
+    for i in range(n_episodes):
+        agent.rng = random.Random(seed + i)
+        env = TextCourtEnv(case_path=case_path, difficulty=difficulty)
+        result = agent.run_episode(env, verbose=verbose and i == 0)
+        results.append(result)
+
+    wins = sum(r["won"] for r in results)
+    avg_reward = sum(r["total_reward"] for r in results) / n_episodes
+    avg_steps = sum(r["steps"] for r in results) / n_episodes
+    avg_score = sum(r["composite_score"] for r in results) / n_episodes
+
+    return {
+        "n_episodes": n_episodes,
+        "win_rate": wins / n_episodes,
+        "avg_reward": avg_reward,
+        "avg_steps": avg_steps,
+        "avg_composite_score": avg_score,
+    }

turnabout/cases/stolen_prototype.json

@@ -0,0 +1,395 @@
+{
+  "id": "stolen_prototype",
+  "title": "The Stolen Prototype",
+  "difficulty": "hard",
+  "description": "A revolutionary quantum chip has been stolen from QuantumTech Labs, and junior researcher Alex Park stands accused. With keycard logs pointing squarely at the defendant, only a thorough investigation can uncover the truth behind this high-tech heist.",
+  "metadata": {
+    "author": "human",
+    "version": "1.0",
+    "tags": ["corporate", "technology", "theft", "framing"]
+  },
+  "characters": [
+    {
+      "id": "alex_park",
+      "name": "Alex Park",
+      "description": "A junior researcher at QuantumTech Labs. Quiet and dedicated, Alex has always kept his head down and focused on his work.",
+      "role": "defendant"
+    },
+    {
+      "id": "morrison",
+      "name": "Morrison",
+      "description": "Night security guard at QuantumTech Labs with 10 years of service. Proud of his long tenure but perhaps a bit too comfortable in his routine.",
+      "role": "witness"
+    },
+    {
+      "id": "chen",
+      "name": "Dr. Sarah Chen",
+      "description": "Lead researcher at QuantumTech Labs and Alex Park's direct supervisor. A brilliant scientist who believes in her team.",
+      "role": "npc"
+    },
+    {
+      "id": "hale",
+      "name": "Dr. Victor Hale",
+      "description": "Senior researcher at QuantumTech Labs. Ambitious and competitive, Hale has long coveted the lead researcher position.",
+      "role": "npc"
+    },
+    {
+      "id": "judge",
+      "name": "The Judge",
+      "description": "The presiding judge of this trial. Stern but fair, with little patience for theatrics — unless they reveal the truth.",
+      "role": "judge"
+    }
+  ],
+  "evidence": [
+    {
+      "id": "incident_report",
+      "name": "Incident Report",
+      "item_type": "document",
+      "description": "Official QuantumTech Labs security incident report filed on March 15.",
+      "detail": "Break-in detected at 11:30 PM on March 15. The quantum chip prototype was confirmed missing from Secure Case #3 in the east wing laboratory. No signs of forced entry were found — keycard access was used to enter the lab.",
+      "source": "pre_given",
+      "acquisition": null
+    },
+    {
+      "id": "keycard_log",
+      "name": "Keycard Access Log",
+      "item_type": "document",
+      "description": "Electronic log of all keycard entries to the east wing laboratory.",
+      "detail": "Keycard #0247, registered to Alex Park, was used at Lab Door East at 11:15:03 PM on March 15. This is the only keycard entry recorded between 9:00 PM and midnight.",
+      "source": "pre_given",
+      "acquisition": null
+    },
+    {
+      "id": "security_footage",
+      "name": "Security Camera Footage",
+      "item_type": "document",
+      "description": "Recovered footage from the east wing security camera.",
+      "detail": "The footage shows a hooded figure entering the lab at 11:15 PM and exiting at 11:25 PM carrying a small protective case. The figure's face is completely obscured by the hood, making positive identification impossible from the video alone.",
+      "source": "investigation",
+      "acquisition": {
+        "method": "examine",
+        "location_id": "security_office",
+        "target_id": "monitor_desk",
+        "prerequisites": [],
+        "present_evidence_id": null
+      }
+    },
+    {
+      "id": "alex_alibi",
+      "name": "Alex's Bus Pass Record",
+      "item_type": "document",
+      "description": "Digital bus pass transaction record for Alex Park.",
+      "detail": "Alex Park's digital bus pass was scanned at Downtown Station at 10:50 PM on March 15. The next bus from Downtown Station to the QuantumTech area does not arrive until 11:55 PM — forty minutes AFTER the lab entry was recorded.",
+      "source": "investigation",
+      "acquisition": {
+        "method": "talk",
+        "location_id": "detention_center",
+        "target_id": "alex_park",
+        "prerequisites": [],
+        "present_evidence_id": null
+      }
+    },
+    {
+      "id": "cloning_device",
+      "name": "RFID Cloning Device",
+      "item_type": "physical",
+      "description": "A handheld RFID cloning device found hidden in Dr. Hale's desk.",
+      "detail": "A sophisticated RFID keycard cloner. Internal logs show it was last used on March 14 — the day before the theft. The cloned data stored in its memory is a perfect match for keycard #0247, registered to Alex Park.",
+      "source": "investigation",
+      "acquisition": {
+        "method": "examine",
+        "location_id": "hale_office",
+        "target_id": "hale_desk",
+        "prerequisites": ["hale_suspicion"],
+        "present_evidence_id": null
+      }
+    },
+    {
+      "id": "hale_suspicion",
+      "name": "Dr. Chen's Testimony About Hale",
+      "item_type": "testimony_record",
+      "description": "Dr. Chen's account of Dr. Hale's suspicious behavior in the days before the theft.",
+      "detail": "Dr. Chen recalls that Dr. Victor Hale had been asking unusually detailed questions about the lab's security protocols, keycard systems, and camera placement in the week leading up to the theft. She found it odd at the time but didn't think much of it until seeing the security footage.",
+      "source": "investigation",
+      "acquisition": {
+        "method": "present",
+        "location_id": "lab",
+        "target_id": "chen",
+        "prerequisites": ["security_footage"],
+        "present_evidence_id": "security_footage"
+      }
+    },
+    {
+      "id": "patrol_schedule",
+      "name": "Security Patrol Protocol",
+      "item_type": "document",
+      "description": "Official QuantumTech Labs security patrol schedule and protocol document.",
+      "detail": "The official protocol mandates east wing patrols every 30 MINUTES, not every hour. The document is signed by the head of security and dated January of this year. Morrison's claim of hourly patrols directly contradicts his own employer's standing orders.",
+      "source": "investigation",
+      "acquisition": {
+        "method": "examine",
+        "location_id": "security_office",
+        "target_id": "filing_cabinet",
+        "prerequisites": [],
+        "present_evidence_id": null
+      }
+    }
+  ],
+  "locations": [
+    {
+      "id": "detention_center",
+      "name": "Detention Center",
+      "description": "A stark, sterile visiting room at the city detention center. Alex Park sits behind reinforced glass, looking exhausted and frightened.",
+      "connected_to": ["lab"],
+      "examinables": [],
+      "characters_present": ["alex_park"],
+      "available_from_start": true,
+      "unlock_prerequisites": []
+    },
+    {
+      "id": "lab",
+      "name": "QuantumTech East Wing Laboratory",
+      "description": "A state-of-the-art research lab filled with delicate instruments and humming servers. Yellow crime scene tape still marks the area around Secure Case #3, now empty.",
+      "connected_to": ["detention_center", "security_office", "main_hallway"],
+      "examinables": [
+        {
+          "id": "secure_case",
+          "name": "Secure Case #3",
+          "description": "A reinforced display case designed to hold the quantum chip prototype. The glass is intact — it was opened with an authorized code.",
+          "examined_description": "The case shows no signs of tampering. Whoever took the prototype knew the access code or had a way to bypass it cleanly."
+        },
+        {
+          "id": "workbench",
+          "name": "Research Workbench",
+          "description": "Alex Park's assigned workstation, cluttered with notes and schematics.",
+          "examined_description": "The notes are all related to quantum error correction — Alex's assigned research topic. Nothing here suggests any interest in stealing the prototype."
+        }
+      ],
+      "characters_present": ["chen"],
+      "available_from_start": true,
+      "unlock_prerequisites": []
+    },
+    {
+      "id": "security_office",
+      "name": "Security Office",
+      "description": "The QuantumTech security hub. Banks of monitors line one wall, and a filing cabinet stands in the corner. A half-empty coffee mug sits on the desk.",
+      "connected_to": ["lab", "main_hallway"],
+      "examinables": [
+        {
+          "id": "monitor_desk",
+          "name": "Security Monitor Desk",
+          "description": "Multiple screens showing camera feeds from around the facility. A recording system hums beneath the desk.",
+          "examined_description": "You scrub through the footage from March 15. At 11:15 PM, a hooded figure enters the east wing lab. At 11:25 PM, the same figure exits carrying a small case. The face is never visible."
+        },
+        {
+          "id": "filing_cabinet",
+          "name": "Filing Cabinet",
+          "description": "A metal filing cabinet labeled 'PROTOCOLS & SCHEDULES'. Looks like it hasn't been opened in a while.",
+          "examined_description": "Inside, you find the official patrol protocol. It clearly states: east wing patrols are to be conducted every 30 minutes. Someone hasn't been following the rules."
+        }
+      ],
+      "characters_present": [],
+      "available_from_start": true,
+      "unlock_prerequisites": []
+    },
+    {
+      "id": "main_hallway",
+      "name": "Main Hallway",
+      "description": "The central corridor of QuantumTech Labs. Fluorescent lights buzz overhead, and employee photos line the walls. Dr. Hale's office is visible at the far end.",
+      "connected_to": ["lab", "security_office", "hale_office"],
+      "examinables": [],
+      "characters_present": [],
+      "available_from_start": true,
+      "unlock_prerequisites": []
+    },
+    {
+      "id": "hale_office",
+      "name": "Dr. Hale's Office",
+      "description": "A private office belonging to Dr. Victor Hale. Immaculately organized, with awards and patents displayed prominently on the walls. The desk drawers are conspicuously locked.",
+      "connected_to": ["main_hallway"],
+      "examinables": [
+        {
+          "id": "hale_desk",
+          "name": "Dr. Hale's Desk",
+          "description": "An expensive mahogany desk. The locked bottom drawer has a faint scratch around the keyhole, as if it's been opened and closed frequently.",
+          "examined_description": "You manage to open the locked drawer and discover a handheld RFID cloning device! Its internal log shows it was last used on March 14, and the cloned data matches Alex Park's keycard #0247 exactly."
+        }
+      ],
+      "characters_present": ["hale"],
+      "available_from_start": false,
+      "unlock_prerequisites": ["hale_suspicion"]
+    }
+  ],
+  "dialogues": [
+    {
+      "character_id": "alex_park",
+      "lines": [
+        {
+          "id": "alex_intro",
+          "text": "I didn't do it! I wasn't even at the lab that night. I was downtown until late.",
+          "prerequisites": [],
+          "grants_evidence": null
+        },
+        {
+          "id": "alex_bus",
+          "text": "I took the bus home. I have a digital bus pass - it should show when I scanned it!",
+          "prerequisites": [],
+          "grants_evidence": "alex_alibi"
+        }
+      ],
+      "present_responses": []
+    },
+    {
+      "character_id": "chen",
+      "lines": [
+        {
+          "id": "chen_intro",
+          "text": "Alex is a good researcher. I can't believe he would steal the prototype. But the keycard evidence...",
+          "prerequisites": [],
+          "grants_evidence": null
+        },
+        {
+          "id": "chen_hale_info",
+          "text": "Now that I think about it, Dr. Hale has been acting strangely lately. He's been staying late and asking about security protocols.",
+          "prerequisites": ["security_footage"],
+          "grants_evidence": null
+        }
+      ],
+      "present_responses": [
+        {
+          "evidence_id": "security_footage",
+          "text": "That hooded figure... the build looks like it could be Victor Hale too. And he's been asking me strange questions about our security lately.",
+          "grants_evidence": "hale_suspicion",
+          "unlocks_dialogue_line": "chen_hale_info"
+        }
+      ]
+    },
+    {
+      "character_id": "hale",
+      "lines": [
+        {
+          "id": "hale_intro",
+          "text": "Terrible business, this theft. Alex always seemed a bit... envious of the project leads. I'm not surprised, frankly.",
+          "prerequisites": [],
+          "grants_evidence": null
+        }
+      ],
+      "present_responses": []
+    }
+  ],
+  "court": {
+    "penalty_limit": 5,
+    "rounds": [
+      {
+        "witness_id": "morrison",
+        "order": 0,
+        "initial_testimony_id": "morrison_patrol",
+        "testimonies": [
+          {
+            "id": "morrison_patrol",
+            "title": "My Patrol That Night",
+            "witness_id": "morrison",
+            "preamble": "The witness, Morrison, will now testify about his patrol duties on the night of March 15.",
+            "statements": [
+              {
+                "id": "patrol_1",
+                "text": "I patrol the east wing every hour on the hour. That's standard protocol.",
+                "press_response": "It's what we've always done. Every hour, like clockwork. I've been doing this job for ten years — I know the drill better than anyone.",
+                "press_reveals_statement": null,
+                "press_grants_evidence": null,
+                "contradiction": {
+                  "evidence_id": "patrol_schedule",
+                  "explanation": "OBJECTION! The witness claims patrols are conducted every HOUR — but the official QuantumTech security protocol clearly states that east wing patrols must be conducted every THIRTY MINUTES! Morrison, you've been cutting your patrols in half! That means there was a much larger window of opportunity for the real thief than you've led this court to believe!",
+                  "is_primary": true,
+                  "triggers_testimony": "morrison_revised"
+                }
+              },
+              {
+                "id": "patrol_2",
+                "text": "At 11:00 PM, I made my regular pass. Everything was normal in the lab.",
+                "press_response": "I looked through the window. The prototype was still in its case. Nobody was inside. Everything was quiet — just another normal night. Or so I thought.",
+                "press_reveals_statement": null,
+                "press_grants_evidence": null,
+                "contradiction": null
+              },
+              {
+                "id": "patrol_3",
+                "text": "The alarm went off at 11:30 PM. I rushed straight to the lab.",
+                "press_response": "I was at my desk when I heard it. Took me about two minutes to get there. My heart was pounding — in ten years, we've never had a real breach before.",
+                "press_reveals_statement": null,
+                "press_grants_evidence": null,
+                "contradiction": null
+              },
+              {
+                "id": "patrol_4",
+                "text": "When I arrived, the door was open and the prototype case was empty.",
+                "press_response": "No sign of forced entry. Whoever did it had a keycard. The case was wide open, prototype gone. That's when I called the police.",
+                "press_reveals_statement": null,
+                "press_grants_evidence": null,
+                "contradiction": null
+              }
+            ]
+          },
+          {
+            "id": "morrison_revised",
+            "title": "The Truth About My Patrol",
+            "witness_id": "morrison",
+            "preamble": "The witness has admitted to neglecting patrol protocol. He will now provide revised testimony about what he actually saw that night.",
+            "statements": [
+              {
+                "id": "revised_1",
+                "text": "Fine... I admit I sometimes skip patrols. But I was definitely awake the whole time!",
+                "press_response": "I just... rest my eyes sometimes. But I was at my desk! I would have noticed if anything was wrong. ...Probably.",
+                "press_reveals_statement": null,
+                "press_grants_evidence": null,
+                "contradiction": null
+              },
+              {
+                "id": "revised_2",
+                "text": "I saw the defendant enter the lab on the security camera at 11:15 PM.",
+                "press_response": "Well, I saw someone enter. It was definitely the defendant's keycard that was used. The log doesn't lie!",
+                "press_reveals_statement": "revised_2b",
+                "press_grants_evidence": null,
+                "contradiction": null
+              },
+              {
+                "id": "revised_2b",
+                "text": "I mean... the camera showed someone in a hood. But the keycard log showed it was the defendant's card.",
+                "press_response": "A keycard is a keycard. If it says Alex Park, it was Alex Park. Those systems don't make mistakes!",
+                "press_reveals_statement": null,
+                "press_grants_evidence": null,
+                "contradiction": {
+                  "evidence_id": "cloning_device",
+                  "explanation": "OBJECTION! A keycard is NOT always what it seems! This RFID cloning device was found in Dr. Hale's office — and its internal log proves it was used to create a PERFECT COPY of Alex Park's keycard #0247 on March 14, the day BEFORE the theft! The keycard system didn't make a mistake — it was deliberately DECEIVED! Someone cloned the defendant's card to frame him for a crime he didn't commit!",
+                  "is_primary": true,
+                  "triggers_testimony": null
+                }
+              },
+              {
+                "id": "revised_3",
+                "text": "There's no way anyone else could have gotten into that lab. Only authorized keycards work.",
+                "press_response": "The system is foolproof. Whoever's card it shows, that's who was there. There's simply no other explanation!",
+                "press_reveals_statement": null,
+                "press_grants_evidence": null,
+                "contradiction": {
+                  "evidence_id": "alex_alibi",
+                  "explanation": "OBJECTION! The witness claims only Alex Park could have entered that lab — but that is a PHYSICAL IMPOSSIBILITY! Alex Park's bus pass was scanned at Downtown Station at 10:50 PM. The next bus to the QuantumTech area doesn't arrive until 11:55 PM! The lab entry was recorded at 11:15 PM! Unless my client can teleport, he could NOT have been the one who walked through that door! Someone ELSE used a card with his name on it!",
+                  "is_primary": true,
+                  "triggers_testimony": null
+                }
+              }
+            ]
+          }
+        ]
+      }
+    ],
+    "win_condition": {
+      "required_contradiction_ids": ["patrol_1", "revised_2b", "revised_3"],
+      "final_evidence_id": "cloning_device"
+    }
+  },
+  "investigation_gate": {
+    "required_evidence": ["security_footage", "alex_alibi", "patrol_schedule", "cloning_device"],
+    "auto_advance": false
+  }
+}

turnabout/core/actions.py

@@ -0,0 +1,228 @@
+"""Action definitions, text parsing, and discrete encoding."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from difflib import get_close_matches
+from enum import Enum
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from turnabout.i18n import t
+
+if TYPE_CHECKING:
+    from turnabout.core.schema import CaseData
+
+
+class ActionType(Enum):
+    # Investigation
+    MOVE = "move"
+    EXAMINE = "examine"
+    TALK = "talk"
+    PRESENT_TO_NPC = "present_to_npc"
+    GO_TO_COURT = "go_to_court"
+    # Court
+    PRESS = "press"
+    PRESENT_EVIDENCE = "present_evidence"
+    NEXT_STATEMENT = "next_statement"
+    PREV_STATEMENT = "prev_statement"
+
+
+@dataclass(frozen=True)
+class Action:
+    action_type: ActionType
+    target_id: str | None = None
+    secondary_id: str | None = None
+
+    def __str__(self) -> str:
+        t = self.action_type
+        if t == ActionType.GO_TO_COURT:
+            return "go to court"
+        if t == ActionType.NEXT_STATEMENT:
+            return "next"
+        if t == ActionType.PREV_STATEMENT:
+            return "prev"
+        if t == ActionType.MOVE:
+            return f"move {self.target_id}"
+        if t == ActionType.EXAMINE:
+            return f"examine {self.target_id}"
+        if t == ActionType.TALK:
+            return f"talk {self.target_id}"
+        if t == ActionType.PRESS:
+            return f"press {self.target_id}"
+        if t == ActionType.PRESENT_EVIDENCE:
+            return f"present {self.target_id}"
+        if t == ActionType.PRESENT_TO_NPC:
+            return f"present {self.target_id} to {self.secondary_id}"
+        return self.action_type.value
+
+    def display(self, lang: str, case: "CaseData") -> str:
+        at = self.action_type
+        if at == ActionType.MOVE:
+            loc = case.get_location(self.target_id)
+            name = loc.name if loc else self.target_id
+            return t("action_move", lang).format(name=name)
+        if at == ActionType.EXAMINE:
+            name = self.target_id
+            for loc in case.locations:
+                for ex in loc.examinables:
+                    if ex.id == self.target_id:
+                        name = ex.name
+                        break
+            return t("action_examine", lang).format(name=name)
+        if at == ActionType.TALK:
+            ch = case.get_character(self.target_id)
+            name = ch.name if ch else self.target_id
+            return t("action_talk", lang).format(name=name)
+        if at == ActionType.PRESS:
+            return t("action_press", lang)
+        if at == ActionType.PRESENT_EVIDENCE:
+            ev = case.get_evidence(self.target_id)
+            name = ev.name if ev else self.target_id
+            return t("action_present_evidence", lang).format(name=name)
+        if at == ActionType.PRESENT_TO_NPC:
+            ev = case.get_evidence(self.target_id)
+            ch = case.get_character(self.secondary_id)
+            ev_name = ev.name if ev else self.target_id
+            ch_name = ch.name if ch else self.secondary_id
+            return t("action_present_to_npc", lang).format(ev=ev_name, char=ch_name)
+        if at == ActionType.GO_TO_COURT:
+            return t("action_go_to_court", lang)
+        if at == ActionType.NEXT_STATEMENT:
+            return t("action_next", lang)
+        if at == ActionType.PREV_STATEMENT:
+            return t("action_prev", lang)
+        return str(self)
+
+
+_PATTERNS: list[tuple[re.Pattern, ActionType, int]] = [
+    (re.compile(r"^go\s+to\s+court$", re.I), ActionType.GO_TO_COURT, 0),
+    (re.compile(r"^next$", re.I), ActionType.NEXT_STATEMENT, 0),
+    (re.compile(r"^prev(?:ious)?$", re.I), ActionType.PREV_STATEMENT, 0),
+    (re.compile(r"^move\s+(?:to\s+)?(.+)$", re.I), ActionType.MOVE, 1),
+    (re.compile(r"^examine\s+(.+)$", re.I), ActionType.EXAMINE, 1),
+    (re.compile(r"^talk\s+(?:to\s+)?(.+)$", re.I), ActionType.TALK, 1),
+    (re.compile(r"^press(?:\s+(\S+))?$", re.I), ActionType.PRESS, 1),
+    (re.compile(r"^present\s+(\S+)\s+(?:to\s+)?(\S+)$", re.I), ActionType.PRESENT_TO_NPC, 2),
+    (re.compile(r"^present\s+(\S+)$", re.I), ActionType.PRESENT_EVIDENCE, 1),
+]
+
+
+class ActionParser:
+    def __init__(self, case: CaseData):
+        self._names: dict[str, str] = {}
+        for loc in case.locations:
+            self._names[loc.name.lower()] = loc.id
+            self._names[loc.id.lower()] = loc.id
+            for ex in loc.examinables:
+                self._names[ex.name.lower()] = ex.id
+                self._names[ex.id.lower()] = ex.id
+        for ch in case.characters:
+            self._names[ch.name.lower()] = ch.id
+            self._names[ch.id.lower()] = ch.id
+        for ev in case.evidence:
+            self._names[ev.name.lower()] = ev.id
+            self._names[ev.id.lower()] = ev.id
+        for rnd in case.court.rounds:
+            for tst in rnd.testimonies:
+                for stmt in tst.statements:
+                    self._names[stmt.id.lower()] = stmt.id
+
+    def _resolve(self, raw: str) -> str | None:
+        low = raw.strip().lower()
+        if low in self._names:
+            return self._names[low]
+        matches = get_close_matches(low, self._names.keys(), n=1, cutoff=0.6)
+        if matches:
+            return self._names[matches[0]]
+        return raw.strip()
+
+    def parse(self, text: str) -> Action | None:
+        text = text.strip()
+        for pattern, action_type, n_groups in _PATTERNS:
+            m = pattern.match(text)
+            if not m:
+                continue
+            if n_groups == 0:
+                return Action(action_type)
+            if n_groups == 1:
+                g = m.group(1)
+                target = self._resolve(g) if g else None
+                return Action(action_type, target_id=target)
+            if n_groups == 2:
+                return Action(
+                    action_type,
+                    target_id=self._resolve(m.group(1)),
+                    secondary_id=self._resolve(m.group(2)),
+                )
+        return None
+
+
+class DiscreteActionEncoder:
+    def __init__(self, case: CaseData):
+        self._actions: list[Action] = []
+        self._index: dict[Action, int] = {}
+        self._build(case)
+
+    def _build(self, case: CaseData) -> None:
+        actions: list[Action] = []
+        loc_ids = [loc.id for loc in case.locations]
+        for lid in loc_ids:
+            actions.append(Action(ActionType.MOVE, target_id=lid))
+
+        exam_ids: list[str] = []
+        for loc in case.locations:
+            for ex in loc.examinables:
+                if ex.id not in exam_ids:
+                    exam_ids.append(ex.id)
+        for eid in exam_ids:
+            actions.append(Action(ActionType.EXAMINE, target_id=eid))
+
+        char_ids = [c.id for c in case.characters if c.role not in ("judge",)]
+        for cid in char_ids:
+            actions.append(Action(ActionType.TALK, target_id=cid))
+
+        ev_ids = [e.id for e in case.evidence]
+        for eid in ev_ids:
+            for cid in char_ids:
+                actions.append(Action(ActionType.PRESENT_TO_NPC, target_id=eid, secondary_id=cid))
+
+        actions.append(Action(ActionType.GO_TO_COURT))
+
+        all_stmts: list[str] = []
+        for rnd in case.court.rounds:
+            for t in rnd.testimonies:
+                for s in t.statements:
+                    if s.id not in all_stmts:
+                        all_stmts.append(s.id)
+        for sid in all_stmts:
+            actions.append(Action(ActionType.PRESS, target_id=sid))
+
+        for eid in ev_ids:
+            actions.append(Action(ActionType.PRESENT_EVIDENCE, target_id=eid))
+
+        actions.append(Action(ActionType.NEXT_STATEMENT))
+        actions.append(Action(ActionType.PREV_STATEMENT))
+
+        self._actions = actions
+        self._index = {a: i for i, a in enumerate(actions)}
+
+    @property
+    def n_actions(self) -> int:
+        return len(self._actions)
+
+    def encode(self, action: Action) -> int:
+        return self._index[action]
+
+    def decode(self, action_int: int) -> Action:
+        return self._actions[action_int]
+
+    def get_action_mask(self, valid_actions: list[Action]) -> np.ndarray:
+        mask = np.zeros(self.n_actions, dtype=np.int8)
+        valid_set = set(valid_actions)
+        for i, a in enumerate(self._actions):
+            if a in valid_set:
+                mask[i] = 1
+        return mask

turnabout/core/engine.py

@@ -0,0 +1,617 @@
+"""Core game engine — state machine driving all game logic."""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from typing import Literal
+
+from turnabout.core.actions import Action, ActionType
+from turnabout.core.schema import CaseData, Statement, Testimony
+from turnabout.core.state import ActionRecord, GamePhase, GameState
+from turnabout.i18n import t
+
+DEFAULT_REWARDS = {
+    "correct_contradiction": 1.0,
+    "optional_contradiction": 0.3,
+    "wrong_presentation": -0.5,
+    "evidence_collected": 0.1,
+    "press_useful": 0.05,
+    "press_redundant": 0.0,
+    "win": 5.0,
+    "lose": -5.0,
+    "step_cost": -0.01,
+    "invalid_action": -0.1,
+}
+
+
+@dataclass
+class StepResult:
+    observation: str
+    reward: float
+    done: bool
+    info: dict
+
+
+class TurnaboutEngine:
+    def __init__(
+        self,
+        case: CaseData,
+        difficulty: Literal["easy", "hard"] | None = None,
+        rewards: dict[str, float] | None = None,
+        lang: str = "en",
+    ):
+        self.case = case
+        self.difficulty = difficulty or case.difficulty
+        self.rewards = {**DEFAULT_REWARDS, **(rewards or {})}
+        self.lang = lang
+        self.state: GameState | None = None
+
+    def reset(self) -> tuple[GameState, str]:
+        if self.difficulty == "easy":
+            inventory = {e.id for e in self.case.evidence}
+            phase = GamePhase.COURT_TESTIMONY
+            location = None
+        else:
+            inventory = {e.id for e in self.case.get_pre_given_evidence()}
+            phase = GamePhase.INVESTIGATION
+            start_locs = [loc for loc in self.case.locations if loc.available_from_start]
+            location = start_locs[0].id if start_locs else None
+
+        rnd = self.case.court.rounds[0]
+        testimony_id = rnd.initial_testimony_id
+
+        self.state = GameState(
+            phase=phase,
+            current_location_id=location,
+            inventory=inventory,
+            unlocked_locations={loc.id for loc in self.case.locations if loc.available_from_start},
+            current_round_index=0,
+            current_testimony_id=testimony_id,
+            current_statement_index=0,
+        )
+
+        obs = self._make_observation("", phase_entry=True)
+        return self.state, obs
+
+    def step(self, action: Action) -> tuple[GameState, str, float, bool, dict]:
+        assert self.state is not None, "Must call reset() first"
+        assert not self.state.is_terminal, "Game is already over"
+
+        self.state.step_count += 1
+        reward = self.rewards["step_cost"]
+
+        if action.action_type == ActionType.PRESS and action.target_id is None:
+            testimony = self._current_testimony()
+            visible = self._visible_statements(testimony)
+            idx = self.state.current_statement_index
+            if idx < len(visible):
+                action = Action(ActionType.PRESS, target_id=visible[idx].id)
+
+        valid = self.get_valid_actions()
+        if action not in valid:
+            obs = t("invalid_action", self.lang).format(action=action, valid=', '.join(str(a) for a in valid))
+            reward += self.rewards["invalid_action"]
+            self._record(action, obs)
+            return self.state, obs, reward, False, {"valid": False}
+
+        if self.state.phase == GamePhase.INVESTIGATION:
+            result = self._handle_investigation(action)
+        elif self.state.phase in (GamePhase.COURT_TESTIMONY, GamePhase.COURT_CROSS_EXAM):
+            result = self._handle_court(action)
+        else:
+            result = StepResult("Unexpected phase.", 0, False, {})
+
+        reward += result.reward
+        self._record(action, result.observation)
+        return self.state, result.observation, reward, result.done, result.info
+
+    def get_valid_actions(self) -> list[Action]:
+        if self.state is None or self.state.is_terminal:
+            return []
+
+        actions: list[Action] = []
+
+        if self.state.phase == GamePhase.INVESTIGATION:
+            self._add_investigation_actions(actions)
+        elif self.state.phase in (GamePhase.COURT_TESTIMONY, GamePhase.COURT_CROSS_EXAM):
+            self._add_court_actions(actions)
+
+        return actions
+
+    def _add_investigation_actions(self, actions: list[Action]) -> None:
+        loc = self.case.get_location(self.state.current_location_id)
+        if not loc:
+            return
+
+        for cid in loc.connected_to:
+            target_loc = self.case.get_location(cid)
+            if target_loc and cid in self.state.unlocked_locations:
+                actions.append(Action(ActionType.MOVE, target_id=cid))
+
+        for ex in loc.examinables:
+            actions.append(Action(ActionType.EXAMINE, target_id=ex.id))
+
+        for cid in loc.characters_present:
+            ch = self.case.get_character(cid)
+            if ch and ch.role != "judge":
+                actions.append(Action(ActionType.TALK, target_id=cid))
+
+        for eid in sorted(self.state.inventory):
+            for cid in loc.characters_present:
+                ch = self.case.get_character(cid)
+                if ch and ch.role not in ("judge", "defendant"):
+                    actions.append(Action(ActionType.PRESENT_TO_NPC, target_id=eid, secondary_id=cid))
+
+        if self._can_go_to_court():
+            actions.append(Action(ActionType.GO_TO_COURT))
+
+    def _add_court_actions(self, actions: list[Action]) -> None:
+        testimony = self._current_testimony()
+        if not testimony:
+            return
+
+        visible = self._visible_statements(testimony)
+        if not visible:
+            return
+
+        if self.state.phase == GamePhase.COURT_TESTIMONY:
+            actions.append(Action(ActionType.NEXT_STATEMENT))
+            return
+
+        idx = self.state.current_statement_index
+        stmt = visible[idx] if idx < len(visible) else None
+        if stmt:
+            actions.append(Action(ActionType.PRESS, target_id=stmt.id))
+
+        for eid in sorted(self.state.inventory):
+            actions.append(Action(ActionType.PRESENT_EVIDENCE, target_id=eid))
+
+        if idx < len(visible) - 1:
+            actions.append(Action(ActionType.NEXT_STATEMENT))
+        if idx > 0:
+            actions.append(Action(ActionType.PREV_STATEMENT))
+
+    def _handle_investigation(self, action: Action) -> StepResult:
+        if action.action_type == ActionType.MOVE:
+            return self._do_move(action.target_id)
+        elif action.action_type == ActionType.EXAMINE:
+            return self._do_examine(action.target_id)
+        elif action.action_type == ActionType.TALK:
+            return self._do_talk(action.target_id)
+        elif action.action_type == ActionType.PRESENT_TO_NPC:
+            return self._do_present_to_npc(action.target_id, action.secondary_id)
+        elif action.action_type == ActionType.GO_TO_COURT:
+            return self._do_go_to_court()
+        return StepResult(t("unknown_action", self.lang), 0, False, {})
+
+    def _handle_court(self, action: Action) -> StepResult:
+        if self.state.phase == GamePhase.COURT_TESTIMONY:
+            if action.action_type == ActionType.NEXT_STATEMENT:
+                return self._do_advance_testimony()
+            return StepResult(t("during_testimony", self.lang), 0, False, {})
+
+        if action.action_type == ActionType.PRESS:
+            return self._do_press(action.target_id)
+        elif action.action_type == ActionType.PRESENT_EVIDENCE:
+            return self._do_present_evidence(action.target_id)
+        elif action.action_type == ActionType.NEXT_STATEMENT:
+            return self._do_next_statement()
+        elif action.action_type == ActionType.PREV_STATEMENT:
+            return self._do_prev_statement()
+        return StepResult(t("unknown_action", self.lang), 0, False, {})
+
+    # --- Investigation actions ---
+
+    def _do_move(self, location_id: str) -> StepResult:
+        self.state.current_location_id = location_id
+        loc = self.case.get_location(location_id)
+        obs = t("move_to", self.lang).format(name=loc.name, desc=loc.description)
+        return StepResult(obs, 0, False, {"action": "move", "location": location_id})
+
+    def _do_examine(self, target_id: str) -> StepResult:
+        loc = self.case.get_location(self.state.current_location_id)
+        ex = next((e for e in loc.examinables if e.id == target_id), None)
+        if not ex:
+            return StepResult(t("nothing_to_examine", self.lang), 0, False, {})
+
+        already = target_id in self.state.examined
+        if already and ex.examined_description:
+            obs = ex.examined_description
+        else:
+            obs = ex.description
+            self.state.examined.add(target_id)
+
+        reward = 0.0
+        new_evidence = self._check_evidence_from_examine(target_id)
+        if new_evidence:
+            reward = self.rewards["evidence_collected"]
+            obs += t("new_evidence", self.lang).format(name=new_evidence.name)
+
+        return StepResult(obs, reward, False, {"action": "examine", "target": target_id})
+
+    def _do_talk(self, character_id: str) -> StepResult:
+        dialogue = next((d for d in self.case.dialogues if d.character_id == character_id), None)
+        ch = self.case.get_character(character_id)
+        if not dialogue:
+            return StepResult(t("nothing_to_say", self.lang).format(name=ch.name), 0, False, {})
+
+        visible_lines = [
+            line for line in dialogue.lines
+            if all(p in self.state.inventory for p in line.prerequisites)
+            and line.id not in self.state.dialogue_lines_seen
+        ]
+
+        if not visible_lines:
+            already_seen = [
+                line for line in dialogue.lines
+                if all(p in self.state.inventory for p in line.prerequisites)
+            ]
+            if already_seen:
+                obs = f"{ch.name}: \"{already_seen[-1].text}\"\n{t('nothing_new', self.lang)}"
+            else:
+                obs = t("nothing_to_say_now", self.lang).format(name=ch.name)
+            return StepResult(obs, 0, False, {"action": "talk"})
+
+        reward = 0.0
+        parts = []
+        for line in visible_lines:
+            self.state.dialogue_lines_seen.add(line.id)
+            parts.append(f'{ch.name}: "{line.text}"')
+            if line.grants_evidence:
+                ev = self.case.get_evidence(line.grants_evidence)
+                if ev and line.grants_evidence not in self.state.inventory:
+                    self.state.inventory.add(line.grants_evidence)
+                    reward += self.rewards["evidence_collected"]
+                    parts.append(t("new_evidence", self.lang).format(name=ev.name))
+
+        obs = "\n".join(parts)
+        return StepResult(obs, reward, False, {"action": "talk", "character": character_id})
+
+    def _do_present_to_npc(self, evidence_id: str, character_id: str) -> StepResult:
+        pair = (evidence_id, character_id)
+        self.state.evidence_presented_to.add(pair)
+
+        dialogue = next((d for d in self.case.dialogues if d.character_id == character_id), None)
+        ch = self.case.get_character(character_id)
+        ev = self.case.get_evidence(evidence_id)
+        if not dialogue:
+            return StepResult(t("no_comment", self.lang).format(char=ch.name, ev=ev.name), 0, False, {})
+
+        response = next(
+            (r for r in dialogue.present_responses if r.evidence_id == evidence_id), None
+        )
+        if not response:
+            return StepResult(
+                t("nothing_useful", self.lang).format(char=ch.name, ev=ev.name),
+                0, False, {"action": "present_to_npc"},
+            )
+
+        reward = 0.0
+        obs = f'{ch.name}: "{response.text}"'
+        if response.grants_evidence and response.grants_evidence not in self.state.inventory:
+            new_ev = self.case.get_evidence(response.grants_evidence)
+            self.state.inventory.add(response.grants_evidence)
+            reward += self.rewards["evidence_collected"]
+            obs += t("new_evidence", self.lang).format(name=new_ev.name)
+            self._check_unlock_locations()
+
+        if response.unlocks_dialogue_line:
+            pass
+
+        ev_from_acquisition = self._check_evidence_from_present(evidence_id, character_id)
+        if ev_from_acquisition and ev_from_acquisition.id not in self.state.inventory:
+            self.state.inventory.add(ev_from_acquisition.id)
+            reward += self.rewards["evidence_collected"]
+            obs += t("new_evidence", self.lang).format(name=ev_from_acquisition.name)
+            self._check_unlock_locations()
+
+        return StepResult(obs, reward, False, {"action": "present_to_npc"})
+
+    def _do_go_to_court(self) -> StepResult:
+        self.state.phase = GamePhase.COURT_TESTIMONY
+        self.state.current_round_index = 0
+        rnd = self.case.court.rounds[0]
+        self.state.current_testimony_id = rnd.initial_testimony_id
+        self.state.current_statement_index = 0
+
+        testimony = self._current_testimony()
+        obs = t("court_in_session", self.lang) + "\n\n"
+        if testimony:
+            witness = self.case.get_character(testimony.witness_id)
+            obs += t("witness_label", self.lang).format(name=witness.name) + "\n"
+            obs += t("testimony_label", self.lang).format(title=testimony.title) + "\n\n"
+            obs += testimony.preamble
+        return StepResult(obs, 0, False, {"action": "go_to_court", "phase": "court_testimony"})
+
+    # --- Court actions ---
+
+    def _do_advance_testimony(self) -> StepResult:
+        self.state.phase = GamePhase.COURT_CROSS_EXAM
+        self.state.current_statement_index = 0
+        testimony = self._current_testimony()
+        visible = self._visible_statements(testimony)
+
+        obs = t("cross_exam_header", self.lang) + "\n"
+        if testimony:
+            obs += f'"{testimony.title}"\n\n'
+        if visible:
+            obs += t("statement_label", self.lang).format(num=1, text=visible[0].text) + "\n"
+            obs += t("press_or_present", self.lang)
+        return StepResult(obs, 0, False, {"phase": "cross_exam"})
+
+    def _do_press(self, statement_id: str | None) -> StepResult:
+        testimony = self._current_testimony()
+        visible = self._visible_statements(testimony)
+        if not statement_id:
+            idx = self.state.current_statement_index
+            if idx < len(visible):
+                stmt = visible[idx]
+                statement_id = stmt.id
+            else:
+                return StepResult(t("no_current_statement", self.lang), 0, False, {})
+        else:
+            stmt = next((s for s in visible if s.id == statement_id), None)
+        if not stmt:
+            return StepResult(t("statement_not_visible", self.lang), 0, False, {})
+
+        self.state.statements_pressed.add(statement_id)
+        reward = 0.0
+        obs = t("hold_it", self.lang) + f"\n\n{stmt.press_response}"
+
+        if stmt.press_reveals_statement:
+            self.state.revealed_statements.add(stmt.press_reveals_statement)
+            new_stmt = self.case.get_statement(stmt.press_reveals_statement)
+            if new_stmt:
+                obs += t("witness_amends", self.lang).format(text=new_stmt.text)
+                reward = self.rewards["press_useful"]
+
+        if stmt.press_grants_evidence and stmt.press_grants_evidence not in self.state.inventory:
+            ev = self.case.get_evidence(stmt.press_grants_evidence)
+            self.state.inventory.add(stmt.press_grants_evidence)
+            reward = self.rewards["press_useful"]
+            obs += t("new_evidence", self.lang).format(name=ev.name)
+
+        if reward == 0:
+            reward = self.rewards["press_redundant"]
+
+        return StepResult(obs, reward, False, {"action": "press", "statement": statement_id})
+
+    def _do_present_evidence(self, evidence_id: str) -> StepResult:
+        testimony = self._current_testimony()
+        visible = self._visible_statements(testimony)
+        idx = self.state.current_statement_index
+        if idx >= len(visible):
+            return StepResult(t("no_current_statement", self.lang), 0, False, {})
+
+        stmt = visible[idx]
+
+        if stmt.contradiction and stmt.contradiction.evidence_id == evidence_id:
+            return self._correct_contradiction(stmt)
+        else:
+            return self._wrong_presentation(evidence_id, stmt)
+
+    def _correct_contradiction(self, stmt: Statement) -> StepResult:
+        c = stmt.contradiction
+        self.state.contradictions_found.add(stmt.id)
+
+        reward = (
+            self.rewards["correct_contradiction"]
+            if c.is_primary
+            else self.rewards["optional_contradiction"]
+        )
+
+        obs = t("objection", self.lang) + f"\n\n{c.explanation}"
+
+        if c.triggers_testimony:
+            self.state.current_testimony_id = c.triggers_testimony
+            self.state.current_statement_index = 0
+            self.state.phase = GamePhase.COURT_TESTIMONY
+            new_testimony = self._current_testimony()
+            if new_testimony:
+                witness = self.case.get_character(new_testimony.witness_id)
+                obs += t("new_testimony", self.lang) + "\n"
+                obs += t("witness_label", self.lang).format(name=witness.name) + "\n"
+                obs += f'"{new_testimony.title}"\n\n'
+                obs += new_testimony.preamble
+            return StepResult(obs, reward, False, {"action": "objection", "triggers": c.triggers_testimony})
+
+        if self._check_win():
+            self.state.phase = GamePhase.VERDICT_WIN
+            obs += t("not_guilty", self.lang)
+            reward += self.rewards["win"]
+            return StepResult(obs, reward, True, {"action": "objection", "won": True})
+
+        return StepResult(obs, reward, False, {"action": "objection"})
+
+    def _wrong_presentation(self, evidence_id: str, stmt: Statement) -> StepResult:
+        self.state.penalties += 1
+        ev = self.case.get_evidence(evidence_id)
+
+        obs = t("wrong_present", self.lang).format(
+            ev=ev.name, cur=self.state.penalties, max=self.case.court.penalty_limit
+        )
+
+        reward = self.rewards["wrong_presentation"]
+
+        if self.state.penalties >= self.case.court.penalty_limit:
+            self.state.phase = GamePhase.VERDICT_LOSE
+            obs += t("guilty", self.lang)
+            reward += self.rewards["lose"]
+            return StepResult(obs, reward, True, {"action": "wrong_present", "lost": True})
+
+        return StepResult(obs, reward, False, {"action": "wrong_present"})
+
+    def _do_next_statement(self) -> StepResult:
+        testimony = self._current_testimony()
+        visible = self._visible_statements(testimony)
+        if self.state.current_statement_index < len(visible) - 1:
+            self.state.current_statement_index += 1
+        idx = self.state.current_statement_index
+        stmt = visible[idx]
+        obs = t("statement_label", self.lang).format(num=idx + 1, text=stmt.text)
+        return StepResult(obs, 0, False, {"action": "next", "index": idx})
+
+    def _do_prev_statement(self) -> StepResult:
+        if self.state.current_statement_index > 0:
+            self.state.current_statement_index -= 1
+        idx = self.state.current_statement_index
+        testimony = self._current_testimony()
+        visible = self._visible_statements(testimony)
+        stmt = visible[idx]
+        obs = t("statement_label", self.lang).format(num=idx + 1, text=stmt.text)
+        return StepResult(obs, 0, False, {"action": "prev", "index": idx})
+
+    # --- Helpers ---
+
+    def _current_testimony(self) -> Testimony | None:
+        return self.case.get_testimony(self.state.current_testimony_id)
+
+    def _visible_statements(self, testimony: Testimony | None) -> list[Statement]:
+        if not testimony:
+            return []
+        visible = []
+        for s in testimony.statements:
+            if s.press_reveals_statement and s.id not in self.state.revealed_statements:
+                if any(
+                    prev.press_reveals_statement == s.id
+                    for prev in testimony.statements
+                    if prev.id != s.id
+                ):
+                    continue
+            visible.append(s)
+        return visible
+
+    def _can_go_to_court(self) -> bool:
+        if self.difficulty == "easy":
+            return False
+        gate = self.case.investigation_gate
+        if not gate:
+            return True
+        if gate.required_evidence:
+            return all(eid in self.state.inventory for eid in gate.required_evidence)
+        return True
+
+    def _check_win(self) -> bool:
+        required = set(self.case.court.win_condition.required_contradiction_ids)
+        return required.issubset(self.state.contradictions_found)
+
+    def _check_evidence_from_examine(self, target_id: str) -> "EvidenceItem | None":
+        for ev in self.case.evidence:
+            if (
+                ev.source == "investigation"
+                and ev.acquisition
+                and ev.acquisition.method == "examine"
+                and ev.acquisition.target_id == target_id
+                and ev.id not in self.state.inventory
+                and all(p in self.state.inventory for p in ev.acquisition.prerequisites)
+            ):
+                self.state.inventory.add(ev.id)
+                self._check_unlock_locations()
+                return ev
+        return None
+
+    def _check_evidence_from_present(self, evidence_id: str, character_id: str) -> "EvidenceItem | None":
+        for ev in self.case.evidence:
+            if (
+                ev.source == "investigation"
+                and ev.acquisition
+                and ev.acquisition.method == "present"
+                and ev.acquisition.target_id == character_id
+                and ev.acquisition.present_evidence_id == evidence_id
+                and ev.id not in self.state.inventory
+                and all(p in self.state.inventory for p in ev.acquisition.prerequisites)
+            ):
+                return ev
+        return None
+
+    def _check_unlock_locations(self) -> None:
+        for loc in self.case.locations:
+            if (
+                not loc.available_from_start
+                and loc.id not in self.state.unlocked_locations
+                and all(p in self.state.inventory for p in loc.unlock_prerequisites)
+            ):
+                self.state.unlocked_locations.add(loc.id)
+
+    def _record(self, action: Action, obs: str) -> None:
+        self.state.action_history.append(
+            ActionRecord(
+                step=self.state.step_count,
+                phase=self.state.phase,
+                action_type=action.action_type.value,
+                target_id=action.target_id,
+                secondary_id=action.secondary_id,
+                result=obs[:200],
+            )
+        )
+
+    def _make_observation(self, text: str, phase_entry: bool = False) -> str:
+        if not phase_entry:
+            return text
+
+        if self.state.phase == GamePhase.INVESTIGATION:
+            loc = self.case.get_location(self.state.current_location_id)
+            if loc:
+                return t("investigation_header", self.lang) + "\n" + t("move_to", self.lang).format(name=loc.name, desc=loc.description)
+            return t("investigation_header", self.lang)
+        elif self.state.phase == GamePhase.COURT_TESTIMONY:
+            testimony = self._current_testimony()
+            if testimony:
+                witness = self.case.get_character(testimony.witness_id)
+                return (
+                    t("court_in_session", self.lang) + "\n\n"
+                    + t("witness_label", self.lang).format(name=witness.name) + "\n"
+                    + t("testimony_label", self.lang).format(title=testimony.title) + "\n\n"
+                    + testimony.preamble
+                )
+            return t("court_in_session", self.lang)
+        return text
+
+    def get_optimal_path(self) -> list[Action] | None:
+        """BFS to find shortest winning action sequence."""
+        if self.state is None:
+            return None
+
+        initial = self.state.copy()
+        queue: deque[tuple[GameState, list[Action]]] = deque()
+        queue.append((initial, []))
+        visited: set[str] = set()
+
+        while queue:
+            state, path = queue.popleft()
+            key = self._state_key(state)
+            if key in visited:
+                continue
+            visited.add(key)
+
+            if state.phase == GamePhase.VERDICT_WIN:
+                return path
+
+            if len(visited) > 50000:
+                return None
+
+            saved = self.state
+            self.state = state
+            valid_actions = self.get_valid_actions()
+            self.state = saved
+
+            for action in valid_actions:
+                child_engine = TurnaboutEngine(self.case, self.difficulty, self.rewards)
+                child_engine.state = state.copy()
+                _, _, _, done, _ = child_engine.step(action)
+                new_state = child_engine.state
+                new_key = self._state_key(new_state)
+                if new_key not in visited:
+                    queue.append((new_state, path + [action]))
+
+        return None
+
+    @staticmethod
+    def _state_key(state: GameState) -> str:
+        return (
+            f"{state.phase.value}|{state.current_location_id}|"
+            f"{sorted(state.inventory)}|{state.current_testimony_id}|"
+            f"{state.current_statement_index}|{state.penalties}|"
+            f"{sorted(state.contradictions_found)}|{sorted(state.revealed_statements)}"
+        )

turnabout/core/schema.py

@@ -0,0 +1,187 @@
+"""Pydantic v2 models defining the case data schema.
+
+This is the most critical file in the project. All other components
+consume or produce this schema.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, field_validator
+
+
+class CaseMetadata(BaseModel):
+    author: str = "human"
+    version: str = "1.0"
+    tags: list[str] = []
+
+
+class Character(BaseModel):
+    id: str
+    name: str
+    description: str
+    role: Literal["defendant", "witness", "npc", "prosecutor", "judge"]
+
+
+class EvidenceAcquisition(BaseModel):
+    method: Literal["examine", "talk", "present"]
+    location_id: str
+    target_id: str
+    prerequisites: list[str] = []
+    present_evidence_id: str | None = None
+
+
+class EvidenceItem(BaseModel):
+    id: str
+    name: str
+    item_type: Literal["document", "physical", "photo", "testimony_record"]
+    description: str
+    detail: str
+    source: Literal["pre_given", "investigation"]
+    acquisition: EvidenceAcquisition | None = None
+
+    @field_validator("acquisition")
+    @classmethod
+    def check_acquisition(cls, v: EvidenceAcquisition | None, info) -> EvidenceAcquisition | None:
+        source = info.data.get("source")
+        if source == "investigation" and v is None:
+            raise ValueError("investigation evidence must have acquisition info")
+        return v
+
+
+class Examinable(BaseModel):
+    id: str
+    name: str
+    description: str
+    examined_description: str | None = None
+
+
+class Location(BaseModel):
+    id: str
+    name: str
+    description: str
+    connected_to: list[str] = []
+    examinables: list[Examinable] = []
+    characters_present: list[str] = []
+    available_from_start: bool = True
+    unlock_prerequisites: list[str] = []
+
+
+class DialogueLine(BaseModel):
+    id: str
+    text: str
+    prerequisites: list[str] = []
+    grants_evidence: str | None = None
+
+
+class EvidencePresentResponse(BaseModel):
+    evidence_id: str
+    text: str
+    grants_evidence: str | None = None
+    unlocks_dialogue_line: str | None = None
+
+
+class DialogueTree(BaseModel):
+    character_id: str
+    lines: list[DialogueLine] = []
+    present_responses: list[EvidencePresentResponse] = []
+
+
+class Contradiction(BaseModel):
+    evidence_id: str
+    explanation: str
+    is_primary: bool = True
+    triggers_testimony: str | None = None
+
+
+class Statement(BaseModel):
+    id: str
+    text: str
+    press_response: str
+    press_reveals_statement: str | None = None
+    press_grants_evidence: str | None = None
+    contradiction: Contradiction | None = None
+
+
+class Testimony(BaseModel):
+    id: str
+    title: str
+    witness_id: str
+    preamble: str
+    statements: list[Statement]
+
+
+class CourtRound(BaseModel):
+    witness_id: str
+    order: int
+    initial_testimony_id: str
+    testimonies: list[Testimony]
+
+
+class WinCondition(BaseModel):
+    required_contradiction_ids: list[str]
+    final_evidence_id: str | None = None
+
+
+class CourtProceedings(BaseModel):
+    penalty_limit: int = 5
+    rounds: list[CourtRound]
+    win_condition: WinCondition
+
+
+class InvestigationGate(BaseModel):
+    required_evidence: list[str]
+    auto_advance: bool = False
+
+
+class CaseData(BaseModel):
+    id: str
+    title: str
+    difficulty: Literal["easy", "hard"]
+    description: str
+    metadata: CaseMetadata = CaseMetadata()
+    characters: list[Character]
+    evidence: list[EvidenceItem]
+    locations: list[Location] = []
+    dialogues: list[DialogueTree] = []
+    court: CourtProceedings
+    investigation_gate: InvestigationGate | None = None
+
+    def get_character(self, character_id: str) -> Character | None:
+        return next((c for c in self.characters if c.id == character_id), None)
+
+    def get_evidence(self, evidence_id: str) -> EvidenceItem | None:
+        return next((e for e in self.evidence if e.id == evidence_id), None)
+
+    def get_location(self, location_id: str) -> Location | None:
+        return next((loc for loc in self.locations if loc.id == location_id), None)
+
+    def get_testimony(self, testimony_id: str) -> Testimony | None:
+        for rnd in self.court.rounds:
+            for t in rnd.testimonies:
+                if t.id == testimony_id:
+                    return t
+        return None
+
+    def get_statement(self, statement_id: str) -> Statement | None:
+        for rnd in self.court.rounds:
+            for t in rnd.testimonies:
+                for s in t.statements:
+                    if s.id == statement_id:
+                        return s
+        return None
+
+    def get_pre_given_evidence(self) -> list[EvidenceItem]:
+        return [e for e in self.evidence if e.source == "pre_given"]
+
+    def get_all_evidence_ids(self) -> set[str]:
+        return {e.id for e in self.evidence}
+
+    def get_required_contradiction_statements(self) -> list[Statement]:
+        result = []
+        for sid in self.court.win_condition.required_contradiction_ids:
+            s = self.get_statement(sid)
+            if s:
+                result.append(s)
+        return result

turnabout/core/scoring.py

@@ -0,0 +1,126 @@
+"""Evaluation metrics computation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from turnabout.core.engine import TurnaboutEngine
+from turnabout.core.schema import CaseData
+from turnabout.core.state import GameState
+
+
+@dataclass
+class EpisodeMetrics:
+    won: bool = False
+    # Court
+    total_contradictions_required: int = 0
+    contradictions_found: int = 0
+    correct_presentations: int = 0
+    wrong_presentations: int = 0
+    contradiction_accuracy: float = 0.0
+    statements_pressed: int = 0
+    total_statements: int = 0
+    press_coverage: float = 0.0
+    # Investigation
+    evidence_available: int = 0
+    evidence_collected: int = 0
+    evidence_coverage: float = 0.0
+    required_evidence_collected: int = 0
+    required_evidence_total: int = 0
+    # Efficiency
+    total_steps: int = 0
+    optimal_steps: int | None = None
+    step_efficiency: float = 0.0
+    investigation_steps: int = 0
+    court_steps: int = 0
+    # Aggregate
+    total_reward: float = 0.0
+    composite_score: float = 0.0
+
+    def to_dict(self) -> dict:
+        return {
+            "won": self.won,
+            "total_contradictions_required": self.total_contradictions_required,
+            "contradictions_found": self.contradictions_found,
+            "correct_presentations": self.correct_presentations,
+            "wrong_presentations": self.wrong_presentations,
+            "contradiction_accuracy": self.contradiction_accuracy,
+            "statements_pressed": self.statements_pressed,
+            "total_statements": self.total_statements,
+            "press_coverage": self.press_coverage,
+            "evidence_available": self.evidence_available,
+            "evidence_collected": self.evidence_collected,
+            "evidence_coverage": self.evidence_coverage,
+            "total_steps": self.total_steps,
+            "optimal_steps": self.optimal_steps,
+            "step_efficiency": self.step_efficiency,
+            "investigation_steps": self.investigation_steps,
+            "court_steps": self.court_steps,
+            "total_reward": self.total_reward,
+            "composite_score": self.composite_score,
+        }
+
+
+class MetricsComputer:
+    def __init__(self, engine: TurnaboutEngine):
+        self.engine = engine
+        self.case = engine.case
+        self._total_reward = 0.0
+
+    def accumulate_reward(self, reward: float) -> None:
+        self._total_reward += reward
+
+    def compute(self, state: GameState) -> EpisodeMetrics:
+        m = EpisodeMetrics()
+        m.won = state.phase.value == "verdict_win"
+        m.total_reward = self._total_reward
+
+        required_ids = set(self.case.court.win_condition.required_contradiction_ids)
+        m.total_contradictions_required = len(required_ids)
+        m.contradictions_found = len(state.contradictions_found & required_ids)
+
+        m.correct_presentations = len(state.contradictions_found)
+        m.wrong_presentations = state.penalties
+        total_presentations = m.correct_presentations + m.wrong_presentations
+        m.contradiction_accuracy = (
+            m.correct_presentations / total_presentations if total_presentations > 0 else 0.0
+        )
+
+        total_stmts = set()
+        for rnd in self.case.court.rounds:
+            for t in rnd.testimonies:
+                for s in t.statements:
+                    total_stmts.add(s.id)
+        m.total_statements = len(total_stmts)
+        m.statements_pressed = len(state.statements_pressed)
+        m.press_coverage = (
+            m.statements_pressed / m.total_statements if m.total_statements > 0 else 0.0
+        )
+
+        m.evidence_available = len(self.case.evidence)
+        m.evidence_collected = len(state.inventory)
+        m.evidence_coverage = (
+            m.evidence_collected / m.evidence_available if m.evidence_available > 0 else 0.0
+        )
+
+        if self.case.investigation_gate:
+            req = set(self.case.investigation_gate.required_evidence)
+            m.required_evidence_total = len(req)
+            m.required_evidence_collected = len(state.inventory & req)
+
+        m.total_steps = state.step_count
+        from turnabout.core.state import GamePhase
+        m.investigation_steps = sum(
+            1 for a in state.action_history if a.phase == GamePhase.INVESTIGATION
+        )
+        m.court_steps = m.total_steps - m.investigation_steps
+
+        m.composite_score = (
+            0.4 * (1.0 if m.won else 0.0)
+            + 0.2 * m.contradiction_accuracy
+            + 0.2 * m.step_efficiency
+            + 0.1 * m.evidence_coverage
+            + 0.1 * m.press_coverage
+        )
+
+        return m

turnabout/core/state.py

@@ -0,0 +1,73 @@
+"""Game phase definitions and mutable game state."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class GamePhase(Enum):
+    INVESTIGATION = "investigation"
+    COURT_TESTIMONY = "court_testimony"
+    COURT_CROSS_EXAM = "court_cross_examination"
+    COURT_PENALTY = "court_penalty"
+    COURT_OBJECTION = "court_objection"
+    VERDICT_WIN = "verdict_win"
+    VERDICT_LOSE = "verdict_lose"
+
+
+@dataclass
+class ActionRecord:
+    step: int
+    phase: GamePhase
+    action_type: str
+    target_id: str | None = None
+    secondary_id: str | None = None
+    result: str = ""
+
+
+@dataclass
+class GameState:
+    phase: GamePhase
+    # Investigation
+    current_location_id: str | None = None
+    inventory: set[str] = field(default_factory=set)
+    examined: set[str] = field(default_factory=set)
+    dialogue_lines_seen: set[str] = field(default_factory=set)
+    evidence_presented_to: set[tuple[str, str]] = field(default_factory=set)
+    unlocked_locations: set[str] = field(default_factory=set)
+    # Court
+    current_round_index: int = 0
+    current_testimony_id: str | None = None
+    current_statement_index: int = 0
+    penalties: int = 0
+    contradictions_found: set[str] = field(default_factory=set)
+    statements_pressed: set[str] = field(default_factory=set)
+    revealed_statements: set[str] = field(default_factory=set)
+    # Tracking
+    action_history: list[ActionRecord] = field(default_factory=list)
+    step_count: int = 0
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.phase in (GamePhase.VERDICT_WIN, GamePhase.VERDICT_LOSE)
+
+    def copy(self) -> GameState:
+        return GameState(
+            phase=self.phase,
+            current_location_id=self.current_location_id,
+            inventory=set(self.inventory),
+            examined=set(self.examined),
+            dialogue_lines_seen=set(self.dialogue_lines_seen),
+            evidence_presented_to=set(self.evidence_presented_to),
+            unlocked_locations=set(self.unlocked_locations),
+            current_round_index=self.current_round_index,
+            current_testimony_id=self.current_testimony_id,
+            current_statement_index=self.current_statement_index,
+            penalties=self.penalties,
+            contradictions_found=set(self.contradictions_found),
+            statements_pressed=set(self.statements_pressed),
+            revealed_statements=set(self.revealed_statements),
+            action_history=list(self.action_history),
+            step_count=self.step_count,
+        )

turnabout/envs/__init__.py

@@ -0,0 +1,15 @@
+"""Environment registration for Gymnasium."""
+
+from gymnasium.envs.registration import register
+
+register(
+    id="Turnabout-Text-v0",
+    entry_point="turnabout.envs.gym_env:TurnaboutEnv",
+    kwargs={"mode": "text"},
+)
+
+register(
+    id="Turnabout-Discrete-v0",
+    entry_point="turnabout.envs.gym_env:TurnaboutEnv",
+    kwargs={"mode": "discrete"},
+)

turnabout/envs/gym_env.py

@@ -0,0 +1,181 @@
+"""Gymnasium-compatible environment wrapper."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Literal
+
+import gymnasium as gym
+import numpy as np
+from gymnasium import spaces
+
+from turnabout.core.actions import ActionParser, DiscreteActionEncoder
+from turnabout.core.engine import TurnaboutEngine
+from turnabout.core.schema import CaseData
+from turnabout.core.scoring import MetricsComputer
+from turnabout.core.state import GamePhase
+from turnabout.envs.renderer import Renderer
+
+
+class TurnaboutEnv(gym.Env):
+    """Gymnasium environment for Turnabout.
+
+    Supports two modes:
+    - "text": observation and action spaces are Text
+    - "discrete": observation is Dict, action is Discrete with masking
+    """
+
+    metadata = {"render_modes": ["human", "ansi"]}
+
+    def __init__(
+        self,
+        case_path: str | None = None,
+        case_data: dict | None = None,
+        difficulty: str | None = None,
+        mode: Literal["text", "discrete"] = "discrete",
+        render_mode: str | None = None,
+        reward_config: dict | None = None,
+        max_steps: int = 200,
+    ):
+        super().__init__()
+        self.render_mode = render_mode
+        self.mode = mode
+        self.max_steps = max_steps
+
+        if case_path:
+            with open(case_path) as f:
+                case_data = json.load(f)
+        if case_data is None:
+            raise ValueError("Must provide case_path or case_data")
+
+        self.case = CaseData(**case_data) if isinstance(case_data, dict) else case_data
+        self.engine = TurnaboutEngine(self.case, difficulty=difficulty, rewards=reward_config)
+        self.renderer = Renderer(self.case)
+        self.parser = ActionParser(self.case)
+        self.metrics_computer: MetricsComputer | None = None
+        self._step_count = 0
+
+        if mode == "text":
+            self.observation_space = spaces.Text(max_length=8192)
+            self.action_space = spaces.Text(max_length=256)
+        else:
+            self.action_encoder = DiscreteActionEncoder(self.case)
+            n_evidence = len(self.case.evidence)
+            n_phases = len(GamePhase)
+            n_locations = len(self.case.locations) + 1
+
+            total_stmts = 0
+            for rnd in self.case.court.rounds:
+                for t in rnd.testimonies:
+                    total_stmts += len(t.statements)
+
+            self.observation_space = spaces.Dict({
+                "phase": spaces.Discrete(n_phases),
+                "location": spaces.Discrete(n_locations),
+                "evidence_held": spaces.MultiBinary(n_evidence),
+                "current_statement": spaces.Discrete(max(total_stmts, 1) + 1),
+                "penalties": spaces.Discrete(self.case.court.penalty_limit + 1),
+                "contradictions_found": spaces.MultiBinary(
+                    len(self.case.court.win_condition.required_contradiction_ids)
+                ),
+                "text_obs": spaces.Text(max_length=2048),
+            })
+            self.action_space = spaces.Discrete(self.action_encoder.n_actions)
+
+        self._phase_to_int = {p: i for i, p in enumerate(GamePhase)}
+        self._location_to_int = {loc.id: i for i, loc in enumerate(self.case.locations)}
+        self._evidence_ids = [e.id for e in self.case.evidence]
+        self._required_ids = list(self.case.court.win_condition.required_contradiction_ids)
+
+    def reset(self, seed=None, options=None) -> tuple[Any, dict]:
+        super().reset(seed=seed)
+        state, obs_text = self.engine.reset()
+        self._step_count = 0
+        self.metrics_computer = MetricsComputer(self.engine)
+
+        full_obs = self.renderer.render(state, obs_text)
+
+        if self.mode == "text":
+            return full_obs, self._make_info(state)
+        return self._make_discrete_obs(state, full_obs), self._make_info(state)
+
+    def step(self, action) -> tuple[Any, float, bool, bool, dict]:
+        if self.mode == "text":
+            parsed = self.parser.parse(action)
+            if parsed is None:
+                obs_text = f"Invalid action: {action}"
+                reward = -0.05
+                state = self.engine.state
+                done = False
+            else:
+                state, obs_text, reward, done, _ = self.engine.step(parsed)
+        else:
+            parsed = self.action_encoder.decode(action)
+            state, obs_text, reward, done, _ = self.engine.step(parsed)
+
+        self._step_count += 1
+        self.metrics_computer.accumulate_reward(reward)
+
+        truncated = False
+        if self._step_count >= self.max_steps and not done:
+            truncated = True
+
+        full_obs = self.renderer.render(state, obs_text)
+
+        if self.mode == "text":
+            obs = full_obs
+        else:
+            obs = self._make_discrete_obs(state, full_obs)
+
+        return obs, reward, done, truncated, self._make_info(state)
+
+    def action_masks(self) -> np.ndarray:
+        if self.mode != "discrete":
+            raise ValueError("action_masks() only available in discrete mode")
+        valid = self.engine.get_valid_actions()
+        return self.action_encoder.get_action_mask(valid)
+
+    def render(self) -> str | None:
+        if self.engine.state is None:
+            return None
+        text = self.renderer.render(self.engine.state)
+        if self.render_mode == "human":
+            print(text)
+            return None
+        return text
+
+    def close(self) -> None:
+        pass
+
+    def _make_discrete_obs(self, state, text_obs: str) -> dict:
+        phase_int = self._phase_to_int.get(state.phase, 0)
+        loc_int = self._location_to_int.get(state.current_location_id, len(self.case.locations))
+        evidence_held = np.array(
+            [1 if eid in state.inventory else 0 for eid in self._evidence_ids],
+            dtype=np.int8,
+        )
+        contradictions = np.array(
+            [1 if sid in state.contradictions_found else 0 for sid in self._required_ids],
+            dtype=np.int8,
+        )
+        return {
+            "phase": phase_int,
+            "location": loc_int,
+            "evidence_held": evidence_held,
+            "current_statement": state.current_statement_index,
+            "penalties": state.penalties,
+            "contradictions_found": contradictions,
+            "text_obs": text_obs[:2048],
+        }
+
+    def _make_info(self, state) -> dict:
+        info = {
+            "phase": state.phase.value,
+            "penalties": state.penalties,
+            "step": self._step_count,
+            "evidence_held": sorted(state.inventory),
+        }
+        if self.mode == "discrete":
+            info["action_mask"] = self.action_masks()
+        return info

turnabout/envs/renderer.py

@@ -0,0 +1,141 @@
+"""Render game state into human-readable text observations."""
+
+from __future__ import annotations
+
+from turnabout.core.actions import Action, ActionType
+from turnabout.core.schema import CaseData
+from turnabout.core.state import GamePhase, GameState
+from turnabout.i18n import t
+
+
+class Renderer:
+    def __init__(self, case: CaseData, verbose: bool = True, lang: str = "en"):
+        self.case = case
+        self.verbose = verbose
+        self.lang = lang
+
+    def render(self, state: GameState, action_result: str = "") -> str:
+        parts = []
+        if action_result:
+            parts.append(action_result)
+
+        if state.phase == GamePhase.INVESTIGATION:
+            parts.append(self._render_investigation(state))
+        elif state.phase in (GamePhase.COURT_TESTIMONY, GamePhase.COURT_CROSS_EXAM):
+            parts.append(self._render_court(state))
+        elif state.phase == GamePhase.VERDICT_WIN:
+            parts.append(t("not_guilty_short", self.lang))
+        elif state.phase == GamePhase.VERDICT_LOSE:
+            parts.append(t("guilty_short", self.lang))
+
+        if self.verbose:
+            parts.append(self._render_evidence_list(state))
+
+        return "\n\n".join(p for p in parts if p)
+
+    def _render_investigation(self, state: GameState) -> str:
+        loc = self.case.get_location(state.current_location_id)
+        if not loc:
+            return t("investigation_header", self.lang)
+
+        lines = [t("investigation_header", self.lang), t("location_label", self.lang).format(name=loc.name), loc.description]
+
+        people = []
+        for cid in loc.characters_present:
+            ch = self.case.get_character(cid)
+            if ch:
+                people.append(f"{ch.name} ({ch.role})")
+        if people:
+            lines.append("\n" + t("people_here", self.lang).format(names=', '.join(people)))
+
+        if loc.examinables:
+            names = [ex.name for ex in loc.examinables]
+            lines.append(t("examine_label", self.lang).format(names=', '.join(names)))
+
+        connected = []
+        for cid in loc.connected_to:
+            if cid in state.unlocked_locations:
+                c = self.case.get_location(cid)
+                if c:
+                    connected.append(c.name)
+        if connected:
+            lines.append(t("travel_to", self.lang).format(names=', '.join(connected)))
+
+        return "\n".join(lines)
+
+    def _render_court(self, state: GameState) -> str:
+        testimony = self.case.get_testimony(state.current_testimony_id)
+        if not testimony:
+            return t("court_header", self.lang)
+
+        witness = self.case.get_character(testimony.witness_id)
+        header = t("testimony_header", self.lang) if state.phase == GamePhase.COURT_TESTIMONY else t("cross_exam_header", self.lang)
+        lines = [
+            header,
+            t("witness_label", self.lang).format(name=witness.name if witness else '???'),
+            t("testimony_label", self.lang).format(title=testimony.title),
+            "",
+        ]
+
+        visible = self._visible_statements(state, testimony)
+        for i, stmt in enumerate(visible):
+            marker = ">" if i == state.current_statement_index else " "
+            lines.append(f"  {marker} {i + 1}. \"{stmt.text}\"")
+
+        lines.append("\n" + t("penalties_label", self.lang).format(cur=state.penalties, max=self.case.court.penalty_limit))
+
+        if state.phase == GamePhase.COURT_CROSS_EXAM:
+            lines.append(t("actions_hint", self.lang))
+
+        return "\n".join(lines)
+
+    def _render_evidence_list(self, state: GameState) -> str:
+        if not state.inventory:
+            return ""
+        lines = [t("evidence_header", self.lang)]
+        for i, eid in enumerate(sorted(state.inventory), 1):
+            ev = self.case.get_evidence(eid)
+            if ev:
+                desc = ev.detail if ev.detail else ev.description
+                lines.append(f"  {i}. {ev.name} - {desc}")
+        return "\n".join(lines)
+
+    def _visible_statements(self, state, testimony):
+        visible = []
+        for s in testimony.statements:
+            if s.press_reveals_statement and s.id not in state.revealed_statements:
+                if any(
+                    prev.press_reveals_statement == s.id
+                    for prev in testimony.statements
+                    if prev.id != s.id
+                ):
+                    continue
+            visible.append(s)
+        return visible
+
+    def render_valid_actions(self, valid_actions: list[Action]) -> str:
+        if not valid_actions:
+            return ""
+        lines = ["[Available Actions]"]
+        for a in valid_actions:
+            lines.append(f"  {a}")
+        return "\n".join(lines)
+
+    def render_system_prompt(self) -> str:
+        return (
+            "You are playing as a defense attorney in a courtroom game.\n\n"
+            "INVESTIGATION PHASE:\n"
+            "  move <location>    - Travel to a location\n"
+            "  examine <object>   - Examine an object or area\n"
+            "  talk <person>      - Talk to a character\n"
+            "  present <evidence> to <person> - Show evidence to someone\n"
+            "  go to court        - Proceed to court (when ready)\n\n"
+            "COURT PHASE:\n"
+            "  press              - Press the witness on the current statement\n"
+            "  present <evidence> - Present evidence that contradicts the current statement\n"
+            "  next               - Move to the next statement\n"
+            "  prev               - Move to the previous statement\n\n"
+            "Find contradictions in witness testimony by presenting the right evidence.\n"
+            "Wrong evidence = penalty from the judge. Too many penalties = you lose.\n"
+            f"\nCase: {self.case.title}\n{self.case.description}"
+        )

turnabout/envs/text_env.py

@@ -0,0 +1,105 @@
+"""Text-based environment for LLM agents. String in, string out."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Literal
+
+from turnabout.core.actions import ActionParser
+from turnabout.core.engine import TurnaboutEngine
+from turnabout.core.schema import CaseData
+from turnabout.core.scoring import EpisodeMetrics, MetricsComputer
+from turnabout.envs.renderer import Renderer
+
+
+class TextCourtEnv:
+    """Text-based environment suitable for LLM agents.
+
+    Not a Gymnasium env. Provides a simpler string-in/string-out interface.
+    """
+
+    def __init__(
+        self,
+        case_path: str | Path | None = None,
+        case_data: dict | None = None,
+        difficulty: Literal["easy", "hard"] | None = None,
+        verbose: bool = True,
+        max_steps: int = 200,
+        lang: str = "en",
+    ):
+        if case_path:
+            with open(case_path) as f:
+                case_data = json.load(f)
+        if case_data is None:
+            raise ValueError("Must provide case_path or case_data")
+
+        self.case = CaseData(**case_data) if isinstance(case_data, dict) else case_data
+        self.lang = lang
+        self.engine = TurnaboutEngine(self.case, difficulty=difficulty, lang=lang)
+        self.parser = ActionParser(self.case)
+        self.renderer = Renderer(self.case, verbose=verbose, lang=lang)
+        self.metrics_computer = MetricsComputer(self.engine)
+        self.max_steps = max_steps
+        self._step_count = 0
+
+    def reset(self) -> str:
+        state, engine_obs = self.engine.reset()
+        self._step_count = 0
+        self.metrics_computer = MetricsComputer(self.engine)
+        return self.renderer.render(state, engine_obs)
+
+    def step(self, action_text: str) -> tuple[str, float, bool, dict]:
+        """Process a text action.
+
+        Returns:
+            observation: Text observation after the action
+            reward: Numerical reward
+            done: Whether the episode is over
+            info: Dict with valid_actions, phase, penalties, parse_error, etc.
+        """
+        action = self.parser.parse(action_text)
+        if action is None:
+            valid = self.engine.get_valid_actions()
+            valid_text = [str(a) for a in valid]
+            obs = (
+                f"Could not parse action: '{action_text}'\n\n"
+                f"Available commands:\n" +
+                "\n".join(f"  {v}" for v in valid_text)
+            )
+            return obs, -0.05, False, {
+                "valid_actions": valid_text,
+                "phase": self.engine.state.phase.value,
+                "parse_error": action_text,
+            }
+
+        state, engine_obs, reward, done, info = self.engine.step(action)
+        self._step_count += 1
+        self.metrics_computer.accumulate_reward(reward)
+
+        if self._step_count >= self.max_steps and not done:
+            done = True
+            engine_obs += "\n\n[Time limit reached. Case dismissed.]"
+
+        obs = self.renderer.render(state, engine_obs)
+        valid = self.engine.get_valid_actions()
+
+        info.update({
+            "valid_actions": [str(a) for a in valid],
+            "phase": state.phase.value,
+            "penalties": state.penalties,
+            "evidence_held": sorted(state.inventory),
+            "step": self._step_count,
+        })
+
+        return obs, reward, done, info
+
+    def get_metrics(self) -> EpisodeMetrics:
+        return self.metrics_computer.compute(self.engine.state)
+
+    @property
+    def system_prompt(self) -> str:
+        return self.renderer.render_system_prompt()
+
+    def render(self) -> str:
+        return self.renderer.render(self.engine.state)

turnabout/generation/__init__.py

@@ -0,0 +1,5 @@
+"""Case generation pipeline for Turnabout."""
+
+from turnabout.generation.validator import CaseValidator, ValidationReport
+
+__all__ = ["CaseValidator", "ValidationReport"]

turnabout/generation/generator.py

@@ -0,0 +1,386 @@
+"""Multi-step LLM case generator with validation and retry logic.
+
+Supports both Anthropic SDK and OpenAI-compatible APIs (e.g. custom
+gateways). The module is importable without either SDK installed; a
+missing SDK only raises an error when ``generate()`` is actually called.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+from typing import Any, Literal
+
+from turnabout.core.schema import CaseData
+from turnabout.generation.prompts import (
+    CHARACTERS_EVIDENCE_PROMPT,
+    INVESTIGATION_PROMPT,
+    NARRATIVE_PROMPT,
+    TESTIMONY_PROMPT,
+)
+from turnabout.generation.validator import CaseValidator, ValidationReport
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_MODEL = "claude-sonnet-4-6"
+_MAX_RETRIES = 3
+
+
+def _extract_json(text: str) -> dict[str, Any]:
+    """Extract JSON from LLM response text."""
+    match = re.search(r"```(?:json)?\s*\n?(.*?)```", text, re.DOTALL)
+    if match:
+        return json.loads(match.group(1).strip())
+    start = text.find("{")
+    end = text.rfind("}")
+    if start != -1 and end != -1 and end > start:
+        return json.loads(text[start : end + 1])
+    raise ValueError("No valid JSON found in LLM response")
+
+
+class CaseGenerator:
+    """Generates Ace Attorney case data via multi-step LLM pipeline."""
+
+    def __init__(
+        self,
+        llm_client: Any | None = None,
+        model: str | None = None,
+        backend: Literal["anthropic", "openai"] | None = None,
+        base_url: str | None = None,
+        api_key: str | None = None,
+    ):
+        """Initialize the generator.
+
+        Parameters
+        ----------
+        llm_client:
+            A pre-built client (Anthropic or OpenAI). If provided,
+            backend/base_url/api_key are ignored.
+        model:
+            Model identifier. Defaults based on backend or env vars.
+        backend:
+            "anthropic" or "openai". Auto-detected from env vars if None.
+        base_url:
+            Custom API base URL (for OpenAI-compatible gateways).
+            Falls back to GATEWAY_URL env var.
+        api_key:
+            API key. Falls back to GATEWAY_API_KEY or standard env vars.
+        """
+        self._client = llm_client
+        self._validator = CaseValidator()
+
+        if llm_client is not None:
+            self._backend = backend or "anthropic"
+            self._model = model or _DEFAULT_MODEL
+            return
+
+        gateway_url = base_url or os.environ.get("GATEWAY_URL")
+        gateway_key = api_key or os.environ.get("GATEWAY_API_KEY")
+        gateway_model = os.environ.get("GATEWAY_MODELS")
+
+        if backend == "openai" or (backend is None and gateway_url):
+            self._backend = "openai"
+            self._base_url = gateway_url
+            self._api_key = gateway_key
+            self._model = model or gateway_model or "gpt-4"
+        else:
+            self._backend = "anthropic"
+            self._base_url = None
+            self._api_key = None
+            self._model = model or _DEFAULT_MODEL
+
+    def _get_client(self) -> Any:
+        if self._client is not None:
+            return self._client
+
+        if self._backend == "openai":
+            try:
+                from openai import OpenAI
+            except ImportError as exc:
+                raise ImportError(
+                    "The 'openai' package is required for OpenAI-compatible "
+                    "gateway. Install with: pip install openai"
+                ) from exc
+            kwargs: dict[str, Any] = {}
+            if self._base_url:
+                kwargs["base_url"] = self._base_url
+            if self._api_key:
+                kwargs["api_key"] = self._api_key
+            self._client = OpenAI(**kwargs)
+        else:
+            try:
+                import anthropic
+            except ImportError as exc:
+                raise ImportError(
+                    "The 'anthropic' package is required. "
+                    "Install with: pip install anthropic"
+                ) from exc
+            self._client = anthropic.Anthropic()
+        return self._client
+
+    def _call_llm(self, prompt: str) -> str:
+        client = self._get_client()
+        if self._backend == "openai":
+            response = client.chat.completions.create(
+                model=self._model,
+                max_tokens=8192,
+                messages=[{"role": "user", "content": prompt}],
+                temperature=0.7,
+            )
+            return response.choices[0].message.content
+        else:
+            message = client.messages.create(
+                model=self._model,
+                max_tokens=8192,
+                messages=[{"role": "user", "content": prompt}],
+            )
+            return message.content[0].text
+
+    def _call_llm_json(self, prompt: str) -> dict[str, Any]:
+        text = self._call_llm(prompt)
+        return _extract_json(text)
+
+    async def generate(
+        self,
+        theme: str | None = None,
+        difficulty: str = "easy",
+    ) -> CaseData:
+        """Full generation pipeline with validation and retries.
+
+        Steps:
+        1. Generate crime narrative
+        2. Generate characters and evidence
+        3. Generate testimonies with contradictions
+        4. Generate investigation phase (hard mode only)
+        5. Assemble and validate CaseData
+
+        Each step is validated before proceeding. If validation fails,
+        the step is retried up to ``_MAX_RETRIES`` times.
+
+        Parameters
+        ----------
+        theme:
+            Optional theme hint (e.g. "corporate espionage", "art heist").
+            A random theme is chosen if *None*.
+        difficulty:
+            "easy" (court only) or "hard" (investigation + court).
+
+        Returns
+        -------
+        CaseData
+            A validated case ready for use in the engine.
+        """
+        if difficulty not in ("easy", "hard"):
+            raise ValueError(f"difficulty must be 'easy' or 'hard', got '{difficulty}'")
+
+        theme = theme or "a mysterious crime"
+
+        # Step 1: Narrative
+        logger.info("Step 1: Generating narrative...")
+        narrative = await self._step_with_retry(
+            "narrative",
+            lambda: self._generate_narrative(theme, difficulty),
+        )
+
+        # Step 2: Characters & evidence
+        logger.info("Step 2: Generating characters and evidence...")
+        chars_evidence = await self._step_with_retry(
+            "characters_evidence",
+            lambda: self._generate_characters_evidence(narrative, difficulty),
+        )
+
+        # Step 3: Testimonies
+        logger.info("Step 3: Generating testimonies...")
+        court = await self._step_with_retry(
+            "testimonies",
+            lambda: self._generate_testimonies(
+                narrative, chars_evidence, difficulty
+            ),
+        )
+
+        # Step 4: Investigation (hard mode)
+        investigation = None
+        if difficulty == "hard":
+            logger.info("Step 4: Generating investigation phase...")
+            investigation = await self._step_with_retry(
+                "investigation",
+                lambda: self._generate_investigation(
+                    narrative, chars_evidence
+                ),
+            )
+
+        # Step 5: Assemble
+        logger.info("Assembling final case...")
+        case = self._assemble_case(
+            narrative, chars_evidence, court, investigation, difficulty
+        )
+
+        # Final validation
+        report = self._validator.validate(case)
+        if not report.is_valid:
+            logger.warning(
+                "Final case has validation errors: %s", report.errors
+            )
+            raise ValueError(
+                f"Generated case failed validation: {report.errors}"
+            )
+
+        if report.warnings:
+            logger.info("Validation warnings: %s", report.warnings)
+
+        return case
+
+    async def _step_with_retry(
+        self,
+        step_name: str,
+        fn: Any,
+    ) -> dict[str, Any]:
+        """Execute a generation step with retry on failure."""
+        last_error: Exception | None = None
+        for attempt in range(1, _MAX_RETRIES + 1):
+            try:
+                result = fn()
+                logger.info(
+                    "Step '%s' succeeded on attempt %d", step_name, attempt
+                )
+                return result
+            except Exception as exc:
+                last_error = exc
+                logger.warning(
+                    "Step '%s' attempt %d failed: %s",
+                    step_name,
+                    attempt,
+                    exc,
+                )
+        raise RuntimeError(
+            f"Step '{step_name}' failed after {_MAX_RETRIES} attempts: "
+            f"{last_error}"
+        )
+
+    # ------------------------------------------------------------------
+    # Individual generation steps
+    # ------------------------------------------------------------------
+
+    def _generate_narrative(
+        self, theme: str, difficulty: str
+    ) -> dict[str, Any]:
+        prompt = NARRATIVE_PROMPT.format(theme=theme, difficulty=difficulty)
+        result = self._call_llm_json(prompt)
+
+        # Basic structural validation
+        required = {"title", "description", "defendant", "true_culprit", "witnesses"}
+        missing = required - set(result.keys())
+        if missing:
+            raise ValueError(f"Narrative missing required fields: {missing}")
+        return result
+
+    def _generate_characters_evidence(
+        self, narrative: dict[str, Any], difficulty: str
+    ) -> dict[str, Any]:
+        prompt = CHARACTERS_EVIDENCE_PROMPT.format(
+            narrative_json=json.dumps(narrative, indent=2),
+            difficulty=difficulty,
+        )
+        result = self._call_llm_json(prompt)
+
+        if "characters" not in result or "evidence" not in result:
+            raise ValueError("Response missing 'characters' or 'evidence'")
+        if not isinstance(result["characters"], list) or len(result["characters"]) < 2:
+            raise ValueError("Must have at least 2 characters")
+        if not isinstance(result["evidence"], list) or len(result["evidence"]) < 2:
+            raise ValueError("Must have at least 2 evidence items")
+
+        # Validate roles
+        roles = {c.get("role") for c in result["characters"]}
+        if "defendant" not in roles:
+            raise ValueError("No defendant character found")
+        if "witness" not in roles:
+            raise ValueError("No witness character found")
+
+        return result
+
+    def _generate_testimonies(
+        self,
+        narrative: dict[str, Any],
+        chars_evidence: dict[str, Any],
+        difficulty: str,
+    ) -> dict[str, Any]:
+        prompt = TESTIMONY_PROMPT.format(
+            narrative_json=json.dumps(narrative, indent=2),
+            characters_json=json.dumps(chars_evidence["characters"], indent=2),
+            evidence_json=json.dumps(chars_evidence["evidence"], indent=2),
+            difficulty=difficulty,
+        )
+        result = self._call_llm_json(prompt)
+
+        if "court" not in result:
+            raise ValueError("Response missing 'court'")
+        court = result["court"]
+        if "rounds" not in court or not court["rounds"]:
+            raise ValueError("Court must have at least one round")
+        if "win_condition" not in court:
+            raise ValueError("Court must have a win_condition")
+
+        return result
+
+    def _generate_investigation(
+        self,
+        narrative: dict[str, Any],
+        chars_evidence: dict[str, Any],
+    ) -> dict[str, Any]:
+        prompt = INVESTIGATION_PROMPT.format(
+            narrative_json=json.dumps(narrative, indent=2),
+            characters_json=json.dumps(chars_evidence["characters"], indent=2),
+            evidence_json=json.dumps(chars_evidence["evidence"], indent=2),
+        )
+        result = self._call_llm_json(prompt)
+
+        if "locations" not in result:
+            raise ValueError("Response missing 'locations'")
+        if not result["locations"]:
+            raise ValueError("Must have at least one location")
+
+        return result
+
+    # ------------------------------------------------------------------
+    # Assembly
+    # ------------------------------------------------------------------
+
+    def _assemble_case(
+        self,
+        narrative: dict[str, Any],
+        chars_evidence: dict[str, Any],
+        court: dict[str, Any],
+        investigation: dict[str, Any] | None,
+        difficulty: str,
+    ) -> CaseData:
+        """Combine all generation outputs into a single CaseData."""
+        # Build a slug-style ID from the title
+        title = narrative.get("title", "Untitled Case")
+        case_id = re.sub(r"[^a-z0-9]+", "_", title.lower()).strip("_")
+
+        case_dict: dict[str, Any] = {
+            "id": case_id,
+            "title": title,
+            "difficulty": difficulty,
+            "description": narrative.get("description", ""),
+            "metadata": {
+                "author": "llm_generated",
+                "version": "1.0",
+                "tags": [narrative.get("crime_type", "crime")],
+            },
+            "characters": chars_evidence["characters"],
+            "evidence": chars_evidence["evidence"],
+            "court": court["court"],
+        }
+
+        if investigation:
+            case_dict["locations"] = investigation.get("locations", [])
+            case_dict["dialogues"] = investigation.get("dialogues", [])
+            case_dict["investigation_gate"] = investigation.get(
+                "investigation_gate"
+            )
+
+        return CaseData(**case_dict)

turnabout/generation/prompts.py

@@ -0,0 +1,315 @@
+"""Prompt templates for multi-step LLM case generation.
+
+Each prompt targets a specific generation step and includes structure
+requirements plus the expected JSON output schema.
+"""
+
+from __future__ import annotations
+
+# ------------------------------------------------------------------
+# Step 1: Narrative generation
+# ------------------------------------------------------------------
+
+NARRATIVE_PROMPT = """\
+You are a writer for an Ace Attorney-style courtroom drama game. Generate a \
+compelling crime narrative for a case.
+
+Theme: {theme}
+Difficulty: {difficulty}
+
+Requirements:
+- A clear crime (theft, fraud, assault, arson, etc. — NOT murder if possible for variety)
+- A wrongly accused defendant
+- The true culprit who framed the defendant
+- 1-2 key witnesses
+- 2-3 pieces of evidence that contradict witness testimony
+- A logical chain of deductions leading to the truth
+- If difficulty is "hard", include an investigation phase with multiple locations
+
+Output ONLY valid JSON with this structure:
+{{
+  "title": "The Case Title",
+  "description": "2-3 sentence case overview for the player",
+  "crime_type": "theft|fraud|assault|arson|other",
+  "crime_summary": "Detailed description of what actually happened",
+  "defendant": {{
+    "name": "Full Name",
+    "description": "Character description",
+    "why_accused": "Why they appear guilty"
+  }},
+  "true_culprit": {{
+    "name": "Full Name",
+    "description": "Character description",
+    "motive": "Why they did it",
+    "method": "How they did it and framed the defendant"
+  }},
+  "witnesses": [
+    {{
+      "name": "Full Name",
+      "description": "Character description",
+      "role_in_case": "What they saw or claim to have seen",
+      "lie_or_mistake": "What they get wrong in testimony (and why)"
+    }}
+  ],
+  "key_evidence_concepts": [
+    {{
+      "name": "Evidence Name",
+      "description": "What this evidence is",
+      "why_important": "How it helps prove the truth"
+    }}
+  ],
+  "locations": [
+    {{
+      "name": "Location Name",
+      "description": "Location description",
+      "what_can_be_found": "Evidence or clues available here"
+    }}
+  ]
+}}
+"""
+
+# ------------------------------------------------------------------
+# Step 2: Characters and evidence generation
+# ------------------------------------------------------------------
+
+CHARACTERS_EVIDENCE_PROMPT = """\
+You are building an Ace Attorney-style case. Given the narrative below, \
+generate the full characters and evidence lists.
+
+NARRATIVE:
+{narrative_json}
+
+DIFFICULTY: {difficulty}
+
+Requirements for characters:
+- Each character needs: id (snake_case), name, description, role
+- Roles: "defendant", "witness", "npc", "prosecutor", "judge"
+- Must include exactly one defendant and at least one witness
+- Include a judge character
+
+Requirements for evidence:
+- Each evidence needs: id (snake_case), name, item_type, description, detail, source
+- item_type: "document" | "physical" | "photo" | "testimony_record"
+- source: "pre_given" (player starts with it) | "investigation" (must be found)
+- pre_given evidence: set acquisition to null
+- investigation evidence: must have acquisition with:
+  - method: "examine" | "talk" | "present"
+  - location_id: where to find it (snake_case)
+  - target_id: what to examine or who to talk to (snake_case)
+  - prerequisites: list of evidence IDs needed first (can be empty)
+  - present_evidence_id: if method is "present", which evidence to show (else null)
+- At least 2 pieces of pre_given evidence
+- Each investigation evidence must be obtainable (no impossible prerequisites)
+
+Output ONLY valid JSON with this structure:
+{{
+  "characters": [
+    {{
+      "id": "character_id",
+      "name": "Full Name",
+      "description": "Description",
+      "role": "defendant|witness|npc|prosecutor|judge"
+    }}
+  ],
+  "evidence": [
+    {{
+      "id": "evidence_id",
+      "name": "Evidence Name",
+      "item_type": "document|physical|photo|testimony_record",
+      "description": "Short description shown in court record",
+      "detail": "Detailed text revealed when examining the evidence",
+      "source": "pre_given|investigation",
+      "acquisition": null | {{
+        "method": "examine|talk|present",
+        "location_id": "location_id",
+        "target_id": "target_id",
+        "prerequisites": [],
+        "present_evidence_id": null | "evidence_id"
+      }}
+    }}
+  ]
+}}
+"""
+
+# ------------------------------------------------------------------
+# Step 3: Testimony and contradiction generation
+# ------------------------------------------------------------------
+
+TESTIMONY_PROMPT = """\
+You are building an Ace Attorney-style case. Given the narrative and evidence \
+below, generate witness testimonies with contradictions.
+
+NARRATIVE:
+{narrative_json}
+
+CHARACTERS:
+{characters_json}
+
+EVIDENCE:
+{evidence_json}
+
+DIFFICULTY: {difficulty}
+
+Requirements for testimonies:
+- Each CourtRound has one witness and multiple testimonies
+- The initial testimony is what the witness first says
+- Contradictions in the initial testimony trigger new testimonies
+- Each testimony has 3-5 statements
+
+Requirements for statements:
+- id: unique snake_case identifier
+- text: what the witness says
+- press_response: what they say when pressed (HOLD IT!)
+- press_reveals_statement: optional statement ID revealed by pressing
+- press_grants_evidence: optional evidence ID obtained by pressing
+- contradiction: null OR {{evidence_id, explanation, is_primary, triggers_testimony}}
+
+Requirements for contradictions:
+- evidence_id must match an existing evidence item
+- explanation: dramatic OBJECTION text explaining why the evidence contradicts
+- is_primary: true if this is a required contradiction for winning
+- triggers_testimony: testimony ID of the next testimony (or null if final)
+
+Requirements for win_condition:
+- required_contradiction_ids: list of statement IDs the player MUST contradict
+- final_evidence_id: the most important evidence (optional)
+
+The testimony chain must be logically solvable. The player needs to find \
+contradictions using the provided evidence.
+
+Output ONLY valid JSON with this structure:
+{{
+  "court": {{
+    "penalty_limit": 5,
+    "rounds": [
+      {{
+        "witness_id": "witness_character_id",
+        "order": 0,
+        "initial_testimony_id": "testimony_id",
+        "testimonies": [
+          {{
+            "id": "testimony_id",
+            "title": "Testimony Title",
+            "witness_id": "witness_character_id",
+            "preamble": "Judge's introduction of the testimony",
+            "statements": [
+              {{
+                "id": "statement_id",
+                "text": "What the witness says",
+                "press_response": "Response when pressed",
+                "press_reveals_statement": null,
+                "press_grants_evidence": null,
+                "contradiction": null | {{
+                  "evidence_id": "evidence_id",
+                  "explanation": "OBJECTION! ...",
+                  "is_primary": true,
+                  "triggers_testimony": null | "next_testimony_id"
+                }}
+              }}
+            ]
+          }}
+        ]
+      }}
+    ],
+    "win_condition": {{
+      "required_contradiction_ids": ["statement_id_1", "statement_id_2"],
+      "final_evidence_id": "evidence_id" | null
+    }}
+  }}
+}}
+"""
+
+# ------------------------------------------------------------------
+# Step 4: Investigation phase generation (hard mode)
+# ------------------------------------------------------------------
+
+INVESTIGATION_PROMPT = """\
+You are building the investigation phase of an Ace Attorney-style case. \
+Given the narrative, characters, and evidence, generate locations and dialogues.
+
+NARRATIVE:
+{narrative_json}
+
+CHARACTERS:
+{characters_json}
+
+EVIDENCE:
+{evidence_json}
+
+Requirements for locations:
+- Each location has: id (snake_case), name, description, connected_to, \
+examinables, characters_present, available_from_start, unlock_prerequisites
+- connected_to: list of other location IDs (bidirectional connections)
+- examinables: objects the player can examine at this location
+- characters_present: character IDs found here
+- available_from_start: whether the player can visit immediately
+- unlock_prerequisites: evidence IDs needed to unlock (if not available from start)
+- At least 2 locations available from start
+- All locations must be connected (reachable via connections)
+- Locked locations must have obtainable prerequisites
+
+Requirements for examinables:
+- id, name, description, examined_description (optional detailed text)
+- Must include examinables that yield investigation evidence (matching \
+  evidence acquisition target_ids)
+
+Requirements for dialogues:
+- Each dialogue tree is for one character
+- Lines: things the character says (with optional prerequisites and grants_evidence)
+- present_responses: how the character reacts when shown specific evidence
+
+Requirements for investigation_gate:
+- required_evidence: evidence IDs the player needs before going to court
+- auto_advance: false (player chooses when to go to court)
+
+Ensure all evidence acquisition target_ids and location_ids match the \
+locations and examinables you generate.
+
+Output ONLY valid JSON with this structure:
+{{
+  "locations": [
+    {{
+      "id": "location_id",
+      "name": "Location Name",
+      "description": "Location description",
+      "connected_to": ["other_location_id"],
+      "examinables": [
+        {{
+          "id": "examinable_id",
+          "name": "Object Name",
+          "description": "Brief description",
+          "examined_description": "Detailed description when examined"
+        }}
+      ],
+      "characters_present": ["character_id"],
+      "available_from_start": true,
+      "unlock_prerequisites": []
+    }}
+  ],
+  "dialogues": [
+    {{
+      "character_id": "character_id",
+      "lines": [
+        {{
+          "id": "line_id",
+          "text": "What they say",
+          "prerequisites": [],
+          "grants_evidence": null | "evidence_id"
+        }}
+      ],
+      "present_responses": [
+        {{
+          "evidence_id": "evidence_id",
+          "text": "Response when shown this evidence",
+          "grants_evidence": null | "evidence_id",
+          "unlocks_dialogue_line": null | "line_id"
+        }}
+      ]
+    }}
+  ],
+  "investigation_gate": {{
+    "required_evidence": ["evidence_id_1", "evidence_id_2"],
+    "auto_advance": false
+  }}
+}}
+"""

turnabout/generation/validator.py

@@ -0,0 +1,575 @@
+"""Case data validation with multi-level checks.
+
+Validates structural integrity, reference consistency, evidence reachability,
+contradiction validity, solvability, and deadlock detection.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+
+from turnabout.core.schema import CaseData
+
+
+@dataclass
+class ValidationReport:
+    """Result of validating a CaseData instance."""
+
+    is_valid: bool = True
+    errors: list[str] = field(default_factory=list)  # Must fix
+    warnings: list[str] = field(default_factory=list)  # Should fix
+
+    def add_error(self, msg: str) -> None:
+        self.errors.append(msg)
+        self.is_valid = False
+
+    def add_warning(self, msg: str) -> None:
+        self.warnings.append(msg)
+
+
+class CaseValidator:
+    """Validates a CaseData instance across six dimensions."""
+
+    def validate(self, case: CaseData) -> ValidationReport:
+        """Run all validations and return a consolidated report."""
+        report = ValidationReport()
+
+        for error in self._validate_references(case):
+            report.add_error(error)
+
+        for error in self._validate_contradictions(case):
+            report.add_error(error)
+
+        for error in self._validate_solvability(case):
+            report.add_error(error)
+
+        for error in self._validate_no_deadlocks(case):
+            report.add_error(error)
+
+        for error in self._validate_reachability(case):
+            report.add_error(error)
+
+        # Structural warnings (non-blocking)
+        for warning in self._validate_structure(case):
+            report.add_warning(warning)
+
+        return report
+
+    # ------------------------------------------------------------------
+    # Level 1: Reference integrity
+    # ------------------------------------------------------------------
+
+    def _validate_references(self, case: CaseData) -> list[str]:
+        """All IDs referenced must exist (evidence IDs, location IDs,
+        character IDs, statement IDs, testimony IDs, etc.)."""
+        errors: list[str] = []
+
+        char_ids = {c.id for c in case.characters}
+        ev_ids = case.get_all_evidence_ids()
+        loc_ids = {loc.id for loc in case.locations}
+        testimony_ids: set[str] = set()
+        statement_ids: set[str] = set()
+        examinable_ids: set[str] = set()
+
+        for loc in case.locations:
+            for ex in loc.examinables:
+                examinable_ids.add(ex.id)
+
+        for rnd in case.court.rounds:
+            for t in rnd.testimonies:
+                testimony_ids.add(t.id)
+                for s in t.statements:
+                    statement_ids.add(s.id)
+
+        # Location connected_to
+        for loc in case.locations:
+            for cid in loc.connected_to:
+                if cid not in loc_ids:
+                    errors.append(
+                        f"Location '{loc.id}' connects to unknown location '{cid}'"
+                    )
+
+        # Characters present in locations
+        for loc in case.locations:
+            for cid in loc.characters_present:
+                if cid not in char_ids:
+                    errors.append(
+                        f"Location '{loc.id}' references unknown character '{cid}'"
+                    )
+
+        # Evidence acquisition references
+        for ev in case.evidence:
+            if ev.acquisition:
+                acq = ev.acquisition
+                if acq.location_id and acq.location_id not in loc_ids:
+                    errors.append(
+                        f"Evidence '{ev.id}' acquisition references unknown "
+                        f"location '{acq.location_id}'"
+                    )
+                # target_id is either an examinable or a character
+                if acq.method == "examine":
+                    if acq.target_id not in examinable_ids:
+                        errors.append(
+                            f"Evidence '{ev.id}' acquisition references unknown "
+                            f"examinable '{acq.target_id}'"
+                        )
+                elif acq.method in ("talk", "present"):
+                    if acq.target_id not in char_ids:
+                        errors.append(
+                            f"Evidence '{ev.id}' acquisition references unknown "
+                            f"character '{acq.target_id}'"
+                        )
+                # present_evidence_id
+                if acq.present_evidence_id and acq.present_evidence_id not in ev_ids:
+                    errors.append(
+                        f"Evidence '{ev.id}' acquisition references unknown "
+                        f"present_evidence_id '{acq.present_evidence_id}'"
+                    )
+                # prerequisites are evidence IDs
+                for prereq in acq.prerequisites:
+                    if prereq not in ev_ids:
+                        errors.append(
+                            f"Evidence '{ev.id}' acquisition prerequisite "
+                            f"'{prereq}' is not a known evidence ID"
+                        )
+
+        # Dialogue character references
+        for dlg in case.dialogues:
+            if dlg.character_id not in char_ids:
+                errors.append(
+                    f"Dialogue references unknown character '{dlg.character_id}'"
+                )
+            for line in dlg.lines:
+                if line.grants_evidence and line.grants_evidence not in ev_ids:
+                    errors.append(
+                        f"Dialogue line '{line.id}' grants unknown evidence "
+                        f"'{line.grants_evidence}'"
+                    )
+                for prereq in line.prerequisites:
+                    if prereq not in ev_ids:
+                        errors.append(
+                            f"Dialogue line '{line.id}' prerequisite "
+                            f"'{prereq}' is not a known evidence ID"
+                        )
+            for pr in dlg.present_responses:
+                if pr.evidence_id not in ev_ids:
+                    errors.append(
+                        f"Present response references unknown evidence "
+                        f"'{pr.evidence_id}'"
+                    )
+                if pr.grants_evidence and pr.grants_evidence not in ev_ids:
+                    errors.append(
+                        f"Present response grants unknown evidence "
+                        f"'{pr.grants_evidence}'"
+                    )
+
+        # Court round references
+        for rnd in case.court.rounds:
+            if rnd.witness_id not in char_ids:
+                errors.append(
+                    f"Court round references unknown witness '{rnd.witness_id}'"
+                )
+            if rnd.initial_testimony_id not in testimony_ids:
+                errors.append(
+                    f"Court round initial_testimony_id "
+                    f"'{rnd.initial_testimony_id}' not found"
+                )
+            for t in rnd.testimonies:
+                if t.witness_id not in char_ids:
+                    errors.append(
+                        f"Testimony '{t.id}' references unknown witness "
+                        f"'{t.witness_id}'"
+                    )
+
+        # Statement press_reveals_statement
+        for rnd in case.court.rounds:
+            for t in rnd.testimonies:
+                for s in t.statements:
+                    if (
+                        s.press_reveals_statement
+                        and s.press_reveals_statement not in statement_ids
+                    ):
+                        errors.append(
+                            f"Statement '{s.id}' press_reveals_statement "
+                            f"'{s.press_reveals_statement}' not found"
+                        )
+                    if s.press_grants_evidence and s.press_grants_evidence not in ev_ids:
+                        errors.append(
+                            f"Statement '{s.id}' press_grants_evidence "
+                            f"'{s.press_grants_evidence}' not found"
+                        )
+
+        # Contradiction triggers_testimony
+        for rnd in case.court.rounds:
+            for t in rnd.testimonies:
+                for s in t.statements:
+                    if s.contradiction and s.contradiction.triggers_testimony:
+                        if s.contradiction.triggers_testimony not in testimony_ids:
+                            errors.append(
+                                f"Statement '{s.id}' contradiction "
+                                f"triggers_testimony "
+                                f"'{s.contradiction.triggers_testimony}' not found"
+                            )
+
+        # Win condition statement IDs
+        for sid in case.court.win_condition.required_contradiction_ids:
+            if sid not in statement_ids:
+                errors.append(
+                    f"Win condition references unknown statement '{sid}'"
+                )
+
+        # Win condition final_evidence_id
+        if (
+            case.court.win_condition.final_evidence_id
+            and case.court.win_condition.final_evidence_id not in ev_ids
+        ):
+            errors.append(
+                f"Win condition final_evidence_id "
+                f"'{case.court.win_condition.final_evidence_id}' not found"
+            )
+
+        # Investigation gate evidence IDs
+        if case.investigation_gate:
+            for eid in case.investigation_gate.required_evidence:
+                if eid not in ev_ids:
+                    errors.append(
+                        f"Investigation gate references unknown evidence '{eid}'"
+                    )
+
+        # Location unlock_prerequisites are evidence IDs
+        for loc in case.locations:
+            for prereq in loc.unlock_prerequisites:
+                if prereq not in ev_ids:
+                    errors.append(
+                        f"Location '{loc.id}' unlock_prerequisite "
+                        f"'{prereq}' is not a known evidence ID"
+                    )
+
+        return errors
+
+    # ------------------------------------------------------------------
+    # Level 2: Evidence reachability (BFS from initial state)
+    # ------------------------------------------------------------------
+
+    def _validate_reachability(self, case: CaseData) -> list[str]:
+        """All required evidence can be obtained via BFS from initial state.
+
+        Simulates the investigation phase: starting with pre_given evidence
+        and available_from_start locations, iteratively collect evidence and
+        unlock locations until no more progress can be made.
+        """
+        errors: list[str] = []
+
+        # If no locations defined (easy-mode only case), skip
+        if not case.locations:
+            return errors
+
+        inventory = {e.id for e in case.get_pre_given_evidence()}
+        unlocked = {loc.id for loc in case.locations if loc.available_from_start}
+
+        # Iterative fixed-point: keep collecting until nothing new
+        changed = True
+        while changed:
+            changed = False
+
+            # Try to unlock new locations
+            for loc in case.locations:
+                if loc.id not in unlocked and not loc.available_from_start:
+                    if all(p in inventory for p in loc.unlock_prerequisites):
+                        unlocked.add(loc.id)
+                        changed = True
+
+            # Try to obtain new evidence from unlocked locations
+            for ev in case.evidence:
+                if ev.id in inventory:
+                    continue
+                if ev.source == "pre_given":
+                    continue
+                if not ev.acquisition:
+                    continue
+                acq = ev.acquisition
+                if acq.location_id not in unlocked:
+                    continue
+                if not all(p in inventory for p in acq.prerequisites):
+                    continue
+                if acq.method == "present" and acq.present_evidence_id:
+                    if acq.present_evidence_id not in inventory:
+                        continue
+                # Verify that the target actually exists at the location
+                loc = case.get_location(acq.location_id)
+                if loc:
+                    if acq.method == "examine":
+                        if not any(
+                            ex.id == acq.target_id for ex in loc.examinables
+                        ):
+                            continue
+                    elif acq.method in ("talk", "present"):
+                        if acq.target_id not in loc.characters_present:
+                            continue
+                inventory.add(ev.id)
+                changed = True
+
+            # Try to obtain evidence from dialogue lines
+            for dlg in case.dialogues:
+                # Check if the character's location is unlocked
+                char_locations = [
+                    loc for loc in case.locations
+                    if dlg.character_id in loc.characters_present
+                    and loc.id in unlocked
+                ]
+                if not char_locations:
+                    continue
+                for line in dlg.lines:
+                    if line.grants_evidence and line.grants_evidence not in inventory:
+                        if all(p in inventory for p in line.prerequisites):
+                            inventory.add(line.grants_evidence)
+                            changed = True
+                # Present responses
+                for pr in dlg.present_responses:
+                    if pr.grants_evidence and pr.grants_evidence not in inventory:
+                        if pr.evidence_id in inventory:
+                            inventory.add(pr.grants_evidence)
+                            changed = True
+
+        # Check investigation gate requirements
+        if case.investigation_gate:
+            for eid in case.investigation_gate.required_evidence:
+                if eid not in inventory:
+                    errors.append(
+                        f"Required evidence '{eid}' is unreachable from "
+                        f"initial state"
+                    )
+
+        # Check that all investigation evidence is reachable
+        for ev in case.evidence:
+            if ev.source == "investigation" and ev.id not in inventory:
+                errors.append(
+                    f"Investigation evidence '{ev.id}' is unreachable from "
+                    f"initial state"
+                )
+
+        return errors
+
+    # ------------------------------------------------------------------
+    # Level 3: Contradiction validity
+    # ------------------------------------------------------------------
+
+    def _validate_contradictions(self, case: CaseData) -> list[str]:
+        """Each contradiction references existing evidence."""
+        errors: list[str] = []
+        ev_ids = case.get_all_evidence_ids()
+
+        for rnd in case.court.rounds:
+            for t in rnd.testimonies:
+                for s in t.statements:
+                    if s.contradiction:
+                        if s.contradiction.evidence_id not in ev_ids:
+                            errors.append(
+                                f"Statement '{s.id}' contradiction references "
+                                f"unknown evidence '{s.contradiction.evidence_id}'"
+                            )
+
+        return errors
+
+    # ------------------------------------------------------------------
+    # Level 4: Solvability
+    # ------------------------------------------------------------------
+
+    def _validate_solvability(self, case: CaseData) -> list[str]:
+        """Win condition statements all have contradictions defined."""
+        errors: list[str] = []
+
+        for sid in case.court.win_condition.required_contradiction_ids:
+            stmt = case.get_statement(sid)
+            if stmt is None:
+                # Already caught by reference validation
+                continue
+            if stmt.contradiction is None:
+                errors.append(
+                    f"Win condition requires contradiction on statement "
+                    f"'{sid}', but it has no contradiction defined"
+                )
+
+        # Check that contradictions leading to required testimonies are
+        # reachable (the chain of triggers_testimony must eventually reach
+        # all required statements)
+        required_ids = set(case.court.win_condition.required_contradiction_ids)
+        reachable_testimonies: set[str] = set()
+        for rnd in case.court.rounds:
+            reachable_testimonies.add(rnd.initial_testimony_id)
+
+        changed = True
+        while changed:
+            changed = False
+            for rnd in case.court.rounds:
+                for t in rnd.testimonies:
+                    if t.id not in reachable_testimonies:
+                        continue
+                    for s in t.statements:
+                        if (
+                            s.contradiction
+                            and s.contradiction.triggers_testimony
+                            and s.contradiction.triggers_testimony
+                            not in reachable_testimonies
+                        ):
+                            reachable_testimonies.add(
+                                s.contradiction.triggers_testimony
+                            )
+                            changed = True
+
+        for sid in required_ids:
+            stmt = case.get_statement(sid)
+            if stmt is None:
+                continue
+            # Find which testimony contains this statement
+            for rnd in case.court.rounds:
+                for t in rnd.testimonies:
+                    if any(s.id == sid for s in t.statements):
+                        if t.id not in reachable_testimonies:
+                            errors.append(
+                                f"Win condition statement '{sid}' is in "
+                                f"testimony '{t.id}' which is unreachable "
+                                f"(no contradiction triggers it)"
+                            )
+
+        return errors
+
+    # ------------------------------------------------------------------
+    # Level 5: Deadlock detection
+    # ------------------------------------------------------------------
+
+    def _validate_no_deadlocks(self, case: CaseData) -> list[str]:
+        """Check for unreachable locations or circular prerequisites."""
+        errors: list[str] = []
+
+        if not case.locations:
+            return errors
+
+        # Check for locations with prerequisites that can never be satisfied
+        # (circular dependency detection via topological analysis)
+        ev_ids = case.get_all_evidence_ids()
+
+        # Build a dependency graph for evidence acquisition
+        # Evidence A depends on evidence B if B is in A's prerequisites
+        # or if B is needed to unlock the location where A is found
+        depends_on: dict[str, set[str]] = {}
+        for ev in case.evidence:
+            deps: set[str] = set()
+            if ev.acquisition:
+                deps.update(ev.acquisition.prerequisites)
+                if ev.acquisition.present_evidence_id:
+                    deps.add(ev.acquisition.present_evidence_id)
+                # If location requires evidence to unlock
+                loc = case.get_location(ev.acquisition.location_id)
+                if loc and not loc.available_from_start:
+                    deps.update(loc.unlock_prerequisites)
+            depends_on[ev.id] = deps
+
+        # Check for circular dependencies using DFS
+        WHITE, GRAY, BLACK = 0, 1, 2
+        color: dict[str, int] = {eid: WHITE for eid in depends_on}
+
+        def dfs(node: str, path: list[str]) -> str | None:
+            color[node] = GRAY
+            path.append(node)
+            for dep in depends_on.get(node, set()):
+                if dep not in color:
+                    # pre_given evidence, no cycle through here
+                    continue
+                if color[dep] == GRAY:
+                    cycle_start = path.index(dep)
+                    cycle = path[cycle_start:] + [dep]
+                    return " -> ".join(cycle)
+                if color[dep] == WHITE:
+                    result = dfs(dep, path)
+                    if result:
+                        return result
+            path.pop()
+            color[node] = BLACK
+            return None
+
+        for eid in depends_on:
+            if color[eid] == WHITE:
+                cycle = dfs(eid, [])
+                if cycle:
+                    errors.append(
+                        f"Circular prerequisite dependency detected: {cycle}"
+                    )
+                    break  # One cycle report is enough
+
+        # Check location connectivity: all locations should be reachable
+        # from at least one available_from_start location
+        start_locs = {loc.id for loc in case.locations if loc.available_from_start}
+        if start_locs:
+            reachable: set[str] = set()
+            queue: deque[str] = deque(start_locs)
+            while queue:
+                lid = queue.popleft()
+                if lid in reachable:
+                    continue
+                reachable.add(lid)
+                loc = case.get_location(lid)
+                if loc:
+                    for cid in loc.connected_to:
+                        if cid not in reachable:
+                            queue.append(cid)
+
+            # Locations not reachable even via connections (ignoring prereqs)
+            for loc in case.locations:
+                if loc.id not in reachable:
+                    errors.append(
+                        f"Location '{loc.id}' is not reachable from any "
+                        f"starting location via connections"
+                    )
+
+        return errors
+
+    # ------------------------------------------------------------------
+    # Structural warnings (non-blocking)
+    # ------------------------------------------------------------------
+
+    def _validate_structure(self, case: CaseData) -> list[str]:
+        """Produce warnings for structural issues that are not hard errors."""
+        warnings: list[str] = []
+
+        # Check for defendant character
+        defendants = [c for c in case.characters if c.role == "defendant"]
+        if not defendants:
+            warnings.append("No character with role 'defendant' found")
+
+        # Check for witness characters
+        witnesses = [c for c in case.characters if c.role == "witness"]
+        if not witnesses:
+            warnings.append("No character with role 'witness' found")
+
+        # Check for at least one testimony
+        total_testimonies = sum(
+            len(rnd.testimonies) for rnd in case.court.rounds
+        )
+        if total_testimonies == 0:
+            warnings.append("No testimonies defined in court proceedings")
+
+        # Hard mode should have locations and dialogues
+        if case.difficulty == "hard":
+            if not case.locations:
+                warnings.append(
+                    "Hard difficulty case has no locations defined"
+                )
+            if not case.dialogues:
+                warnings.append(
+                    "Hard difficulty case has no dialogues defined"
+                )
+            if not case.investigation_gate:
+                warnings.append(
+                    "Hard difficulty case has no investigation gate"
+                )
+
+        # Check for empty connected_to lists (isolated locations)
+        for loc in case.locations:
+            if not loc.connected_to and len(case.locations) > 1:
+                warnings.append(
+                    f"Location '{loc.id}' has no connections to other locations"
+                )
+
+        return warnings

turnabout/i18n.py

@@ -0,0 +1,237 @@
+"""Internationalization — centralized translations for all user-facing strings."""
+
+from __future__ import annotations
+
+TRANSLATIONS: dict[str, dict[str, str]] = {
+    # ── Engine observations ──
+    "move_to": {
+        "en": "You move to {name}.\n{desc}",
+        "zh": "你前往了{name}。\n{desc}",
+    },
+    "nothing_to_examine": {
+        "en": "Nothing to examine here.",
+        "zh": "这里没有什么可以调查的。",
+    },
+    "new_evidence": {
+        "en": "\n\n[New evidence obtained: {name}]",
+        "zh": "\n\n【获得新证据：{name}】",
+    },
+    "nothing_to_say": {
+        "en": "{name} has nothing to say.",
+        "zh": "{name}无话可说。",
+    },
+    "nothing_new": {
+        "en": "(Nothing new to discuss.)",
+        "zh": "（没有新的内容可以讨论。）",
+    },
+    "nothing_to_say_now": {
+        "en": "{name} has nothing to say right now.",
+        "zh": "{name}现在没什么可说的。",
+    },
+    "no_comment": {
+        "en": "{char} examines {ev} but has no comment.",
+        "zh": "{char}查看了{ev}，但没有什么评论。",
+    },
+    "nothing_useful": {
+        "en": "{char} examines {ev} but doesn't have anything useful to say about it.",
+        "zh": "{char}查看了{ev}，但对此没有什么有用的信息。",
+    },
+    "court_in_session": {
+        "en": "=== COURT IS NOW IN SESSION ===",
+        "zh": "=== 开庭审理 ===",
+    },
+    "witness_label": {
+        "en": "Witness: {name}",
+        "zh": "证人：{name}",
+    },
+    "testimony_label": {
+        "en": 'Testimony: "{title}"',
+        "zh": "证词：「{title}」",
+    },
+    "cross_exam_header": {
+        "en": "=== CROSS-EXAMINATION ===",
+        "zh": "=== 质证 ===",
+    },
+    "press_or_present": {
+        "en": "\nYou may press the witness or present evidence.",
+        "zh": "\n你可以追问证人或出示证据。",
+    },
+    "statement_label": {
+        "en": '> Statement {num}: "{text}"',
+        "zh": '> 第{num}条证言：「{text}」',
+    },
+    "hold_it": {
+        "en": "HOLD IT!",
+        "zh": "等一下！",
+    },
+    "witness_amends": {
+        "en": '\n\nThe witness amends their testimony:\n"{text}"',
+        "zh": "\n\n证人修改了证词：\n「{text}」",
+    },
+    "objection": {
+        "en": "OBJECTION!",
+        "zh": "异议！",
+    },
+    "new_testimony": {
+        "en": "\n\n--- New Testimony ---",
+        "zh": "\n\n--- 新证词 ---",
+    },
+    "not_guilty": {
+        "en": "\n\n=== NOT GUILTY ===\nThe defendant has been found NOT GUILTY!",
+        "zh": "\n\n=== 无罪 ===\n被告被判定为无罪！",
+    },
+    "wrong_present": {
+        "en": "You present {ev} against this statement, but it doesn't prove anything.\n"
+              "Judge: That evidence is irrelevant! Penalty!\n"
+              "[Penalties: {cur}/{max}]",
+        "zh": "你针对这条证言出示了{ev}，但无法证明任何事情。\n"
+              "法官：该证据与本案无关！罚分！\n"
+              "【罚分：{cur}/{max}】",
+    },
+    "guilty": {
+        "en": "\n\n=== GUILTY ===\nThe defendant has been found GUILTY!",
+        "zh": "\n\n=== 有罪 ===\n被告被判定为有罪！",
+    },
+    "no_current_statement": {
+        "en": "No current statement.",
+        "zh": "当前没有证言。",
+    },
+    "statement_not_visible": {
+        "en": "That statement is not visible.",
+        "zh": "该证言当前不可见。",
+    },
+    "unknown_action": {
+        "en": "Unknown action.",
+        "zh": "未知操作。",
+    },
+    "during_testimony": {
+        "en": "During testimony, you can only advance.",
+        "zh": "证词陈述中，你只能继续。",
+    },
+    "invalid_action": {
+        "en": "Invalid action: {action}. Valid actions: {valid}",
+        "zh": "无效操作：{action}。可用操作：{valid}",
+    },
+
+    # ── Renderer labels ──
+    "investigation_header": {
+        "en": "=== INVESTIGATION ===",
+        "zh": "=== 调查阶段 ===",
+    },
+    "location_label": {
+        "en": "[Location] {name}",
+        "zh": "【地点】{name}",
+    },
+    "people_here": {
+        "en": "[People Here] {names}",
+        "zh": "【在场人物】{names}",
+    },
+    "examine_label": {
+        "en": "[Examine] {names}",
+        "zh": "【可调查】{names}",
+    },
+    "travel_to": {
+        "en": "[Travel To] {names}",
+        "zh": "【可前往】{names}",
+    },
+    "testimony_header": {
+        "en": "=== TESTIMONY ===",
+        "zh": "=== 证词陈述 ===",
+    },
+    "court_header": {
+        "en": "=== COURT ===",
+        "zh": "=== 法庭 ===",
+    },
+    "penalties_label": {
+        "en": "[Penalties: {cur}/{max}]",
+        "zh": "【罚分：{cur}/{max}】",
+    },
+    "actions_hint": {
+        "en": "[Actions] press | present <evidence> | next | prev",
+        "zh": "【可用操作】追问 | 出示证据 | 下一条 | 上一条",
+    },
+    "evidence_header": {
+        "en": "[Court Record - Evidence]",
+        "zh": "【法庭记录 - 证据】",
+    },
+    "not_guilty_short": {
+        "en": "\n=== NOT GUILTY ===",
+        "zh": "\n=== 无罪 ===",
+    },
+    "guilty_short": {
+        "en": "\n=== GUILTY ===",
+        "zh": "\n=== 有罪 ===",
+    },
+
+    # ── Action display names ──
+    "action_move": {"en": "Move to {name}", "zh": "前往 {name}"},
+    "action_examine": {"en": "Examine {name}", "zh": "调查 {name}"},
+    "action_talk": {"en": "Talk to {name}", "zh": "与{name}对话"},
+    "action_press": {"en": "Press (current statement)", "zh": "追问（当前证言）"},
+    "action_present_evidence": {"en": "Present {name}", "zh": "出示 {name}"},
+    "action_present_to_npc": {"en": "Show {ev} to {char}", "zh": "向{char}出示{ev}"},
+    "action_go_to_court": {"en": "Go to court", "zh": "前往法庭"},
+    "action_next": {"en": "Next statement", "zh": "下一条证言"},
+    "action_prev": {"en": "Previous statement", "zh": "上一条证言"},
+    "action_continue": {"en": "Continue", "zh": "继续"},
+
+    # ── UI labels ──
+    "ui_title": {
+        "en": "# Turnabout Bench\n*Ace Attorney-style interactive environment for agent long-horizon reasoning evaluation*",
+        "zh": "# 逆转法庭\n*逆转裁判风格的 Agent 长程推理评估交互环境*",
+    },
+    "ui_new_game": {"en": "New Game", "zh": "新游戏"},
+    "ui_execute": {"en": "Execute", "zh": "执行"},
+    "ui_case": {"en": "Case", "zh": "案件"},
+    "ui_difficulty": {"en": "Difficulty", "zh": "难度"},
+    "ui_status": {"en": "Status", "zh": "状态"},
+    "ui_evidence": {"en": "Evidence", "zh": "证据"},
+    "ui_select_action": {"en": "Select an action", "zh": "选择操作"},
+    "ui_click_new_game": {
+        "en": "Click **New Game** to start.",
+        "zh": "点击**新游戏**开始。",
+    },
+    "ui_no_game": {
+        "en": "No game in progress.",
+        "zh": "当前没有游戏进行中。",
+    },
+    "ui_no_evidence": {
+        "en": "No evidence collected yet.",
+        "zh": "尚未收集到证据。",
+    },
+    "ui_phase": {"en": "Phase", "zh": "阶段"},
+    "ui_penalties": {"en": "Penalties", "zh": "罚分"},
+    "ui_contradictions": {"en": "Contradictions", "zh": "矛盾"},
+    "ui_steps": {"en": "Steps", "zh": "步数"},
+    "ui_result": {"en": "Result", "zh": "结果"},
+    "ui_won": {"en": "WON", "zh": "胜诉"},
+    "ui_lost": {"en": "LOST", "zh": "败诉"},
+    "ui_contradiction_accuracy": {"en": "Contradiction Accuracy", "zh": "矛盾发现准确率"},
+    "ui_evidence_coverage": {"en": "Evidence Coverage", "zh": "证据覆盖率"},
+    "ui_composite_score": {"en": "Composite Score", "zh": "综合得分"},
+    "ui_game_over": {"en": "GAME OVER", "zh": "游戏结束"},
+    "ui_reward": {"en": "Reward", "zh": "奖励"},
+    "ui_play": {"en": "Play", "zh": "游玩"},
+    "ui_generate": {"en": "Generate Case", "zh": "生成案件"},
+    "ui_about": {"en": "About", "zh": "关于"},
+    "ui_language": {"en": "Language", "zh": "语言"},
+    "ui_commands_ref": {"en": "Commands Reference", "zh": "命令参考"},
+    "ui_theme": {"en": "Theme (optional)", "zh": "主题（可选）"},
+    "ui_generate_btn": {"en": "Generate Case", "zh": "生成案件"},
+    "ui_game_label": {"en": "Game", "zh": "游戏"},
+    "ui_no_cases": {"en": "No case files found.", "zh": "未找到案件文件。"},
+
+    # ── Phase display names ──
+    "phase_investigation": {"en": "Investigation", "zh": "调查"},
+    "phase_court_testimony": {"en": "Testimony", "zh": "证词陈述"},
+    "phase_court_cross_examination": {"en": "Cross-Examination", "zh": "质证"},
+    "phase_verdict_win": {"en": "Not Guilty", "zh": "无罪"},
+    "phase_verdict_lose": {"en": "Guilty", "zh": "有罪"},
+}
+
+
+def t(key: str, lang: str = "en") -> str:
+    entry = TRANSLATIONS.get(key)
+    if entry is None:
+        return key
+    return entry.get(lang, entry.get("en", key))