Skip to content

Commit 3ec3aae

Browse files
Muhtashamjohn-b-yang
Muhtasham
and
john-b-yang
authored
Update the docs to be uv-native and more onboarding-friendly (#85)
* Update the docs to be uv-native and more onboarding-friendly * Revert changes to dockerfiles --------- Co-authored-by: John Yang <[email protected]>
1 parent e6f3901 commit 3ec3aae

File tree

8 files changed

+4222
-124
lines changed

8 files changed

+4222
-124
lines changed

‎.env.example‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# CodeClash Environment Variables
2+
# Copy this file to .env and fill in your values
3+
4+
# Required: GitHub token with repo access for cloning game repositories
5+
GITHUB_TOKEN=your_github_token_here
6+
7+
# Optional: LLM Provider API Keys (configure the ones you plan to use)
8+
OPENAI_API_KEY=
9+
ANTHROPIC_API_KEY=

‎CONTRIBUTING.md‎

Lines changed: 191 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,198 @@
1-
# Contributing Guide
1+
# Contributing to CodeClash
22

33
Thanks for your interest in contributing to CodeClash!
44

5-
We're actively working on expanding the coverage of CodeClash in terms of models, arenas, and evaluation techniques.
6-
We're also excited about your ideas!
5+
We're actively working on expanding the coverage of CodeClash in terms of models, arenas, and evaluation techniques. We'd love your help!
6+
7+
## Ideas and Discussions
78

89
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.
910

1011
Have suggestions? Please open an issue, and let's discuss!
12+
13+
## Development Setup
14+
15+
### Prerequisites
16+
17+
- Python 3.11+
18+
- [uv](https://docs.astral.sh/uv/) - Fast Python package manager
19+
- Docker - For running games in containers
20+
- Git
21+
22+
### Getting Started
23+
24+
```bash
25+
# Clone the repository
26+
git clone https://github.com/CodeClash-ai/CodeClash.git
27+
cd CodeClash
28+
29+
# Install uv (if you haven't already)
30+
curl -LsSf https://astral.sh/uv/install.sh | sh
31+
32+
# Install dependencies with dev extras
33+
uv sync --extra dev
34+
35+
# Install pre-commit hooks
36+
uv run pre-commit install
37+
38+
# Set up environment variables
39+
cp .env.example .env
40+
# Edit .env with your GITHUB_TOKEN and any LLM API keys
41+
```
42+
43+
### Running Tests
44+
45+
```bash
46+
# Run all tests
47+
uv run pytest
48+
49+
# Run with coverage
50+
uv run pytest --cov=codeclash
51+
52+
# Run tests in parallel
53+
uv run pytest -n auto
54+
55+
# Run a specific test file
56+
uv run pytest tests/test_integration.py
57+
```
58+
59+
### Code Quality
60+
61+
We use [ruff](https://docs.astral.sh/ruff/) for linting and formatting:
62+
63+
```bash
64+
# Check for linting issues
65+
uv run ruff check .
66+
67+
# Auto-fix linting issues
68+
uv run ruff check . --fix
69+
70+
# Format code
71+
uv run ruff format .
72+
73+
# Check formatting without changing files
74+
uv run ruff format . --check
75+
```
76+
77+
Pre-commit hooks will run these checks automatically before each commit.
78+
79+
### Documentation
80+
81+
We use [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) for documentation:
82+
83+
```bash
84+
# Install docs dependencies
85+
uv sync --extra docs
86+
87+
# Preview docs locally (with hot reload)
88+
uv run mkdocs serve
89+
90+
# Build static docs
91+
uv run mkdocs build
92+
```
93+
94+
Documentation lives in the `docs/` directory.
95+
96+
## Project Structure
97+
98+
```
99+
CodeClash/
100+
├── codeclash/
101+
│ ├── agents/ # AI agent implementations (MiniSWEAgent, etc.)
102+
│ ├── arenas/ # Game arena implementations
103+
│ ├── analysis/ # Post-tournament analysis tools
104+
│ ├── tournaments/ # Tournament orchestration
105+
│ ├── viewer/ # Web-based results viewer
106+
│ └── utils/ # Shared utilities
107+
├── configs/ # Tournament configuration files
108+
├── docs/ # Documentation (MkDocs)
109+
├── tests/ # Test suite
110+
└── main.py # Main entry point
111+
```
112+
113+
## Types of Contributions
114+
115+
### Adding a New Arena
116+
117+
1. Create a new file in `codeclash/arenas/`
118+
2. Extend the `CodeArena` abstract class
119+
3. Implement required methods: `execute_round()`, `validate_code()`, `get_results()`
120+
4. Add documentation in `docs/reference/arenas/`
121+
5. Add example configs in `configs/`
122+
123+
### Adding a New Agent Type
124+
125+
1. Create a new file in `codeclash/agents/`
126+
2. Extend the `Player` abstract class
127+
3. Implement the `run()` method for code improvement logic
128+
4. Add documentation in `docs/reference/player/`
129+
130+
### Improving Analysis Tools
131+
132+
Analysis tools live in `codeclash/analysis/`. We're particularly interested in:
133+
134+
- New metrics for evaluating agent performance
135+
- Better visualization of tournament results
136+
- Statistical analysis improvements
137+
138+
### Bug Fixes and Improvements
139+
140+
- Bug fixes are always welcome!
141+
- Performance improvements
142+
- Documentation improvements
143+
- Test coverage improvements
144+
145+
## Pull Request Process
146+
147+
1. Fork the repository
148+
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
149+
3. Make your changes
150+
4. Run tests and linting (`uv run pytest && uv run ruff check .`)
151+
5. Commit your changes with a descriptive message
152+
6. Push to your fork
153+
7. Open a Pull Request
154+
155+
### PR Guidelines
156+
157+
- Keep PRs focused on a single change
158+
- Add tests for new functionality
159+
- Update documentation as needed
160+
- Follow existing code style (enforced by ruff)
161+
162+
## Common Development Tasks
163+
164+
| Task | Command |
165+
|------|---------|
166+
| Install dependencies | `uv sync --extra dev` |
167+
| Run tests | `uv run pytest` |
168+
| Lint code | `uv run ruff check .` |
169+
| Format code | `uv run ruff format .` |
170+
| Preview docs | `uv run mkdocs serve` |
171+
| Build wheel | `uv build --wheel` |
172+
| Build wheel + sdist | `uv build` |
173+
| Run a tournament | `uv run python main.py <config>` |
174+
| View results | `uv run python scripts/run_viewer.py` |
175+
176+
### Building Distributions
177+
178+
To build a distributable wheel package:
179+
180+
```bash
181+
# Build wheel only
182+
uv build --wheel
183+
184+
# Build both wheel and source distribution
185+
uv build
186+
187+
# Build with clean output directory
188+
uv build --wheel --clear
189+
```
190+
191+
Built artifacts will be placed in the `dist/` directory by default.
192+
193+
## Contact
194+
195+
- **John Yang**: [[email protected]](mailto:[email protected])
196+
- **Kilian Lieret**: [[email protected]](mailto:[email protected])
197+
198+
Feel free to reach out with questions or ideas!

‎README.md‎

Lines changed: 38 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,10 @@
55
</p>
66

77
<div align="center">
8-
<a href="https://www.python.org/"><img alt="Build" src="https://img.shields.io/badge/Python-3.10+-1f425f.svg?color=purple"></a>
9-
<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>
8+
<a href="https://www.python.org/"><img alt="Build" src="https://img.shields.io/badge/Python-3.11+-1f425f.svg?color=purple"></a>
9+
<a href="https://copyright.princeton.edu/policy"><img alt="License" src="https://img.shields.io/badge/License-MIT-blue"></a>
10+
<a href="https://arxiv.org/abs/2511.00839"><img src="https://img.shields.io/badge/arXiv-2511.00839-b31b1b.svg"></a>
11+
<a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/badge/uv-package%20manager-blueviolet"></a>
1012
</div>
1113

1214
<hr />
@@ -28,22 +30,50 @@ Check out our [arXiv paper](https://arxiv.org/abs/2511.00839) and [website](http
2830

2931
## 🏎️ Quick Start
3032

31-
To start, follow these steps to set up CodeClash and run a test battle:
33+
### Prerequisites
34+
35+
- **Python 3.11+**
36+
- **[uv](https://docs.astral.sh/uv/)** - Fast Python package manager
37+
- **Docker** - For running games in containers
38+
- **Git**
39+
40+
### Installation
41+
3242
```bash
33-
$ git clone [email protected]:CodeClash-ai/CodeClash.git
34-
$ cd CodeClash
35-
$ pip install -e '.[dev]'
36-
$ python main.py configs/test/battlesnake.yaml
43+
# Clone the repository
44+
git clone https://github.com/CodeClash-ai/CodeClash.git
45+
cd CodeClash
46+
47+
# Install uv (if you haven't already)
48+
curl -LsSf https://astral.sh/uv/install.sh | sh
49+
50+
# Install dependencies and create virtual environment
51+
uv sync --extra dev
52+
53+
# Set up your environment variables
54+
cp .env.example .env # Then edit .env with your GITHUB_TOKEN
55+
56+
# Run a test battle
57+
uv run python main.py configs/test/battlesnake.yaml
3758
```
3859

3960
> [!TIP]
4061
> CodeClash requires Docker to create execution environments. CodeClash was developed and tested on Ubuntu 22.04.4 LTS.
4162
> The same instructions should work for Mac. If not, check out [#81](https://github.com/CodeClash-ai/CodeClash/issues/81) for an alternative solution.
4263
64+
<details>
65+
<summary>Alternative: Using pip (not recommended)</summary>
66+
67+
```bash
68+
pip install -e '.[dev]'
69+
python main.py configs/test/battlesnake.yaml
70+
```
71+
</details>
72+
4373
Once this works, you should be set up to run a real tournament!
4474
To run *Claude Sonnet 4.5* against *o3* in a *BattleSnake* tournament with *5 rounds* and *1000 competition simulations* per round, run:
4575
```bash
46-
$ python main.py configs/examples/BattleSnake__claude-sonnet-4-5-20250929__o3__r5__s1000.yaml
76+
uv run python main.py configs/examples/BattleSnake__claude-sonnet-4-5-20250929__o3__r5__s1000.yaml
4777
```
4878

4979
## ⚔️ How It Works

0 commit comments

Comments
 (0)