AI_AVALON : English FrontPage

( jump to Japanese FrontPage )

( jump to Download Page )
>> The latest version of the AI_AVALON system is ver.0.9.5 (20240518_1322).

AI_AVALON is a project aimed at creating an AI that can play "THE RESISTANCE: AVALON", a game that emphasizes persuasive conversations involving humans. However, enabling unrestricted conversation is currently unrealistic, so we have narrowed down and protocolized conversation flows and expressions necessary for "persuasion."

For instance, continuously making statements to increase trust for persuasion effectiveness, or offering immediate rebuttals to inhibit others' persuasive actions, might be strategies. Yet, accepting these unconditionally would make game control difficult. Therefore, in AI_AVALON, while generally giving players turns to speak in order, we allow "interrupting speech" as an act separate from the speaking turn, albeit requiring the expenditure of accrued points to acquire the right to "interrupt."

This approach enables "interrupting speech" while imposing restrictions to avoid disrupting gameplay. It also poses challenges such as determining when and at what cost effective "interrupting speech" should be made.

Please refer to the following README file for an overview of the system.

 [ README about AI AVALON ]
                          Copyright (c) 2022 Hidetoshi NAGAI
                          Copyright (c) 2022 Kyutech AI AVALON Team

*** AI_AVALON System ***

The programs and documents for the AI_AVALON system are located
in this directory.

AI_AVALON is a project aimed at creating an AI that can play
"THE RESISTANCE: AVALON", a game that emphasizes persuasive
conversations involving humans. However, enabling unrestricted
conversation is currently unrealistic, so we have narrowed down
and protocolized conversation flows and expressions necessary
for "persuasion."

For instance, continuously making statements to increase trust for
persuasion effectiveness, or offering immediate rebuttals to inhibit
others' persuasive actions, might be strategies. Yet, accepting
these unconditionally would make game control difficult. Therefore,
in AI_AVALON, while generally giving players turns to speak in order,
we allow "interrupting speech" as an act separate from the speaking
turn, albeit requiring the expenditure of accrued points to acquire
the right to "interrupt."

This approach enables "interrupting speech" while imposing restrictions
to avoid disrupting gameplay. It also poses challenges such as determining
when and at what cost effective "interrupting speech" should be made.

Details regarding the current AI_AVALON system's supported protocols
(overall flow and types of speech) are outlined in Document/Protocol.txt.
Please refer to that for more information.


*** System Configuration ***

The components of the AI_AVALON system are as follows:
--------------------------------------------------------------------------
> Server
    The core part which manages the progress of gameplay.

> Player Object
    On the server process, generated one per agent, handling interactions
    with the server and an agent.
    Each object establishes Socket (TCP or UNIX domain) communication
    channels with one client.

> Client
    Each agent has one, serving as a relay between the server and the agent.
    Operates on the same machine as the machine running the agent process,
    communicating with the player object via Socket and with the agent via pipe.

> Agent
    The AI (or human) performing actual gameplay actions as a game player.
    Connects standard input/output with the client via pipes for
    communication related to gameplay.
--------------------------------------------------------------------------

In other words, the configuration during gameplay is:
--------------------------------------------------------------------------
        [method]                [Socket]           [pipe]
<Server> <----> <PlayerObject-1> <----> <Client-1> <----> <Agent-1>
  ^ ^
  | |
  | +---------> <PlayerObject-2> <----> <Client-2> <----> <Agent-2>
  |
  +-----------> <PlayerObject-3> <----> <Client-3> <----> <Agent-3>
                       :                    :                 :
                       :                    :                 :
--------------------------------------------------------------------------
From the server's perspective, each set of
   <PlayerObject> <----> <Client> <----> <Agent>
represents one player.

The AI_AVALON system's code is written in Ruby, but the agent responsible
for decision-making communicates independently via standard input/output,
allowing implementation in any preferred programming language.


*** Directory Contents ***

