Skip to content

feat: Open RAG, a Windows desktop app with categories and sections - #6

Merged
TWadi merged 11 commits into
twadi/local-apifrom
twadi/desktop-app
Nov 2, 2026
Merged

TWadi merged 11 commits into
twadi/local-apifrom
twadi/desktop-app

Conversation

@TWadi

@TWadi TWadi commented Nov 2, 2026

Copy link
Copy Markdown
Collaborator

What

Open RAG, the Windows desktop app (step 2 of 3), in desktop/. It is for teachers, researchers and students:

  • Organise documents into categories (a subject or research area) and sections (a course, session, project or reading list).
  • Point each section at its folders.
  • Ask questions with cited answers, from one section or from a whole category.

It runs entirely on the computer. The self-contained installer is the next PR.

What it looks like:

  • The AI Engineering Arena's "sticker arcade" theme: Lilita One titles, chunky ink outlines and hard shadows, candy accents and the dot grid.
  • Light or dark, following Windows.
  • Fonts bundled, so it looks the same offline.
  • An Arena-style tilted-sticker icon.

What you can do in it:

  • Sidebar: categories with their sections. Hover to add, rename or delete.
  • Section view:
    • a chat that answers only from that section;
    • folders you can add or remove (indexing starts on its own);
    • indexing progress and a summary of the last update;
    • the list of indexed documents.
  • Category view: a chat that searches all of its sections together.
  • Answers:
    • they stream in;
    • citations are pills, and the sources are cards with snippets;
    • clicking either opens the document, or shows it in Explorer;
    • "Not found in your documents" and "no source cited" are shown as notes on the answer.
  • Conversations are kept per section on this computer, and follow-ups use the recent history.

How it is built (ADR-0007, updated here):

  • OpenRag.App (WPF, .NET 10):
    • It hosts the React interface in WebView2 from the app's own folder (https://app.ore).
    • It starts ore serve itself, with a new 256-bit token per launch, and ties it to a job object. Closing the app stopped the engine in testing.
    • The page never sees the token and never calls a local port. Every API call and question goes to the window as a message. EngineProxy adds the token and allows only the engine's API paths and methods, and answers stream back line by line.
    • This also avoids WebView2 blocking the page's direct calls to 127.0.0.1.
  • OpenRag.Core:
    • Finds the engine: a bundled Python next to the app when installed, otherwise the checkout through uv run.
    • Parses ORE_READY port=N and writes the engine's output to %LOCALAPPDATA%\OpenRag\logs\engine.log.
    • Opens only documents (.pdf, .md, .txt) that exist, by absolute path, so nothing the page sends can launch a program.
  • web/: React 19, Tailwind 4 and motion, with a mock engine, so the interface can be designed in a browser with no Python.
  • Engine additions:
    • ore serve --data-dir keeps the app's data in %LOCALAPPDATA%\OpenRag.
    • --warm loads the models in the background, so the first question doesn't wait.
    • python -m open_rag_engine is how the installed app will start it.

Stacked on #5 (which is on #4). Merge those first.

Why

Wadi asked for an offline WPF app for teachers, researchers and students, with sections and categories, in the Arena's look.

How it was tested

  • .NET: 36 tests. They cover:
    • starting a real child process and reading its ready line or its crash output;
    • the locator for the installed and checkout layouts;
    • the proxy's path allow-list (it refuses .., other hosts and other methods), the token, streaming and 503s;
    • safe file opening.
  • Web: 13 tests (the line splitter, citation splitting, saved chats and history, and the engine client over a fake transport), plus tsc and ESLint.
  • Engine: 113 tests pass, and ruff is clean.
  • CI: a new Windows job builds and tests the interface and the app.
  • By hand:
    • The interface works in the browser against the mock in light and dark.
    • The real OpenRag.exe started the engine. The models loaded fully offline: the log shows it refused to contact Hugging Face.
    • Wadi created a category and a section, added a folder and indexed 10 PDFs in the app.
    • Closing the window stopped the engine.

Checklist

  • Tests cover the change
  • Docs updated (README, docs/, or a new ADR for architectural decisions)
  • No secrets, keys or private data in the diff

