### MJAI Debugging: Docker Setup and Execution

Source: https://github.com/smly/mjai.app/blob/main/README.md

Provides commands for setting up and running the mjai-client Docker image for debugging AI. It includes pulling the latest image, launching a container, installing bot programs, and initiating an interactive debugging session.

```bash
# pull latest docker image
% docker pull docker.io/smly/mjai-client:v3

# launch
% CONTAINER_ID=`docker run -d --rm -p 28080:3000 --mount "type=bind,src=/Users/smly/gitws/mjai.app/examples/rulebase.zip,dst=/bot.zip,readonly" smly/mjai-client:v3 sleep infinity`

# install bot program
% docker exec ${CONTAINER_ID} unzip -q /bot.zip

# debug
% docker exec -it ${CONTAINER_ID} /workspace/.pyenv/shims/python -u bot.py 0
```

--------------------------------

### Install mjai Package

Source: https://github.com/smly/mjai.app/blob/main/README.md

Installs the mjai package from the Python Package Index (PyPI) using pip. This is the primary method for obtaining the simulator library.

```sh
pip install mjai
```

--------------------------------

### Install Build Tool and Build Project

Source: https://github.com/smly/mjai.app/blob/main/README.md

Installs the maturin build tool using pip and then builds the project in release mode for the aarch64-apple-darwin target, outputting the result to the 'dist' directory.

```sh
$ pip install maturin  # install build tool
$ maturin build --release --locked --target aarch64-apple-darwin --out dist
```

--------------------------------

### MJAI Debugging: HTTP Server Setup

Source: https://github.com/smly/mjai.app/blob/main/README.md

Instructions for setting up an HTTP server interface for the MJAI protocol within the Docker container. This allows for debugging by sending game events via HTTP requests.

```bash
# install http server interface of mjai protocol
% docker cp python/mjai/http_server/server.py ${CONTAINER_ID}:/workspace/00__server__.py

# http server mode. `0` is the player index.
% docker exec -it ${CONTAINER_ID} /workspace/.pyenv/shims/python 00__server__.py 0
```

--------------------------------

### Run Mahjong Simulation

Source: https://github.com/smly/mjai.app/blob/main/README.md

Simulates a mahjong game using the mjai simulator. It takes a list of submission file paths and an optional logs directory. The simulator requires Docker to be installed and accessible.

```py
import mjai

submissions = [
    "examples/shanten.zip",
    "examples/tsumogiri.zip",
    "examples/tsumogiri.zip",
    "examples/invalidbot2.zip",
]
mjai.Simulator(submissions, logs_dir="./logs").run()
```

--------------------------------

### MJAI Debugging: Interactive Shell Example

Source: https://github.com/smly/mjai.app/blob/main/README.md

Demonstrates an interactive debugging session using the MJAI client within a Docker container. It shows the input game events and the corresponding AI output, allowing step-by-step analysis of AI behavior.

```json
[{"type":"start_game","id":0}]  <-- Input
{"type":"none"}  <-- Output
```

```json
[{"type":"start_kyoku","bakaze":"E","dora_marker":"2s","kyoku":1,"honba":0,"kyotaku":0,"oya":0,"scores":[25000,25000,25000,25000],"tehais":[[...]]},{"type":"tsumo","actor":0,"pai":"1m"}]  <-- Input
{"type": "dahai", "actor": 0, "pai": "C", "tsumogiri": false}  <-- Output
```

```json
[{"type":"dahai","actor":0,"pai":"C","tsumogiri":false},{"type":"tsumo","actor":1,"pai":"?"},{"type":"dahai","actor":1,"pai":"3m","tsumogiri":false},{"type":"tsumo","actor":2,"pai":"?"},{"type":"dahai","actor":2,"pai":"1m","tsumogiri":false}]  <-- Input
{"type": "none"}  <-- Output
```

```json
[{"type":"tsumo","actor":3,"pai":"?"},{"type":"dahai","actor":3,"pai":"1m","tsumogiri":false}]  <-- Input
{"type": "none"}  <-- Output
```

