fow-rl 0.1.0__tar.gz

fow_rl-0.1.0/Cargo.lock

@@ -0,0 +1,403 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "addr2line"
+version = "0.25.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b5d307320b3181d6d7954e663bd7c774a838b8220fe0593c86d9fb09f498b4b"
+dependencies = [
+ "gimli",
+]
+
+[[package]]
+name = "adler2"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
+
+[[package]]
+name = "arrayvec"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23b62fc65de8e4e7f52534fb52b0f3ed04746ae267519eef2a83941e8085068b"
+
+[[package]]
+name = "autocfg"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
+
+[[package]]
+name = "backtrace"
+version = "0.3.76"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb531853791a215d7c62a30daf0dde835f381ab5de4589cfe7c649d2cbe92bd6"
+dependencies = [
+ "addr2line",
+ "cfg-if",
+ "libc",
+ "miniz_oxide",
+ "object",
+ "rustc-demangle",
+ "windows-link",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "chess"
+version = "3.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2ed299b171ec34f372945ad6726f7bc1d2afd5f59fb8380f64f48e2bab2f0ec8"
+dependencies = [
+ "arrayvec",
+ "failure",
+ "nodrop",
+ "rand",
+]
+
+[[package]]
+name = "failure"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d32e9bd16cc02eae7db7ef620b392808b89f6a5e16bb3497d159c6b92a0f4f86"
+dependencies = [
+ "backtrace",
+ "failure_derive",
+]
+
+[[package]]
+name = "failure_derive"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aa4da3c766cd7a0db8242e326e9e4e081edd567072893ed320008189715366a4"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 1.0.109",
+ "synstructure",
+]
+
+[[package]]
+name = "fow_rl"
+version = "0.1.0"
+dependencies = [
+ "chess",
+ "pyo3",
+]
+
+[[package]]
+name = "gimli"
+version = "0.32.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e629b9b98ef3dd8afe6ca2bd0f89306cec16d43d907889945bc5d6687f2f13c7"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "indoc"
+version = "2.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.186"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+
+[[package]]
+name = "memchr"
+version = "2.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
+
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "miniz_oxide"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
+dependencies = [
+ "adler2",
+]
+
+[[package]]
+name = "nodrop"
+version = "0.1.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72ef4a56884ca558e5ddb05a1d1e7e1bfd9a68d9ed024c21704cc98872dae1bb"
+
+[[package]]
+name = "object"
+version = "0.37.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff76201f031d8863c38aa7f905eca4f53abbfa15f609db4277d44cd8938f33fe"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
+
+[[package]]
+name = "ppv-lite86"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
+dependencies = [
+ "zerocopy",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7778bffd85cf38175ac1f545509665d0b9b92a198ca7941f131f85f7a4f9a872"
+dependencies = [
+ "cfg-if",
+ "indoc",
+ "libc",
+ "memoffset",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+ "unindent",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94f6cbe86ef3bf18998d9df6e0f3fc1050a8c5efa409bf712e661a4366e010fb"
+dependencies = [
+ "once_cell",
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e9f1b4c431c0bb1c8fb0a338709859eed0d030ff6daa34368d3b152a63dfdd8d"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fbc2201328f63c4710f68abdf653c89d8dbc2858b88c5d88b0ff38a75288a9da"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn 2.0.117",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fca6726ad0f3da9c9de093d6f116a93c1a38e417ed73bf138472cf4064f72028"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "pyo3-build-config",
+ "quote",
+ "syn 2.0.117",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rand"
+version = "0.7.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a6b1679d49b24bbfe0c803429aa1874472f50d9b363131f0e89fc356b544d03"
+dependencies = [
+ "rand_chacha",
+ "rand_core",
+ "rand_hc",
+ "rand_pcg",
+]
+
+[[package]]
+name = "rand_chacha"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f4c8ed856279c9737206bf725bf36935d8666ead7aa69b52be55af369d193402"
+dependencies = [
+ "ppv-lite86",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "90bde5296fc891b0cef12a6d03ddccc162ce7b2aff54160af9338f8d40df6d19"
+
+[[package]]
+name = "rand_hc"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ca3129af7b92a17112d59ad498c6f81eaf463253766b90396d39ea7a39d6613c"
+dependencies = [
+ "rand_core",
+]
+
+[[package]]
+name = "rand_pcg"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "16abd0c1b639e9eb4d7c50c0b8100b0d0f849be2349829c740fe8e6eb4816429"
+dependencies = [
+ "rand_core",
+]
+
+[[package]]
+name = "rustc-demangle"
+version = "0.1.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b50b8869d9fc858ce7266cce0194bd74df58b9d0e3f6df3a9fc8eb470d95c09d"
+
+[[package]]
+name = "rustversion"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+
+[[package]]
+name = "syn"
+version = "1.0.109"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b64191b275b66ffe2469e8af2c1cfe3bafa67b529ead792a6d0160888b4237"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "synstructure"
+version = "0.12.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f36bdaa60a83aca3921b5259d5400cbf5e90fc51931376a9bd4a0eb79aa7210f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 1.0.109",
+ "unicode-xid",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.12.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unicode-xid"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
+
+[[package]]
+name = "unindent"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "zerocopy"
+version = "0.8.48"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eed437bf9d6692032087e337407a86f04cd8d6a16a37199ed57949d415bd68e9"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.48"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "70e3cd084b1788766f53af483dd21f93881ff30d7320490ec3ef7526d203bad4"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]

fow_rl-0.1.0/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "fow_rl"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+[lib]
+name = "fow_rl"
+crate-type = ["rlib"]
+
+[dependencies]
+pyo3 = "0.23.3"
+chess = "3.2"
+
+[features]
+extension-module = ["pyo3/extension-module"]
+fuzzing = []

fow_rl-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: fow_rl
+Version: 0.1.0
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.8

fow_rl-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["maturin>=1.8,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "fow_rl"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Rust",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: Implementation :: PyPy",
+]
+dynamic = ["version"]
+[tool.maturin]
+features = ["extension-module"]

fow_rl-0.1.0/src/lib.rs

@@ -0,0 +1,903 @@
+use std::collections::{HashSet, VecDeque};
+use std::str::FromStr;
+
+use chess::{
+    get_bishop_moves, get_king_moves, get_knight_moves, get_pawn_attacks, get_rook_moves, Board,
+    BitBoard, ChessMove, Color, File, MoveGen, Piece, Rank, Square, EMPTY,
+};
+use pyo3::exceptions::PyValueError;
+use pyo3::prelude::*;
+use pyo3::types::PyDict;
+
+const HISTORY_LEN: usize = 8;
+const SLICE_CHANNELS: usize = 13;
+const CASTLING_CHANNELS: usize = 2;
+const BOARD_SQUARES: usize = 64;
+const PROMOTION_BASE: usize = 4096;
+
+const FILES: [File; 8] = [
+    File::A,
+    File::B,
+    File::C,
+    File::D,
+    File::E,
+    File::F,
+    File::G,
+    File::H,
+];
+
+const RANKS: [Rank; 8] = [
+    Rank::First,
+    Rank::Second,
+    Rank::Third,
+    Rank::Fourth,
+    Rank::Fifth,
+    Rank::Sixth,
+    Rank::Seventh,
+    Rank::Eighth,
+];
+
+fn square_from_index(index: usize) -> Square {
+    let file = FILES[index % 8];
+    let rank = RANKS[index / 8];
+    Square::make_square(rank, file)
+}
+
+fn square_index(square: Square) -> usize {
+    square.to_index() as usize
+}
+
+fn mirror_index(index: usize) -> usize {
+    index ^ 56
+}
+
+fn mirror_square(square: Square) -> Square {
+    square_from_index(mirror_index(square_index(square)))
+}
+
+fn piece_base_index(piece: Piece) -> usize {
+    match piece {
+        Piece::Pawn => 0,
+        Piece::Knight => 1,
+        Piece::Bishop => 2,
+        Piece::Rook => 3,
+        Piece::Queen => 4,
+        Piece::King => 5,
+    }
+}
+
+fn piece_value(piece: Piece) -> i8 {
+    match piece {
+        Piece::Pawn => 1,
+        Piece::Knight => 2,
+        Piece::Bishop => 3,
+        Piece::Rook => 4,
+        Piece::Queen => 5,
+        Piece::King => 6,
+    }
+}
+
+fn promotion_index(piece: Piece) -> Option<usize> {
+    match piece {
+        Piece::Queen => Some(0),
+        Piece::Rook => Some(1),
+        Piece::Bishop => Some(2),
+        Piece::Knight => Some(3),
+        _ => None,
+    }
+}
+
+fn reshape_rows(data: Vec<f32>, cols: usize) -> Vec<Vec<f32>> {
+    data.chunks(cols).map(|chunk| chunk.to_vec()).collect()
+}
+
+fn fen_from_py(board_obj: &Bound<'_, PyAny>) -> PyResult<String> {
+    if let Ok(fen) = board_obj.extract::<String>() {
+        return Ok(fen);
+    }
+
+    if let Ok(fen_attr) = board_obj.getattr("fen") {
+        if fen_attr.is_callable() {
+            return fen_attr.call0()?.extract::<String>();
+        }
+        if let Ok(fen) = fen_attr.extract::<String>() {
+            return Ok(fen);
+        }
+    }
+
+    Err(PyValueError::new_err(
+        "board must be a python-chess Board or FEN string",
+    ))
+}
+
+fn flatten_matrix(matrix: Vec<Vec<f32>>) -> PyResult<Vec<f32>> {
+    if matrix.len() != BOARD_SQUARES {
+        return Err(PyValueError::new_err(format!(
+            "history_tensors entries must have {} rows",
+            BOARD_SQUARES
+        )));
+    }
+
+    let mut flat = Vec::with_capacity(BOARD_SQUARES * SLICE_CHANNELS);
+    for row in matrix {
+        if row.len() != SLICE_CHANNELS {
+            return Err(PyValueError::new_err(format!(
+                "history_tensors entries must have {} columns",
+                SLICE_CHANNELS
+            )));
+        }
+        flat.extend_from_slice(&row);
+    }
+
+    Ok(flat)
+}
+
+fn validate_flat(flat: Vec<f32>) -> PyResult<Vec<f32>> {
+    if flat.len() != BOARD_SQUARES * SLICE_CHANNELS {
+        return Err(PyValueError::new_err(format!(
+            "history_tensors entries must have length {}",
+            BOARD_SQUARES * SLICE_CHANNELS
+        )));
+    }
+    Ok(flat)
+}
+
+fn tensor_to_flat(tensor_obj: &Bound<'_, PyAny>) -> PyResult<Vec<f32>> {
+    if let Ok(matrix) = tensor_obj.extract::<Vec<Vec<f32>>>() {
+        return flatten_matrix(matrix);
+    }
+    if let Ok(flat) = tensor_obj.extract::<Vec<f32>>() {
+        return validate_flat(flat);
+    }
+
+    if let Ok(tolist) = tensor_obj.getattr("tolist") {
+        if tolist.is_callable() {
+            let list_obj = tolist.call0()?;
+            if let Ok(matrix) = list_obj.extract::<Vec<Vec<f32>>>() {
+                return flatten_matrix(matrix);
+            }
+            if let Ok(flat) = list_obj.extract::<Vec<f32>>() {
+                return validate_flat(flat);
+            }
+        }
+    }
+
+    Err(PyValueError::new_err(
+        "history_tensors entries must be 64x13 tensors or lists",
+    ))
+}
+
+fn history_from_py(history_obj: &Bound<'_, PyAny>) -> PyResult<VecDeque<Vec<f32>>> {
+    let mut deque = VecDeque::new();
+
+    for item in history_obj.try_iter()? {
+        let item = item?;
+        let flat = tensor_to_flat(&item)?;
+        deque.push_back(flat);
+    }
+
+    while deque.len() > HISTORY_LEN {
+        deque.pop_front();
+    }
+
+    Ok(deque)
+}
+
+fn uci_from_py(action_obj: &Bound<'_, PyAny>) -> PyResult<String> {
+    if let Ok(uci) = action_obj.extract::<String>() {
+        return Ok(uci);
+    }
+
+    if let Ok(uci_attr) = action_obj.getattr("uci") {
+        if uci_attr.is_callable() {
+            return uci_attr.call0()?.extract::<String>();
+        }
+        if let Ok(uci) = uci_attr.extract::<String>() {
+            return Ok(uci);
+        }
+    }
+
+    Err(PyValueError::new_err(
+        "action must be a python-chess Move or UCI string",
+    ))
+}
+
+#[pyclass]
+#[derive(Clone)]
+pub struct SelfPlayGame {
+    board: Board,
+    history_tensors: VecDeque<Vec<f32>>,
+}
+
+impl SelfPlayGame {
+    fn new_internal(board: Board, history_tensors: Option<VecDeque<Vec<f32>>>) -> Self {
+        let mut game = SelfPlayGame {
+            board,
+            history_tensors: history_tensors.unwrap_or_default(),
+        };
+
+        if game.history_tensors.is_empty() {
+            game.save_history_state();
+        }
+
+        game
+    }
+
+    fn side_to_move(&self) -> Color {
+        self.board.side_to_move()
+    }
+
+    fn push_history(&mut self, slice: Vec<f32>) {
+        if self.history_tensors.len() == HISTORY_LEN {
+            self.history_tensors.pop_front();
+        }
+        self.history_tensors.push_back(slice);
+    }
+
+    fn save_history_state(&mut self) {
+        let current_player = self.side_to_move();
+        let visible_squares = self.compute_visibility(current_player);
+
+        let mut slice_tensor = vec![0.0; BOARD_SQUARES * SLICE_CHANNELS];
+
+        for index in 0..BOARD_SQUARES {
+            let view_index = if current_player == Color::White {
+                index
+            } else {
+                mirror_index(index)
+            };
+
+            if !visible_squares.contains(&index) {
+                slice_tensor[view_index * SLICE_CHANNELS + 12] = 1.0;
+                continue;
+            }
+
+            let square = square_from_index(index);
+            if let Some(piece) = self.board.piece_on(square) {
+                let is_own_piece = self.board.color_on(square) == Some(current_player);
+                let mut piece_idx = piece_base_index(piece);
+                if !is_own_piece {
+                    piece_idx += 6;
+                }
+                slice_tensor[view_index * SLICE_CHANNELS + piece_idx] = 1.0;
+            }
+        }
+
+        self.push_history(slice_tensor);
+    }
+
+    fn board_matrix(&self) -> Vec<Vec<i8>> {
+        let mut mat = Vec::with_capacity(8);
+        for rank in (0..8).rev() {
+            let mut row = Vec::with_capacity(8);
+            for file in 0..8 {
+                let square = Square::make_square(RANKS[rank], FILES[file]);
+                if let Some(piece) = self.board.piece_on(square) {
+                    let mut val = piece_value(piece);
+                    if self.board.color_on(square) == Some(Color::Black) {
+                        val = -val;
+                    }
+                    row.push(val);
+                } else {
+                    row.push(0);
+                }
+            }
+            mat.push(row);
+        }
+        mat
+    }
+
+    fn castle_eligible_internal(&self) -> (bool, bool) {
+        let rights = self.board.castle_rights(self.side_to_move());
+        (rights.has_kingside(), rights.has_queenside())
+    }
+
+    fn legal_actions_internal(&self) -> Vec<ChessMove> {
+        MoveGen::new_legal(&self.board).collect()
+    }
+
+    fn apply_internal(&mut self, action: ChessMove) {
+        self.board = self.board.make_move_new(action);
+        self.save_history_state();
+    }
+
+    fn is_terminal_internal(&self) -> bool {
+        !self.king_present(Color::White) || !self.king_present(Color::Black)
+    }
+
+    fn terminal_value_internal(&self, player: Color) -> f32 {
+        if !self.king_present(Color::White) {
+            return if player == Color::Black { 1.0 } else { -1.0 };
+        }
+        if !self.king_present(Color::Black) {
+            return if player == Color::White { 1.0 } else { -1.0 };
+        }
+        0.0
+    }
+
+    fn king_present(&self, color: Color) -> bool {
+        let kings = *self.board.pieces(Piece::King) & *self.board.color_combined(color);
+        kings != EMPTY
+    }
+
+    fn piece_attacks(&self, square: Square, piece: Piece, color: Color) -> BitBoard {
+        let blockers = *self.board.combined();
+        match piece {
+            Piece::Pawn => get_pawn_attacks(square, color, !EMPTY),
+            Piece::Knight => get_knight_moves(square),
+            Piece::Bishop => get_bishop_moves(square, blockers),
+            Piece::Rook => get_rook_moves(square, blockers),
+            Piece::Queen => get_bishop_moves(square, blockers) | get_rook_moves(square, blockers),
+            Piece::King => get_king_moves(square),
+        }
+    }
+
+    fn compute_visibility(&self, player: Color) -> HashSet<usize> {
+        let mut visible = HashSet::new();
+
+        for index in 0..BOARD_SQUARES {
+            let square = square_from_index(index);
+            let piece = self.board.piece_on(square);
+            let color = self.board.color_on(square);
+
+            if piece.is_some() && color == Some(player) {
+                visible.insert(index);
+                let attacks = self.piece_attacks(square, piece.unwrap(), player);
+                for target in attacks {
+                    visible.insert(square_index(target));
+                }
+
+                if piece == Some(Piece::Pawn) {
+                    let forward_offset: i32 = if player == Color::White { 8 } else { -8 };
+                    let fwd_index = index as i32 + forward_offset;
+                    if (0..BOARD_SQUARES as i32).contains(&fwd_index) {
+                        visible.insert(fwd_index as usize);
+
+                        let rank = index / 8;
+                        let start_rank = if player == Color::White { 1 } else { 6 };
+                        if rank == start_rank {
+                            let fwd_square = square_from_index(fwd_index as usize);
+                            if self.board.piece_on(fwd_square).is_none() {
+                                let dbl_index = index as i32 + 2 * forward_offset;
+                                if (0..BOARD_SQUARES as i32).contains(&dbl_index) {
+                                    visible.insert(dbl_index as usize);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
+        visible
+    }
+
+    fn encode_flat(&self) -> Vec<f32> {
+        let mut history_list: Vec<Vec<f32>> = if self.history_tensors.is_empty() {
+            vec![vec![0.0; BOARD_SQUARES * SLICE_CHANNELS]]
+        } else {
+            self.history_tensors.iter().cloned().collect()
+        };
+
+        while history_list.len() < HISTORY_LEN {
+            let first = history_list[0].clone();
+            history_list.insert(0, first);
+        }
+
+        let history_channels = SLICE_CHANNELS * HISTORY_LEN;
+        let mut tensor = vec![0.0; BOARD_SQUARES * history_channels];
+
+        for square in 0..BOARD_SQUARES {
+            for (idx, slice) in history_list.iter().enumerate() {
+                let dst_base = square * history_channels + idx * SLICE_CHANNELS;
+                let src_base = square * SLICE_CHANNELS;
+                tensor[dst_base..dst_base + SLICE_CHANNELS]
+                    .copy_from_slice(&slice[src_base..src_base + SLICE_CHANNELS]);
+            }
+        }
+
+        let mut castling_channel = vec![0.0; BOARD_SQUARES * CASTLING_CHANNELS];
+        let (king_side, queen_side) = self.castle_eligible_internal();
+        let king_val = if king_side { 1.0 } else { 0.0 };
+        let queen_val = if queen_side { 1.0 } else { 0.0 };
+
+        if BOARD_SQUARES >= 2 {
+            castling_channel[0] += king_val;
+            castling_channel[1] += king_val;
+            castling_channel[2] += queen_val;
+            castling_channel[3] += queen_val;
+        }
+
+        let mut encoded = vec![0.0; BOARD_SQUARES * (history_channels + CASTLING_CHANNELS)];
+        for square in 0..BOARD_SQUARES {
+            let dst_base = square * (history_channels + CASTLING_CHANNELS);
+            let src_base = square * history_channels;
+            encoded[dst_base..dst_base + history_channels]
+                .copy_from_slice(&tensor[src_base..src_base + history_channels]);
+
+            let castling_base = square * CASTLING_CHANNELS;
+            encoded[dst_base + history_channels..dst_base + history_channels + CASTLING_CHANNELS]
+                .copy_from_slice(&castling_channel[castling_base..castling_base + CASTLING_CHANNELS]);
+        }
+
+        encoded
+    }
+
+    fn action_index_internal(&self, action: ChessMove) -> Result<usize, String> {
+        let mut from_sq = action.get_source();
+        let mut to_sq = action.get_dest();
+
+        if self.side_to_move() == Color::Black {
+            from_sq = mirror_square(from_sq);
+            to_sq = mirror_square(to_sq);
+        }
+
+        if let Some(promotion) = action.get_promotion() {
+            let promotion_idx = promotion_index(promotion)
+                .ok_or_else(|| format!("Unsupported promotion piece: {:?}", promotion))?;
+            return Ok(PROMOTION_BASE + square_index(from_sq) * 4 + promotion_idx);
+        }
+
+        Ok(square_index(from_sq) * BOARD_SQUARES + square_index(to_sq))
+    }
+}
+
+#[pymethods]
+impl SelfPlayGame {
+    #[new]
+    #[pyo3(signature = (board=None, history_tensors=None))]
+    fn new(
+        py: Python,
+        board: Option<PyObject>,
+        history_tensors: Option<PyObject>,
+    ) -> PyResult<Self> {
+        let board = match board {
+            Some(obj) => {
+                let bound = obj.bind(py);
+                let fen = fen_from_py(&bound)?;
+                Board::from_str(&fen).map_err(|_| PyValueError::new_err("Invalid FEN string"))?
+            }
+            None => Board::default(),
+        };
+
+        let history_deque = match history_tensors {
+            Some(obj) => {
+                let bound = obj.bind(py);
+                Some(history_from_py(&bound)?)
+            }
+            None => None,
+        };
+
+        Ok(SelfPlayGame::new_internal(board, history_deque))
+    }
+
+    #[getter]
+    fn turn(&self) -> bool {
+        self.side_to_move() == Color::White
+    }
+
+    #[getter]
+    fn board(&self) -> Vec<Vec<i8>> {
+        self.board_matrix()
+    }
+
+    fn castle_eligible(&self) -> (bool, bool) {
+        self.castle_eligible_internal()
+    }
+
+    fn clone(&self) -> SelfPlayGame {
+        Clone::clone(self)
+    }
+
+    fn current_player(&self) -> bool {
+        self.side_to_move() == Color::White
+    }
+
+    #[pyo3(name = "legal_actions")]
+    fn legal_actions_py(&self, py: Python) -> PyResult<Vec<PyObject>> {
+        let chess_mod = PyModule::import(py, "chess")
+            .map_err(|_| PyValueError::new_err("python-chess is required for legal_actions()"))?;
+        let move_type = chess_mod.getattr("Move")?;
+        let from_uci = move_type.getattr("from_uci")?;
+
+        let mut moves = Vec::new();
+        for mv in self.legal_actions_internal() {
+            let obj = from_uci.call1((mv.to_string(),))?;
+            moves.push(obj.unbind());
+        }
+
+        Ok(moves)
+    }
+
+    fn apply(&mut self, py: Python, action: PyObject) -> PyResult<()> {
+        let bound = action.bind(py);
+        let uci = uci_from_py(&bound)?;
+        let action = ChessMove::from_str(&uci)
+            .map_err(|_| PyValueError::new_err("Invalid UCI move"))?;
+        self.apply_internal(action);
+        Ok(())
+    }
+
+    fn is_terminal(&self) -> bool {
+        self.is_terminal_internal()
+    }
+
+    fn terminal_value(&self, player_is_white: bool) -> f32 {
+        let player = if player_is_white { Color::White } else { Color::Black };
+        self.terminal_value_internal(player)
+    }
+
+    fn encode(&self, py: Python) -> PyResult<PyObject> {
+        let flat = self.encode_flat();
+        let cols = SLICE_CHANNELS * HISTORY_LEN + CASTLING_CHANNELS;
+        let rows = reshape_rows(flat, cols);
+
+        let torch = PyModule::import(py, "torch")
+            .map_err(|_| PyValueError::new_err("torch is required for encode()"))?;
+        let tensor_fn = torch.getattr("tensor")?;
+        let kwargs = PyDict::new(py);
+        kwargs.set_item("dtype", torch.getattr("float32")?)?;
+        let tensor = tensor_fn.call((rows,), Some(&kwargs))?;
+        Ok(tensor.unbind())
+    }
+
+    fn action_index(&self, py: Python, action: PyObject) -> PyResult<usize> {
+        let bound = action.bind(py);
+        let uci = uci_from_py(&bound)?;
+        let action = ChessMove::from_str(&uci)
+            .map_err(|_| PyValueError::new_err("Invalid UCI move"))?;
+        self.action_index_internal(action)
+            .map_err(PyValueError::new_err)
+    }
+}
+
+/// A Python module implemented in Rust.
+#[pymodule]
+fn fow_rl(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    m.add_class::<SelfPlayGame>()?;
+    Ok(())
+}
+
+#[cfg(feature = "fuzzing")]
+pub mod fuzzing {
+    use super::*;
+
+    pub fn new_default_game() -> SelfPlayGame {
+        SelfPlayGame::new_internal(Board::default(), None)
+    }
+
+    pub fn apply(game: &mut SelfPlayGame, action: ChessMove) {
+        game.apply_internal(action);
+    }
+
+    pub fn legal_actions(game: &SelfPlayGame) -> Vec<ChessMove> {
+        game.legal_actions_internal()
+    }
+
+    pub fn board_matrix(game: &SelfPlayGame) -> Vec<Vec<i8>> {
+        game.board_matrix()
+    }
+
+    pub fn castle_eligible(game: &SelfPlayGame) -> (bool, bool) {
+        game.castle_eligible_internal()
+    }
+
+    pub fn encode_flat(game: &SelfPlayGame) -> Vec<f32> {
+        game.encode_flat()
+    }
+
+    pub fn action_index(game: &SelfPlayGame, action: ChessMove) -> Result<usize, String> {
+        game.action_index_internal(action)
+    }
+
+    pub fn is_white_to_move(game: &SelfPlayGame) -> bool {
+        game.side_to_move() == Color::White
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pyo3::types::PyModule;
+    use std::ffi::CString;
+
+    const PY_SELFPLAY_CODE: &str = r#"
+import chess
+import torch
+from collections import deque
+
+_PROMOTION_PIECE_ORDER = {
+    chess.QUEEN: 0,
+    chess.ROOK: 1,
+    chess.BISHOP: 2,
+    chess.KNIGHT: 3,
+}
+_PROMOTION_OPTION_COUNT = len(_PROMOTION_PIECE_ORDER)
+
+
+class SelfPlayGame:
+    """Mutable game-state protocol consumed by PPO for Fog of War Chess."""
+
+    def __init__(self, board: chess.Board = None, history_tensors: deque = None):
+        self._board = board if board else chess.Board()
+
+        if history_tensors is not None:
+            self._history_tensors = history_tensors
+        else:
+            self._history_tensors = deque(maxlen=8)
+            self._save_history_state()
+
+    def _save_history_state(self) -> None:
+        current_player = self.turn
+        visible_squares = self._compute_visibility(self._board, current_player)
+
+        slice_tensor = torch.zeros((64, 13), dtype=torch.float32)
+
+        for sq in chess.SQUARES:
+            view_sq = sq if current_player == chess.WHITE else chess.square_mirror(sq)
+
+            if sq not in visible_squares:
+                slice_tensor[view_sq, 12] = 1.0
+            else:
+                piece = self._board.piece_at(sq)
+                if piece is not None:
+                    is_own_piece = (piece.color == current_player)
+                    piece_idx = piece.piece_type - 1
+                    if not is_own_piece:
+                        piece_idx += 6
+                    slice_tensor[view_sq, piece_idx] = 1.0
+
+        self._history_tensors.append(slice_tensor)
+
+    @property
+    def turn(self) -> bool:
+        return self._board.turn
+
+    @property
+    def board(self):
+        mat = []
+        for rank in range(7, -1, -1):
+            row = []
+            for file in range(8):
+                piece = self._board.piece_at(chess.square(file, rank))
+                if not piece:
+                    row.append(0)
+                else:
+                    val = piece.piece_type
+                    row.append(val if piece.color == chess.WHITE else -val)
+            mat.append(row)
+        return mat
+
+    def castle_eligible(self):
+        return (
+            self._board.has_kingside_castling_rights(self.turn),
+            self._board.has_queenside_castling_rights(self.turn),
+        )
+
+    def clone(self):
+        cloned_history = deque([t.clone() for t in self._history_tensors], maxlen=8)
+        return SelfPlayGame(board=self._board.copy(), history_tensors=cloned_history)
+
+    def current_player(self):
+        return self.turn
+
+    def legal_actions(self):
+        return list(self._board.pseudo_legal_moves)
+
+    def apply(self, action):
+        self._board.push(action)
+        self._save_history_state()
+
+    def is_terminal(self) -> bool:
+        return (self._board.king(chess.WHITE) is None) or (
+            self._board.king(chess.BLACK) is None
+        )
+
+    def terminal_value(self, player):
+        white_king = self._board.king(chess.WHITE)
+        black_king = self._board.king(chess.BLACK)
+        if white_king is None:
+            return 1.0 if player == chess.BLACK else -1.0
+        if black_king is None:
+            return 1.0 if player == chess.WHITE else -1.0
+        return 0.0
+
+    def _compute_visibility(self, board: chess.Board, player: bool):
+        visible = set()
+        for sq in chess.SQUARES:
+            piece = board.piece_at(sq)
+            if piece and piece.color == player:
+                visible.add(sq)
+                visible.update(board.attacks(sq))
+
+                if piece.piece_type == chess.PAWN:
+                    forward_offset = 8 if player == chess.WHITE else -8
+                    fwd_sq = sq + forward_offset
+                    if 0 <= fwd_sq < 64:
+                        visible.add(fwd_sq)
+                        rank = chess.square_rank(sq)
+                        if (player == chess.WHITE and rank == 1) or (
+                            player == chess.BLACK and rank == 6
+                        ):
+                            if board.piece_at(fwd_sq) is None:
+                                visible.add(sq + 2 * forward_offset)
+        return visible
+
+    def encode(self):
+        history_list = list(self._history_tensors)
+        while len(history_list) < 8:
+            history_list.insert(0, history_list[0])
+
+        tensor = torch.cat(history_list, dim=1)
+
+        castle_eligibility = self.castle_eligible()
+
+        castling_channel = torch.zeros((64, 2), dtype=torch.float32)
+        castling_channel[0] += castle_eligibility[0]
+        castling_channel[1] += castle_eligibility[1]
+
+        return torch.cat([tensor, castling_channel], dim=1)
+
+    def action_index(self, action):
+        from_sq = action.from_square
+        to_sq = action.to_square
+
+        if not self.turn:
+            from_sq = chess.square_mirror(from_sq)
+            to_sq = chess.square_mirror(to_sq)
+
+        if action.promotion is not None:
+            promotion_idx = _PROMOTION_PIECE_ORDER.get(action.promotion)
+            if promotion_idx is None:
+                raise ValueError(f"Unsupported promotion piece: {action.promotion}")
+            return 4096 + from_sq * 4 + promotion_idx
+
+        return from_sq * 64 + to_sq
+"#;
+
+    fn python_selfplay_module<'py>(py: Python<'py>) -> PyResult<Bound<'py, PyModule>> {
+        let code = CString::new(PY_SELFPLAY_CODE).expect("Python code contains no NUL bytes");
+        let filename = CString::new("selfplay_ref.py").expect("valid filename");
+        let module = CString::new("selfplay_ref").expect("valid module name");
+        PyModule::from_code(py, code.as_c_str(), filename.as_c_str(), module.as_c_str())
+    }
+
+    fn flatten_2d(matrix: Vec<Vec<f32>>) -> Vec<f32> {
+        let mut flat = Vec::new();
+        for row in matrix {
+            flat.extend_from_slice(&row);
+        }
+        flat
+    }
+
+    fn py_encode_flat(game: &Bound<'_, PyAny>) -> PyResult<Vec<f32>> {
+        let tensor = game.call_method0("encode")?;
+        let list = tensor.call_method0("tolist")?;
+        let rows: Vec<Vec<f32>> = list.extract()?;
+        Ok(flatten_2d(rows))
+    }
+
+    #[test]
+    fn regression_default_state() -> PyResult<()> {
+        pyo3::prepare_freethreaded_python();
+        Python::with_gil(|py| {
+            let chess_mod = match PyModule::import(py, "chess") {
+                Ok(module) => module,
+                Err(_) => return Ok(()),
+            };
+            if PyModule::import(py, "torch").is_err() {
+                return Ok(());
+            }
+
+            let module = python_selfplay_module(py)?;
+            let cls = module.getattr("SelfPlayGame")?;
+            let py_game = cls.call0()?;
+            let rust_game = SelfPlayGame::new_internal(Board::default(), None);
+
+            let py_turn: bool = py_game.getattr("turn")?.extract()?;
+            assert_eq!(rust_game.side_to_move() == Color::White, py_turn);
+
+            let py_board: Vec<Vec<i8>> = py_game.getattr("board")?.extract()?;
+            assert_eq!(rust_game.board_matrix(), py_board);
+
+            let py_castle: (bool, bool) = py_game.call_method0("castle_eligible")?.extract()?;
+            assert_eq!(rust_game.castle_eligible_internal(), py_castle);
+
+            let py_encoded = py_encode_flat(&py_game)?;
+            assert_eq!(rust_game.encode_flat(), py_encoded);
+
+            let mv = chess_mod
+                .getattr("Move")?
+                .getattr("from_uci")?
+                .call1(("e2e4",))?;
+            let py_idx: usize = py_game.call_method1("action_index", (mv,))?.extract()?;
+            let rust_idx = rust_game
+                .action_index_internal(ChessMove::from_str("e2e4").unwrap())
+                .unwrap();
+            assert_eq!(rust_idx, py_idx);
+
+            Ok(())
+        })
+    }
+
+    #[test]
+    fn regression_after_moves() -> PyResult<()> {
+        pyo3::prepare_freethreaded_python();
+        Python::with_gil(|py| {
+            let chess_mod = match PyModule::import(py, "chess") {
+                Ok(module) => module,
+                Err(_) => return Ok(()),
+            };
+            if PyModule::import(py, "torch").is_err() {
+                return Ok(());
+            }
+
+            let module = python_selfplay_module(py)?;
+            let cls = module.getattr("SelfPlayGame")?;
+            let py_game = cls.call0()?;
+            let mut rust_game = SelfPlayGame::new_internal(Board::default(), None);
+
+            for uci in ["e2e4", "e7e5", "g1f3"] {
+                let mv = chess_mod
+                    .getattr("Move")?
+                    .getattr("from_uci")?
+                    .call1((uci,))?;
+                py_game.call_method1("apply", (mv,))?;
+
+                let rust_mv = ChessMove::from_str(uci).unwrap();
+                rust_game.apply_internal(rust_mv);
+            }
+
+            let py_turn: bool = py_game.getattr("turn")?.extract()?;
+            assert_eq!(rust_game.side_to_move() == Color::White, py_turn);
+
+            let py_board: Vec<Vec<i8>> = py_game.getattr("board")?.extract()?;
+            assert_eq!(rust_game.board_matrix(), py_board);
+
+            let py_castle: (bool, bool) = py_game.call_method0("castle_eligible")?.extract()?;
+            assert_eq!(rust_game.castle_eligible_internal(), py_castle);
+
+            let py_encoded = py_encode_flat(&py_game)?;
+            assert_eq!(rust_game.encode_flat(), py_encoded);
+
+            Ok(())
+        })
+    }
+
+    #[test]
+    fn regression_promotion_action_index() -> PyResult<()> {
+        pyo3::prepare_freethreaded_python();
+        Python::with_gil(|py| {
+            let chess_mod = match PyModule::import(py, "chess") {
+                Ok(module) => module,
+                Err(_) => return Ok(()),
+            };
+            if PyModule::import(py, "torch").is_err() {
+                return Ok(());
+            }
+
+            let module = python_selfplay_module(py)?;
+            let cls = module.getattr("SelfPlayGame")?;
+
+            let fen = "8/P7/8/8/8/8/8/K6k w - - 0 1";
+            let py_board = chess_mod.getattr("Board")?.call1((fen,))?;
+            let py_game = cls.call1((py_board,))?;
+
+            let rust_board = Board::from_str(fen).unwrap();
+            let rust_game = SelfPlayGame::new_internal(rust_board, None);
+
+            let mv = chess_mod
+                .getattr("Move")?
+                .getattr("from_uci")?
+                .call1(("a7a8q",))?;
+            let py_idx: usize = py_game.call_method1("action_index", (mv,))?.extract()?;
+
+            let rust_idx = rust_game
+                .action_index_internal(ChessMove::from_str("a7a8q").unwrap())
+                .unwrap();
+            assert_eq!(rust_idx, py_idx);
+
+            Ok(())
+        })
+    }
+}