:wolf: Werewolf Game with autogen

Requirements

• Get your API key

  • OpenAI API Key
  • https://platform.openai.com/api-keys
  • Groq API Key
  • https://console.groq.com/keys
  • Gemini API Key
  • https://aistudio.google.com/app/apikey

• (optional) docker compose

• (optional) python >= 3.10

Note that either of docker compose or python is required.

How to Use

Preparation

1. Create .env file

2. Set OPENAI_API_KEY, GROQ_API_KEY or GOOGLE_API_KEY in the .env file as follows:

   OPENAI_API_KEY=HERE_IS_YOUR_API_KEY
   GROQ_API_KEY=HERE_IS_YOUR_API_KEY
   GOOGLE_API_KEY=HERE_IS_YOUR_API_KEY
   

3. If you don't use docker but python in your machine, create a virtual environment and install libraries manually:

   python -m venv venv
   source venv/bin/activate  # or `venv/Scripts/activate` in windows
   python -m pip install .

Enjoy a Werewolf Game

The simple use is as follows:

docker compose run werewolf python -m werewolf

In this case, you are an observer. If you want to join a game, use the flag -h or --include-human:

docker compose run werewolf python -m werewolf -h

You can see all options with --help option as follows:

$ docker compose run werewolf python -m werewolf --help
Usage: python -m werewolf [OPTIONS]

Options:
  -n, --n-players INTEGER         The number of players. Default is 6.
  -w, --n-werewolves INTEGER      The number of werewolves. Default is 2.
  -k, --n-knight INTEGER          The number of knights. Default is 1.
  -f, --n-fortune-teller INTEGER  The number of fortune tellers. Default is 1.
  -t, --n-turns-per-day INTEGER   The number of turns per day. Default is 2.
  -s, --speaker-selection-method ESPEAKERSELECTIONMETHOD
                                  The method to select a speaker. Default is
                                  round_robin.
  -h, --include-human             Whether to include human or not.
  -o, --open-game                 Whether to open game or not.
  -l, --log TEXT                  The log file name. Default is
                                  werewolf%Y%m%d%H%M%S.log
  -m, --model TEXT                The model name. Default is gpt-4o-mini. The
                                  valid model is as follows: ('gpt-3.5-turbo',
                                  'gpt-4', 'gpt-4-turbo', 'gpt-4o',
                                  'gpt-4o-mini', 'gemini-1.5-flash', 'gemini-
                                  pro-vision', 'gemini-pro', 'gemma2-9b-it',
                                  'gemma2-7b-it', 'llama3-groq-70b-8192-tool-
                                  use-preview', 'llama3-groq-8b-8192-tool-use-
                                  preview', 'llama-3.1-70b-versatile',
                                  'llama-3.1-8b-instant', 'llama-guard-3-8b',
                                  'llava-v1.5-7b-4096-preview',
                                  'llama3-70b-8192', 'llama3-8b-8192',
                                  'mixtral-8x7b-32768') or the repository id
                                  of huggingface.
  -p, --printer TEXT              The printer name. The valid values is in
                                  ('print', 'click.echo', 'logging.info').
                                  Default is click.echo.
  --sub-model TEXT                The sub-model name. Default is gpt-4o-mini.
                                  The valid model is as follows:
                                  ('gpt-3.5-turbo', 'gpt-4', 'gpt-4-turbo',
                                  'gpt-4o', 'gpt-4o-mini', 'gemini-1.5-flash',
                                  'gemini-pro-vision', 'gemini-pro',
                                  'gemma2-9b-it', 'gemma2-7b-it',
                                  'llama3-groq-70b-8192-tool-use-preview',
                                  'llama3-groq-8b-8192-tool-use-preview',
                                  'llama-3.1-70b-versatile',
                                  'llama-3.1-8b-instant', 'llama-guard-3-8b',
                                  'llava-v1.5-7b-4096-preview',
                                  'llama3-70b-8192', 'llama3-8b-8192',
                                  'mixtral-8x7b-32768') or the repository id
                                  of huggingface
  --seed INTEGER                  The random seed. Default to -1. NOTE: a
                                  negative integer means "not specify the
                                  seed"
  --log-level TEXT                The log level, DEBUG, INFO, WARNING, ERROR
                                  or CRITICAL. Default is WARNING.
  --debug                         Whether to show debug logs or not.
  --help                          Show this message and exit.

If you don't use docker, ignore docker compose run werewolf in the above commands.

Examples

Case1: 1 villager, 1 werewolf, 1 knight and 1 fortune teller with 2 times to speak per day

This is an example of a werewolf game with 1 villager, 1 werewolf, 1 knight and 1 fortune teller with 2 times to speak per day.

