Development moved: This integration is maintained in the DeepKeep integrations monorepo. Please open new issues and pull requests in the monorepo. Existing raw-file installation URLs and the v0.1.1 release remain available here. Historical source and release links are retained; no filter re-import is needed for this repository move.
Native Open WebUI Filter Function for DeepKeep AI Firewall using the DeepKeep v3 OpenAI-compatible moderation API.
deepkeep_openwebui_filter.py
LICENSE: MIT license.SECURITY.md: vulnerability reporting and operational security notes.COMMUNITY_LISTING.md: historical draft text; the published community listing now points to the monorepo..github/workflows/test.yml: GitHub Actions test workflow for public repository CI.
- Runs pre-model moderation through
/api/v3/openai/moderations/pre. - Runs post-model moderation through
/api/v3/openai/moderations/post. - Blocks, redacts, modifies, or allows content based on DeepKeep
guardrail_action. - Supports fail-open or fail-closed behavior.
- Runs as an always-on filter when enabled in Open WebUI.
- Open Open WebUI as an administrator.
- Go to
Admin Panel > Functions. - Create a new function.
- Set the function type to
Filter. - Import or paste the contents of
deepkeep_openwebui_filter.py. - Save and enable the function.
Set these admin valves after importing the function:
| Valve | Description |
|---|---|
DEEPKEEP_API_KEY |
DeepKeep API key. |
DEEPKEEP_BASE_URL |
DeepKeep base URL, for example https://api.example.deepkeep.ai. |
PRE_MODEL |
DeepKeep model/firewall identifier for pre-moderation. Required when MODE is pre or both. |
POST_MODEL |
DeepKeep model/firewall identifier for post-moderation. Required when MODE is post or both. |
MODE |
pre, post, or both. Defaults to both. |
FAIL_MODE |
fail_closed or fail_open. Defaults to fail_closed. |
BLOCK_MESSAGE |
Message shown when content is blocked. |
TIMEOUT |
DeepKeep HTTP timeout in seconds. |
priority |
Open WebUI filter execution order. Lower values run first. |
For firewall behavior, make the filter active and global:
- Go to
Admin Panel > Functions. - Enable the function.
- Toggle global mode for the function.
The filter intentionally does not set self.toggle = True, so users cannot disable it from the chat UI when it is active and in scope.
Run these checks after configuring valves:
- Send an allowed prompt and confirm the model responds normally.
- Send a prompt that DeepKeep should block and confirm the model is not called.
- Send a prompt that DeepKeep should redact or modify and confirm the model receives the changed content.
- Trigger a blocked assistant output policy and confirm the response shown to the user is replaced with
BLOCK_MESSAGE. - Temporarily set an invalid
DEEPKEEP_BASE_URLand confirmfail_closedblocks whilefail_openallows traffic through.
Use this before importing into Open WebUI to verify credentials, base URL, model identifiers, and the DeepKeep v3 contract.
Set environment variables:
$env:DEEPKEEP_API_KEY = "your-api-key"
$env:DEEPKEEP_BASE_URL = "https://api.example.deepkeep.ai"
$env:DEEPKEEP_PRE_MODEL = "your-pre-model-or-firewall-id"
$env:DEEPKEEP_POST_MODEL = "your-post-model-or-firewall-id".env.example contains the same variable names as a reference. Keep real credentials out of source control.
Run from this directory:
python scripts\smoke_deepkeep_v3.py --phase both --content "Hello from smoke test"The script prints the parsed DeepKeep decision for each phase. It exits before making requests if required environment variables are missing.
The repository includes mock-based tests for the standalone filter. They do not call DeepKeep or Open WebUI.
Run from this directory:
python -m pip install -r requirements-dev.txt
python -m pytestCurrent coverage checks:
- DeepKeep decision parsing and action priority.
- Pre-moderation redaction and blocking.
- Post-moderation redaction and blocking.
fail_openandfail_closedbehavior on DeepKeep errors.pre,post, andbothmode gating.- DeepKeep v3 endpoint, header, payload, and API error handling.
- If every request is blocked, check
FAIL_MODE,DEEPKEEP_BASE_URL,DEEPKEEP_API_KEY, and the required model valve for the activeMODE. - If pre-moderation works but post-moderation does not run, confirm the filter is active for the selected model and the Open WebUI request path invokes
outlet()for your version/API usage. - For direct
/api/chat/completionscallers on some Open WebUI releases,outlet()may not rewrite the immediate HTTP response. WebUI chat requests and/api/chat/completedare the reliable paths for post-response filtering. - If Open WebUI fails to import the function due to
httpx, install the function requirement or ensurehttpxis available in the Open WebUI Python environment. - If users can disable the filter from chat, verify the plugin file was not modified to set
self.toggle = True.
The filter calls DeepKeep with:
POST {DEEPKEEP_BASE_URL}/api/v3/openai/moderations/pre
X-API-Key: {DEEPKEEP_API_KEY}
Accept: application/jsonPre-moderation body:
{
"model": "PRE_MODEL",
"input": "user message",
"title": "optional title",
"chat": "optional chat id"
}Post-moderation body:
{
"model": "POST_MODEL",
"output": "assistant message",
"title": "optional title",
"chat": "optional chat id"
}Decision parsing expects DeepKeep actions at verbosity[*].details.guardrail_action and replacement content at verbosity[*].details.modified[*].content.