Files

T

coolguyandClaude Opus 4.7 5c221fb3c6 Accept first survey batch + add commit-hash post-processing

Spot-check of the three drafts gemini produced in the --max 3
survey smoke test: all cited file paths exist, line numbers and
function names land within 1-2 lines of actual symbols
(game.pyx:217 cdef class GameState, evaluate.py:220 batched-entropy
block, trainer.py:892 _evaluate_parallel, action_distribution at
evaluate.py:238 with cited code at line 250 inside it). Numbers
cross-checked against archives match. Conclusions preserved.

The one systemic weakness was the Last-verified commit field:
gemini left a `<short-hash>` placeholder, a literal `HEAD`, or
omitted the commit entirely depending on the call. Fixed in two
places:

1. Manually patched the three drafts before acceptance and copied
   them into docs/research/.
2. Added _current_commit_sha and _post_process_draft helpers to
   both librarian_survey.py and librarian_promote.py. The drafts
   now go through `**Last verified:**` line normalization that
   substitutes today's date and `git rev-parse --short HEAD`
   before being written to disk. Future runs converge
   deterministically.

Net: docs/research/ gains classic-port-notes.md,
deep-cfr-batched-evaluation.md, and deep-cfr-evaluation-profile.md.
12 archive entries remain unprocessed.

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

2026-05-08 01:52:08 +09:00

3.8 KiB

Raw Permalink Blame History

Classic Game Port Architecture

Last verified: 2026-05-08, commit b0b3855 Source: docs/archive/classic-port-notes.md

The "classic" game port serves as the fundamental layer of the coolrl-lost-cities project, representing a focused extraction of the Lost Cities game from the legacy coolrl repository. This architectural foundation was established to isolate the core mechanics of the two-player card game from the experimental "tiers" (simplified variants tier0 through tier3) used in earlier research. By centering the repository on the full classic ruleset, the project provides a stable, high-performance API that serves both as a playable game and a rigorous training environment.

Question: Architectural Scope and Design

How is the Lost Cities "classic" game structured and scoped to serve as the foundation of the repository while remaining decoupled from specific training algorithms?

Code Reference

src/coolrl_lost_cities/games/classic/game.pyx: The core high-performance game logic and state management.
src/coolrl_lost_cities/games/classic/env.py: The standard environment wrapper for algorithmic interaction.
src/coolrl_lost_cities/games/classic/pygame_pvp.py: The graphical interface for human-to-human play and debugging.

Analysis and Derivation

The transition from the legacy coolrl codebase to this standalone repository involved a deliberate narrowing of scope. The primary design goal was to treat the classic game as the initial concrete implementation under coolrl_lost_cities.games, avoiding the complexity of a variant registry or broad abstraction layers before they were strictly necessary.

A key technical decision was the use of an in-process Cython implementation for the game state. By defining cdef class GameState (see src/coolrl_lost_cities/games/classic/game.pyx:217), the project achieves C-level performance for state transitions, legal action masking, and scoring. This efficiency is critical for compute-intensive search algorithms like Deep Counterfactual Regret Minimization (Deep CFR), where the overhead of pure Python state management would be prohibitive.

The architecture strictly separates the game rules from the training infrastructure. While the classic game provides the necessary hooks for reinforcement learning—such as observation vectors and reward signals—it does not depend on any specific learning library. This separation ensures that the game logic remains verifiable and readable, centered on the rules and state transitions rather than the requirements of a particular neural network architecture.

Furthermore, the "classic" designation is specifically applied to the five-expedition version of the game. This naming convention leaves room for future variants, such as six-expedition versions, without requiring a breaking change to the core package structure. The removal of separate native backends in favor of a single, highly-optimized Cython backend simplifies the build process and ensures consistency between local play and large-scale training runs.

Practical Implication

The resulting package structure allows developers to interact with the game through multiple interfaces: a raw Cython API for high-performance search, a Gym-like environment for reinforcement learning, and a Pygame-based GUI for manual verification. This modularity means that improvements to the game logic (e.g., scoring optimizations in score_expedition at src/coolrl_lost_cities/games/classic/game.pyx:188) automatically benefit all downstream consumers, from the training loops to the interactive bots.

References

src/coolrl_lost_cities/games/classic/game.pyx: Core logic, state cloning, and legal action generation.
src/coolrl_lost_cities/games/classic/env.py: Environment state management and step logic.
docs/archive/classic-port-notes.md: Original design notes regarding the extraction and scoping.

3.8 KiB Raw Permalink Blame History