| # 🛠️ 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) |
| ```bash |
| /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" |
| ``` |
|
|
| 2. **Install Python 3.11** |
| ```bash |
| brew install python@3.11 |
| ``` |
| Verify: `python3.11 --version` |
|
|
| 3. **Install Git** |
| ```bash |
| 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 |
|
|
| ```bash |
| # 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 |
|
|
| ```bash |
| # Replace "yourname" with your actual name |
| git checkout -b feature/yourname-improvements |
| ``` |
|
|
| Verify you're on your branch: |
| ```bash |
| git branch |
| # Should show * feature/yourname-improvements |
| ``` |
|
|
| --- |
|
|
| ## 🐍 Set Up Virtual Environment |
|
|
| ### Windows |
| ```powershell |
| python -m venv venv |
| venv\Scripts\activate |
| pip install --upgrade pip |
| pip install -r requirements.txt |
| pip install python-dotenv |
| ``` |
|
|
| ### Mac |
| ```bash |
| 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://huggingface.co/proxy/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 |
| ```powershell |
| python ui.py |
| ``` |
| #### Mac |
| ```bash |
| python ui.py |
| ``` |
| |
| ### Terminal 2 — Test the API |
| #### Windows |
| ```powershell |
| Invoke-WebRequest -Uri http://localhost:7860/health -Method GET |
| ``` |
| #### Mac |
| ```bash |
| 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 |
| ```bash |
| # Make sure .env file has your HF_TOKEN |
| python inference.py |
| ``` |
|
|
| --- |
|
|
| ## 🐳 Test with Docker |
|
|
| ```bash |
| docker build -t ai-sprint-manager . |
| ``` |
|
|
| ### Windows |
| ```powershell |
| docker run -p 7860:7860 ai-sprint-manager |
| ``` |
| ### Mac |
| ```bash |
| 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: |
| ```bash |
| 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 |
| ```powershell |
| Invoke-WebRequest -Uri "https://YOUR_HF_USERNAME-ai-sprint-manager-yourname.hf.space/health" -Method GET |
| ``` |
| ### Mac |
| ```bash |
| curl https://YOUR_HF_USERNAME-ai-sprint-manager-yourname.hf.space/health |
| ``` |
|
|
| --- |
|
|
| ## 🔧 Run OpenEnv Validation |
|
|
| ```bash |
| 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 |
|
|
| ```bash |
| 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`. |
