Merge branch 'main' into chess-arena

Author: john-b-yang

.env.example

@@ -0,0 +1,9 @@
+# CodeClash Environment Variables
+# Copy this file to .env and fill in your values
+
+# Required: GitHub token with repo access for cloning game repositories
+GITHUB_TOKEN=your_github_token_here
+
+# Optional: LLM Provider API Keys (configure the ones you plan to use)
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=

CONTRIBUTING.md

@@ -1,10 +1,198 @@
-# Contributing Guide
+# Contributing to CodeClash
 
 Thanks for your interest in contributing to CodeClash!
 
-We're actively working on expanding the coverage of CodeClash in terms of models, arenas, and evaluation techniques.
-We're also excited about your ideas!
+We're actively working on expanding the coverage of CodeClash in terms of models, arenas, and evaluation techniques. We'd love your help!
+
+## Ideas and Discussions
 
 We have a [living document](https://docs.google.com/document/d/17-Jcexy1KDAbxXILH-GlHrFwGTpLG5yml-0OMFfgnZU/edit?usp=sharing) where we track ideas and contributions we're excited about.
 
 Have suggestions? Please open an issue, and let's discuss!
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) - Fast Python package manager
+- Docker - For running games in containers
+- Git
+
+### Getting Started
+
+```bash
+# Clone the repository
+git clone https://github.com/CodeClash-ai/CodeClash.git
+cd CodeClash
+
+# Install uv (if you haven't already)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install dependencies with dev extras
+uv sync --extra dev
+
+# Install pre-commit hooks
+uv run pre-commit install
+
+# Set up environment variables
+cp .env.example .env
+# Edit .env with your GITHUB_TOKEN and any LLM API keys
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov=codeclash
+
+# Run tests in parallel
+uv run pytest -n auto
+
+# Run a specific test file
+uv run pytest tests/test_integration.py
+```
+
+### Code Quality
+
+We use [ruff](https://docs.astral.sh/ruff/) for linting and formatting:
+
+```bash
+# Check for linting issues
+uv run ruff check .
+
+# Auto-fix linting issues
+uv run ruff check . --fix
+
+# Format code
+uv run ruff format .
+
+# Check formatting without changing files
+uv run ruff format . --check
+```
+
+Pre-commit hooks will run these checks automatically before each commit.
+
+### Documentation
+
+We use [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) for documentation:
+
+```bash
+# Install docs dependencies
+uv sync --extra docs
+
+# Preview docs locally (with hot reload)
+uv run mkdocs serve
+
+# Build static docs
+uv run mkdocs build
+```
+
+Documentation lives in the `docs/` directory.
+
+## Project Structure
+
+```
+CodeClash/
+├── codeclash/
+│   ├── agents/          # AI agent implementations (MiniSWEAgent, etc.)
+│   ├── arenas/          # Game arena implementations
+│   ├── analysis/        # Post-tournament analysis tools
+│   ├── tournaments/     # Tournament orchestration
+│   ├── viewer/          # Web-based results viewer
+│   └── utils/           # Shared utilities
+├── configs/             # Tournament configuration files
+├── docs/                # Documentation (MkDocs)
+├── tests/               # Test suite
+└── main.py              # Main entry point
+```
+
+## Types of Contributions
+
+### Adding a New Arena
+
+1. Create a new file in `codeclash/arenas/`
+2. Extend the `CodeArena` abstract class
+3. Implement required methods: `execute_round()`, `validate_code()`, `get_results()`
+4. Add documentation in `docs/reference/arenas/`
+5. Add example configs in `configs/`
+
+### Adding a New Agent Type
+
+1. Create a new file in `codeclash/agents/`
+2. Extend the `Player` abstract class
+3. Implement the `run()` method for code improvement logic
+4. Add documentation in `docs/reference/player/`
+
+### Improving Analysis Tools
+
+Analysis tools live in `codeclash/analysis/`. We're particularly interested in:
+
+- New metrics for evaluating agent performance
+- Better visualization of tournament results
+- Statistical analysis improvements
+
+### Bug Fixes and Improvements
+
+- Bug fixes are always welcome!
+- Performance improvements
+- Documentation improvements
+- Test coverage improvements
+
+## Pull Request Process
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests and linting (`uv run pytest && uv run ruff check .`)
+5. Commit your changes with a descriptive message
+6. Push to your fork
+7. Open a Pull Request
+
+### PR Guidelines
+
+- Keep PRs focused on a single change
+- Add tests for new functionality
+- Update documentation as needed
+- Follow existing code style (enforced by ruff)
+
+## Common Development Tasks
+
+| Task | Command |
+|------|---------|
+| Install dependencies | `uv sync --extra dev` |
+| Run tests | `uv run pytest` |
+| Lint code | `uv run ruff check .` |
+| Format code | `uv run ruff format .` |
+| Preview docs | `uv run mkdocs serve` |
+| Build wheel | `uv build --wheel` |
+| Build wheel + sdist | `uv build` |
+| Run a tournament | `uv run python main.py <config>` |
+| View results | `uv run python scripts/run_viewer.py` |
+
+### Building Distributions
+
+To build a distributable wheel package:
+
+```bash
+# Build wheel only
+uv build --wheel
+
+# Build both wheel and source distribution
+uv build
+
+# Build with clean output directory
+uv build --wheel --clear
+```
+
+Built artifacts will be placed in the `dist/` directory by default.
+
+## Contact
+
+- **John Yang**: [johnby@stanford.edu](mailto:johnby@stanford.edu)
+- **Kilian Lieret**: [kl5675@princeton.edu](mailto:kl5675@princeton.edu)
+
+Feel free to reach out with questions or ideas!

README.md

@@ -5,8 +5,10 @@
 </p>
 
 <div align="center">
-<a href="https://www.python.org/"><img alt="Build" src="https://img.shields.io/badge/Python-3.10+-1f425f.svg?color=purple"></a>
-<a href="https://copyright.princeton.edu/policy"><img alt="License" src="https://img.shields.io/badge/License-MIT-blue"></a> <a href="https://arxiv.org/abs/2511.00839"><img src="https://img.shields.io/badge/arXiv-2511.00839-b31b1b.svg"></a>
+<a href="https://www.python.org/"><img alt="Build" src="https://img.shields.io/badge/Python-3.11+-1f425f.svg?color=purple"></a>
+<a href="https://copyright.princeton.edu/policy"><img alt="License" src="https://img.shields.io/badge/License-MIT-blue"></a>
+<a href="https://arxiv.org/abs/2511.00839"><img src="https://img.shields.io/badge/arXiv-2511.00839-b31b1b.svg"></a>
+<a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/badge/uv-package%20manager-blueviolet"></a>
 </div>
 
 <hr />
@@ -28,21 +30,50 @@ Check out our [arXiv paper](https://arxiv.org/abs/2511.00839) and [website](http
 
 ## 🏎️ Quick Start
 
-To start, follow these steps to set up CodeClash and run a test battle:
+### Prerequisites
+
+- **Python 3.11+**
+- **[uv](https://docs.astral.sh/uv/)** - Fast Python package manager
+- **Docker** - For running games in containers
+- **Git**
+
+### Installation
+
 ```bash
-$ git clone git@github.com:CodeClash-ai/CodeClash.git
-$ cd CodeClash
-$ pip install -e '.[dev]'
-$ python main.py configs/test/battlesnake.yaml
+# Clone the repository
+git clone https://github.com/CodeClash-ai/CodeClash.git
+cd CodeClash
+
+# Install uv (if you haven't already)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install dependencies and create virtual environment
+uv sync --extra dev
+
+# Set up your environment variables
+cp .env.example .env  # Then edit .env with your GITHUB_TOKEN
+
+# Run a test battle
+uv run python main.py configs/test/battlesnake.yaml
 ```
 
 > [!TIP]
 > CodeClash requires Docker to create execution environments. CodeClash was developed and tested on Ubuntu 22.04.4 LTS.
+> The same instructions should work for Mac. If not, check out [#81](https://github.com/CodeClash-ai/CodeClash/issues/81) for an alternative solution.
+
+<details>
+<summary>Alternative: Using pip (not recommended)</summary>
+
+```bash
+pip install -e '.[dev]'
+python main.py configs/test/battlesnake.yaml
+```
+</details>
 
 Once this works, you should be set up to run a real tournament!
 To run *Claude Sonnet 4.5* against *o3* in a *BattleSnake* tournament with *5 rounds* and *1000 competition simulations* per round, run:
 ```bash
-$ python main.py configs/examples/BattleSnake__claude-sonnet-4-5-20250929__o3__r5__s1000.yaml
+uv run python main.py configs/examples/BattleSnake__claude-sonnet-4-5-20250929__o3__r5__s1000.yaml
 ```
 
 ## ⚔️ How It Works

codeclash/agents/minisweagent.py

@@ -16,7 +16,9 @@
 from codeclash.utils.environment import copy_to_container
 
 os.environ["MSWEA_MODEL_RETRY_STOP_AFTER_ATTEMPT"] = "90"
-os.environ["LITELLM_MODEL_REGISTRY_PATH"] = str((REPO_DIR / "configs" / "litellm_custom_model_config.yaml").resolve())
+os.environ["LITELLM_MODEL_REGISTRY_PATH"] = str(
+    (REPO_DIR / "configs" / "mini" / "litellm_custom_model_config.yaml").resolve()
+)
 
 
 class ClashAgent(DefaultAgent):

codeclash/analysis/llm_as_judge/action_categories_by_model.py

@@ -132,7 +132,7 @@
 gap = 0.3
 y_positions = []
 model_positions = []
-for i, model in enumerate(models):
+for i in range(len(models)):
     base = i * (2 + gap)
     y_positions.extend([base, base + 1])
     model_positions.append(base + 0.5)
@@ -197,7 +197,7 @@
     )
 
 # Add round labels on the left side of the plot
-for i, (y_late, y_early) in enumerate(zip(y_positions[::2], y_positions[1::2])):
+for y_late, y_early in zip(y_positions[::2], y_positions[1::2]):
     ax.text(-0.2, y_late, "round ≥8", fontsize=11, ha="right", va="center", color="gray", fontproperties=FONT_BOLD)
     ax.text(-0.2, y_early, "round ≤7", fontsize=11, ha="right", va="center", color="gray", fontproperties=FONT_BOLD)
 

codeclash/analysis/llm_as_judge/big_questions.py

@@ -6,7 +6,7 @@
 import re
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
-from typing import Literal
+from typing import Any, Literal
 
 import jinja2
 import yaml
@@ -23,7 +23,6 @@
     stop_after_attempt,
     wait_exponential,
 )
-from typing_extensions import Any
 
 from codeclash.analysis.llm_as_judge.utils import FileLock, Instance, InstanceBatch, get_instances
 from codeclash.utils.log import get_logger

codeclash/analysis/llm_as_judge/visualize.ipynb.py

@@ -280,7 +280,7 @@
 gap = 0.3
 y_positions = []
 model_positions = []
-for i, model in enumerate(models):
+for i in range(len(models)):
     base = i * (2 + gap)
     y_positions.extend([base, base + 1])
     model_positions.append(base + 0.5)
@@ -340,7 +340,7 @@
     left = [left[i] + values[i] for i in range(len(y_positions))]
 
 # Add round labels on the right side of the plot
-for i, (y_late, y_early) in enumerate(zip(y_positions[::2], y_positions[1::2])):
+for y_late, y_early in zip(y_positions[::2], y_positions[1::2]):
     ax.text(-2, y_late, "round ≥8", fontsize=9, ha="right", va="center", color="gray")
     ax.text(-2, y_early, "round ≤7", fontsize=9, ha="right", va="center", color="gray")
 

codeclash/analysis/matrix.py

@@ -8,7 +8,7 @@
 
 from codeclash.agents.dummy_agent import Dummy
 from codeclash.agents.utils import GameContext
-from codeclash.arenas import get_game
+from codeclash.arenas import get_arena
 from codeclash.constants import DIR_WORK
 from codeclash.tournaments.utils.git_utils import filter_git_diff
 from codeclash.utils.atomic_write import atomic_write
@@ -109,7 +109,7 @@ def _initialize_game_pool(self):
             config = self.config.copy()
             config["game"]["sims_per_round"] = self.n_repetitions
 
-            game = get_game(
+            game = get_arena(
                 config,
                 tournament_id=tournament_id,
                 local_output_dir=self.pvp_output_dir / "matrix_eval" / f"worker_{i}",