owui-deploy 0.1.2__py3-none-any.whl
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.
- owui_deploy/__init__.py +10 -0
- owui_deploy/__main__.py +5 -0
- owui_deploy/applier.py +96 -0
- owui_deploy/cli.py +324 -0
- owui_deploy/client.py +101 -0
- owui_deploy/config.py +190 -0
- owui_deploy/errors.py +41 -0
- owui_deploy/fake.py +353 -0
- owui_deploy/frontmatter.py +28 -0
- owui_deploy/i18n.py +60 -0
- owui_deploy/lint.py +246 -0
- owui_deploy/locales/en.json +107 -0
- owui_deploy/locales/ko.json +107 -0
- owui_deploy/normalize.py +22 -0
- owui_deploy/planner.py +124 -0
- owui_deploy/pull.py +100 -0
- owui_deploy/render.py +111 -0
- owui_deploy-0.1.2.dist-info/METADATA +374 -0
- owui_deploy-0.1.2.dist-info/RECORD +22 -0
- owui_deploy-0.1.2.dist-info/WHEEL +4 -0
- owui_deploy-0.1.2.dist-info/entry_points.txt +3 -0
- owui_deploy-0.1.2.dist-info/licenses/LICENSE +21 -0
owui_deploy/pull.py
ADDED
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
"""Export the server's Tools and Functions into files (valves values are never written)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
from dataclasses import dataclass, field
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
|
|
9
|
+
from .client import OpenWebUIClient
|
|
10
|
+
from .config import Config, derive_description, derive_name, load_config, default_config
|
|
11
|
+
from .normalize import normalize
|
|
12
|
+
from .planner import remote_description
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@dataclass
|
|
16
|
+
class PullResult:
|
|
17
|
+
written: list[str] = field(default_factory=list)
|
|
18
|
+
unchanged: list[str] = field(default_factory=list)
|
|
19
|
+
kept: list[str] = field(default_factory=list) # local file differs; not overwritten without --force
|
|
20
|
+
invalid_ids: list[str] = field(default_factory=list)
|
|
21
|
+
valves_dropped: int = 0
|
|
22
|
+
config_written: Path | None = None
|
|
23
|
+
config_kept: Path | None = None
|
|
24
|
+
# (kind, id, field 'active'|'global', config value, server value); rendered by the CLI
|
|
25
|
+
state_differences: list[tuple[str, str, str, bool, bool]] = field(default_factory=list)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def _toml_str(value: str) -> str:
|
|
29
|
+
return json.dumps(value, ensure_ascii=False)
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def render_config(url: str | None, entries: dict[str, list[dict]]) -> str:
|
|
33
|
+
"""Write a fresh ``owui-deploy.toml`` that reproduces the pulled server state (plan exits 0)."""
|
|
34
|
+
lines = ["[server]", f"url = {_toml_str(url or 'http://localhost:8080')}", "", "[paths]",
|
|
35
|
+
'tools = "tools"', 'functions = "functions"', "", "[defaults]", "active = true", "global = false", ""]
|
|
36
|
+
for section, items in (("tools", entries["tool"]), ("functions", entries["function"])):
|
|
37
|
+
for entry in sorted(items, key=lambda e: e["id"]):
|
|
38
|
+
content = entry.get("content") or ""
|
|
39
|
+
override = {}
|
|
40
|
+
if entry.get("name") != derive_name(entry["id"], content, {}):
|
|
41
|
+
override["name"] = _toml_str(entry.get("name") or entry["id"])
|
|
42
|
+
if remote_description(entry) != derive_description(content, {}):
|
|
43
|
+
override["description"] = _toml_str(remote_description(entry))
|
|
44
|
+
if not entry.get("is_active"):
|
|
45
|
+
override["active"] = "false"
|
|
46
|
+
if section == "functions" and entry.get("is_global"):
|
|
47
|
+
override["global"] = "true"
|
|
48
|
+
if override:
|
|
49
|
+
lines.append(f"[{section}.{entry['id']}]")
|
|
50
|
+
lines.extend(f"{k} = {v}" for k, v in override.items())
|
|
51
|
+
lines.append("")
|
|
52
|
+
return "\n".join(lines).rstrip() + "\n"
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def pull(client: OpenWebUIClient, out: Path, config_path: Path, url: str | None, force: bool = False) -> PullResult:
|
|
56
|
+
result = PullResult()
|
|
57
|
+
cfg: Config = load_config(config_path) if config_path.is_file() else default_config(out)
|
|
58
|
+
exported = {kind: client.export_all(kind) for kind in ("tool", "function")}
|
|
59
|
+
|
|
60
|
+
for kind, folder in (("tool", cfg.tools_dir), ("function", cfg.functions_dir)):
|
|
61
|
+
for entry in exported[kind]:
|
|
62
|
+
if "valves" in entry: # a server that ignores "no valves requested": drop, never write
|
|
63
|
+
result.valves_dropped += 1
|
|
64
|
+
item_id = entry["id"]
|
|
65
|
+
if not item_id.isidentifier():
|
|
66
|
+
result.invalid_ids.append(item_id)
|
|
67
|
+
continue
|
|
68
|
+
target = folder / f"{item_id}.py"
|
|
69
|
+
label = f"{kind}:{item_id}"
|
|
70
|
+
content = entry.get("content") or ""
|
|
71
|
+
if target.exists():
|
|
72
|
+
existing = target.read_text(encoding="utf-8")
|
|
73
|
+
if normalize(existing) == content:
|
|
74
|
+
result.unchanged.append(label)
|
|
75
|
+
continue
|
|
76
|
+
if not force:
|
|
77
|
+
result.kept.append(label)
|
|
78
|
+
continue
|
|
79
|
+
folder.mkdir(parents=True, exist_ok=True)
|
|
80
|
+
target.write_text(content, encoding="utf-8")
|
|
81
|
+
result.written.append(label)
|
|
82
|
+
|
|
83
|
+
if config_path.is_file():
|
|
84
|
+
result.config_kept = config_path
|
|
85
|
+
section = {"tool": "tools", "function": "functions"}
|
|
86
|
+
for kind in ("tool", "function"):
|
|
87
|
+
for entry in exported[kind]:
|
|
88
|
+
override = cfg.overrides[section[kind]].get(entry["id"], {})
|
|
89
|
+
want_active = override.get("active", cfg.default_active)
|
|
90
|
+
if bool(entry.get("is_active")) != want_active:
|
|
91
|
+
result.state_differences.append((kind, entry["id"], "active", want_active, bool(entry.get("is_active"))))
|
|
92
|
+
if kind == "function":
|
|
93
|
+
want_global = override.get("global", cfg.default_global)
|
|
94
|
+
if bool(entry.get("is_global")) != want_global:
|
|
95
|
+
result.state_differences.append((kind, entry["id"], "global", want_global, bool(entry.get("is_global"))))
|
|
96
|
+
else:
|
|
97
|
+
config_path.parent.mkdir(parents=True, exist_ok=True)
|
|
98
|
+
config_path.write_text(render_config(url, exported), encoding="utf-8")
|
|
99
|
+
result.config_written = config_path
|
|
100
|
+
return result
|
owui_deploy/render.py
ADDED
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
"""Human readable and JSON output for lint results and plans."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
|
|
7
|
+
from .applier import ApplyResult
|
|
8
|
+
from .i18n import t
|
|
9
|
+
from .lint import Finding
|
|
10
|
+
from .planner import Plan
|
|
11
|
+
|
|
12
|
+
_SYMBOL = {"create": "+", "update": "~", "state": "~", "delete": "-", "unmanaged": "?", "skip": "!"}
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def finding_text(finding: Finding) -> str:
|
|
16
|
+
message = t(finding.msg_key, **finding.params)
|
|
17
|
+
return f"{finding.path}:{finding.line} {finding.code} {finding.level}: {message}"
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def lint_summary(findings: list[Finding], files: int) -> str:
|
|
21
|
+
errors = sum(1 for f in findings if f.level == "error")
|
|
22
|
+
warnings = sum(1 for f in findings if f.level == "warning")
|
|
23
|
+
if not findings:
|
|
24
|
+
return t("lint.clean", files=files)
|
|
25
|
+
return t("lint.summary", files=files, errors=errors, warnings=warnings)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def lint_json(findings: list[Finding], files: int) -> str:
|
|
29
|
+
payload = {
|
|
30
|
+
"findings": [
|
|
31
|
+
{
|
|
32
|
+
"path": f.path,
|
|
33
|
+
"line": f.line,
|
|
34
|
+
"col": f.col,
|
|
35
|
+
"code": f.code,
|
|
36
|
+
"level": f.level,
|
|
37
|
+
"message": t(f.msg_key, **f.params),
|
|
38
|
+
}
|
|
39
|
+
for f in findings
|
|
40
|
+
],
|
|
41
|
+
"summary": {
|
|
42
|
+
"files": files,
|
|
43
|
+
"errors": sum(1 for f in findings if f.level == "error"),
|
|
44
|
+
"warnings": sum(1 for f in findings if f.level == "warning"),
|
|
45
|
+
},
|
|
46
|
+
}
|
|
47
|
+
return json.dumps(payload, ensure_ascii=False, indent=2)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def _field_names(fields: list[str]) -> str:
|
|
51
|
+
return ", ".join(t(f"field.{name}") for name in fields)
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def change_line(change, width: int = 0) -> str: # noqa: ANN001 - planner.Change
|
|
55
|
+
symbol = _SYMBOL[change.action]
|
|
56
|
+
head = f"{symbol} {change.action:<9} {change.kind:<8} {change.id:<{width}}"
|
|
57
|
+
if change.action in ("create", "update"):
|
|
58
|
+
return f"{head} ({_field_names(change.fields)})"
|
|
59
|
+
if change.action == "state":
|
|
60
|
+
parts = [f"{name}: {str(old).lower()} -> {str(new).lower()}" for name, (old, new) in change.detail.items()]
|
|
61
|
+
return f"{head} ({', '.join(parts)})"
|
|
62
|
+
if change.action == "unmanaged":
|
|
63
|
+
return f"{head} ({t('plan.unmanaged_note')})"
|
|
64
|
+
if change.action == "delete":
|
|
65
|
+
return f"{head} ({t('plan.delete_note')})"
|
|
66
|
+
reason = t(change.detail["reason_key"], **change.detail["params"])
|
|
67
|
+
return f"{head} ({reason})"
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def summary_line(plan: Plan) -> str:
|
|
71
|
+
counts = plan.summary
|
|
72
|
+
parts = [t(f"plan.part.{name}", n=counts[name]) for name in ("create", "update", "state", "delete", "unmanaged", "skipped") if counts[name]]
|
|
73
|
+
if not parts:
|
|
74
|
+
return t("plan.none")
|
|
75
|
+
return t("plan.summary", parts=", ".join(parts))
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def plan_text(plan: Plan, show_diff: bool = False) -> str:
|
|
79
|
+
width = max((len(c.id) for c in plan.changes), default=0)
|
|
80
|
+
lines = [change_line(c, width) for c in plan.changes]
|
|
81
|
+
if show_diff:
|
|
82
|
+
for change in plan.changes:
|
|
83
|
+
if change.diff:
|
|
84
|
+
lines.append("")
|
|
85
|
+
lines.append(change.diff.rstrip("\n"))
|
|
86
|
+
if lines:
|
|
87
|
+
lines.append("")
|
|
88
|
+
lines.append(summary_line(plan))
|
|
89
|
+
return "\n".join(lines)
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def plan_json(plan: Plan, mock: bool, server: str, show_diff: bool = False) -> str:
|
|
93
|
+
changes = []
|
|
94
|
+
for c in plan.changes:
|
|
95
|
+
entry = {"kind": c.kind, "id": c.id, "action": c.action, "fields": c.fields}
|
|
96
|
+
if c.detail and c.action == "state":
|
|
97
|
+
entry["detail"] = c.detail
|
|
98
|
+
if c.action == "skip":
|
|
99
|
+
entry["detail"] = {"reason": t(c.detail["reason_key"], **c.detail["params"])}
|
|
100
|
+
if show_diff and c.diff:
|
|
101
|
+
entry["diff"] = c.diff
|
|
102
|
+
changes.append(entry)
|
|
103
|
+
payload = {"server": server, "mock": mock, "changes": changes, "summary": plan.summary}
|
|
104
|
+
return json.dumps(payload, ensure_ascii=False, indent=2)
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def apply_lines(result: ApplyResult) -> list[str]:
|
|
108
|
+
lines = [t("apply.done_line", action=a, kind=k, id=i) for a, k, i in result.done]
|
|
109
|
+
for r in result.rejected:
|
|
110
|
+
lines.append(t("apply.rejected_line", action=r.action, kind=r.kind, id=r.id, status=r.status, detail=r.detail))
|
|
111
|
+
return lines
|
|
@@ -0,0 +1,374 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: owui-deploy
|
|
3
|
+
Version: 0.1.2
|
|
4
|
+
Summary: Lint, plan and apply Open WebUI Tools and Functions from a git folder (no code execution, idempotent, CI-friendly exit codes).
|
|
5
|
+
Keywords: open-webui,openwebui,llm,deploy,lint,gitops,cli
|
|
6
|
+
Author: LeeGyeongPil
|
|
7
|
+
Author-email: LeeGyeongPil <50697071+LeeGyeongPil@users.noreply.github.com>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
18
|
+
Requires-Dist: httpx==0.28.1
|
|
19
|
+
Requires-Python: >=3.11
|
|
20
|
+
Project-URL: Homepage, https://github.com/LeeGyeongPil/owui-deploy
|
|
21
|
+
Project-URL: Issues, https://github.com/LeeGyeongPil/owui-deploy/issues
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
|
|
24
|
+
# owui-deploy
|
|
25
|
+
|
|
26
|
+
**English** | [한국어](https://github.com/LeeGyeongPil/owui-deploy/blob/v0.1.2/README.ko.md)
|
|
27
|
+
|
|
28
|
+
Keep your Open WebUI Tools and Functions (Filter, Pipe, Action) in a git folder, check them before upload, see what would change on the server, and apply the changes so that running the same command twice gives the same result. A `lint`, `plan`, `apply` and `pull` command line tool, with no code execution on your machine.
|
|
29
|
+
|
|
30
|
+

|
|
31
|
+
*`owui-deploy lint` finds problems that the server would only report as "Error creating function". Exit code 1 means problems were found.*
|
|
32
|
+
|
|
33
|
+
## Who it is for
|
|
34
|
+
|
|
35
|
+
- You run Open WebUI for a team or at home and paste Tool and Function code into the admin screen by hand.
|
|
36
|
+
- You want a pull request to show what will change on the server, and a check that nobody edited a Function in the browser (drift).
|
|
37
|
+
- You keep a collection of Functions in a repository and want the same version on a dev and a prod instance.
|
|
38
|
+
|
|
39
|
+
Think of Terraform: the folder is the source of truth, `plan` shows the difference, `apply` makes the server match.
|
|
40
|
+
|
|
41
|
+
## Install
|
|
42
|
+
|
|
43
|
+
Needs Python 3.11 or newer. [uv](https://docs.astral.sh/uv/) is the easiest way to get it: `curl -LsSf https://astral.sh/uv/install.sh | sh`. On a minimal Linux image you also need `git` (`apt-get install -y git`).
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
uv tool install git+https://github.com/LeeGyeongPil/owui-deploy
|
|
47
|
+
owui-deploy --version
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
To try it from a clone instead (this is what the examples below use):
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
git clone https://github.com/LeeGyeongPil/owui-deploy
|
|
54
|
+
cd owui-deploy
|
|
55
|
+
uv run owui-deploy --version
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Quick start (no server needed)
|
|
59
|
+
|
|
60
|
+
`--fake` switches to a **practice mock**: a small built-in model of Open WebUI 0.13.3 that keeps its state in a JSON file next to your config. It is not a real Open WebUI, and it never runs your code (it only reads the class names with `ast`). Use it to learn the commands. Use a real server to verify real behavior. A real server can be slow to start (installing Open WebUI took about 76 seconds and 2 GB in our probe, and start-up another minute), which is why the practice mock exists.
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
uv run owui-deploy plan --config examples/demo/owui-deploy.toml --fake
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
Server: fake server (practice mock, not a real Open WebUI). State file: examples/demo/.owui-deploy-fake.json
|
|
68
|
+
+ create function shout_action (content, name, description, active)
|
|
69
|
+
~ update tool clock (content, description)
|
|
70
|
+
~ state function pii_mask (active: false -> true, global: false -> true)
|
|
71
|
+
? unmanaged function legacy_filter (only on the server; left alone without --prune)
|
|
72
|
+
|
|
73
|
+
Plan: 1 to create, 1 to update, 1 to change state, 1 unmanaged.
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+

|
|
77
|
+
*The practice mock starts with a few items so the plan has something to show. The exit code is 1 because there are differences.*
|
|
78
|
+
|
|
79
|
+
How to read it:
|
|
80
|
+
|
|
81
|
+
| Mark | Meaning |
|
|
82
|
+
|---|---|
|
|
83
|
+
| `+ create` | In your folder, not on the server yet. |
|
|
84
|
+
| `~ update` | On both, but the code or description differs. |
|
|
85
|
+
| `~ state` | The on/off (`active`) or "for all models" (`global`) switch differs. |
|
|
86
|
+
| `? unmanaged` | Only on the server. Left alone unless you pass `--prune`. It does not make the exit code 1. |
|
|
87
|
+
|
|
88
|
+
Now apply it, twice:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
uv run owui-deploy apply --yes --config examples/demo/owui-deploy.toml --fake
|
|
92
|
+
uv run owui-deploy apply --yes --config examples/demo/owui-deploy.toml --fake
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
```
|
|
96
|
+
Server: fake server (practice mock, not a real Open WebUI). State file: examples/demo/.owui-deploy-fake.json
|
|
97
|
+
+ create function shout_action (content, name, description, active)
|
|
98
|
+
~ update tool clock (content, description)
|
|
99
|
+
~ state function pii_mask (active: false -> true, global: false -> true)
|
|
100
|
+
? unmanaged function legacy_filter (only on the server; left alone without --prune)
|
|
101
|
+
|
|
102
|
+
Plan: 1 to create, 1 to update, 1 to change state, 1 unmanaged.
|
|
103
|
+
applied: create function shout_action
|
|
104
|
+
applied: toggle function shout_action
|
|
105
|
+
applied: update tool clock
|
|
106
|
+
applied: toggle function pii_mask
|
|
107
|
+
applied: toggle_global function pii_mask
|
|
108
|
+
Apply: 5 requests applied, 0 rejected.
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Second run:
|
|
112
|
+
|
|
113
|
+
```
|
|
114
|
+
Server: fake server (practice mock, not a real Open WebUI). State file: examples/demo/.owui-deploy-fake.json
|
|
115
|
+
? unmanaged function legacy_filter (only on the server; left alone without --prune)
|
|
116
|
+
|
|
117
|
+
Plan: 1 unmanaged.
|
|
118
|
+
No changes.
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+

|
|
122
|
+
*The second run sends no write requests.*
|
|
123
|
+
|
|
124
|
+
Apply created `examples/demo/.owui-deploy-fake.json` (ignored by git). Delete it to start over: `rm examples/demo/.owui-deploy-fake.json`.
|
|
125
|
+
|
|
126
|
+
## Connect to your Open WebUI
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
export OWUI_URL=http://localhost:8080
|
|
130
|
+
export OWUI_TOKEN=<admin token>
|
|
131
|
+
owui-deploy plan
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
- The token is never read from the config file, only from `OWUI_TOKEN`.
|
|
135
|
+
- An admin **login token (JWT)** works: sign in with `POST /api/v1/auths/signin` (JSON body with `email` and `password`) and take `token` from the answer.
|
|
136
|
+
- An **API key** also works, but Open WebUI only lets you create one when the server runs with `ENABLE_API_KEYS=true`. Without that, use the JWT.
|
|
137
|
+
- The server URL can also come from `server.url` in the config file or `--url` (priority: `--url`, then `OWUI_URL`, then the file).
|
|
138
|
+
- `apply` makes the server run your code. Read [Security notes](#security-notes) before you point it at a real server.
|
|
139
|
+
|
|
140
|
+
## Commands
|
|
141
|
+
|
|
142
|
+
| Command | What it does | Example |
|
|
143
|
+
|---|---|---|
|
|
144
|
+
| `lint [PATH]` | Static checks, no code is executed. `--json` for machines, `--strict` makes warnings exit 1. | `owui-deploy lint examples/broken` |
|
|
145
|
+
| `plan` | Shows what `apply` would change. `--diff` adds a unified diff, `--json` prints JSON, `--prune` shows server-only items as deletions, `--fail-on-unmanaged` exits 1 for them. | `owui-deploy plan --diff` |
|
|
146
|
+
| `apply` | Creates and updates, switches state only when it differs, deletes only with `--prune`. Asks first; `--yes` skips the question (required when stdin is not a terminal). `--message` is stored in the server history (default: the git short hash). | `owui-deploy apply --yes` |
|
|
147
|
+
| `pull --out DIR` | Downloads Tools and Functions into files and creates `DIR/owui-deploy.toml` if missing. Does not overwrite files that differ from the server unless `--force`. | `owui-deploy pull --out ./owui` |
|
|
148
|
+
|
|
149
|
+
Options differ per command (all of them take `--lang en|ko`):
|
|
150
|
+
|
|
151
|
+
| Command | Options |
|
|
152
|
+
|---|---|
|
|
153
|
+
| `plan`, `apply` | `--config PATH` (default `./owui-deploy.toml`), `--url`, `--fake`, `--lang` |
|
|
154
|
+
| `pull` | `--out DIR`, `--url`, `--fake`, `--force`, `--lang` (the config file is `DIR/owui-deploy.toml`) |
|
|
155
|
+
| `lint` | `[PATH]`, `--config PATH`, `--json`, `--strict`, `--lang` (needs no server, so no `--url` or `--fake`) |
|
|
156
|
+
|
|
157
|
+
Exit codes:
|
|
158
|
+
|
|
159
|
+
| Code | Meaning |
|
|
160
|
+
|---|---|
|
|
161
|
+
| 0 | No difference, no problem. |
|
|
162
|
+
| 1 | A difference or problem was found: plan drift, lint error, or the server rejected an item. |
|
|
163
|
+
| 2 | Tool error: missing config or token, cannot connect, 401/403, wrong usage. |
|
|
164
|
+
|
|
165
|
+
### See the content difference
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
uv run owui-deploy plan --config examples/demo/owui-deploy.toml --fake --diff
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+

|
|
172
|
+
*`--diff` shows the code difference. The `from utils.misc` line in `pii_mask` is not listed as a difference, see "How plan stays honest".*
|
|
173
|
+
|
|
174
|
+
### Pull an existing server into git
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
uv run owui-deploy pull --fake --out pulled
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
```
|
|
181
|
+
Server: fake server (practice mock, not a real Open WebUI). State file: pulled/.owui-deploy-fake.json
|
|
182
|
+
wrote tool:clock
|
|
183
|
+
wrote function:pii_mask
|
|
184
|
+
wrote function:legacy_filter
|
|
185
|
+
Pull: 3 written, 0 unchanged, 0 kept.
|
|
186
|
+
wrote config file pulled/owui-deploy.toml
|
|
187
|
+
Valves (settings and secrets) are not exported; they stay on the server.
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+

|
|
191
|
+
*Valves (settings that can hold API keys) are never written to files.*
|
|
192
|
+
|
|
193
|
+
The result is `pulled/tools/clock.py`, `pulled/functions/*.py` and `pulled/owui-deploy.toml`. Clean up with `rm -r pulled`.
|
|
194
|
+
|
|
195
|
+
## Config file
|
|
196
|
+
|
|
197
|
+
`owui-deploy.toml`, paths are relative to the file. The id of an item is its file name without `.py`.
|
|
198
|
+
|
|
199
|
+
```toml
|
|
200
|
+
[server]
|
|
201
|
+
url = "http://localhost:8080" # OWUI_URL overrides it, --url overrides both
|
|
202
|
+
|
|
203
|
+
[paths]
|
|
204
|
+
tools = "tools"
|
|
205
|
+
functions = "functions"
|
|
206
|
+
|
|
207
|
+
[defaults]
|
|
208
|
+
active = true # deploy everything switched on unless said otherwise
|
|
209
|
+
global = false
|
|
210
|
+
|
|
211
|
+
[functions.pii_mask]
|
|
212
|
+
global = true # a Filter that should run for every model
|
|
213
|
+
|
|
214
|
+
[functions.shout_action]
|
|
215
|
+
name = "Shout"
|
|
216
|
+
description = "Add a button that repeats the last answer in capital letters"
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Config keys are case-insensitive (matched in lowercase, like server ids), and two keys that differ only in case are a config error.
|
|
220
|
+
|
|
221
|
+
The name comes from the config, else the `title:` in the file's first docstring, else the id. A working copy is in `examples/demo/`.
|
|
222
|
+
|
|
223
|
+
| Variable | Use |
|
|
224
|
+
|---|---|
|
|
225
|
+
| `OWUI_URL` | Server address. |
|
|
226
|
+
| `OWUI_TOKEN` | Admin JWT or API key. |
|
|
227
|
+
| `OWUI_DEPLOY_LANG` | `en` or `ko`. |
|
|
228
|
+
|
|
229
|
+
## Lint rules
|
|
230
|
+
|
|
231
|
+
The server answers a broken upload with one line (`[ERROR: Error creating function]`) and the reason only appears in its log. `lint` reads the files with Python's `ast` and reports the reason, with file, line and rule code.
|
|
232
|
+
|
|
233
|
+
| Code | Level | What it finds |
|
|
234
|
+
|---|---|---|
|
|
235
|
+
| OWD001 | error | Syntax error. |
|
|
236
|
+
| OWD002 | error | No `Tools` class in a tool file, or no Pipe/Filter/Action/Event class in a function file. |
|
|
237
|
+
| OWD003 | warning | Several Function classes in one file. The server uses one (Pipe first). |
|
|
238
|
+
| OWD004 | error / warning | File name is not a valid id (error), or contains capitals (warning). |
|
|
239
|
+
| OWD005 | warning | First line is not exactly `"""`, so the server ignores the frontmatter; or `title`/`version` missing. |
|
|
240
|
+
| OWD006 | error | `Valves` or `UserValves` does not inherit from pydantic `BaseModel`. |
|
|
241
|
+
| OWD007 | warning | `from utils`, `from apps`, `from main` or `from config` imports, which the server rewrites. |
|
|
242
|
+
| OWD008 | warning | Public Tool method without docstring or type hints (the model reads them as the tool description). |
|
|
243
|
+
| OWD009 | warning | A secret-looking valve (`api_key`, `token`, ...) with a non-empty default in the source. |
|
|
244
|
+
|
|
245
|
+
## How plan stays honest
|
|
246
|
+
|
|
247
|
+
```mermaid
|
|
248
|
+
flowchart LR
|
|
249
|
+
F["folder: tools/ functions/"] --> L["lint (ast)"]
|
|
250
|
+
F --> N["normalize like the server"]
|
|
251
|
+
S["server (export)"] --> P["plan"]
|
|
252
|
+
N --> P
|
|
253
|
+
P --> A["apply"]
|
|
254
|
+
A -->|"create / update / toggle if differs / delete only with --prune"| S
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
`plan` compares your files with the server, `apply` changes only what differs. The server has four traps that the tool handles in code (observed on Open WebUI 0.13.3):
|
|
258
|
+
|
|
259
|
+
1. **Import rewriting.** The server rewrites `from utils...` to `from open_webui.utils...` when saving, so a naive diff never reaches zero. `plan` applies the same rewrite to your file before comparing. `lint` warns with OWD007.
|
|
260
|
+
2. **The toggle endpoint flips.** Calling it twice turns the Function off again. `apply` reads the current state right before and calls it only when the state differs.
|
|
261
|
+
3. **New Functions start inactive.** After creating, `apply` switches them to the state you declared.
|
|
262
|
+
4. **`/functions/sync` deletes silently.** Syncing a partial list deletes everything else, so this tool never calls it. Deleting needs the explicit `--prune`.
|
|
263
|
+
|
|
264
|
+
The practice mock reproduces these four behaviors, and the tests compare it with responses recorded from a real 0.13.3 server (`tests/fixtures/owui-0.13.3/`).
|
|
265
|
+
|
|
266
|
+
## Use in CI
|
|
267
|
+
|
|
268
|
+
```bash
|
|
269
|
+
owui-deploy plan --json > plan.json
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
Exit code 0: nothing to do. 1: the server differs from the folder. 2: setup problem (token, URL, config). Output of the same command on the practice mock after an apply (the `Server:` line goes to the other stream):
|
|
273
|
+
|
|
274
|
+
```json
|
|
275
|
+
{
|
|
276
|
+
"server": "fake (examples/demo/.owui-deploy-fake.json)",
|
|
277
|
+
"mock": true,
|
|
278
|
+
"changes": [
|
|
279
|
+
{
|
|
280
|
+
"kind": "function",
|
|
281
|
+
"id": "legacy_filter",
|
|
282
|
+
"action": "unmanaged",
|
|
283
|
+
"fields": []
|
|
284
|
+
}
|
|
285
|
+
],
|
|
286
|
+
"summary": {
|
|
287
|
+
"create": 0,
|
|
288
|
+
"update": 0,
|
|
289
|
+
"state": 0,
|
|
290
|
+
"delete": 0,
|
|
291
|
+
"unmanaged": 1,
|
|
292
|
+
"skipped": 0
|
|
293
|
+
}
|
|
294
|
+
}
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
Server-only items do not fail the check unless you add `--fail-on-unmanaged`.
|
|
298
|
+
|
|
299
|
+
## Security notes
|
|
300
|
+
|
|
301
|
+
This tool holds an admin token and makes a server run code, so read this once.
|
|
302
|
+
|
|
303
|
+
- **`apply` makes the server execute your code.** Open WebUI runs uploaded Tool and Function code with `exec`, and installs the packages listed in the `requirements:` line of the file's frontmatter with `pip install`. Deploy only code you have reviewed. Open WebUI treats this as intended behavior, see its [vendor disposition for CVE-2026-0765](https://docs.openwebui.com/security/vendor-dispositions/cve-2026-0765) (checked 2026-11-12).
|
|
304
|
+
- **Valves values never touch your files.** `pull` does not request valves and drops them if a server sends them, so API keys set in the admin screen do not end up in git. `lint` rule OWD009 warns about secret-looking defaults in the source.
|
|
305
|
+
- **The token comes only from `OWUI_TOKEN`.** It is never read from the config file and never printed.
|
|
306
|
+
- **The token is sent to the server URL.** The URL can come from `server.url` in the config file, so in CI pin `OWUI_URL` as a secret or protected variable. Then a pull request cannot change the URL in the file to send your token elsewhere. Use `https://` when the server is not on your own machine.
|
|
307
|
+
- `lint` and `--fake` never run your code; they only parse it with `ast`.
|
|
308
|
+
|
|
309
|
+
## Language
|
|
310
|
+
|
|
311
|
+
Output and `--help` are available in English and Korean. Priority: `--lang en|ko`, then `OWUI_DEPLOY_LANG`, then `LC_ALL`, `LC_MESSAGES`, `LANG`. Anything that is not Korean falls back to English.
|
|
312
|
+
|
|
313
|
+
```bash
|
|
314
|
+
uv run owui-deploy --lang ko plan --config examples/demo/owui-deploy.toml --fake
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
See [README.ko.md](https://github.com/LeeGyeongPil/owui-deploy/blob/v0.1.2/README.ko.md) for the Korean screenshots.
|
|
318
|
+
|
|
319
|
+
## When to use it
|
|
320
|
+
|
|
321
|
+
- Good fit: your own Tools and Functions live in git and you want lint, a reviewable plan and a repeatable apply.
|
|
322
|
+
- Different tools for other jobs: see [Compared with other tools](#compared-with-other-tools) below.
|
|
323
|
+
- Not covered in 0.1.2: valves values, several environments in one config, history and rollback, Models, Prompts and Knowledge.
|
|
324
|
+
|
|
325
|
+
## Compared with other tools
|
|
326
|
+
|
|
327
|
+
The short version: owui-cli is an **imperative** tool (you run one command per file, it changes the server right away). owui-deploy is **declarative** (the folder and `owui-deploy.toml` describe the wanted state, `plan` shows the difference, `apply` closes it) and adds `lint` before anything is uploaded.
|
|
328
|
+
|
|
329
|
+
| Tool (version checked 2026-11-12) | What it is | Tools and Functions from files | Preview before change (plan/diff, drift exit code) | Static checks before upload | Declared `active` / `global` state |
|
|
330
|
+
|---|---|---|---|---|---|
|
|
331
|
+
| [oikb](https://docs.openwebui.com/ecosystem/knowledge-base-sync) 0.6.0 (official) | Syncs files from local folders, GitHub, Confluence and more into **knowledge bases**, with `--dry-run` | Not its job | For knowledge bases (`--dry-run`) | No | No |
|
|
332
|
+
| [owui-cli](https://github.com/rndmcnlly/owui-cli) 0.7.1 | Imperative CLI for many Open WebUI resources: `tools deploy file.py` (create or update), `pull-all`, `valves-set` | Yes, one file per command (this overlaps with owui-deploy) | No | No | No |
|
|
333
|
+
| [owui-client](https://pypi.org/project/owui-client/) 11.0.0 | Async Python client for the whole API, for your own scripts | Through your own code (`create`/`update`, `sync_functions`) | No | No | Through your own code |
|
|
334
|
+
| [suurt8ll/open_webui_functions](https://github.com/suurt8ll/open_webui_functions) `dev/function_updater.py` | Development script inside one repository: uploads the files listed in `FILEPATHS`, watches for changes | Yes, for that repository | No | No | No |
|
|
335
|
+
| owui-deploy 0.1.2 (this repo) | Declarative `lint` / `plan` / `apply` / `pull` | Yes, a whole folder | Yes (`plan`, `--diff`, `--json`, exit code 1 on drift) | Yes (`lint`, OWD001-OWD009) | Yes |
|
|
336
|
+
|
|
337
|
+
Notes:
|
|
338
|
+
|
|
339
|
+
- owui-cli can also deploy a Tool file and export everything with `pull-all`. If you only need to push one file now and then, it does the job. owui-deploy is for when the folder in git is the source of truth and you want to review a plan in CI before changing the server.
|
|
340
|
+
- owui-deploy also matches the server's import rewriting before comparing (no false diffs), flips the toggle only when the state differs, and never calls `/functions/sync`, which deletes every Function missing from the list it receives. If you use owui-client's `sync_functions`, send the full list.
|
|
341
|
+
- owui-deploy does not manage knowledge bases; use oikb for that.
|
|
342
|
+
|
|
343
|
+
Sources, checked 2026-11-12: [oikb docs](https://docs.openwebui.com/ecosystem/knowledge-base-sync), [oikb on PyPI](https://pypi.org/project/oikb/), [owui-cli on GitHub](https://github.com/rndmcnlly/owui-cli), [owui-cli on PyPI](https://pypi.org/project/owui-cli/), [owui-client reference](https://whogben.github.io/owui_client/reference/routers/functions), [owui-client on PyPI](https://pypi.org/project/owui-client/), [suurt8ll/open_webui_functions](https://github.com/suurt8ll/open_webui_functions). These tools may have changed since that date.
|
|
344
|
+
|
|
345
|
+
## Troubleshooting
|
|
346
|
+
|
|
347
|
+
| Symptom | Cause | Fix |
|
|
348
|
+
|---|---|---|
|
|
349
|
+
| `error: no token. Export OWUI_TOKEN ...` (exit 2) | `OWUI_TOKEN` is not set. | Export an admin JWT or API key, or add `--fake`. |
|
|
350
|
+
| `error: cannot connect to ...` (exit 2) | Server is down or the URL is wrong. | Check the URL and that Open WebUI is running. |
|
|
351
|
+
| `the server refused the token (HTTP 401/403 ...)` (exit 2) | Token expired, not admin, or API keys disabled. | Use a fresh admin JWT, or start the server with `ENABLE_API_KEYS=true`. |
|
|
352
|
+
| `error: config file not found: ...` (exit 2) | No `owui-deploy.toml` in the current folder. | Pass `--config PATH` or run `pull --out` to create one. |
|
|
353
|
+
| The server rejected an item, exit 1 | Usually a lint error the server will not explain. | Run `owui-deploy lint` and fix the lines it lists. |
|
|
354
|
+
| `plan` shows `? unmanaged` | The item exists only on the server. | Add the file with `pull`, or delete it with `apply --prune`. |
|
|
355
|
+
|
|
356
|
+
## Development
|
|
357
|
+
|
|
358
|
+
```bash
|
|
359
|
+
uv run pytest -q
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
Bugs and ideas are welcome as issues. Changes are listed in [CHANGELOG.md](https://github.com/LeeGyeongPil/owui-deploy/blob/v0.1.2/CHANGELOG.md).
|
|
363
|
+
|
|
364
|
+
## Tested with
|
|
365
|
+
|
|
366
|
+
| What | Version | How |
|
|
367
|
+
|---|---|---|
|
|
368
|
+
| Open WebUI | 0.13.3 | One run against a real server (`tests/test_e2e_real.py`, needs `OWUI_E2E_URL` and `OWUI_E2E_TOKEN`). |
|
|
369
|
+
| Practice mock (`--fake`) | follows 0.13.3 | Matched to responses recorded from 0.13.3 by contract tests. |
|
|
370
|
+
| Python | 3.11 and 3.13 (CI) | `uv run pytest -q`. |
|
|
371
|
+
|
|
372
|
+
## License
|
|
373
|
+
|
|
374
|
+
MIT, see [LICENSE](https://github.com/LeeGyeongPil/owui-deploy/blob/v0.1.2/LICENSE). Open WebUI has its own license; this project is not affiliated with it.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
owui_deploy/__init__.py,sha256=wtc20n95ThXr9aEsO-aGk1awhgV_MAQGqhHxFMbER1I,335
|
|
2
|
+
owui_deploy/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
|
|
3
|
+
owui_deploy/applier.py,sha256=FzZmiHD2Yw27B8IluVgAMA7sWsiom0tqhO3MQ9GJEqQ,3448
|
|
4
|
+
owui_deploy/cli.py,sha256=Yskxu_YEebnOD3SzBmUU5c6oEzBPYNhEu-eJLbzl6Zo,14064
|
|
5
|
+
owui_deploy/client.py,sha256=Q-tffKi-fzG73ny--94BiDaT8HjQkUEsTcdc_umgExg,4126
|
|
6
|
+
owui_deploy/config.py,sha256=5IX0QBsDC7u37QfrwXwAef_glghv69hVdhO-3CdVuoE,8156
|
|
7
|
+
owui_deploy/errors.py,sha256=bNb-aD_tzt20U8dH65YS6BBdNyKqL-jpgr0o3qhikBw,1148
|
|
8
|
+
owui_deploy/fake.py,sha256=theYH8KQOFkLgDSP7V9Glp8NY15Yn0B8zlkZ6aYPA00,15284
|
|
9
|
+
owui_deploy/frontmatter.py,sha256=QZZgaBA6uALtbzsJEM9UmeRttFDZ_GNl60tehW0aiMU,890
|
|
10
|
+
owui_deploy/i18n.py,sha256=19nhdiTKZZgKg9UloLPwAoyObHyEc1arnSedpwvxn_s,1708
|
|
11
|
+
owui_deploy/lint.py,sha256=EiVNcMpd4hMqWZZijSVZB7EgCaHsuT5ip4YSDX5cYr4,10186
|
|
12
|
+
owui_deploy/locales/en.json,sha256=Qel8vTQJWqQeOEKa73cOsy9McXCmaY5hlJ9ObAfkFus,7624
|
|
13
|
+
owui_deploy/locales/ko.json,sha256=5sTmnLXivXNN1q9RIevy0nDl81mAGajz_-AVcUi-sKw,9442
|
|
14
|
+
owui_deploy/normalize.py,sha256=vH85xj8120F4AV0s5teQ4Su7ZhshGFmU8Sgu6KecpGM,747
|
|
15
|
+
owui_deploy/planner.py,sha256=ba5H9mimlD6xiICw4SgZscciNsueDHbA6kGW2x_xJ5k,4518
|
|
16
|
+
owui_deploy/pull.py,sha256=8obwy96-dEU_IU5_hHV1maNBMi6j8uiMDrV7cyt_CPw,4869
|
|
17
|
+
owui_deploy/render.py,sha256=JUD8uub5PHNPPbTE1EFemn5qFwyEmW8WWSa3YL_FvcQ,4115
|
|
18
|
+
owui_deploy-0.1.2.dist-info/licenses/LICENSE,sha256=RRsvuvgBgx_uEpuct2Q4NeA9z27j12FFqpzQt1KVHL0,1069
|
|
19
|
+
owui_deploy-0.1.2.dist-info/WHEEL,sha256=3NO1oYsF7mANFUWVdyEQLM-zmecczWWEmmF5rEbXrWk,80
|
|
20
|
+
owui_deploy-0.1.2.dist-info/entry_points.txt,sha256=zKxI7qkF5gmx-0Fon9sDjST2o1g26zXzyn3VySqVXPQ,54
|
|
21
|
+
owui_deploy-0.1.2.dist-info/METADATA,sha256=AyN_glpKwHhQqrquLvJa_7KPsTLN2kATnsY6ebHC9ng,20252
|
|
22
|
+
owui_deploy-0.1.2.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 LeeGyeongPil
|
|
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.
|