|
4 | 4 | <a href="https://github.com/coder/balatrollm/releases"> |
5 | 5 | <img alt="GitHub release" src="https://img.shields.io/github/v/release/coder/balatrollm?include_prereleases&sort=semver&style=for-the-badge&logo=github"/> |
6 | 6 | </a> |
7 | | - <a href="https://pypi.org/project/balatrollm/"> |
8 | | - <img alt="PyPI" src="https://img.shields.io/pypi/v/balatrollm?style=for-the-badge&logo=pypi&logoColor=white"/> |
9 | | - </a> |
10 | 7 | <a href="https://discord.gg/TPn6FYgGPv"> |
11 | 8 | <img alt="Discord" src="https://img.shields.io/badge/discord-server?style=for-the-badge&logo=discord&logoColor=%23FFFFFF&color=%235865F2"/> |
12 | 9 | </a> |
13 | 10 | </p> |
14 | | - <div><video src="https://github.com/user-attachments/assets/777d0c4f-d66a-47dd-9eab-7efb20beaaf2" alt="BalatroLLM playing Balatro"></div> |
| 11 | + <div><img src="./docs/assets/balatrollm.svg" alt="balatrobot" width="170" height="170"></div> |
15 | 12 | <p><em>A Balatro bot powered by LLMs</em></p> |
16 | 13 | </div> |
17 | 14 |
|
18 | 15 | --- |
19 | 16 |
|
20 | | -BalatroLLM is a bot that uses Large Language Models (LLMs) to play [Balatro](https://www.playbalatro.com/), the popular roguelike poker deck-building game. The bot analyzes game states, makes strategic decisions, and executes actions through the [BalatroBot](https://github.com/coder/balatrobot) client. |
21 | | - |
22 | | -The system combines multiple components to make informed decisions: |
23 | | - |
24 | | -- **Strategy templates** (`STRATEGY.md.jinja`) - Define the playing style and approach |
25 | | -- **Game state analysis** (`GAMESTATE.md.jinja`) - Current game situation and available options |
26 | | -- **Memory system** (`MEMORY.md.jinja`) - Historical context from previous decisions |
27 | | -- **Action tools** (`TOOLS.json`) - Available game actions and their parameters |
28 | | - |
29 | | -These components are processed together in a single LLM call, enabling the bot to understand the current situation and perform the optimal tool call based on its configured strategy. |
30 | | - |
31 | | ---- |
32 | | - |
33 | | -### š Requirements |
34 | | - |
35 | | -- [uv](https://docs.astral.sh/uv/) package manager |
36 | | -- Balatro instance with [BalatroBot](https://github.com/coder/balatrobot) mod installed |
37 | | - |
38 | | -> [!IMPORTANT] |
39 | | -> Setting up Balatro with the BalatroBot mod requires careful configuration. Please refer to the [BalatroBot](https://github.com/coder/balatrobot) documentation and follow the instructions step by step. |
40 | | -
|
41 | | -### š¦ Installation |
42 | | - |
43 | | -- Clone the repository |
44 | | - |
45 | | -```bash |
46 | | -git clone https://github.com/coder/balatrollm.git |
47 | | -cd balatrollm |
48 | | -``` |
49 | | - |
50 | | -- Create environment and install dependencies |
51 | | - |
52 | | -```bash |
53 | | -uv sync --no-dev |
54 | | -``` |
55 | | - |
56 | | -- Activate environment |
57 | | - |
58 | | -```bash |
59 | | -source .venv/bin/activate |
60 | | -``` |
61 | | - |
62 | | -> [!TIP] |
63 | | -> You can use [direnv](https://direnv.net/) to automatically activate the environment when you enter the project directory. The `.envrc.example` file contains an example configuration for direnv. |
64 | | -
|
65 | | -### āļø LLM Configuration |
66 | | - |
67 | | -BalatroLLM performs single requests to an OpenAI-compatible chat/completions endpoint. You need to configure: |
68 | | - |
69 | | -- `--model`: LLM model identifier |
70 | | -- `--base-url`: OpenAI-compatible API base URL |
71 | | -- `--api-key`: API key (if required) |
72 | | - |
73 | | -The default configuration uses [OpenRouter](https://openrouter.ai/), which provides access to many LLMs: |
74 | | - |
75 | | -- `--model openai/gpt-oss-20b`: Small, fast, and affordable model |
76 | | -- `--base-url https://openrouter.ai/api/v1`: OpenRouter API base URL |
77 | | -- `--api-key $OPENROUTER_API_KEY`: It's recommended to export the API key in the `.envrc` file. |
78 | | - |
79 | | -> [!TIP] |
80 | | -> After configuring the base URL and API key, you can check the available models by running `balatrollm --list-models` |
81 | | -
|
82 | | ---- |
83 | | - |
84 | | -### ā” Usage |
85 | | - |
86 | | -The typical workflow to run BalatroLLM is: |
| 17 | +BalatroLLM is a bot that uses Large Language Models (LLMs) to play [Balatro](https://www.playbalatro.com/), the popular roguelike poker deck-building game. The bot analyzes game states, makes strategic decisions, and executes actions through the [BalatroBot](https://github.com/coder/balatrobot) API. |
87 | 18 |
|
88 | | -- Start Balatro with the BalatroBot mod: |
| 19 | +## š Documentation |
89 | 20 |
|
90 | | -```bash |
91 | | -bash balatro.sh |
92 | | -``` |
93 | | - |
94 | | -- Run the bot, typically with multiple runs using the same configuration: |
95 | | - |
96 | | -```bash |
97 | | -balatrollm --runs-per-seed 3 --seed ABCDEFG |
98 | | -``` |
99 | | - |
100 | | -- Generate benchmark reports from the runs: |
101 | | - |
102 | | -```bash |
103 | | -balatrobench --models |
104 | | -``` |
105 | | - |
106 | | -> [!TIP] |
107 | | -> You can run `bash balatro.sh --help`, `balatrollm --help`, and `balatrobench --help` to see all available options. |
108 | | -
|
109 | | ---- |
| 21 | +https://coder.github.io/balatrollm/ |
110 | 22 |
|
111 | | -### š Documentation |
| 23 | +## š Related Projects |
112 | 24 |
|
113 | | -https://coder.github.io/balatrollm/ |
| 25 | +- [**BalatroBot**](https://github.com/coder/balatrobot): API for developing Balatro bots |
| 26 | +- [**BalatroLLM**](https://github.com/coder/balatrollm): Play Balatro with LLMs |
| 27 | +- [**BalatroBench**](https://github.com/coder/balatrobench): Benchmark LLMs playing Balatro |
0 commit comments