Initial Commit

docs/filters.md

@@ -0,0 +1,103 @@
+# The Open WebUI filters
+
+Five small plugins in [`../owui-functions/`](../owui-functions/). **All are optional**, and
+the tool server works without any of them.
+
+They are installed by **pasting them into Open WebUI**, because they run inside it, not
+here. Nothing in `docker-compose.yml` installs them.
+
+## How to install one
+
+1. Open WebUI → **Admin Panel → Settings → Functions → +**
+2. Paste the whole file.
+3. Save, then toggle it **on**.
+4. If it has valves, open them with the gear icon and fill them in.
+
+To update one later, paste the new version over the old and save. The change takes effect
+on the next message — Open WebUI recompiles a function whose content has changed, so no
+restart is needed.
+
+## What each one is for
+
+### `vm_agent_progress` — needed if you want to watch a VM session
+
+**Valve: `api_key` — set it to your `OWUITOOLS_AUTH_TOKEN`.** The tool server's token, the
+same value as the tool connection's Auth field.
+
+A `vm_agent` call is one tool call that runs for minutes to hours. Without this filter the
+chat shows nothing at all until it finishes, which is indistinguishable from a hang. With
+it, you get the task list, what the agent is doing now, its output as it arrives, and
+screenshots of the guest's screen.
+
+It is also what asks you the question when the agent needs one answered.
+
+Needs `ENABLE_FORWARD_USER_INFO_HEADERS: "True"` on the Open WebUI container, or it has no
+chat id to attach to and logs *"live progress disabled"*.
+
+### `inline_tool_images` — makes plots visible to you
+
+When a tool returns a `data:image/png` URI, Open WebUI routes it to the **model** as a
+vision input and never renders it for the user. So `matlab_run` can draw a graph, the model
+can describe it accurately, and you never see it.
+
+This puts the picture in the chat as well. Install it if you use `matlab_run` for anything
+that plots.
+
+### `answer_sources` — appends what was actually read
+
+When an answer used tools but cites nothing, this adds the URLs the tools **opened** — never
+a search result that was not read. Three graded rounds showed the "cite your source" rule
+surviving neither the system prompt nor a `Sources:` trailer; of forty answers, exactly one
+carried a URL.
+
+### `live_progress_status` — says what it is doing
+
+Replaces the spinner with the real phase: *Processing prompt → Thinking → Calling
+web_search → Writing response*, driven by Ollama's own counters rather than a guess. Most
+useful on a long context, where the prefill alone can take a while and silence looks like a
+crash.
+
+### `quantitative_question_nudge` — raises tool salience
+
+A short inlet note on casually-phrased measurement questions. It exists because a question
+about FFT aliasing got a confident wrong answer from recall when the tool would have got it
+right, and because static prompt text loses to the shape of the conversation.
+
+The narrowest and most optional of the five.
+
+## Auditing what is actually installed
+
+Open WebUI's Functions page lists these alongside anything else you have added — pipes that
+add model providers, other people's filters — and it is easy to lose track of which are
+part of this project. To see the lot, including whether each is enabled and applied
+globally:
+
+```sh
+sudo python3 -c "
+import sqlite3
+db = sqlite3.connect('file:/srv/openwebui/data/webui.db?mode=ro', uri=True)
+for r in db.execute('SELECT type,id,is_active,is_global FROM function ORDER BY type,id'):
+    print('%-7s %-32s active=%s global=%s' % r)"
+```
+
+The five above are the only ones this project ships. A `pipe` is never one of ours — this
+repo adds no model providers.
+
+To check which tool connections a model is set to use, and its capabilities:
+
+```sh
+sudo python3 -c "
+import json, sqlite3
+db = sqlite3.connect('file:/srv/openwebui/data/webui.db?mode=ro', uri=True)
+for mid, meta in db.execute('SELECT id, meta FROM model'):
+    m = json.loads(meta or '{}')
+    if m.get('toolIds'):
+        print(mid, m['toolIds'], json.dumps(m.get('capabilities', {})))"
+```
+
+`server:owuitools` in `toolIds` is this tool server.
+
+## Where to read more
+
+Each file opens with a `# WHY THIS EXISTS` block giving the measured failure that produced
+it. [TUNING.md](TUNING.md) has the full argument for each.