chessathon-engine 0.1.0__tar.gz

chessathon_engine-0.1.0/.gitignore

@@ -0,0 +1,2 @@
+/target
+/.venv-dev

chessathon_engine-0.1.0/Cargo.lock

@@ -0,0 +1,187 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 3
+
+[[package]]
+name = "arrayvec"
+version = "0.7.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3fb67a6e08acf24fdeccbac2cb6ac4305825bd1f117462e0e6f2f193345ad56"
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "chessathon-engine"
+version = "0.1.0"
+dependencies = [
+ "arrayvec",
+ "pyo3",
+]
+
+[[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.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
+[[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.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f402062616ab18202ae8319da13fa4279883a2b8a9d9f83f20dbade813ce1884"
+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.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b14b5775b5ff446dd1056212d778012cbe8a0fbffd368029fd9e25b514479c38"
+dependencies = [
+ "once_cell",
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ab5bcf04a2cdcbb50c7d6105de943f543f9ed92af55818fd17b660390fc8636"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fd24d897903a9e6d80b968368a34e1525aeb719d568dba8b3d4bfa5dc67d453"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36c011a03ba1e50152b4b394b479826cad97e7a21eb52df179cd91ac411cbfbe"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "pyo3-build-config",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[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 = "unindent"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"

chessathon_engine-0.1.0/Cargo.toml

@@ -0,0 +1,33 @@
+[package]
+name = "chessathon-engine"
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.74"
+description = "Bitboard chess move generation, search and evaluation for the AI Chessathon agent"
+license = "MIT"
+repository = "https://github.com/prog-dj/aichessathon-dev"
+readme = "README.md"
+
+[lib]
+name = "chessathon_engine"
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+pyo3 = { version = "0.22", default-features = false, features = ["abi3-py312", "macros"] }
+arrayvec = "0.7"
+
+[features]
+default = []
+# maturin turns this on; it stops pyo3 linking libpython so the wheel loads
+# against the host interpreter. `cargo test` runs without it.
+extension-module = ["pyo3/extension-module"]
+
+[profile.release]
+opt-level = 3
+lto = "fat"
+codegen-units = 1
+# keep unwind (not abort): a panic then surfaces as a Python exception and
+# agent.py falls back to its own engine instead of the process dying.
+
+[profile.test]
+opt-level = 3

chessathon_engine-0.1.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: chessathon-engine
+Version: 0.1.0
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Games/Entertainment :: Board Games
+Summary: Bitboard chess move generation, search and evaluation for the AI Chessathon agent
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# chessathon-engine
+
+Bitboard chess move generation, evaluation and search for the AI Chessathon
+agent. Built as a Python extension with [maturin](https://www.maturin.rs/) /
+[pyo3](https://pyo3.rs/); `agent.py` imports it and falls back to a pure-Python
+engine if the wheel is unavailable.
+
+```python
+import chessathon_engine as ce
+ce.init()
+ce.best_move("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1", 2000, 2500)
+```
+
+Local dev:
+
+```
+cd engine
+maturin develop --release          # build + install into the active venv
+cargo test --release                # perft suite
+```
+

chessathon_engine-0.1.0/README.md

@@ -0,0 +1,20 @@
+# chessathon-engine
+
+Bitboard chess move generation, evaluation and search for the AI Chessathon
+agent. Built as a Python extension with [maturin](https://www.maturin.rs/) /
+[pyo3](https://pyo3.rs/); `agent.py` imports it and falls back to a pure-Python
+engine if the wheel is unavailable.
+
+```python
+import chessathon_engine as ce
+ce.init()
+ce.best_move("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1", 2000, 2500)
+```
+
+Local dev:
+
+```
+cd engine
+maturin develop --release          # build + install into the active venv
+cargo test --release                # perft suite
+```

chessathon_engine-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["maturin>=1.7,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "chessathon-engine"
+version = "0.1.0"
+description = "Bitboard chess move generation, search and evaluation for the AI Chessathon agent"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+classifiers = [
+    "Programming Language :: Rust",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Topic :: Games/Entertainment :: Board Games",
+]
+
+[tool.maturin]
+# abi3 wheel: one wheel works on 3.12, 3.13, ...
+features = ["extension-module"]
+strip = true

chessathon_engine-0.1.0/src/eval.rs

@@ -0,0 +1,229 @@
+//! Hand-crafted evaluation. Tapered material + piece-square tables plus a few
+//! structural terms. Centipawns, from the side to move's point of view.
+
+use crate::position::Position;
+use crate::tables::tables;
+use crate::types::*;
+
+pub const MATE: i32 = 30_000;
+pub const MATE_IN_MAX: i32 = MATE - 512;
+
+// midgame / endgame piece values
+const MG_VAL: [i32; 6] = [82, 337, 365, 477, 1025, 0];
+const EG_VAL: [i32; 6] = [94, 281, 297, 512, 936, 0];
+const PHASE_W: [i32; 6] = [0, 1, 1, 2, 4, 0];
+const PHASE_MAX: i32 = 24;
+
+// piece-square tables, White's view, a1..h8 (index 0 = a1). From PeSTO.
+#[rustfmt::skip]
+const MG_PST: [[i32; 64]; 6] = [
+    // pawn
+    [ 0,0,0,0,0,0,0,0, -35,-1,-20,-23,-15,24,38,-22, -26,-4,-4,-10,3,3,33,-12,
+      -27,-2,-5,12,17,6,10,-25, -14,13,6,21,23,12,17,-23, -6,7,26,31,65,56,25,-20,
+      98,134,61,95,68,126,34,-11, 0,0,0,0,0,0,0,0 ],
+    // knight
+    [ -105,-21,-58,-33,-17,-28,-19,-23, -29,-53,-12,-3,-1,18,-14,-19, -23,-9,12,10,19,17,25,-16,
+      -13,4,16,13,28,19,21,-8, -9,17,19,53,37,69,18,22, -47,60,37,65,84,129,73,44,
+      -73,-41,72,36,23,62,7,-17, -167,-89,-34,-49,61,-97,-15,-107 ],
+    // bishop
+    [ -33,-3,-14,-21,-13,-12,-39,-21, 4,15,16,0,7,21,33,1, 0,15,15,15,14,27,18,10,
+      -6,13,13,26,34,12,10,4, -4,5,19,50,37,37,7,-2, -16,37,43,40,35,50,37,-2,
+      -26,16,-18,-13,30,59,18,-47, -29,4,-82,-37,-25,-42,7,-8 ],
+    // rook
+    [ -19,-13,1,17,16,7,-37,-26, -44,-16,-20,-9,-1,11,-6,-71, -45,-25,-16,-17,3,0,-5,-33,
+      -36,-26,-12,-1,9,-7,6,-23, -24,-11,7,26,24,35,-8,-20, -5,19,26,36,17,45,61,16,
+      27,32,58,62,80,67,26,44, 32,42,32,51,63,9,31,43 ],
+    // queen
+    [ -1,-18,-9,10,-15,-25,-31,-50, -35,-8,11,2,8,15,-3,1, -14,2,-11,-2,-5,2,14,5,
+      -9,-26,-9,-10,-2,-4,3,-3, -27,-27,-16,-16,-1,17,-2,1, -13,-17,7,8,29,56,47,57,
+      -24,-39,-5,1,-16,57,28,54, -28,0,29,12,59,44,43,45 ],
+    // king
+    [ -15,36,12,-54,8,-28,24,14, 1,7,-8,-64,-43,-16,9,8, -14,-14,-22,-46,-44,-30,-15,-27,
+      -49,-1,-27,-39,-46,-44,-33,-51, -17,-20,-12,-27,-30,-25,-14,-36, -9,24,2,-16,-20,6,22,-22,
+      29,-1,-20,-7,-8,-4,-38,-29, -65,23,16,-15,-56,-34,2,13 ],
+];
+
+#[rustfmt::skip]
+const EG_PST: [[i32; 64]; 6] = [
+    [ 0,0,0,0,0,0,0,0, 13,8,8,10,13,0,2,-7, 4,7,-6,1,0,-5,-1,-8, 13,9,-3,-7,-7,-8,3,-1,
+      32,24,13,5,-2,4,17,17, 94,100,85,67,56,53,82,84, 178,173,158,134,147,132,165,187, 0,0,0,0,0,0,0,0 ],
+    [ -29,-51,-23,-15,-22,-18,-50,-64, -42,-20,-10,-5,-2,-20,-23,-44, -23,-3,-1,15,10,-3,-20,-22,
+      -18,-6,16,25,16,17,4,-18, -17,3,22,22,22,11,8,-18, -24,-20,10,9,-1,-9,-19,-41,
+      -25,-8,-25,-2,-9,-25,-24,-52, -58,-38,-13,-28,-31,-27,-63,-99 ],
+    [ -23,-9,-23,-5,-9,-16,-5,-17, -14,-18,-7,-1,4,-9,-15,-27, -12,-3,8,10,13,3,-7,-15,
+      -6,3,13,19,7,10,-3,-9, -3,9,12,9,14,10,3,2, 2,-8,0,-1,-2,6,0,4,
+      -8,-4,7,-12,-3,-13,-4,-14, -14,-21,-11,-8,-7,-9,-17,-24 ],
+    [ -9,2,3,-1,-5,-13,4,-20, -6,-6,0,2,-9,-9,-11,-3, -4,0,-5,-1,-7,-12,-8,-16,
+      3,5,8,4,-5,-6,-8,-11, 4,3,13,1,2,1,-1,2, 7,7,7,5,4,-3,-5,-3,
+      11,13,13,11,-3,3,8,3, 13,10,18,15,12,12,8,5 ],
+    [ -33,-28,-22,-43,-5,-32,-20,-41, -22,-23,-30,-16,-16,-23,-36,-32, -16,-27,15,6,9,17,10,5,
+      -18,28,19,47,31,34,39,23, 3,22,24,45,57,40,57,36, -20,6,9,49,47,35,19,9,
+      -17,20,32,41,58,25,30,0, -9,22,22,27,27,19,10,20 ],
+    [ -53,-34,-21,-11,-28,-14,-24,-43, -27,-11,4,13,14,4,-5,-17, -19,-3,11,21,23,16,7,-9,
+      -18,-4,21,24,27,23,9,-11, -8,22,24,27,26,33,26,3, 10,17,23,15,20,45,44,13,
+      -12,17,14,17,17,38,23,11, -74,-35,-18,-18,-11,15,4,-17 ],
+];
+
+fn phase(pos: &Position) -> i32 {
+    let mut p = 0;
+    for pt in [
+        PieceType::Knight,
+        PieceType::Bishop,
+        PieceType::Rook,
+        PieceType::Queen,
+    ] {
+        p += PHASE_W[pt.index()] * pos.pieces[pt.index()].count_ones() as i32;
+    }
+    p.min(PHASE_MAX)
+}
+
+#[inline]
+fn pst_sq(sq: Square, c: Color) -> usize {
+    (if c == Color::White { sq } else { flip_square(sq) }) as usize
+}
+
+const PASSED_MG: [i32; 8] = [0, 5, 10, 15, 30, 55, 90, 0];
+const PASSED_EG: [i32; 8] = [0, 10, 18, 30, 55, 95, 160, 0];
+const ISOLATED: i32 = 12;
+const DOUBLED: i32 = 10;
+const BISHOP_PAIR: i32 = 25;
+const ROOK_OPEN: i32 = 22;
+const ROOK_HALF: i32 = 10;
+const TEMPO: i32 = 14;
+
+pub fn evaluate(pos: &Position) -> i32 {
+    let t = tables();
+    let ph = phase(pos);
+    let occ = pos.occupied();
+    let mut mg = 0i32;
+    let mut eg = 0i32;
+
+    let mut safety = [0i32; 2]; // enemy pressure on [white king, black king]
+    let mut mobility_mg = [0i32; 2];
+
+    for c in [Color::White, Color::Black] {
+        let sign = if c == Color::White { 1 } else { -1 };
+        let ci = c.index();
+        let them = c.flip();
+        let king_ring = t.king[pos.king_sq(them) as usize] | bb(pos.king_sq(them));
+
+        for pt in PieceType::ALL {
+            let mut b = pos.piece_bb(c, pt);
+            while b != 0 {
+                let sq = b.trailing_zeros() as Square;
+                b &= b - 1;
+                let idx = pst_sq(sq, c);
+                mg += sign * (MG_VAL[pt.index()] + MG_PST[pt.index()][idx]);
+                eg += sign * (EG_VAL[pt.index()] + EG_PST[pt.index()][idx]);
+
+                match pt {
+                    PieceType::Knight | PieceType::Bishop | PieceType::Rook | PieceType::Queen => {
+                        let att = t.attacks(pt, sq, occ) & !pos.color[ci];
+                        mobility_mg[ci] += (att.count_ones() as i32) * 2;
+                        let ring_hits = (att & king_ring).count_ones() as i32;
+                        if ring_hits > 0 {
+                            safety[them.index()] += ring_hits
+                                * match pt {
+                                    PieceType::Knight | PieceType::Bishop => 2,
+                                    PieceType::Rook => 3,
+                                    _ => 5,
+                                };
+                        }
+                    }
+                    _ => {}
+                }
+            }
+        }
+
+        // bishop pair
+        if pos.piece_bb(c, PieceType::Bishop).count_ones() >= 2 {
+            mg += sign * BISHOP_PAIR;
+            eg += sign * BISHOP_PAIR;
+        }
+
+        // pawns: passed / isolated / doubled
+        let own_pawns = pos.piece_bb(c, PieceType::Pawn);
+        let enemy_pawns = pos.piece_bb(them, PieceType::Pawn);
+        let mut p = own_pawns;
+        while p != 0 {
+            let sq = p.trailing_zeros() as Square;
+            p &= p - 1;
+            let f = file_of(sq);
+            let file_mask = file_bb(f);
+            let adj = (if f > 0 { file_bb(f - 1) } else { 0 })
+                | (if f < 7 { file_bb(f + 1) } else { 0 });
+            // isolated
+            if own_pawns & adj == 0 {
+                mg -= sign * ISOLATED;
+                eg -= sign * ISOLATED;
+            }
+            // doubled
+            if (own_pawns & file_mask).count_ones() > 1 {
+                mg -= sign * DOUBLED / 2;
+                eg -= sign * DOUBLED;
+            }
+            // passed
+            let front = if c == Color::White {
+                pawn_front_span_white(sq)
+            } else {
+                pawn_front_span_black(sq)
+            };
+            if (file_mask | adj) & front & enemy_pawns == 0 {
+                let rr = if c == Color::White {
+                    rank_of(sq)
+                } else {
+                    7 - rank_of(sq)
+                } as usize;
+                mg += sign * PASSED_MG[rr];
+                eg += sign * PASSED_EG[rr];
+            }
+        }
+
+        // rooks on open / half-open files
+        let mut r = pos.piece_bb(c, PieceType::Rook);
+        while r != 0 {
+            let sq = r.trailing_zeros() as Square;
+            r &= r - 1;
+            let fm = file_bb(file_of(sq));
+            if fm & pos.pieces[PieceType::Pawn.index()] == 0 {
+                mg += sign * ROOK_OPEN;
+            } else if fm & own_pawns == 0 {
+                mg += sign * ROOK_HALF;
+            }
+        }
+    }
+
+    // king danger -> superlinear penalty
+    let wd = king_danger(safety[Color::White.index()]);
+    let bd = king_danger(safety[Color::Black.index()]);
+    mg += bd - wd;
+
+    mg += mobility_mg[Color::White.index()] - mobility_mg[Color::Black.index()];
+
+    let score = (mg * ph + eg * (PHASE_MAX - ph)) / PHASE_MAX;
+    let stm = if pos.stm == Color::White { score } else { -score };
+    stm + TEMPO
+}
+
+#[inline]
+fn king_danger(units: i32) -> i32 {
+    let u = units.min(40);
+    (u * u * 3) / 8
+}
+
+fn pawn_front_span_white(sq: Square) -> Bitboard {
+    let r = rank_of(sq);
+    let mut m = 0u64;
+    for rr in (r + 1)..8 {
+        m |= rank_bb(rr);
+    }
+    m
+}
+fn pawn_front_span_black(sq: Square) -> Bitboard {
+    let r = rank_of(sq);
+    let mut m = 0u64;
+    for rr in 0..r {
+        m |= rank_bb(rr);
+    }
+    m
+}

chessathon_engine-0.1.0/src/lib.rs

@@ -0,0 +1,154 @@
+//! Python bindings for the Chessathon engine.
+//!
+//! `best_move(fen, time_left_ms, ...)` runs an iterative-deepening search and
+//! returns the chosen move in UCI. Everything heavy (movegen, eval, search)
+//! lives in Rust; `agent.py` is a thin wrapper with a pure-Python fallback.
+
+mod eval;
+mod movegen;
+mod perft;
+mod position;
+mod search;
+mod see;
+mod tables;
+mod tt;
+mod types;
+
+use position::Position;
+use pyo3::exceptions::PyValueError;
+use pyo3::prelude::*;
+use search::{Limits, Searcher};
+use std::sync::Mutex;
+use types::Move;
+
+const VERSION: &str = env!("CARGO_PKG_VERSION");
+
+// one searcher (and its TT) kept alive across calls within a process
+struct Engine {
+    searcher: Searcher,
+}
+
+fn engine() -> &'static Mutex<Engine> {
+    use std::sync::OnceLock;
+    static E: OnceLock<Mutex<Engine>> = OnceLock::new();
+    E.get_or_init(|| {
+        // touch the tables so the ~ms of magic generation happens at import
+        tables::tables();
+        Mutex::new(Engine {
+            searcher: Searcher::new(128),
+        })
+    })
+}
+
+#[pyfunction]
+fn version() -> String {
+    format!("chessathon-engine {VERSION}")
+}
+
+/// Warm the attack tables and TT. Call once at import.
+#[pyfunction]
+fn init() -> bool {
+    let guard = engine().lock().unwrap();
+    drop(guard);
+    true
+}
+
+fn parse(fen: &str) -> PyResult<Position> {
+    Position::from_fen(fen).map_err(|e| PyValueError::new_err(format!("bad fen: {e}")))
+}
+
+/// Apply a list of UCI moves to a position, so the search sees the real game
+/// history (for repetition detection).
+fn apply_moves(pos: &mut Position, moves: &[String]) -> PyResult<()> {
+    for uci in moves {
+        let legal = pos.legal_moves();
+        let mv = legal.iter().find(|m| m.to_uci() == *uci).copied();
+        match mv {
+            Some(m) => pos.make_move(m),
+            None => return Err(PyValueError::new_err(format!("illegal history move {uci}"))),
+        }
+    }
+    Ok(())
+}
+
+/// Pick a move. `budget_ms` is the soft target, `hard_ms` the absolute cap.
+/// `moves` are UCI moves already played from `fen` to reach the position to search.
+#[pyfunction]
+#[pyo3(signature = (fen, budget_ms, hard_ms, moves=Vec::new(), max_depth=64))]
+fn best_move(
+    fen: &str,
+    budget_ms: u64,
+    hard_ms: u64,
+    moves: Vec<String>,
+    max_depth: i32,
+) -> PyResult<String> {
+    let mut pos = parse(fen)?;
+    apply_moves(&mut pos, &moves)?;
+    let mut guard = engine().lock().unwrap();
+    let limits = Limits {
+        soft_ms: budget_ms,
+        hard_ms: hard_ms.max(budget_ms),
+        max_depth: max_depth.clamp(1, 120),
+        max_nodes: u64::MAX,
+    };
+    let r = guard.searcher.search(&mut pos, &limits);
+    if r.best.is_none() {
+        return Err(PyValueError::new_err("no legal move"));
+    }
+    Ok(r.best.to_uci())
+}
+
+/// Search to a fixed depth (for tests / analysis). Returns (uci, score_cp, depth, nodes).
+#[pyfunction]
+fn search_depth(fen: &str, depth: i32) -> PyResult<(String, i32, i32, u64)> {
+    let mut pos = parse(fen)?;
+    let mut guard = engine().lock().unwrap();
+    let limits = Limits {
+        soft_ms: u64::MAX,
+        hard_ms: u64::MAX,
+        max_depth: depth.clamp(1, 120),
+        max_nodes: u64::MAX,
+    };
+    let r = guard.searcher.search(&mut pos, &limits);
+    Ok((r.best.to_uci(), r.score, r.depth, r.nodes))
+}
+
+#[pyfunction]
+fn evaluate_fen(fen: &str) -> PyResult<i32> {
+    let pos = parse(fen)?;
+    Ok(eval::evaluate(&pos))
+}
+
+#[pyfunction]
+#[pyo3(name = "perft")]
+fn perft_fen(fen: &str, depth: u32) -> PyResult<u64> {
+    let mut pos = parse(fen)?;
+    Ok(perft::perft(&mut pos, depth))
+}
+
+#[pyfunction]
+fn legal_moves(fen: &str) -> PyResult<Vec<String>> {
+    let pos = parse(fen)?;
+    Ok(pos.legal_moves().iter().map(|m| m.to_uci()).collect())
+}
+
+/// Clear the transposition table (call between games).
+#[pyfunction]
+fn reset() {
+    engine().lock().unwrap().searcher.tt.clear();
+}
+
+#[pymodule]
+fn chessathon_engine(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    m.add("__version__", VERSION)?;
+    m.add_function(wrap_pyfunction!(version, m)?)?;
+    m.add_function(wrap_pyfunction!(init, m)?)?;
+    m.add_function(wrap_pyfunction!(best_move, m)?)?;
+    m.add_function(wrap_pyfunction!(search_depth, m)?)?;
+    m.add_function(wrap_pyfunction!(evaluate_fen, m)?)?;
+    m.add_function(wrap_pyfunction!(perft_fen, m)?)?;
+    m.add_function(wrap_pyfunction!(legal_moves, m)?)?;
+    m.add_function(wrap_pyfunction!(reset, m)?)?;
+    let _ = Move::none();
+    Ok(())
+}