클래식 공개 API 정리

맥락:
- GUI 이식 전에 classic 패키지 루트에서 노출할 API 범위를 정리했다.
- Claude Opus 4.7 xhigh 자문에서 root export 축소와 backend builder 이름 단일화를 우선 권장했다.

변경:
- classic package root export를 GameState, config, env, backend, bot registry 중심으로 줄였다.
- backend factory 이름을 build_backend로 단일화하고 README 사용 예시를 갱신했다.
- public API smoke test를 추가하고 pyproject description 및 Cython build failure 처리를 정리했다.

확인:
- uv run pytest tests/games/classic
- uv run lost-cities-classic

README.md

@@ -21,4 +21,27 @@ uv run pytest tests/games/classic
 uv run lost-cities-classic
 ```
 
+## Basic Usage
+
+```python
+from coolrl_lost_cities.games.classic import GameState, build_bot, classic_config
+
+state = GameState.new_game(classic_config(seed=1))
+bot = build_bot("random", seed=1)
+
+while not state.terminal:
+    state.apply_action(bot.act(state))
+
+print(state.total_score(0), state.total_score(1))
+```
+
+Backends use the same snapshot/apply/undo interface:
+
+```python
+from coolrl_lost_cities.games.classic import build_backend, classic_config
+
+backend = build_backend("python", classic_config(), seed=1)
+snapshot = backend.snapshot()
+```
+
 See [classic port notes](docs/classic-port-notes.md) for the current direction.

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "coolrl-lost-cities"
 version = "0.1.0"
-description = "Add your description here"
+description = "Focused Lost Cities classic game extraction"
 readme = "README.md"
 authors = [
     { name = "정시원", email = "sebastianrcnt@gmail.com" }

setup.py

@@ -4,27 +4,25 @@ from setuptools import Extension, setup
 
 try:
     from Cython.Build import cythonize
-except ImportError:  # pragma: no cover
+except ImportError as exc:  # pragma: no cover
-    cythonize = None
+    raise RuntimeError("Cython is required to build coolrl-lost-cities") from exc
 
 
-extensions: list[Extension] = []
+extensions = cythonize(
-if cythonize is not None:
+    [
-    extensions = cythonize(
+        Extension(
-        [
+            "coolrl_lost_cities.games.classic.game",
-            Extension(
+            ["src/coolrl_lost_cities/games/classic/game.pyx"],
-                "coolrl_lost_cities.games.classic.game",
+        )
-                ["src/coolrl_lost_cities/games/classic/game.pyx"],
+    ],
-            )
+    language_level=3,
-        ],
+    compiler_directives={
-        language_level=3,
+        "boundscheck": False,
-        compiler_directives={
+        "wraparound": False,
-            "boundscheck": False,
+        "cdivision": True,
-            "wraparound": False,
+        "initializedcheck": False,
-            "cdivision": True,
+    },
-            "initializedcheck": False,
+)
-        },
-    )
 
 
 setup(ext_modules=extensions)

src/coolrl_lost_cities/games/classic/__init__.py

@@ -1,13 +1,37 @@
 from __future__ import annotations
 
-from .game import Card, GameState, IllegalMoveError, LostCitiesConfig, classic_config
+from .backends import build_backend
+from .bots import (
+    LostCitiesBot,
+    available_bot_names,
+    build_bot,
+    play_game,
+    run_series,
+)
+from .env import LostCitiesEnv
+from .game import (
+    GameState,
+    IllegalMoveError,
+    LostCitiesConfig,
+    classic_config,
+)
+from .interfaces import BackendName, LostCitiesBackend, Snapshot
 
 __all__ = [
-    "Card",
+    "BackendName",
     "GameState",
     "IllegalMoveError",
+    "LostCitiesBackend",
+    "LostCitiesBot",
     "LostCitiesConfig",
+    "LostCitiesEnv",
+    "Snapshot",
+    "available_bot_names",
+    "build_backend",
+    "build_bot",
     "classic_config",
+    "play_game",
+    "run_series",
 ]
 
 

src/coolrl_lost_cities/games/classic/backends/__init__.py

@@ -1,11 +1,11 @@
 from __future__ import annotations
 
-from .factory import build_lost_cities_backend
+from .factory import build_backend
 from .python import PythonLostCitiesBackend
 from .rust import RustLostCitiesBackend
 
 __all__ = [
     "PythonLostCitiesBackend",
     "RustLostCitiesBackend",
-    "build_lost_cities_backend",
+    "build_backend",
 ]

src/coolrl_lost_cities/games/classic/backends/factory.py

@@ -6,7 +6,7 @@ from .python import PythonLostCitiesBackend
 from .rust import RustLostCitiesBackend
 
 
-def build_lost_cities_backend(
+def build_backend(
     backend: BackendName,
     config: LostCitiesConfig,
     seed: int | None,

tests/games/classic/test_public_api.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import coolrl_lost_cities.games.classic as classic
+
+
+def test_classic_package_exports_common_game_api() -> None:
+    config = classic.classic_config(seed=1)
+    state = classic.GameState.new_game(config)
+    bot = classic.build_bot("random", seed=1)
+
+    action = bot.act(state)
+    assert state.unified_legal_mask()[state.to_unified_action(action)]
+    assert state.config.deck_size == 60
+
+
+def test_classic_package_exports_backend_alias() -> None:
+    backend = classic.build_backend("python", classic.classic_config(), seed=1)
+
+    assert isinstance(backend.snapshot(), classic.Snapshot)
+
+
+def test_classic_package_exports_bot_registry_helpers() -> None:
+    assert "random" in classic.available_bot_names()
+    assert isinstance(classic.build_bot("random", seed=1), classic.LostCitiesBot)