kaggle-environments 1.16.11__py2.py3-none-any.whl → 1.17.3__py2.py3-none-any.whl

kaggle_environments/envs/open_spiel/games/connect_four/connect_four_proxy.py

@@ -0,0 +1,86 @@
+"""Change Connect Four state and action string representations."""
+
+import json
+from typing import Any
+
+from ... import proxy
+import pyspiel
+
+
+class ConnectFourState(proxy.State):
+  """Connect Four state proxy."""
+
+  def _player_string(self, player: int) -> str:
+    if player < 0:
+      return pyspiel.PlayerId(player).name.lower()
+    elif player == 0:
+      return 'x'
+    elif player == 1:
+      return 'o'
+    else:
+      raise ValueError(f'Invalid player: {player}')
+
+  def state_dict(self) -> dict[str, Any]:
+    # row 0 is now bottom row
+    rows = reversed(self.to_string().strip().split('\n'))
+    board = [list(row) for row in rows]
+    winner = None
+    if self.is_terminal():
+      if self.returns()[0] > self.returns()[1]:
+        winner = 'x'
+      elif self.returns()[1] > self.returns()[0]:
+        winner = 'o'
+      else:
+        winner = 'draw'
+    return {
+        'board': board,
+        'current_player': self._player_string(self.current_player()),
+        'is_terminal': self.is_terminal(),
+        'winner': winner,
+    }
+
+  def to_json(self) -> str:
+    return json.dumps(self.state_dict())
+
+  def action_to_dict(self, action: int) -> dict[str, Any]:
+    return {'col': action}
+
+  def action_to_json(self, action: int) -> str:
+    return json.dumps(self.action_to_dict(action))
+
+  def dict_to_action(self, action_dict: dict[str, Any]) -> int:
+    return int(action_dict['col'])
+
+  def json_to_action(self, action_json: str) -> int:
+    action_dict = json.loads(action_json)
+    return self.dict_to_action(action_dict)
+
+  def observation_string(self, player: int) -> str:
+    return self.observation_json(player)
+
+  def observation_json(self, player: int) -> str:
+    del player
+    return self.to_json()
+
+  def __str__(self):
+    return self.to_json()
+
+
+class ConnectFourGame(proxy.Game):
+  """Connect Four game proxy."""
+
+  def __init__(self, params: Any | None = None):
+    params = params or {}
+    wrapped = pyspiel.load_game('connect_four', params)
+    super().__init__(
+        wrapped,
+        short_name='connect_four_proxy',
+        long_name='Connect Four (proxy)',
+    )
+
+  def new_initial_state(self, *args) -> ConnectFourState:
+    return ConnectFourState(self.__wrapped__.new_initial_state(*args),
+                            game=self)
+
+
+pyspiel.register_game(ConnectFourGame().get_type(), ConnectFourGame)

kaggle_environments/envs/open_spiel/games/connect_four/connect_four_proxy_test.py

@@ -0,0 +1,57 @@
+"""Test for proxied Connect Four game."""
+
+import json
+
+from absl.testing import absltest
+from absl.testing import parameterized
+import pyspiel
+from . import connect_four_proxy as connect_four
+
+
+NUM_ROWS = 6
+NUM_COLS = 7
+
+
+class ConnectFourTest(parameterized.TestCase):
+
+  def test_game_is_registered(self):
+    game = pyspiel.load_game('connect_four_proxy')
+    self.assertIsInstance(game, connect_four.ConnectFourGame)
+
+  def test_random_sim(self):
+    game = connect_four.ConnectFourGame()
+    pyspiel.random_sim_test(game, num_sims=10, serialize=False, verbose=False)
+
+  def test_state_to_json(self):
+    game = connect_four.ConnectFourGame()
+    state = game.new_initial_state()
+    json_state = json.loads(state.to_json())
+    expected_board = [['.'] * NUM_COLS for _ in range(NUM_ROWS)]
+    self.assertEqual(json_state['board'], expected_board)
+    self.assertEqual(json_state['current_player'], 'x')
+    state.apply_action(3)
+    json_state = json.loads(state.to_json())
+    expected_board[0][3] = 'x'
+    self.assertEqual(json_state['board'], expected_board)
+    self.assertEqual(json_state['current_player'], 'o')
+    state.apply_action(2)
+    json_state = json.loads(state.to_json())
+    expected_board[0][2] = 'o'
+    self.assertEqual(json_state['board'], expected_board)
+    self.assertEqual(json_state['current_player'], 'x')
+    state.apply_action(2)
+    json_state = json.loads(state.to_json())
+    expected_board[1][2] = 'x'
+    self.assertEqual(json_state['board'], expected_board)
+    self.assertEqual(json_state['current_player'], 'o')
+
+  def test_action_to_json(self):
+    game = connect_four.ConnectFourGame()
+    state = game.new_initial_state()
+    action = json.loads(state.action_to_json(3))
+    self.assertEqual(json.loads(state.action_to_json(3)), action)
+    self.assertEqual(action['col'], 3)
+
+
+if __name__ == '__main__':
+  absltest.main()

