USI プロトコル（rsshogi.usi / USI 局面解析）

rsshogi.usi は USI（Universal Shogi Interface）プロトコルの文字列と構造化オブジェクトを相互変換するステートレスなモジュールである。 また、rsshogi.core には USI の position コマンド文字列を検証、分解、正規化する関数群が用意されている。

from rsshogi.core import (
    UsiPositionParts,
    normalize_usi_position,
    parse_usi_position,
    parse_usi_position_parts,
)
from rsshogi.usi import (
    MAX_PLY,
    VALUE_MATE,
    VALUE_MATE_IN_MAX_PLY,
    UsiBestMove,
    UsiBound,
    UsiGoCommand,
    UsiInfo,
    UsiScore,
    move_from_usi,
    parse_bestmove,
    parse_info,
    parse_score,
)

定数と指し手変換（rsshogi.usi）

Note

rsshogi.core.Move.from_usi(usi) は通常の指し手と "0000"（パス手）のみを受理し、"resign" や "win" には ValueError を送出する。エンジンの bestmove トークンを扱う場合は rsshogi.usi.move_from_usi(usi) または parse_bestmove(line) を使用する。

スコアと探索情報の解析（UsiScore / UsiBound / UsiInfo）

UsiBound

探索評価値が真の値のどの境界であるかを表す列挙型（IntEnum）である。

UsiScore

USI の score cp <x> および score mate <y> を表すイミュータブルなデータクラスである。

UsiInfo

UsiInfo.parse(text: str) -> UsiInfo
parse_info(line: str) -> UsiInfo

USI エンジンが出力する info 行の各項目を保持するイミュータブルなデータクラスである。 score トークンが含まれる場合、score プロパティには to_raw() で変換された内部整数スコアが入り、raw_score プロパティには UsiScore オブジェクトが入る。

from rsshogi.usi import UsiBound, parse_info

info = parse_info(
    "info depth 18 seldepth 26 time 450 nodes 890000 nps 1977777 hashfull 310 "
    "multipv 1 score cp 145 lowerbound pv 7g7f 3c3d 2g2f"
)
assert info.depth == 18
assert info.score == 145
assert info.raw_score is not None and info.raw_score.to_usi() == "cp 145"
assert info.bound is UsiBound.LOWER
assert [m.to_usi() for m in info.pv] == ["7g7f", "3c3d", "2g2f"]

UsiBestMove と UsiGoCommand

UsiBestMove

UsiBestMove(bestmove: Move, ponder: Move | None = None) -> UsiBestMove
UsiBestMove.parse(text: str) -> UsiBestMove
parse_bestmove(line: str) -> UsiBestMove

エンジンの bestmove 応答行を表すイミュータブルなデータクラスである。

UsiGoCommand

UsiGoCommand(
    *,
    searchmoves: tuple[Move, ...] = (),
    ponder: bool = False,
    btime: int | None = None,
    wtime: int | None = None,
    byoyomi: int | None = None,
    binc: int | None = None,
    winc: int | None = None,
    nodes: int | None = None,
    depth: int | None = None,
    mate: int | None = None,
    infinite: bool = False,
) -> UsiGoCommand

エンジンへ送信する go コマンドを組み立てるイミュータブルなデータクラスである。 mate に負の整数（例：-1）を指定すると go mate infinite として出力され、正の整数を指定すると詰み探索の制限時間（ミリ秒）として出力される。

from rsshogi.core import Move
from rsshogi.usi import UsiGoCommand, parse_bestmove

cmd = UsiGoCommand(
    searchmoves=(Move.from_usi("7g7f"), Move.from_usi("2g2f")),
    btime=60000,
    wtime=60000,
    byoyomi=10000,
    depth=20,
)
print(cmd.to_string())
# => "go searchmoves 7g7f 2g2f btime 60000 wtime 60000 byoyomi 10000 depth 20"

bm = parse_bestmove("bestmove 7g7f ponder 3c3d")
print(bm.bestmove.to_usi(), bm.ponder.to_usi() if bm.ponder else None)
# => 7g7f 3c3d

USI position 文字列の解析と正規化（rsshogi.core）

USI の position コマンド文字列（"position startpos moves 7g7f 3c3d" や "sfen ... moves ..."）を検証し、初期局面、合法手リスト、最終局面に分解する関数群が rsshogi.core に用意されている。 手順中に非合法手や不正なトークンが含まれている場合は ValueError を送出する。

UsiPositionParts

parse_usi_position_parts(position) が返すオブジェクトは以下のプロパティとメソッドを持つ。

from rsshogi.core import normalize_usi_position, parse_usi_position_parts

parts = parse_usi_position_parts("startpos moves 7g7f 3c3d")
print(parts.initial_sfen)
# => "lnsgkgsnl/1r5b1/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGKGSNL b - 1"
print(parts.move_usi)
# => ['7g7f', '3c3d']
print(parts.final_sfen)
# => "lnsgkgsnl/1r5b1/pppppp1pp/6p2/9/2P6/PP1PPPPPP/1B5R1/LNSGKGSNL b - 3"

normalized = normalize_usi_position("startpos moves 7g7f")
assert normalized == "position startpos moves 7g7f"

Board および Record との連携

• 盤面への直接適用：Board.set_usi_position(position) を使うと、Board インスタンスに初期局面と手順を直接反映できる。
• 棋譜オブジェクトとの相互変換：Record.from_usi_position(position, *, allow_special_tokens=False) と Record.to_usi_position(*, include_special_tokens=False) を使うと、開始局面が startpos であったか sfen ... であったかを保持したまま Record と相互変換できる。
• 探索テレメトリ付き棋譜の生成：対局実行ループで収集した USI 手順と評価値、ノード数、消費時間から Record を作る場合は Record.from_usi_main_line(...) を使用する。

関連項目

• 盤面管理（Board）
• 指し手クラス（Move）
• 棋譜管理（Record）