The contetns of each directory are as follows:
--------------------------------------------------------------------------
> Document
    Contains documents such as protocol descriptions.

    * Protocol.txt
        Defines the overall system, including gameplay progress and message
        types.

    * KeyCode.txt
        Specifies numerical codes used in communication.

    * CommunicationFormat.txt
        Specifies data formats in binary for communication channels.
        Used for communication between player objects and clients.
        Optionally used for communication between clients and agents.

    * CommunicationString.txt
        Specifies data formats in text for communication channels.
        Default for communication between clients and agents.

    * Connection.txt
        Defines the procedure for establishing connections between server
        and clients.

    * Query.txt
        Defines inquiries from agents to the server (player object).
        (Currently incomplete due to perceived low necessity.)

    * Terminate.txt
        Describes procedures for game termination.

> Library
    Contains Ruby and Python3 versions of programs useful for agent creation
    within the system.

    * msg_catalog/
        Message catalog for expressing data format contents in natural
        language, aiding human confirmation of logs.
        Refer to Utility/msg_log_to_nl.rb or Utility/serverlog_to_nl.rb to
        display log data file contents in natural language.

> System
    Contains core server and client programs of the system.

    * server.rb
        Server for the AI_AVALON system.

    * client.rb
        Client for the AI_AVALON system.

    * server_launcher.rb
        Program that accepts communication from clients, generates player
        objects, and launches the server to start gameplay.
        Intended for a single game execution.

    * agent_launcher.rb
        Program that establishes communication with the server (player object),
        generates clients, and launches agents.

    * multi_server_service.rb
        Listens on a single port and launches multiple servers.
        Launches servers in parallel for each configured number of players.
        The number of servers operating simultaneously is adjustable; if
        exceeded, connecting clients will wait in line for server termination.
        Intended for running the AI_AVALON system as a service.
        This program uses process generation via fork command; therefore,
        it will not function on OSes that do not support fork (e.g., Windows).

    * group_controller.rb
        Because multi_server_service.rb creates a player group in the order
        in which agents complete negotiations, it does not guarantee that a
        player group will be created in the order in which agents are started
        when socket connections are concentrated in parallel.
        This program controls that games are started with a particular group of
        agents by repeatedly launching a program to start one group of agents
        while monitoring the startup of servers after the group is formed.    

    * request_group_key.rb
        This program aquires a group-key string to identify a player group.
        Refer to System/test-grpkey.rb or System/test-grpkey_ux.sh to 
        launch an agent with a group-key.
        Based on current settings, expiring timee of a group-key is 10 minutes.
        If a new game with the group-key starts up, then extend expiring time
        of the group-key by 10 minutes after the starting tiem.
        The server can keep 1000 available group-keys on current settings.
        When the limit is exhausted, agents must wait for expireing an entried
        group-key.
        These settings are written in a head part of multi_server_service.rb.

> Agent
    Contains dummy agents and interfaces for human players.

    * basic_agent.rb (Ruby version) / basic_agent.py (Python3 version)
        Base class definition for creating custom agents.
        To create a simple custom agent, inherit this class and override
        methods corresponding to various message receptions.
        When launched directly as an agent program, it sends "omit" messages
        in response to all message requests. Therefore, it can also be used
        directly as a dummy agent.

    * basic_nl_agent.rb (Ruby version) / basic_nl_agent.py (Python3 version)
        Agent that converts outputs to natural language, based on the
        definitions on basic_agent.{rb,py}. An example class created by
        inheriting definitions from basic_agent.{rb,py}.
        Like basic_agent.{rb,py}, it can also be used as a dummy agent.
 
    * human_if/human_if.rb
        Interface for human participation in gameplay.
        Allows viewing received messages in natural language and editing
        messages to be sent.

> Utility
    Contains utility programs useful for tasks outside of gameplay, such as
    examining play logs.

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


*** Launching Programs ***

Please follow these steps to launch the server and agents.
--------------------------------------------------------------------------
> Launching the Server with server_launcher.rb
    The command line for launching is as follows:
        ruby server_launcher.rb <logfile> <config> <restriction>

    * <logfile>
        File name for recording play logs.
        If omitted, specified as "-" or an empty string, logs will be written
        to standard error output.

    * <config>
        File configuring the server's operating conditions.
        If unspecified, the server_launcher.rb will use server.conf located
        in the same directory.
        Sample configurations include server.conf for 10-player games and
        server-minimum.conf for minimal 5-player setups, 
        And for the UNIX-domain-server version of the server, they are
        server_ux.conf and unix_ux-minimum.conf.
        While usable as-is, note that message sending timeouts for human
        players are set to 30 seconds; consider extending this timeout for
        actual human gameplay.

    * <restriction>
        Specifies conditions for agent role assignments and player order
        during gameplay.
        Refer to assign_rst.conf.sample for specific formatting details
        and examples.

