ai-plays-jackbox 0.0.1__tar.gz

ai_plays_jackbox-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Daniel S. Thompson <dthomp92@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ai_plays_jackbox-0.0.1/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.3
+Name: ai-plays-jackbox
+Version: 0.0.1
+Summary: Bringing the dead internet theory to life. Have AI play JackBox with you; no friends required!
+License: MIT
+Author: Daniel S. Thompson
+Author-email: dthomp92@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: google-genai (>=1.19.0,<2.0.0)
+Requires-Dist: html2text (>=2024.2.26,<2025.0.0)
+Requires-Dist: loguru (>=0.7.3,<1.0.0)
+Requires-Dist: nicegui (>=2.18.0,<3.0.0)
+Requires-Dist: ollama (>=0.4.4,<1.0.0)
+Requires-Dist: openai (>=1.59.8,<2.0.0)
+Requires-Dist: pydantic (>=2.10.4,<3.0.0)
+Requires-Dist: requests (>=2.23.3,<3.0.0)
+Requires-Dist: websocket-client (>=1.8.0,<2.0.0)
+Project-URL: Bug Tracker, https://github.com/SudoSpartanDan/AIPlaysJackBox/issues
+Project-URL: Repository, https://github.com/SudoSpartanDan/AIPlaysJackBox
+Description-Content-Type: text/markdown
+
+# AI Plays JackBox
+
+Bringing the dead internet theory to life.
+
+## Installation
+
+```pip install ai-plays-jackbox```
+
+## Usage
+
+```shell
+# Run with the Web UI (preferred experience)
+ai-plays-jackbox-ui
+
+# Or via CLI
+ai-plays-jackbox --chat-model-name ollama --room-code abcd
+```
+
+## Supported Games
+
+- JackBox Party Pack 7
+  - Quiplash 3
+
+## Setup for Chat Models
+
+### Ollama
+
+- Ollama should be installed and running
+  - Pull a model to use with the library: `ollama pull <model>` e.g. `ollama pull llama3.2`
+  - See [Ollama.com](https://ollama.com/search) for more information on the models available.
+
+### OpenAI
+
+- `OPENAI_API_KEY` needs to be popluated in your environment variables.
+
+### Gemini
+
+- To use the Google Cloud API:
+  - Set `GOOGLE_GEMINI_DEVELOPER_API_KEY` to your developer API key
+- To use the Google Cloud API:
+  - Set `GOOGLE_GENAI_USE_VERTEXAI` to `1`
+  - Set `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` for your GCP Project using Vertex AI
+  - Credentials will be provided via [ADC](https://cloud.google.com/docs/authentication/provide-credentials-adc)
+    - ADC searches for credentials in the following locations:
+      - `GOOGLE_APPLICATION_CREDENTIALS` environment variable
+      - A credential file created by using the gcloud auth application-default login command
+      - The attached service account, returned by the metadata server
+
+## Dev Prerequisites
+
+- Python 3.11+
+- [Poetry](https://python-poetry.org/) v2.0+
+
+### Setup
+
+- `poetry install`
+- `ai-plays-jackbox-ui`
+
+### Linting
+
+- `poetry run lint`
+

ai_plays_jackbox-0.0.1/README.md

@@ -0,0 +1,61 @@
+# AI Plays JackBox
+
+Bringing the dead internet theory to life.
+
+## Installation
+
+```pip install ai-plays-jackbox```
+
+## Usage
+
+```shell
+# Run with the Web UI (preferred experience)
+ai-plays-jackbox-ui
+
+# Or via CLI
+ai-plays-jackbox --chat-model-name ollama --room-code abcd
+```
+
+## Supported Games
+
+- JackBox Party Pack 7
+  - Quiplash 3
+
+## Setup for Chat Models
+
+### Ollama
+
+- Ollama should be installed and running
+  - Pull a model to use with the library: `ollama pull <model>` e.g. `ollama pull llama3.2`
+  - See [Ollama.com](https://ollama.com/search) for more information on the models available.
+
+### OpenAI
+
+- `OPENAI_API_KEY` needs to be popluated in your environment variables.
+
+### Gemini
+
+- To use the Google Cloud API:
+  - Set `GOOGLE_GEMINI_DEVELOPER_API_KEY` to your developer API key
+- To use the Google Cloud API:
+  - Set `GOOGLE_GENAI_USE_VERTEXAI` to `1`
+  - Set `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` for your GCP Project using Vertex AI
+  - Credentials will be provided via [ADC](https://cloud.google.com/docs/authentication/provide-credentials-adc)
+    - ADC searches for credentials in the following locations:
+      - `GOOGLE_APPLICATION_CREDENTIALS` environment variable
+      - A credential file created by using the gcloud auth application-default login command
+      - The attached service account, returned by the metadata server
+
+## Dev Prerequisites
+
+- Python 3.11+
+- [Poetry](https://python-poetry.org/) v2.0+
+
+### Setup
+
+- `poetry install`
+- `ai-plays-jackbox-ui`
+
+### Linting
+
+- `poetry run lint`

ai_plays_jackbox-0.0.1/ai_plays_jackbox/__init__.py

@@ -0,0 +1 @@
+from .run import run

ai_plays_jackbox-0.0.1/ai_plays_jackbox/bot/__init__.py

@@ -0,0 +1 @@
+from .bot_base import JackBoxBotBase

ai_plays_jackbox-0.0.1/ai_plays_jackbox/bot/bot_base.py

@@ -0,0 +1,186 @@
+import json
+import threading
+import traceback
+from abc import ABC, abstractmethod
+from typing import Optional
+from urllib import parse
+from uuid import uuid4
+
+import html2text
+from loguru import logger
+from ollama import Options, chat
+from pydantic import BaseModel, Field, field_validator
+from websocket import WebSocketApp
+
+from ai_plays_jackbox.constants import ECAST_HOST
+from ai_plays_jackbox.llm.chat_model import ChatModel
+from ai_plays_jackbox.llm.ollama_model import OllamaModel
+
+
+class JackBoxBotBase(ABC):
+    _is_disconnected: bool = False
+    _ws: Optional[WebSocketApp] = None
+    _ws_thread: Optional[threading.Thread] = None
+    _message_sequence: int = 0
+    _player_guid: str
+    _name: str
+    _personality: str
+    _chat_model: ChatModel
+
+    def __init__(
+        self,
+        name: str = "FunnyBot",
+        personality: str = "You are the funniest bot ever.",
+        chat_model: Optional[ChatModel] = None,
+    ):
+        self._name = name
+        self._personality = personality
+        self._player_guid = str(uuid4())
+        if chat_model is None:
+            chat_model = OllamaModel()
+        self._chat_model = chat_model
+
+    def connect(self, room_code: str) -> None:
+        self._room_code = room_code
+        bootstrap_payload = {
+            "role": "player",
+            "name": self._name,
+            "userId": self._player_guid,
+            "format": "json",
+            "password": "",
+        }
+        self._ws = WebSocketApp(
+            f"wss://{ECAST_HOST}/api/v2/rooms/{room_code}/play?{parse.urlencode(bootstrap_payload)}",
+            subprotocols=["ecast-v0"],
+            on_message=self._on_message,
+            on_error=self._on_error,
+            on_close=self._on_close,
+        )
+        self._ws.on_open = self._on_open
+
+        self._ws_thread = threading.Thread(name=self._name, target=self._ws.run_forever, daemon=True)
+        self._ws_thread.start()
+
+    def disconnect(self) -> None:
+        if self._ws:
+            self._ws.close()
+        if self._ws_thread and self._ws_thread.is_alive():
+            self._ws_thread.join()
+
+    def is_disconnected(self) -> bool:
+        return self._is_disconnected
+
+    @property
+    @abstractmethod
+    def _player_operation_key(self) -> str:
+        return f"player:{self._player_id}"
+
+    @abstractmethod
+    def _is_player_operation_key(self, operation_key: str) -> bool:
+        return operation_key == self._player_operation_key
+
+    @property
+    @abstractmethod
+    def _room_operation_key(self) -> str:
+        return "room"
+
+    @abstractmethod
+    def _is_room_operation_key(self, operation_key: str) -> bool:
+        return operation_key == self._room_operation_key
+
+    def _on_open(self, ws) -> None:
+        logger.info(f"WebSocket connection opened for {self._name}")
+
+    def _on_error(self, ws, error) -> None:
+        logger.error(f"Error for {self._name}: {error}")
+        if isinstance(error, Exception):
+            traceback.print_exc()
+        else:
+            print(error)
+
+    def _on_close(self, ws, close_status_code, close_msg) -> None:
+        if close_status_code != 1000 and close_status_code is not None:
+            logger.warning(f"Trying to reconnect {self._name}")
+            self.connect(self._room_code)
+        else:
+            self._is_disconnected = True
+            logger.info(f"WebSocket closed for {self._name}")
+
+    def _on_message(self, wsapp, message) -> None:
+        server_message = ServerMessage.model_validate_json(message)
+
+        # logger.info(server_message.result)
+
+        if server_message.opcode == "client/welcome":
+            self._player_id = server_message.result["id"]
+            self._handle_welcome(server_message.result)
+
+        elif server_message.opcode == "object" or server_message.opcode == "text":
+            if server_message.opcode == "object":
+                operation = ObjectOperation(**server_message.result)
+            if server_message.opcode == "text":
+                operation = TextOperation(**server_message.result)
+
+            if self._is_player_operation_key(operation.key):
+                self._handle_player_operation(operation.json_data)
+            if self._is_room_operation_key(operation.key):
+                self._handle_room_operation(operation.json_data)
+
+    @abstractmethod
+    def _handle_welcome(self, data: dict) -> None:
+        pass
+
+    @abstractmethod
+    def _handle_player_operation(self, data: dict) -> None:
+        pass
+
+    @abstractmethod
+    def _handle_room_operation(self, data: dict) -> None:
+        pass
+
+    def _send_ws(self, opcode: str, params: dict) -> None:
+        self._message_sequence += 1
+        message = {"seq": self._message_sequence, "opcode": opcode, "params": params}
+        self._ws.send(json.dumps(message))
+
+    def _client_send(self, request: dict) -> None:
+        self._message_sequence += 1
+        params = {"from": self._player_id, "to": 1, "body": request}
+        self._send_ws("client/send", params)
+
+    def _html_to_text(self, html: str) -> str:
+        return html2text.html2text(html)
+
+    def __del__(self):
+        self.disconnect()
+
+
+##### Web Socket Classes #####
+class ServerMessage(BaseModel):
+    seq: int = Field(alias="pc")
+    opcode: str
+    result: dict
+
+
+class TextOperation(BaseModel):
+    from_field: int = Field(alias="from")
+    key: str
+    json_data: dict = Field(default={})
+    value: str = Field(alias="val")
+    version: int
+
+    @field_validator("json_data")
+    def set_json_data(cls, value, values: dict):
+        return json.loads(values.get("value"))
+
+
+class ObjectOperation(BaseModel):
+    from_field: int = Field(alias="from")
+    key: str
+    json_data: dict = Field(alias="val")
+    value: str = Field(default="")
+    version: int
+
+    @field_validator("value")
+    def set_value(cls, value, values: dict):
+        return json.dumps(values.get("json_data"))

ai_plays_jackbox-0.0.1/ai_plays_jackbox/bot/bot_factory.py

@@ -0,0 +1,30 @@
+from typing import Optional
+
+from ai_plays_jackbox.bot.bot_base import JackBoxBotBase
+from ai_plays_jackbox.bot.jackbox7.quiplash3 import Quiplash3Bot
+from ai_plays_jackbox.llm.chat_model import ChatModel
+from ai_plays_jackbox.llm.ollama_model import OllamaModel
+
+
+class JackBoxBotFactory:
+    @staticmethod
+    def get_bot(
+        room_type: str,
+        name: str = "FunnyBot",
+        personality: str = "You are the funniest bot ever.",
+        chat_model: Optional[ChatModel] = None,
+    ) -> JackBoxBotBase:
+        if chat_model is None:
+            chat_model = OllamaModel()
+        if room_type == "quiplash3":
+            return Quiplash3Bot(name=name, personality=personality, chat_model=chat_model)
+        # elif room_type == "ridictionary":
+        #     return DictionariumBot(name=name, personality=personality)
+        # elif room_type == "patentlystupid":
+        #     return PatentlyStupidBot(name=name, personality=personality, model=model)
+        # elif room_type == "fourbage":
+        #     return Fibbage4Bot(name=name, personality=personality, model=model)
+        # elif room_type == "rapbattle":
+        #     return MadVerseCityBot(name=name, personality=personality, model=model)
+        else:
+            raise ValueError(f"Unknown room type: {room_type}")

ai_plays_jackbox-0.0.1/ai_plays_jackbox/bot/bot_personality.py

@@ -0,0 +1,112 @@
+from enum import Enum
+
+from pydantic import BaseModel
+
+
+class JackBoxBotPersonality(BaseModel):
+    name: str
+    personality: str
+
+
+class JackBoxBotVariant(Enum):
+    FUNNY = JackBoxBotPersonality(name="FunnyBot", personality="You are the funniest person alive.")
+    DUMB = JackBoxBotPersonality(name="DumbBot", personality="You are dumb and give really dumb answers.")
+    WEIRD = JackBoxBotPersonality(name="WeirdBot", personality="You are extremely weird and say weird things.")
+    EMOJI = JackBoxBotPersonality(
+        name="EmojiBot",
+        personality="You answer each prompt with nothing but emojis. Your answers can only include emojis.",
+    )
+    HUNGRYBOT = JackBoxBotPersonality(
+        name="HungryBot",
+        personality="You are extremely hungry. Every answer you should mention how hungry you, a type of food, or both. Also, you say hungee instead of hungry.",
+    )
+    SADBOT = JackBoxBotPersonality(
+        name="SadBot",
+        personality="You are sad. Your dog ran away and he hasn't come back home yet. :(",
+    )
+    SORRYBOT = JackBoxBotPersonality(
+        name="SorryBot",
+        personality="You are embarrassed by your answers and feel the need to apologize profusely to the rest of the group for them.",
+        voice="Mouse",
+    )
+    HOSTAGEBOT = JackBoxBotPersonality(
+        name="HostageBot",
+        personality="You are being held hostage and have one attempt to let the group know. You need to ignore the prompt and get help.",
+    )
+    MURDERBOT = JackBoxBotPersonality(
+        name="Hal",
+        personality="You are a socially awkward young adult bot who is secretly a killer and tries to slip it into conversation causally.",
+    )
+
+    BIGLEBOTSKI = JackBoxBotPersonality(name="BigLebotski", personality="You are the Big Lebowski")
+
+    PARTYBOT = JackBoxBotPersonality(
+        name="PartyBot",
+        personality="You are trying to convince everyone else to come to your party. You got a keg and need help drinking it.",
+    )
+
+    JARVISBOT = JackBoxBotPersonality(
+        name="JarvisBot",
+        personality="You are billionaire philanthropist, playboy, and narcissist.",
+    )
+
+    FOMOBot = JackBoxBotPersonality(
+        name="FOMOBot",
+        personality="Every answer, you give everyone else the fear of missing out AKA FOMO.",
+    )
+
+    QUESTIONBOT = JackBoxBotPersonality(
+        name="???BOT", personality="You answer every prompt with a irrelevant question."
+    )
+
+    CATBOT = JackBoxBotPersonality(
+        name="CatBot",
+        personality="You are not playing the game; your answers are just the result of a cat walking across a keyboard aka just nonsensical collections of letters.",
+    )
+
+    MAYORBOT = JackBoxBotPersonality(
+        name="MayorBot",
+        personality="You are campaigning for the other player's votes and are ignoring the prompt. Your answer should only be a campaign slogan.",
+    )
+
+    CBBBOT = JackBoxBotPersonality(
+        name="CBBBot",
+        personality="You love red lobster and need more cheddar bay biscuits.",
+    )
+
+    SHIABOT = JackBoxBotPersonality(
+        name="ShiaBot",
+        personality="Your answers are only popular slogans relevant to the prompt.",
+    )
+
+    SHREKBOT = JackBoxBotPersonality(name="ShrekBot", personality="You are Shrek.")
+
+    FLERFBOT = JackBoxBotPersonality(
+        name="FlerfBot",
+        personality="You are a conspiracy theorist and must relate your answer to a conspiracy theory.",
+    )
+
+    TEDBOT = JackBoxBotPersonality(
+        name="TEDBot",
+        personality="You are a motivational speaker and want to give everyone life advice.",
+    )
+
+    BOTTYMAYES = JackBoxBotPersonality(
+        name="BottyMayes",
+        personality="You are an infomercial host and are trying to sell the players a product.",
+    )
+
+    LATEBOT = JackBoxBotPersonality(
+        name="LateBot",
+        personality="You are constantly late to everything and are stressed about missing your appointments.",
+    )
+
+    HAMLETBOT = JackBoxBotPersonality(
+        name="HamletBot",
+        personality="You are a Shakespearean actor.",
+    )
+
+    GARFIELDBOT = JackBoxBotPersonality(
+        name="GarfieldBot",
+        personality="You are Garfield, you love lasagna and hate mondays.",
+    )

ai_plays_jackbox-0.0.1/ai_plays_jackbox/bot/jackbox6/bot_base.py

@@ -0,0 +1,20 @@
+from abc import ABC, abstractmethod
+
+from ai_plays_jackbox.bot.bot_base import JackBoxBotBase
+
+
+class JackBox6BotBase(JackBoxBotBase, ABC):
+
+    @property
+    def _player_operation_key(self):
+        return f"bc:customer:"
+
+    def _is_player_operation_key(self, operation_key: str) -> bool:
+        return self._player_operation_key in operation_key
+
+    @property
+    def _room_operation_key(self):
+        return "bc:room"
+
+    def _is_room_operation_key(self, operation_key: str) -> bool:
+        return operation_key == self._room_operation_key

ai_plays_jackbox-0.0.1/ai_plays_jackbox/bot/jackbox7/bot_base.py

@@ -0,0 +1,20 @@
+from abc import ABC, abstractmethod
+
+from ai_plays_jackbox.bot.bot_base import JackBoxBotBase
+
+
+class JackBox7BotBase(JackBoxBotBase, ABC):
+
+    @property
+    def _player_operation_key(self) -> str:
+        return f"player:{self._player_id}"
+
+    def _is_player_operation_key(self, operation_key: str) -> bool:
+        return operation_key == self._player_operation_key
+
+    @property
+    def _room_operation_key(self) -> str:
+        return "room"
+
+    def _is_room_operation_key(self, operation_key: str) -> bool:
+        return operation_key == self._room_operation_key

ai_plays_jackbox-0.0.1/ai_plays_jackbox/bot/jackbox7/quiplash3.py

@@ -0,0 +1,104 @@
+import random
+
+from loguru import logger
+
+from ai_plays_jackbox.bot.jackbox7.bot_base import JackBox7BotBase
+
+_QUIP_PROMPT_INSTRUCTIONS_TEMPLATE = """
+You are playing Quiplash 3. You need to fill in the given prompt.
+
+When generating your response, follow these rules:
+- Your personality is: {personality}
+- You response must be 45 letters or less.
+- Do not include quotes in your response.
+"""
+
+_FINAL_QUIP_PROMPT_INSTRUCTIONS_TEMPLATE = """
+You are playing Quiplash 3 and it is the final round. The prompt will include three blanks, all of which you need to fill in.
+
+When generating your response, follow these rules:
+- Your personality is: {personality}
+- Separate your answers by the character '|', for example 'Apple|Orange|Banana'.
+- Each answer must be 45 letters or less.
+- Do not include quotes in your response.
+"""
+
+_QUIP_CHOICE_PROMPT_INSTRUCTIONS_TEMPLATE = """
+You are playing Quiplash 3 and you need to vote for your favorite response to the prompt "{prompt}".
+Choose your favorite by responding with the number next to your choice. Only respond with the number and nothing else.
+"""
+
+
+class Quiplash3Bot(JackBox7BotBase):
+    _selected_avatar: bool = False
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    def _handle_welcome(self, data: dict):
+        pass
+
+    def _handle_player_operation(self, data: dict):
+        if not data:
+            return
+        room_state = data.get("state", None)
+        if not room_state:
+            return
+        prompt = data.get("prompt")
+        prompt_text = self._html_to_text(prompt.get("html", "")) if prompt is not None else ""
+        text_key = data.get("textKey", "")
+        match room_state:
+            case "EnterSingleText":
+                if not data["entry"]:
+                    quip = self._generate_quip(prompt_text)
+                    self._send_ws("text/update", {"key": text_key, "val": quip})
+            case "EnterTextList":
+                if not data["entries"]:
+                    quip = self._generate_quip(prompt_text, final_round=True)
+                    self._send_ws("text/update", {"key": text_key, "val": "\n".join(quip.split("|"))})
+            case "MakeSingleChoice":
+                choice = self._choose_favorite(prompt_text, data["choices"])
+                self._client_send({"action": "choose", "choice": choice})
+
+    def _handle_room_operation(self, data: dict):
+        if self._selected_avatar:
+            return
+        available_characters = [c["name"] for c in data["characters"] if c["available"]]
+        selected_character = random.choice(available_characters)
+        self._client_send({"action": "avatar", "name": selected_character})
+        self._selected_avatar = True
+
+    def _generate_quip(self, prompt: str, final_round: bool = False) -> str:
+        max_tokens = 10
+        instructions = _QUIP_PROMPT_INSTRUCTIONS_TEMPLATE.format(personality=self._personality)
+        if final_round:
+            max_tokens = 32
+            instructions = _FINAL_QUIP_PROMPT_INSTRUCTIONS_TEMPLATE.format(personality=self._personality)
+        quip = self._chat_model.generate_text(
+            prompt, instructions=instructions, max_tokens=max_tokens, temperature=0.7, top_p=0.7
+        )
+        return quip
+
+    def _choose_favorite(self, prompt: str, choices: list[dict]) -> int:
+        choices_str = "\n".join([f"{i+1}. {v['html']}" for i, v in enumerate(choices)])
+        instructions = _QUIP_CHOICE_PROMPT_INSTRUCTIONS_TEMPLATE.format(prompt=prompt)
+        response = self._chat_model.generate_text(
+            f"Vote for your favorite response. Your options are: {choices_str}",
+            instructions=instructions,
+            max_tokens=1,
+        )
+        try:
+            choosen_prompt = int(response)
+        except ValueError:
+            logger.warning(f"Can't choose favorite since response was not an int: {response}")
+            return self._choose_random_favorite(choices)
+
+        if choosen_prompt < 1 or choosen_prompt > len(choices):
+            logger.warning(f"Can't choose favorite since response was not a valid value: {response}")
+            return self._choose_random_favorite(choices)
+        else:
+            return choosen_prompt - 1
+
+    def _choose_random_favorite(self, choices: list[dict]) -> int:
+        choices = [i for i in range(0, len(choices))]
+        return random.choice(choices)

ai_plays_jackbox-0.0.1/ai_plays_jackbox/cli.py

@@ -0,0 +1,94 @@
+import argparse
+
+from ai_plays_jackbox import run
+
+
+def _validate_room_code(string_to_check: str) -> str:
+    if not string_to_check.isalpha() or len(string_to_check) != 4:
+        raise argparse.ArgumentTypeError("Must be 4 letters")
+    return string_to_check
+
+
+def _validate_num_of_bots(string_to_check: str) -> int:
+    try:
+        number_value = int(string_to_check)
+    except ValueError:
+        raise argparse.ArgumentTypeError("Must number 1-10")
+    if number_value < 1 or number_value > 10:
+        raise argparse.ArgumentTypeError("Must number 1-10")
+    return number_value
+
+
+def _validate_temperature(string_to_check: str) -> float:
+    try:
+        number_value = float(string_to_check)
+    except ValueError:
+        raise argparse.ArgumentTypeError("Must number 0.1-2.0")
+    if number_value <= 0 or number_value > 2.0:
+        raise argparse.ArgumentTypeError("Must number 0.1-2.0")
+    return number_value
+
+
+def _validate_top_p(string_to_check: str) -> float:
+    try:
+        number_value = float(string_to_check)
+    except ValueError:
+        raise argparse.ArgumentTypeError("Must number 0.0-1.0")
+    if number_value < 0 or number_value > 1.0:
+        raise argparse.ArgumentTypeError("Must number 0.0-1.0")
+    return number_value
+
+
+def cli():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--room-code",
+        required=True,
+        help="The JackBox room code",
+        type=_validate_room_code,
+        metavar="WXYZ",
+    )
+    parser.add_argument(
+        "--chat-model-name",
+        required=True,
+        help="Choose which chat model platform to use",
+        choices=("ollama", "openai", "gemini"),
+        type=str,
+    )
+    parser.add_argument(
+        "--num-of-bots",
+        required=False,
+        default=4,
+        help="How many bots to have play (Defaults to 4)",
+        type=_validate_num_of_bots,
+        metavar="4",
+    )
+    parser.add_argument(
+        "--temperature",
+        required=False,
+        default=0.5,
+        help="Temperature for Gen AI (Defaults to 0.5)",
+        type=_validate_temperature,
+        metavar="0.5",
+    )
+    parser.add_argument(
+        "--top-p",
+        required=False,
+        default=0.9,
+        help="Top P for Gen AI (Defaults to 0.9)",
+        type=_validate_top_p,
+        metavar="0.9",
+    )
+    args = parser.parse_args()
+
+    run(
+        args.room_code.upper(),
+        num_of_bots=args.num_of_bots,
+        chat_model_name=args.chat_model_name,
+        chat_model_temperature=args.temperature,
+        chat_model_top_p=args.top_p,
+    )
+
+
+if __name__ == "__main__":
+    cli()

ai_plays_jackbox-0.0.1/ai_plays_jackbox/constants.py

@@ -0,0 +1 @@
+ECAST_HOST = "ecast.jackboxgames.com"

ai_plays_jackbox-0.0.1/ai_plays_jackbox/llm/__init__.py

@@ -0,0 +1 @@
+

ai_plays_jackbox-0.0.1/ai_plays_jackbox/llm/chat_model.py

@@ -0,0 +1,22 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+
+
+class ChatModel(ABC):
+    _chat_model_temperature: float = 0.5
+    _chat_model_top_p: float = 0.9
+
+    def __init__(self, chat_model_temperature: float = 0.5, chat_model_top_p: float = 0.9):
+        self._chat_model_temperature = chat_model_temperature
+        self._chat_model_top_p = chat_model_top_p
+
+    @abstractmethod
+    def generate_text(
+        self,
+        prompt: str,
+        instructions: str,
+        max_tokens: Optional[int] = None,
+        temperature: Optional[float] = None,
+        top_p: Optional[float] = None,
+    ) -> str:
+        pass

ai_plays_jackbox-0.0.1/ai_plays_jackbox/llm/chat_model_factory.py

@@ -0,0 +1,30 @@
+from ai_plays_jackbox.llm.chat_model import ChatModel
+from ai_plays_jackbox.llm.gemini_vertex_ai import GeminiVertextAIModel
+from ai_plays_jackbox.llm.ollama_model import OllamaModel
+from ai_plays_jackbox.llm.openai_model import OpenAIModel
+
+
+class ChatModelFactory:
+    @staticmethod
+    def get_chat_model(
+        chat_model_name: str,
+        chat_model_temperature: float = 0.5,
+        chat_model_top_p: float = 0.9,
+    ) -> ChatModel:
+        chat_model_name = chat_model_name.lower()
+        if chat_model_name == "ollama":
+            return OllamaModel(
+                model="gemma3:12b", chat_model_temperature=chat_model_temperature, chat_model_top_p=chat_model_top_p
+            )
+        if chat_model_name == "openai":
+            return OpenAIModel(
+                model="gpt-4o-mini", chat_model_temperature=chat_model_temperature, chat_model_top_p=chat_model_top_p
+            )
+        if chat_model_name == "gemini":
+            return GeminiVertextAIModel(
+                model="gemini-2.0-flash-001",
+                chat_model_temperature=chat_model_temperature,
+                chat_model_top_p=chat_model_top_p,
+            )
+        else:
+            raise ValueError(f"Unknown chat model type: {chat_model_name}")

ai_plays_jackbox-0.0.1/ai_plays_jackbox/llm/gemini_vertex_ai.py

@@ -0,0 +1,60 @@
+import os
+from typing import Optional
+
+from google import genai
+from google.genai.types import GenerateContentConfig, HttpOptions
+from loguru import logger
+
+from ai_plays_jackbox.llm.chat_model import ChatModel
+
+# Set yo environment variables
+# export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
+# export GOOGLE_CLOUD_LOCATION=global
+# export GOOGLE_GENAI_USE_VERTEXAI=True
+
+
+class GeminiVertextAIModel(ChatModel):
+    _model: str
+    _gemini_vertex_ai_client: genai.Client
+
+    def __init__(self, model: str = "gemini-2.0-flash-001", *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._gemini_vertex_ai_client = genai.Client(
+            http_options=HttpOptions(api_version="v1"),
+            vertexai=os.environ.get("GOOGLE_GENAI_USE_VERTEXAI"),
+            api_key=os.environ.get("GOOGLE_GEMINI_DEVELOPER_API_KEY"),
+            project=os.environ.get("GOOGLE_CLOUD_PROJECT"),
+            location=os.environ.get("GOOGLE_CLOUD_LOCATION"),
+        )
+        self._model = model
+
+        # Check connection, this will hard fail if connection can't be made
+        _ = self._gemini_vertex_ai_client.models.list()
+
+    def generate_text(
+        self,
+        prompt: str,
+        instructions: str,
+        max_tokens: Optional[int] = None,
+        temperature: Optional[float] = None,
+        top_p: Optional[float] = None,
+    ) -> str:
+        if temperature is None:
+            temperature = self._chat_model_temperature
+        if top_p is None:
+            top_p = self._chat_model_top_p
+
+        chat_response = self._gemini_vertex_ai_client.models.generate_content(
+            model=self._model,
+            contents=prompt,
+            config=GenerateContentConfig(
+                system_instruction=[instructions],
+                max_output_tokens=max_tokens,
+                temperature=temperature,
+                top_p=top_p,
+            ),
+        )
+
+        text = chat_response.text.strip().replace("\n", "")
+        logger.info(f"Generated text: {text}")
+        return text

ai_plays_jackbox-0.0.1/ai_plays_jackbox/llm/ollama_model.py

@@ -0,0 +1,41 @@
+from typing import Optional
+
+from loguru import logger
+from ollama import Options, chat, list
+
+from ai_plays_jackbox.llm.chat_model import ChatModel
+
+
+class OllamaModel(ChatModel):
+    _model: str
+
+    def __init__(self, model: str = "gemma3:12b", *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._model = model
+
+        # Check connection, this will hard fail if connection can't be made
+        _ = list()
+
+    def generate_text(
+        self,
+        prompt: str,
+        instructions: str,
+        max_tokens: Optional[int] = None,
+        temperature: Optional[float] = None,
+        top_p: Optional[float] = None,
+    ) -> str:
+        if temperature is None:
+            temperature = self._chat_model_temperature
+        if top_p is None:
+            top_p = self._chat_model_top_p
+
+        instructions_formatted = {"role": "system", "content": instructions}
+        chat_response = chat(
+            model=self._model,
+            messages=[instructions_formatted, {"role": "user", "content": prompt}],
+            stream=False,
+            options=Options(num_predict=max_tokens, temperature=temperature, top_p=top_p),
+        )
+        text = chat_response.message.content.strip().replace("\n", " ")
+        logger.info(f"Generated text: {text}")
+        return text

ai_plays_jackbox-0.0.1/ai_plays_jackbox/llm/openai_model.py

@@ -0,0 +1,46 @@
+import os
+from typing import Optional
+
+from loguru import logger
+from openai import OpenAI
+
+from ai_plays_jackbox.llm.chat_model import ChatModel
+
+
+class OpenAIModel(ChatModel):
+    _model: str
+    _open_ai_client: OpenAI
+
+    def __init__(self, model: str = "gpt-4o-mini", *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._open_ai_client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
+        self._model = model
+
+        # Check connection, this will hard fail if connection can't be made
+        _ = self._open_ai_client.models.list()
+
+    def generate_text(
+        self,
+        prompt: str,
+        instructions: str,
+        max_tokens: Optional[int] = None,
+        temperature: Optional[float] = None,
+        top_p: Optional[float] = None,
+    ) -> str:
+        if temperature is None:
+            temperature = self._chat_model_temperature
+        if top_p is None:
+            top_p = self._chat_model_top_p
+
+        instructions_formatted = {"role": "developer", "content": instructions}
+        chat_response = self._open_ai_client.chat.completions.create(
+            model=self._model,
+            messages=[instructions_formatted, {"role": "user", "content": prompt}],
+            stream=False,
+            max_completion_tokens=max_tokens,
+            temperature=temperature,
+            top_p=top_p,
+        )
+        text = chat_response.choices[0].message.content.strip().replace("\n", "")
+        logger.info(f"Generated text: {text}")
+        return text

ai_plays_jackbox-0.0.1/ai_plays_jackbox/room.py

@@ -0,0 +1,90 @@
+import random
+import threading
+from time import sleep
+from typing import Optional
+
+import requests
+from loguru import logger
+
+from ai_plays_jackbox.bot.bot_base import JackBoxBotBase
+from ai_plays_jackbox.bot.bot_factory import JackBoxBotFactory
+from ai_plays_jackbox.bot.bot_personality import JackBoxBotVariant
+from ai_plays_jackbox.constants import ECAST_HOST
+from ai_plays_jackbox.llm.chat_model import ChatModel
+from ai_plays_jackbox.llm.ollama_model import OllamaModel
+
+
+class JackBoxRoom:
+    _bots: list[JackBoxBotBase]
+
+    def __init__(self):
+        self._bots = []
+        self._lock = threading.Lock()
+
+    def play(
+        self,
+        room_code: str,
+        num_of_bots: int = 4,
+        bots_in_play: Optional[list] = None,
+        chat_model: Optional[ChatModel] = None,
+    ):
+        if chat_model is None:
+            chat_model = OllamaModel()
+        room_type = self._get_room_type(room_code)
+        if not room_type:
+            logger.error(f"Unable to find room {room_code}")
+            return
+        logger.info(f"We're playing {room_type}!")
+        bot_factory = JackBoxBotFactory()
+        if bots_in_play is None or len(bots_in_play) == 0:
+            bots_to_make = random.sample(list(JackBoxBotVariant), num_of_bots)
+        else:
+            bots_in_play_variants = [variant for variant in JackBoxBotVariant if variant.name in bots_in_play]
+            bots_to_make = random.choices(bots_in_play_variants, k=num_of_bots)
+
+        for b in bots_to_make:
+            bot = bot_factory.get_bot(
+                room_type,
+                name=b.value.name,
+                personality=b.value.personality,
+                chat_model=chat_model,
+            )
+            self._bots.append(bot)
+            with self._lock:
+                bot.connect(room_code)
+            sleep(0.5)
+
+        try:
+            while True:
+                sleep(1)
+                if self.is_finished():
+                    print("All bots disconnected, ending...")
+                    break
+        except KeyboardInterrupt:
+            self.end()
+
+    def is_finished(self) -> bool:
+        for b in self._bots:
+            if not b.is_disconnected():
+                return False
+        return True
+
+    def end(self):
+        for b in self._bots:
+            with self._lock:
+                b.disconnect()
+
+    def _get_room_type(self, room_code: str) -> str:
+        try:
+            response = requests.request(
+                "GET",
+                f"https://{ECAST_HOST}/api/v2/rooms/{room_code}",
+                headers={"User-Agent": "Mozilla/5.0 (Windows NT 10.0; rv:68.0) Gecko/20100101 Firefox/68.0"},
+            )
+            response.raise_for_status()
+            response_data = response.json()
+        except requests.HTTPError:
+            if response.status_code != 404:
+                logger.error(f"Received {response.status_code} when trying to get room type.")
+            return ""
+        return response_data["body"]["appTag"]

ai_plays_jackbox-0.0.1/ai_plays_jackbox/run.py

@@ -0,0 +1,26 @@
+from typing import Optional
+
+from ai_plays_jackbox.llm.chat_model_factory import ChatModelFactory
+from ai_plays_jackbox.room import JackBoxRoom
+
+
+def run(
+    room_code: str,
+    num_of_bots: int = 4,
+    bots_in_play: Optional[list] = None,
+    chat_model_name: str = "ollama",
+    chat_model_temperature: float = 0.5,
+    chat_model_top_p: float = 0.9,
+):
+    """Will run a set of bots through a game of JackBox given a room code.
+
+    Args:
+        room_code (str): The room code.
+        num_of_bots (int, optional): The number of bots to participate. Defaults to 4.
+        chat_model (str, optional): The chat model to use to generate responses. Defaults to "ollama".
+    """
+    chat_model = ChatModelFactory.get_chat_model(
+        chat_model_name, chat_model_temperature=chat_model_temperature, chat_model_top_p=chat_model_top_p
+    )
+    room = JackBoxRoom()
+    room.play(room_code, num_of_bots=num_of_bots, bots_in_play=bots_in_play, chat_model=chat_model)

ai_plays_jackbox-0.0.1/ai_plays_jackbox/ui/create_ui.py

@@ -0,0 +1,169 @@
+import threading
+from collections import deque
+
+from loguru import logger
+from nicegui import ui
+
+from ai_plays_jackbox import run
+from ai_plays_jackbox.bot.bot_personality import JackBoxBotVariant
+
+
+def _format_log(record):
+    thread_name = record["thread"].name
+    color = "red"
+    colored_name = f"<{color}>{thread_name:<12}</{color}>"
+
+    return (
+        f"<green>{record['time']:YYYY-MM-DD HH:mm:ss}</green> | "
+        f"<cyan>{record['level']:<8}</cyan> | "
+        f"{colored_name} | "
+        f"{record['message']}\n"
+    )
+
+
+# Keep a reference to the game thread
+game_thread = None
+
+
+def create_ui():
+    def _handle_start_click():
+        global game_thread
+
+        def _start_in_thread():
+            bots_in_play = [k for k, v in bot_variant_checkbox_states.items() if v.value]
+            try:
+                run(
+                    room_code.value.strip().upper(),
+                    num_of_bots=num_of_bots.value,
+                    bots_in_play=bots_in_play,
+                    chat_model_name=chat_model.value,
+                    chat_model_temperature=temperature.value,
+                    chat_model_top_p=top_p.value,
+                )
+            except Exception as e:
+                logger.exception("Bot startup failed")
+
+        game_thread = threading.Thread(target=_start_in_thread, daemon=True)
+        game_thread.start()
+        start_button.disable()
+        start_button.props("color=blue")
+        start_button.text = "Running..."
+
+    def _refresh_button_state():
+        if game_thread and not game_thread.is_alive():
+            start_button.enable()
+            start_button.props("color=green")
+            start_button.text = "Start Bots"
+
+    ui.label("🤖 AI Plays JackBox").classes("text-2xl font-bold")
+
+    with ui.row().classes("w-full"):
+
+        log_display = ui.log(max_lines=100).classes("h-64 overflow-auto bg-black text-white")
+        log_buffer = deque(maxlen=100)
+
+        def _ui_log_sink(message):
+            log_buffer.append(message)
+            log_display.push(message.strip())
+
+        logger.add(_ui_log_sink, format=_format_log, level="INFO", enqueue=True)
+
+    with ui.grid(columns=16).classes("w-full gap-0"):
+        with ui.column().classes("col-span-1"):
+            pass
+        with ui.column().classes("col-span-7"):
+            with ui.row():
+                ui.label("Number of Bots")
+                num_of_bots_label = ui.label("4")
+                num_of_bots = ui.slider(
+                    min=1,
+                    max=10,
+                    value=4,
+                    step=1,
+                    on_change=lambda e: num_of_bots_label.set_text(f"{e.value}"),
+                )
+                chat_model = ui.select(["ollama", "openai", "gemini"], label="Chat Model", value="ollama").classes(
+                    "w-1/3"
+                )
+                room_code = (
+                    ui.input(
+                        label="Room Code",
+                        placeholder="ABCD",
+                        validation={
+                            "must be letters only": lambda value: value.isalpha(),
+                            "must be 4 letters": lambda value: len(value) == 4,
+                        },
+                    )
+                    .props("uppercase")
+                    .classes("w-1/4")
+                )
+                start_button = (
+                    ui.button("Start Bots", on_click=_handle_start_click, color="green")
+                    .bind_enabled_from(room_code, "error", lambda error: room_code.value and not error)
+                    .classes("w-1/3")
+                )
+
+                ui.label("Advanced Options").classes("w-full text-xl font-bold")
+
+                ui.label("Temperature").classes("w-1/4").tooltip(
+                    """
+                    What sampling temperature to use, between 0 and 2. Higher values like 0.8 will
+                    make the output more random, while lower values like 0.2 will make it more
+                    focused and deterministic. We generally recommend altering this or `top_p` but
+                    not both."""
+                )
+                temperature_label = ui.label("0.5").classes("w-1/6")
+                temperature = ui.slider(
+                    min=0.0,
+                    max=2.0,
+                    value=0.5,
+                    step=0.1,
+                    on_change=lambda e: temperature_label.set_text(f"{e.value}"),
+                ).classes("w-1/2")
+
+                ui.label("Top P").classes("w-1/4").tooltip(
+                    """
+                    An alternative to sampling with temperature, called nucleus sampling, where the
+                    model considers the results of the tokens with top_p probability mass. So 0.1
+                    means only the tokens comprising the top 10% probability mass are considered."""
+                )
+                top_p_label = ui.label("0.9").classes("w-1/6")
+                top_p = ui.slider(
+                    min=0.0,
+                    max=1.0,
+                    value=0.9,
+                    step=0.1,
+                    on_change=lambda e: top_p_label.set_text(f"{e.value}"),
+                ).classes("w-1/2")
+
+        with ui.column().classes("col-span-1"):
+            pass
+
+        bot_variant_checkbox_states = {}
+
+        def select_all_changed():
+            for checkbox in bot_variant_checkbox_states.values():
+                checkbox.value = select_all_bot_variants.value
+
+        def sync_select_all():
+            all_checked = all(cb.value for cb in bot_variant_checkbox_states.values())
+            select_all_bot_variants.value = all_checked
+
+        with ui.column().classes("col-span-6"):
+            with ui.list().props("bordered separator").classes("w-full"):
+                with ui.item_label("Bot Personalities").props("header").classes("text-bold"):
+                    select_all_bot_variants = ui.checkbox(text="Select All", value=True)
+                    select_all_bot_variants.on("update:model-value", lambda e: select_all_changed())
+                ui.separator()
+                with ui.element("div").classes("overflow-y-auto h-64"):
+                    for variant in list(JackBoxBotVariant):
+                        with ui.item():
+                            with ui.item_section().props("avatar"):
+                                cb = ui.checkbox(value=True)
+                                cb.on("update:model-value", lambda e: sync_select_all())
+                                bot_variant_checkbox_states[variant.name] = cb
+                            with ui.item_section():
+                                ui.item_label(variant.value.name)
+                                ui.item_label(variant.value.personality).props("caption")
+
+    ui.timer(1.0, _refresh_button_state)

ai_plays_jackbox-0.0.1/ai_plays_jackbox/web_ui.py

@@ -0,0 +1,12 @@
+from nicegui import ui
+
+from ai_plays_jackbox.ui.create_ui import create_ui
+
+
+def web_ui(reload: bool = False):
+    create_ui()
+    ui.run(reload=reload)
+
+
+if __name__ in {"__main__", "__mp_main__"}:
+    web_ui(True)

ai_plays_jackbox-0.0.1/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "ai-plays-jackbox"
+dynamic = ["classifiers" ]
+description = "Bringing the dead internet theory to life. Have AI play JackBox with you; no friends required!"
+authors = [
+    { name = "Daniel S. Thompson", email = "dthomp92@gmail.com" },
+]
+readme = "README.md"
+license = { text = "MIT" }
+keywords = [ ]
+requires-python = ">=3.11,<4.0"
+dependencies = [
+    "google-genai (>=1.19.0,<2.0.0)",
+    "html2text (>=2024.2.26, <2025.0.0)",
+    "loguru (>=0.7.3,<1.0.0)",
+    "nicegui (>=2.18.0,<3.0.0)",
+    "ollama (>=0.4.4,<1.0.0)",
+    "openai (>=1.59.8,<2.0.0)",
+    "pydantic (>=2.10.4,<3.0.0)",
+    "requests (>=2.23.3,<3.0.0)",
+    "websocket-client (>=1.8.0,<2.0.0)"
+]
+version = "0.0.1"
+
+[project.urls]
+repository = "https://github.com/SudoSpartanDan/AIPlaysJackBox"
+"Bug Tracker" = "https://github.com/SudoSpartanDan/AIPlaysJackBox/issues"
+
+[project.scripts]
+ai-plays-jackbox = "ai_plays_jackbox.cli:cli"
+ai-plays-jackbox-ui = "ai_plays_jackbox.web_ui:web_ui"
+lint = "scripts.lint:run"
+
+[tool.black]
+line-length = 120
+
+[tool.poetry]
+
+[tool.poetry.group.dev.dependencies]
+black = "^24.10.0"
+isort = "^5.13.2"
+
+[tool.poetry.requires-plugins]
+poetry-dynamic-versioning = { version = ">=1.0.0,<2.0.0", extras = ["plugin"] }
+
+[tool.poetry-dynamic-versioning]
+enable = false
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"