okforge-webui

A LAN web UI and job runner for okforge
knowledge bases: drop a scanned book in an inbox and drive it through
VLM OCR, optional translation, and ingestion into an LLM-synthesized
wiki — then browse, query, and publish the result. Built for local-first
setups where the LLM is your own llama.cpp/vLLM box, not a cloud API.

The pipeline is five screens: probe (inspect the PDF: text layer?
language? page count) → pilot (OCR a page or three, check the
transcription and image crops before committing) → project (pick or
name the project that collects the output) → run (chunked OCR →
translate → markdown with live progress) → verify & use (review the
markdown, ingest it into the project's knowledge base, then query and
publish). OCR and ingestion are always separate steps, so the same tool
doubles as a pure PDF→markdown converter — skip the ingest and take the
files from md-out/.

Inputs: PDFs, page-scan images (jpg/png/tif/bmp — wrapped into PDF on
upload so the OCR pipeline handles them), and your own markdown/text
documents (added straight to a project, no OCR). Selecting several
PDFs/images at once combines them into one PDF in natural file-name
order — the upload shows the exact order and combined name before
anything is sent. Other formats (docx, pptx, html …) should be
pre-converted to markdown first.

What's in the box

• Serial job queue (sqlite + one worker, on purpose): one add or
  OCR run at a time protects single-slot LLM hosts and the engine's
  per-KB ingest lock. Jobs survive backend restarts; every finished job
  keeps its log. One-click resume/retry, a stall watchdog
  (flags, never kills), per-chunk ETA from real history, and a git
  pre-ingest snapshot of the KB before every add.
• Markdown first, ingest second: every run OCRs into the project's
  md-out/<name>/ folder (chunked .md + page maps + image crops);
  hand-made markdown/text files can be added to the same folder from
  the UI ("Add markdown…" — no OCR involved);
  ingesting that markdown into the knowledge base is a separate step —
  a one-click button in the verify stage (KB stats update chunk by
  chunk) or an auto-ingest toggle on the run. The KB is created on
  first ingest — or never, if all you wanted was the markdown.
• Archive-first deletes: removing an uploaded PDF, a project's
  markdown, a published site, or a whole project moves it to
  trash/ (KBs retire to kbs-retired/) — nothing in the UI is
  destructive, restore is a mv back.
• OCR + image extraction via
  okforge-vision-ocr
  (one VLM call per page: markdown transcription + photo bounding boxes
  together), with a table mode for pages the fast path mangles and a
  per-page re-OCR + re-ingest repair loop.
• Translation workflow for non-English scans: faithful transcription
  first, page-by-page translation second — both language versions share
  one image directory and page citations survive.
• Wiki browser with lexical search (source hits carry real page
  numbers), image lightbox, and markdown rendering.
• MCP server at /mcp (streamable HTTP): list_projects,
  project_status, ask, search, read_wiki_page. Connect any MCP
  client, e.g. claude mcp add --transport http okforge http://<host>/mcp.
  Clients that don't surface MCP server instructions (Open-WebUI and
  other OpenAPI-bridged clients) should get the recommended system
  prompt from docs/MCP_CLIENT_PROMPT.md.
• Static-site publishing per KB via Quartz
  — full-text search, graph view, backlinks — one button, then a printed
  rsync command to go public.

Prerequisites

• An OpenAI-compatible LLM endpoint — the whole pipeline's brain
  (llama.cpp or vLLM on your own hardware, or a hosted service; see
  Configuration). For the OCR path the endpoint's model must be
  vision-capable (Qwen-VL family or similar) — it reads page
  images. Text-layer extraction, ingestion, and querying work with any
  capable chat model.
• Python 3.10+
• Git — for the clone; on Windows it also provides the grep
  binary the engine's query agent uses.
• Node.js 18+ — only for the optional static-site publishing
  (Quartz); everything else runs without it. Quartz is a one-time,
  once-per-machine install into the shared quartz dir (<base>/quartz,
  or OKFORGE_WEBUI_QUARTZ_DIR) — clone it, check out v5, npm ci, then
  npx quartz plugin install; the exact steps are in
  OPERATIONS.
  Skipping the plugin install step is the usual first-publish failure:
  the build aborts with Could not resolve "../../.quartz/plugins",
  which is exactly the dir that step generates. On a LAN-only /
  offline box, also disable the default og-image emitter in
  quartz.config.ts (it fetches a font over the network at build time
  and otherwise fails); nothing else in Quartz needs outbound access.

Directory layout

<base>/                 e.g. /opt/okforge/  or  C:\okforge\
    okforge-webui/      ← this repo; .venv/ inside it
    kbs/<Subject>/      ← one self-contained knowledge base per subject
    inbox/              ← PDF drop point for the web UI
    md-out/<Project>/   ← OCR'd markdown per project (created on demand)
    kbs-retired/        ← retired KBs (archive-first "delete")
    trash/              ← web-UI deletes move things here, never erase
    quartz/             ← shared Quartz install (site publishing, optional)
    sites/<Subject>/    ← published static sites (optional)

