Quickstart

This project provides a generic Monte Carlo Tree Search (MCTS) framework. Its core concept is the replacement of the Genetic Programming (GP) engine from chess-ant with a modern AI agent. While inspired by AlphaZero, it uses a simpler, decoupled approach: the standard UCT algorithm is augmented by an external AI agent that performs Policy Pruning—narrowing the search space by supplying a pre-filtered list of promising moves.

This guide covers how to install the package and configure it for use with an AI agent like the Gemini CLI.

Installation

Standard Installation

The core package can be installed directly using pip:

pip install mcts-gen

Installation with Game-Specific Dependencies

To include support for specific games, you can install optional dependencies (extras).

For Shogi support:
```
pip install mcts-gen[shogi]
```
This installs the python-shogi library.
For Chess support:
```
pip install mcts-gen[chess]
```
This installs the python-chess library.
For Ligand Generation:
```
pip install mcts-gen[ligand]
```
This installs rdkit and pandas for de novo ligand design capabilities. This feature allows for MCTS-based molecule generation guided by a protein pocket. It supports building ligands from single atoms or multi-atom fragments generated from a user-provided file of source molecules (e.g., SMILES, SDF, or CSV).

Note

v0.0.4+ Change: The ligand generator now supports conformational diversity (including side-chain orientations) and AI-guided size control via the target_size parameter.
Note

This feature also requires the external tool fpocket for identifying protein binding pockets. It can be installed on Debian/Ubuntu systems using snap:
```
sudo snap install fpocket
```

Server Setup for Gemini CLI

To allow the Gemini agent to use the MCTS-Gen tools, you must register the server in your settings.json file. This allows the Gemini CLI to automatically manage the server process and provide the necessary context files.

Note

v0.0.2+ Change: As of version 0.0.2, the core agent instructions are built-in. Specifying a context file is no longer required for standard operation. Only configure the context block if you wish to provide additional instructions to the agent.

Create or update your settings.json file with the following configuration:

{
  "context": {
    "fileName": [
      "src/mcts_gen/AGENTS.md",
      "GEMINI.md"
    ]
  },
  "mcpServers": {
    "mcts_gen_simulator_server": {
      "command": "python",
      "args": [
        "-m",
        "mcts_gen.fastmcp_server"
      ]
    }
  }
}

Note: The context block tells the Gemini CLI to load AGENTS.md (and GEMINI.md if it exists), which is crucial for the agent to understand how to use the tools.

Advanced Search and Search Limit

MCTS-Gen provides high-level tools to manage search precision and efficiency, avoiding API throttling and repetitive tool call errors.

`run_mcts_analysis(exploration_constant, num_rounds, …)`: This tool serves as the “Search Limit” (similar to the routine() loop in chess-ant). It executes a specified number of MCTS rounds in a single batch. AI agents use this tool to strategically allocate their search budget based on the complexity of the current state.
Conformational Diversity: For ligand generation, the engine now explores diverse 3D orientations (conformations) and side-chain rotations. These are represented as distinct actions in the MCTS tree, allowing for a more granular and realistic search.

Spatial Partitioning and Predictive Search (v0.0.5+)

To handle large search spaces or pre-calculate future states, MCTS-Gen introduces spatial zones and search slots.

Spatial Partitioning: For ligand generation in large binding pockets, you can restrict the search to a specific coordinate box using the spatial_filter argument in reinitialize_mcts. This reduces the branching factor and allows for focused exploration of specific pocket regions.
Predictive Search (Slots): You can initialize multiple independent search trees in parallel using the slot_id argument. This is particularly useful for pre-calculating the best response to an opponent’s predicted moves in games like Shogi or Chess. Use activate_mcts_slot to instantly switch to a pre-calculated tree when a predicted state occurs.

Quantum Chemical Evaluation with MOPAC (v0.0.4+)

For high-precision ligand design, MCTS-Gen now integrates with MOPAC2022, a semi-empirical molecular orbital package. This allows the simulation to evaluate the thermodynamic stability (Heat of Formation) of generated molecules.

Deduplication: The fragment library now uses SMILES-based deduplication, ensuring that the MCTS search explores a unique set of chemical branches.
High-Fidelity State: The engine preserves the full RDKit molecule object, including 3D coordinates and conformers, across state transitions to provide accurate input for quantum calculations.
MOPAC Reward: Once a molecule reaches the target size, MOPAC is used to calculate its energy. Lower energy (more stable) molecules receive higher rewards.

Note

This feature requires MOPAC2022 to be installed and available in your system path. For academic and personal use, it is available as open-source software from OpenMOPAC.

Installation with uv (Recommended)

For a faster and more modern package management experience, we recommend using uv.

Install `pipx` and `uv`:

# Install pipx (a tool to install and run Python applications in isolated environments)
sudo apt install pipx

# Install uv using pipx
pipx install uv

Set up the environment and install `mcts-gen`:

# Create a virtual environment in your project directory
uv venv

# Activate the environment
source .venv/bin/activate

# Install mcts-gen with Shogi support
uv pip install mcts-gen[shogi]

To exit the virtual environment, simply run deactivate.

Configure `gemini-cli` with `fastmcp`:

Instead of manually editing settings.json, you can use the fastmcp command to automatically configure the tool server.
```
fastmcp install gemini-cli .venv/lib/python3.12/site-packages/mcts_gen/fastmcp_server.py:mcp
```
This command will automatically detect and configure the mcts_gen server, creating a .gemini/settings.json file for you.

Note on the ``:mcp`` suffix: The :mcp at the end is required because fastmcp_server.py contains multiple objects. This suffix explicitly tells fastmcp which object is the MCP server instance to be run.

Agent Context Configuration with uv

Note

v0.0.2+ Change: The instructions below are for older versions or for cases where you need to add custom, additional context. As of v0.0.2, specifying AGENTS.md is not required for the agent to function correctly.

If you installed the package using uv or pip, the AGENTS.md file is included inside the package. To allow the Gemini agent to use it, you need to specify its full path in your .gemini/settings.json file.

Add the path to the context.fileName list. The exact path may vary depending on your Python version and environment.

Example `.gemini/settings.json`:

{
  "context": {
    "fileName": [
      ".venv/lib/python3.12/site-packages/mcts_gen/AGENTS.md",
      "GEMINI.md"
    ]
  },
  "mcpServers": {
    "mcts_gen_simulator_server": {
      "command": "uv",
      "args": [
        "run",
        "fastmcp",
        "run",
        ".venv/lib/python3.12/site-packages/mcts_gen/fastmcp_server.py:mcp"
      ]
    }
  }
}

For Maintainers: How to Release a New Version

The package publication process is automated using GitHub Actions.

Releasing to TestPyPI (for testing)

To release a version to the TestPyPI repository for verification, create and push a git tag with a -test suffix.

# Example for version 0.1.0
git tag v0.1.0-test1
git push origin v0.1.0-test1

Releasing to PyPI (Official)

To perform an official release, create and push a git tag that follows the semantic versioning format (e.g., vX.Y.Z).

# Example for version 0.1.0
git tag v0.1.0
git push origin v0.1.0