Metadata-Version: 2.4
Name: kuzongavis
Version: 0.1.3
Summary: To help visualize the game graph
Author: Jacinto Jeje Matamba Quimua
License: MIT
Project-URL: Homepage, https://github.com/jaci-hub/kuzongavis
Project-URL: Repository, https://github.com/jaci-hub/kuzongavis
Keywords: Explainable AI,Reinforcement Learning,Symbolic AI,Benchmark,Kuzonga
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gymnasium>=0.29
Requires-Dist: numpy>=1.23
Requires-Dist: kuzongaenv>=0.3.3
Dynamic: license-file
Dynamic: requires-python

# 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:

```bash
pip install gymnasium
pip install kuzongaenv
```

## Class: `KuzongaVis`

### Constructor

```python
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

```python
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

```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}},
}
```
