{"id":30226944,"url":"https://github.com/karhal/openwebui-flowise-pipe","last_synced_at":"2026-07-16T13:33:18.563Z","repository":{"id":308514948,"uuid":"1033084013","full_name":"Karhal/openwebui-flowise-pipe","owner":"Karhal","description":"A comprehensive OpenWebUI pipe that provides seamless integration with Flowise AI workflows, featuring dynamic model loading, real-time streaming, and rich UI feedback.","archived":false,"fork":false,"pushed_at":"2025-08-14T09:38:46.000Z","size":14,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-24T12:04:42.457Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Karhal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-08-06T09:19:14.000Z","updated_at":"2025-08-14T09:38:50.000Z","dependencies_parsed_at":"2025-08-06T11:31:31.969Z","dependency_job_id":"0e1cce51-5c0a-4d85-b1eb-17ad1f95fb2c","html_url":"https://github.com/Karhal/openwebui-flowise-pipe","commit_stats":null,"previous_names":["karhal/openwebui-flowise-pipe"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Karhal/openwebui-flowise-pipe","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Karhal%2Fopenwebui-flowise-pipe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Karhal%2Fopenwebui-flowise-pipe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Karhal%2Fopenwebui-flowise-pipe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Karhal%2Fopenwebui-flowise-pipe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Karhal","download_url":"https://codeload.github.com/Karhal/openwebui-flowise-pipe/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Karhal%2Fopenwebui-flowise-pipe/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35546266,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-16T02:00:06.687Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","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-08-14T17:15:23.757Z","updated_at":"2026-07-16T13:33:18.558Z","avatar_url":"https://github.com/Karhal.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flowise Integration for OpenWebUI\n\nAn OpenWebUI pipe that provides seamless integration with Flowise AI workflows, featuring dynamic model loading, real-time streaming, and UI feedback.\n\n## ✨ Features\n\n- **Dynamic Model Discovery**: Automatically loads and displays all available Flowise chatflows\n- **Streaming Support**: Real-time response streaming with proper token handling\n- **Rich Status Indicators**: Visual feedback with emojis and progress updates\n- **Robust Error Handling**: Comprehensive error management with helpful messages\n- **Debug Mode**: Detailed logging for troubleshooting and development\n- **Flexible Response Handling**: Supports multiple Flowise response formats\n- **Session Management**: Maintains conversation context across messages\n- **Unicode Support**: Proper handling of international characters and emojis\n - **History Forwarding**: Optionally forwards prior messages to Flowise via `history`\n - **Override Merging**: Merges user `overrideConfig` while preserving `sessionId`\n - **File Uploads**: Forward files and data URLs via Flowise `uploads` API\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- OpenWebUI instance\n- Flowise AI instance running and accessible\n- Flowise API key (if authentication is enabled)\n\n### Installation\n\n1. **Download the script**:\n   \n   **Option A - Clone the repository:**\n   ```bash\n   git clone git@github.com:Karhal/openwebui-flowise-pipe.git\n   cd openwebui-flowise-pipe\n   ```\n   \n   **Option B - Download directly (if public):**\n   ```bash\n   wget https://raw.githubusercontent.com/Karhal/openwebui-flowise-pipe/main/flowise.py\n   ```\n   \n   **Option C - Download and save manually:**\n   - Go to https://github.com/Karhal/openwebui-flowise-pipe\n   - Click on `flowise.py` \n   - Click \"Raw\" button\n   - Save the file locally\n\n2. **Set environment variables**:\n   ```bash\n   export FLOWISE_API_URL=\"http://your-flowise-instance:3001\"\n   export FLOWISE_API_KEY=\"your-api-key-here\"  # Optional if no auth\n   ```\n\n3. **Install in OpenWebUI**:\n   - Go to Settings → Pipelines\n   - Click \"Add Pipeline\"\n   - Upload `flowise.py`\n   - Configure the pipeline settings\n\n### Configuration\n\nThe pipe can be configured through environment variables or the OpenWebUI interface:\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `FLOWISE_API_URL` | Flowise instance URL | `http://localhost:3001` | Yes |\n| `FLOWISE_API_KEY` | Flowise API key | `\"\"` | No* |\n| `enable_status_indicator` | Show status updates | `true` | No |\n| `emit_interval` | Status update frequency (seconds) | `1.0` | No |\n| `timeout` | Request timeout (seconds) | `600` | Yes, via `FLOWISE_TIMEOUT` |\n| `connect_timeout` | TCP connect timeout (seconds) | `15` | Yes, via `FLOWISE_CONNECT_TIMEOUT` |\n| `read_timeout` | Read timeout for non-streaming requests (seconds) | `600` | Yes, via `FLOWISE_READ_TIMEOUT` |\n| `read_timeout_stream` | Read timeout for streaming (SSE) requests (seconds) | `1800` | Yes, via `FLOWISE_READ_TIMEOUT_STREAM` |\n| `debug_mode` | Enable debug logging | `false` | No |\n| `history` | Forward prior messages (role/content) | auto | No |\n| `FLOWISE_ALLOW_REMOTE_FILE_URLS` | Allow http(s) URLs in uploads | `0` | No |\n| `FLOWISE_DEFAULT_UPLOAD_TYPE` | Default upload type | `file:full` | No |\n\n*Required if your Flowise instance has authentication enabled.\n\n## 🎯 Usage\n\n### Basic Usage\n\n1. **Select a Flowise Model**: After installation, available Flowise chatflows will appear in your model selector with descriptive emojis:\n   - 🤖 Agent-based flows\n   - 💬 Chat flows\n   - 🔄 Other workflow types\n\n2. **Start Chatting**: Send messages normally through OpenWebUI. The pipe will:\n   - Show real-time status updates\n   - Stream responses as they're generated\n   - Maintain conversation context\n\n### Advanced Features\n\n#### Debug Mode\n\nEnable debug mode to troubleshoot issues:\n\n```python\n# In the pipe configuration or environment\ndebug_mode = True\n```\n\nThis will log detailed information about:\n- Request/response data\n- Flowise API communication\n- Streaming data parsing\n- Error details\n\n#### Session Management\n\nThe pipe automatically manages conversation sessions using OpenWebUI's chat ID, ensuring context is maintained across the conversation.\n\n#### Custom Response Handling\n\nThe pipe supports multiple Flowise response formats:\n- `text` field (standard)\n- `message` field\n- `content` field\n- `response` field\n- Raw text responses\n- Streaming token events\n - OpenAI-like delta choices in stream\n \n### File Uploads\n\nYou can attach files either at the top-level `uploads` field or embedded in message content. The pipe will forward them to Flowise’s `uploads` API field.\n\nMinimal example (top-level):\n\n```json\n{\n  \"uploads\": [\n    {\n      \"data\": \"data:text/plain;base64,SGVsbG8=\",\n      \"type\": \"file:full\",\n      \"name\": \"example.txt\",\n      \"mime\": \"text/plain\"\n    }\n  ]\n}\n```\n\nSupported sources:\n- Data URLs (`data:*;base64,....`)\n- Remote URLs (`http(s)://...`) if `FLOWISE_ALLOW_REMOTE_FILE_URLS=1`\n- Structured content items with `type` in `file`, `input_file`, `data_url`, or `image_url` (converted)\n\nNotes:\n- If `type` is not provided, `FLOWISE_DEFAULT_UPLOAD_TYPE` is used (`file:full`).\n- The pipe also sets `chatId` alongside `overrideConfig.sessionId` for maximum compatibility.\n### History Forwarding\n\nWhen sending a message, prior messages in the chat are converted to a minimal history object and sent to Flowise as `history`:\n\n```json\n{\n  \"history\": [\n    {\"role\": \"system\", \"content\": \"You are helpful\"},\n    {\"role\": \"user\", \"content\": \"Hi\"},\n    {\"role\": \"assistant\", \"content\": \"Hello!\"}\n  ]\n}\n```\n\nOnly non-empty message contents are forwarded. Roles unsupported by Flowise are normalized to `user`.\n\n### Override Config Merging\n\nYou can pass custom overrides using `overrideConfig` (or `flowise_override`). The pipe merges them while preserving the OpenWebUI session:\n\n```json\n{\n  \"overrideConfig\": {\n    \"model\": \"gpt-4o-mini\",\n    \"temperature\": 0.2\n  }\n}\n```\n\nIf you explicitly set `sessionId`, your value will be used.\n\n\n## 🔧 Troubleshooting\n\n### Common Issues\n\n#### \"Response ready!\" but no actual response\n\n**Cause**: Usually indicates a response format issue or streaming problem.\n\n**Solution**:\n1. Enable debug mode\n2. Check the logs for response format\n3. Verify Flowise is returning expected data\n\n#### Connection timeouts\n\n**Cause**: Flowise instance is slow or unreachable.\n\n**Solutions**:\n- For streaming (SSE) timeouts: increase `FLOWISE_READ_TIMEOUT_STREAM`, e.g. `export FLOWISE_READ_TIMEOUT_STREAM=3600`\n- For general requests: adjust `FLOWISE_TIMEOUT` (applies to both connect/read), or tune `FLOWISE_CONNECT_TIMEOUT` and `FLOWISE_READ_TIMEOUT` separately\n- Check Flowise instance health\n- Verify network connectivity\n\n#### No chatflows appear\n\n**Causes \u0026 Solutions**:\n- **Missing API key**: Set `FLOWISE_API_KEY` if required\n- **Wrong URL**: Verify `FLOWISE_API_URL` is correct\n- **Network issues**: Check connectivity to Flowise\n- **Authentication**: Ensure API key has proper permissions\n\n#### Streaming not working\n\n**Solutions**:\n- Check if Flowise supports streaming for your workflow\n- Verify the chatflow configuration\n- Enable debug mode to see streaming data\n\n### Debug Information\n\nWhen debug mode is enabled, you'll see detailed logs including:\n\n```\nDebug - Request URL: http://localhost:3001/api/v1/prediction/abc123\nDebug - Request data: {\n  \"question\": \"Hello\",\n  \"overrideConfig\": {\n    \"sessionId\": \"session_123456\"\n  },\n  \"streaming\": true\n}\nDebug - Response status: 200\nDebug - Streaming line: data: {\"event\":\"token\",\"data\":\"Hello\"}\n```\n\n## 🏗️ Architecture\n\n### Core Components\n\n```\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   OpenWebUI     │───▶│  Flowise Pipe    │───▶│   Flowise API   │\n│                 │    │                  │    │                 │\n│ • Chat Interface│    │ • Model Discovery│    │ • Chatflows     │\n│ • Model Selector│    │ • Stream Handling│    │ • AI Workflows  │\n│ • Status Display│    │ • Error Handling │    │ • Predictions   │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n```\n\n### Flow Diagram\n\n```mermaid\nsequenceDiagram\n    participant UI as OpenWebUI\n    participant P as Flowise Pipe\n    participant F as Flowise API\n    \n    UI-\u003e\u003eP: Load available models\n    P-\u003e\u003eF: GET /api/v1/chatflows\n    F-\u003e\u003eP: Return chatflows list\n    P-\u003e\u003eUI: Display available models\n    \n    UI-\u003e\u003eP: Send message\n    P-\u003e\u003eP: Process message content\n    P-\u003e\u003eF: POST /api/v1/prediction/{id}\n    F-\u003e\u003eP: Stream response tokens\n    P-\u003e\u003eUI: Yield response tokens\n```\n\n### Response Processing\n\nThe pipe handles multiple response formats from Flowise:\n\n1. **Streaming Responses**: Server-Sent Events (SSE) with token data\n2. **Non-Streaming**: JSON responses with various field names\n3. **Error Responses**: HTTP errors with descriptive messages\n\n## 🤝 Contributing\n\n### Development Setup\n\n1. Clone the repository\n2. Set up a local Flowise instance for testing\n3. Configure environment variables\n4. Test with various chatflow types\n\n### Code Style\n\n- Follow PEP 8 guidelines\n- Add type hints for all functions\n- Include comprehensive error handling\n- Write descriptive docstrings\n- Add debug logging for troubleshooting\n\n### Testing\n\nTest the pipe with:\n- Different Flowise chatflow types\n- Various message formats (text, structured content)\n- Error conditions (network issues, invalid responses)\n- Both streaming and non-streaming modes\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## 🙏 Acknowledgments\n\n- [OpenWebUI](https://github.com/open-webui/open-webui) for the excellent chat interface\n- [Flowise](https://github.com/FlowiseAI/Flowise) for the powerful AI workflow platform\n- The open-source community for inspiration and support\n\n## 📚 Related Resources\n\n- [OpenWebUI Documentation](https://docs.openwebui.com/)\n- [Flowise Documentation](https://docs.flowiseai.com/)\n- [OpenWebUI Pipelines Guide](https://docs.openwebui.com/pipelines/)\n\n---\n\n**Need help?** Open an issue with:\n- Your OpenWebUI version\n- Flowise version and configuration\n- Debug logs (with sensitive data removed)\n- Steps to reproduce the issue","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarhal%2Fopenwebui-flowise-pipe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkarhal%2Fopenwebui-flowise-pipe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarhal%2Fopenwebui-flowise-pipe/lists"}