feat(desktop): scaffold Tauri desktop shell + slim API sidecar packaging

Foundation for packaging OpenKB as a desktop app for non-technical users. The
architecture is a thin Tauri (Rust) shell that spawns the openkb-api server
(from #150) frozen into a slim, self-contained PyInstaller sidecar, then points
the system WebView at it over localhost.

desktop/packaging/ — freezes openkb.api:main into a slim onedir binary:
  - pyi_rthook_magika.py: runtime hook stubbing magika so markitdown converts
    Office/HTML by file extension, letting the build exclude magika +
    onnxruntime entirely.
  - prune_litellm_proxy.py: post-build removal of the unused LiteLLM Proxy
    Server (static/data assets no client code path imports).
  - build_sidecar.sh: the PyInstaller recipe wiring both together.
  - sidecar_entry.py: frozen entry mirroring the openkb-api console script.

desktop/src-tauri/ — reference Tauri v2 shell: spawns the sidecar, shows a
  splash while polling its health, navigates the WebView to it, kills it on
  exit. PyInstaller onedir output is bundled as a resource directory (not
  externalBin, which expects a single file).

Verified (x86_64 Linux): the frozen slim sidecar boots uvicorn and serves
GET /api/v1/kbs -> 200; ≈134 MB compressed / 338 MB on disk. The src-tauri
shell is a skeleton, not compiled here (the dev container lacks webkit2gtk);
build it where the platform WebView libraries are present. See desktop/README.md.

Claude-Session: https://claude.ai/code/session_01KZyUSGAzVL9yxpsWWPv6Y2

Author: KylinMountain

desktop/.gitignore

@@ -0,0 +1,8 @@
+# PyInstaller sidecar build artifacts
+packaging/build/
+packaging/dist/
+packaging/*.spec
+
+# Tauri / Rust build artifacts
+src-tauri/target/
+src-tauri/gen/

desktop/README.md

@@ -0,0 +1,90 @@
+# OpenKB Desktop (Tauri)
+
+A desktop app that wraps OpenKB for non-technical users: no `pip`, no terminal.
+It is a thin [Tauri](https://tauri.app) (Rust) shell around two things OpenKB
+already produces:
+
+1. **The API sidecar** — `openkb-api` (the FastAPI server from the Knowledge
+   Workbench, `openkb.api:main`) frozen into a self-contained binary with
+   PyInstaller. It serves both the JSON/SSE API and the built web UI.
+2. **The web UI** — the `frontend/` Vite SPA, served by the sidecar at `/`.
+
+```
+┌─────────────────────────────────────────────┐
+│  Tauri shell (Rust + system WebView)         │
+│                                              │
+│   spawns ──▶  openkb-api-sidecar (frozen)    │
+│               ├─ FastAPI  /api/v1/*          │
+│               └─ web UI   /                  │
+│   WebView ──▶ http://127.0.0.1:<port>/       │
+└─────────────────────────────────────────────┘
+```
+
+The user double-clicks the app; the Rust shell starts the sidecar on a
+localhost port, waits until it answers, then points the WebView at it. No
+browser, no port, no "server" ever surfaces to the user.
+
+## Why this shape
+
+- OpenKB's capability lives in a heavy Python stack (litellm, pageindex,
+  markitdown, pymupdf). Rust can't replace that, so the Python runs as a frozen
+  sidecar. The Rust shell is glue: window, WebView, process lifecycle, updater.
+- Tauri (vs Electron) ships no Chromium — smaller download, less memory — at the
+  cost of using each platform's system WebView.
+
+## Layout
+
+```
+desktop/
+  packaging/            # freeze the Python API into a slim sidecar binary
+    build_sidecar.sh    #   PyInstaller recipe (slim: no magika/onnxruntime)
+    sidecar_entry.py    #   frozen entry -> openkb.api:main
+    pyi_rthook_magika.py#   runtime hook: stub magika (drops onnxruntime)
+    prune_litellm_proxy.py  # post-build: delete the unused LiteLLM proxy server
+  src-tauri/            # Tauri (Rust) shell — spawns the sidecar, opens the window
+```
+
+## Build pipeline
+
+```bash
+# 1. Python env with API + PyInstaller
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[api]" pyinstaller
+
+# 2. Build the web UI (its output is what the sidecar serves)
+cd frontend && npm install && npm run build && cd ..
+
+# 3. Freeze the slim API sidecar  ->  desktop/packaging/dist/openkb-api-sidecar/
+PYTHON=.venv/bin/python desktop/packaging/build_sidecar.sh
+
+# 4. Build the Tauri app (bundles the sidecar + opens the WebView)
+cd desktop/src-tauri && cargo tauri build
+```
+
+## Slimming (measured, x86_64 Linux)
+
+The sidecar reuses the packaging work from the CLI slimming (see PR #186 for the
+lazy-markitdown source change that makes it possible):
+
+| stage | compressed |
+|---|---|
+| full PyInstaller freeze | 147 MB |
+| − magika / onnxruntime (stub hook) | 140 MB |
+| − LiteLLM proxy server | 133 MB |
+
+The frozen **API sidecar** (adds FastAPI + uvicorn over the CLI baseline)
+measures **≈134 MB compressed / 338 MB on disk**, verified booting uvicorn and
+serving `GET /api/v1/kbs` → 200.
+
+`pymupdf` (PDF engine) and `pandas`/`numpy` (Excel support) are kept
+deliberately — they are load-bearing for OpenKB's document formats.
+
+## Toolchain / status
+
+Full builds need, per platform: Rust + Cargo, Node + npm, a Python 3.10+ env,
+and on **Linux `webkit2gtk`** (`libwebkit2gtk-4.1-dev`) for the WebView.
+
+**Status:** the API sidecar freeze (`packaging/`) is implemented and verified.
+The `src-tauri/` shell is a reference skeleton — it is *not* compiled in the
+CI/dev container used so far because `webkit2gtk` is absent there; build it on a
+machine (or CI runner) that has the WebView libraries installed.

desktop/packaging/build_sidecar.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+#
+# Build the OpenKB API sidecar: a self-contained, slimmed PyInstaller binary
+# that the Tauri desktop shell spawns and talks to over localhost HTTP.
+#
+# Slimming (see ../README.md for measured sizes):
+#   - exclude magika + onnxruntime; a runtime hook stubs magika so markitdown
+#     still converts Office/HTML by file extension.
+#   - post-build prune of the unused LiteLLM Proxy Server.
+#
+# Prerequisites: a Python env with `pip install -e ".[api]"` and `pyinstaller`.
+# Set PYTHON to that env's interpreter (default: python3).
+#
+# Usage:  PYTHON=/path/to/venv/bin/python desktop/packaging/build_sidecar.sh
+# Output: desktop/packaging/dist/openkb-api-sidecar/
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PYTHON="${PYTHON:-python3}"
+cd "$HERE"
+
+rm -rf build dist openkb-api-sidecar.spec
+
+COLLECT=(litellm markitdown pageindex tiktoken agents openai tiktoken_ext uvicorn fastapi)
+EXCLUDE=(magika onnxruntime)
+
+ARGS=(--onedir --name openkb-api-sidecar --noconfirm --clean --log-level=WARN)
+ARGS+=(--runtime-hook "$HERE/pyi_rthook_magika.py")
+for pkg in "${COLLECT[@]}"; do ARGS+=(--collect-all "$pkg"); done
+for pkg in "${EXCLUDE[@]}"; do ARGS+=(--exclude-module "$pkg"); done
+
+echo ">>> freezing openkb-api sidecar (slim: no magika/onnxruntime)"
+"$PYTHON" -m PyInstaller "${ARGS[@]}" sidecar_entry.py
+
+echo ">>> pruning unused litellm proxy server"
+"$PYTHON" prune_litellm_proxy.py "dist/openkb-api-sidecar"
+
+echo ">>> done: dist/openkb-api-sidecar/openkb-api-sidecar"

desktop/packaging/prune_litellm_proxy.py

@@ -0,0 +1,51 @@
+"""Prune the unused LiteLLM Proxy Server from a frozen build.
+
+`--collect-all litellm` pulls litellm's entire *Proxy Server* (~44 MB: a
+FastAPI gateway with an admin UI, swagger assets and OpenAPI snapshots), but
+OpenKB only uses litellm as a client. `import litellm` loads a handful of small
+proxy submodules; none of the static/data assets below are reached by any
+client code path (verified: not in sys.modules after `import litellm` plus a
+completion call). Deleting them from the frozen tree is safe; the sidecar smoke
+test (`GET /api/v1/kbs` returns 200) confirms the client path stays intact.
+
+Usage: python prune_litellm_proxy.py <path-to-frozen-app-dir>
+The frozen app dir is PyInstaller's onedir output (contains `_internal/`).
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Static/data dead weight — never imported by a litellm *client*.
+_PRUNE_DIRS = ("_experimental", "swagger")
+_PRUNE_GLOBS = ("*.jpg", "*.json", "*.yaml", "*.txt", "README.md")
+
+
+def _dir_size_mb(path: Path) -> int:
+    return sum(f.stat().st_size for f in path.rglob("*") if f.is_file()) // (1024 * 1024)
+
+
+def prune(app_dir: Path) -> None:
+    proxy = app_dir / "_internal" / "litellm" / "proxy"
+    if not proxy.is_dir():
+        print(f"prune_litellm_proxy: no proxy dir at {proxy}; nothing to do")
+        return
+    before = _dir_size_mb(proxy)
+    import shutil
+
+    for name in _PRUNE_DIRS:
+        target = proxy / name
+        if target.exists():
+            shutil.rmtree(target)
+    for pattern in _PRUNE_GLOBS:
+        for f in proxy.glob(pattern):
+            f.unlink()
+    after = _dir_size_mb(proxy)
+    print(f"prune_litellm_proxy: {before}M -> {after}M")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        raise SystemExit("usage: python prune_litellm_proxy.py <frozen-app-dir>")
+    prune(Path(sys.argv[1]))

desktop/packaging/pyi_rthook_magika.py

@@ -0,0 +1,39 @@
+"""PyInstaller runtime hook: stub `magika` so markitdown runs without onnxruntime.
+
+markitdown hard-depends on magika, which loads an ONNX model via onnxruntime
+(tens of MB) purely to sniff a file's type from its content. OpenKB only ever
+converts real files with correct extensions, so markitdown's extension/mimetype
+based stream-info guessing is sufficient and magika's content sniffing is
+redundant. This hook installs a lightweight in-memory `magika` module before
+markitdown imports it; `identify_stream` returns a non-"ok" status, which makes
+markitdown fall back to the extension guess. Paired with
+`--exclude-module magika --exclude-module onnxruntime` at build time, this drops
+onnxruntime (and magika's model) from the packaged sidecar entirely.
+"""
+
+import sys
+import types
+
+
+class _Result:
+    # Any status other than "ok" makes markitdown use its extension-based guess.
+    status = "stub"
+
+
+class Magika:
+    def __init__(self, *args, **kwargs):
+        pass
+
+    def identify_stream(self, *args, **kwargs):
+        return _Result()
+
+    def identify_bytes(self, *args, **kwargs):
+        return _Result()
+
+    def identify_path(self, *args, **kwargs):
+        return _Result()
+
+
+_stub = types.ModuleType("magika")
+_stub.Magika = Magika
+sys.modules.setdefault("magika", _stub)

desktop/packaging/sidecar_entry.py

@@ -0,0 +1,11 @@
+"""Frozen entry point for the OpenKB API sidecar.
+
+Mirrors the `openkb-api = openkb.api:main` console script. The Tauri shell
+spawns the frozen binary as `openkb-api-sidecar --host 127.0.0.1 --port <PORT>`;
+argparse in `openkb.api.main` reads those args from sys.argv unchanged.
+"""
+
+from openkb.api import main
+
+if __name__ == "__main__":
+    main()

desktop/src-tauri/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "openkb-desktop"
+version = "0.1.0"
+edition = "2021"
+description = "OpenKB desktop shell (Tauri) — wraps the frozen openkb-api sidecar"
+license = "Apache-2.0"
+
+[build-dependencies]
+tauri-build = { version = "2", features = [] }
+
+[dependencies]
+tauri = { version = "2", features = [] }
+# ureq is a tiny blocking HTTP client used only to poll the sidecar's health
+# endpoint during startup. Swap for anything you prefer.
+ureq = "2"

desktop/src-tauri/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    tauri_build::build()
+}

desktop/src-tauri/splash/index.html

@@ -0,0 +1,32 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>OpenKB</title>
+    <style>
+      html, body {
+        margin: 0;
+        height: 100%;
+        display: grid;
+        place-items: center;
+        font-family: system-ui, -apple-system, sans-serif;
+        background: #0b0d10;
+        color: #e6e8eb;
+      }
+      .box { text-align: center; }
+      .dot {
+        width: 10px; height: 10px; border-radius: 50%;
+        background: #4c8bf5; display: inline-block;
+        animation: pulse 1s ease-in-out infinite;
+      }
+      @keyframes pulse { 0%,100% { opacity: .3 } 50% { opacity: 1 } }
+    </style>
+  </head>
+  <body>
+    <div class="box">
+      <h1>OpenKB</h1>
+      <p>Starting your knowledge base <span class="dot"></span></p>
+    </div>
+  </body>
+</html>

desktop/src-tauri/src/main.rs

@@ -0,0 +1,97 @@
+// OpenKB desktop shell.
+//
+// Reference skeleton (Tauri v2). On launch it: (1) spawns the frozen
+// openkb-api sidecar on a localhost port, (2) shows a splash window while
+// polling the sidecar's health, (3) navigates the WebView to the sidecar once
+// it answers, and (4) kills the sidecar on exit.
+//
+// NOTE: not compiled in the container used so far (no webkit2gtk). Build on a
+// machine with the platform WebView libraries. Treat exact Tauri-v2 API details
+// (navigate signature, resource path) as things to confirm against your Tauri
+// version.
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+
+use std::process::{Child, Command};
+use std::sync::Mutex;
+use std::time::{Duration, Instant};
+
+use tauri::{Manager, RunEvent, Url};
+
+/// Held in Tauri state so the sidecar can be killed when the app exits.
+struct Sidecar(Mutex<Option<Child>>);
+
+const HOST: &str = "127.0.0.1";
+const PORT: u16 = 8765;
+
+/// Spawn the bundled PyInstaller onedir sidecar.
+///
+/// The sidecar is bundled as a resource *directory* named `sidecar` (see
+/// `tauri.conf.json` `bundle.resources`), because PyInstaller onedir output is
+/// a folder, not a single executable — so this can't use Tauri's `externalBin`
+/// mechanism.
+fn spawn_sidecar(app: &tauri::App) -> std::io::Result<Child> {
+    let resource_dir = app
+        .path()
+        .resource_dir()
+        .expect("resource dir should resolve");
+    let exe_name = if cfg!(windows) {
+        "openkb-api-sidecar.exe"
+    } else {
+        "openkb-api-sidecar"
+    };
+    let exe = resource_dir
+        .join("sidecar")
+        .join("openkb-api-sidecar")
+        .join(exe_name);
+    Command::new(exe)
+        .args(["--host", HOST, "--port", &PORT.to_string()])
+        .spawn()
+}
+
+/// Poll `url` until it answers or `timeout` elapses.
+fn wait_until_ready(url: &str, timeout: Duration) -> bool {
+    let deadline = Instant::now() + timeout;
+    while Instant::now() < deadline {
+        if ureq::get(url)
+            .timeout(Duration::from_millis(500))
+            .call()
+            .is_ok()
+        {
+            return true;
+        }
+        std::thread::sleep(Duration::from_millis(200));
+    }
+    false
+}
+
+fn main() {
+    tauri::Builder::default()
+        .manage(Sidecar(Mutex::new(None)))
+        .setup(|app| {
+            let child = spawn_sidecar(app)?;
+            app.state::<Sidecar>().0.lock().unwrap().replace(child);
+
+            let url = format!("http://{HOST}:{PORT}/");
+            let handle = app.handle().clone();
+            // Poll off the main thread so the splash window can paint.
+            std::thread::spawn(move || {
+                if wait_until_ready(&url, Duration::from_secs(30)) {
+                    if let (Some(win), Ok(parsed)) =
+                        (handle.get_webview_window("main"), Url::parse(&url))
+                    {
+                        let _ = win.navigate(parsed);
+                    }
+                }
+            });
+            Ok(())
+        })
+        .build(tauri::generate_context!())
+        .expect("error while building tauri app")
+        .run(|app_handle, event| {
+            if let RunEvent::Exit = event {
+                if let Some(mut child) = app_handle.state::<Sidecar>().0.lock().unwrap().take() {
+                    let _ = child.kill();
+                }
+            }
+        });
+}