The base directory can be anywhere — all defaults are relative to where
this repo sits (each is individually overridable by env var, see
Configuration). Every KB is self-contained (sources, wiki, engine state,
.env, its own git history) — copy the directory and you've copied the
KB. The UI discovers KBs by scanning the KB root; nothing is registered
anywhere else.

Install

Linux/macOS:

cd /opt/okforge   # or any base dir
git clone https://github.com/okforge/okforge-webui
cd okforge-webui
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
mkdir -p ../kbs ../inbox

Windows (PowerShell):

cd C:\okforge     # or any base dir
git clone https://github.com/okforge/okforge-webui
cd okforge-webui
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
md ..\kbs, ..\inbox

(PowerShell gotcha: anything in the current directory needs a .\
prefix to run — .\script.ps1, not script.ps1. The .venv\Scripts\…
forms above already qualify.)

requirements.txt pins the two okforge packages from PyPI — the
okforge engine (ingestion, wiki
compilation, query; see its
GETTING_STARTED)
and okforge-vision-ocr
(pre-conversion console scripts) — plus the FastAPI backend's own
dependencies.

Run it

One process serves the frontend, the API, and the MCP server. Run it
from this repo's directory — python -m webui resolves the webui
package relative to the current dir, so from anywhere else Python exits
with No module named webui:

cd <base>/okforge-webui
.venv/bin/python -m webui          # Linux/macOS
.venv\Scripts\python -m webui      # Windows
# browse http://<host>:8500/

OKFORGE_WEBUI_HOST / OKFORGE_WEBUI_PORT change the bind (default
0.0.0.0:8500 — LAN-visible; use 127.0.0.1 to keep it local). Same
trust model in every mode: LAN-only, no auth — don't expose it beyond a
network you trust.

First time? Follow the
small-test walkthrough below
before pointing it at a whole book.

To run it as a service: on Linux,
webui/deploy/okforge-webui-standalone.service
is a ready-to-edit systemd unit; on Windows, use Task Scheduler
("At startup", run <repo>\.venv\Scripts\python.exe -m webui) or
NSSM.

Optional: Apache in front (Linux)

For port 80, a LAN vhost name, and an easy basic-auth option, deploy.sh
installs Apache (static docroot + /api/ reverse proxy) in front of the
same backend under systemd:

SERVER_NAME=okforge.local OKFORGE_WEBUI_ENDPOINTS="gpu1=http://gpu1:8080/v1" \
    webui/deploy.sh

deploy.sh is idempotent — rerun it after changes (it restarts the
backend, so never while a job is running). In this mode frontend
files are served by Apache, so frontend-only changes are
sudo rsync -a --delete webui/static/ /var/www/okforge-webui/
(standalone mode serves them straight from the repo — nothing to copy).

First run — start with a small test

Prove the whole loop — endpoint, OCR quality, ingest, query — on a
handful of pages before committing to a book. Five pages take about ten
minutes on a local GPU; a 300-page book is an overnight-plus run (see
ingest cost).
Everything below happens in the browser at http://<host>:8500/.

1. Check the header. Pick your LLM server in the dropdown; the
   status light beside it polls the server, so a steady light means
   you're actually talking to it. This choice gets baked into the
   knowledge base at first ingest (queries and MCP clients then use it
   too — changeable later).
2. Stage 1 — get a document in. Upload a short PDF — or a few
   phone photos of pages, which combine into one PDF (the panel shows
   the page order before anything uploads; it comes from the file
   names). The probe runs automatically: scan means the OCR
   pipeline (the normal path), text means an embedded text layer
   you can optionally trust in stage 4.
3. Stage 2 — pilot one page. Enter one page number with real
   content on it (not the cover) and Run pilot. Read the
   transcription beside the rendered page; check the image crops. Bad
   OCR here means bad OCR everywhere, so fix it now — table mode for
   complex tables, --figures if line drawings were missed, or an OCR
   hint ("ignore marginalia"). Re-run until the page reads right.
4. Stage 3 — create a project. Use a throwaway name like
   MyBook-test — you'll delete it after the test (one click, and
   nothing is ever erased — it all moves to trash/).
