クイックスタート

このプロジェクトは汎用的なモンテカルロ木探索（ MCTS ）フレームワークを提供します。その中核概念は、 chess-ant の遺伝的プログラミング（ GP ）エンジンを現代的な AI エージェントに置き換えることです。 AlphaZero に着想を得つつも、より簡素で分離された手法を採用しています。標準的な UCT アルゴリズムを外部 AI エージェントで拡張し、 ポリシーによる枝刈り（ Policy Pruning ） 、すなわち事前にフィルタリングされた有望な手のリストを供給することで探索空間を効率的に狭めます。

このガイドでは、パッケージのインストール方法と、 Gemini CLI のような AI エージェントで利用するための設定方法を説明します。

インストール

標準インストール

コアパッケージは pip を使い直接インストールできます：

pip install mcts-gen

ゲーム固有の依存関係を含むインストール

特定のゲームのサポートを含めるには、オプションの依存関係（ extras ）をインストールできます。

  • 将棋のサポート :

    pip install mcts-gen[shogi]

    これにより python-shogi ライブラリがインストールされます。

  • チェスのサポート :

    pip install mcts-gen[chess]

    これにより python-chess ライブラリがインストールされます。

  • リガンド生成のサポート :

    pip install mcts-gen[ligand]

    これにより、 de novo （新規）リガンド設計機能に必要な rdkit と pandas がインストールされます。この機能は、タンパク質のポケットに誘導された MCTS ベースの分子生成を可能にします。ユーザーが提供するソース分子ファイル（ SMILES 、 SDF 、または CSV ）から生成された単一原子または多原子フラグメントからのリガンド構築をサポートします。

    注釈

    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.

    注釈

    この機能は、タンパク質の結合ポケットを特定するために、外部ツール fpocket も必要とします。これは、 Debian/Ubuntu システムでは snap を使用してインストールできます :

    sudo snap install fpocket

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.

注釈

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.

以下の設定で settings.json ファイルを作成または更新してください：

{
  "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.

高度な探索と探索予算（ Search Limit ）

MCTS-Gen は、探索の精度と効率を管理し、 API の制限や繰り返しのツール呼び出しエラーを回避するための高レベルツールを提供します。

  • `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.

空間分割と予測探索 (v0.0.5+)

巨大な探索空間への対処や、未来の状態の事前計算を可能にするため、 MCTS-Gen は空間ゾーン（ Spatial Zone ）と探索スロット（ Search Slot ）を導入しました。

  • 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.

MOPACによる量子化学評価 (v0.0.4+)

高精度なリガンド設計のために、 MCTS-Gen は半経験的分子軌道法パッケージである MOPAC2022 と統合されました。これにより、生成された分子の熱力学的な安定性（生成熱）をシミュレーションで評価できるようになりました。

  • 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.

注釈

この機能を利用するには、 MOPAC2022 がインストールされ、システムパスに含まれている必要があります。アカデミックおよび個人利用向けには、 OpenMOPAC からオープンソースソフトウェアとして入手可能です。

uv でのエージェントコンテキスト設定

注釈

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.

** .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"
      ]
    }
  }
}

メンテナー向け：新しいバージョンのリリース方法

パッケージの公開プロセスは GitHub Actions を使用して自動化されています。

TestPyPI へのリリース（テスト用）

TestPyPI リポジトリにバージョンをリリースして検証するには、 -test 接尾辞を付けて git タグを作成し、プッシュします。

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

PyPI へのリリース（公式）

公式リリースを実行するには、セマンティックバージョニング形式（例： vX.Y.Z ）に従った git タグを作成してプッシュします。

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