owpp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- owpp-0.1.0/.gitignore +8 -0
- owpp-0.1.0/CHANGELOG.md +33 -0
- owpp-0.1.0/LICENSE +21 -0
- owpp-0.1.0/NOTICE.md +38 -0
- owpp-0.1.0/PKG-INFO +130 -0
- owpp-0.1.0/README.md +108 -0
- owpp-0.1.0/SECURITY.md +94 -0
- owpp-0.1.0/docs/README.md +72 -0
- owpp-0.1.0/docs/adopting.md +33 -0
- owpp-0.1.0/docs/agents/domain.md +51 -0
- owpp-0.1.0/docs/agents/issue-tracker.md +50 -0
- owpp-0.1.0/docs/agents/triage-labels.md +15 -0
- owpp-0.1.0/docs/authoring.md +58 -0
- owpp-0.1.0/docs/bundling.md +57 -0
- owpp-0.1.0/docs/contributing.md +44 -0
- owpp-0.1.0/docs/decisions.md +83 -0
- owpp-0.1.0/docs/libraries.md +276 -0
- owpp-0.1.0/docs/plugin-format.md +161 -0
- owpp-0.1.0/docs/reviewing.md +59 -0
- owpp-0.1.0/docs/runtime.md +45 -0
- owpp-0.1.0/docs/screenshots/deploy/functions.png +0 -0
- owpp-0.1.0/docs/screenshots/excalidraw/editor-in-chat.png +0 -0
- owpp-0.1.0/docs/screenshots/excalidraw/editor-without-same-origin.png +0 -0
- owpp-0.1.0/docs/screenshots/excalidraw/signed-out-redirect.png +0 -0
- owpp-0.1.0/docs/screenshots/inline_visualizer/disabled.png +0 -0
- owpp-0.1.0/docs/screenshots/inline_visualizer/skills.png +0 -0
- owpp-0.1.0/docs/screenshots/inline_visualizer/tools.png +0 -0
- owpp-0.1.0/docs/screenshots/litellm_model_sync/admin-models.png +0 -0
- owpp-0.1.0/docs/screenshots/litellm_model_sync/model-selector.png +0 -0
- owpp-0.1.0/docs/screenshots/mcpo_sync/tool-servers.png +0 -0
- owpp-0.1.0/docs/screenshots/page_banners/banner-in-a-chat.png +0 -0
- owpp-0.1.0/docs/screenshots/page_banners/collapsed.png +0 -0
- owpp-0.1.0/docs/screenshots/page_banners/live-update.png +0 -0
- owpp-0.1.0/docs/screenshots/page_banners/position-bottom.png +0 -0
- owpp-0.1.0/docs/screenshots/screenshots.json +152 -0
- owpp-0.1.0/docs/screenshots/stale_data/dashboard.png +0 -0
- owpp-0.1.0/docs/screenshots/stale_data/not-an-admin.png +0 -0
- owpp-0.1.0/docs/screenshots.md +62 -0
- owpp-0.1.0/docs/testing.md +119 -0
- owpp-0.1.0/docs/tooling.md +118 -0
- owpp-0.1.0/examples/plugins/excalidraw/README.md +72 -0
- owpp-0.1.0/examples/plugins/excalidraw/config.yaml +2 -0
- owpp-0.1.0/examples/plugins/excalidraw/function.py +211 -0
- owpp-0.1.0/examples/plugins/excalidraw/plugin.yaml +16 -0
- owpp-0.1.0/examples/plugins/excalidraw/self-host/.gitignore +2 -0
- owpp-0.1.0/examples/plugins/excalidraw/self-host/build.sh +21 -0
- owpp-0.1.0/examples/plugins/excalidraw/self-host/bun.lock +493 -0
- owpp-0.1.0/examples/plugins/excalidraw/self-host/editor.js +7 -0
- owpp-0.1.0/examples/plugins/excalidraw/self-host/package.json +11 -0
- owpp-0.1.0/examples/plugins/excalidraw/shared.py +150 -0
- owpp-0.1.0/examples/plugins/excalidraw/templates/viewer.html +210 -0
- owpp-0.1.0/examples/plugins/excalidraw/tests/test_excalidraw_filter.py +255 -0
- owpp-0.1.0/examples/plugins/excalidraw/tests/test_excalidraw_self_host.py +204 -0
- owpp-0.1.0/examples/plugins/excalidraw/tests/test_excalidraw_tool.py +275 -0
- owpp-0.1.0/examples/plugins/excalidraw/tool.py +145 -0
- owpp-0.1.0/examples/plugins/inline_visualizer/README.md +27 -0
- owpp-0.1.0/examples/plugins/inline_visualizer/plugin.yaml +21 -0
- owpp-0.1.0/examples/plugins/inline_visualizer/tests/test_inline_visualizer.py +112 -0
- owpp-0.1.0/examples/plugins/litellm_model_sync/README.md +30 -0
- owpp-0.1.0/examples/plugins/litellm_model_sync/function.py +365 -0
- owpp-0.1.0/examples/plugins/litellm_model_sync/plugin.yaml +10 -0
- owpp-0.1.0/examples/plugins/litellm_model_sync/tests/test_litellm_model_sync.py +306 -0
- owpp-0.1.0/examples/plugins/mcpo_sync/README.md +32 -0
- owpp-0.1.0/examples/plugins/mcpo_sync/config.yaml +8 -0
- owpp-0.1.0/examples/plugins/mcpo_sync/function.py +154 -0
- owpp-0.1.0/examples/plugins/mcpo_sync/plugin.yaml +10 -0
- owpp-0.1.0/examples/plugins/mcpo_sync/tests/test_mcpo_sync.py +425 -0
- owpp-0.1.0/examples/plugins/page_banners/README.md +30 -0
- owpp-0.1.0/examples/plugins/page_banners/assets/custom.css +46 -0
- owpp-0.1.0/examples/plugins/page_banners/assets/loader.js +590 -0
- owpp-0.1.0/examples/plugins/page_banners/function.py +57 -0
- owpp-0.1.0/examples/plugins/page_banners/plugin.yaml +9 -0
- owpp-0.1.0/examples/plugins/page_banners/tests/test_page_banners.py +165 -0
- owpp-0.1.0/examples/plugins/stale_data/README.md +19 -0
- owpp-0.1.0/examples/plugins/stale_data/function.py +458 -0
- owpp-0.1.0/examples/plugins/stale_data/plugin.yaml +9 -0
- owpp-0.1.0/examples/plugins/stale_data/templates/index.html +49 -0
- owpp-0.1.0/examples/plugins/stale_data/tests/test_stale_data.py +156 -0
- owpp-0.1.0/pyproject.toml +81 -0
- owpp-0.1.0/src/owpp/__init__.py +3 -0
- owpp-0.1.0/src/owpp/__main__.py +5 -0
- owpp-0.1.0/src/owpp/bundle.py +961 -0
- owpp-0.1.0/src/owpp/cli.py +423 -0
- owpp-0.1.0/src/owpp/deploy.py +435 -0
- owpp-0.1.0/src/owpp/envtemplate.py +57 -0
- owpp-0.1.0/src/owpp/errors.py +2 -0
- owpp-0.1.0/src/owpp/events.py +39 -0
- owpp-0.1.0/src/owpp/lint.py +208 -0
- owpp-0.1.0/src/owpp/manifest.py +119 -0
- owpp-0.1.0/src/owpp/runtime/lib/live_reload.py +211 -0
- owpp-0.1.0/src/owpp/runtime/lib/plugin_assets.py +130 -0
- owpp-0.1.0/src/owpp/runtime/lib/plugin_chat_data.py +129 -0
- owpp-0.1.0/src/owpp/runtime/lib/plugin_config.py +29 -0
- owpp-0.1.0/src/owpp/runtime/lib/plugin_core.py +124 -0
- owpp-0.1.0/src/owpp/runtime/lib/plugin_events.py +104 -0
- owpp-0.1.0/src/owpp/runtime/lib/plugin_jobs.py +235 -0
- owpp-0.1.0/src/owpp/runtime/lib/plugin_routes.py +327 -0
- owpp-0.1.0/src/owpp/runtime/lib/plugin_static.py +101 -0
- owpp-0.1.0/src/owpp/runtime/lib/plugin_templates.py +31 -0
- owpp-0.1.0/src/owpp/runtime/lib/shared_assets.py +198 -0
- owpp-0.1.0/src/owpp/runtime/plugin_runtime.py +366 -0
- owpp-0.1.0/src/owpp/sources.py +190 -0
- owpp-0.1.0/src/owpp/testing/__init__.py +26 -0
- owpp-0.1.0/src/owpp/testing/mock.py +1247 -0
- owpp-0.1.0/src/owpp/testing/pytest_plugin.py +38 -0
- owpp-0.1.0/tests/conftest.py +219 -0
- owpp-0.1.0/tests/plugin_libs_test.py +689 -0
- owpp-0.1.0/tests/plugin_runtime_test.py +356 -0
- owpp-0.1.0/tests/test_access.py +943 -0
- owpp-0.1.0/tests/test_assets.py +254 -0
- owpp-0.1.0/tests/test_bundle.py +999 -0
- owpp-0.1.0/tests/test_cli.py +154 -0
- owpp-0.1.0/tests/test_deploy.py +441 -0
- owpp-0.1.0/tests/test_env.py +293 -0
- owpp-0.1.0/tests/test_events.py +443 -0
- owpp-0.1.0/tests/test_jobs.py +251 -0
- owpp-0.1.0/tests/test_lint.py +252 -0
- owpp-0.1.0/tests/test_mock.py +114 -0
- owpp-0.1.0/tests/test_sources.py +225 -0
- owpp-0.1.0/tests/test_test_docs.py +32 -0
owpp-0.1.0/.gitignore
ADDED
owpp-0.1.0/CHANGELOG.md
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0 (2026-11-19)
|
|
4
|
+
|
|
5
|
+
The first standalone release, extracted from a working deployment. On [PyPI](https://pypi.org/project/owpp/) as `owpp`; the GitHub Action is `zmnatz/open-webui-plugin-protocol@v0.1.0`.
|
|
6
|
+
|
|
7
|
+
- Plugin folders with a `plugin.yaml` manifest: a function (the parent) plus an optional tool and skills, `shared.py`, `static/`, `templates/` and `assets/`.
|
|
8
|
+
- Bundler: fixed order (header, libraries, `shared.py`, code, runtime), `{{file:}}`, `from __future__` hoisting, git sources pinned by full SHA, skills as whole folders.
|
|
9
|
+
- Runtime: the function installs, updates and removes its tool and skills; parent valves `INSTALL_TOOLS`, `INSTALL_SKILLS`, `TOOL_VALVES`.
|
|
10
|
+
- Libraries: `assets` (`assets/loader.js` and `assets/custom.css` published through the Shared Assets Protocol, with `class Event(PluginAssets)`), `config` (a `config.yaml` parsed at bundle time), `core`, `routes`, `jobs` (with `PluginScheduledSync`), `chat_data`, `static` (files served as they are), `templates` (files the function renders, never served), and the vendored Shared Assets Protocol.
|
|
11
|
+
- The `jobs:` manifest section: the sync mixin adds its `ENABLE` and `SYNC_INTERVAL_MINUTES` valves itself, and the interval's default is declared in `plugin.yaml`.
|
|
12
|
+
- Environment templates, `${NAME:-default}`, in `jobs:` and `config.yaml`: embedded as written and resolved from the Open-WebUI container's environment when the plugin loads, never when bundling (so a bundle never depends on the machine that built it). `owpp check` lists the variables a plugin reads.
|
|
13
|
+
- `plugin_token` / `plugin_check_token`: signed, expiring tokens scoped to the function, for a route that cannot carry a session. A `plugin_mount` name is the mount's identity, so a moved mount replaces its old self. The events mixin creates `self.valves` itself.
|
|
14
|
+
- A page opened with no session is not just refused: the no-input sign-ins (trusted headers, auth off) are tried in-process, then the browser goes to Open-WebUI's login page and back; iframes and API calls get a plain 401.
|
|
15
|
+
- `owpp check` warns about a valve with no description and about tool methods with no docstring, type hints or `:param` lines; `--strict` fails on warnings.
|
|
16
|
+
- `SECURITY.md`: the trust model, what `owpp` limits, the known limits, how to report.
|
|
17
|
+
- Signed in by default, public only on purpose: every route needs a signed-in user, marked on the route, on the mount (`access=`) or, for `static/` files, with `static: {access: user | admin | public}`, and enforced by `plugin_mount`. `access="public"` (exactly that word, per mount) serves people who are not signed in, and `owpp check` notes every one. The `public/` folder and `dynamic:` list of the deployment it was extracted from are refused, with a message saying where things went (`static/`, `templates/`). Unknown top-level keys in `plugin.yaml` are refused. A single route is marked with `user: PluginAdmin` or `user: PluginUser` (tighten only), or by its chat with `chat_id: WritableChat` / `ReadableChat`. `guard=` replaces the check for a sandboxed API. Code that mounts straight onto the app is refused.
|
|
18
|
+
- Event handlers by decorator: `@on("event.name", own=True)` on a `PluginEvents` class, with event names checked by `owpp check`. `PluginScheduledSync` and `PluginAssets` are built on it.
|
|
19
|
+
- Function types read from the top-level class; `global` only for filters and actions.
|
|
20
|
+
- `owpp` CLI (a Python package, `uvx owpp`): `list`, `check`, `bundle`, `deploy`, `init`. Configurable plugins folder and ownership marker; `--only` deploys without pruning.
|
|
21
|
+
- Composite GitHub Action (runs `owpp` from its own checkout with uv).
|
|
22
|
+
- Excalidraw can load its editor from a host you run (`EXCALIDRAW_ASSETS_URL`, built by `self-host/build.sh`), so the page needs nothing from the internet.
|
|
23
|
+
- `owpp test [id ...]`: runs each plugin's `tests/` folder with pytest against a mock Open-WebUI (`owpp.testing.MockOpenWebUI`, `docs/testing.md`). The mock covers the function, tool and skill tables, users and auth, chats in SQLite, config, the socket, event sinks and the FastAPI app. The `owui`, `plugin_dir` and `plugin` pytest fixtures are registered wherever owpp is installed. The extra `owpp[test]` brings pytest and the packages Open-WebUI ships.
|
|
24
|
+
- `owpp init` scaffolds a plugin, with a `tests/test_<id>.py` that passes.
|
|
25
|
+
- Examples: `excalidraw`, `mcpo_sync`, `stale_data`, `inline_visualizer`, `page_banners`, `litellm_model_sync`, each with unit tests in its own `tests/` folder. Every test has a docstring: what it checks, then `By hand:` steps to repeat it on a live Open-WebUI. `owpp init` scaffolds tests that do the same, and `tests/test_test_docs.py` enforces it.
|
|
26
|
+
- A documentation site (Zensical, `zensical.toml`, built by `tools/build_docs.py`), published to GitHub Pages by `.github/workflows/docs.yml`. It adds pages for review: a test catalogue built from the test docstrings, an audit trail built from `git log`, and how to review and make a change.
|
|
27
|
+
- Screenshots on a real Open-WebUI: `tools/screenshots/run.py` starts Open-WebUI v0.13.4, a scripted model and mcpo in Docker, deploys `examples/plugins` with `owpp deploy`, and follows the plugins' By hand steps with Playwright (`docs/screenshots.md`). The screenshots are in `docs/screenshots/`, and the site shows them in the test catalogue, on each example's page and on a page of their own. `.github/workflows/screenshots.yml` takes them on GitHub when run by hand.
|
|
28
|
+
- Known limitation: the Excalidraw editor needs **iframe Sandbox Allow Same Origin** in Open-WebUI. Without it, the sandboxed panel sends no session and the page answers 401. The README says how to turn it on and what that costs. It is kept on purpose, as Inline Visualizer needs the same setting (issue #6, `docs/decisions.md`).
|
|
29
|
+
- `access: public` on a tool or skill is Open-WebUI's `user:*` read grant, so every signed-in user can use it. Grants an earlier copy of the runtime wrote to the no-auth `anyone:*` audience, which Open-WebUI ignores for tools and skills, are swapped once on the next sync.
|
|
30
|
+
- `global: false` for a filter that each user switches on (a toggle): the deploy never makes it global, and takes it out of global if someone did. Without the key, a new filter is still made global on first deploy.
|
|
31
|
+
- The mock Open-WebUI fetches a `source:` plugin's pinned files from git when a test gives no `sources=`, stands in for any `open_webui.*` module or name it does not implement (using one raises `NotImplementedError` naming it), and has Open-WebUI's data directories (`owui.data_dir`).
|
|
32
|
+
- `jobs: adopt_markers` in `plugin.yaml`: the markers of an earlier sync whose entries a sync treats as its own (`plugin_sync_markers()`), for moving from that sync without leaving its entries behind. mcpo Sync and LiteLLM Model Sync use it.
|
|
33
|
+
- Decisions and assumptions: `docs/decisions.md`.
|
owpp-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Zaven
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
owpp-0.1.0/NOTICE.md
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Third-party notices
|
|
2
|
+
|
|
3
|
+
`src/owpp/runtime/lib/shared_assets.py` and `src/owpp/runtime/lib/live_reload.py` are the reference implementation of the [Shared Assets Protocol](https://github.com/Classic298/open-webui-plugins/tree/main/shared-assets-protocol) by Classic298, vendored unmodified, under this licence:
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
BSD 3-Clause License
|
|
7
|
+
|
|
8
|
+
Copyright (c) 2026, Classic298
|
|
9
|
+
|
|
10
|
+
Redistribution and use in source and binary forms, with or without
|
|
11
|
+
modification, are permitted provided that the following conditions are met:
|
|
12
|
+
|
|
13
|
+
1. Redistributions of source code must retain the above copyright notice, this
|
|
14
|
+
list of conditions and the following disclaimer.
|
|
15
|
+
|
|
16
|
+
2. Redistributions in binary form must reproduce the above copyright notice,
|
|
17
|
+
this list of conditions and the following disclaimer in the documentation
|
|
18
|
+
and/or other materials provided with the distribution.
|
|
19
|
+
|
|
20
|
+
3. Neither the name of the copyright holder nor the names of its
|
|
21
|
+
contributors may be used to endorse or promote products derived from
|
|
22
|
+
this software without specific prior written permission.
|
|
23
|
+
|
|
24
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
25
|
+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
26
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
27
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
|
28
|
+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
29
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
30
|
+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
31
|
+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
32
|
+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
33
|
+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
`examples/plugins/page_banners/` is a variant of [Better Banners](https://github.com/Classic298/open-webui-plugins/tree/main/better-banners) by Classic298, under the same licence and copyright notice as above: `assets/loader.js`, `assets/custom.css` and `function.py` are derived from it, with the changes listed in that plugin's README.
|
|
37
|
+
|
|
38
|
+
Plugins referenced by `source:` in the examples (such as `inline_visualizer`) are fetched from their own repositories at deploy time, under their own licences, and are not redistributed here.
|
owpp-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: owpp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Write, test and deploy Open-WebUI plugins (a function plus its tool and skills) from a git repository.
|
|
5
|
+
Project-URL: Repository, https://github.com/zmnatz/open-webui-plugin-protocol
|
|
6
|
+
Project-URL: Changelog, https://github.com/zmnatz/open-webui-plugin-protocol/blob/main/CHANGELOG.md
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
License-File: NOTICE.md
|
|
10
|
+
Keywords: deploy,functions,open-webui,plugins,skills,tools
|
|
11
|
+
Classifier: Operating System :: OS Independent
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Requires-Python: >=3.10
|
|
14
|
+
Requires-Dist: pyyaml>=6.0
|
|
15
|
+
Provides-Extra: test
|
|
16
|
+
Requires-Dist: aiohttp>=3.9; extra == 'test'
|
|
17
|
+
Requires-Dist: fastapi>=0.115; extra == 'test'
|
|
18
|
+
Requires-Dist: httpx>=0.27; extra == 'test'
|
|
19
|
+
Requires-Dist: pytest>=8; extra == 'test'
|
|
20
|
+
Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'test'
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
23
|
+
# Open-WebUI plugin protocol
|
|
24
|
+
|
|
25
|
+
Write, test and deploy [Open-WebUI](https://github.com/open-webui/open-webui) plugins from a git repository.
|
|
26
|
+
|
|
27
|
+
A **plugin** is a folder: a function (the parent), plus an optional tool and skills that are installed when the function is enabled and removed when it is disabled. Shared libraries cover what every plugin ends up re-implementing: HTTP routes that survive reloads, scheduled jobs that run on one worker, data stored with a chat, static files. A CLI (`owpp`) checks, bundles and deploys them, from a laptop or a GitHub Action.
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
plugins/excalidraw/
|
|
31
|
+
plugin.yaml function + tool + libraries, in one manifest
|
|
32
|
+
function.py class Filter: serves the editor, adds it to replies
|
|
33
|
+
tool.py class Tools: lets the model read and change the drawing
|
|
34
|
+
shared.py code both need
|
|
35
|
+
templates/viewer.html the page, kept out of Python strings
|
|
36
|
+
README.md what it is, how to test it, how to deploy it
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
```yaml
|
|
40
|
+
# plugin.yaml
|
|
41
|
+
function:
|
|
42
|
+
title: Excalidraw
|
|
43
|
+
version: 3.1.0
|
|
44
|
+
global: true
|
|
45
|
+
tool:
|
|
46
|
+
id: excalidraw
|
|
47
|
+
include: [chat_data]
|
|
48
|
+
access: public
|
|
49
|
+
include: [routes, chat_data]
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
uvx owpp list
|
|
54
|
+
# excalidraw filter (global)
|
|
55
|
+
# mcpo_sync event
|
|
56
|
+
uvx owpp check # bundle, compile, report undefined names
|
|
57
|
+
uvx --from 'owpp[test]' owpp test # each plugin's tests/, against a mock Open-WebUI
|
|
58
|
+
uvx owpp deploy --only excalidraw --dry-run
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Why
|
|
62
|
+
|
|
63
|
+
Open-WebUI stores each function and tool as **one code blob**, edited in the admin UI. That makes it hard to review changes, share code between plugins, keep a tool in step with the function it belongs to, or pin third-party code. This project:
|
|
64
|
+
|
|
65
|
+
- **bundles a folder into the single file Open-WebUI stores**, in a fixed order, with vendored libraries and code pulled from any git repo at a pinned commit;
|
|
66
|
+
- **makes the function the parent**: its tool and skills come and go with it;
|
|
67
|
+
- **deploys from git**, updating only what it created (an ownership marker), never hand-made functions.
|
|
68
|
+
|
|
69
|
+
## Install
|
|
70
|
+
|
|
71
|
+
Requires [uv](https://docs.astral.sh/uv/) (it brings its own Python) and `git` (for remote sources). Nothing to install: `uvx` runs `owpp` straight from PyPI. To have it on your `PATH`, `uv tool install owpp` (or `pipx install owpp`).
|
|
72
|
+
|
|
73
|
+
```sh
|
|
74
|
+
uvx owpp init hello --type event # scaffold plugins/hello/
|
|
75
|
+
uvx owpp check
|
|
76
|
+
OPEN_WEBUI_URL=https://chat.example.com OPEN_WEBUI_API_KEY=sk-... uvx owpp deploy --dry-run
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Deploy from GitHub Actions
|
|
80
|
+
|
|
81
|
+
```yaml
|
|
82
|
+
- uses: actions/checkout@v5
|
|
83
|
+
- uses: zmnatz/open-webui-plugin-protocol@v0.1.0
|
|
84
|
+
with:
|
|
85
|
+
url: https://chat.example.com
|
|
86
|
+
api-key: ${{ secrets.OPEN_WEBUI_API_KEY }}
|
|
87
|
+
plugins-dir: plugins
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## Documentation
|
|
91
|
+
|
|
92
|
+
Published at **https://zmnatz.github.io/open-webui-plugin-protocol/**, built from `docs/` (`uv run --group docs python tools/build_docs.py serve` to preview it).
|
|
93
|
+
|
|
94
|
+
| | |
|
|
95
|
+
| --- | --- |
|
|
96
|
+
| [Overview](docs/README.md) | concepts, guarantees, status |
|
|
97
|
+
| [Authoring guide](docs/authoring.md) | function types, conventions, checklist |
|
|
98
|
+
| [Plugin format](docs/plugin-format.md) | `plugin.yaml` reference |
|
|
99
|
+
| [Bundling](docs/bundling.md) | exactly what gets deployed; git sources |
|
|
100
|
+
| [Runtime](docs/runtime.md) | install/remove of tools and skills, parent valves |
|
|
101
|
+
| [Libraries](docs/libraries.md) | `core`, `routes`, `jobs`, `events`, `chat_data`, `static`, `templates`, `assets`, Shared Assets |
|
|
102
|
+
| [Testing](docs/testing.md) | unit tests per plugin, the mock Open-WebUI, `owpp test` |
|
|
103
|
+
| [Tooling](docs/tooling.md) | CLI, deploy settings, ownership marker, GitHub Action, tests |
|
|
104
|
+
| [Adopting](docs/adopting.md) | new repositories, migrating existing functions |
|
|
105
|
+
| [Decisions](docs/decisions.md) | the calls made for 0.1.0 and what is not done yet |
|
|
106
|
+
| [Security](SECURITY.md) | the trust model, what `owpp` limits, known limits, how to report |
|
|
107
|
+
|
|
108
|
+
## Examples
|
|
109
|
+
|
|
110
|
+
[`examples/plugins/`](examples/plugins): `excalidraw` (filter + tool + page), `mcpo_sync` (scheduled event), `stale_data` (admin dashboard), `inline_visualizer` (third-party tool and skill from a pinned commit), `page_banners` (a variant of Better Banners: its script and stylesheet are files in `assets/`), `litellm_model_sync` (scheduled event that writes Open-WebUI's model configs from a LiteLLM gateway).
|
|
111
|
+
|
|
112
|
+
## Status
|
|
113
|
+
|
|
114
|
+
0.1.0, released 2026-11-19, written against Open-WebUI v0.13.4. The bundler, runtime and libraries are tested against stubbed Open-WebUI modules, and each example plugin has unit tests run against a mock Open-WebUI (`owpp test`). The examples have been deployed and photographed on a real Open-WebUI v0.13.4 ([screenshots](docs/screenshots.md)), but that run is started by hand, not part of CI. See [decisions](docs/decisions.md#not-done-yet).
|
|
115
|
+
|
|
116
|
+
## Development
|
|
117
|
+
|
|
118
|
+
```sh
|
|
119
|
+
uv sync
|
|
120
|
+
uv run pytest # owpp's tests and every example plugin's tests/
|
|
121
|
+
uv run owpp test --dir examples/plugins
|
|
122
|
+
uv run ruff check . && uv run ruff format --check .
|
|
123
|
+
uv run owpp check --dir examples/plugins
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
## Licence
|
|
127
|
+
|
|
128
|
+
MIT ([LICENSE](LICENSE)). Vendored third-party code (Classic298's Shared Assets Protocol, BSD-3-Clause): [NOTICE.md](NOTICE.md).
|
|
129
|
+
|
|
130
|
+
This project contains no Open WebUI code: it talks to Open WebUI's API and produces plugins that run inside it. It is an independent project, **not affiliated with or endorsed by Open WebUI Inc.**; "Open WebUI" is used only to say what it works with. Open WebUI itself is under the [Open WebUI License](https://github.com/open-webui/open-webui/blob/main/LICENSE).
|
owpp-0.1.0/README.md
ADDED
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# Open-WebUI plugin protocol
|
|
2
|
+
|
|
3
|
+
Write, test and deploy [Open-WebUI](https://github.com/open-webui/open-webui) plugins from a git repository.
|
|
4
|
+
|
|
5
|
+
A **plugin** is a folder: a function (the parent), plus an optional tool and skills that are installed when the function is enabled and removed when it is disabled. Shared libraries cover what every plugin ends up re-implementing: HTTP routes that survive reloads, scheduled jobs that run on one worker, data stored with a chat, static files. A CLI (`owpp`) checks, bundles and deploys them, from a laptop or a GitHub Action.
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
plugins/excalidraw/
|
|
9
|
+
plugin.yaml function + tool + libraries, in one manifest
|
|
10
|
+
function.py class Filter: serves the editor, adds it to replies
|
|
11
|
+
tool.py class Tools: lets the model read and change the drawing
|
|
12
|
+
shared.py code both need
|
|
13
|
+
templates/viewer.html the page, kept out of Python strings
|
|
14
|
+
README.md what it is, how to test it, how to deploy it
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
```yaml
|
|
18
|
+
# plugin.yaml
|
|
19
|
+
function:
|
|
20
|
+
title: Excalidraw
|
|
21
|
+
version: 3.1.0
|
|
22
|
+
global: true
|
|
23
|
+
tool:
|
|
24
|
+
id: excalidraw
|
|
25
|
+
include: [chat_data]
|
|
26
|
+
access: public
|
|
27
|
+
include: [routes, chat_data]
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
uvx owpp list
|
|
32
|
+
# excalidraw filter (global)
|
|
33
|
+
# mcpo_sync event
|
|
34
|
+
uvx owpp check # bundle, compile, report undefined names
|
|
35
|
+
uvx --from 'owpp[test]' owpp test # each plugin's tests/, against a mock Open-WebUI
|
|
36
|
+
uvx owpp deploy --only excalidraw --dry-run
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Why
|
|
40
|
+
|
|
41
|
+
Open-WebUI stores each function and tool as **one code blob**, edited in the admin UI. That makes it hard to review changes, share code between plugins, keep a tool in step with the function it belongs to, or pin third-party code. This project:
|
|
42
|
+
|
|
43
|
+
- **bundles a folder into the single file Open-WebUI stores**, in a fixed order, with vendored libraries and code pulled from any git repo at a pinned commit;
|
|
44
|
+
- **makes the function the parent**: its tool and skills come and go with it;
|
|
45
|
+
- **deploys from git**, updating only what it created (an ownership marker), never hand-made functions.
|
|
46
|
+
|
|
47
|
+
## Install
|
|
48
|
+
|
|
49
|
+
Requires [uv](https://docs.astral.sh/uv/) (it brings its own Python) and `git` (for remote sources). Nothing to install: `uvx` runs `owpp` straight from PyPI. To have it on your `PATH`, `uv tool install owpp` (or `pipx install owpp`).
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
uvx owpp init hello --type event # scaffold plugins/hello/
|
|
53
|
+
uvx owpp check
|
|
54
|
+
OPEN_WEBUI_URL=https://chat.example.com OPEN_WEBUI_API_KEY=sk-... uvx owpp deploy --dry-run
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Deploy from GitHub Actions
|
|
58
|
+
|
|
59
|
+
```yaml
|
|
60
|
+
- uses: actions/checkout@v5
|
|
61
|
+
- uses: zmnatz/open-webui-plugin-protocol@v0.1.0
|
|
62
|
+
with:
|
|
63
|
+
url: https://chat.example.com
|
|
64
|
+
api-key: ${{ secrets.OPEN_WEBUI_API_KEY }}
|
|
65
|
+
plugins-dir: plugins
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Documentation
|
|
69
|
+
|
|
70
|
+
Published at **https://zmnatz.github.io/open-webui-plugin-protocol/**, built from `docs/` (`uv run --group docs python tools/build_docs.py serve` to preview it).
|
|
71
|
+
|
|
72
|
+
| | |
|
|
73
|
+
| --- | --- |
|
|
74
|
+
| [Overview](docs/README.md) | concepts, guarantees, status |
|
|
75
|
+
| [Authoring guide](docs/authoring.md) | function types, conventions, checklist |
|
|
76
|
+
| [Plugin format](docs/plugin-format.md) | `plugin.yaml` reference |
|
|
77
|
+
| [Bundling](docs/bundling.md) | exactly what gets deployed; git sources |
|
|
78
|
+
| [Runtime](docs/runtime.md) | install/remove of tools and skills, parent valves |
|
|
79
|
+
| [Libraries](docs/libraries.md) | `core`, `routes`, `jobs`, `events`, `chat_data`, `static`, `templates`, `assets`, Shared Assets |
|
|
80
|
+
| [Testing](docs/testing.md) | unit tests per plugin, the mock Open-WebUI, `owpp test` |
|
|
81
|
+
| [Tooling](docs/tooling.md) | CLI, deploy settings, ownership marker, GitHub Action, tests |
|
|
82
|
+
| [Adopting](docs/adopting.md) | new repositories, migrating existing functions |
|
|
83
|
+
| [Decisions](docs/decisions.md) | the calls made for 0.1.0 and what is not done yet |
|
|
84
|
+
| [Security](SECURITY.md) | the trust model, what `owpp` limits, known limits, how to report |
|
|
85
|
+
|
|
86
|
+
## Examples
|
|
87
|
+
|
|
88
|
+
[`examples/plugins/`](examples/plugins): `excalidraw` (filter + tool + page), `mcpo_sync` (scheduled event), `stale_data` (admin dashboard), `inline_visualizer` (third-party tool and skill from a pinned commit), `page_banners` (a variant of Better Banners: its script and stylesheet are files in `assets/`), `litellm_model_sync` (scheduled event that writes Open-WebUI's model configs from a LiteLLM gateway).
|
|
89
|
+
|
|
90
|
+
## Status
|
|
91
|
+
|
|
92
|
+
0.1.0, released 2026-11-19, written against Open-WebUI v0.13.4. The bundler, runtime and libraries are tested against stubbed Open-WebUI modules, and each example plugin has unit tests run against a mock Open-WebUI (`owpp test`). The examples have been deployed and photographed on a real Open-WebUI v0.13.4 ([screenshots](docs/screenshots.md)), but that run is started by hand, not part of CI. See [decisions](docs/decisions.md#not-done-yet).
|
|
93
|
+
|
|
94
|
+
## Development
|
|
95
|
+
|
|
96
|
+
```sh
|
|
97
|
+
uv sync
|
|
98
|
+
uv run pytest # owpp's tests and every example plugin's tests/
|
|
99
|
+
uv run owpp test --dir examples/plugins
|
|
100
|
+
uv run ruff check . && uv run ruff format --check .
|
|
101
|
+
uv run owpp check --dir examples/plugins
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
## Licence
|
|
105
|
+
|
|
106
|
+
MIT ([LICENSE](LICENSE)). Vendored third-party code (Classic298's Shared Assets Protocol, BSD-3-Clause): [NOTICE.md](NOTICE.md).
|
|
107
|
+
|
|
108
|
+
This project contains no Open WebUI code: it talks to Open WebUI's API and produces plugins that run inside it. It is an independent project, **not affiliated with or endorsed by Open WebUI Inc.**; "Open WebUI" is used only to say what it works with. Open WebUI itself is under the [Open WebUI License](https://github.com/open-webui/open-webui/blob/main/LICENSE).
|
owpp-0.1.0/SECURITY.md
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# Security
|
|
2
|
+
|
|
3
|
+
## Reporting a vulnerability
|
|
4
|
+
|
|
5
|
+
Please report it privately, not in a public issue: use GitHub's **Security** tab on this repository,
|
|
6
|
+
**Report a vulnerability**. If that is not available, open an issue that says only that you have a
|
|
7
|
+
security report and ask for a private channel; leave the details out.
|
|
8
|
+
|
|
9
|
+
Supported: the latest 0.1.x release. This is pre-1.0 software, written against Open-WebUI v0.13.4
|
|
10
|
+
and **not yet exercised against a live Open-WebUI** (see [decisions](docs/decisions.md#not-done-yet)),
|
|
11
|
+
so treat it accordingly.
|
|
12
|
+
|
|
13
|
+
## The trust model, in one paragraph
|
|
14
|
+
|
|
15
|
+
A plugin is **code that runs inside Open-WebUI with admin rights**, and `owpp deploy` uses an **admin
|
|
16
|
+
API key** to put it there. Whoever can change the plugins repository, or the repository a plugin's
|
|
17
|
+
`source:` points at, can therefore run code as an Open-WebUI admin, so a CI job that deploys on push
|
|
18
|
+
makes *write access to that repository* equivalent to *admin on Open-WebUI*. Everything below is
|
|
19
|
+
about keeping that explicit and narrow, not about making untrusted plugins safe.
|
|
20
|
+
|
|
21
|
+
## What runs where
|
|
22
|
+
|
|
23
|
+
| | Runs as | Notes |
|
|
24
|
+
|---|---|---|
|
|
25
|
+
| A plugin's `function.py`, `tool.py`, `shared.py` | Python in the Open-WebUI process, admin rights | Arbitrary code. Read it before you deploy it. |
|
|
26
|
+
| `assets/loader.js` | JavaScript in **every user's browser, on every page** | It is a fragment of the shared `/static/loader.js`: it can read and change the whole interface, including other users' content and their session. Treat it as full access to the UI. |
|
|
27
|
+
| `assets/custom.css` | CSS on every page | Can restyle or hide anything (a phishing-grade overlay is possible). |
|
|
28
|
+
| `owpp check`, `bundle`, `list` | Your machine | They parse and compile plugin code but never run it. `check` and `list` fetch `source:` files with `git`. |
|
|
29
|
+
| `owpp deploy` | Your machine / CI | Sends code to Open-WebUI with the admin key. |
|
|
30
|
+
|
|
31
|
+
## What `owpp` does to limit the damage
|
|
32
|
+
|
|
33
|
+
- **Pinned third-party code.** A `source:` is a git URL (https or ssh only) and a **full 40-character
|
|
34
|
+
commit SHA**, never a branch or tag; it is fetched by that SHA, shallow, into a scratch repository.
|
|
35
|
+
Upgrading means reviewing the upstream diff and changing the SHA.
|
|
36
|
+
- **Reproducible bundles.** A bundle depends only on the plugin folder and the pinned commits. In
|
|
37
|
+
particular **environment variables are never read while bundling or deploying**: `${NAME:-x}` in
|
|
38
|
+
`config.yaml` or `jobs:` is embedded as written and resolved inside the Open-WebUI container when
|
|
39
|
+
the plugin loads, so the machine that deploys cannot change the code or leak its environment into it.
|
|
40
|
+
A secret goes in a plugin as a reference, `${NAME}`, never as text.
|
|
41
|
+
- **It only deletes what it created.** Functions it deploys carry an ownership marker, and pruning acts
|
|
42
|
+
on that marker alone. A mass delete (more than half) is refused without `--force-prune`.
|
|
43
|
+
- **Signed in by default; public only on purpose.** Every route a plugin mounts requires a signed-in
|
|
44
|
+
Open-WebUI user, and the library refuses to mount one that does not (`plugin_mount`, including the
|
|
45
|
+
`static/` files). A route that needs more is marked on its handler (`user: PluginAdmin`,
|
|
46
|
+
`chat_id: WritableChat`); the checks are not hand-written. Serving people who are not signed in takes
|
|
47
|
+
`access="public"` on a mount of its own, or `static: {access: public}`, in exactly those words, and
|
|
48
|
+
**`owpp check` lists every one as a `note`** so a reviewer sees it. `owpp check` also refuses a
|
|
49
|
+
`function.py` that adds routes straight to the app, which would skip the guard, and refuses unknown or
|
|
50
|
+
removed keys in `plugin.yaml` (including the old `public:` and `routes:`) rather than ignoring a
|
|
51
|
+
setting that was meant to restrict something.
|
|
52
|
+
|
|
53
|
+
## Known limits
|
|
54
|
+
|
|
55
|
+
- **A public mount is open to the internet** (or to whatever can reach Open-WebUI). It gets no
|
|
56
|
+
session, no admin check and no rate limit from this library, and its handlers must treat every input as
|
|
57
|
+
hostile. Keep them few, small and idempotent, and check the `note` lines `owpp check` prints.
|
|
58
|
+
- **`plugin_mount(guard=...)` is the one exception to "every route needs a login".** It exists for an
|
|
59
|
+
API called from a sandboxed iframe, which sends no cookies (Excalidraw's editor). The route is
|
|
60
|
+
protected by a short-lived, signed token (`plugin_token`) that is scoped to the plugin and to one
|
|
61
|
+
subject and is only minted on a guarded page, but a holder of a token keeps access until it expires
|
|
62
|
+
even if their access to the chat is removed in the meantime.
|
|
63
|
+
- **Temporary chats** (`local:...`) have no stored record, so `WritableChat` and `ReadableChat` cannot
|
|
64
|
+
check ownership: any signed-in user who knows the id passes. Do not keep anything private in them.
|
|
65
|
+
- **A page opened with no session tries the no-input sign-ins first.** For a browser navigation the
|
|
66
|
+
guard calls Open-WebUI's own sign-in endpoint, inside the app, with the request's headers (as its
|
|
67
|
+
login page does), so a trusted-header or no-auth setup works without visiting the home page first;
|
|
68
|
+
otherwise the browser is sent to the login page. This inherits Open-WebUI's own assumption about
|
|
69
|
+
trusted headers: **your reverse proxy must strip a client-supplied trusted-identity header** and
|
|
70
|
+
Open-WebUI must not be reachable except through it. If it is, anyone can claim any identity at the
|
|
71
|
+
login page already, and now at plugin pages too.
|
|
72
|
+
- **Excalidraw and Inline Visualizer need Open-WebUI's "iframe Sandbox Allow Same Origin".** With it
|
|
73
|
+
on, the script of every artifact, not only theirs, runs with Open-WebUI's origin and can act as the
|
|
74
|
+
user. This is an Open-WebUI setting the plugins cannot narrow; enable them only where you trust what
|
|
75
|
+
the models put into artifacts. Why it is required, and why it is not worked around:
|
|
76
|
+
`docs/libraries.md`, "Pages in the Artifacts panel".
|
|
77
|
+
- **Third-party hosting is yours to secure.** Excalidraw loads its editor from esm.sh unless you
|
|
78
|
+
self-host it (see its README); either way the code runs in your users' browsers with no integrity
|
|
79
|
+
check.
|
|
80
|
+
- **Not tested against a live Open-WebUI.** The tests use stand-ins for its session check, chat access
|
|
81
|
+
and function table. Several behaviours are assumptions until verified (that `/api/v1/auths/signin`
|
|
82
|
+
accepts empty credentials under trusted-header auth, that the login page honours `?redirect=`, the
|
|
83
|
+
argument names Open-WebUI passes to an Event function's `event()`).
|
|
84
|
+
|
|
85
|
+
## For people deploying plugins
|
|
86
|
+
|
|
87
|
+
- Give CI a **dedicated admin user and API key** used for nothing else, stored as a secret, and rotate it.
|
|
88
|
+
- Restrict who can push to the plugins repository (and to any repository a `source:` names). Require
|
|
89
|
+
review for changes to `plugin.yaml`, `assets/` and anything that touches `ref:`.
|
|
90
|
+
- **Pin `owpp`** (`uvx owpp@0.1.0`) and pin the action to a tag or SHA: the runtime and libraries are
|
|
91
|
+
copied into what you deploy, so an upgrade changes your deployed code.
|
|
92
|
+
- Run `owpp deploy --dry-run` before the first deploy and read the plan; run `owpp check --strict`
|
|
93
|
+
in CI.
|
|
94
|
+
- Serve anything you self-host (such as Excalidraw's editor) over HTTPS.
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Open-WebUI plugin protocol
|
|
2
|
+
|
|
3
|
+
A way to write, test and deploy Open-WebUI **plugins** from a git repository: a function (the parent) plus an optional tool and skills, installed and removed together, with shared libraries for the things every plugin ends up needing (routes, background jobs, per-chat data, static files).
|
|
4
|
+
|
|
5
|
+
Open-WebUI stores a function or tool as **one code blob** and cannot import siblings. This protocol is the layer that makes a folder of files behave like one plugin:
|
|
6
|
+
|
|
7
|
+
1. A **plugin** is a folder with a `plugin.yaml` manifest ([plugin format](plugin-format.md)).
|
|
8
|
+
2. A **bundler** turns the folder into the single file Open-WebUI stores, in a fixed order, and can pull function, tool and skill code from any git repo at a pinned commit ([bundling](bundling.md)).
|
|
9
|
+
3. A **runtime**, appended to the bundle, makes the function the parent: enabling it installs its tool and skills, disabling or deleting it removes them ([runtime](runtime.md)).
|
|
10
|
+
4. **Libraries** are vendored Python blocks a manifest lists under `include:` ([libraries](libraries.md)).
|
|
11
|
+
5. A **CLI and a deploy script** check, bundle and deploy one plugin or all of them, from a laptop or CI ([tooling](tooling.md)).
|
|
12
|
+
|
|
13
|
+
## Reading order
|
|
14
|
+
|
|
15
|
+
| If you want to... | Read |
|
|
16
|
+
| --- | --- |
|
|
17
|
+
| Write a plugin | [authoring guide](authoring.md), then [plugin format](plugin-format.md) |
|
|
18
|
+
| Know exactly what ends up in the deployed file | [bundling](bundling.md) |
|
|
19
|
+
| Understand install/remove, valves and sync | [runtime](runtime.md) |
|
|
20
|
+
| Use routes, jobs, chat data, static files and templates | [libraries](libraries.md) |
|
|
21
|
+
| Unit-test a plugin against a mock Open-WebUI | [testing](testing.md) |
|
|
22
|
+
| Test, deploy, set up CI | [tooling](tooling.md) |
|
|
23
|
+
| Use it in your repository, or move existing functions over | [adopting](adopting.md) |
|
|
24
|
+
| Know why it is the way it is | [decisions](decisions.md) |
|
|
25
|
+
| Review a change, or repeat the tests by hand | [reviewing](reviewing.md), [test catalogue](reference/test-catalogue.md) |
|
|
26
|
+
| Make a change to this repository | [making a change](contributing.md) |
|
|
27
|
+
| See every change so far | [audit trail](project/audit-trail.md), [changelog](../CHANGELOG.md) |
|
|
28
|
+
| Know what you are trusting, and how to report a problem | [security](../SECURITY.md) |
|
|
29
|
+
|
|
30
|
+
## At a glance
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
plugins/<id>/
|
|
34
|
+
plugin.yaml function: (parent) / tool: / skills: / source: / include: / public:
|
|
35
|
+
function.py the function's code (a Filter, Event, Action or Pipe)
|
|
36
|
+
tool.py optional tool code
|
|
37
|
+
shared.py optional code both need, placed in front of each
|
|
38
|
+
skills/<id>/ optional skills, whole folders
|
|
39
|
+
static/ optional files served at /<id>/<path>
|
|
40
|
+
templates/ optional files the function renders itself (never served)
|
|
41
|
+
tests/ optional unit tests, run by `owpp test` (never deployed)
|
|
42
|
+
README.md what it is, how to test it, how to deploy it
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
```yaml
|
|
46
|
+
# plugin.yaml
|
|
47
|
+
function:
|
|
48
|
+
title: My Plugin
|
|
49
|
+
author: me
|
|
50
|
+
version: 1.0.0
|
|
51
|
+
global: true # filters and actions only
|
|
52
|
+
include: [routes, chat_data]
|
|
53
|
+
tool: { id: my_plugin, access: public }
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
owpp list # plugins and their function type
|
|
58
|
+
owpp check my_plugin # bundle, compile, find undefined names
|
|
59
|
+
owpp test my_plugin # its tests/, against a mock Open-WebUI
|
|
60
|
+
owpp deploy --only my_plugin --dry-run
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Guarantees
|
|
64
|
+
|
|
65
|
+
- **Reproducible.** A bundle depends only on the folder and the pinned git commits it names. Libraries are vendored byte for byte.
|
|
66
|
+
- **Reviewed upgrades.** Remote code is referenced by full commit SHA, never a branch or tag, because it runs inside Open-WebUI with admin rights.
|
|
67
|
+
- **Owned objects only.** The deploy marks what it creates (`meta.managed_by`) and only ever updates or deletes those. Hand-made functions are never touched.
|
|
68
|
+
- **No surprises on disable.** Whatever a function installed (tools, skills, routes, background jobs) goes away or stops when it is disabled.
|
|
69
|
+
|
|
70
|
+
## Status and limits
|
|
71
|
+
|
|
72
|
+
Written against Open-WebUI **v0.13.4**. API shapes (skills as `files` lists, tool valves, `Functions.get_function_valves_by_id`) were read from that source, and the libraries are tested against stubbed Open-WebUI modules, not a live instance. Known gaps are collected in [decisions](decisions.md#not-done-yet).
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Adopting the protocol
|
|
2
|
+
|
|
3
|
+
## A new repository
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
mkdir my-plugins && cd my-plugins && git init
|
|
7
|
+
uvx owpp init hello --type event
|
|
8
|
+
uvx owpp check
|
|
9
|
+
OPEN_WEBUI_URL=https://chat.example.com OPEN_WEBUI_API_KEY=sk-... uvx owpp deploy --dry-run
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
Then add the [GitHub Action](tooling.md#github-action).
|
|
13
|
+
|
|
14
|
+
## Existing functions pasted into the UI
|
|
15
|
+
|
|
16
|
+
1. Make a folder per function: `plugins/<id>/function.py`, with the docstring header moved into `plugin.yaml` under `function:` (or keep a flat `plugins/<id>.py` with its header).
|
|
17
|
+
2. The id must equal the id the function already has in Open-WebUI, or the deploy will create a second copy. Ids cannot contain hyphens.
|
|
18
|
+
3. The first deploy **updates** a same-id function and marks it as managed. Its valves and active/global state are kept.
|
|
19
|
+
4. Replace copied helpers with libraries (`routes`, `jobs`, `chat_data`, `static`, `templates`) as you go; `owpp check` reports anything left undefined.
|
|
20
|
+
|
|
21
|
+
## Third-party functions
|
|
22
|
+
|
|
23
|
+
Prefer a pinned `source:` (git URL plus a full commit SHA) over copying the file in: upgrades become a reviewed change of the SHA. Review the upstream diff before moving it; this code runs with admin rights.
|
|
24
|
+
|
|
25
|
+
## Keep your existing marker
|
|
26
|
+
|
|
27
|
+
If you used this protocol before it had its own repository (the deploy script inside another repo), your functions carry that repo's marker. Pass it, or every function will look hand-made and stop being pruned:
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
OWPP_MANAGED_BY='git:owner/repo:path' uvx owpp deploy
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
or `managed-by:` in the action. The description note changed to a generic wording, so the first deploy with this package updates each function once; that is expected.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Domain Docs
|
|
2
|
+
|
|
3
|
+
How the engineering skills should consume this repo's domain documentation when exploring the codebase.
|
|
4
|
+
|
|
5
|
+
## Before exploring, read these
|
|
6
|
+
|
|
7
|
+
- **`GLOSSARY.md`** at the repo root, or
|
|
8
|
+
- **`GLOSSARY-MAP.md`** at the repo root if it exists: it points at one `GLOSSARY.md` per context. Read each one relevant to the topic.
|
|
9
|
+
- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
|
|
10
|
+
|
|
11
|
+
If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
|
|
12
|
+
|
|
13
|
+
## File structure
|
|
14
|
+
|
|
15
|
+
Single-context repo (most repos):
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
/
|
|
19
|
+
├── GLOSSARY.md
|
|
20
|
+
├── docs/adr/
|
|
21
|
+
│ ├── 0001-event-sourced-orders.md
|
|
22
|
+
│ └── 0002-postgres-for-write-model.md
|
|
23
|
+
└── src/
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Multi-context repo (presence of `GLOSSARY-MAP.md` at the root):
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
/
|
|
30
|
+
├── GLOSSARY-MAP.md
|
|
31
|
+
├── docs/adr/ ← system-wide decisions
|
|
32
|
+
└── src/
|
|
33
|
+
├── ordering/
|
|
34
|
+
│ ├── GLOSSARY.md
|
|
35
|
+
│ └── docs/adr/ ← context-specific decisions
|
|
36
|
+
└── billing/
|
|
37
|
+
├── GLOSSARY.md
|
|
38
|
+
└── docs/adr/
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Use the glossary's vocabulary
|
|
42
|
+
|
|
43
|
+
When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `GLOSSARY.md`. Don't drift to synonyms the glossary explicitly avoids.
|
|
44
|
+
|
|
45
|
+
If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
|
|
46
|
+
|
|
47
|
+
## Flag ADR conflicts
|
|
48
|
+
|
|
49
|
+
If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
|
|
50
|
+
|
|
51
|
+
> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_
|