{"id":28863226,"url":"https://github.com/kirtijha/langgraph-interrupt-workflow-template","last_synced_at":"2026-04-07T21:31:59.544Z","repository":{"id":298860326,"uuid":"1001347024","full_name":"KirtiJha/langgraph-interrupt-workflow-template","owner":"KirtiJha","description":"⚡ Production-ready LangGraph interrupt template with modern web interface | Human-in-the-loop AI workflows | FastAPI backend + Next.js frontend","archived":false,"fork":false,"pushed_at":"2025-06-13T08:55:30.000Z","size":70,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-13T09:41:03.765Z","etag":null,"topics":["ai-workflows","chatbot-framework","conversational-ai","fastapi","human-in-the-loop","ibm-watsonx","interactive-ai","interrupts","langchain","langgraph","llm","nextjs","python","react","state-management","typescript","workflow-automation"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/KirtiJha.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-13T08:18:02.000Z","updated_at":"2025-06-13T08:55:33.000Z","dependencies_parsed_at":"2025-06-13T09:51:21.751Z","dependency_job_id":null,"html_url":"https://github.com/KirtiJha/langgraph-interrupt-workflow-template","commit_stats":null,"previous_names":["kirtijha/langgraph-interrupt-workflow-template"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/KirtiJha/langgraph-interrupt-workflow-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KirtiJha%2Flanggraph-interrupt-workflow-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KirtiJha%2Flanggraph-interrupt-workflow-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KirtiJha%2Flanggraph-interrupt-workflow-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KirtiJha%2Flanggraph-interrupt-workflow-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KirtiJha","download_url":"https://codeload.github.com/KirtiJha/langgraph-interrupt-workflow-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KirtiJha%2Flanggraph-interrupt-workflow-template/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260898762,"owners_count":23079263,"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","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":["ai-workflows","chatbot-framework","conversational-ai","fastapi","human-in-the-loop","ibm-watsonx","interactive-ai","interrupts","langchain","langgraph","llm","nextjs","python","react","state-management","typescript","workflow-automation"],"created_at":"2025-06-20T07:02:16.488Z","updated_at":"2026-04-07T21:31:59.527Z","avatar_url":"https://github.com/KirtiJha.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LangGraph Interrupt Workflow Template\n\n[![LangGraph](https://img.shields.io/badge/LangGraph-Human--in--the--Loop-blue)](https://langchain-ai.github.io/langgraph/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-009688?logo=fastapi\u0026logoColor=white)](https://fastapi.tiangolo.com/)\n[![Next.js](https://img.shields.io/badge/Next.js-000000?logo=nextdotjs\u0026logoColor=white)](https://nextjs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![Python](https://img.shields.io/badge/Python-3776AB?logo=python\u0026logoColor=white)](https://www.python.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n⚡ **Production-ready LangGraph interrupt template** with modern web interface for building human-in-the-loop AI workflows. This starter kit provides everything you need to create interactive AI applications that can pause execution, request user input, and resume processing based on user decisions.\n\n## 🎯 Quick Start\n\nThis template includes a **research assistant example** to demonstrate the interrupt patterns. You can easily replace this with your own use case while keeping the robust interrupt infrastructure.\n\n1. **Clone the template**\n2. **Set up your environment** (Watson API keys or swap to your preferred LLM)\n3. **Run the example** to see interrupts in action\n4. **Customize** the workflow for your specific needs\n\nPerfect for building: Content review systems, data processing pipelines, quality control workflows, configuration wizards, and any AI application requiring human oversight.\n\n## 🚀 Features\n\n### 🎯 **Template/Starter Kit**\n- **Ready-to-use**: Clone and customize for your specific use case\n- **Production-ready**: Includes testing, Docker, and deployment configurations\n- **Well-documented**: Comprehensive guides and examples\n- **Modular design**: Easy to extend and modify\n\n### Core LangGraph Interrupt Capabilities\n- **Dynamic Interrupts**: Pause graph execution at any node for user input\n- **State Preservation**: Maintain conversation and workflow state across interrupts\n- **Resume Functionality**: Continue execution with user-provided choices\n- **Multiple Interrupt Types**: Support different types of user interactions\n- **Flexible Options**: Both predefined choices and free-text input support\n\n### Technical Implementation\n- **Backend**: FastAPI with LangGraph state management\n- **Frontend**: Next.js with real-time UI updates\n- **LLM Integration**: IBM Watson ChatWatsonx (easily swappable)\n- **State Management**: Persistent conversation threading\n- **Interactive UI**: Modern glassmorphism design with animations\n\n## 🏗️ Architecture\n\n```\n┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐\n│   Frontend      │    │   Backend       │    │   LangGraph     │\n│   (Next.js)     │◄──►│   (FastAPI)     │◄──►│   Workflow      │\n│                 │    │                 │    │                 │\n│ • Chat Interface│    │ • State Mgmt    │    │ • Node Execution│\n│ • Interrupt UI  │    │ • API Endpoints │    │ • Interrupts    │\n│ • Progress Bar  │    │ • Threading     │    │ • State Flow    │\n└─────────────────┘    └─────────────────┘    └─────────────────┘\n```\n\n## 📋 Prerequisites\n\n- **Python 3.11+** (for backend)\n- **Node.js 18+** (for frontend)\n- **IBM Watson Account** (or modify for other LLM providers)\n\n## 🛠️ Installation\n\n### 1. Clone the Repository\n```bash\ngit clone https://github.com/yourusername/langgraph-interrupt-workflow-template.git\ncd langgraph-interrupt-workflow-template\n```\n\n### 2. Backend Setup\n```bash\ncd backend\n\n# Create virtual environment\npython -m venv langgraph-interrupt\nsource langgraph-interrupt/bin/activate  # On Windows: langgraph-interrupt\\Scripts\\activate\n\n# Upgrade pip\npip install --upgrade pip\n\n# Install dependencies\npip install -r requirements.txt\n\n# For development (optional)\npip install -r requirements-dev.txt\n\n# Create environment file\ncp .env.example .env\n# Edit .env with your credentials (see Configuration section)\n```\n\n### 3. Frontend Setup\n```bash\ncd frontend\n\n# Install dependencies\nnpm install\n\n# Or with yarn\nyarn install\n```\n\n## ⚙️ Configuration\n\nCreate a `.env` file in the `backend/` directory:\n\n```env\n# IBM Watson Configuration\nWATSONX_URL=https://us-south.ml.cloud.ibm.com\nWATSONX_API_KEY=your_watson_api_key_here\nWATSONX_PROJECT_ID=your_project_id_here\n\n# LangChain Tracing (Optional)\nLANGCHAIN_API_KEY=your_langchain_api_key\nLANGCHAIN_TRACING_V2=true\nLANGCHAIN_ENDPOINT=https://api.smith.langchain.com\nLANGCHAIN_PROJECT=your_project_name\n```\n\n### Environment Variables Explained\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `WATSONX_URL` | Watson ML service endpoint | Yes |\n| `WATSONX_API_KEY` | Your IBM Watson API key | Yes |\n| `WATSONX_PROJECT_ID` | Watson project identifier | Yes |\n| `LANGCHAIN_*` | LangChain tracing config | No |\n\n## 🚀 Running the Application\n\n### Option 1: Local Development\n\n#### Start Backend Server\n```bash\ncd backend\nsource langgraph-interrupt/bin/activate\npython main.py\n# Server runs on http://localhost:8000\n```\n\n#### Start Frontend Server\n```bash\ncd frontend\nnpm run dev\n# Frontend runs on http://localhost:3000\n```\n\n### Option 2: Docker (Recommended for Production)\n\n```bash\n# Copy environment file\ncp backend/.env.example backend/.env\n# Edit backend/.env with your credentials\n\n# Build and run with Docker Compose\ndocker-compose up --build\n\n# Access the application at http://localhost:8000\n```\n\n## 📖 Understanding LangGraph Interrupts\n\n### How Interrupts Work\n\n1. **Node Execution**: Graph executes nodes sequentially\n2. **Interrupt Trigger**: Node calls `interrupt()` function\n3. **State Pause**: Execution stops, state is preserved\n4. **User Interaction**: Frontend displays options to user\n5. **Resume**: User choice sent back via `Command(resume=choice)`\n6. **Continue**: Graph resumes with user input\n\n### Code Example\n\n```python\nfrom langgraph.types import interrupt\n\ndef interactive_node(state: State) -\u003e Dict[str, Any]:\n    # Process current state\n    analysis = analyze_data(state[\"input\"])\n    \n    # Interrupt for user decision\n    user_choice = interrupt({\n        \"message\": \"How should I proceed?\",\n        \"options\": [\"option1\", \"option2\", \"option3\"],\n        \"context\": analysis\n    })\n    \n    # Continue based on user choice\n    return {\n        \"user_decision\": user_choice,\n        \"next_step\": determine_next_step(user_choice)\n    }\n```\n\n### API Endpoints\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/start` | POST | Initialize new conversation thread |\n| `/resume` | POST | Resume interrupted workflow |\n| `/get_state/{thread_id}` | GET | Get current workflow state |\n\n## 🎨 Customization\n\n### Adding New Interrupt Types\n\n1. **Create Node Function**:\n```python\ndef custom_interrupt_node(state: YourState) -\u003e Dict[str, Any]:\n    result = interrupt(\"Your custom message here\")\n    return {\"custom_field\": result}\n```\n\n2. **Add to Graph**:\n```python\ngraph_builder.add_node(\"custom_node\", custom_interrupt_node)\ngraph_builder.add_edge(\"previous_node\", \"custom_node\")\n```\n\n3. **Update Frontend** (optional):\n```typescript\n// Handle custom interrupt types in your UI\nif (interruptType === \"custom\") {\n    // Custom UI logic\n}\n```\n\n### Swapping LLM Providers\n\nReplace the Watson LLM in `backend/graph.py`:\n\n```python\n# Instead of ChatWatsonx\nfrom langchain_openai import ChatOpenAI\n# or\nfrom langchain_anthropic import ChatAnthropic\n\ndef get_llm():\n    return ChatOpenAI(model=\"gpt-4\")  # or your preferred model\n```\n\n## 🧪 Testing\n\n### Backend Tests\n```bash\ncd backend\nsource langgraph-interrupt/bin/activate\npython -m pytest test_main.py -v\n```\n\n### Frontend Tests (Future)\n```bash\ncd frontend\nnpm test\n```\n\n### End-to-End Testing\n1. Start both backend and frontend\n2. Navigate to http://localhost:3000\n3. Test the complete interrupt flow:\n   - Start a conversation\n   - Verify interrupt appears\n   - Select options and resume\n   - Check final response\n\n## 🧪 Example Use Cases\n\nThis interrupt framework can be adapted for various scenarios:\n\n- **Content Review**: Pause for human approval before publishing\n- **Data Processing**: User selection of processing methods\n- **Workflow Routing**: Dynamic path selection based on user input\n- **Quality Control**: Human verification at critical steps\n- **Configuration**: Runtime parameter adjustment\n- **Error Handling**: User decision on error recovery\n\n## 📁 Project Structure\n\n```\nlanggraph-interrupt-workflow-template/\n├── backend/\n│   ├── main.py              # FastAPI application\n│   ├── graph.py             # LangGraph workflow definition\n│   ├── requirements.txt     # Python dependencies\n│   ├── requirements-dev.txt # Development dependencies\n│   ├── test_main.py         # Basic tests\n│   ├── .env.example         # Environment template\n│   └── .env                 # Environment variables (create from example)\n├── frontend/\n│   ├── app/\n│   │   ├── page.tsx         # Main chat interface\n│   │   ├── layout.tsx       # App layout\n│   │   └── globals.css      # Global styles\n│   ├── package.json         # Node.js dependencies\n│   └── tailwind.config.js   # Tailwind configuration\n├── .github/\n│   └── ISSUE_TEMPLATE/      # GitHub issue templates\n│       ├── bug_report.md\n│       └── feature_request.md\n├── .gitignore              # Git ignore rules\n├── CHANGELOG.md            # Version history\n├── CONTRIBUTING.md         # Contribution guidelines\n├── Dockerfile              # Docker configuration\n├── docker-compose.yml      # Docker Compose setup\n├── LICENSE                 # MIT License\n├── README.md               # This file\n└── SECURITY.md             # Security policy\n```\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## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🆘 Troubleshooting\n\n### Common Issues\n\n**Backend Issues:**\n- **Import errors**: Ensure virtual environment is activated\n- **Watson authentication**: Verify API keys in `.env`\n- **Port conflicts**: Change port in `main.py` if needed\n\n**Frontend Issues:**\n- **Build errors**: Clear `.next` folder and rebuild\n- **API connection**: Verify backend is running on correct port\n- **Styling issues**: Check Tailwind CSS configuration\n\n**LangGraph Issues:**\n- **State persistence**: Ensure checkpointer is properly configured\n- **Interrupt not working**: Verify `interrupt()` function usage\n- **Threading errors**: Check thread_id consistency\n\n### Debug Mode\n\nEnable debug logging in `backend/main.py`:\n\n```python\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n```\n\n## 🔗 Resources\n\n- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/)\n- [FastAPI Documentation](https://fastapi.tiangolo.com/)\n- [Next.js Documentation](https://nextjs.org/docs)\n- [IBM Watson Documentation](https://cloud.ibm.com/docs/watson)\n\n## 💡 Next Steps\n\n### 🎨 **Customization Ideas**\n- [ ] Add more interrupt types (file upload, drawing, etc.)\n- [ ] Integrate different LLM providers (OpenAI, Anthropic, etc.)\n- [ ] Implement webhook support for external interrupts\n- [ ] Add workflow visualization components\n- [ ] Create interrupt analytics and monitoring\n- [ ] Build domain-specific interrupt patterns\n\n### 🚀 **Template Usage**\n- [ ] Replace the research assistant example with your use case\n- [ ] Customize the interrupt types for your domain\n- [ ] Update the UI to match your brand/requirements\n- [ ] Add authentication/authorization if needed\n- [ ] Deploy to your preferred cloud platform\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkirtijha%2Flanggraph-interrupt-workflow-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkirtijha%2Flanggraph-interrupt-workflow-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkirtijha%2Flanggraph-interrupt-workflow-template/lists"}