Case2: (Open Game) 1 villager, 1 werewolf, 1 knight and 1 fortune teller with 2 times to speak per day

This is an example of a opened werewolf game with 1 villager, 1 werewolf, 1 knight and 1 fortune teller with 2 times to speak per day.

"opened" means that you can see the all conversations between players. Note that each player cannot know the secret contents of what another player has said, like the conversion between a player and the game master.

TODO

• [x] fix a bug that a night actions of a knight and a fortune teller are invalid. See Case2;
  • solved by #12 and #14

Contribution

Development

1. Fork the repository: https://github.com/hmasdev/autogen-werewolf

2. Clone the repository

   git clone https://github.com/{YOURE_NAME}/autogen-werewolf
   cd autogen-werewolf

3. Create a virtual environment

   python -m venv venv
   source venv/bin/activate

4. Install the required packages

   pip install -e .[dev]

5. Checkout your working branch

   git checkout -b your-working-branch

6. Make your changes

7. Test your changes

   pytest
   flake8 autogen-werewolf tests
   mypy autogen-werewolf tests

8. Commit your changes

   git add .
   git commit -m "Your commit message"

9. Push your changes

   git push origin your-working-branch

10. Create a pull request: https://github.com/hmasdev/autogen-werewolf/compare

Note that you can use uv to develop the project in step 3, 4 and 7.

Update README

1. Fork the repository: https://github.com/hmasdev/autogen-werewolf

2. Clone the repository

   git clone https://github.com/{YOURE_NAME}/autogen-werewolf
   cd autogen-werewolf

3. Create a virtual environment

   python -m venv venv
   source venv/bin/activate

4. Install the required packages

   pip install -e .[dev]

5. Checkout your working branch

   git checkout -b your-working-branch

6. Make your changes

   • Update ./README.md.j2

     • CAUTION: Do not update ./README.md directly. It will be generated automatically from ./README.md.j2.

   • Update or add an example in ./examples

     • Name Rule: Case{number}.json
     • Schema:

     {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
            "title": {
            "type": "string",
            "description": "The title of the example case."
            },
            "description": {
            "type": "string",
            "description": "A brief description of the example case."
            },
            "log": {
            "type": "string",
            "description": "The game log for the example case."
            },
            "log_translated": {
            "type": "object",
            "description": "Translations of the game log.",
            "additionalProperties": {
                "type": "string"
            }
            }
        },
        "required": ["title", "description", "log", "log_translated"]
     }

7. Test your changes

   python update_readme.py

8. Commit your changes

   git add .
   git commit -m "Your commit message"

9. Push your changes

   git push origin your-working-branch

10. Create a pull request: https://github.com/hmasdev/autogen-werewolf/compare

Classes

classDiagram

   class ConversableAgent {
      <<external>>
   }

   class IWerewolfPlayer {
      <<interface>>
   }
   class BaseWerewolfPlayer {
      <<abstract>>
   }

   class DefaultGameMaster {
      <<concrete>>
   }
   class VillagerRole {
      <<concrete>>
   }
   class WerewolfRole {
      <<concrete>>
   }
   class KnightRole {
      <<concrete>>
   }
   class FortuneTellerRole {
      <<concrete>>
   }

   class GroupChatManager {
      <<external>>
   }
   class IWerewolfGameMaster {
      <<interface>>
   }
   class BaseGameMaster {
      <<abstract>>
   }

   VillagerRole --|> BaseWerewolfPlayer
   WerewolfRole --|> BaseWerewolfPlayer
   KnightRole --|> BaseWerewolfPlayer
   FortuneTellerRole --|> BaseWerewolfPlayer
   IWerewolfPlayer <|.. BaseWerewolfPlayer
   IWerewolfPlayer --|> ConversableAgent

   BaseGameMaster <|-- DefaultGameMaster
   IWerewolfGameMaster <|.. BaseGameMaster
   IWerewolfGameMaster --|> GroupChatManager

NOTE: IWereWolfPlayer and IWerewolfGameMaster are NOT interfaces strictly, because they inherit from ConversableAgent and GroupChatManager respectively. They are introduced to avoid circular dependencies.

LICENSE

MIT

Authors

• hmasdev

Reference

• Autogen: https://github.com/microsoft/autogen
• Click: https://github.com/pallets/click
• LangChain: https://github.com/langchain-ai/langchain
• python-dotenv: https://github.com/theskumar/python-dotenv
• Werewolf Game (in Japanese): https://ja.wikipedia.org/wiki/%E4%BA%BA%E7%8B%BC%E3%82%B2%E3%83%BC%E3%83%A0