SETUP.md

Setup Guide (VS Code)

Prerequisites

• Python 3.11 or higher — download from python.org
• Git — download from git-scm.com
• VS Code — download from 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
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