kuzongavis 0.1.3

To help visualize the game graph

KuzongaVis

Author: Jacinto Jeje Matamba Quimua

Date: March 2026

Overview

KuzongaVis is a Python utility designed to generate and represent the state-space graph of the Kuzonga game as an adjacency list. The graph encodes all reachable game states (nodes) at a given depth, and valid transitions (edges) from a given initial state, making it suitable for:

• Visualization pipelines
• Graph search algorithms (BFS, DFS, A*, etc.)
• Reinforcement learning analysis
• Game complexity exploration

The Kuzonga game environment is accessed via a Gymnasium-compatible interface (Kuzonga-v0), enabling structured interaction with the game dynamics.

Features

• Adjacency List Representation Efficient storage of nodes and edges for scalable graph traversal.

• Custom Edge Weights Supports configurable cost functions for:

  • Division operations
  • Digit-change operations

• Depth-Limited Expansion Control how far the state-space tree is expanded from the root.

• Automatic Environment Integration Uses gymnasium and kuzongaenv to simulate valid transitions.

• Utility Methods Easily query:

  • All nodes
  • All edges
  • Node degree
  • Adjacent nodes

Installation Requirements

Make sure the following dependencies are installed:

pip install gymnasium
pip install kuzongaenv

Class: KuzongaVis

Constructor

KuzongaVis(state=None, division_cost=None, digit_change_cost=None, depth=None)

Parameters

• state (dict) A Kuzonga game state (start node of the graph).

• division_cost (str | int | float) Cost for division actions:

  • None (default): cost = divisor g
  • "random": random cost in [0, 100]
  • numeric: fixed cost

• digit_change_cost (str | int | float) Cost for digit-change actions:

  • None (default): cost = 10(r + 1) + b
  • "random": random cost in [0, 100]
  • numeric: fixed cost

• depth (int) Maximum expansion depth of the graph (default = 1).

Core Methods

Graph Construction

make_adjacency_list()

Builds the graph using a breadth-first traversal up to the specified depth.

• Avoids recomputation if already built
• Handles terminal (leaf) nodes automatically
• Uses environment actions to generate valid transitions

Graph Accessors

get_adjacency_list()

Returns the full adjacency list.

all_nodes()

Returns a list of all unique nodes in the graph.

total_nodes()

Returns the total number of nodes.

Edge Utilities

all_edges()

Returns all valid edges in the graph.

total_edges()

Returns the total number of edges.

Node Utilities

adjacent_nodes(node)

Returns all valid neighboring nodes.

degree(node)

Returns the number of adjacent nodes (out-degree).

Internal Methods

These are used internally and typically not called directly:

• _is_leaf_node(node) Checks if a state is terminal.

• _node_exists(node) Ensures uniqueness of nodes in the graph.

Example Usage

from kuzongavis import KuzongaVis

# Define an initial Kuzonga state
initial_state = {...}  # valid Kuzonga state dict

# Create visualization object
graph = KuzongaVis(
    state=initial_state,
    division_cost=None,
    digit_change_cost=None,
    depth=3
)

# Build the graph
graph.make_adjacency_list()

# Access data
print("Total nodes:", graph.total_nodes())
print("Total edges:", graph.total_edges())

# Inspect adjacency list
adj_list = graph.get_adjacency_list()

Acknowledgments

• Kuzonga game environment (kuzongaenv)
• Gymnasium API for structured RL environments

Cite This Project

If you use KuzongaVis in your research, projects, or publications, please cite it as:

Jacinto Jeje Matamba Quimua (2026). KuzongaVis: A Platform for AI Experimentation. GitHub repository: https://github.com/jaci-hub/KuzongaVis

BibTeX

@misc{KuzongaVis2025,
  author       = {Jacinto Jeje Matamba Quimua},
  title        = {KuzongaVis: A Platform for AI Experimentation},
  year         = 2026,
  howpublished = {\url{https://github.com/jaci-hub/KuzongaVis}},
}