kondiplo_api/README.md

Diplomacy Calculation Engine API

ディプロマシー（Diplomacy）ボードゲームの計算エンジンとして機能する、ステートレスなFastAPIアプリケーションです。 diplomacyライブラリの計算ロジックをウェブAPIとして提供します。フロントエンドアプリケーション等から利用されることを想定しています。

主な機能

• ステートレスな計算: ゲームの状態（JSON）と命令を送り、次の状態を取得可能。
• 命令の解決 (Processing): フェイズを進行させ、命令を解決します。
• 命令の検証 (Validation): 指定された命令がルール上有効かどうかをチェック。
• 実行可能な命令の取得: 現在の盤面で各ユニットができる全命令のリストを取得。
• 可視化 (Rendering): 現在の盤面や入力中の命令を反映したSVG画像を生成。

開発環境のセットアップ

# 仮想環境の作成と有効化
python -m venv .venv
source .venv/bin/activate  # Linux/macOS

# 依存ライブラリのインストール
pip install -r requirements.txt
pip install requests  # テスト用

起動方法

推奨: Pythonコマンド

python main.py

Option: uvicornコマンド

# main.pyがルートにあるため main:app と指定します
uvicorn main:app --host 127.0.0.1 --port 8000

起動後、Swagger UIが http://127.0.0.1:8000/docs で利用可能です。

---

API エンドポイント仕様

1. マップ情報の取得

マップ一覧の取得

• URL: /maps
• Method: GET
• Description: 利用可能なマップ名の一覧を返します。

マップ詳細の取得

• URL: /maps/{map_name}
• Method: GET
• Description: 指定したマップのトポロジー情報（地域、隣接関係など）を返します。
• Example: /maps/standard

2. 計算・フェイズ進行

ゲームの進行 (Process)

現在の状態と命令を受け取り、判定を行い、次のフェイズの状態を返します。

• URL: /calculate/process

• Method: POST

• Request Body:

  {
    "game_state": { ... },  // diplomacyライブラリの Game.to_dict() 形式
    "orders": {
      "FRANCE": ["A MAR - SPA", "A PAR - BUR"],
      "ENGLAND": ["F LON - ENG"]
    }
  }
  

• Response:

  {
    "game_state": { ... } // 更新された新しいゲーム状態
  }
  

命令の検証 (Validate)

指定された命令が現在の局面で有効かどうかを検証します（フェイズは進みません）。

• URL: /calculate/validate

• Method: POST

• Request Body: process と同様（game_state と orders）

• Response:

  {
    "validated_orders": {
      "FRANCE": ["A MAR - SPA"] // 受け付けられた命令
    },
    "errors": [] // エラーがあればここにリストされます
  }
  

実行可能な命令の取得 (Possible Orders)

現在の局面で実行可能なすべての命令のリストを取得します。

• URL: /calculate/possible-orders

• Method: POST

• Query Param:

  • power_name (Optional) - 特定の国の命令のみ取得する場合に指定。
  • by_power (Optional) - trueを指定すると、結果を国ごとにグループ化して返します。

• Request Body:

  {
    "game_state": { ... } // diplomacyライブラリの Game.to_dict() 形式
  }
  

• Response:

  {
    "possible_orders": {
      "ADR": [],              // ユニットがいない地域
      "ANK": [ ... ],         // ユニットがいる地域の命令リスト
      ...
    }
  }
  

  ※ by_power=true 指定時は、以下のように国名がキーとなります：

  {
    "possible_orders": {
      "FRANCE": {
        "PAR": [ ... ],
        "MAR": [ ... ]
      },
      "ENGLAND": { ... }
    }
  }
  

  ※ power_name 指定時は、その国のユニットが存在する地域のみが含まれます。

命令の自動生成 (Auto Orders)

指定した国に対して、ランダムに有効な命令を生成します。

• URL: /calculate/auto-orders

• Method: POST

• Query Param: power_name (Required)

• Request Body:

  {
    "game_state": { ... }
  }
  

• Response:

  {
    "orders": ["A PAR - BUR", "F BRE H", ...]
  }
  

ゲームの強制終了 (Draw)

ゲームの状態を手動で「引き分け (Draw)」に変更し、フェイズを COMPLETED にします。

• URL: /game/draw

• Method: POST

• Request Body:

  {
    "game_state": { ... },  // Game.to_dict() 形式
    "winners": ["FRANCE", "GERMANY"] // (Optional) 特定の勝者を指定する場合
  }
  

• Response:

  {
    "game_state": { ... } // COMPLETED状態のゲーム
  }
  

3. 可視化 (Rendering)

マップ画像の生成

現在の状態（および入力中の命令）を反映したSVG画像を生成します。

• URL: /render

• Method: POST

• Request Body:

  {
    "game_state": { ... },
    "orders": { ... },     // Optional: 入力中の命令（矢印で描画されます）
    "incl_orders": true,   // Optional: 命令を描画するか (default: true)
    "incl_abbrev": true    // Optional: 地名の略称を表示するか (default: true)
  }
  

• Response: image/svg+xml (SVG画像データ)

プロジェクト構造

• main.py: APIサーバー実装
• test_api.py: 動作確認用スクリプト
• requirements.txt: 依存パッケージ