```json
[{"type":"tsumo","actor":0,"pai":"C"}]  <-- Input
{"type": "dahai", "actor": 0, "pai": "C", "tsumogiri": true}  <-- Output
```

--------------------------------

### Develop Mjai Protocol Bot

Source: https://github.com/smly/mjai.app/blob/main/README.md

Provides a base class `Bot` for creating mahjong AI bots that communicate using the mjai protocol. The example demonstrates a simple rule-based bot that prioritizes specific actions like tsumo agari, ron agari, or riichi.

```py
from mjai import Bot
import sys


class RulebaseBot(Bot):
    def think(self) -> str:
        if self.can_tsumo_agari:
            return self.action_tsumo_agari()
        elif self.can_ron_agari:
            return self.action_ron_agari()
        elif self.can_riichi:
            return self.action_riichi()

        ...

if __name__ == "__main__":
    RulebaseBot(player_id=int(sys.argv[1])).start()
```

--------------------------------

### MJAI Game Events and Flow

Source: https://github.com/smly/mjai.app/blob/main/README.md

Demonstrates the sequence of MJAI events during a Mahjong game, including starting a game, ending a round, and player actions like tsumo (drawing a tile) and dahai (discarding a tile). This is crucial for understanding the game state and AI decision-making.

```json
[{"type":"start_game","names":["0","1","2","3"],"id":0}]
```

```json
{"type":"none"}
```

```json
[{"type":"end_kyoku"}]
```

```json
[{"type":"start_kyoku","bakaze":"S","dora_marker":"1p","kyoku":2,"honba":2,"kyotaku":0,"oya":1,"scores":[800,61100,11300,26800],"tehais":[[...]]},{"type":"tsumo","actor":1,"pai":"?"},{"type":"dahai","actor":1,"pai":"F","tsumogiri":false},{"type":"tsumo","actor":2,"pai":"?"},{"type":"dahai","actor":2,"pai":"3m","tsumogiri":true},{"type":"tsumo","actor":3,"pai":"?"},{"type":"dahai","actor":3,"pai":"1m","tsumogiri":true},{"type":"tsumo","actor":0,"pai":"3s"}]
```

```json
{"type":"dahai","pai":"3s","actor":0,"tsumogiri":true}
```

--------------------------------

### MJAI Debugging: HTTP Server API Interaction

Source: https://github.com/smly/mjai.app/blob/main/README.md

Demonstrates how to interact with the MJAI HTTP server for debugging. It shows sending initial game states and subsequent game events using cURL commands to test AI responses.

```bash
% curl http://localhost:28080/
OK

% curl -X POST -d '[{"type":"start_game","id":0}]' http://localhost:28080/
{"type":"none"}
```

```bash
% cat > request.json
[{"type":"start_kyoku","bakaze":"E","dora_marker":"2s","kyoku":1,"honba":0,"kyotaku":0,"oya":0,"scores":[25000,25000,25000,25000],"tehais":[[...]]},{"type":"tsumo","actor":0,"pai":"1m"}]

% curl -X POST -d '@request.json' http://localhost:28080/
{"type":"dahai","actor":0,"pai":"6p","tsumogiri":false}
```

--------------------------------

### Core Python Dependencies

Source: https://github.com/smly/mjai.app/blob/main/docker/requirements.txt

Specifies the essential Python packages and their versions for the mjai.app project. This includes machine learning, numerical computation, and logging libraries.

```python
torch==2.2.2
numpy==1.26.4
loguru
mahjong
```

--------------------------------

### MJAI Protocol API Reference

Source: https://github.com/smly/mjai.app/blob/main/README.md

Defines the structure and types of messages exchanged within the MJAI protocol. This serves as an API reference for understanding game events and AI communication.

