kuzongaenv 0.2.9__tar.gz

kuzongaenv-0.2.9/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jacinto Jeje Matamba Quimua
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kuzongaenv-0.2.9/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: kuzongaenv
+Version: 0.2.9
+Summary: Gymnasium environment for the game Kuzonga
+Home-page: https://github.com/jaci-hub/kuzongaenv
+Author: Jacinto Jeje Matamba Quimua
+License: MIT
+Project-URL: Source, https://github.com/jaci-hub/kuzongaenv
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gymnasium>=0.30.0
+Requires-Dist: numpy>=1.23
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# KuzongaEnv
+
+A custom Gymnasium-compatible environment for the [Kuzonga game](https://www.kuzonga.com).
+
+## Environment Details
+### Action Space
+
+The environment uses a dictionary action space with three components:
+
+| Key       | Value       | Description |
+|-----------|------------|-------------|
+| v  | 1 or 0 (or True and False, respectively)     | Whether to attempt division (`1`) or change a digit (`0`). |
+| g     | 0–9        | If `v=1`, the divisor; if `v=0`, the new digit to set at `r`. |
+| r     | 0…digits-1 or `None` | Rindex (Right-to-left or reverse index) of the digit to overwrite (if `v=1`, it should be `None`). |
+
+
+Example:
+
+```python
+action = {"v": 1, "g": 3, "r": None}  # attempt division by 3
+action = {"v": 0, "g": 7, "r": 1}  # set the second digit (from the right) to 7
+```
+
+### Observation Space
+
+The environment uses a dictionary observation space with the following keys:
+
+| Key                        | Type                     | Description |
+|----------------------------|-------------------------|-------------|
+| s             | np.int8 array (digits,) | The original number as an array of digits. |
+| d             | np.int8 array (digits,) | The current number as an array of digits. |
+| a | np.int64 array (digits*10,) | Binary mask of which digits can be set at each position. Flattened from shape (digits, 10). |
+| p                    | np.int64 array (num_players*3,) | Each player’s `[i, c, m]`, where `i` is the ID, `c` is the score and `m` tells if it is the player's turn (`m=1`) or not (`m=0`). Flattened array of all players. It has one player by default. |
+| t                | int                      | ID of the player whose turn it is. |
+
+
+Example:
+
+```python
+obs, info = env.reset()
+print(obs["s"])   # [1, 7]
+print(obs["d"])   # [4, 7]
+print(obs["a"])   # array([1,1,0,...])
+print(obs["p"])   # array([0,0,1,1,0,0])  # two players
+print(obs["t"])   # 0
+```
+
+### Quick Notes
+
+The *a* mask ensures illegal moves (e.g., setting a leading zero or creating number 0/1) are prevented.
+
+Rewards and penalties are automatically updated in the environment during *step()*.
+
+The environment fully supports multiple players, and tracks turns via *t* and *m*.
+
+The *options* parameter in *reset()* allows resetting the environment to a specific given state/obs, by setting it with the format: `options = {'obs': <state/obs dict>}`
+
+
+## Usage Example
+
+```python
+import gymnasium as gym
+import kuzongaenv
+
+env = gym.make("Kuzonga-v0")
+obs, info = env.reset()
+action = env.action_space.sample()
+obs, reward, terminated, truncated, info = env.step(action)
+
+print(f"Observation: {obs}")
+print(f"Reward: {reward}, Terminated: {terminated}")
+```
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Cite This Project
+
+If you use **Kuzonga** in your research, projects, or publications, please cite it as:
+
+Jacinto Jeje Matamba Quimua (2025). KuzongaEnv: Gym Environment for Reinforcement Learning Experiments. GitHub repository: https://github.com/jaci-hub/kuzongaenv
+
+
+### BibTeX
+
+```bibtex
+@misc{kuzongaenv2025,
+  author       = {Jacinto Jeje Matamba Quimua},
+  title        = {KuzongaEnv: Gym Environment for Reinforcement Learning Experiments},
+  year         = 2025,
+  howpublished = {\url{https://github.com/jaci-hub/kuzongaenv}},
+}
+```
+
+## Play Kuzonga Online
+
+[Kuzonga game](https://www.kuzonga.com)

kuzongaenv-0.2.9/README.md

@@ -0,0 +1,100 @@
+# KuzongaEnv
+
+A custom Gymnasium-compatible environment for the [Kuzonga game](https://www.kuzonga.com).
+
+## Environment Details
+### Action Space
+
+The environment uses a dictionary action space with three components:
+
+| Key       | Value       | Description |
+|-----------|------------|-------------|
+| v  | 1 or 0 (or True and False, respectively)     | Whether to attempt division (`1`) or change a digit (`0`). |
+| g     | 0–9        | If `v=1`, the divisor; if `v=0`, the new digit to set at `r`. |
+| r     | 0…digits-1 or `None` | Rindex (Right-to-left or reverse index) of the digit to overwrite (if `v=1`, it should be `None`). |
+
+
+Example:
+
+```python
+action = {"v": 1, "g": 3, "r": None}  # attempt division by 3
+action = {"v": 0, "g": 7, "r": 1}  # set the second digit (from the right) to 7
+```
+
+### Observation Space
+
+The environment uses a dictionary observation space with the following keys:
+
+| Key                        | Type                     | Description |
+|----------------------------|-------------------------|-------------|
+| s             | np.int8 array (digits,) | The original number as an array of digits. |
+| d             | np.int8 array (digits,) | The current number as an array of digits. |
+| a | np.int64 array (digits*10,) | Binary mask of which digits can be set at each position. Flattened from shape (digits, 10). |
+| p                    | np.int64 array (num_players*3,) | Each player’s `[i, c, m]`, where `i` is the ID, `c` is the score and `m` tells if it is the player's turn (`m=1`) or not (`m=0`). Flattened array of all players. It has one player by default. |
+| t                | int                      | ID of the player whose turn it is. |
+
+
+Example:
+
+```python
+obs, info = env.reset()
+print(obs["s"])   # [1, 7]
+print(obs["d"])   # [4, 7]
+print(obs["a"])   # array([1,1,0,...])
+print(obs["p"])   # array([0,0,1,1,0,0])  # two players
+print(obs["t"])   # 0
+```
+
+### Quick Notes
+
+The *a* mask ensures illegal moves (e.g., setting a leading zero or creating number 0/1) are prevented.
+
+Rewards and penalties are automatically updated in the environment during *step()*.
+
+The environment fully supports multiple players, and tracks turns via *t* and *m*.
+
+The *options* parameter in *reset()* allows resetting the environment to a specific given state/obs, by setting it with the format: `options = {'obs': <state/obs dict>}`
+
+
+## Usage Example
+
+```python
+import gymnasium as gym
+import kuzongaenv
+
+env = gym.make("Kuzonga-v0")
+obs, info = env.reset()
+action = env.action_space.sample()
+obs, reward, terminated, truncated, info = env.step(action)
+
+print(f"Observation: {obs}")
+print(f"Reward: {reward}, Terminated: {terminated}")
+```
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Cite This Project
+
+If you use **Kuzonga** in your research, projects, or publications, please cite it as:
+
+Jacinto Jeje Matamba Quimua (2025). KuzongaEnv: Gym Environment for Reinforcement Learning Experiments. GitHub repository: https://github.com/jaci-hub/kuzongaenv
+
+
+### BibTeX
+
+```bibtex
+@misc{kuzongaenv2025,
+  author       = {Jacinto Jeje Matamba Quimua},
+  title        = {KuzongaEnv: Gym Environment for Reinforcement Learning Experiments},
+  year         = 2025,
+  howpublished = {\url{https://github.com/jaci-hub/kuzongaenv}},
+}
+```
+
+## Play Kuzonga Online
+
+[Kuzonga game](https://www.kuzonga.com)

kuzongaenv-0.2.9/kuzongaenv/__init__.py

@@ -0,0 +1,6 @@
+from gymnasium.envs.registration import register
+
+register(
+    id="Kuzonga-v0",
+    entry_point="kuzongaenv.envs.kuzonga_env:KuzongaEnv",
+)

kuzongaenv-0.2.9/kuzongaenv/envs/__init__.py

@@ -0,0 +1 @@
+from kuzongaenv.envs.kuzonga_env import KuzongaEnv

kuzongaenv-0.2.9/kuzongaenv/envs/kuzonga_env.py

@@ -0,0 +1,499 @@
+'''
+Name: Jacinto Jeje Matamba Quimua
+Date: 10/28/2025
+
+This is the python gym-style API for my game Kuzonga
+'''
+
+import math
+import random
+import gymnasium as gym
+from gymnasium import spaces
+import numpy as np
+import warnings
+from kuzongaenv.inspection.inspector import Inspector
+
+
+
+class KuzongaEnv(gym.Env):
+    metadata = {"render_modes": ["human"]}
+
+    def __init__(self, digits=2, players=1, render_mode=None, auto_render=False):
+        super().__init__()
+        self.players = [{"i": i, "c": 0, "m": 1 if i==0 else 0} for i in range(players)]
+        self.static_number = None
+        self.dynamic_number = None
+        self.player_turn = 0
+        self.digits = digits
+        self.available_digits_per_rindex = {i: list(range(10)) for i in range(digits)}
+        self.maxScore = 9*digits
+        self.render_mode = render_mode
+        self.auto_render = auto_render
+        
+        warnings.filterwarnings(
+            "ignore",
+            message=".*Box observation space maximum and minimum values are equal.*"
+        )
+
+        # (1) Action space:
+        # action is dictionary with keys: division, digit, rindex
+        #   division (bool): true/false
+        #   digit (int): if division=true, then it is the divisor, else it is the new digit in the rindex chosen
+        #   rindex (int): if division=true, then it is None, else the rindex where the digit will be overwriten
+        self.action_space = spaces.Dict({
+            "v": spaces.Discrete(2),
+            "g": spaces.Discrete(10),
+            "r": spaces.Discrete(digits)
+        })
+
+        # (2) Observation space: 
+        # observation is a dictionary with keys: static_number, dynamic_number, available_digits_per_rindex, players, player_turn]
+        #   static_number (int): the value of the number originally generated
+        #   dynamic_number (int): the current value of the number whose digits are manipulated
+        #   available_digits_per_rindex (dict): a dictionary where the keys are the rindexes of the dynamic_number and their values are the list of digits available at that rindex
+        #   players (list): the list of dictionaries with each player's id, score and a variable (is_current_turn) that tells if it is the player's turn to play. By default there is one player in the list
+        #   player_turn (int): the id of the player with the turn
+        number_of_players = len(self.players)
+        self.observation_space = spaces.Dict({
+            "s": spaces.Box(
+                low=0,
+                high=9,
+                shape=(digits,),
+                dtype=np.int8
+            ),
+            "d": spaces.Box(
+                low=0,
+                high=9,
+                shape=(digits,),
+                dtype=np.int8
+            ),
+            "a": spaces.MultiBinary(10 * digits),
+            "p": spaces.Box(
+                low=np.array([0, -self.maxScore-8, 0] * number_of_players, dtype=np.int64),
+                high=np.array([number_of_players - 1, self.maxScore+8, 1] * number_of_players, dtype=np.int64),
+                shape=(number_of_players * 3,),
+                dtype=np.int64
+            ),
+            "t": spaces.Discrete(number_of_players)
+        })
+    
+    
+    def _encode_players(self, given_players=None):
+        '''
+        Encodes player info numerically:
+        Each player has attributes: i, c, m
+            Note: if m=1, it is the player's turn to play, else, it is not 
+        '''
+        if given_players != None:
+            self.players = given_players
+        
+        if not self.players:
+            # create a default single-player representation
+            encoded = np.zeros((1, 3), dtype=np.int64)
+            encoded[0] = [0, 0, 1]  # i=0, c=0, m=1
+            return encoded.flatten()
+        
+        num_players = len(self.players)
+        encoded = np.zeros((num_players, 3), dtype=np.int64)
+        for i, p in enumerate(self.players):
+            encoded[i, 0] = p.get("i", i)
+            encoded[i, 1] = p.get("c", 0)
+            encoded[i, 2] = 1 if i == self.player_turn else 0
+        return encoded.flatten()
+    
+    def _has_one_digit_divisor(self, num):
+        res = False
+        for i in range(2, 10):
+            if num % i == 0:
+                res = True
+                break
+        return res
+    
+    def _create_dynamic_number(self):
+        min_val = 10 ** (self.digits - 1)
+        max_val = (10 ** self.digits) - 1
+
+        num = random.randint(min_val, max_val)
+
+        while self._has_one_digit_divisor(num):
+            num = random.randint(min_val, max_val)
+
+        return int(num)
+    
+    def _get_prohibited_digit_list_at_rindex(self, rindex):
+        prohibited = set()
+        # no leading zero
+        if rindex == self.digits-1:
+            prohibited.add(0)
+
+        # can’t make number 0 or 1
+        for d in [0, 1]:
+            modified = str(self.dynamic_number)
+            modified = list(modified)        
+            if rindex > 0:
+                modified[-rindex-1] = str(d)
+            else:
+                modified[self.digits-1] = str(d)
+            modified = ''.join(modified)
+            
+            if int(modified) in (0, 1):
+                prohibited.add(d)
+
+        return list(prohibited)
+    
+    def _remove_all_prohibited_digits_at_given_rindex_from_given_list(self, rindex, digit_list):
+        prohibited_digits = set(self._get_prohibited_digit_list_at_rindex(rindex))
+        return [d for d in digit_list if d not in prohibited_digits]
+    
+    def _setup_available_digits_per_rindex(self):
+        available_digits_per_rindex = {}
+
+        for i in range(self.digits):
+            current_digit = int(str(self.dynamic_number)[self.digits-i-1])
+            all_digits = [d for d in range(10) if d != current_digit]
+            filtered_digits = self._remove_all_prohibited_digits_at_given_rindex_from_given_list(i, all_digits)
+            available_digits_per_rindex[i] = filtered_digits
+
+        return available_digits_per_rindex
+    
+    def _encode_available_digits(self, given_available_digits_per_rindex=None):
+        if given_available_digits_per_rindex is not None:
+            # convert string keys to int if necessary
+            self.available_digits_per_rindex = {
+                int(k): v for k, v in given_available_digits_per_rindex.items()
+            }
+
+        mask = np.zeros((self.digits, 10), dtype=np.int64)
+        for idx, available in self.available_digits_per_rindex.items():
+            mask[int(idx), available] = 1
+        return mask.flatten()
+
+    def reset(self, *, seed = None, options = None):
+        manual_obs = None
+        if options:
+            manual_obs = options.get('obs', None)
+        inspector = Inspector(state=manual_obs)
+        inspector.inspect_state()
+        
+        if inspector.state_passed():
+            return self._manual_reset(seed=seed, options=options)
+        
+        super().reset(seed=seed)
+        original_number = self._create_dynamic_number()
+        self.static_number = original_number
+        self.dynamic_number = original_number
+        self.available_digits_per_rindex = self._setup_available_digits_per_rindex()
+        self.player_turn = 0
+        obs = {
+            "s": np.array([int(d) for d in str(self.static_number)], dtype=np.int8),
+            "d": np.array([int(d) for d in str(self.dynamic_number)], dtype=np.int8),
+            "a": self._encode_available_digits(),
+            "p": self._encode_players(),
+            "t": np.int64(self.player_turn)
+        }
+        
+        info = {"seed": seed}
+        return obs, info
+    
+    def _manual_reset(self, *, seed = None, options = None):
+        '''
+        resets the ennvironment manually with the obs key-value dictionary (obs) as an argument.
+            if obs does not pass inspection, it falls back to the default gym-env reset
+        '''
+        super().reset(seed=seed)
+        
+        obs = None
+        if options:
+            obs = options.get('obs', None)
+        else:
+            return # It should not get here!
+        
+        # update observation space var
+        number_of_players = len(obs["p"])
+        self.maxScore = 9*len(str(obs["s"]))
+        self.observation_space = spaces.Dict({
+            "s": spaces.Box(
+                low=0,
+                high=9,
+                shape=(len(str(obs["s"])),),
+                dtype=np.int8
+            ),
+            "d": spaces.Box(
+                low=0,
+                high=9,
+                shape=(len(str(obs["d"])),),
+                dtype=np.int8
+            ),
+            "a": spaces.MultiBinary(10 * len(str(obs["d"]))),
+            "p": spaces.Box(
+                low=np.array([0, -self.maxScore-8, 0] * number_of_players, dtype=np.int64),
+                high=np.array([number_of_players - 1, self.maxScore+8, 1] * number_of_players, dtype=np.int64),
+                shape=(number_of_players * 3,),
+                dtype=np.int64
+            ),
+            "t": spaces.Discrete(number_of_players)
+        })
+        
+        # update the number of digits
+        self.digits = len(str(obs["d"]))
+        
+        self.static_number = obs["s"]
+        self.dynamic_number = obs["d"]
+        # convert string keys to int if necessary
+        self.available_digits_per_rindex = {
+            int(k): v for k, v in obs["a"].items()
+        }
+        self.players = obs["p"]
+        self.player_turn = obs["t"]
+        
+        new_obs = {
+            "s": np.array([int(d) for d in str(obs["s"])], dtype=np.int8),
+            "d": np.array([int(d) for d in str(obs["d"])], dtype=np.int8),
+            "a": self._encode_available_digits(obs["a"]),
+            "p": self._encode_players(obs["p"]),
+            "t": np.int64(obs["t"])
+        }
+        
+        info = {"seed": seed}
+        info = {"manual_reset": True}
+        return new_obs, info
+    
+    def _rindex_available_digit_list_is_empty(self, rindex):
+        if not self.available_digits_per_rindex:
+            return True
+
+        rindex_available_digit_list = self.available_digits_per_rindex[rindex]
+        return len(rindex_available_digit_list) == 0
+    
+    def _update_available_digits_per_rindex(self, rindex=None):
+        if rindex is None: # division was performed
+            for i in range(self.digits):
+                current_digit = int(str(self.dynamic_number)[self.digits-i-1])
+                rindex_available_digit_list = [d for d in self.available_digits_per_rindex[i] if d != current_digit]
+                rindex_available_digit_list = self._remove_all_prohibited_digits_at_given_rindex_from_given_list(i, rindex_available_digit_list)
+
+                if rindex_available_digit_list:
+                    self.available_digits_per_rindex[i] = rindex_available_digit_list
+                else:
+                    all_digits = [d for d in range(10) if d != current_digit]
+                    all_digits = self._remove_all_prohibited_digits_at_given_rindex_from_given_list(i, all_digits)
+                    self.available_digits_per_rindex[i] = all_digits
+        else: # division was not performed
+            if not self._rindex_available_digit_list_is_empty(rindex):
+                return
+            
+            current_digit = None
+            if rindex>0:
+                current_digit = int(str(self.dynamic_number)[-rindex-1])
+            else:
+                current_digit = int(str(self.dynamic_number)[self.digits-1])
+            all_digits = [d for d in range(10) if d != current_digit]
+            all_digits = self._remove_all_prohibited_digits_at_given_rindex_from_given_list(rindex, all_digits)
+            self.available_digits_per_rindex[rindex] = all_digits
+    
+    def _remove_each_quotient_digit_from_available_digits_per_rindex(self, quotient_string):
+        if not self.available_digits_per_rindex:
+            return
+
+        for i in range(len(quotient_string)):
+            rindex_available_digit_list = self.available_digits_per_rindex[i]
+            if not rindex_available_digit_list:
+                continue
+
+            digit_to_remove = int(quotient_string[self.digits-i-1])
+            rindex_available_digit_list = [d for d in rindex_available_digit_list if d != digit_to_remove]
+            self.available_digits_per_rindex[i] = rindex_available_digit_list
+    
+    def _remove_digit_from_rindex_available_digits(self, rindex, digit_to_remove):
+        if not self.available_digits_per_rindex:
+            return
+
+        rindex_available_digit_list = self.available_digits_per_rindex[rindex]
+        if not rindex_available_digit_list:
+            return
+
+        rindex_available_digit_list = [d for d in rindex_available_digit_list if d != digit_to_remove]
+        self.available_digits_per_rindex[rindex] = rindex_available_digit_list
+    
+    def _game_over(self):
+        # (1) quotient 1
+        if self.dynamic_number == 1:
+            return True
+        # (2) max points
+        for player in self.players:
+            if player["c"] >= self.maxScore:
+                return True
+        # (3) only one player left without -max points or less
+        count = 0
+        for player in self.players:
+            if player["c"] <= -self.maxScore:
+                if len(self.players) > 1:
+                    count += 1
+                else:
+                    return True
+        if len(self.players) > 1 and count == len(self.players) - 1:
+            return True
+        
+        return False
+    
+    def _update_player_turn(self):
+        if self.players:
+            self.player_turn = (self.player_turn + 1) % len(self.players)
+            if len(self.players) > 1:
+                while self.players[self.player_turn]["c"] <= -self.maxScore:
+                    self.player_turn = (self.player_turn + 1) % len(self.players)
+            self.players[self.player_turn]["m"] = 1
+            for player in self.players:
+                if player["i"] != self.players[self.player_turn]["i"]:
+                    player["m"] = 0
+    
+    def step(self, action):
+        """
+        Executes one step of the Kuzonga environment.
+        Args:
+            action (dict): {
+                "v": 0 or 1,
+                "g": int,
+                "r": int if division == 0, else None
+            }
+        Returns:
+            obs, reward, terminated, truncated, info
+        """
+        reward = 0
+        terminated = False
+        truncated = False
+        info = {}
+        
+        # check action
+        expected_keys = {"v", "g", "r"}
+        if not isinstance(action, dict):
+            reward += -5
+            info["critical"] = "Action must be a Python dictionary."
+        elif set(action.keys()) != expected_keys:
+            reward += -5
+            info["critical"] = f"Action dictionary must have exactly these keys: {', '.join(expected_keys)}."
+        else:
+            # get attributes
+            division = bool(action["v"]) if action["v"] in [0, 1, True, False] else None
+            digit = int(action["g"]) if action["g"] in range(0, 10) else None
+            rindex = int(action["r"]) if (isinstance(action["r"], (int, np.integer)) and action["r"]>=0) else None
+
+            # check division
+            if division is None:
+                reward += -5
+                info["critical"] = "The value for the division key, v, must be either True or False, or 1 or 0."
+            # check digit
+            elif digit is None:
+                reward += -5
+                info["critical"] = "Digit must be between 0-9."
+            # check rindex
+            elif rindex is None and division is None:
+                reward += -5
+                info["critical"] = "Rindex, r, must be an integer greater than or equal to 0."
+            
+            # (1) Division attempt
+            elif division:
+                # deduct points if rindex is not None
+                if rindex != None:
+                    reward += -2
+                    info["warning"] = "Rindex, r, should have not been provided!"
+                
+                if digit in [0, 1]: # not allowed to divide by 0 or 1
+                    reward += -5
+                    info["critical"] = "Division by 0 or 1 is not allowed!"
+                elif self.dynamic_number % digit == 0:
+                    self.dynamic_number = self.dynamic_number // digit
+                    # whenever the number of digits in the quotient is less than that of the original number, 
+                    #   remove the rindex key greater than the number of digits in the quotient
+                    for j in range(len(str(self.dynamic_number)), self.digits):
+                        if j in self.available_digits_per_rindex:
+                            del self.available_digits_per_rindex[j]
+                    # update the number of digits
+                    self.digits = len(str(self.dynamic_number))
+                    reward += 1
+                    # update the list of available digits per rindex
+                    #   (1) remove each quotient digit from available digits per rindex
+                    self._remove_each_quotient_digit_from_available_digits_per_rindex(str(self.dynamic_number))
+                    #   (2) update available digits per rindex
+                    self._update_available_digits_per_rindex() # no need to pass the rindex, because a division was performed
+                    # update player score
+                    if self.players:
+                        self.players[self.player_turn]["c"] += digit
+                    info["note"] = f"Divided by {digit}."
+                else:
+                    reward += -1
+                    # update player score
+                    if self.players:
+                        self.players[self.player_turn]["c"] -= digit
+                        if self.players[self.player_turn]["c"] <= -self.maxScore:
+                            # update player turn
+                            self._update_player_turn()
+                    info["note"] = f"Careful, {digit} is not a factor of {self.dynamic_number}."
+            # (2) Digit change
+            else:
+                if rindex in self.available_digits_per_rindex and digit in self.available_digits_per_rindex[rindex]:
+                    num_str = list(str(self.dynamic_number))
+                    if rindex>0:
+                        num_str[-rindex-1] = str(digit)
+                    else:
+                        num_str[len(num_str)-1] = str(digit)
+                    self.dynamic_number = "".join(num_str)
+                    self.dynamic_number = int(self.dynamic_number)
+                    reward += 1
+                    # update the list of available digits per rindex
+                    # (1) remove digit from rindex available digits
+                    self._remove_digit_from_rindex_available_digits(rindex, digit)
+                    # (2) update available digits per rindex
+                    self._update_available_digits_per_rindex(rindex)
+                    # update player turn
+                    self._update_player_turn()
+                    info["note"] = f"Updated digit at rindex r={rindex} to {digit}."
+                else:
+                    reward += -2
+                    info["warning"] = f"Cannot update the digit at rindex r={rindex} to {digit}."
+
+        # Check if game is over
+        if self._game_over():
+            terminated = True
+            
+            if reward > 0:
+                reward += 10
+            else:
+                reward -= 10
+            
+            info["concluded"] = True
+
+        # Create Observation
+        obs = {
+            "s": np.array([int(d) for d in str(self.static_number)], dtype=np.int8),
+            "d": np.array([int(d) for d in str(self.dynamic_number)], dtype=np.int8),
+            "a": self._encode_available_digits(),
+            "p": self._encode_players(),
+            "t": np.int64(self.player_turn)
+        }
+        
+        # Render to see output
+        if self.render_mode == "human" and getattr(self, "auto_render", True):
+            self.render()
+
+        return obs, float(reward), terminated, truncated, info
+
+
+    def render(self):
+        if self.render_mode == "human":
+            print()
+            print(f"Static Number: {self.static_number}")
+            print(f"Dynamic Number: {self.dynamic_number}")
+            print(f"Available digits per rindex: {self.available_digits_per_rindex}")
+            print(f"Turn: Player{self.player_turn}")
+            print('*** Scoreboard ***')
+            for p in self.players:
+                id = p["i"]
+                score = p["c"]
+                print(f"Player{id}: {score} pts")
+            print('******************')
+
+
+    def close(self):
+        return super().close()
+    

kuzongaenv-0.2.9/kuzongaenv/inspection/inspector.py

@@ -0,0 +1,269 @@
+import kuzongaenv
+import json
+import os
+import numpy as np
+from kuzongaenv.utils.logger import EpisodeLogger
+
+# base dir
+BASE_DIR = './kuzongax/inspection/logs'
+# categories
+ACTION = 'action'
+STATE = 'state'
+# types
+CRITICAL = 'critical'
+WARNING = 'warning'
+NOTE = 'note'
+SCORE = 'score'
+
+class Inspector():
+    def __init__(self, action=None, state=None):
+        self.action = action
+        # action keys
+        self.division = None
+        self.digit = None
+        self.rindex = None
+        
+        self.state = state
+        # state keys
+        self.static_number = None
+        self.dynamic_number = None
+        self.available_digits_per_rindex = None
+        self.players = None
+        self.player_turn = None
+        
+        # scores
+        self.action_score = 10
+        self.state_score = 40
+        self.overall_score = self.action_score + self.state_score
+        self.action_passing_score = 10
+        self.state_passing_score = 40
+        self.overall_passing_score = self.action_passing_score + self.state_passing_score
+                
+        # Logging
+        self.logger = EpisodeLogger(BASE_DIR)
+    
+    def get_action(self):
+        return self.action
+    
+    def get_state(self):
+        return self.state
+    
+    def inspect_action(self):
+        '''
+        inspect the action, to ensure it follows the format of the game Kuzonga
+        '''
+        # check action
+        expected_keys = {"v", "g", "r"}
+        if not isinstance(self.action, dict):
+            self.action_score -= 10
+            message = "Action must be a Python dictionary."
+            self.logger.add_info(ACTION, CRITICAL, message)
+        elif set(self.action.keys()) != expected_keys:
+            self.action_score -= 9
+            message = f"Action dictionary must have exactly these keys: {', '.join(expected_keys)}."
+            self.logger.add_info(ACTION, CRITICAL, message)
+        else:
+            # get key values
+            if self.action["v"] in [0, 1, True, False]:
+                self.division = bool(self.action["v"])
+            if self.action["g"] in range(0, 10):
+                self.digit = int(self.action["g"])
+            if (isinstance(self.action["r"], (int, np.integer)) and self.action["r"] >= 0):
+                self.rindex = int(self.action["r"])
+
+            # check division
+            if self.division is None:
+                self.action_score -= 7
+                message = "The value for the division attribute must be either True or False, or 1 or 0."
+                self.logger.add_info(ACTION, CRITICAL, message)
+            # check digit
+            elif self.digit is None:
+                self.action_score -= 7
+                message = "Digit must be between 0-9."
+                self.logger.add_info(ACTION, CRITICAL, message)
+            # check rindex
+            elif self.rindex is None and self.division is None:
+                self.action_score -= 7
+                message = "*Rindex, r, must be an integer greater than or equal to 0."
+                self.logger.add_info(ACTION, CRITICAL, message)
+                
+            # Division attempt
+            elif self.division:
+                # deduct points if rindex is not None
+                if self.rindex != None:
+                    self.action_score -= 2
+                    message = "Rindex, r, should have not been provided!"
+                    self.logger.add_info(ACTION, WARNING, message)
+                    
+        message = self.action_score
+        self.logger.add_info(ACTION, SCORE, message)
+        # log
+        if self.logger.info not in self.logger.episode_log:
+            self.logger.episode_log.append(self.logger.info)
+    
+    def inspect_state(self):
+        '''
+        inspect the state, to ensure it follows the format of the game Kuzonga
+        '''
+        # check state
+        expected_keys = {"s", "d", "a", "p", "t"}
+        if not isinstance(self.state, dict):
+            self.state_score -= 40
+            message = "State must be a Python dictionary."
+            self.logger.add_info(STATE, CRITICAL, message)
+        elif set(self.state.keys()) != expected_keys:
+            self.state_score -= 38
+            message = f"State dictionary must have exactly these keys: {', '.join(expected_keys)}."
+            self.logger.add_info(STATE, CRITICAL, message)
+        else:
+            # get attributes
+            #   (0) check static_number
+            if (isinstance(self.state["s"], (int, np.integer)) and self.state["s"] > 0):
+                self.static_number = self.state["s"]
+            else:
+                self.state_score -= 7
+                message = "The static number, s, must be a non-negative integer."
+                self.logger.add_info(STATE, CRITICAL, message)
+            
+            #   (1) check dynamic_number
+            if (isinstance(self.state["d"], (int, np.integer)) and self.state["d"] > 0):
+                self.dynamic_number = self.state["d"]
+            else:
+                self.state_score -= 7
+                message = "The dynamic number, d, must be a non-negative integer."
+                self.logger.add_info(STATE, CRITICAL, message)
+            
+            #   (2) check available digits per rindex
+            field = "a"
+            value = self.state.get(field, None)
+            # (2.1) Must be a dictionary
+            if not isinstance(value, dict):
+                self.state_score -= 7
+                message = f"'{field}' must be a Python dictionary."
+                self.logger.add_info(STATE, CRITICAL, message)
+                return
+            # (2.2) Must not be empty
+            if len(value) == 0:
+                self.state_score -= 6
+                message = f"'{field}' dictionary must not be empty."
+                self.logger.add_info(STATE, CRITICAL, message)
+                return
+            # (2.3) Validate keys and values
+            for k, v in value.items():
+                # Key must be an integer ≥ 0
+                if isinstance(k, (int, np.integer)) and 0 <= k < len(str(self.static_number)) == False:
+                    self.state_score -= 5
+                    message = f"Key '{k}' in '{field}' must be a non-negative integer."
+                    self.logger.add_info(STATE, CRITICAL, message)
+                    break
+                # Value must be a list
+                if not isinstance(v, list):
+                    self.state_score -= 5
+                    message = f"Value for key '{k}' in '{field}' must be a Python list."
+                    self.logger.add_info(STATE, CRITICAL, message)
+                    break
+                # Each element must be a unique integer digit between 0–9
+                if not all(isinstance(d, (int, np.integer)) and 0 <= d <= 9 for d in v):
+                    self.state_score -= 4
+                    message = f"All elements in '{field}[{k}]' must be digits between 0 and 9."
+                    self.logger.add_info(STATE, CRITICAL, message)
+                    break
+                if len(v) != len(set(v)):
+                    self.state_score -= 3
+                    message = f"Duplicate digits found in '{field}[{k}]'."
+                    self.logger.add_info(STATE, WARNING, message)
+            # (2.4) Assign valid value
+            self.available_digits_per_rindex = value
+            
+            #   (3) check players
+            if isinstance(self.state["p"], list):
+                # check the length
+                if len(self.state["p"]) == 0:
+                    self.state_score -= 6
+                    message = "players list must have at least one player."
+                    self.logger.add_info(STATE, CRITICAL, message)
+                else:
+                    # check the player keys
+                    expected_players_key = {"i", "c", "m"}
+                    for player in self.state["p"]:
+                        if set(player.keys()) != expected_players_key:
+                            self.state_score -= 5
+                            message = f"player must have exactly these keys: {', '.join(expected_players_key)}."
+                            self.logger.add_info(STATE, CRITICAL, message)
+                            break
+                        else:
+                            # check the value of the keys
+                            #   id
+                            if not (isinstance(player["i"], (int, np.integer)) and 0 <= player["i"] < len(self.state["p"])):
+                                self.state_score -= 4
+                                message = "The player id, i, must be a non-negative integer less than the number of players."
+                                self.logger.add_info(STATE, CRITICAL, message)
+                                break
+                            #   score
+                            elif not (isinstance(player["c"], (int, np.integer)) and -9*len(str(self.static_number)) - 8 <= player["c"] <= 9*len(str(self.static_number)) + 8):
+                                self.state_score -= 4
+                                message = "The player score, c, must satisfy: -9*(the original number of digits) - 8 <= c <= 9*(the original number of digits) + 8."
+                                self.logger.add_info(STATE, CRITICAL, message)
+                                break
+                            #   is_current_turn
+                            elif not (isinstance(player["m"], (int, np.integer)) and 0 <= player["m"] <= 1):
+                                self.state_score -= 4
+                                message = "m must be 1 or 0, which means that it is the player's turn or not, respectivelly."
+                                self.logger.add_info(STATE, CRITICAL, message)
+                                break
+                            # assign valid value for players
+                            self.players = self.state["p"]
+            else:
+                self.state_score -= 7
+                message = "players must be a Python list."
+                self.logger.add_info(STATE, CRITICAL, message)
+            
+            #   (4) check player_turn
+            if self.players is not None:
+                if (isinstance(self.state["t"], (int, np.integer)) and 0 <= self.state["t"] < len(self.players)):
+                    self.player_turn = int(self.state["t"])
+            if self.player_turn is None:
+                self.state_score -= 7
+                message = "The player turn must be a non-negative integer less than the number of players."
+                self.logger.add_info(STATE, CRITICAL, message)
+                
+        message = self.state_score
+        self.logger.add_info(STATE, SCORE, message)
+        # log
+        if self.logger.info not in self.logger.episode_log:
+            self.logger.episode_log.append(self.logger.info)
+    
+    def inspect_all(self):
+        '''
+        inspect both the action and the state, to ensure they follow the format of the game Kuzonga
+        '''
+        self.inspect_action()
+        self.inspect_state()
+        self.logger.save_episode()
+    
+    def get_action_score(self):
+        return self.action_score
+    
+    def action_passed(self):
+        return self.action_passing_score == self.action_score
+    
+    def get_state_score(self):
+        return self.state_score
+    
+    def state_passed(self):
+        return self.state_passing_score == self.state_score
+    
+    def get_overall_score(self):
+        return self.overall_score
+    
+    def all_passed(self):
+        return self.overall_score == self.overall_passing_score
+    
+    def get_action_passing_score(self):
+        return self.action_passing_score
+    
+    def get_state_passing_score(self):
+        return self.state_passing_score
+    
+    def get_overall_passing_score(self):
+        return self.overall_passing_score

kuzongaenv-0.2.9/kuzongaenv/utils/logger.py

@@ -0,0 +1,40 @@
+import json
+import os
+from datetime import datetime
+
+SCORE = 'score'
+
+class EpisodeLogger:
+    def __init__(self, base_dir="./logs"):
+        os.makedirs(base_dir, exist_ok=True)
+        self.base_dir = base_dir
+        self.info = {}
+        self.episode = 0
+        self.episode_log = []
+
+    def add_info(self, category=None, type=None, message=None):
+        if category not in self.info:
+            self.info[category] = {}
+
+        if type not in self.info[category]:
+            if type != SCORE:
+                self.info[category][type] = []
+                self.info[category][type].append(message)
+            else:
+                self.info[category][type] = message
+        else:
+            if type != SCORE:
+                self.info[category][type].append(message)
+            else:
+                self.info[category][type] = message
+    
+    def save_episode(self):
+        if not self.episode_log:
+            return
+        
+        ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+        path = os.path.join(self.base_dir, f"episode_{self.episode}_{ts}.json")
+        with open(path, "w") as f:
+            json.dump(self.episode_log, f, indent=2)
+        self.episode += 1
+        return path

kuzongaenv-0.2.9/kuzongaenv.egg-info/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: kuzongaenv
+Version: 0.2.9
+Summary: Gymnasium environment for the game Kuzonga
+Home-page: https://github.com/jaci-hub/kuzongaenv
+Author: Jacinto Jeje Matamba Quimua
+License: MIT
+Project-URL: Source, https://github.com/jaci-hub/kuzongaenv
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gymnasium>=0.30.0
+Requires-Dist: numpy>=1.23
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# KuzongaEnv
+
+A custom Gymnasium-compatible environment for the [Kuzonga game](https://www.kuzonga.com).
+
+## Environment Details
+### Action Space
+
+The environment uses a dictionary action space with three components:
+
+| Key       | Value       | Description |
+|-----------|------------|-------------|
+| v  | 1 or 0 (or True and False, respectively)     | Whether to attempt division (`1`) or change a digit (`0`). |
+| g     | 0–9        | If `v=1`, the divisor; if `v=0`, the new digit to set at `r`. |
+| r     | 0…digits-1 or `None` | Rindex (Right-to-left or reverse index) of the digit to overwrite (if `v=1`, it should be `None`). |
+
+
+Example:
+
+```python
+action = {"v": 1, "g": 3, "r": None}  # attempt division by 3
+action = {"v": 0, "g": 7, "r": 1}  # set the second digit (from the right) to 7
+```
+
+### Observation Space
+
+The environment uses a dictionary observation space with the following keys:
+
+| Key                        | Type                     | Description |
+|----------------------------|-------------------------|-------------|
+| s             | np.int8 array (digits,) | The original number as an array of digits. |
+| d             | np.int8 array (digits,) | The current number as an array of digits. |
+| a | np.int64 array (digits*10,) | Binary mask of which digits can be set at each position. Flattened from shape (digits, 10). |
+| p                    | np.int64 array (num_players*3,) | Each player’s `[i, c, m]`, where `i` is the ID, `c` is the score and `m` tells if it is the player's turn (`m=1`) or not (`m=0`). Flattened array of all players. It has one player by default. |
+| t                | int                      | ID of the player whose turn it is. |
+
+
+Example:
+
+```python
+obs, info = env.reset()
+print(obs["s"])   # [1, 7]
+print(obs["d"])   # [4, 7]
+print(obs["a"])   # array([1,1,0,...])
+print(obs["p"])   # array([0,0,1,1,0,0])  # two players
+print(obs["t"])   # 0
+```
+
+### Quick Notes
+
+The *a* mask ensures illegal moves (e.g., setting a leading zero or creating number 0/1) are prevented.
+
+Rewards and penalties are automatically updated in the environment during *step()*.
+
+The environment fully supports multiple players, and tracks turns via *t* and *m*.
+
+The *options* parameter in *reset()* allows resetting the environment to a specific given state/obs, by setting it with the format: `options = {'obs': <state/obs dict>}`
+
+
+## Usage Example
+
+```python
+import gymnasium as gym
+import kuzongaenv
+
+env = gym.make("Kuzonga-v0")
+obs, info = env.reset()
+action = env.action_space.sample()
+obs, reward, terminated, truncated, info = env.step(action)
+
+print(f"Observation: {obs}")
+print(f"Reward: {reward}, Terminated: {terminated}")
+```
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Cite This Project
+
+If you use **Kuzonga** in your research, projects, or publications, please cite it as:
+
+Jacinto Jeje Matamba Quimua (2025). KuzongaEnv: Gym Environment for Reinforcement Learning Experiments. GitHub repository: https://github.com/jaci-hub/kuzongaenv
+
+
+### BibTeX
+
+```bibtex
+@misc{kuzongaenv2025,
+  author       = {Jacinto Jeje Matamba Quimua},
+  title        = {KuzongaEnv: Gym Environment for Reinforcement Learning Experiments},
+  year         = 2025,
+  howpublished = {\url{https://github.com/jaci-hub/kuzongaenv}},
+}
+```
+
+## Play Kuzonga Online
+
+[Kuzonga game](https://www.kuzonga.com)

kuzongaenv-0.2.9/kuzongaenv.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+setup.py
+kuzongaenv/__init__.py
+kuzongaenv.egg-info/PKG-INFO
+kuzongaenv.egg-info/SOURCES.txt
+kuzongaenv.egg-info/dependency_links.txt
+kuzongaenv.egg-info/requires.txt
+kuzongaenv.egg-info/top_level.txt
+kuzongaenv/envs/__init__.py
+kuzongaenv/envs/kuzonga_env.py
+kuzongaenv/inspection/__init__.py
+kuzongaenv/inspection/inspector.py
+kuzongaenv/utils/__init__.py
+kuzongaenv/utils/logger.py

kuzongaenv-0.2.9/kuzongaenv.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kuzongaenv-0.2.9/kuzongaenv.egg-info/requires.txt

@@ -0,0 +1,2 @@
+gymnasium>=0.30.0
+numpy>=1.23

kuzongaenv-0.2.9/kuzongaenv.egg-info/top_level.txt

@@ -0,0 +1 @@
+kuzongaenv

kuzongaenv-0.2.9/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=65", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kuzongaenv"
+version = "0.2.9"
+description = "Gymnasium environment for the game Kuzonga"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+    { name="Jacinto Jeje Matamba Quimua" }
+]
+dependencies = [
+    "gymnasium>=0.30.0",
+    "numpy>=1.23"
+]
+
+[project.urls]
+"Source" = "https://github.com/jaci-hub/kuzongaenv"

kuzongaenv-0.2.9/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kuzongaenv-0.2.9/setup.py

@@ -0,0 +1,22 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="kuzongaenv",
+    version="0.2.9",
+    author="Jacinto Jeje Matamba Quimua",
+    description="A custom Gymnasium-compatible environment for the Kuzonga",
+    long_description=open("README.md", encoding="utf-8").read(),
+    long_description_content_type="text/markdown",
+    packages=find_packages(),
+    install_requires=[
+        "gymnasium>=0.30.0",
+        "numpy>=1.23"
+    ],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Operating System :: OS Independent",
+    ],
+    url="https://github.com/jaci-hub/kuzongaenv",
+    license="MIT",
+    python_requires=">=3.11",
+)