{"id":29654535,"url":"https://github.com/dpguthrie/langgraph-supervisor","last_synced_at":"2025-08-08T16:21:21.396Z","repository":{"id":305187780,"uuid":"1018066949","full_name":"dpguthrie/langgraph-supervisor","owner":"dpguthrie","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-18T16:20:44.000Z","size":10,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-18T20:45:11.305Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dpguthrie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-11T14:50:50.000Z","updated_at":"2025-07-18T16:20:48.000Z","dependencies_parsed_at":"2025-07-18T20:45:19.041Z","dependency_job_id":"85e7e61e-1770-4229-928c-b7bd2e9cf6ca","html_url":"https://github.com/dpguthrie/langgraph-supervisor","commit_stats":null,"previous_names":["dpguthrie/langgraph-supervisor"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dpguthrie/langgraph-supervisor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpguthrie%2Flanggraph-supervisor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpguthrie%2Flanggraph-supervisor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpguthrie%2Flanggraph-supervisor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpguthrie%2Flanggraph-supervisor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dpguthrie","download_url":"https://codeload.github.com/dpguthrie/langgraph-supervisor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpguthrie%2Flanggraph-supervisor/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266448544,"owners_count":23930241,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-22T07:34:53.588Z","updated_at":"2025-07-22T07:34:54.153Z","avatar_url":"https://github.com/dpguthrie.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LangGraph Supervisor\n\nA multi-agent AI system built with LangGraph that intelligently routes user queries between specialized agents for optimal task handling.\n\n## 🎯 Overview\n\nThis project implements a **supervisor pattern** using LangGraph to manage two specialized AI agents:\n\n- **🧮 Math Agent**: Handles mathematical calculations, arithmetic, and numerical problems\n- **🔍 Research Agent**: Manages factual queries, web searches, and information retrieval\n\nThe supervisor intelligently routes user queries to the appropriate agent based on the content and context of the request.\n\n## ✨ Features\n\n- **Intelligent Routing**: Automatic task delegation to specialized agents\n- **Rich UI**: Beautiful terminal interface with colors and progress indicators\n- **Comprehensive Evaluation**: LLM-as-a-Judge evaluation system using Braintrust\n- **Real-time Processing**: Streaming responses with live updates\n- **Error Handling**: Robust error management and fallback mechanisms\n\n## 🛠️ Technology Stack\n\n- **[LangGraph](https://langchain-ai.github.io/langgraph/)**: Multi-agent workflow orchestration\n- **[LangChain](https://langchain.com/)**: LLM framework and integrations\n- **[Braintrust](https://braintrust.dev/)**: AI evaluation and observability\n- **[Rich](https://rich.readthedocs.io/)**: Terminal UI enhancements\n- **[Tavily](https://tavily.com/)**: Web search API for research tasks\n\n## 📋 Prerequisites\n\n- Python 3.9+\n- OpenAI API key\n- Tavily API key  \n- Braintrust API key\n\n## 🚀 Quick Start\n\n### 1. Clone the Repository\n\n```bash\ngit clone \u003crepository-url\u003e\ncd langgraph-supervisor\n```\n\n### 2. Install Dependencies\n\nUsing uv (recommended):\n```bash\nuv pip install -r requirements.txt\n```\n\nOr using pip:\n```bash\npip install -r requirements.txt\n```\n\n### 3. Environment Setup\n\nCreate a `.env` file in the project root:\n\n```env\nOPENAI_API_KEY=your_openai_api_key_here\nTAVILY_API_KEY=your_tavily_api_key_here\nBRAINTRUST_API_KEY=your_braintrust_api_key_here\n```\n\n### 4. Run the Application\n\n```bash\npython src/app.py\n```\n\n## 💬 Usage Examples\n\n### Math Queries\n```\nYou: What is 15 + 27?\n🤖: 42\n\nYou: Calculate the square root of 169\n🤖: 13\n```\n\n### Research Queries\n```\nYou: Who is the mayor of Denver?\n🤖: The current mayor of Denver is Mike Johnston.\n\nYou: What is the capital of Japan?\n🤖: The capital of Japan is Tokyo.\n```\n\n### Interactive Commands\n- Type your question and press Enter\n- Use `quit`, `exit`, or `q` to exit the application\n- Ctrl+C for emergency exit\n\n## 📊 Evaluation System\n\nThis project includes a comprehensive evaluation framework using **LLM-as-a-Judge** methodology.\n\n### Running Evaluations\n\n```bash\n# Run the evaluation suite\nbraintrust eval evals/\n```\n\n### Evaluation Metrics\n\n- **🎯 Routing Accuracy**: Measures correct agent selection\n- **📝 Response Quality**: Assesses answer accuracy and completeness\n- **⚡ Performance**: Tracks token usage and response times\n\n### View Results\n\nEvaluation results are automatically uploaded to your Braintrust dashboard where you can:\n- Track performance over time\n- Compare different model versions\n- Analyze detailed evaluation traces\n- Export results for further analysis\n\n## 📁 Project Structure\n\n```\nlanggraph-supervisor/\n├── src/                          # Main application code\n│   ├── app.py                   # Supervisor system and main entry point\n│   ├── helpers.py               # Utility functions for UI\n│   └── __init__.py\n├── evals/                       # Evaluation framework\n│   └── eval_simple.py          # LLM-as-a-Judge evaluations\n├── requirements.txt             # Python dependencies\n├── .env.example                # Environment variables template\n├── .gitignore\n└── README.md\n```\n\n## 🔧 Configuration\n\n### Agent Customization\n\nModify agent behavior in `src/app.py`:\n\n```python\n# Customize math agent\nmath_agent = create_react_agent(\n    model=\"openai:gpt-4.1\",\n    tools=[add, multiply, divide],\n    prompt=\"Your custom math agent prompt...\",\n    name=\"math_agent\",\n)\n\n# Customize research agent  \nresearch_agent = create_react_agent(\n    model=\"openai:gpt-4.1\",\n    tools=[web_search],\n    prompt=\"Your custom research agent prompt...\",\n    name=\"research_agent\",\n)\n```\n\n### Supervisor Behavior\n\nAdjust supervisor routing logic:\n\n```python\nsupervisor = create_supervisor(\n    model=init_chat_model(\"openai:gpt-4.1\"),\n    agents=[research_agent, math_agent],\n    prompt=\"Your custom supervisor prompt...\",\n    add_handoff_back_messages=True,\n    output_mode=\"full_history\",\n).compile()\n```\n\n## 🧪 Development\n\n### Adding New Agents\n\n1. Create agent in `src/app.py`:\n```python\nnew_agent = create_react_agent(\n    model=\"openai:gpt-4.1\",\n    tools=[your_tools],\n    prompt=\"Agent prompt...\",\n    name=\"new_agent\",\n)\n```\n\n2. Add to supervisor agents list:\n```python\nagents=[research_agent, math_agent, new_agent]\n```\n\n3. Update supervisor prompt to include routing logic\n\n### Adding Evaluation Tests\n\nExtend the evaluation dataset in `evals/eval_simple.py`:\n\n```python\n{\n    \"input\": {\n        \"messages\": [\n            {\n                \"content\": \"Your test question\",\n                \"type\": \"human\",\n                # ... other fields\n            }\n        ]\n    }\n}\n```\n\n## 📈 Performance Monitoring\n\nThe system automatically tracks:\n\n- **Token Usage**: Input/output tokens per conversation\n- **Response Times**: End-to-end latency metrics  \n- **Agent Selection**: Routing decision accuracy\n- **Error Rates**: Failed requests and error types\n\nView metrics in your Braintrust dashboard for continuous monitoring and optimization.\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Development Guidelines\n\n- Add tests for new functionality in `evals/`\n- Update documentation for API changes\n- Follow existing code style and patterns\n- Ensure all evaluations pass before submitting\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🆘 Support\n\n- **Issues**: Report bugs and request features via [GitHub Issues](../../issues)\n- **Discussions**: Join conversations in [GitHub Discussions](../../discussions)\n- **Documentation**: Full docs available at [Project Wiki](../../wiki)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdpguthrie%2Flanggraph-supervisor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdpguthrie%2Flanggraph-supervisor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdpguthrie%2Flanggraph-supervisor/lists"}