Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
104 lines (79 loc) · 4.82 KB

CONTRIBUTING.md

File metadata and controls

104 lines (79 loc) · 4.82 KB
Raw

Contributing to Micro-State-Space

First off, thank you for considering contributing to Micro-State-Space! It's people like you that make academic and research-oriented open source projects thrive.

Table of Contents

Code of Conduct

This project and everyone participating in it is governed by the Micro-State-Space Code of Conduct. By participating, you are expected to uphold this code.

How to Contribute

Reporting Bugs

Before creating bug reports, please check existing issues to see if the problem has already been reported. When creating a bug report, please include as many details as possible:

  • Use a clear and descriptive title for the issue to identify the problem.
  • Describe the exact steps which reproduce the problem in as many details as possible.
  • Provide specific examples to demonstrate the steps.
  • Describe the behavior you observed after following the steps and point out what exactly is the problem.
  • Explain which behavior you expected to see instead and why.
  • Include screenshots and animated GIFs showing the bug if possible.
  • Specify your environment: OS, Python version, Streamlit version.

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement request, please include:

  • Use a clear and descriptive title.
  • Provide a step-by-step description of the suggested enhancement.
  • Provide specific examples to demonstrate the steps.
  • Describe the current behavior and explain which behavior you expected to see instead and why.
  • Explain why this enhancement would be useful to most users.

Pull Requests

  • Fill in the required template.
  • Do not include issue numbers in the PR title.
  • Include screenshots and animated GIFs in your pull request whenever possible.
  • End files with a newline.
  • Document new code based on the Docstring guidelines.

Development Setup

  1. Fork the repository on GitHub.
  2. Clone the fork to your local machine: 
    git clone https://github.com/YOUR-USERNAME/Micro-State-Space.git
cd Micro-State-Space
  3. Create a virtual environment: 
    python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
  4. Install dependencies: 
    pip install -r requirements.txt
    (If requirements.txt is missing, run: pip install streamlit matplotlib pandas numpy)

Architecture Guidelines

Adding a New Game Environment

If you want to introduce a new micro-state environment, follow these structural requirements:

  1. Standalone File: Each game must exist as a standalone Streamlit script (e.g., new_game.py).
  2. Game Logic Class: Create a class (e.g., NewGame) that handles:
    • State representation (get_state, get_state_key)
    • Action generation (get_valid_actions or get_valid_moves)
    • State transition (make_action)
    • Terminal state checking (check_win)
    • Heuristic evaluation (evaluate_position) - crucial for Negamax.
  3. MCTS Node Class: Implement a standard MCTS node class tailored to your game's action representations.
  4. Agent Class: The agent must combine MCTS (for policy priors and exploration) and Negamax (for leaf evaluation and tactical lookahead), along with tabular Q-learning components for self-play updates.
  5. Visualization: Use Matplotlib for rendering the board state. Streamlit UI controls should remain in the sidebar.

Modifying AI Agents

When modifying the AI architecture (e.g., HexLineAgent, QuantumAgent):

  • Maintain the AlphaZero-inspired structure: MCTS uses PUCT, with leaf nodes evaluated by Negamax.
  • Ensure that any new hyperparameters (e.g., exploration constants) are exposed in the Streamlit sidebar.
  • Update the serialize_agent and deserialize_agent functions to account for new state variables to ensure save/load functionality is preserved.

Coding Standards

  • Follow PEP 8 style guidelines.
  • Use type hints (from the typing module) for all function arguments and return types.
  • Keep files self-contained where possible to align with the repository's design philosophy.
  • Provide descriptive comments for heuristic evaluation weights. Explain why a specific board configuration receives a specific bonus or penalty.

Thank you for contributing!