```APIDOC
MJAI Protocol Message Types:

start_game:
  type: "start_game"
  id: int (game id)
  names: list[str] (player names)

end_game:
  type: "end_game"
  winner: int (player id)
  scores: list[int] (final scores)

start_kyoku:
  type: "start_kyoku"
  bakaze: str (prevailing wind)
  dora_marker: str (current dora indicator)
  kyoku: int (current round number, 0-3)
  honba: int (number of honba)
  kyotaku: int (number of kyotaku)
  oya: int (player id of the oya)
  scores: list[int] (current scores)
  tehais: list[list[str]] (hands of each player, '?' for unknown)

end_kyoku:
  type: "end_kyoku"

tsumo:
  type: "tsumo"
  actor: int (player id who drew)
  pai: str (drawn tile)

dahai:
  type: "dahai"
  actor: int (player id who discarded)
  pai: str (discarded tile)
  tsumogiri: bool (true if discarded without changing hand)

pon:
  type: "pon"
  actor: int (player id who called pon)
  target: int (player id who discarded the tile)
  pai: str (discarded tile)
  consumed: list[str] (the three tiles forming the pon)

chi:
  type: "chi"
  actor: int (player id who called chi)
  target: int (player id who discarded the tile)
  pai: str (discarded tile)
  consumed: list[str] (the three tiles forming the chi)

ankan:
  type: "ankan"
  actor: int (player id who performed ankan)
  consumed: list[str] (the four identical tiles)

dora:
  type: "dora"
  dora_marker: str (new dora indicator)

open_kan:
  type: "open_kan"
  actor: int (player id who opened the kan)
  target: int (player id who discarded the tile)
  pai: str (discarded tile)
  consumed: list[str] (the three tiles forming the meld)
  open_kan_tiles: list[str] (the fourth tile forming the kan)

none:
  type: "none" (placeholder for no action)
```

--------------------------------

### Clean Up Stale Docker Containers

Source: https://github.com/smly/mjai.app/blob/main/README.md

Removes all terminated Docker containers associated with the `smly/mjai-client:v3` image. This is useful for freeing up resources and preventing potential conflicts if new containers fail to launch due to port issues.

```sh
% for cid in `docker ps -a --filter ancestor=smly/mjai-client:v3 --format \"{{.ID}}\"`; do docker rm -f $cid; done
```

--------------------------------

### Furiten Case Study: Player Cannot Ron

Source: https://github.com/smly/mjai.app/blob/main/README.md

Illustrates a Furiten scenario where a player cannot call Ron even if the waiting tile is discarded. This occurs when the player has already discarded a tile that matches their current wait, making their hand invalid for Ron.

```json
[{"type":"dahai","actor":3,"pai":"P","tsumogiri":true},{"type":"tsumo","actor":0,"pai":"?"},{"type":"dahai","actor":0,"pai":"2p","tsumogiri":true},{"type":"tsumo","actor":1,"pai":"?"},{"type":"dahai","actor":1,"pai":"4m","tsumogiri":true},{"type":"tsumo","actor":2,"pai":"?"},{"type":"dahai","actor":2,"pai":"6m","tsumogiri":true}]
```

--------------------------------

### Ankan (Concealed Kan) Event Sequence

Source: https://github.com/smly/mjai.app/blob/main/README.md

Details the event order for an Ankan (concealed kan) action. The 'dora' event typically precedes the 'tsumo' event when an Ankan is performed, followed by the player's discard.

```json
[{"type":"ankan","actor":3,"consumed":["6s","6s","6s","6s"]}]
```

```json
[{"type":"ankan","actor":3,"consumed":["6s","6s","6s","6s"]},{"type":"dora","dora_marker":"6p"},{"type":"tsumo","actor":3,"pai":"7p"}]
```

```json
{"type":"dahai","actor":3,"pai":"7p","tsumogiri":true}
```

--------------------------------

### Adjust Simulation Timeout

Source: https://github.com/smly/mjai.app/blob/main/README.md

Allows adjustment of the simulation timeout duration. The default timeout is 3.0 seconds. Increasing this value can prevent timeout errors when debugging on non-native architectures that require emulation.

```py
Simulator(submissions, logs_dir="./logs", timeout=20.0).run()
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.