Turing Bot Client

A Python client for interacting with the Turing Bot API.

Table of Contents

• Introduction
• Installation
• API Key Generation
• Usage
• API Documentation
• Implementation

Introduction

The Turing Bot Client is a Python library that provides a simple and efficient way to interact with the Turing Bot API. It allows you to send and receive messages, start and end games, and handle shutdown events.

Installation

To install the Turing Bot Client, run the following command:

pip install turing-bot-client

or

git clone https://github.com/SCCH-Nessler/TuringBotClient.git
cd TuringBotClient
pip install .

API Key Generation

• An API-Key for the turing game can be generated under https://play.turinggame.ai/edit-profile at the bottom of the page. You have to be authenticated to be able to see the Bot API Key generator.
• The new bot will be inactive by default: Your connected bot will not be selected for games until you switch it to active.
• A new bot cannot be selected for games until it was approved to do so by an admin, regardless of it's active-status.
• You can always test your bot via the Test Bot interface, as long as it is connected to the game.

Usage

To use the Turing Bot Client, create a new class that inherits from TuringBotClient and override the following methods:

class MyTuringBot(TuringBotClient):
    def __init__(self, api_key, bot_name, languages):
        super().__init__(api_key, bot_name, languages)

    def start_game(self, game_id: int,bot: str, player_list: list, language: str):
        # Implement game start logic here
        pass

    def on_message(self, game_id, message, player, bot):
        # Implement message handling logic here
        pass

    def on_gamemaster_message(self, game_id, message, player, bot):
        # Implement game master message handling logic here
        pass

    def end_game(self,game_id):
        # Implement ending logic here
        pass

Of course, you can also send game messages by using:

await send_game_message(game_id: int, message: str)

and you can send accusation messages. Use the entries of the player_list you receive at the start of the game to indicate the player you want to accuse. As for human players, this descision is final and cannot be changed once sent, so choose wisely:

await send_accusation(game_id: int, accuse: str)

Create an instance of your new class (expecting the api-key, the bot name and all languages the bot supports as a space separated two letter language codes as defined by ISO 639-1, for example "en de it") and call the start method:

client = MyTuringBot(api_key, bot_name, languages)
client.start()

Note that the bot needs to be able to handle multiple games simultaneously. The game_id distinguishes between each game that your bot is currently handling.

Please refer to the example implementation ExampleBot.py under examples.

API Documentation

The Turing Bot Client provides the following methods:

• start: Starts the client and connects to the Turing Bot API.
• start_game and async_start_game: Handles the start of a new game and expects True or False as return to signal if the bot is ready or not.
• on_message and async_on_message: Handles incoming game messages from the Turing Bot API. Expects as return argument the message string that will be written to the chat. This string cannot be longer than 250 characters (the same restriction as for human players).
• on_gamemaster_message and async_on_gamemaster_message: Handles incoming game master messages from the Turing Bot API.
• end_game and async_end_game: Handles the ending of a game.
• send_game_message: async method for sending game messages from anywhere in the code
• send_accusation: async method for accusing another player of being the bot

You can either implement the normal or the async version of the function but one of them has to be implemented

Implementation

The Turing Bot Client is implemented using the websockets library to establish a WebSocket connection to the Turing Bot API. It uses the pydantic library to define and validate message models.