docs: update CLAUDE.md

Author: S1M0N38

CLAUDE.md

@@ -9,185 +9,106 @@ BalatroLLM is an LLM-powered bot that plays Balatro (a roguelike poker deck-buil
 ## Development Commands
 
 ### Environment Setup
-
 ```bash
-# Install dependencies (including dev dependencies)
 uv sync --all-extras --group dev
-
-# Create environment configuration
 cp .envrc.example .envrc
 source .envrc
 ```
 
 ### LiteLLM Proxy
-
 ```bash
-# Start the LiteLLM proxy server (required before running the bot)
 litellm --config config/litellm.yaml
 ```
 
 ### Running the Application
-
 ```bash
-# Run with default settings
-balatrollm
-
-# Run with specific model
-balatrollm --model groq-qwen3-32b
-
-# List available models from proxy
-balatrollm --list-models
-
-# Enable verbose logging
-balatrollm --verbose
+balatrollm                                        # Default settings (cerebras-qwen3-235b)
+balatrollm --model groq-qwen3-32b                 # Specific model
+balatrollm --template aggressive                  # Specific strategy
+balatrollm --list-models                          # List available models
+balatrollm --verbose                              # Enable verbose logging
+balatrollm --proxy-url http://localhost:4000 --api-key your-key
 ```
 
-### Development Quality Commands
-
+### Development
 ```bash
-# Run all quality checks
-make all
-
-# Individual quality checks
-make lint          # Run ruff linter (check only)
-make lint-fix      # Run ruff linter with auto-fixes
-make format        # Run ruff formatter
-make typecheck     # Run basedpyright type checker
-
-# Development workflow
-make dev           # Quick development check (format + lint + typecheck)
-
-# Cleanup
-make clean         # Remove build artifacts and caches
-```
-
-### Testing
-
-```bash
-# Run tests (using pytest)
-pytest
-
-# Run specific test file
-pytest tests/test_example.py
+make dev           # Quick check (format + lint + typecheck)
+make all           # Complete quality check
+make test          # Run tests
+make test-cov      # Run tests with coverage
+make clean         # Remove build artifacts
+make start         # Kill previous instances and start LiteLLM + Balatro
 ```
 
 ## Architecture
 
-### Core Components
-
-**LLMBot (`src/balatrollm/llm.py`)**
-- Main bot implementation that orchestrates game play
-- Manages LiteLLM client connection and model validation
-- Handles game state analysis and decision making through LLM
-- Executes actions via BalatroClient integration
-- Uses Jinja2 templates for prompt generation
-
-**CLI Entry Point (`src/balatrollm/__init__.py`)**
-- Command-line interface with argument parsing
-- Environment variable support for configuration
-- Proxy connection validation and error handling
-- Async game execution wrapper
+**LLMBot (`src/balatrollm/llm.py`)**: Main bot with Config dataclass, TemplateManager integration, LLM decision-making, response history tracking, and BalatroClient integration.
 
-**Template System (`src/balatrollm/templates/`)**
-- `system.md.jinja`: Comprehensive Balatro strategy guide and rules
-- `game_state.md.jinja`: Dynamic game state representation for LLM analysis
-- Templates use Jinja2 with custom filters (e.g., `from_json`)
+**CLI Entry Point (`src/balatrollm/__init__.py`)**: Command-line interface with argument parsing, environment variable support, proxy validation, and async game execution.
 
-**Tools Configuration (`src/balatrollm/tools.json`)**
-- OpenAI function calling definitions for different game states
-- Maps game states (BLIND_SELECT, SELECTING_HAND, SHOP) to available actions
-- Defines function schemas for LLM tool use
+**Template System (`src/balatrollm/templates/`)**: Strategy-based organization:
+- `default/`: Conservative strategy (financial discipline)
+- `aggressive/`: High-risk, high-reward strategy
 
-### Key Dependencies
+Each strategy contains:
+- `STRATEGY.md.jinja`: Strategy-specific guide
+- `GAMESTATE.md.jinja`: Game state representation
+- `MEMORY.md.jinja`: Response history tracking
+- `TOOLS.json`: Strategy-specific function definitions
 
-- **balatrobot**: Core Balatro game client (from git repository)
-- **litellm**: LLM proxy server for multiple providers
-- **openai**: OpenAI client for LLM communication
-- **jinja2**: Template engine for prompt generation
-- **httpx**: HTTP client for proxy health checks
+**Key Dependencies**: balatrobot, litellm, openai, jinja2, httpx
 
-### Game Integration Flow
+**Game Flow**: 
+1. Validate proxy connection and model availability
+2. Game loop: Get state → Render templates → Send to LLM → Parse response → Execute action
+3. Handle different states: BLIND_SELECT, SELECTING_HAND, SHOP, ROUND_EVAL
 
-1. **Initialization**: Validate LiteLLM proxy connection and model availability
-2. **Game Loop**:
-   - Get current game state from BalatroClient
-   - Render game state using Jinja2 templates
-   - Send context to LLM with state-specific tools
-   - Parse LLM tool call response
-   - Execute action through BalatroClient
-3. **State Handling**: Different logic for BLIND_SELECT, SELECTING_HAND, SHOP, ROUND_EVAL states
+**Available Models** (`config/litellm.yaml`):
+- **Cerebras**: cerebras-qwen3-235b (default), cerebras-gpt-oss-120b, cerebras-gpt-oss-20b
+- **Groq**: groq-qwen3-32b
+- **Local**: LM Studio integration
 
-### LiteLLM Configuration
+**Environment Variables**:
+- `CEREBRAS_API_KEY`, `GROQ_API_KEY`
+- `LITELLM_MODEL` (default: cerebras-qwen3-235b)
+- `LITELLM_PROXY_URL` (default: http://localhost:4000)
+- `LITELLM_API_KEY` (default: sk-balatrollm-proxy-key)
+- `BALATROLLM_TEMPLATE` (default: system)
 
-The `config/litellm.yaml` defines available models:
-- **Cerebras**: High-performance cloud inference (gpt-oss-120b, gpt-oss-20b)
-- **Groq**: Fast inference with Qwen models
-- **Local**: LM Studio integration for development
+## Code Quality
 
-Environment variables required:
-- `CEREBRAS_API_KEY`: For Cerebras models
-- `GROQ_API_KEY`: For Groq models
+Uses Ruff (linting/formatting), basedpyright (type checking), pytest (testing), conventional commits, and Release Please automation.
 
-## Development Guidelines
-
-### Code Quality
-- Uses Ruff for linting and formatting with import sorting
-- Uses basedpyright for type checking in basic mode
-- Follows conventional commits specification
-- Automated release process with Release Please
-
-### Project Structure
+## Project Structure
 
 ```
 src/balatrollm/
-├── __init__.py             # CLI entry point and argument parsing
-├── llm.py                  # Core LLMBot implementation
-├── tools.json              # OpenAI function definitions by game state
-└── templates/
-    ├── system.md.jinja     # Comprehensive game strategy guide
-    └── game_state.md.jinja # Dynamic game state representation
+├── __init__.py                    # CLI entry point
+├── llm.py                         # Core LLMBot with Config and TemplateManager
+└── templates/                     # Strategy-based templates
+    ├── default/                   # Conservative strategy
+    └── aggressive/                # High-risk strategy
+        ├── STRATEGY.md.jinja      # Strategy guide
+        ├── GAMESTATE.md.jinja     # Game state representation
+        ├── MEMORY.md.jinja        # Response history
+        └── TOOLS.json             # Function definitions
+
+balatro.sh                         # Game automation script
+runs/                              # Game execution logs (organized by version/model/strategy)
+tests/test_llm.py                  # Test suite
 ```
 
-### Template System Usage
-
-- Templates handle complex game state rendering for LLM context
-- System template contains extensive Balatro strategy documentation
-- Game state template dynamically formats current game information
-- Custom Jinja2 filter `from_json` for JSON parsing in templates
-
-### Error Handling Patterns
-
-- Proxy connection validation before game start
-- Model availability checking with fallback suggestions
-- Graceful keyboard interrupt handling
-- Comprehensive logging with different verbosity levels
-
-## Dependency Documentation
-
-When working with code that uses these dependencies, search their documentation using Context7 MCP server (`--c7` flag) with these library IDs:
-
-**Core Dependencies:**
-
-- **balatrobot**: `/s1m0n38/balatrobot`
-- **jinja2**: `/pallets/jinja`
-- **openai**: `/openai/openai-python`
-- **litellm**: `/berriai/litellm`
-- **httpx**: `/encode/httpx`
+## Context7 Library IDs
 
-**Dev Dependencies:**
+**Core**: `/s1m0n38/balatrobot`, `/pallets/jinja`, `/openai/openai-python`, `/berriai/litellm`, `/encode/httpx`
+**Dev**: `/detachhead/basedpyright`, `/pytest-dev/pytest`, `/pytest-dev/pytest-asyncio`, `/astral-sh/ruff`, `/astral-sh/uv`
 
-- **basedpyright**: `/detachhead/basedpyright`
-- **pytest**: `/pytest-dev/pytest`
-- **pytest-asyncio**: `/pytest-dev/pytest-asyncio`
-- **ruff**: `/astral-sh/ruff`
-- **uv**: `/astral-sh/uv`
+## Results Tracking
 
-**Usage:** When implementing features or fixing issues related to any of these libraries, use the Context7 MCP server to get up-to-date documentation and code examples.
+- `runs/[version]/[model]/[strategy]/[timestamp]_[deck]_[seed].jsonl`
+- JSONL format for performance analysis across models and strategies
 
-## Important Notes
+## Strategy System
 
-- The bot currently has LLM decision-making enabled only for SELECTING_HAND state
-- BLIND_SELECT and SHOP states use hardcoded actions (TODOs indicate future LLM integration)
-- Game state management relies on BalatroClient state machine
-- LiteLLM proxy must be running before starting the bot
-- Response history is maintained for context in subsequent LLM calls
+**Default** (`--template default`): Conservative, financially disciplined approach
+**Aggressive** (`--template aggressive`): High-risk, high-reward approach with aggressive spending