SETUP.md

🛠️ Team Setup Guide — AI Sprint Manager OpenEnv

Complete setup instructions for Windows and Mac teammates.

---

📋 Prerequisites

Windows

1. Install Python 3.11

   • Download from https://www.python.org/downloads/
   • ✅ Check "Add Python to PATH" during install
   • Verify: open PowerShell and run python --version

2. Install Git

   • Download from https://git-scm.com/download/win
   • Use default options during install
   • Verify: git --version

3. Install Docker Desktop

   • Download from https://www.docker.com/products/docker-desktop/
   • Requires Windows 10/11 with WSL2 enabled
   • After install, open Docker Desktop and wait for it to start
   • Verify: docker --version

4. Install VS Code (recommended)

   • Download from https://code.visualstudio.com/

Mac

1. Install Homebrew (package manager)

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   

2. Install Python 3.11

   brew install python@3.11
   

   Verify: python3.11 --version

3. Install Git

   brew install git
   

   Verify: git --version

4. Install Docker Desktop

   • Download from https://www.docker.com/products/docker-desktop/
   • Choose Apple Silicon or Intel depending on your Mac
   • Open Docker Desktop and wait for it to start
   • Verify: docker --version

---

📥 Clone the GitHub Repo

# Both Windows (PowerShell) and Mac (Terminal)
git clone https://github.com/YOUR_GITHUB_USERNAME/ai-sprint-manager-openenv.git
cd ai-sprint-manager-openenv

---

🌿 Create Your Own Branch

# Replace "yourname" with your actual name
git checkout -b feature/yourname-improvements

Verify you're on your branch:

git branch
# Should show * feature/yourname-improvements

---

🐍 Set Up Virtual Environment

Windows

python -m venv venv
venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txt
pip install python-dotenv

Mac

python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
pip install python-dotenv

---

⚙️ Create Your .env File

Create a file called .env in the project root (never commit this!):

HF_TOKEN=hf_your_token_here
API_BASE_URL=https://router.huggingface.co/v1
MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct
ENV_BASE_URL=http://localhost:7860

We'll get the HF_TOKEN in the next section.

---

🤗 Create Hugging Face Account & Token

1. Go to https://huggingface.co and sign up
2. Go to https://huggingface.co/settings/tokens
3. Click New token
4. Name: sprint-manager-token
5. Type: Read
6. Click Create token and copy it
7. Paste it into your .env file as HF_TOKEN=hf_...

---

🚀 Run Locally & Test

Terminal 1 — Start the API + UI server

Windows

python ui.py

Mac

python ui.py

Terminal 2 — Test the API

Windows

Invoke-WebRequest -Uri http://localhost:7860/health -Method GET

Mac

curl http://localhost:7860/health
# Expected: {"status":"ok","env":"ai-sprint-manager"}

Test via Browser

Open http://localhost:7860 — you should see the Gradio sprint board UI.

Try:

1. Select easy_sprint, click 🔄 Reset Sprint
2. Set Action=assign, Task ID=T1, Dev ID=dev1
3. Click ▶️ Take Action
4. You should see a positive reward and T1 assigned to Alice

Run Inference Locally

# Make sure .env file has your HF_TOKEN
python inference.py

---

🐳 Test with Docker

docker build -t ai-sprint-manager .

Windows

docker run -p 7860:7860 ai-sprint-manager

Mac

docker run -p 7860:7860 ai-sprint-manager

Open http://localhost:7860 to verify.

---

☁️ Create Your Own HF Space & Deploy

1. Go to https://huggingface.co/new-space

2. Fill in:

   • Space name: ai-sprint-manager-yourname
   • SDK: Docker
   • Visibility: Public

3. Click Create Space

4. Add your HF token as a Secret:

   • Go to Space → Settings → Variables and secrets
   • Add secret: Name=HF_TOKEN, Value=your token

5. Add HF as a git remote and push your branch:

git remote add myspace https://huggingface.co/spaces/YOUR_HF_USERNAME/ai-sprint-manager-yourname
git push myspace feature/yourname-improvements:main

6. Wait 2-3 minutes for build. Test your live Space:

Windows

Invoke-WebRequest -Uri "https://YOUR_HF_USERNAME-ai-sprint-manager-yourname.hf.space/health" -Method GET

Mac

curl https://YOUR_HF_USERNAME-ai-sprint-manager-yourname.hf.space/health

---

🔧 Run OpenEnv Validation

pip install openenv-core uv
uv lock
openenv validate
# Expected: [OK] ai-sprint-manager: Ready for multi-mode deployment

---

💡 Suggested Improvements for Teammates

🟢 Easy (Good for getting started)

1. Better skill matching UI — Show a skill-to-dev mapping table in the Gradio UI so users know which dev to pick
2. Sprint history chart — Add a reward-over-time line chart using gr.Plot
3. Add more tasks — Expand tasks.py with more realistic task names and types
4. Auto-assign button — Add a Gradio button that automatically assigns all backlog tasks using a simple rule (best skill match)

🟡 Medium

5. Session isolation — Currently all users share one env instance. Add session IDs so multiple users can use the UI simultaneously
6. Sprint replay — Save the full episode history and add a "replay" feature to the UI
7. Better reward visualization — Add a bar chart showing per-task completion status
8. Configurable sprint length — Let users set sprint length (5/10/15 days) in the UI

🔴 Hard (Advanced)

9. Real RL training loop — Add a train.py script using Stable-Baselines3 or TRL+GRPO to actually train a policy
10. Multi-agent support — Let multiple AI agents collaborate on sprint management
11. WebSocket support — Upgrade from HTTP to WebSocket for real-time updates per OpenEnv spec
12. Custom sprint builder — Let users define their own tasks and team in the UI

---

📤 Submit Your Changes

git add .
git commit -m "feat: your improvement description"
git push origin feature/yourname-improvements

Then open a Pull Request on GitHub to merge into main.