Skip to content

Commit 9caa373

Browse files
committed
docs: update the README following the balatrobot README
1 parent 89eb755 commit 9caa373

1 file changed

Lines changed: 8 additions & 94 deletions

File tree

ā€ŽREADME.mdā€Ž

Lines changed: 8 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -4,110 +4,24 @@
44
<a href="https://github.com/coder/balatrollm/releases">
55
<img alt="GitHub release" src="https://img.shields.io/github/v/release/coder/balatrollm?include_prereleases&sort=semver&style=for-the-badge&logo=github"/>
66
</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>
107
<a href="https://discord.gg/TPn6FYgGPv">
118
<img alt="Discord" src="https://img.shields.io/badge/discord-server?style=for-the-badge&logo=discord&logoColor=%23FFFFFF&color=%235865F2"/>
129
</a>
1310
</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>
1512
<p><em>A Balatro bot powered by LLMs</em></p>
1613
</div>
1714

1815
---
1916

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.
8718

88-
- Start Balatro with the BalatroBot mod:
19+
## šŸ“š Documentation
8920

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/
11022

111-
### šŸ“š Documentation
23+
## šŸš€ Related Projects
11224

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

Comments
Ā (0)
⚔