datacamp-mcp-multiagent-demo

# Promotion Advisor — Multi-Agent System with LangGraph + MongoDB Atlas > AI-powered promotion packet preparation: define your target role, document your projects, generate an impact analysis, and discover similar professionals — all orchestrated with **LangGraph**, persisted in **MongoDB Atlas**, and wrapped in a **Gradio** UI. --- ## 🎯 What This Does A **practical AI workflow** that helps you prepare for career advancement: - **🎯 Target Role Builder** → Define your promotion goal (e.g., *Staff Engineer*, *Senior PM*, *VP of AI*) - **📁 Project Curator** → Extract structured project records with metrics from free text - **📊 Impact Analyzer** → Generate executive-ready reports with strengths, gaps, and recommendations - **👥 Mentor Finder** → Discover similar professionals on LinkedIn (via Tavily search) - **⬇️ Export** → Download a complete promotion packet in Markdown --- ## 🎬 See It In Action  **📺 Watch the full demo walkthrough:** [AI-Powered Promotion Advisor - Complete Demo (3 min)](https://youtu.be/mYr4xmX3lgA) <details> <summary>📸 More Screenshots</summary> ### Initial Interface  ### Complete Workflow  ---  ---  ### Generated Impact Report  ### Agent Execution Trace  </details> --- ## 🚀 Quick Start ### 1. Clone the repository ```bash git clone https://github.com/mikikob-mongodb/datacamp-mcp-multiagent-demo.git cd datacamp-mcp-multiagent-demo git checkout v1_webinar_version ``` ### 2. Set up environment variables ```bash cp env.template .env ``` Edit `.env` and add your API keys: ```env OPENAI_API_KEY=sk-your-key-here MONGODB_URI=mongodb+srv://your-connection-string TAVILY_API_KEY=tvly-your-key-here # Optional ``` **Get your API keys:** - **OpenAI**: https://platform.openai.com/api-keys ($5 minimum credit) - **MongoDB Atlas**: https://www.mongodb.com/cloud/atlas/register (free M0 cluster) - **Tavily** *(optional)*: https://tavily.com (1,000 free searches/month) ### 3. Install dependencies ```bash make setup ``` This will: - Kill any processes on port 7860 - Create a virtual environment - Install all required packages - Set up development tools (linters/formatters) ### 4. Run the application ```bash source .venv/bin/activate # Windows: .venv\Scripts\activate make run ``` Open your browser to: **http://localhost:7860** --- ## 📋 How It Works 1. **Start** → Chat interface asks: *"What role are you targeting?"* 2. **Define Role** → AI parses your goal and sets expectations (focus areas, responsibilities, success metrics) 3. **Add Projects** → Paste project descriptions; AI extracts context, actions, outcomes, and metrics 4. **Generate Report** → Get executive-ready impact analysis with: - Strengths backed by specific evidence - Gaps to address - Actionable recommendations - Industry salary data (if Tavily enabled) 5. **Find Mentors** *(optional)* → Discover LinkedIn profiles of professionals in similar roles 6. **Download** → Export complete promotion packet as Markdown --- ## 🛠️ Development Commands ### Available Make Commands ```bash make setup # Create venv and install all dependencies make run # Run the application (kills port first) make lint # Check code for issues make format # Auto-fix and format code make clean # Remove cache files make clean-all # Remove cache files AND venv make kill-ports # Kill process on port 7860 make help # Show all available commands ``` ### Full Reset Script For a complete fresh start (useful during development or debugging): ```bash ./reset.sh ``` **What `reset.sh` does:** 1. Checks if you're in a virtual environment and warns you 2. Deactivates the venv (within the script's context) 3. Runs `make clean-all` to remove all caches and the venv directory 4. Runs `make setup` to create a fresh environment and install dependencies 5. Provides clear instructions for activating the new environment **After running `reset.sh`, activate the new environment:** ```bash source .venv/bin/activate && make run ``` **Note:** The script cannot automatically activate the venv in your terminal (this is a fundamental shell limitation). Your terminal prompt may still show `(.venv)` after the reset, but the old environment has been removed and a fresh one created. Simply run the activation command above to use the new environment. --- ## 📁 Project Structure ``` promotion_tycoon/ ├── main.py # Application entry point ├── config.py # Environment configuration ├── storage.py # MongoDB operations & checkpointer ├── models.py # Pydantic data models ├── prompts.py # System prompts ├── tracing.py # Execution logging └── ui.py # Gradio interface ├── env.template # Environment variables template ├── Makefile # Build and run commands ├── reset.sh # Development reset script └── README.md # This file ``` --- ## 🔧 Configuration ### Environment Variables (.env) ```env # Required OPENAI_API_KEY=sk-... MONGODB_URI=mongodb+srv://... # Optional TAVILY_API_KEY=tvly-... # For industry research DATABASE_NAME=promotion_advisor # Default database name GRADIO_SERVER_PORT=7860 # Default port ``` ### MongoDB Atlas Setup 1. **Create a free M0 cluster** at https://www.mongodb.com/cloud/atlas 2. **Create a database user** with read/write permissions 3. **Get your connection string** (looks like `mongodb+srv://username:password@cluster.mongodb.net/`) 4. **Whitelist your IP** in Network Access settings 5. **Add to `.env` file** **Fallback behavior:** If MongoDB is unavailable, the app automatically falls back to in-memory storage with a warning message in the logs. --- ## 🎓 Key Concepts Demonstrated This project showcases several advanced patterns for building production-ready AI applications: - **Multi-Agent Orchestration** → LangGraph manages routing between specialized agents - **Interrupt/Resume Patterns** → Human-in-the-loop workflows with checkpoint/resume - **Structured Data Extraction** → Pydantic models ensure type safety and validation - **Persistent Memory** → MongoDB Atlas stores conversation state and checkpoints - **Industry Research Integration** → MCP (Model Context Protocol) with Tavily for real-time data - **Interactive UI** → Gradio provides rapid prototyping with production-ready interfaces - **Graceful Degradation** → App continues functioning even if external services fail --- ## 🐛 Troubleshooting ### Port Already in Use If you see "Cannot find empty port" error: ```bash make kill-ports make run ``` Or specify a different port in `.env`: ```env GRADIO_SERVER_PORT=7861 ``` ### MongoDB Connection Failed **Symptoms:** `Authentication failed` or `Connection timeout` **Solutions:** - Verify your connection string in `.env` is correct - Check database user has proper read/write permissions - Ensure your IP address is whitelisted in Atlas Network Access - Test connection string with MongoDB Compass **The app will automatically fall back to in-memory storage if MongoDB is unavailable.** ### Dependencies Not Installing Make sure you have Python 3.10+ installed: ```bash python3 --version ``` If you encounter dependency conflicts: ```bash ./reset.sh # Full clean reinstall ``` ### Tavily Search Not Working **Symptoms:** No industry research or salary data in reports **Solutions:** - Verify `TAVILY_API_KEY` is set correctly in `.env` - Check you haven't exceeded free tier limits (1,000 searches/month) - Monitor execution trace panel in UI for Tavily-specific errors **Note:** The app works without Tavily but won't include industry research in reports. ### Virtual Environment Issues If you see `(.venv)` in your prompt but commands fail: ```bash deactivate ./reset.sh source .venv/bin/activate make run ``` Or simply open a new terminal window: ```bash cd datacamp-mcp-multiagent-demo source .venv/bin/activate make run ``` --- ## 💡 Inspired By This project was inspired by Julia Evans' concept of **[Brag Documents](https://jvns.ca/blog/brag-documents/)** - a systematic approach to tracking your accomplishments for performance reviews and promotions. **The Problem Julia Identified:** > "There's this idea that, if you do great work at your job, people will (or should!) automatically recognize that work and reward you for it with promotions / increased pay. In practice, it's often more complicated than that." **Our Solution:** While Julia's brag document is a manual process, **Promotion Advisor automates the hard parts**: - ✅ **Structured extraction** → Turn free-form project descriptions into organized, metrics-backed records - ✅ **Gap analysis** → Compare your achievements against target role requirements - ✅ **Industry benchmarking** → Include salary data and real role expectations - ✅ **Mentor discovery** → Find people who've successfully made similar transitions - ✅ **Executive-ready output** → Generate polished reports that managers actually read **We're building on Julia's wisdom with AI tooling**, making it easier to maintain your professional narrative and advocate for yourself effectively. **Read Julia's original post:** [Get your work recognized: write a brag document](https://jvns.ca/blog/brag-documents/) --- ## 🎯 Future Enhancements **Planned features:** - **Vector & Hybrid Search** → MongoDB Atlas Vector Search for semantic project/mentor matching - **File Uploads** → Resume and job description parsing - **Embeddings & Reranking** → Voyage AI integration for improved search quality - **PDF Export** → Professional promotion packet documents - **Team Collaboration** → Multi-user review and comment features - **Advanced Mentor Filtering** → Search by company, location, seniority level - **Monitoring & Observability** → LLM cost tracking, latency metrics, quality dashboards - **Model Flexibility** → Support for additional LLM providers and local models --- ## 📺 Demo & Tutorial This project was created for the **DataCamp Multi-Agent Systems Webinar**. **Key topics covered:** - Building multi-agent systems with LangGraph - Persistent memory with MongoDB Atlas - Human-in-the-loop AI workflows - MCP integration for real-time data enrichment - Production deployment patterns --- ## 🤝 Contributing Issues and pull requests are welcome! For major changes, please open an issue first to discuss what you'd like to change. **Development workflow:** 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Make your changes 4. Run linters: `make format && make lint` 5. Commit your changes (`git commit -m 'Add amazing feature'`) 6. Push to the branch (`git push origin feature/amazing-feature`) 7. Open a Pull Request --- ## 📄 License If this demo sparked ideas, **check out the Gen-AI Showcase** for more hands-on examples of **agentic patterns**, **memory architectures**, and **MongoDB-backed AI apps**. 👉 **[Gen-AI Showcase]([https://example.com/showcase](https://github.com/mongodb-developer/GenAI-Showcase))** --- ## 🌟 Explore More ### 🔧 MongoDB AI Resources **Interested in building production-grade AI applications with MongoDB?** 👉 **[MongoDB GenAI Showcase](https://github.com/mongodb-developer/GenAI-Showcase)** - Collection of production-ready AI application patterns and examples 👉 **[LangChain + MongoDB Integration](https://www.mongodb.com/docs/atlas/ai-integrations/langchain/)** - Official documentation for using MongoDB Atlas with LangChain 👉 **[MongoDB AI Use Cases](https://www.mongodb.com/resources/use-cases/artificial-intelligence)** - Real-world AI applications built on MongoDB ### 📚 Core Technologies **LangGraph & Multi-Agent Systems:** - **[LangGraph Checkpoint MongoDB](https://pypi.org/project/langgraph-checkpoint-mongodb/)** - Persistent state management for LangGraph workflows - **[LangGraph Supervisor Pattern](https://docs.langchain.com/oss/python/langchain/supervisor)** - Router-based multi-agent orchestration (used in this project) - **[LangGraph Interrupts](https://docs.langchain.com/oss/python/langgraph/interrupts)** - Pause/resume workflows for human review (powers our interrupt/resume pattern) - **[Human-in-the-Loop Workflows](https://docs.langchain.com/oss/python/langchain/human-in-the-loop)** - Interactive AI systems with user approval gates - **[Building Multi-Agent Systems with LangGraph](https://levelup.gitconnected.com/building-a-multi-agent-ai-system-with-langgraph-and-langsmith-6cb70487cd81)** - Tutorial on agent coordination and monitoring **Model Context Protocol (MCP):** - **[MCP Documentation](https://modelcontextprotocol.io/)** - Official MCP specification and guides - **[LangChain MCP Adapters](https://changelog.langchain.com/announcements/mcp-adapters-for-langchain-and-langgraph)** - Integrate external tools and data sources (Tavily, GitHub, etc.) - **[MCP Adapters GitHub](https://github.com/langchain-ai/langchain-mcp-adapters)** - Implementation details and examples **UI & Deployment:** - **[Gradio Documentation](https://www.gradio.app/docs/)** - Rapid ML/AI UI prototyping - **[Agentic RAG with LangGraph](https://docs.langchain.com/oss/python/langgraph/agentic-rag)** - Advanced retrieval patterns ### 📖 Tutorials & Inspiration **MongoDB + MCP Integration:** - **[Building AI Agents with MongoDB MCP](https://medium.com/@SojeongBaek/building-ai-agent-with-mongodb-mcp-1339516643c8)** - Step-by-step agent construction - **[MongoDB Chat Agent with MCP](https://blog.gopenai.com/langgraph-tutorial-4-build-a-mongodb-chat-agent-with-mcp-88e27602b4b9)** - LangGraph tutorial with persistent memory **Search & Research:** - **[LinkedIn Profile Search with Tavily](https://docs.tavily.com/examples/quick-tutorials/linkedin-profile-search)** - Finding professionals by role (used in Mentor Finder agent) **Career Development:** - **[Brag Documents](https://jvns.ca/blog/brag-documents/)** by Julia Evans - The manual process this tool automates ### 🎓 Learn More **Want to dive deeper into multi-agent systems?** - Start with the [LangGraph Supervisor Pattern](https://docs.langchain.com/oss/python/langchain/supervisor) to understand routing - Learn about [interrupts](https://docs.langchain.com/oss/python/langgraph/interrupts) and [human-in-the-loop](https://docs.langchain.com/oss/python/langchain/human-in-the-loop) patterns used in this project - Explore [MongoDB Atlas Vector Search](https://www.mongodb.com/products/platform/atlas-vector-search) for semantic search - Check out the [GenAI Showcase](https://github.com/mongodb-developer/GenAI-Showcase) for more production patterns **Questions or want to contribute?** - Open an [issue on GitHub](https://github.com/mikikob-mongodb/datacamp-mcp-multiagent-demo/issues) - Join the [MongoDB Community Forums](https://www.mongodb.com/community/forums/) - Connect on [LinkedIn](https://www.linkedin.com/in/mikikobazeley/)