Merge pull request #92 from CurtisTechSolutions/feat/remote-python-environments

feat(python): connect local policies to remote environments

Author: nosam1998

.github/scripts/python-remote-smoke.py

@@ -0,0 +1,71 @@
+"""Compare the installed wheel's remote wrappers with a real local server."""
+import json
+from pathlib import Path
+import re
+import selectors
+import subprocess
+import tempfile
+
+import numpy as np
+from gamesforai import NativeEnv, connect, make
+
+with tempfile.TemporaryDirectory() as directory:
+    process = subprocess.Popen([
+        str(Path("target/debug/gfa").resolve()), "serve", "--sqlite",
+        str(Path(directory) / "remote.sqlite"), "--port", "0",
+    ], stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
+    try:
+        with selectors.DefaultSelector() as selector:
+            selector.register(process.stdout, selectors.EVENT_READ)
+            if not selector.select(timeout=30):
+                raise RuntimeError("server startup timed out")
+            line = process.stdout.readline()
+        match = re.search(r"http://127\.0\.0\.1:\d+", line)
+        assert match, "server did not publish a local address"
+        client = connect(match.group(), timeout=15)
+        for game in ["tictactoe", "connect4", "chess"]:
+            remote, local = client.native(game, seed=42), NativeEnv(game, seed=42)
+            for _ in range(12):
+                assert json.loads(remote.get_state()) == json.loads(local.get_state())
+                if any(local.flags()):
+                    break
+                seat = local.current_players()[0]
+                left, right = remote.frame(seat), local.frame(seat)
+                np.testing.assert_array_equal(left["observation"], right["observation"])
+                np.testing.assert_array_equal(left["action_mask"], right["action_mask"])
+                action = int(np.flatnonzero(right["action_mask"])[0])
+                assert remote.step(seat, action) == local.step(seat, action)
+        for seat in [0, 1]:
+            remote = client.make("tictactoe", seat=seat, opponent="minimax:3")
+            local = make("tictactoe", seat=seat, opponent="minimax:3")
+            left, _ = remote.reset(seed=19)
+            right, _ = local.reset(seed=19)
+            np.testing.assert_array_equal(left, right)
+            while not any(remote.native.flags()):
+                action = int(np.flatnonzero(local.action_masks())[0])
+                a, b = remote.step(action), local.step(action)
+                np.testing.assert_array_equal(a[0], b[0])
+                assert a[1:4] == b[1:4]
+        env = client.aec("tictactoe")
+        env.reset(seed=0)
+        checkpoint = env.get_state()
+        env.step(0)
+        env.set_state(checkpoint)
+        for action in [0, 3, 1, 4, 2]:
+            env.step(action)
+        assert all(env.terminations.values())
+        assert env.rewards == {"player_0": 1.0, "player_1": -1.0}
+        assert isinstance(env.render(), str)
+        env = client.make("connect4")
+        obs, info = env.reset(seed=42, options={"position_set": "connect4-solved-positions@1"})
+        assert info["curriculum"]["position_set"] == "connect4-solved-positions@1"
+    finally:
+        process.terminate()
+        try:
+            process.wait(timeout=15)
+        except subprocess.TimeoutExpired:
+            process.kill()
+            process.wait()
+            raise
+        assert process.returncode == 0, "server shutdown failed"
+print("Remote/native checkpoints, frames, Gym/AEC rewards and curricula verified")

.github/workflows/python.yml

@@ -41,6 +41,14 @@ jobs:
         env:
           POSITION_BASE_SHA: ${{ github.event.pull_request.base.sha }}
       - run: python -m pytest python/tests -q
+      - name: Build local server for remote SDK integration
+        if: runner.os == 'Linux'
+        env:
+          SQLX_OFFLINE: true
+        run: cargo build -p gfa-cli --locked
+      - name: Compare remote and native SDK against real server
+        if: runner.os == 'Linux'
+        run: python .github/scripts/python-remote-smoke.py
       - run: python examples/vector_throughput.py --output vector-benchmark.json
       - uses: actions/upload-artifact@v4
         with:

examples/remote-training.md

@@ -0,0 +1,61 @@
+# Use the SDK against a server
+
+Start `gfa serve --sqlite training.sqlite` and connect to its printed address:
+
+```python
+import os
+import gamesforai as gfa
+
+client = gfa.connect("http://127.0.0.1:8080")
+# For an authenticated deployment: gfa.connect(url, os.environ["GFA_API_KEY"])
+env = client.make("connect4", seat=0, opponent="random")
+obs, info = env.reset(seed=42)
+obs, reward, terminated, truncated, info = env.step(3)
+
+checkpoint = env.get_state()
+branch = env.clone()
+branch.set_state(checkpoint)
+
+multi = client.aec("tictactoe")
+multi.reset(seed=42)
+native = client.native("chess")
+```
+
+Gymnasium and PettingZoo use the same wrappers as local training, including
+curriculum resets, reward semantics and wrapper checkpoints. Python callbacks
+and `ChatPolicy` run in your training process using only the requested seat's
+observation and legal moves. Random opponents use the wrapper's checkpointed
+RNG. Native minimax/MCTS recommendations use the server's analysis endpoint
+and its configured budgets; the same local assistance guards apply. Remote
+Stockfish Gym configuration and vector wrappers are not yet available; native
+Stockfish/VectorEnv remain available for in-process training.
+
+`client.batch(operations)` exposes the [batch REST contract](../docs/training-batches.md)
+directly, with up to 64 independent create/reset/step/observe operations. It
+returns all row results, including errors. Callers decide whether to accept
+successful rows or treat their whole local batch as atomic.
+
+Remote environments keep **full private checkpoints in the trusted controller**.
+They do not create database matches. The server validates each supplied
+checkpoint and returns a separately projected frame. Never give checkpoints
+to a model, opponent, spectator, or benchmark participant. Policies receive
+only their seat-visible observation and legal mask.
+
+A remote transition validates the returned checkpoint, rewards, catalog, mask
+and tensor, then fetches all player frames before updating local state.
+Transport errors or a failure fetching any frame preserve the previous state.
+Gym also rolls back the entire learner/opponent exchange, including its RNG.
+Clones hold independent checkpoints and share connection configuration.
+
+Use native environments for peak throughput: remote stepping serializes full
+checkpoints and incurs HTTP round trips. Each environment controller is intended
+for one caller thread. `close()` has no server environment handle to release.
+Arrays and checkpoint dictionaries returned to callers are independent copies.
+
+The client sends an optional key only as a Bearer header, follows no redirects,
+performs no implicit retries, and caps requests at 4 MiB and responses at 8 MiB.
+`RemoteError.code` and `status` expose stable failures without response bodies,
+credentials or endpoint URLs. Timeout is a socket timeout, not a total run
+deadline. The current server is local-only and does not validate API keys;
+do not expose it through a public proxy. Use TLS for future authenticated
+remote deployments. Server and SDK engine versions must be compatible.

python/README.md

@@ -127,3 +127,7 @@ ChatPolicy uses the chat-completions protocol implemented by servers such as [vL
 Credentials are read from the named environment variable on each call; omit `api_key_env` for a server without authentication. No model or provider account is required by the engine. Structured output uses a JSON Schema with the legal moves as an enum, as supported by [vLLM structured outputs](https://docs.vllm.ai/en/latest/features/structured_outputs/). Set `structured=False` for a server that accepts the chat protocol but not that parameter; the reply must still be the exact JSON object.
 
 Requests and replies are capped at 64 KiB; output tokens and the socket timeout are configurable. Calls do not retry or follow redirects. `PolicyError.code` distinguishes malformed/illegal replies, authentication, rate limits, timeouts, and connection failures without exposing response bodies or credentials. A Gymnasium opponent failure rolls back the complete learner/opponent exchange. This synchronous adapter is for local training/evaluation code; durable server-side LLM transcripts and budgets are a separate integration.
+
+## Remote environments
+
+Use `client = gamesforai.connect(server_url)` and `client.make(...)` or `client.aec(...)` for the same wrapper API over stateless REST training. See [remote training](../examples/remote-training.md) for checkpoint ownership, batch calls, limits and current server mode.

python/gamesforai/__init__.py

@@ -6,5 +6,6 @@
 from .vector_env import VectorEnv
 from .gym_env import GameEnv, make
 from .aec_env import AECGameEnv, aec
+from .remote import Client, RemoteError, RemoteNativeEnv, connect
 
-__all__ = ["AECGameEnv", "ChatPolicy", "PolicyError", "GameEnv", "NativeEnv", "PositionSet", "StockfishPool", "VectorEnv", "aec", "games", "make"]
+__all__ = ["Client", "RemoteError", "RemoteNativeEnv", "connect", "AECGameEnv", "ChatPolicy", "PolicyError", "GameEnv", "NativeEnv", "PositionSet", "StockfishPool", "VectorEnv", "aec", "games", "make"]

python/gamesforai/aec_env.py

@@ -21,11 +21,12 @@ class AECGameEnv(AECEnv):
     metadata = {"render_modes": ["ansi"], "name": "gamesforai_v0", "is_parallelizable": False}
 
     def __init__(
-        self, game: str, *, config: dict[str, Any] | None = None, render_mode: str | None = None
+        self, game: str, *, config: dict[str, Any] | None = None, render_mode: str | None = None,
+        _native_factory=NativeEnv
     ) -> None:
         if render_mode not in (None, "ansi"):
             raise ValueError("render_mode must be None or 'ansi'")
-        self.native = NativeEnv(game, json.dumps(config or {}))
+        self.native = _native_factory(game, json.dumps(config or {}))
         self.render_mode = render_mode
         self.possible_agents = [f"player_{seat}" for seat in range(self.native.num_players)]
         self._seats = {agent: seat for seat, agent in enumerate(self.possible_agents)}

python/gamesforai/gym_env.py

@@ -37,6 +37,7 @@ def __init__(
         opponent: str | Policy = "random",
         stockfish_pool: StockfishPool | None = None,
         render_mode: str | None = None,
+        _native_factory=NativeEnv,
     ) -> None:
         if render_mode not in (None, "ansi"):
             raise ValueError("render_mode must be None or 'ansi'")
@@ -60,7 +61,7 @@ def __init__(
             raise ValueError("opponent must be a supported name or Python policy callable")
         if stockfish_pool is not None and self._stockfish is None:
             raise ValueError("stockfish_pool requires a stockfish opponent")
-        self.native = NativeEnv(game, json.dumps(config or {}))
+        self.native = _native_factory(game, json.dumps(config or {}))
         if isinstance(seat, bool) or not isinstance(seat, int) or not 0 <= seat < self.native.num_players:
             raise ValueError("seat is outside this game's player range")
         self._spec = json.loads(self.native.spec_json())