5. Stage 4 — run a small range. Set From page / to to a few
   content pages, tick ingest into KB when OCR finishes, and Start
   run. The queue shows one plain-language row ("working — n/m chunks
   OCR'd"; ▸ expands the technical steps) and markdown appears in
   stage 5 as chunks finish.
6. Stage 5 — verify and ask. Read the markdown. Watch the
   knowledge-base stats tick up as chunks ingest; a one-line project
   description is written automatically at the end, and Publish
   unlocks when the last chunk is in. Then ask the knowledge base a
   question — answers cite source pages as (p. N).
7. Happy? Delete the test and run for real. Delete project… in
   stage 3, then repeat with the real project name and the full page
   range. (If you'd rather keep the test: make its range exactly the
   first chunk — e.g. pages 1–20 at the default 20 pages per chunk —
   and the full run will skip it instead of re-OCRing it.)

What a small test catches early: a wrong endpoint or non-vision model
(pilot fails or returns junk), OCR quirks your document needs hints
for, and a misconfigured model paying a hidden reasoning block on every
call — a 20-page chunk should ingest in a couple of minutes on a local
27B model, not 27 (see the llm_extra_body note below).

Configuration

Everything is an environment variable (for the systemd deployments, set
them in the unit — deploy.sh passes any that are exported when it
runs). <base> below means the directory this repo sits in.

Note: these use the OKFORGE_WEBUI_* prefix. The pre-rebrand
OPENKB_WEBUI_* names (and OPENKB_DIR for the engine dir) still work
— the backend reads the new name first and falls back to the old one,
printing a one-time deprecation line on stderr naming what to rename.

The documented install puts .venv inside the repo, which is why OKFORGE_WEBUI_ENGINE_DIR needs no setting by default. If you instead share one .venv across checkouts or keep it in the base dir, point this var at the directory that contains it — otherwise the UI looks for openkb/okforge-vision-ocr under <repo>/.venv/bin and reports them missing.

Local llama.cpp/vLLM endpoints need only label=url. A hosted
OpenAI-compatible service takes two more |-separated fields — its API
key and the model in LiteLLM provider/model format:

OKFORGE_WEBUI_ENDPOINTS="gpu1=http://gpu1:8080/v1,openrouter=https://openrouter.ai/api/v1|sk-or-v1-...|openrouter/qwen/qwen3.6-27b"

KBs created on such an endpoint get the key in their .env, the model
in their config.yaml, and a provider-appropriate thinking-off block
(OpenRouter's reasoning.enabled=false instead of llama.cpp's
chat_template_kwargs). OCR/translate jobs strip the LiteLLM provider
prefix and pass the rest as the OpenAI-protocol model name. Note the
key lives in plain text in the unit file/environment — acceptable on a
single-operator LAN box; protect the systemd drop-in accordingly
(chmod 640).

How the endpoint choice binds to a KB

The endpoint picked in the header is baked into each knowledge base
at first ingest: that's when the KB's own .env (OPENAI_API_BASE,
LLM_API_KEY) and config.yaml (model, thinking-off block) are
written. From then on, everything that touches that KB — later
ingests, the stage-5 Ask box, and the MCP server's ask tool — uses
the KB's own endpoint, regardless of what the header currently
shows. (The header selection still drives OCR/translate runs, which
produce markdown before any KB exists.) So two KBs on one machine can
happily run against two different LLM servers, and an MCP client
querying a project lights up whichever server that project pins.

To repoint an existing KB (LLM moved to a new box, or a new
model): edit those two files in the KB directory — .env for the URL
and key, config.yaml for model: — and the next call uses them; no
restart, nothing to re-register. Keep the llm_extra_body block
appropriate for the new host (see below). The stage-3 project info box
shows which endpoint a KB currently points at.

One setting matters more than all the
others on llama.cpp hosts serving Qwen-family models with thinking
enabled by default — without it every ingest silently pays a hidden
reasoning block (measured: a 2-minute add becomes 27):

llm_extra_body:
  chat_template_kwargs:
    enable_thinking: false

KBs created through the web UI get this automatically. Pilot and OCR
runs are the exception — they happen before a KB exists, calling the
vision model directly. That path already sends enable_thinking: false
(and reasoning.enabled: false) and strips any stray <think> block
from the transcript, so nothing is normally needed. But if your model's
own chat template overrides that request-level flag — the
Qwen3.6-27B-MTP template is one that keeps thinking on regardless — the
model still generates (and you still pay for) the reasoning block even
though the text is discarded. That can only be fixed at the server: use
a llama.cpp/vLLM preset (or a --jinja chat template) that honors
enable_thinking: false. Symptom: pilot/OCR pages take far longer than
their token count suggests.

One more expectation worth setting for large collections: ingest cost
scales with the size of the wiki, not the document being added —
recurring concept and entity pages are rewritten on every mention — so
a document that takes 3 minutes into a fresh KB takes ~9 into the same
KB 300 documents later. llama.cpp's prefix cache absorbs most of the
growth (84% of input tokens were cache hits over a measured
364-document run); see
docs/OPERATIONS.md
for the measured figures before planning a multi-day run.

Docs

• First run: the small-test walkthrough
  above is the intended on-ramp.
• docs/INSTALL_PROMPT.md — a prompt to hand a
  coding agent so it walks you through install and configuration
  interactively, Quartz included.
• docs/OPERATIONS.md — operating KBs day to day:
  anatomy, copying between machines, re-ingest semantics (what happens
  when you add the same document twice), Obsidian editing safety, Quartz
  publishing, troubleshooting.
• docs/MCP_CLIENT_PROMPT.md — the system
  prompt to paste into MCP clients that don't surface the server's own
  instructions (Open WebUI and most OpenAPI-bridged clients); also
  served from the server as the MCP prompt kb-search-guide.
• webui/PLAN.md — architecture and API design notes.

License

MIT — see LICENSE.