> Launching Agents with agent_launcher.rb
    The command line for launching is as follows:
        ruby agent_launcher.rb <addr>:<port> <mode> <name> <add> <command> ...
               or
        ruby agent_launcher.rb ux:<unix_sock> <mode> <name> <add> <command> ...

    * <addr>:<port>
        Specifies the server's IP address and port number.
        Defaults are '127.0.0.1' for IP address and 7625 for port number
        if omitted.

    * ux:<unix_sock>
        Specifies the filename of the server's UNIX domain socket.

    * <mode>
        Specifies the agent type; values can be "AI" or "HM".
        When "AI" is specified, the agent is assumed to be an AI, and
        AI-specific timeout settings are applied. Similarly, when "HM" is
        specified, the agent is assumed to be a human, and human-specific
        timeout settings are applied.

    * <name>
        Specifies the agent's name.
        However, this name serves solely to identify which player corresponds
        to which agent in server logs and is not disclosed to other players.
        To accommodate multiple agents attempting to join with the same name,
        registered names will have ":<number>" appended to them.
        The registered name is communicated and established during the
        connection process with the server.
        The agent needs to receive its registered name as a command-line
        argument based on the <add> parameter setting.

    * <add>
        During the connection establishment with the server, three pieces of
        information are obtained: <logname>, <timeout>, <roles>.
        They represent:
            <logname>: Agent's registered name
            <timeout>: Time until a message sent by the agent times out
            <roles>: Number of each role appearing in the play
        Refer to server configuration files (e.g., server.conf) for the
        format of <roles>.
        If "1" is specified, these three pieces of information will be
        appended to the end of the command-line arguments when launching
        the agent program.

    * <command> ...
        Specifies the token list that constitutes the command line to launch
        the agent program.
        The agent program should receive messages via standard input and
        write outgoing messages to standard output.
        Remember that if you specify "1" for the <add> parameter, three
        additional parameters are added to the end of the token list.

> Launching AI_AVALON Service with multi_server_service.rb
    The command line for launching is as follows:
        ruby server_launcher.rb <limit> <loghead> <config> <restriction>

    * <limit>
        Specifies the maximum number of servers to launch simultaneously.

    * <loghead>
        Header (including path) for the file where play logs are recorded.
        Play logs are written to <loghead><server_start_datetime>.log,
        and server output to standard error is written to
        <loghead><server_start_datetime>.err.
        The server start date and time are formatted in 24-hour clock as
        "YYYYmmdd-HHMMSS".

    * <config>
        File configuring the operating conditions for concurrently launched
        servers.
        Same as the file specified in server_launcher.rb.
        If unspecified, multi_server_service.rb will use server.conf located
        in the same directory as itself.

    * <restriction>
        Specifies conditions for agent role assignments and player order
        during gameplay.
        Same as the file specified in server_launcher.rb.
--------------------------------------------------------------------------

Here is an example of launching agents using agent_launcher.rb:

(Example-1) Launching a dummy agent with default server IP address and
            port number:
    ruby agent_launcher.rb :  AI dummy 0 ruby ../Agent/basic_agent.rb

(Example-2) Launching a dummy agent with the server's UNIX domain socket
            "/tmp/AI_AVALON.sock" (in reality, on one line):
    ruby agent_launcher.rb ux:/tmp/AI_AVALON.sock"
                           AI dummy 0 ruby ../Agent/basic_agent.rb

(Example-3) Launching a human interface as an agent (in reality, on one line):
    ruby agent_launcher.rb xxx.yyy.zzz:nnnn 
        HM human 1 ruby ../Agent/human_if/human_if.rb xxx.log ja_JP.UTF-8

Test scripts to launch five dummy agents against a server started with
settings for 5-player gameplay (System/server-minimum.conf) are provided as:
    System/test-rb.sh, System/test-py.sh, System/test-nl.sh,
and for the UNIX domain socket version (System/server_ux-minimum.conf) are
provided as:
    System/test-ux-sock.sh.
Please use these for system operation testing.