kaggle_environments/envs/open_spiel/observation.py

@@ -0,0 +1,133 @@
+# Copyright 2019 DeepMind Technologies Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""An observation of a game.
+
+This is intended to be the main way to get observations of states in Python.
+The usage pattern is as follows:
+
+0. Create the game we will be playing
+1. Create each kind of observation required, using `make_observation`
+2. Every time a new observation is required, call:
+      `observation.set_from(state, player)`
+   The tensor contained in the Observation class will be updated with an
+   observation of the supplied state. This tensor is updated in-place, so if
+   you wish to retain it, you must make a copy.
+
+The following options are available when creating an Observation:
+ - perfect_recall: if true, each observation must allow the observing player to
+   reconstruct their history of actions and observations.
+ - public_info: if true, the observation should include public information
+ - private_info: specifies for which players private information should be
+   included - all players, the observing player, or no players
+ - params: game-specific parameters for observations
+
+We ultimately aim to have all games support all combinations of these arguments.
+However, initially many games will only support the combinations corresponding
+to ObservationTensor and InformationStateTensor:
+ - ObservationTensor: perfect_recall=False, public_info=True,
+   private_info=SinglePlayer
+ - InformationStateTensor: perfect_recall=True, public_info=True,
+   private_info=SinglePlayer
+
+Three formats of observation are supported:
+a. 1-D numpy array, accessed by `observation.tensor`
+b. Dict of numpy arrays, accessed by `observation.dict`. These are pieces of the
+   1-D array, reshaped. The np.array objects refer to the same memory as the
+   1-D array (no copying!).
+c. String, hopefully human-readable (primarily for debugging purposes)
+
+For usage examples, see `observation_test.py`.
+"""
+
+import numpy as np
+
+import pyspiel
+
+
+# Corresponds to the old information_state_XXX methods.
+INFO_STATE_OBS_TYPE = pyspiel.IIGObservationType(perfect_recall=True)
+
+
+class _Observation:
+  """Contains an observation from a game."""
+
+  def __init__(self, game, observer):
+    self._observation = pyspiel._Observation(game, observer)
+    self.dict = {}
+    if self._observation.has_tensor():
+      self.tensor = np.frombuffer(self._observation, np.float32)
+      offset = 0
+      for tensor_info in self._observation.tensors_info():
+        size = np.prod(tensor_info.shape, dtype=np.int64)
+        values = self.tensor[offset:offset + size].reshape(tensor_info.shape)
+        self.dict[tensor_info.name] = values
+        offset += size
+    else:
+      self.tensor = None
+
+  def set_from(self, state, player):
+    self._observation.set_from(state, player)
+
+  def string_from(self, state, player):
+    return (self._observation.string_from(state, player)
+            if self._observation.has_string() else None)
+
+  def compress(self):
+    return self._observation.compress()
+
+  def decompress(self, compressed_observation):
+    self._observation.decompress(compressed_observation)
+
+
+def make_observation(
+    game,
+    imperfect_information_observation_type=None,
+    params=None,
+):
+  """Returns an _Observation instance if the imperfect_information_observation_type is supported, otherwise None."""
+  params = params or {}
+  if hasattr(game, 'make_py_observer'):
+    return game.make_py_observer(imperfect_information_observation_type, params)
+  else:
+    if imperfect_information_observation_type is not None:
+      observer = game.make_observer(
+          imperfect_information_observation_type, params
+      )
+    else:
+      observer = game.make_observer(params)
+    if observer is None:
+      return None
+    return _Observation(game, observer)
+
+
+class IIGObserverForPublicInfoGame:
+  """Observer for imperfect information obvservations of public-info games."""
+
+  def __init__(self, iig_obs_type, params):
+    if params:
+      raise ValueError(f'Observation parameters not supported; passed {params}')
+    self._iig_obs_type = iig_obs_type
+    self.tensor = None
+    self.dict = {}
+
+  def set_from(self, state, player):
+    pass
+
+  def string_from(self, state, player):
+    del player
+    if self._iig_obs_type.public_info:
+      return state.history_str()
+    else:
+      return ''  # No private information to return

kaggle_environments/envs/open_spiel/open_spiel.py

@@ -0,0 +1,416 @@
+"""Kaggle environment wrapper for OpenSpiel games."""
+
+import copy
+import os
+import pathlib
+import random
+from typing import Any, Callable
+
+from kaggle_environments import core
+from kaggle_environments import utils
+import numpy as np
+import pyspiel
+from .games.connect_four import connect_four_proxy
+
+DEFAULT_ACT_TIMEOUT = 5
+DEFAULT_RUN_TIMEOUT = 1200
+DEFAULT_EPISODE_STEP_BUFFER = 100  # To account for timeouts, retrys, etc...
+
+BASE_SPEC_TEMPLATE = {
+    "name": "PLACEHOLDER_NAME",
+    "title": "PLACEHOLDER_TITLE",
+    "description": "PLACEHOLDER_DESCRIPTION",
+    "version": "0.1.0",
+    "agents": ["PLACEHOLDER_NUM_AGENTS"],
+
+    "configuration": {
+        "episodeSteps": -1,
+        "actTimeout": DEFAULT_ACT_TIMEOUT,
+        "runTimeout": DEFAULT_RUN_TIMEOUT,
+        "openSpielGameString": {
+            "description": "The full game string including parameters.",
+            "type": "string",
+            "default": "PLACEHOLDER_GAME_STRING"
+        },
+        "openSpielGameName": {
+            "description": "The short_name of the OpenSpiel game to load.",
+            "type": "string",
+            "default": "PLACEHOLDER_GAME_SHORT_NAME"
+        },
+    },
+    "observation": {
+        "properties": {
+            "openSpielGameString": {
+                "description": "Full game string including parameters.",
+                "type": "string"
+            },
+            "openSpielGameName": {
+                "description": "Short name of the OpenSpiel game.",
+                "type": "string"
+            },
+            "observation_string": {
+                "description": "String representation of state.",
+                "type": "string"
+            },
+            # TODO(jhtschultz): add legal action strings
+            "legal_actions": {
+                "description": "List of OpenSpiel legal actions.",
+                "type": "array",
+                "items": {
+                    "type": "integer"
+                }
+            },
+            "chance_outcome_probs": {
+                "description": "List of probabilities for chance outcomes.",
+                "type": "array",
+                "items": {
+                    "type": "float"
+                }
+            },
+            "current_player": {
+                "description": "ID of player whose turn it is.",
+                "type": "integer"
+            },
+            "is_terminal": {
+                "description": "Boolean indicating game end.",
+                "type": "boolean"
+            },
+            "player_id": {
+                "description": "ID of the agent receiving this observation.",
+                "type": "integer"
+            },
+            "remainingOverageTime": 60,
+            "step": 0
+        },
+        "default": {}
+    },
+    "action": {
+        "type": ["integer"],
+        "minimum": -1,
+        "default": -1
+    },
+    "reward": {
+        "type": ["number"],
+        "default": 0.0
+    },
+}
+
+
+_OS_GLOBAL_GAME = None
+_OS_GLOBAL_STATE = None
+
+
+def _get_open_spiel_game(env_config: utils.Struct) -> pyspiel.Game:
+  global _OS_GLOBAL_GAME
+  game_string = env_config.get("openSpielGameString")
+  if game_string == str(_OS_GLOBAL_GAME):
+    return _OS_GLOBAL_GAME
+  if _OS_GLOBAL_GAME is not None:
+    print(
+      f"WARNING: Overwriting game. Old: {_OS_GLOBAL_GAME}. New {game_string}"
+    )
+  _OS_GLOBAL_GAME = pyspiel.load_game(game_string)
+  return _OS_GLOBAL_GAME
+
+
+def interpreter(
+  state: list[utils.Struct],
+  env: core.Environment,
+) -> list[utils.Struct]:
+  """Updates environment using player responses and returns new observations."""
+  global _OS_GLOBAL_GAME, _OS_GLOBAL_STATE
+  kaggle_state = state
+  del state
+
+  if env.done:
+    return kaggle_state
+
+  # --- Get Game Info ---
+  game = _get_open_spiel_game(env.configuration)
+  num_players = game.num_players()
+  statuses = [
+      kaggle_state[os_current_player].status
+      for os_current_player in range(num_players)
+  ]
+  if not any(status == "ACTIVE" for status in statuses):
+    raise ValueError("Environment not done and no active agents.")
+
+  # --- Initialization / Reset ---
+  # TODO(jhtschultz): test this behavior.
+  is_initial_step = len(env.steps) == 1
+  if _OS_GLOBAL_STATE is None or (not is_initial_step and env.done):
+    _OS_GLOBAL_STATE = game.new_initial_state()
+
+  # --- Maybe apply agent action ---
+  os_current_player = _OS_GLOBAL_STATE.current_player()
+  action_applied = None
+  if is_initial_step:
+    pass
+  elif 0 <= os_current_player < num_players:
+    if kaggle_state[os_current_player].status != "ACTIVE":
+      pass
+    else:
+      action_submitted = kaggle_state[os_current_player].action
+      legal = _OS_GLOBAL_STATE.legal_actions()
+      if action_submitted in legal:
+        try:
+          _OS_GLOBAL_STATE.apply_action(action_submitted)
+          action_applied = action_submitted
+        except Exception:  # pylint: disable=broad-exception-caught
+          kaggle_state[os_current_player].status = "ERROR"
+      else:
+        kaggle_state[os_current_player].status = "INVALID"
+  elif os_current_player == pyspiel.PlayerId.SIMULTANEOUS:
+    raise NotImplementedError
+  elif os_current_player == pyspiel.PlayerId.TERMINAL:
+    pass
+  elif os_current_player == pyspiel.PlayerId.CHANCE:
+    raise ValueError("Interpreter should not be called at chance nodes.")
+  else:
+    raise ValueError(f"Unknown OpenSpiel player ID: {os_current_player}")
+
+  # --- Update state info ---
+  while _OS_GLOBAL_STATE.is_chance_node():
+    chance_outcomes = _OS_GLOBAL_STATE.chance_outcomes
+    outcomes = _OS_GLOBAL_STATE.chance_outcomes()
+    legal_actions, chance_outcome_probs = zip(*outcomes)
+    action = np.random.choice(legal_actions, p=chance_outcome_probs)
+    _OS_GLOBAL_STATE.apply_action(action)
+  is_terminal = _OS_GLOBAL_STATE.is_terminal()
+  agent_returns = _OS_GLOBAL_STATE.returns() + [None]
+  next_agent = _OS_GLOBAL_STATE.current_player()
+
+  for i, agent_state in enumerate(kaggle_state):
+    input_status = agent_state.status
+    status = ""
+    reward = None
+
+    if input_status in ["TIMEOUT", "ERROR", "INVALID"]:
+      status = input_status
+      reward = None
+    elif is_terminal:
+      status = "DONE"
+      reward = agent_returns[i]
+    elif next_agent == i:
+      status = "ACTIVE"
+      reward = agent_returns[i]
+    else:
+      status = "INACTIVE"
+      reward = agent_returns[i]
+
+    info_dict = {}
+    # Store the applied action in info for potential debugging/analysis
+    if os_current_player == i and action_applied is not None:
+      info_dict["action_applied"] = action_applied
+
+    game_type = _OS_GLOBAL_GAME.get_type()
+    obs_str = str(_OS_GLOBAL_STATE)
+    legal_actions = _OS_GLOBAL_STATE.legal_actions(i)
+
+    if status == "ACTIVE" and not legal_actions:
+      raise ValueError(
+        f"Active agent {i} has no legal actions in state {_OS_GLOBAL_STATE}."
+      )
+
+    # Apply updates
+    obs_update_dict = {
+      "observation_string": obs_str,
+      "legal_actions": legal_actions,
+      "current_player": next_agent,
+      "is_terminal": is_terminal,
+      "player_id": i,
+    }
+    for k, v in obs_update_dict.items():
+      setattr(agent_state.observation, k, v)
+    agent_state.reward = reward
+    agent_state.info = info_dict
+    agent_state.status = status
+
+  return kaggle_state
+
+
+def renderer(state: list[utils.Struct], env: core.Environment) -> str:
+  """Kaggle renderer function."""
+  try:
+    obs_str = state[-1].observation["observation_string"]
+    return obs_str if obs_str else "<Empty observation string>"
+  except Exception as e:  # pylint: disable=broad-exception-caught
+    print(f"Error rendering {env.name} at state: {state}.")
+    raise e
+
+# --- HTML Renderer Logic ---
+
+def _default_html_renderer() -> str:
+  """Provides the JavaScript string for the default HTML renderer."""
+  return """
+function renderer(context) {
+    const { parent, environment, step } = context;
+    parent.innerHTML = ''; // Clear previous rendering
+
+    const currentStepData = environment.steps[step];
+    if (!currentStepData) {
+        parent.textContent = "Waiting for step data...";
+        return;
+    }
+    const numAgents = currentStepData.length;
+    const gameMasterIndex = numAgents - 1;
+    let obsString = "Observation not available for this step.";
+    let title = `Step: ${step}`;
+
+    if (environment.configuration && environment.configuration.openSpielGameName) {
+        title = `${environment.configuration.openSpielGameName} - Step: ${step}`;
+    }
+
+    // Try to get obs_string from game_master of current step
+    if (currentStepData[gameMasterIndex] && 
+        currentStepData[gameMasterIndex].observation && 
+        typeof currentStepData[gameMasterIndex].observation.observation_string === 'string') {
+        obsString = currentStepData[gameMasterIndex].observation.observation_string;
+    } 
+    // Fallback to initial step if current is unavailable (e.g. very first render call)
+    else if (step === 0 && environment.steps[0] && environment.steps[0][gameMasterIndex] && 
+             environment.steps[0][gameMasterIndex].observation &&
+             typeof environment.steps[0][gameMasterIndex].observation.observation_string === 'string') {
+        obsString = environment.steps[0][gameMasterIndex].observation.observation_string;
+    }
+
+    const pre = document.createElement("pre");
+    pre.style.fontFamily = "monospace";
+    pre.style.margin = "10px";
+    pre.style.border = "1px solid #ccc";
+    pre.style.padding = "10px";
+    pre.style.backgroundColor = "#f9f9f9";
+    pre.style.whiteSpace = "pre-wrap";
+    pre.style.wordBreak = "break-all";
+
+    pre.textContent = `${title}\\n\\n${obsString}`;
+    parent.appendChild(pre);
+}
+"""
+
+def _get_html_renderer_content(
+    open_spiel_short_name: str,
+    base_path_for_custom_renderers: pathlib.Path,
+    default_renderer_func: Callable[[], str]
+) -> str:
+  """
+  Tries to load a custom JS renderer for the game.
+  Falls back to the default renderer if not found or on error.
+  """
+  if "proxy" not in open_spiel_short_name:
+    return default_renderer_func()
+  sanitized_game_name = open_spiel_short_name.replace('-', '_').replace('.', '_')
+  sanitized_game_name = sanitized_game_name.removesuffix("_proxy")
+  custom_renderer_js_path = (
+      base_path_for_custom_renderers /
+      sanitized_game_name /
+      f"{sanitized_game_name}.js"
+  )
+  if custom_renderer_js_path.is_file():
+    try:
+      with open(custom_renderer_js_path, "r", encoding="utf-8") as f:
+        content = f.read()
+      print(f"INFO: Using custom HTML renderer for {open_spiel_short_name} from {custom_renderer_js_path}")
+      return content
+    except Exception as e_render:
+      pass
+  return default_renderer_func()
+
+
+# --- Agents ---
+def random_agent(
+  observation: dict[str, Any],
+  configuration: dict[str, Any],
+) -> int:
+  """A built-in random agent specifically for OpenSpiel environments."""
+  del configuration
+  legal_actions = observation.get("legal_actions")
+  if not legal_actions:
+    return None
+  action = random.choice(legal_actions)
+  return int(action)
+
+
+agents = {
+  "random": random_agent,
+}
+
+
+def _register_open_spiel_envs(
+  games_list: list[str] | None = None,
+) -> dict[str, Any]:
+  successfully_loaded_games = []
+  skipped_games = []
+  registered_envs = {}
+  current_file_dir = pathlib.Path(__file__).parent.resolve()
+  custom_renderers_base = current_file_dir / "games"
+  if games_list is None:
+    games_list = pyspiel.registered_names()
+  for short_name in games_list:
+    try:
+      game = pyspiel.load_game(short_name)
+      game_type = game.get_type()
+      if not any([
+        game_type.provides_information_state_string,
+        game_type.provides_observation_string,
+      ]):
+        continue
+      game_spec = copy.deepcopy(BASE_SPEC_TEMPLATE)
+      env_name = f"open_spiel_{short_name.replace('-', '_').replace('.', '_')}"
+      game_spec["name"] = env_name
+      game_spec["title"] = f"Open Spiel: {short_name}"
+      game_spec["description"] = """
+Kaggle environment wrapper for OpenSpiel games.
+For game implementation details see:
+https://github.com/google-deepmind/open_spiel/tree/master/open_spiel/games
+""".strip()
+      game_spec["agents"] = [game.num_players()]
+      game_spec["configuration"]["episodeSteps"] = (
+          game.max_history_length() + DEFAULT_EPISODE_STEP_BUFFER
+      )
+      game_spec["configuration"]["openSpielGameString"]["default"] = str(game)
+      game_spec["configuration"]["openSpielGameName"]["default"] = short_name
+      game_spec["observation"]["properties"]["openSpielGameString"][
+          "default"] = str(game)
+      game_spec["observation"]["properties"]["openSpielGameName"][
+          "default"] = short_name
+
+      # Building html_renderer_callable is a bit convoluted but other approaches
+      # failed for a variety of reasons. Returning a simple lambda function
+      # doesn't work because of late-binding. The last env registered will
+      # overwrite all previous renderers.
+      js_string_content = _get_html_renderer_content(
+          open_spiel_short_name=short_name,
+          base_path_for_custom_renderers=custom_renderers_base,
+          default_renderer_func=_default_html_renderer,
+      )
+
+      def create_html_renderer_closure(captured_content):
+          def html_renderer_callable_no_args():
+              return captured_content
+          return html_renderer_callable_no_args
+
+      html_renderer_callable = create_html_renderer_closure(js_string_content)
+
+      registered_envs[env_name] = {
+          "specification": game_spec,
+          "interpreter": interpreter,
+          "renderer": renderer,
+          "html_renderer": html_renderer_callable,
+          "agents": agents,
+      }
+      successfully_loaded_games.append(short_name)
+
+    except Exception as e:  # pylint: disable=broad-exception-caught
+      skipped_games.append(short_name)
+      continue
+
+  print(f"""
+Successfully loaded OpenSpiel environments: {len(successfully_loaded_games)}.
+OpenSpiel games skipped: {len(skipped_games)}.
+""".strip())
+
+  return registered_envs
+
+
+registered_open_spiel_envs = _register_open_spiel_envs()