| # 🚀 GitHub Models Setup (Recommended) | |
| ## Why Use GitHub Models? | |
| - **Free tier**: No credit card required | |
| - **Excellent tool calling**: More reliable than small local models | |
| - **Stable cloud endpoint**: No disconnects | |
| - **Fast responses**: 2-5 seconds per query | |
| - **Easy setup**: Just need a GitHub personal access token | |
| ## Quick Setup | |
| ### 1. Get a GitHub Personal Access Token | |
| - Go to [GitHub tokens](https://github.com/settings/tokens) | |
| - Click "Generate new token (classic)" | |
| - Name it (e.g., `Multi-Agent Backend Testing`) | |
| - Select scopes: `repo` (if needed), `read:org` (optional) | |
| - Click "Generate token" and copy it | |
| ### 2. Configure Environment | |
| ```powershell | |
| notepad .env | |
| # Add your token: | |
| GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| ``` | |
| ### 3. Test Your Setup | |
| ```powershell | |
| uv run test_agents.py | |
| # Should see: Using GitHub Models: openai/gpt-5-mini via https://models.github.ai | |
| ``` | |
| ## LLM Priority Order | |
| 1. GitHub Models (if `GITHUB_TOKEN` set) | |
| 2. OpenAI (if `OPENAI_API_KEY` set) | |
| 3. Google GenAI (if `GOOGLE_API_KEY` set) | |
| 4. Ollama (local fallback) | |
| ## Troubleshooting | |
| - **Initialization failed**: Check token validity and format (`ghp_` or `github_pat_`, 40+ chars) | |
| - **Rate limit exceeded**: Wait 1 minute or use another provider | |
| - **Model not available**: List available models: | |
| ```powershell | |
| curl -H "Authorization: Bearer YOUR_TOKEN" -H "Accept: application/vnd.github+json" https://models.github.ai/models | |
| ``` | |
| ## Alternative Models | |
| If `gpt-5-mini` has issues, try: | |
| - Claude: `anthropic/claude-3-5-sonnet` | |
| - Llama: `meta-llama/Meta-Llama-3.1-8B-Instruct` | |
| - GPT-4: `openai/gpt-4` | |
| Edit `.env` or [agents.py](agents.py) to change the model. | |
| ## Comparison: GitHub Models vs Ollama | |
| | Feature | GitHub Models | Ollama (qwen3:0.6b) | | |
| |--------------- |--------------|---------------------| | |
| | Setup | 2 min | 10+ min | | |
| | Cost | Free | Free (local) | | |
| | Speed | 2-5 sec | 5-15 sec | | |
| | Reliability | 98% | 50% (disconnects) | | |
| | Tool Calling | Excellent | Poor | | |
| | RAM Usage | 0 MB | 1-2 GB | | |
| | GPU Needed | No | Optional | | |
| | Quality | High | Low | | |
| ## Production Deployment | |
| - Use paid GitHub Models tier for higher limits | |
| - OpenAI API for maximum reliability | |
| - Azure OpenAI for enterprise features | |
| Automatic fallback supported in codebase | |
| ## Reverting to Ollama | |
| Comment out `GITHUB_TOKEN` in `.env` and set: | |
| ```powershell | |
| OLLAMA_BASE_URL=http://localhost:11434 | |
| OLLAMA_MODEL=llama3.2 | |
| ``` | |
| ## Summary | |
| GitHub Models is the **recommended default** for this project: | |
| - Free, easy, production-quality responses | |
| - No local resource requirements | |
| - Excellent tool calling for agentic workflows | |
| [Get started in 2 minutes](https://github.com/settings/tokens) | |
| 🎉 Happy testing! | |