SETUP.md

# Setup Guide (VS Code)

## Prerequisites
- Python 3.11 or higher — download from [python.org](https://python.org)
- Git — download from [git-scm.com](https://git-scm.com)
- VS Code — download from [code.visualstudio.com](https://code.visualstudio.com)

---

## Step 1 — Open the project

1. Unzip `teamforge.zip`
2. In VS Code: **File → Open Folder** → select the `teamforge` folder
3. Open the terminal: **View → Terminal** (or `Ctrl + `` ` ``)

---

## Step 2 — Create virtual environment

**Windows:**
```
python -m venv venv
venv\Scripts\activate
```

**Mac / Linux:**
```
python3 -m venv venv
source venv/bin/activate
```

You should see `(venv)` appear at the start of your terminal prompt.

> **If `python -m venv venv` hangs or errors:**
> - Try `py -m venv venv` (Windows)
> - Try `python3 -m venv venv` (Mac/Linux)
> - Or skip venv and just run `pip install -r requirements.txt` directly

---

## Step 3 — Install dependencies

```
pip install -r requirements.txt
```

This installs: pydantic, openai, rich, pytest, ruff

---

## Step 4 — Run the demo (no API key needed!)

```
python demo.py
```

You will see a beautiful step-by-step agent trace in your terminal.

---

## Step 5 — Run the tests

```
pytest tests/test_environment.py -v
```

All 21 tests should pass (green).

---

## Step 6 — Get a free Groq API key

1. Go to [console.groq.com](https://console.groq.com)
2. Sign up (free, no credit card)
3. Create an API key
4. Copy `.env.example` → `.env` and paste your key:
   ```
   cp .env.example .env
   ```
   Then open `.env` and set:
   ```
   GROQ_API_KEY=gsk_your_key_here
   ```

---

## Step 7 — Run the benchmark

**Windows:**
```
set GROQ_API_KEY=gsk_your_key_here
python benchmark.py --model llama3-8b-8192
```

**Mac / Linux:**
```
export GROQ_API_KEY=gsk_your_key_here
python benchmark.py --model llama3-8b-8192
```

---

## Common Issues

| Problem | Fix |
|---------|-----|
| `python` not found | Use `python3` or `py` instead |
| `venv` command hangs | Skip it, run `pip install -r requirements.txt` directly |
| `ModuleNotFoundError: rich` | Run `pip install -r requirements.txt` |
| `git: command not found` | Install Git from git-scm.com |
| Terminal shows `>>>` | You're in Python REPL — press `Ctrl+Z` then Enter to exit |

---

## File Structure

```
teamforge/
├── demo.py               ← run this first
├── benchmark.py          ← model comparison
├── baseline_inference.py ← single agent run
├── environment.py        ← core environment
├── models.py             ← data models
├── grader.py             ← scoring
├── reward.py             ← reward function
├── tasks/                ← easy / medium / hard / bonus
├── sandbox/              ← git isolation
├── tests/                ← test suite
├── results/              ← benchmark output
├── requirements.txt      ← dependencies
├── .env.example          ← copy to .env with your API key
└── README.md             ← full documentation
```