- WPF shell (.NET 10) hosting a React 19 + Tailwind 4 interface in WebView2, in the AI Engineering Arena's
  sticker-arcade theme (light and dark, fonts bundled for offline use)
- sidebar of categories and sections; per section: folders, background indexing with progress, documents and a chat;
  a category chat searches all its sections; citations as pills and source cards that open the file
- the app starts ore serve itself (bundled Python when installed, uv in a checkout), ties it to a job object and
  routes every API call through an EngineProxy that adds the token and allows only the engine's API paths, so the
  page never sees the token or talks to a local port
- conversations kept per section on this computer; follow-up questions use the recent history
- ore serve: --data-dir and --warm; python -m open_rag_engine
- tests: 36 .NET (engine start, ready line, locator, proxy, safe file opening), 13 web, engine suite; Windows CI job
TWadi added 9 commits November 2, 2026 19:04
The standard Windows title bar is replaced by one drawn in the Arena's top-bar style: the RAG sticker, the app name,
where you are (category > section) and Arena window buttons. It is a WebView2 drag region, so dragging, double-click
to maximise and the window menu still work; WindowChrome keeps resizing from a thin border, rounded corners on
Windows 11, and the frame follows light or dark mode.
The global keyboard-focus outline was unlayered CSS, so it beat the text area's outline-none and drew a rectangle
inside the rounded box. It now lives in the base layer, and the whole box shows focus with a cobalt border and shadow.
A bundled engine loads its models from models_dir/<org>--<name> under the same model names, so the index
fingerprint and existing indexes stay valid. --llm-url points the engine at the llama-server the app starts.
- chat: a late reply after switching section can no longer land in, or be saved under, another conversation; saving is
  debounced and done outside the state update; the chat resets if the engine restarts (+ regression tests)
- a connection lost mid-answer becomes a 503 instead of an unhandled exception; every forwarded call and question now
  always gets an answer for its id; library calls time out instead of hanging
- opening sources: only local document paths (no UNC, device or alternate-stream paths), checked off the UI thread;
  explorer.exe by full path
- engine lifecycle: start and restart are serialised, deliberate stops aren't reported as crashes, a start that times
  out stops the process, only the current engine can report a crash, and unexpected start errors show a message
- WebView2: content-security policy on the built page (connect-src 'none'), DenyCors mapping, all permissions denied,
  no host objects; HttpClient bypasses system proxies
- engine: Stop now really stops generation (the next token raises once the client is gone); models load once under a
  lock, so the warm-up and a first question can't load them twice
- proxy: exact allow-list match (\z), questions only via the stream, problem bodies built with a JSON serialiser
- deleting a section or category also deletes its saved conversation; checkout discovery is Debug-only
The Python .gitignore template ignored every lib/ folder, so desktop/web/src/lib
(the engine client, the WebView2 bridge, chat storage, the mock engine and
their tests) never reached the repository and a fresh checkout couldn't build
the interface. The rule now covers only the root lib/ and lib64/.
installer/build.py stages a self-contained Open RAG and runs Inno Setup:
the published app, a uv-managed CPython 3.12 with the engine and its locked
dependencies (CPU torch), the embedding and reranker models from the Hugging
Face cache, the Qwen3 GGUF from Ollama (digest-checked) and llama.cpp's
llama-server (pinned b12052, sha256-checked). The setup installs per user,
keeps the library on uninstall and comes in parts below GitHub's 2 GiB limit.

The app starts the bundled llama-server on a free loopback port with its own
key and points the engine at it with --llm-url. ChildHost replaces EngineHost
and runs both processes, waiting on ORE_READY or a /health probe. Logs rotate
at 5 MB. installer/smoke_test.py checks a stage or an installed app end to end.

The window also opens the credits' GitHub and LinkedIn links, and only those
(ExternalLinks).
The sidebar says who developed Open RAG and opens a Credits sheet with both
authors' GitHub and LinkedIn and the source code. Links open in the default
browser through the window, which accepts only the links on its own list; a
test checks the sheet's links against it.
feat: Windows installer with a bundled language model, plus credits
@TWadi
TWadi merged commit 68fd4c6 into twadi/local-api Nov 2, 2026
1 of 2 checks passed
@TWadi
TWadi deleted the twadi/desktop-app branch November 2, 2026 19:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant