(null);
+ useEffect(() => {
+ if (request) {
+ setName(request.initial ?? "");
+ setTimeout(() => input.current?.select(), 30);
+ }
+ }, [request]);
+ const valid = name.trim().length > 0 && name.trim().length <= 80;
+ const submit = () => {
+ if (!request || !valid) return;
+ request.onSubmit(name.trim());
+ onClose();
+ };
+ return (
+
+ {request?.title}
+
+ {request?.label}
+ setName(e.target.value)}
+ onKeyDown={(e) => e.key === "Enter" && submit()}
+ className="mt-1.5 block h-10 w-full rounded-xl border-[2.5px] border-edge bg-card-2 px-3 text-[15px] text-ink outline-none focus:shadow-[3px_3px_0_var(--cobalt)]"
+ />
+
+
+ Cancel
+
+ {request?.action}
+
+
+
+ );
+}
+
+export type ConfirmRequest = { title: string; body: string; action: string; onConfirm: () => void };
+
+export function ConfirmDialog({ request, onClose }: { request: ConfirmRequest | null; onClose: () => void }) {
+ return (
+
+ {request?.title}
+ {request?.body}
+
+ Cancel
+ {
+ request?.onConfirm();
+ onClose();
+ }}
+ >
+ {request?.action}
+
+
+
+ );
+}
diff --git a/desktop/web/src/components/Main.tsx b/desktop/web/src/components/Main.tsx
new file mode 100644
index 0000000..af20ba3
--- /dev/null
+++ b/desktop/web/src/components/Main.tsx
@@ -0,0 +1,80 @@
+import { AlertCircle, BookOpen, Pencil, Trash2, X } from "lucide-react";
+import { AnimatePresence, motion } from "motion/react";
+import type { ReactNode } from "react";
+import type { Section } from "../lib/types";
+import { Chip, IconButton, Spinner } from "./primitives";
+
+export function MainHeader({ title, subtitle, chip, onRename, onDelete }: {
+ title: string;
+ subtitle: string;
+ chip?: ReactNode;
+ onRename: () => void;
+ onDelete: () => void;
+}) {
+ return (
+
+
+
+
{title}
+ {chip}
+
+
{subtitle}
+
+
+
+
+
+
+
+
+ );
+}
+
+export function CategoryPanel({ sections, onSelect }: { sections: Section[]; onSelect: (id: string) => void }) {
+ return (
+
+ );
+}
+
+export function Toast({ message, onClose }: { message: string | null; onClose: () => void }) {
+ return (
+
+ {message && (
+
+
+ {message}
+
+
+
+
+ )}
+
+ );
+}
diff --git a/desktop/web/src/components/Message.tsx b/desktop/web/src/components/Message.tsx
new file mode 100644
index 0000000..7da691c
--- /dev/null
+++ b/desktop/web/src/components/Message.tsx
@@ -0,0 +1,127 @@
+import { AlertTriangle, ExternalLink, FolderSearch, Info } from "lucide-react";
+import { motion } from "motion/react";
+import { useState } from "react";
+import { splitCitations } from "../lib/text";
+import type { ChatMessage, Source } from "../lib/types";
+import { Chip, IconButton } from "./primitives";
+
+type SourceActions = { onOpen: (source: Source) => void; onReveal: (source: Source) => void };
+
+export function MessageView({ message, ...actions }: { message: ChatMessage } & SourceActions) {
+ if (message.role === "user") {
+ return (
+
+
+ {message.text}
+
+
+ );
+ }
+ const { answer, status } = message;
+ const sources = answer?.sources ?? [];
+ return (
+
+
+ {status === "streaming" && !message.text && Searching your documents… }
+ {splitCitations(message.text).map((part, i) =>
+ part.kind === "text" ? (
+ {part.text}
+ ) : (
+ part.numbers.map((n) => )
+ ),
+ )}
+ {status === "streaming" && message.text && }
+
+ {status === "error" && (
+
+ )}
+ {status === "stopped" && Stopped.
}
+ {answer && }
+ {answer && answer.sources.length > 0 && !answer.abstained && }
+
+ );
+}
+
+function CitationPill({ number, source, onOpen }: { number: number; source?: Source; onOpen: (s: Source) => void }) {
+ return (
+ source && onOpen(source)}
+ title={source ? `${source.label}${source.page ? `, page ${source.page}` : ""}` : "Unknown source"}
+ className="mx-0.5 inline-grid h-[20px] min-w-[20px] -translate-y-px place-items-center rounded-full border-2 border-edge bg-sun px-1 align-middle font-mono text-[11px] font-semibold text-[#17183a] transition hover:bg-tomato hover:text-white"
+ >
+ {number}
+
+ );
+}
+
+function AnswerNotes({ abstained, grounded, invalid }: { abstained: boolean; grounded: boolean; invalid: number[] }) {
+ if (abstained) {
+ return (
+
+
+ Not found in your documents
+
+
+ );
+ }
+ if (invalid.length > 0) {
+ return (
+
+
+ Cites a source that doesn't exist: check this answer
+
+
+ );
+ }
+ if (!grounded) {
+ return (
+
+
+ No source cited: check this answer
+
+
+ );
+ }
+ return null;
+}
+
+function Sources({ answerSources, cited, onOpen, onReveal }: { answerSources: Source[]; cited: Source[] } & SourceActions) {
+ const [all, setAll] = useState(false);
+ const shown = all || cited.length === 0 ? answerSources : cited;
+ const hidden = answerSources.length - shown.length;
+ return (
+
+ {shown.map((source) => (
+
+
+ {source.number}
+
+
onOpen(source)}>
+
+ {source.label}
+
+ {source.snippet}
+
+
+ onOpen(source)}>
+
+
+ onReveal(source)}>
+
+
+
+
+ ))}
+ {hidden > 0 && (
+
setAll(true)} className="px-1 text-[13px] font-bold text-accent underline-offset-2 hover:underline">
+ Show {hidden} more {hidden === 1 ? "passage" : "passages"} it read
+
+ )}
+
+ );
+}
diff --git a/desktop/web/src/components/Screens.tsx b/desktop/web/src/components/Screens.tsx
new file mode 100644
index 0000000..c9a7ac0
--- /dev/null
+++ b/desktop/web/src/components/Screens.tsx
@@ -0,0 +1,57 @@
+import { AlertTriangle, FolderPlus, Library, RotateCcw } from "lucide-react";
+import type { EngineState } from "../lib/host";
+import { Button, LogoMark, Spinner } from "./primitives";
+
+export function EngineScreen({ engine, onRestart }: { engine: EngineState; onRestart: () => void }) {
+ return (
+
+
+
+ {engine.state === "failed" ? (
+ <>
+
+ The engine didn't start
+
+
+ {engine.message}
+
+
} onClick={onRestart}>
+ Try again
+
+ >
+ ) : (
+ <>
+
Starting Open RAG
+
Loading the engine on this computer. Nothing goes online.
+
+ >
+ )}
+
+
+ );
+}
+
+export function Welcome({ onNewCategory }: { onNewCategory: () => void }) {
+ return (
+
+
+
+
+
+
Ask questions about your own documents
+
+ Organise your material into categories (a subject or a research area) and{" "}
+ sections (a course, a session, a project). Each section answers only from its own
+ folders, with sources you can open. Everything stays on this computer.
+
+
} onClick={onNewCategory}>
+ Create your first category
+
+
+
+ );
+}
+
+export function Pick({ text }: { text: string }) {
+ return {text}
;
+}
diff --git a/desktop/web/src/components/SectionPanel.tsx b/desktop/web/src/components/SectionPanel.tsx
new file mode 100644
index 0000000..68dfec5
--- /dev/null
+++ b/desktop/web/src/components/SectionPanel.tsx
@@ -0,0 +1,148 @@
+import { AlertTriangle, FileText, FolderOpen, FolderPlus, RefreshCw, X } from "lucide-react";
+import type { DocumentInfo, Section } from "../lib/types";
+import { fileName, shortFolder } from "../lib/text";
+import { Button, IconButton, ProgressBar, Spinner } from "./primitives";
+
+type Props = {
+ section: Section;
+ documents: DocumentInfo[] | null;
+ onAddFolder: () => void;
+ onRemoveFolder: (path: string) => void;
+ onIndex: () => void;
+ onOpenDocument: (path: string) => void;
+};
+
+export function SectionPanel({ section, documents, onAddFolder, onRemoveFolder, onIndex, onOpenDocument }: Props) {
+ const { status } = section;
+ const missing = new Set(status.missing_folders);
+ return (
+
+ } onClick={onAddFolder}>Add} />
+ {section.folders.length === 0 ? (
+
+ Add a folder with this section's documents.
+ PDF, Markdown and text files, including subfolders.
+
+ ) : (
+
+ {section.folders.map((folder) => (
+
+
+
+
{shortFolder(folder)}
+ {missing.has(folder) &&
Not found right now (unplugged?)
}
+
+ onRemoveFolder(folder)}>
+
+
+
+ ))}
+
+ )}
+
+
+
+
+ {documents === null ? (
+
+ ) : documents.length === 0 ? (
+ Nothing indexed yet.
+ ) : (
+
+ {documents.map((doc) => (
+
+ onOpenDocument(doc.source)}
+ className="flex w-full items-center gap-2 rounded-lg px-1.5 py-1 text-left text-[13px] hover:bg-card"
+ >
+
+ {doc.name}
+ {doc.chunks}
+
+
+ ))}
+
+ )}
+
+ );
+}
+
+function PanelTitle({ title, action }: { title: string; action?: React.ReactNode }) {
+ return (
+
+
{title}
+ {action}
+
+ );
+}
+
+function IndexCard({ section, onIndex }: { section: Section; onIndex: () => void }) {
+ const { status } = section;
+ if (status.state === "indexing") {
+ const progress = status.total ? status.done / status.total : 0;
+ return (
+
+
+ Indexing{status.total ? ` ${status.done} of ${status.total}` : "…"}
+
+
+ {status.current &&
{fileName(status.current)}
}
+
+ );
+ }
+ if (status.state === "error") {
+ return (
+
+
+
{status.error}
+
Try again
+
+ );
+ }
+ const report = status.report;
+ const never = !report && section.documents === 0;
+ return (
+
+
+
+ {never ? "Not indexed yet." : `${section.documents} ${section.documents === 1 ? "document" : "documents"} ready.`}
+
+
}
+ onClick={onIndex}
+ >
+ {never ? "Index" : "Update"}
+
+
+ {report && (
+
+ Last update: {report.added} new, {report.updated} changed, {report.removed} removed
+ {report.failed.length > 0 && (
+
+ {report.failed.length} couldn't be read
+
+ {report.failed.map((f) => (
+
+ {fileName(f.source)}
+
+ ))}
+
+
+ )}
+
+ )}
+
+ );
+}
diff --git a/desktop/web/src/components/Sidebar.tsx b/desktop/web/src/components/Sidebar.tsx
new file mode 100644
index 0000000..7d8c0cc
--- /dev/null
+++ b/desktop/web/src/components/Sidebar.tsx
@@ -0,0 +1,137 @@
+import { AlertCircle, BookOpen, ChevronRight, FolderClosed, Pencil, Plus, ShieldCheck, Trash2 } from "lucide-react";
+import { useState } from "react";
+import type { Category, Library, Scope, Section } from "../lib/types";
+import { Credits } from "./Credits";
+import { IconButton, Spinner } from "./primitives";
+
+type Props = {
+ library: Library | null;
+ selection: Scope | null;
+ onSelect: (scope: Scope) => void;
+ onNewCategory: () => void;
+ onNewSection: (category: Category) => void;
+ onRenameCategory: (category: Category) => void;
+ onDeleteCategory: (category: Category) => void;
+};
+
+export function Sidebar(props: Props) {
+ const { library, onNewCategory } = props;
+ return (
+
+ );
+}
+
+function CategoryGroup({
+ category,
+ sections,
+ selection,
+ onSelect,
+ onNewSection,
+ onRenameCategory,
+ onDeleteCategory,
+}: Props & { category: Category; sections: Section[] }) {
+ const [open, setOpen] = useState(true);
+ const selected = selection?.kind === "category" && selection.id === category.id;
+ return (
+
+
+
setOpen(!open)}>
+
+
+
onSelect({ kind: "category", id: category.id })}
+ title="Ask across every section in this category"
+ >
+
+ {category.name}
+
+
+
onNewSection(category)}>
+
+
+
onRenameCategory(category)}>
+
+
+
onDeleteCategory(category)}>
+
+
+
+
+ {open && (
+
+ {sections.map((section) => (
+
onSelect({ kind: "section", id: section.id })}
+ />
+ ))}
+ {sections.length === 0 && (
+ onNewSection(category)}
+ className="flex h-8 w-full items-center gap-2 rounded-lg px-2 text-[13px] text-ink-2 hover:bg-card-2 hover:text-ink"
+ >
+ Add a section
+
+ )}
+
+ )}
+
+ );
+}
+
+function SectionRow({ section, selected, onClick }: { section: Section; selected: boolean; onClick: () => void }) {
+ const { state } = section.status;
+ return (
+
+
+ {section.name}
+ {state === "indexing" ? (
+
+ ) : state === "error" ? (
+
+ ) : (
+ {section.documents || ""}
+ )}
+
+ );
+}
diff --git a/desktop/web/src/components/TitleBar.tsx b/desktop/web/src/components/TitleBar.tsx
new file mode 100644
index 0000000..9e227e5
--- /dev/null
+++ b/desktop/web/src/components/TitleBar.tsx
@@ -0,0 +1,45 @@
+import { Copy, Minus, Square, X } from "lucide-react";
+import { useEffect, useState, type ReactNode } from "react";
+import { host } from "../lib/host";
+import { LogoMark } from "./primitives";
+
+/** The window's title bar, drawn in the Arena's top-bar style. Dragging it moves the window, double-clicking maximises,
+ * and right-clicking shows the window menu, because it is a native drag region. */
+export function TitleBar({ children }: { children?: ReactNode }) {
+ const [maximized, setMaximized] = useState(false);
+ useEffect(() => host.onWindowState(setMaximized), []);
+ return (
+
+ );
+}
+
+function WindowButton({ label, danger, onClick, children }: { label: string; danger?: boolean; onClick: () => void; children: ReactNode }) {
+ return (
+
+ {children}
+
+ );
+}
diff --git a/desktop/web/src/components/primitives.tsx b/desktop/web/src/components/primitives.tsx
new file mode 100644
index 0000000..99f46a6
--- /dev/null
+++ b/desktop/web/src/components/primitives.tsx
@@ -0,0 +1,96 @@
+import type { ButtonHTMLAttributes, ReactNode } from "react";
+
+type Variant = "primary" | "secondary" | "ghost" | "danger" | "sun";
+
+const VARIANTS: Record = {
+ primary: "sticker-sm press bg-accent text-on-accent",
+ secondary: "sticker-sm press bg-card text-ink",
+ sun: "sticker-sm press bg-sun text-[#17183a]",
+ danger: "sticker-sm press bg-tomato text-white",
+ ghost: "rounded-xl text-ink-2 hover:bg-card-2 hover:text-ink",
+};
+
+/** The Arena's chunky button: outlined, with a hard shadow that lifts on hover. */
+export function Button({
+ variant = "secondary",
+ icon,
+ children,
+ className = "",
+ ...props
+}: ButtonHTMLAttributes & { variant?: Variant; icon?: ReactNode }) {
+ return (
+
+ {icon}
+ {children}
+
+ );
+}
+
+export function IconButton({
+ label,
+ children,
+ className = "",
+ ...props
+}: ButtonHTMLAttributes & { label: string }) {
+ return (
+
+ {children}
+
+ );
+}
+
+export function Spinner({ className = "size-4" }: { className?: string }) {
+ return (
+
+ );
+}
+
+/** The Arena's XP bar: an outlined track with a mint fill. */
+export function ProgressBar({ value }: { value: number }) {
+ return (
+
+ );
+}
+
+/** A small mono label, like the Arena's XP chips. */
+export function Chip({ children, tone = "neutral" }: { children: ReactNode; tone?: "neutral" | "accent" | "warn" | "bad" | "good" }) {
+ const tones = {
+ neutral: "border-line text-ink-2 bg-card",
+ accent: "border-accent text-accent bg-card",
+ warn: "border-edge text-[#17183a] bg-sun",
+ bad: "border-bad text-bad bg-card",
+ good: "border-edge text-[#17183a] bg-mint",
+ };
+ return (
+
+ {children}
+
+ );
+}
+
+/** The Arena's logo mark: a tilted tomato sticker. */
+export function LogoMark({ className = "" }: { className?: string }) {
+ return (
+
+ RAG
+
+ );
+}
diff --git a/desktop/web/src/hooks/useChat.test.ts b/desktop/web/src/hooks/useChat.test.ts
new file mode 100644
index 0000000..0d02478
--- /dev/null
+++ b/desktop/web/src/hooks/useChat.test.ts
@@ -0,0 +1,72 @@
+// @vitest-environment jsdom
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import type { EngineApi } from "../lib/api";
+import { chatKey, saveChat } from "../lib/chats";
+import type { AnswerDone, ChatMessage, Scope } from "../lib/types";
+import { useChat } from "./useChat";
+
+const A: Scope = { kind: "section", id: "a" };
+const B: Scope = { kind: "section", id: "b" };
+
+function answer(text: string): AnswerDone {
+ return { type: "done", question: "q", text, abstained: false, grounded: true, invalid_citations: [], citations: [], sources: [] };
+}
+
+/** An engine whose answers wait until the test releases them, so a reply can arrive after a scope switch. */
+function slowEngine() {
+ const pending: ((text: string) => void)[] = [];
+ const api = {
+ ask: (_scope: Scope, _q: string, _h: unknown, onToken: (t: string) => void) =>
+ new Promise((resolve) =>
+ pending.push((text) => {
+ onToken(text);
+ resolve(answer(text));
+ }),
+ ),
+ } as unknown as EngineApi;
+ return { api, release: (text: string) => pending.shift()?.(text) };
+}
+
+const saved = (scope: Scope) => JSON.parse(localStorage.getItem(chatKey(scope)) ?? "[]") as ChatMessage[];
+
+afterEach(() => localStorage.clear());
+
+describe("useChat", () => {
+ it("streams an answer into the current conversation and saves it", async () => {
+ const { api, release } = slowEngine();
+ const { result } = renderHook(() => useChat(api, A));
+ let sending!: Promise;
+ act(() => {
+ sending = result.current.send("power?");
+ });
+ expect(result.current.busy).toBe(true);
+ await act(async () => {
+ release("1.2 kW [1].");
+ await sending;
+ });
+ expect(result.current.busy).toBe(false);
+ expect(result.current.messages.map((m) => m.text)).toEqual(["power?", "1.2 kW [1]."]);
+ await waitFor(() => expect(saved(A).map((m) => m.text)).toEqual(["power?", "1.2 kW [1]."]));
+ });
+
+ it("a late reply never lands in, or overwrites, another section's conversation", async () => {
+ saveChat(localStorage, B, [{ id: "b1", role: "user", text: "B's question" }]);
+ const { api, release } = slowEngine();
+ const { result, rerender } = renderHook(({ scope }) => useChat(api, scope), { initialProps: { scope: A } });
+ let sending!: Promise;
+ act(() => {
+ sending = result.current.send("A's question");
+ });
+ rerender({ scope: B });
+ await act(async () => {
+ release("A's answer");
+ await sending;
+ });
+ expect(result.current.messages.map((m) => m.text)).toEqual(["B's question"]);
+ expect(result.current.busy).toBe(false);
+ await new Promise((r) => setTimeout(r, 500));
+ expect(saved(B).map((m) => m.text)).toEqual(["B's question"]);
+ expect(saved(A).every((m) => m.text !== "B's question")).toBe(true);
+ });
+});
diff --git a/desktop/web/src/hooks/useChat.ts b/desktop/web/src/hooks/useChat.ts
new file mode 100644
index 0000000..dbb715d
--- /dev/null
+++ b/desktop/web/src/hooks/useChat.ts
@@ -0,0 +1,97 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { EngineApi } from "../lib/api";
+import { clearChat, historyOf, loadChat, saveChat } from "../lib/chats";
+import type { ChatMessage, Scope } from "../lib/types";
+
+const newId = () => crypto.randomUUID();
+const SAVE_DELAY_MS = 400;
+
+const keyOf = (scope: Scope | null) => (scope ? `${scope.kind}:${scope.id}` : "");
+const scopeOf = (key: string): Scope | null => {
+ const [kind, id] = key.split(":");
+ return kind === "section" || kind === "category" ? { kind, id } : null;
+};
+
+/** Messages together with the conversation they belong to, so they can never be saved under another one. */
+type Conversation = { key: string; messages: ChatMessage[] };
+
+/** One conversation per section or category: streams answers in, keeps them on this computer.
+ *
+ * A reply that arrives after the user moved to another section (an aborted or finished answer) is dropped, because
+ * every change names the conversation it is for. */
+export function useChat(api: EngineApi | null, scope: Scope | null) {
+ const scopeKey = keyOf(scope);
+ const [conversation, setConversation] = useState({ key: "", messages: [] });
+ const [busy, setBusy] = useState(false);
+ const running = useRef(null);
+
+ // A new scope, or a restarted engine: stop what is running and load that scope's conversation.
+ useEffect(() => {
+ running.current?.abort();
+ running.current = null;
+ setBusy(false);
+ const target = scopeOf(scopeKey);
+ setConversation({ key: scopeKey, messages: target ? loadChat(localStorage, target) : [] });
+ }, [scopeKey, api]);
+
+ // Save after changes settle (not on every streamed token), under the conversation's own key.
+ useEffect(() => {
+ const target = scopeOf(conversation.key);
+ if (!target) return;
+ const timer = setTimeout(() => saveChat(localStorage, target, conversation.messages), SAVE_DELAY_MS);
+ return () => clearTimeout(timer);
+ }, [conversation]);
+
+ const messages = useMemo(
+ () => (conversation.key === scopeKey ? conversation.messages : []),
+ [conversation, scopeKey],
+ );
+
+ const send = useCallback(
+ async (question: string) => {
+ if (!api || !scope || running.current || !question.trim()) return;
+ const key = scopeKey;
+ const history = historyOf(messages);
+ const answerId = newId();
+ const controller = new AbortController();
+ running.current = controller;
+ setBusy(true);
+ const update = (change: (all: ChatMessage[]) => ChatMessage[]) =>
+ setConversation((c) => (c.key === key ? { key, messages: change(c.messages) } : c));
+ const patch = (change: (m: Extract) => ChatMessage) =>
+ update((all) => all.map((m) => (m.id === answerId && m.role === "assistant" ? change(m) : m)));
+ update((all) => [
+ ...all,
+ { id: newId(), role: "user", text: question.trim() },
+ { id: answerId, role: "assistant", text: "", status: "streaming" },
+ ]);
+ try {
+ const answer = await api.ask(scope, question.trim(), history, (token) => patch((m) => ({ ...m, text: m.text + token })), controller.signal);
+ patch((m) => ({ ...m, text: answer.text, status: "done", answer }));
+ } catch (error) {
+ if (error instanceof DOMException && error.name === "AbortError") {
+ patch((m) => ({ ...m, status: "stopped" }));
+ } else {
+ patch((m) => ({ ...m, status: "error", error: error instanceof Error ? error.message : String(error) }));
+ }
+ } finally {
+ if (running.current === controller) {
+ running.current = null;
+ setBusy(false);
+ }
+ }
+ },
+ [api, scope, scopeKey, messages],
+ );
+
+ const stop = useCallback(() => running.current?.abort(), []);
+
+ const clear = useCallback(() => {
+ const target = scopeOf(scopeKey);
+ if (!target) return;
+ clearChat(localStorage, target);
+ setConversation({ key: scopeKey, messages: [] });
+ }, [scopeKey]);
+
+ return { messages, busy, send, stop, clear };
+}
diff --git a/desktop/web/src/hooks/useEngine.ts b/desktop/web/src/hooks/useEngine.ts
new file mode 100644
index 0000000..4e3abf9
--- /dev/null
+++ b/desktop/web/src/hooks/useEngine.ts
@@ -0,0 +1,15 @@
+import { useEffect, useMemo, useState } from "react";
+import { Engine, type EngineApi } from "../lib/api";
+import { host, type EngineState } from "../lib/host";
+import { MockEngine } from "../lib/mock";
+
+/** The engine's state as the window reports it, and an API client once it is ready. */
+export function useEngine(): { engine: EngineState; api: EngineApi | null } {
+ const [engine, setEngine] = useState({ state: "starting" });
+ useEffect(() => host.onEngine(setEngine), []);
+ const api = useMemo(() => {
+ if (engine.state !== "ready") return null;
+ return engine.transport === "mock" ? new MockEngine() : new Engine(engine.transport);
+ }, [engine]);
+ return { engine, api };
+}
diff --git a/desktop/web/src/hooks/useLibrary.ts b/desktop/web/src/hooks/useLibrary.ts
new file mode 100644
index 0000000..1cbb067
--- /dev/null
+++ b/desktop/web/src/hooks/useLibrary.ts
@@ -0,0 +1,50 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { EngineApi } from "../lib/api";
+import type { Library } from "../lib/types";
+
+const POLL_MS = 1000;
+
+/** The categories and sections, refreshed after every change and every second while a section is indexing. */
+export function useLibrary(api: EngineApi | null, onError: (message: string) => void) {
+ const [library, setLibrary] = useState(null);
+ const errorRef = useRef(onError);
+ errorRef.current = onError;
+
+ const refresh = useCallback(async () => {
+ if (!api) return;
+ try {
+ setLibrary(await api.library());
+ } catch (error) {
+ errorRef.current(error instanceof Error ? error.message : String(error));
+ }
+ }, [api]);
+
+ useEffect(() => {
+ void refresh();
+ }, [refresh]);
+
+ const indexing = library?.sections.some((s) => s.status.state === "indexing") ?? false;
+ useEffect(() => {
+ if (!indexing) return;
+ const timer = setInterval(() => void refresh(), POLL_MS);
+ return () => clearInterval(timer);
+ }, [indexing, refresh]);
+
+ /** Runs a change against the engine, then refreshes; errors become a notice instead of a crash. */
+ const run = useCallback(
+ async (action: (api: EngineApi) => Promise): Promise => {
+ if (!api) return undefined;
+ try {
+ const result = await action(api);
+ await refresh();
+ return result;
+ } catch (error) {
+ errorRef.current(error instanceof Error ? error.message : String(error));
+ return undefined;
+ }
+ },
+ [api, refresh],
+ );
+
+ return { library, refresh, run };
+}
diff --git a/desktop/web/src/index.css b/desktop/web/src/index.css
new file mode 100644
index 0000000..7dffb60
--- /dev/null
+++ b/desktop/web/src/index.css
@@ -0,0 +1,189 @@
+@import "tailwindcss";
+@import "@fontsource/lilita-one/400.css";
+@import "@fontsource/atkinson-hyperlegible/400.css";
+@import "@fontsource/atkinson-hyperlegible/700.css";
+@import "@fontsource/ibm-plex-mono/500.css";
+@import "@fontsource/ibm-plex-mono/600.css";
+
+/* The AI Engineering Arena's "sticker arcade" theme: chunky ink outlines, hard offset shadows, candy accents on a
+ dot grid. Same tokens as the Arena site (ai-eng-lab/site/src/styles.css), with its dark variant. Fonts are bundled,
+ so the app looks the same offline. */
+:root {
+ --bg: #eaf2ff;
+ --dots: #c9d8f5;
+ --card: #ffffff;
+ --card-2: #f5f8ff;
+ --ink: #17183a;
+ --muted: #5d6290;
+ --edge: #17183a;
+ --shadow: #17183a;
+ --cobalt: #3f5bff;
+ --tomato: #ff6b4a;
+ --mint: #18b98d;
+ --sun: #ffc83d;
+ --pink: #ff7eb6;
+ --on-accent: #ffffff;
+ --done-bg: #dcf7ee;
+ --error: #d6362b;
+ color-scheme: light;
+}
+
+@media (prefers-color-scheme: dark) {
+ :root {
+ --bg: #121429;
+ --dots: #23264a;
+ --card: #1d2042;
+ --card-2: #262a52;
+ --ink: #f2f3ff;
+ --muted: #a3a8d6;
+ --edge: #05061a;
+ --shadow: #05061a;
+ --cobalt: #6f86ff;
+ --tomato: #ff8466;
+ --mint: #3fd9ac;
+ --sun: #ffd25e;
+ --pink: #ff96c4;
+ --on-accent: #10112a;
+ --done-bg: #183a35;
+ --error: #ff8a7a;
+ color-scheme: dark;
+ }
+}
+
+@theme inline {
+ --font-sans: "Atkinson Hyperlegible", "Segoe UI", system-ui, sans-serif;
+ --font-display: "Lilita One", "Arial Rounded MT Bold", "Trebuchet MS", sans-serif;
+ --font-mono: "IBM Plex Mono", ui-monospace, Consolas, monospace;
+ --color-bg: var(--bg);
+ --color-dots: var(--dots);
+ --color-card: var(--card);
+ --color-card-2: var(--card-2);
+ --color-ink: var(--ink);
+ --color-ink-2: var(--muted);
+ --color-ink-3: color-mix(in srgb, var(--muted) 72%, transparent);
+ --color-edge: var(--edge);
+ --color-line: color-mix(in srgb, var(--muted) 30%, transparent);
+ --color-fill: var(--card-2);
+ --color-accent: var(--cobalt);
+ --color-accent-tint: color-mix(in srgb, var(--cobalt) 14%, var(--card));
+ --color-on-accent: var(--on-accent);
+ --color-good: var(--mint);
+ --color-done: var(--done-bg);
+ --color-warn: var(--sun);
+ --color-warn-tint: color-mix(in srgb, var(--sun) 28%, var(--card));
+ --color-bad: var(--error);
+ --color-bad-tint: color-mix(in srgb, var(--tomato) 16%, var(--card));
+ --color-tomato: var(--tomato);
+ --color-sun: var(--sun);
+ --color-mint: var(--mint);
+ --color-pink: var(--pink);
+ --color-cobalt: var(--cobalt);
+}
+
+/* A card with the Arena's outline and hard shadow. */
+@utility sticker {
+ background: var(--card);
+ border: 2.5px solid var(--edge);
+ border-radius: 16px;
+ box-shadow: 4px 4px 0 var(--shadow);
+}
+
+@utility sticker-sm {
+ background: var(--card);
+ border: 2px solid var(--edge);
+ border-radius: 12px;
+ box-shadow: 2px 2px 0 var(--shadow);
+}
+
+/* Pressable stickers lift on hover and sink when clicked, like the Arena's buttons. */
+@utility press {
+ transition:
+ transform 0.12s ease,
+ box-shadow 0.12s ease;
+ &:hover {
+ transform: translate(-1px, -1px);
+ box-shadow: 4px 4px 0 var(--shadow);
+ }
+ &:active {
+ transform: translate(2px, 2px);
+ box-shadow: 1px 1px 0 var(--shadow);
+ }
+}
+
+html,
+body,
+#root {
+ height: 100%;
+ margin: 0;
+ overflow: hidden;
+}
+
+body {
+ background-color: var(--bg);
+ background-image: radial-gradient(var(--dots) 1.4px, transparent 1.6px);
+ background-size: 22px 22px;
+ color: var(--ink);
+ font-family: var(--font-sans);
+ -webkit-font-smoothing: antialiased;
+ user-select: none;
+}
+
+h1,
+h2,
+h3 {
+ font-family: var(--font-display);
+ font-weight: 400;
+ letter-spacing: 0.01em;
+}
+
+/* In the base layer, so components with their own focus style (the question box, dialog fields) can replace it. */
+@layer base {
+ :focus-visible {
+ outline: 3px solid var(--cobalt);
+ outline-offset: 2px;
+ }
+}
+
+textarea,
+input,
+.selectable {
+ user-select: text;
+}
+
+::-webkit-scrollbar {
+ width: 12px;
+ height: 12px;
+}
+
+::-webkit-scrollbar-thumb {
+ background: color-mix(in srgb, var(--muted) 45%, transparent);
+ border-radius: 999px;
+ border: 3px solid transparent;
+ background-clip: content-box;
+}
+
+::-webkit-scrollbar-track {
+ background: transparent;
+}
+
+@keyframes pop-in {
+ from {
+ transform: scale(0.9) rotate(-2deg);
+ opacity: 0;
+ }
+ to {
+ transform: none;
+ opacity: 1;
+ }
+}
+
+/* The top bar moves the window like a title bar (WebView2 non-client regions); its buttons stay clickable. */
+@utility drag {
+ -webkit-app-region: drag;
+ app-region: drag;
+}
+
+@utility no-drag {
+ -webkit-app-region: no-drag;
+ app-region: no-drag;
+}
diff --git a/desktop/web/src/lib/api.test.ts b/desktop/web/src/lib/api.test.ts
new file mode 100644
index 0000000..20a3b58
--- /dev/null
+++ b/desktop/web/src/lib/api.test.ts
@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { ApiError, Engine, type Reply, type Transport } from "./api";
+
+function fake(replies: Record, lines: string[] = [], streamReply: Reply = { status: 200, body: "" }) {
+ const sent: { method: string; path: string; body?: unknown }[] = [];
+ const transport: Transport = {
+ async send(method, path, body) {
+ sent.push({ method, path, body });
+ return replies[`${method} ${path}`] ?? { status: 404, body: '{"title":"Not found","detail":"Unknown"}' };
+ },
+ async stream(_path, _body, onLine) {
+ lines.forEach(onLine);
+ return streamReply;
+ },
+ };
+ return { engine: new Engine(transport), sent };
+}
+
+const done = { type: "done", question: "q", text: "1.2 kW [1].", abstained: false, grounded: true, invalid_citations: [], citations: [], sources: [] };
+
+describe("Engine", () => {
+ it("parses JSON replies and sends bodies", async () => {
+ const { engine, sent } = fake({ "POST /categories": { status: 201, body: '{"id":"a1","name":"Physics"}' } });
+ expect(await engine.addCategory("Physics")).toEqual({ id: "a1", name: "Physics" });
+ expect(sent).toEqual([{ method: "POST", path: "/categories", body: { name: "Physics" } }]);
+ });
+
+ it("treats 204 as no content", async () => {
+ const { engine } = fake({ "DELETE /sections/s1": { status: 204, body: "" } });
+ await expect(engine.deleteSection("s1")).resolves.toBeUndefined();
+ });
+
+ it("turns problem details into ApiError with the engine's explanation", async () => {
+ const { engine } = fake({ "GET /library": { status: 503, body: '{"title":"Engine unavailable","detail":"The engine isn\'t running."}' } });
+ await expect(engine.library()).rejects.toEqual(new ApiError(503, "The engine isn't running."));
+ });
+
+ it("streams tokens and returns the final answer", async () => {
+ const tokens: string[] = [];
+ const lines = ['{"type":"token","text":"1.2 "}', '{"type":"token","text":"kW [1]."}', JSON.stringify(done)];
+ const { engine } = fake({}, lines);
+ const answer = await engine.ask({ kind: "section", id: "s1" }, "q", [], (t) => tokens.push(t));
+ expect(tokens.join("")).toBe("1.2 kW [1].");
+ expect(answer.grounded).toBe(true);
+ });
+
+ it("reports a refused question and an error inside the stream", async () => {
+ const refused = fake({}, [], { status: 409, body: '{"detail":"Still indexing: Optics."}' }).engine;
+ await expect(refused.ask({ kind: "section", id: "s1" }, "q", [], () => {})).rejects.toThrow("Still indexing");
+ const broken = fake({}, ['{"type":"error","status":503,"title":"x","detail":"The local language model isn\'t running."}']).engine;
+ await expect(broken.ask({ kind: "category", id: "c1" }, "q", [], () => {})).rejects.toThrow("language model");
+ });
+
+ it("notices an answer that never finished", async () => {
+ const { engine } = fake({}, ['{"type":"token","text":"half"}']);
+ await expect(engine.ask({ kind: "section", id: "s1" }, "q", [], () => {})).rejects.toThrow("before it was complete");
+ });
+});
diff --git a/desktop/web/src/lib/api.ts b/desktop/web/src/lib/api.ts
new file mode 100644
index 0000000..a1ff70c
--- /dev/null
+++ b/desktop/web/src/lib/api.ts
@@ -0,0 +1,143 @@
+import { LineSplitter } from "./text";
+import type {
+ AnswerDone,
+ AskEvent,
+ Category,
+ DocumentInfo,
+ IndexStatus,
+ Library,
+ Scope,
+ Section,
+ Turn,
+} from "./types";
+
+/** Everything the interface asks of the engine. The real one goes through a transport; the mock one lives in memory. */
+export interface EngineApi {
+ library(): Promise;
+ addCategory(name: string): Promise;
+ renameCategory(id: string, name: string): Promise;
+ deleteCategory(id: string): Promise;
+ addSection(name: string, categoryId: string): Promise>;
+ updateSection(id: string, patch: { name?: string; category_id?: string }): Promise;
+ deleteSection(id: string): Promise;
+ addFolder(sectionId: string, path: string): Promise;
+ removeFolder(sectionId: string, path: string): Promise;
+ index(sectionId: string): Promise;
+ documents(sectionId: string): Promise;
+ ask(scope: Scope, question: string, history: Turn[], onToken: (text: string) => void, signal?: AbortSignal): Promise;
+}
+
+/** A failed request, with the engine's own explanation (RFC 9457 problem details). */
+export class ApiError extends Error {
+ readonly status: number;
+
+ constructor(status: number, message: string) {
+ super(message);
+ this.status = status;
+ }
+}
+
+export type Reply = { status: number; body: string };
+
+/** How requests reach the engine: through the Open RAG window (desktop) or straight over HTTP (browser development). */
+export interface Transport {
+ send(method: string, path: string, body?: unknown): Promise;
+ /** Streams NDJSON lines; resolves when the stream ends, or with the error reply if the engine refused it. */
+ stream(path: string, body: unknown, onLine: (line: string) => void, signal?: AbortSignal): Promise;
+}
+
+export function problem(reply: Reply): ApiError {
+ let detail = "";
+ try {
+ const parsed = JSON.parse(reply.body) as { detail?: string; title?: string };
+ detail = parsed.detail || parsed.title || "";
+ } catch {
+ // Not JSON: fall back to the status below.
+ }
+ return new ApiError(reply.status, detail || `Request failed (${reply.status}).`);
+}
+
+export class Engine implements EngineApi {
+ private readonly transport: Transport;
+
+ constructor(transport: Transport) {
+ this.transport = transport;
+ }
+
+ library = () => this.call("GET", "/library");
+ addCategory = (name: string) => this.call("POST", "/categories", { name });
+ renameCategory = (id: string, name: string) => this.call("PATCH", `/categories/${id}`, { name });
+ deleteCategory = (id: string) => this.call("DELETE", `/categories/${id}`);
+ addSection = (name: string, categoryId: string) =>
+ this.call>("POST", "/sections", { name, category_id: categoryId });
+ updateSection = (id: string, patch: { name?: string; category_id?: string }) => this.call("PATCH", `/sections/${id}`, patch);
+ deleteSection = (id: string) => this.call("DELETE", `/sections/${id}`);
+ addFolder = (sectionId: string, path: string) => this.call("POST", `/sections/${sectionId}/folders`, { path });
+ removeFolder = (sectionId: string, path: string) => this.call("POST", `/sections/${sectionId}/folders/remove`, { path });
+ index = (sectionId: string) => this.call("POST", `/sections/${sectionId}/index`);
+ documents = (sectionId: string) => this.call("GET", `/sections/${sectionId}/documents`);
+
+ async ask(scope: Scope, question: string, history: Turn[], onToken: (text: string) => void, signal?: AbortSignal) {
+ // Filled in by the stream callback; an object, because TypeScript can't follow assignments made inside callbacks.
+ const outcome: { answer: AnswerDone | null; failure: ApiError | null } = { answer: null, failure: null };
+ const reply = await this.transport.stream(
+ "/ask",
+ { scope, question, history },
+ (line) => {
+ const event = JSON.parse(line) as AskEvent;
+ if (event.type === "token") onToken(event.text);
+ else if (event.type === "done") outcome.answer = event;
+ else outcome.failure = new ApiError(event.status, event.detail);
+ },
+ signal,
+ );
+ if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+ if (reply.status >= 400) throw problem(reply);
+ if (outcome.failure) throw outcome.failure;
+ if (!outcome.answer) throw new ApiError(500, "The answer stopped before it was complete.");
+ return outcome.answer;
+ }
+
+ private async call(method: string, path: string, body?: unknown): Promise {
+ const reply = await this.transport.send(method, path, body);
+ if (reply.status >= 400 || reply.status === 0) throw problem(reply);
+ return (reply.body ? JSON.parse(reply.body) : undefined) as T;
+ }
+}
+
+/** Straight to `ore serve` over HTTP, for working on the interface in a browser (`?api=...&token=...`). */
+export function httpTransport(baseUrl: string, token: string): Transport {
+ const base = baseUrl.replace(/\/$/, "");
+ const request = async (method: string, path: string, body?: unknown, signal?: AbortSignal) => {
+ try {
+ return await fetch(base + path, {
+ method,
+ signal,
+ headers: { Authorization: `Bearer ${token}`, ...(body ? { "Content-Type": "application/json" } : {}) },
+ body: body ? JSON.stringify(body) : undefined,
+ });
+ } catch (error) {
+ if (error instanceof DOMException && error.name === "AbortError") throw error;
+ return new Response(JSON.stringify({ detail: "Can't reach the engine." }), { status: 503 });
+ }
+ };
+ return {
+ async send(method, path, body) {
+ const response = await request(method, path, body);
+ return { status: response.status, body: response.status === 204 ? "" : await response.text() };
+ },
+ async stream(path, body, onLine, signal) {
+ const response = await request("POST", path, body, signal);
+ if (!response.ok || !response.body) return { status: response.status, body: await response.text() };
+ const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+ const lines = new LineSplitter();
+ for (;;) {
+ const { value, done } = await reader.read();
+ if (done) break;
+ lines.push(value).forEach(onLine);
+ }
+ lines.flush().forEach(onLine);
+ return { status: response.status, body: "" };
+ },
+ };
+}
diff --git a/desktop/web/src/lib/chats.test.ts b/desktop/web/src/lib/chats.test.ts
new file mode 100644
index 0000000..aeaf744
--- /dev/null
+++ b/desktop/web/src/lib/chats.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { chatKey, clearChat, historyOf, loadChat, saveChat, type KeyValueStore } from "./chats";
+import type { ChatMessage } from "./types";
+
+function memory(): KeyValueStore & { data: Map } {
+ const data = new Map();
+ return {
+ data,
+ getItem: (k) => data.get(k) ?? null,
+ setItem: (k, v) => void data.set(k, v),
+ removeItem: (k) => void data.delete(k),
+ };
+}
+
+const scope = { kind: "section", id: "abc" } as const;
+const user = (text: string): ChatMessage => ({ id: text, role: "user", text });
+const bot = (text: string, status: "done" | "streaming" | "error" = "done"): ChatMessage => ({
+ id: `a-${text}`,
+ role: "assistant",
+ text,
+ status,
+});
+
+describe("chats", () => {
+ it("saves finished messages per scope and loads them back", () => {
+ const store = memory();
+ saveChat(store, scope, [user("q1"), bot("a1"), user("q2"), bot("…", "streaming")]);
+ expect(loadChat(store, scope).map((m) => m.text)).toEqual(["q1", "a1", "q2"]);
+ expect(loadChat(store, { kind: "category", id: "abc" })).toEqual([]);
+ clearChat(store, scope);
+ expect(store.data.has(chatKey(scope))).toBe(false);
+ });
+
+ it("survives corrupt storage", () => {
+ const store = memory();
+ store.setItem(chatKey(scope), "{not json");
+ expect(loadChat(store, scope)).toEqual([]);
+ });
+
+ it("builds history only from completed exchanges", () => {
+ const history = historyOf([user("q1"), bot("a1"), user("q2"), bot("x", "error"), user("q3"), bot("a3")]);
+ expect(history).toEqual([
+ { question: "q1", answer: "a1" },
+ { question: "q3", answer: "a3" },
+ ]);
+ });
+});
diff --git a/desktop/web/src/lib/chats.ts b/desktop/web/src/lib/chats.ts
new file mode 100644
index 0000000..eee828b
--- /dev/null
+++ b/desktop/web/src/lib/chats.ts
@@ -0,0 +1,50 @@
+import type { ChatMessage, Scope, Turn } from "./types";
+
+const MAX_SAVED = 60;
+const HISTORY_TURNS = 6;
+
+/** Minimal storage interface so tests can pass a fake. */
+export type KeyValueStore = Pick;
+
+export const chatKey = (scope: Scope) => `openrag.chat.${scope.kind}.${scope.id}`;
+
+/** Conversations are kept per section or category on this computer, so they survive restarts. */
+export function loadChat(store: KeyValueStore, scope: Scope): ChatMessage[] {
+ try {
+ const raw = store.getItem(chatKey(scope));
+ const parsed: unknown = raw ? JSON.parse(raw) : [];
+ return Array.isArray(parsed) ? (parsed as ChatMessage[]) : [];
+ } catch {
+ return [];
+ }
+}
+
+export function saveChat(store: KeyValueStore, scope: Scope, messages: ChatMessage[]): void {
+ const finished = messages.filter((m) => m.role === "user" || m.status !== "streaming").slice(-MAX_SAVED);
+ try {
+ store.setItem(chatKey(scope), JSON.stringify(finished));
+ } catch {
+ // Storage full or unavailable: the conversation still works, it just isn't kept.
+ }
+}
+
+export function clearChat(store: KeyValueStore, scope: Scope): void {
+ try {
+ store.removeItem(chatKey(scope));
+ } catch {
+ // Nothing to clear.
+ }
+}
+
+/** The last few completed question/answer pairs, so follow-up questions can be understood. */
+export function historyOf(messages: ChatMessage[]): Turn[] {
+ const turns: Turn[] = [];
+ for (let i = 0; i < messages.length - 1; i++) {
+ const asked = messages[i];
+ const answered = messages[i + 1];
+ if (asked.role === "user" && answered.role === "assistant" && answered.status === "done") {
+ turns.push({ question: asked.text, answer: answered.text });
+ }
+ }
+ return turns.slice(-HISTORY_TURNS);
+}
diff --git a/desktop/web/src/lib/credits.ts b/desktop/web/src/lib/credits.ts
new file mode 100644
index 0000000..70ff629
--- /dev/null
+++ b/desktop/web/src/lib/credits.ts
@@ -0,0 +1,29 @@
+/** The people who made Open RAG, shown in the Credits sheet. The desktop window opens only links on its own list
+ * (ExternalLinks in OpenRag.Core), and a test there checks that every link here is on it. */
+
+export type Credit = {
+ name: string;
+ initials: string;
+ role: string;
+ github: string;
+ linkedin: string;
+};
+
+export const CREDITS: readonly Credit[] = [
+ {
+ name: "Wadi Touil",
+ initials: "WT",
+ role: "Embedded Systems Engineer",
+ github: "https://github.com/TWadi",
+ linkedin: "https://www.linkedin.com/in/wadi-touil-117472319/",
+ },
+ {
+ name: "Ghassen Jamoussi",
+ initials: "GJ",
+ role: "Embedded Systems Developer",
+ github: "https://github.com/GhassenJamoussi99",
+ linkedin: "https://www.linkedin.com/in/ghassen-jamoussi/",
+ },
+];
+
+export const SOURCE_URL = "https://github.com/Carthavate/open-rag-engine";
diff --git a/desktop/web/src/lib/host.ts b/desktop/web/src/lib/host.ts
new file mode 100644
index 0000000..99fed65
--- /dev/null
+++ b/desktop/web/src/lib/host.ts
@@ -0,0 +1,154 @@
+/** The bridge to the Open RAG window (WPF + WebView2). The page reaches the engine only through the window: API calls
+ * and questions travel as messages, and the window forwards them with the engine's token, which the page never sees.
+ * In a normal browser it falls back to the mock engine, or to a real `ore serve` given as ?api=...&token=... */
+
+import { httpTransport, type Reply, type Transport } from "./api";
+
+export type EngineState =
+ | { state: "starting" }
+ | { state: "ready"; transport: Transport | "mock" }
+ | { state: "failed"; message: string };
+
+export interface Host {
+ readonly isDesktop: boolean;
+ onEngine(listener: (state: EngineState) => void): () => void;
+ onNotice(listener: (message: string) => void): () => void;
+ pickFolder(): Promise;
+ openSource(path: string): void;
+ revealSource(path: string): void;
+ restartEngine(): void;
+ /** Opens a web page in the default browser; the window opens only the links on its own list. */
+ openLink(url: string): void;
+ /** The custom title bar's buttons; only the desktop window has them. */
+ windowAction(action: "minimize" | "maximize" | "close"): void;
+ onWindowState(listener: (maximized: boolean) => void): () => void;
+}
+
+interface WebViewBridge {
+ postMessage(message: unknown): void;
+ addEventListener(type: "message", listener: (e: MessageEvent) => void): void;
+ removeEventListener(type: "message", listener: (e: MessageEvent) => void): void;
+}
+
+declare global {
+ interface Window {
+ chrome?: { webview?: WebViewBridge };
+ }
+}
+
+type HostMessage =
+ | { type: "engine"; state: "starting" | "ready" | "failed"; message?: string }
+ | { type: "folderPicked"; id: string; path: string | null }
+ | { type: "notice"; message: string }
+ | { type: "windowState"; maximized: boolean }
+ | { type: "apiResult"; id: string; status: number; body: string }
+ | { type: "askLine"; id: string; line: string }
+ | { type: "askEnd"; id: string; status: number; body: string };
+
+/** Library calls are quick; one that takes this long means the engine is stuck. Answers stream and have no limit. */
+const API_TIMEOUT_MS = 120_000;
+
+function desktopHost(bridge: WebViewBridge): Host {
+ const listen = (handler: (m: HostMessage) => void) => {
+ const listener = (e: MessageEvent) => handler(e.data as HostMessage);
+ bridge.addEventListener("message", listener);
+ return () => bridge.removeEventListener("message", listener);
+ };
+
+ /** Sends a message and resolves with the first reply that carries the same id. */
+ const request = (message: Record, isReply: (m: HostMessage, id: string) => m is T) => {
+ const id = crypto.randomUUID();
+ return new Promise((resolve) => {
+ const stop = listen((m) => {
+ if (m && isReply(m, id)) {
+ stop();
+ resolve(m);
+ }
+ });
+ bridge.postMessage({ ...message, id });
+ });
+ };
+
+ const timedOut: Reply = { status: 504, body: '{"detail":"The engine took too long to answer. Try again."}' };
+
+ const transport: Transport = {
+ async send(method, path, body) {
+ const reply = await Promise.race([
+ request(
+ { type: "api", method, path, body: body ?? null },
+ (m, id): m is Extract => m.type === "apiResult" && m.id === id,
+ ),
+ new Promise((resolve) => setTimeout(() => resolve(null), API_TIMEOUT_MS)),
+ ]);
+ return reply ? { status: reply.status, body: reply.body } : timedOut;
+ },
+ stream(_path, body, onLine, signal) {
+ const id = crypto.randomUUID();
+ return new Promise((resolve) => {
+ const cancel = () => bridge.postMessage({ type: "cancel", id });
+ const stop = listen((m) => {
+ if (m?.type === "askLine" && m.id === id) onLine(m.line);
+ if (m?.type === "askEnd" && m.id === id) {
+ stop();
+ signal?.removeEventListener("abort", cancel);
+ resolve({ status: m.status, body: m.body });
+ }
+ });
+ signal?.addEventListener("abort", cancel);
+ bridge.postMessage({ type: "ask", id, body });
+ });
+ },
+ };
+
+ return {
+ isDesktop: true,
+ onEngine(listener) {
+ const stop = listen((m) => {
+ if (m?.type !== "engine") return;
+ if (m.state === "ready") listener({ state: "ready", transport });
+ else if (m.state === "failed") listener({ state: "failed", message: m.message ?? "The engine couldn't start." });
+ else listener({ state: "starting" });
+ });
+ bridge.postMessage({ type: "ready" });
+ return stop;
+ },
+ onNotice: (listener) => listen((m) => m?.type === "notice" && listener(m.message)),
+ async pickFolder() {
+ const reply = await request(
+ { type: "pickFolder" },
+ (m, id): m is Extract => m.type === "folderPicked" && m.id === id,
+ );
+ return reply.path;
+ },
+ openSource: (path) => bridge.postMessage({ type: "openSource", path }),
+ revealSource: (path) => bridge.postMessage({ type: "revealSource", path }),
+ restartEngine: () => bridge.postMessage({ type: "restartEngine" }),
+ openLink: (url) => bridge.postMessage({ type: "openLink", url }),
+ windowAction: (action) => bridge.postMessage({ type: "window", action }),
+ onWindowState: (listener) => listen((m) => m?.type === "windowState" && listener(m.maximized)),
+ };
+}
+
+function browserHost(): Host {
+ const params = new URLSearchParams(window.location.search);
+ const api = params.get("api");
+ const token = params.get("token");
+ const engine: EngineState = { state: "ready", transport: api && token ? httpTransport(api, token) : "mock" };
+ return {
+ isDesktop: false,
+ onEngine(listener) {
+ listener(engine);
+ return () => {};
+ },
+ onNotice: () => () => {},
+ pickFolder: async () => window.prompt("Folder path (browser preview)") || null,
+ openSource: (path) => window.alert(`Would open ${path}`),
+ revealSource: (path) => window.alert(`Would show ${path} in Explorer`),
+ restartEngine: () => window.location.reload(),
+ openLink: (url) => window.open(url, "_blank", "noopener,noreferrer"),
+ windowAction: () => {},
+ onWindowState: () => () => {},
+ };
+}
+
+export const host: Host = window.chrome?.webview ? desktopHost(window.chrome.webview) : browserHost();
diff --git a/desktop/web/src/lib/mock.ts b/desktop/web/src/lib/mock.ts
new file mode 100644
index 0000000..e459a2e
--- /dev/null
+++ b/desktop/web/src/lib/mock.ts
@@ -0,0 +1,154 @@
+import { ApiError, type EngineApi } from "./api";
+import { IDLE, type AnswerDone, type Category, type IndexStatus, type Library, type Scope, type Section, type Source } from "./types";
+
+const delay = (ms: number, signal?: AbortSignal) =>
+ new Promise((resolve, reject) => {
+ const timer = setTimeout(resolve, ms);
+ signal?.addEventListener("abort", () => {
+ clearTimeout(timer);
+ reject(new DOMException("Aborted", "AbortError"));
+ });
+ });
+
+let counter = 0;
+const newId = () => `m${++counter}`;
+
+/** Pretends to be the engine in a normal browser, so the interface can be designed without Python or models. */
+export class MockEngine implements EngineApi {
+ private state: Library;
+ private readonly docs = new Map();
+
+ constructor() {
+ const physics: Category = { id: newId(), name: "Physics" };
+ const research: Category = { id: newId(), name: "Thesis research" };
+ const optics = this.section("Lesson 3: Optics", physics.id, ["C:/Courses/Physics/Optics"]);
+ const papers = this.section("Retrieval papers", research.id, ["D:/Research/Papers"]);
+ this.docs.set(optics.id, ["refraction.pdf", "lenses.md", "lab-sheet.pdf"]);
+ this.docs.set(papers.id, ["rrf-cormack-2009.pdf", "colbert.pdf"]);
+ this.state = {
+ categories: [physics, research],
+ sections: [
+ { ...optics, documents: 3 },
+ { ...papers, documents: 2 },
+ ],
+ };
+ }
+
+ private section(name: string, categoryId: string, folders: string[] = []): Section {
+ return { id: newId(), name, category_id: categoryId, folders, documents: 0, status: IDLE };
+ }
+
+ async library() {
+ await delay(120);
+ return structuredClone(this.state);
+ }
+
+ async addCategory(name: string) {
+ const category = { id: newId(), name };
+ this.state = { ...this.state, categories: [...this.state.categories, category] };
+ return category;
+ }
+
+ async renameCategory(id: string, name: string) {
+ this.state = { ...this.state, categories: this.state.categories.map((c) => (c.id === id ? { ...c, name } : c)) };
+ return { id, name };
+ }
+
+ async deleteCategory(id: string) {
+ if (this.state.sections.some((s) => s.category_id === id)) {
+ throw new ApiError(422, "Move or delete the sections in this category first");
+ }
+ this.state = { ...this.state, categories: this.state.categories.filter((c) => c.id !== id) };
+ }
+
+ async addSection(name: string, categoryId: string) {
+ const section = this.section(name, categoryId);
+ this.state = { ...this.state, sections: [...this.state.sections, section] };
+ return section;
+ }
+
+ async updateSection(id: string, patch: { name?: string; category_id?: string }) {
+ this.patch(id, (s) => ({ ...s, ...patch }));
+ }
+
+ async deleteSection(id: string) {
+ this.state = { ...this.state, sections: this.state.sections.filter((s) => s.id !== id) };
+ }
+
+ async addFolder(sectionId: string, path: string) {
+ this.patch(sectionId, (s) => ({ ...s, folders: s.folders.includes(path) ? s.folders : [...s.folders, path] }));
+ }
+
+ async removeFolder(sectionId: string, path: string) {
+ this.patch(sectionId, (s) => ({ ...s, folders: s.folders.filter((f) => f !== path) }));
+ }
+
+ async index(sectionId: string): Promise {
+ const total = Math.max(1, this.get(sectionId).folders.length * 4);
+ const names = Array.from({ length: total }, (_, i) => `document-${i + 1}.pdf`);
+ this.docs.set(sectionId, names);
+ const step = (done: number) => {
+ const finished = done >= total;
+ const status: IndexStatus = finished
+ ? { ...IDLE, done, total, report: { added: total, updated: 0, unchanged: 0, removed: 0, failed: [] } }
+ : { ...IDLE, state: "indexing", done, total, current: names[done] };
+ this.patch(sectionId, (s) => ({ ...s, status, documents: finished ? total : s.documents }));
+ if (!finished) setTimeout(() => step(done + 1), 450);
+ };
+ step(0);
+ return this.get(sectionId).status;
+ }
+
+ async documents(sectionId: string) {
+ return (this.docs.get(sectionId) ?? []).map((name) => ({ source: `C:/Docs/${name}`, name, chunks: 4 }));
+ }
+
+ async ask(scope: Scope, question: string, _history: unknown, onToken: (t: string) => void, signal?: AbortSignal) {
+ const sectionId = scope.kind === "section" ? scope.id : this.state.sections.find((s) => s.category_id === scope.id)?.id;
+ const names = sectionId ? (this.docs.get(sectionId) ?? []) : [];
+ if (names.length === 0) {
+ const abstain = "I don't know based on the provided documents.";
+ onToken(abstain);
+ return this.done(question, abstain, [], true);
+ }
+ const sources: Source[] = names.slice(0, 3).map((name, i) => ({
+ number: i + 1,
+ label: name,
+ source: `C:/Docs/${name}`,
+ page: name.endsWith(".pdf") ? i + 2 : null,
+ section_id: sectionId ?? null,
+ score: 4 - i,
+ snippet: `A passage from ${name} that talks about ${question.toLowerCase().replace(/\?$/, "")} in some detail…`,
+ }));
+ const text = `Here is what your documents say: light bends when it passes between materials of different density [1], which is why a lens can focus it [2].`;
+ for (const word of text.split(/(?<= )/)) {
+ await delay(35, signal);
+ onToken(word);
+ }
+ return this.done(question, text, sources, false);
+ }
+
+ private done(question: string, text: string, sources: Source[], abstained: boolean): AnswerDone {
+ return {
+ type: "done",
+ question,
+ text,
+ abstained,
+ grounded: !abstained,
+ invalid_citations: [],
+ citations: sources.slice(0, 2),
+ sources,
+ };
+ }
+
+ private get(id: string): Section {
+ const section = this.state.sections.find((s) => s.id === id);
+ if (!section) throw new ApiError(404, `Unknown section: ${id}`);
+ return section;
+ }
+
+ private patch(id: string, change: (s: Section) => Section) {
+ this.get(id);
+ this.state = { ...this.state, sections: this.state.sections.map((s) => (s.id === id ? change(s) : s)) };
+ }
+}
diff --git a/desktop/web/src/lib/text.test.ts b/desktop/web/src/lib/text.test.ts
new file mode 100644
index 0000000..34b4b98
--- /dev/null
+++ b/desktop/web/src/lib/text.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { fileName, LineSplitter, shortFolder, splitCitations } from "./text";
+
+describe("LineSplitter", () => {
+ it("joins lines split across chunks and drops blank ones", () => {
+ const lines = new LineSplitter();
+ expect(lines.push('{"n":1}\n{"n"')).toEqual(['{"n":1}']);
+ expect(lines.push(":2}\n\n")).toEqual(['{"n":2}']);
+ expect(lines.push('{"n":3}')).toEqual([]);
+ expect(lines.flush()).toEqual(['{"n":3}']);
+ expect(lines.flush()).toEqual([]);
+ });
+});
+
+describe("splitCitations", () => {
+ it("turns [n] and [n, m] into citation parts", () => {
+ expect(splitCitations("It draws 1.2 kW [1][2, 3].")).toEqual([
+ { kind: "text", text: "It draws 1.2 kW " },
+ { kind: "cite", numbers: [1] },
+ { kind: "cite", numbers: [2, 3] },
+ { kind: "text", text: "." },
+ ]);
+ });
+
+ it("leaves text without citations alone", () => {
+ expect(splitCitations("No sources.")).toEqual([{ kind: "text", text: "No sources." }]);
+ expect(splitCitations("")).toEqual([]);
+ });
+});
+
+describe("paths", () => {
+ it("shows file names and short folders", () => {
+ expect(fileName("C:/Courses/Physics/lecture 3.pdf")).toBe("lecture 3.pdf");
+ expect(fileName("C:\\a\\b.md")).toBe("b.md");
+ expect(shortFolder("C:/Courses/Physics/")).toBe("Courses › Physics");
+ });
+});
diff --git a/desktop/web/src/lib/text.ts b/desktop/web/src/lib/text.ts
new file mode 100644
index 0000000..497aa75
--- /dev/null
+++ b/desktop/web/src/lib/text.ts
@@ -0,0 +1,45 @@
+/** Splits a stream of text chunks into complete lines (the engine streams answers as one JSON object per line). */
+export class LineSplitter {
+ private buffer = "";
+
+ push(chunk: string): string[] {
+ this.buffer += chunk;
+ const lines = this.buffer.split("\n");
+ this.buffer = lines.pop() ?? "";
+ return lines.filter((line) => line.trim());
+ }
+
+ flush(): string[] {
+ const rest = this.buffer;
+ this.buffer = "";
+ return rest.trim() ? [rest] : [];
+ }
+}
+
+export type AnswerPart = { kind: "text"; text: string } | { kind: "cite"; numbers: number[] };
+
+const CITATION = /\[(\d+(?:\s*,\s*\d+)*)\]/g;
+
+/** "It draws 1.2 kW [1][2, 3]." becomes text and citation parts, so citations can be drawn as clickable pills. */
+export function splitCitations(text: string): AnswerPart[] {
+ const parts: AnswerPart[] = [];
+ let last = 0;
+ for (const match of text.matchAll(CITATION)) {
+ if (match.index > last) parts.push({ kind: "text", text: text.slice(last, match.index) });
+ parts.push({ kind: "cite", numbers: match[1].split(",").map((n) => Number(n.trim())) });
+ last = match.index + match[0].length;
+ }
+ if (last < text.length) parts.push({ kind: "text", text: text.slice(last) });
+ return parts;
+}
+
+/** "C:/Courses/Physics/lecture 3.pdf" -> "lecture 3.pdf" */
+export function fileName(path: string): string {
+ return path.split(/[\\/]/).filter(Boolean).pop() ?? path;
+}
+
+/** "C:/Courses/Physics" -> "Courses › Physics" (the last two folders), for compact folder rows. */
+export function shortFolder(path: string): string {
+ const parts = path.split(/[\\/]/).filter(Boolean);
+ return parts.slice(-2).join(" › ") || path;
+}
diff --git a/desktop/web/src/lib/types.ts b/desktop/web/src/lib/types.ts
new file mode 100644
index 0000000..d5ec27c
--- /dev/null
+++ b/desktop/web/src/lib/types.ts
@@ -0,0 +1,88 @@
+/** The shapes the engine's local API returns (see open_rag_engine/api.py). */
+
+export type Category = { id: string; name: string };
+
+export type IndexState = "idle" | "indexing" | "error";
+
+export type IndexReport = {
+ added: number;
+ updated: number;
+ unchanged: number;
+ removed: number;
+ failed: { source: string; error: string }[];
+};
+
+export type IndexStatus = {
+ state: IndexState;
+ done: number;
+ total: number;
+ current: string | null;
+ error: string | null;
+ missing_folders: string[];
+ report: IndexReport | null;
+};
+
+export type Section = {
+ id: string;
+ name: string;
+ category_id: string;
+ folders: string[];
+ documents: number;
+ status: IndexStatus;
+};
+
+export type Library = { categories: Category[]; sections: Section[] };
+
+export type DocumentInfo = { source: string; name: string; chunks: number };
+
+export type Source = {
+ number: number;
+ label: string;
+ source: string;
+ page: number | null;
+ section_id: string | null;
+ score: number;
+ snippet: string;
+};
+
+export type AnswerDone = {
+ type: "done";
+ question: string;
+ text: string;
+ abstained: boolean;
+ grounded: boolean;
+ invalid_citations: number[];
+ citations: Source[];
+ sources: Source[];
+};
+
+export type AskEvent =
+ | { type: "token"; text: string }
+ | AnswerDone
+ | { type: "error"; status: number; title: string; detail: string };
+
+export type ScopeKind = "section" | "category";
+export type Scope = { kind: ScopeKind; id: string };
+
+export type Turn = { question: string; answer: string };
+
+export type ChatMessage =
+ | { id: string; role: "user"; text: string }
+ | {
+ id: string;
+ role: "assistant";
+ text: string;
+ status: "streaming" | "done" | "error" | "stopped";
+ answer?: AnswerDone;
+ error?: string;
+ };
+
+export const IDLE: IndexStatus = {
+ state: "idle",
+ done: 0,
+ total: 0,
+ current: null,
+ error: null,
+ missing_folders: [],
+ report: null,
+};
diff --git a/desktop/web/src/main.tsx b/desktop/web/src/main.tsx
new file mode 100644
index 0000000..c2a145c
--- /dev/null
+++ b/desktop/web/src/main.tsx
@@ -0,0 +1,10 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import App from "./App";
+import "./index.css";
+
+createRoot(document.getElementById("root")!).render(
+
+
+ ,
+);
diff --git a/desktop/web/src/vite-env.d.ts b/desktop/web/src/vite-env.d.ts
new file mode 100644
index 0000000..11f02fe
--- /dev/null
+++ b/desktop/web/src/vite-env.d.ts
@@ -0,0 +1 @@
+///
diff --git a/desktop/web/tsconfig.app.json b/desktop/web/tsconfig.app.json
new file mode 100644
index 0000000..c9ccbd4
--- /dev/null
+++ b/desktop/web/tsconfig.app.json
@@ -0,0 +1,27 @@
+{
+ "compilerOptions": {
+ "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+ "target": "ES2020",
+ "useDefineForClassFields": true,
+ "lib": ["ES2020", "DOM", "DOM.Iterable"],
+ "module": "ESNext",
+ "skipLibCheck": true,
+
+ /* Bundler mode */
+ "moduleResolution": "bundler",
+ "allowImportingTsExtensions": true,
+ "verbatimModuleSyntax": true,
+ "moduleDetection": "force",
+ "noEmit": true,
+ "jsx": "react-jsx",
+
+ /* Linting */
+ "strict": true,
+ "noUnusedLocals": true,
+ "noUnusedParameters": true,
+ "erasableSyntaxOnly": true,
+ "noFallthroughCasesInSwitch": true,
+ "noUncheckedSideEffectImports": true
+ },
+ "include": ["src"]
+}
diff --git a/desktop/web/tsconfig.json b/desktop/web/tsconfig.json
new file mode 100644
index 0000000..1ffef60
--- /dev/null
+++ b/desktop/web/tsconfig.json
@@ -0,0 +1,7 @@
+{
+ "files": [],
+ "references": [
+ { "path": "./tsconfig.app.json" },
+ { "path": "./tsconfig.node.json" }
+ ]
+}
diff --git a/desktop/web/tsconfig.node.json b/desktop/web/tsconfig.node.json
new file mode 100644
index 0000000..9728af2
--- /dev/null
+++ b/desktop/web/tsconfig.node.json
@@ -0,0 +1,25 @@
+{
+ "compilerOptions": {
+ "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+ "target": "ES2022",
+ "lib": ["ES2023"],
+ "module": "ESNext",
+ "skipLibCheck": true,
+
+ /* Bundler mode */
+ "moduleResolution": "bundler",
+ "allowImportingTsExtensions": true,
+ "verbatimModuleSyntax": true,
+ "moduleDetection": "force",
+ "noEmit": true,
+
+ /* Linting */
+ "strict": true,
+ "noUnusedLocals": true,
+ "noUnusedParameters": true,
+ "erasableSyntaxOnly": true,
+ "noFallthroughCasesInSwitch": true,
+ "noUncheckedSideEffectImports": true
+ },
+ "include": ["vite.config.ts"]
+}
diff --git a/desktop/web/vite.config.ts b/desktop/web/vite.config.ts
new file mode 100644
index 0000000..32a5f7e
--- /dev/null
+++ b/desktop/web/vite.config.ts
@@ -0,0 +1,34 @@
+import { defineConfig } from "vitest/config";
+import type { Plugin } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+
+/** The built page may load only its own files and may not connect anywhere: it reaches the engine through WebView2
+ * messages, so even a compromised dependency couldn't send documents off the computer. Build only, because the dev
+ * server needs inline scripts and a websocket. */
+const CONTENT_SECURITY_POLICY = [
+ "default-src 'self'",
+ "script-src 'self'",
+ "style-src 'self' 'unsafe-inline'",
+ "img-src 'self' data:",
+ "font-src 'self'",
+ "connect-src 'none'",
+ "object-src 'none'",
+ "base-uri 'none'",
+ "form-action 'none'",
+].join("; ");
+
+const contentSecurityPolicy: Plugin = {
+ name: "content-security-policy",
+ apply: "build",
+ transformIndexHtml: (html) =>
+ html.replace("", `\n `),
+};
+
+// base "./" because the built files are served from the Open RAG app's folder, not a web server root.
+export default defineConfig({
+ base: "./",
+ plugins: [react(), tailwindcss(), contentSecurityPolicy],
+ server: { port: 5176, strictPort: true },
+ test: { environment: "node", include: ["src/**/*.test.ts"] },
+});
diff --git a/docs/adr/0007-desktop-app.md b/docs/adr/0007-desktop-app.md
index 0fb9674..5929e8c 100644
--- a/docs/adr/0007-desktop-app.md
+++ b/docs/adr/0007-desktop-app.md
@@ -35,11 +35,15 @@ Option 1, the same structure as our Duet app.
- It ties the engine to a job object, so the engine dies with the app. `--parent-pid` is the backstop.
- **Interface (React and Tailwind, in WebView2).**
- It is served from the app's own files on a virtual host (`https://app.ore`), so it needs no network.
- - It calls the engine's API directly, with the token the shell hands it, and streams answers as newline-delimited JSON.
-- **Engine API (FastAPI, `ore serve`).** It is reachable only from this machine, through three guards:
+ - It reaches the engine only through the shell: API calls and questions go out as WebView2 messages.
+ - The shell's proxy adds the token and allows only the engine's API paths. Answers stream back line by line.
+ - The page never sees the token and never opens a connection to a local port. That also avoids the browser's
+ local-network restrictions for pages that call `127.0.0.1`.
+ - The look is the AI Engineering Arena's "sticker arcade" theme, with its fonts bundled, so the app looks the same offline.
+- **Engine API (FastAPI, `ore serve`).** Only the shell calls it. It is reachable only from this machine, through three guards:
1. It binds to `127.0.0.1` and rejects any non-loopback `Host` header, which blocks DNS rebinding.
2. Every request needs the per-launch bearer token.
- 3. CORS allows only `https://app.ore`.
+ 3. CORS allows only `https://app.ore`, plus a development origin when one is given with `--origin`.
Errors are problem details (RFC 9457) without stack traces or document content.
- **One index per section.** A section is one collection: a Chroma index plus BM25 chunks.
diff --git a/installer/OpenRag.iss b/installer/OpenRag.iss
new file mode 100644
index 0000000..540e4ce
--- /dev/null
+++ b/installer/OpenRag.iss
@@ -0,0 +1,108 @@
+; Open RAG installer. installer/build.py stages the app and passes AppVersion, Stage and OutputDir.
+;
+; Per-user install (no administrator rights) into %LOCALAPPDATA%\Programs\Open RAG. The documents, indexes and chats
+; live in %LOCALAPPDATA%\OpenRag and are kept on uninstall. The setup is split into OpenRag-Setup.exe and .bin parts,
+; because the bundled language model alone is larger than GitHub's 2 GiB limit per release file; keep them together.
+
+#ifndef AppVersion
+ #define AppVersion "0.0.0"
+#endif
+#ifndef Stage
+ #define Stage "build\stage"
+#endif
+#ifndef OutputDir
+ #define OutputDir "dist"
+#endif
+
+#define AppName "Open RAG"
+#define AppExe "OpenRag.exe"
+#define RepoUrl "https://github.com/Carthavate/open-rag-engine"
+
+[Setup]
+AppId={{CCCFBEFA-370C-43F7-B2C9-FE2E442E1CC1}
+AppName={#AppName}
+AppVersion={#AppVersion}
+AppVerName={#AppName} {#AppVersion}
+AppPublisher=Carthavate
+AppPublisherURL={#RepoUrl}
+AppSupportURL={#RepoUrl}/issues
+AppUpdatesURL={#RepoUrl}/releases
+VersionInfoVersion={#AppVersion}
+AppCopyright=Copyright (C) 2026 Wadi Touil and Ghassen Jamoussi
+DefaultDirName={autopf}\{#AppName}
+DisableProgramGroupPage=yes
+PrivilegesRequired=lowest
+ArchitecturesAllowed=x64compatible
+ArchitecturesInstallIn64BitMode=x64compatible
+MinVersion=10.0.17763
+SetupIconFile=..\desktop\src\OpenRag.App\Assets\OpenRag.ico
+UninstallDisplayIcon={app}\{#AppExe}
+UninstallDisplayName={#AppName}
+WizardStyle=modern dynamic
+OutputDir={#OutputDir}
+OutputBaseFilename=OpenRag-Setup
+Compression=lzma2/max
+SolidCompression=yes
+LZMAUseSeparateProcess=yes
+LZMANumBlockThreads=4
+DiskSpanning=yes
+; Below GitHub's 2 GiB per release file (2147483648 bytes). "max" no longer means 2 GiB in Inno Setup 6.5+.
+DiskSliceSize=2000000000
+; The app holds this mutex while it runs, so setup can ask to close it before replacing its files.
+AppMutex=Local\OpenRag.SingleInstance
+CloseApplications=yes
+RestartApplications=no
+
+[Languages]
+Name: "english"; MessagesFile: "compiler:Default.isl"
+
+[Tasks]
+Name: "desktopicon"; Description: "{cm:CreateDesktopIcon}"; GroupDescription: "{cm:AdditionalIcons}"
+
+[InstallDelete]
+; An update replaces the whole engine, so packages a new version dropped don't linger.
+Type: filesandordirs; Name: "{app}\engine"
+
+[Files]
+; The model is already compressed (4-bit GGUF); storing it as is saves minutes of build time and nothing in size.
+Source: "{#Stage}\engine\llm\model.gguf"; DestDir: "{app}\engine\llm"; Flags: ignoreversion nocompression
+Source: "{#Stage}\*"; DestDir: "{app}"; Excludes: "\engine\llm\model.gguf"; Flags: ignoreversion recursesubdirs createallsubdirs
+
+[Icons]
+Name: "{autoprograms}\{#AppName}"; Filename: "{app}\{#AppExe}"
+Name: "{autodesktop}\{#AppName}"; Filename: "{app}\{#AppExe}"; Tasks: desktopicon
+
+[Run]
+Filename: "{app}\{#AppExe}"; Description: "{cm:LaunchProgram,{#AppName}}"; Flags: nowait postinstall skipifsilent
+
+[UninstallDelete]
+; Python writes bytecode caches next to the bundled engine while the app runs.
+Type: filesandordirs; Name: "{app}\engine"
+
+[Code]
+const
+ // Where the WebView2 runtime registers itself: per machine (32-bit view) or per user.
+ WebView2Client = 'Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}';
+
+function Registered(Root: Integer; Key: String): Boolean;
+var
+ Version: String;
+begin
+ Result := RegQueryStringValue(Root, Key, 'pv', Version) and (Version <> '') and (Version <> '0.0.0.0');
+end;
+
+function HasWebView2: Boolean;
+begin
+ Result := Registered(HKLM, 'SOFTWARE\WOW6432Node\' + WebView2Client) or Registered(HKCU, 'Software\' + WebView2Client);
+end;
+
+{ Windows 11 always has the WebView2 runtime; an old Windows 10 may not. The app can't show its window without it. }
+function InitializeSetup: Boolean;
+begin
+ Result := True;
+ if not HasWebView2 then
+ Result := SuppressibleMsgBox(
+ 'Open RAG needs the Microsoft Edge WebView2 Runtime, which this computer doesn''t seem to have.' + #13#10#13#10 +
+ 'You can install it for free from Microsoft (search for "WebView2 Runtime"), before or after Open RAG.' + #13#10#13#10 +
+ 'Continue installing Open RAG?', mbConfirmation, MB_YESNO, IDYES) = IDYES;
+end;
diff --git a/installer/README.md b/installer/README.md
new file mode 100644
index 0000000..9540b27
--- /dev/null
+++ b/installer/README.md
@@ -0,0 +1,74 @@
+# Windows installer
+
+`OpenRag-Setup.exe` installs Open RAG with everything it needs: the desktop app, a private Python with the engine,
+the embedding and reranker models, and a language model served by llama.cpp. After installing, it needs no internet,
+no Python and no Ollama.
+
+## What the installer does
+
+- Installs per user, without administrator rights, into `%LOCALAPPDATA%\Programs\Open RAG`.
+- Adds a Start menu shortcut and, if you tick the box, a desktop shortcut.
+- Keeps your sections, indexes and chats in `%LOCALAPPDATA%\OpenRag` when you uninstall or update.
+- Warns you if the Microsoft Edge WebView2 Runtime is missing. Windows 11 always has it; an old Windows 10 may not.
+
+The setup comes as `OpenRag-Setup.exe` plus `.bin` parts, because the language model alone (2.5 GB) is larger than
+GitHub's 2 GiB limit per release file. Download all the parts into one folder and run the `.exe`.
+
+## How the app runs the language model
+
+When the app finds `engine/llm/llama-server.exe` and `engine/llm/model.gguf`, it:
+
+1. Picks a free loopback port and a random key.
+2. Starts `llama-server` on that port, giving it the key through `LLAMA_API_KEY`.
+3. Starts the engine with `--llm-url http://127.0.0.1:/v1`, giving it the same key through `ORE_LLM_API_KEY`.
+4. Reports ready once the engine prints `ORE_READY` and `llama-server` answers `/health`.
+
+Both processes run in the app's job object, so they close with it. Their logs are `engine.log` and `llm.log` in
+`%LOCALAPPDATA%\OpenRag\logs`.
+
+## Building it
+
+You need:
+
+- Windows with the .NET 10 SDK, Node.js, [uv](https://docs.astral.sh/uv/) and [Inno Setup 6](https://jrsoftware.org/isinfo.php).
+- The models on this computer:
+ - Run `uv run ore ask` once so the Hugging Face models download.
+ - Run `ollama pull qwen3:4b-instruct-2507-q4_K_M` for the language model.
+
+Then, from the repository root:
+
+```
+uv run python installer/build.py
+```
+
+The script:
+
+1. Publishes the app as self-contained `win-x64`.
+2. Copies a uv-managed CPython 3.12.
+3. Installs the engine wheel and its locked dependencies into that Python, using CPU-only torch.
+4. Copies the models from the Hugging Face and Ollama caches. It checks the GGUF against Ollama's digest.
+5. Downloads the pinned llama.cpp CPU build into `installer/.cache` and checks it against its sha256.
+6. Checks that the staged engine imports with nothing from the build machine.
+7. Runs Inno Setup.
+
+The installer lands in `installer/dist`. To stop after staging (in `installer/build/stage`), run it with `--no-iscc`.
+
+## Checking a build
+
+```
+uv run python installer/smoke_test.py
+```
+
+This checks the stage end to end without opening the window. It:
+
+1. Starts the bundled `llama-server` and engine the way the app does, with model downloads blocked.
+2. Checks that `llama-server` refuses requests without its key.
+3. Indexes the example pump manual and asks it a question.
+4. Passes only on an answer with sources.
+
+To check an installed app instead of the stage, pass its folder, for example `"%LOCALAPPDATA%\Programs\Open RAG"`.
+
+To update llama.cpp, change `LLAMA_BUILD` and `LLAMA_SHA256` in `build.py`. Take both from the release page on
+github.com/ggml-org/llama.cpp.
+
+The setup isn't code-signed, so Windows SmartScreen says the publisher is unknown. Choose *More info*, then *Run anyway*.
diff --git a/installer/THIRD_PARTY_NOTICES.md b/installer/THIRD_PARTY_NOTICES.md
new file mode 100644
index 0000000..5248cfc
--- /dev/null
+++ b/installer/THIRD_PARTY_NOTICES.md
@@ -0,0 +1,28 @@
+# Third-party software in Open RAG
+
+Open RAG is developed by Wadi Touil (https://github.com/TWadi) and Ghassen Jamoussi
+(https://github.com/GhassenJamoussi99). It is free software under the GNU Affero General Public License v3.0 (see
+`LICENSE.txt`), and its source code is at https://github.com/Carthavate/open-rag-engine.
+
+The installer also brings the components below, each under its own licence.
+
+## Models
+
+| Component | Where | Licence |
+| --- | --- | --- |
+| Qwen3-4B-Instruct-2507 (Alibaba Qwen team), 4-bit GGUF as published by Ollama | `engine/llm/model.gguf` | Apache-2.0 (`engine/llm/MODEL_LICENSE.txt`) |
+| intfloat/multilingual-e5-small | `engine/models/intfloat--multilingual-e5-small` | MIT (model card in that folder) |
+| cross-encoder/mmarco-mMiniLMv2-L12-H384-v1 | `engine/models/cross-encoder--mmarco-mMiniLMv2-L12-H384-v1` | Apache-2.0 |
+
+## Programs and libraries
+
+| Component | Where | Licence |
+| --- | --- | --- |
+| llama.cpp `llama-server` (ggml-org) | `engine/llm` | MIT (`engine/llm/LICENSE*`) |
+| CPython | `engine/python` | Python Software Foundation License (`engine/python/LICENSE.txt`) |
+| Python packages: LangChain, Chroma, PyTorch, sentence-transformers, FastAPI and their dependencies | `engine/python/Lib/site-packages` | Each package's own licence, in its `*.dist-info` folder |
+| .NET runtime | the app folder | MIT |
+| Microsoft Edge WebView2 SDK | `Microsoft.Web.WebView2.*.dll`, `WebView2Loader.dll` | Microsoft WebView2 SDK licence (BSD-3-Clause style) |
+| React, React DOM, Motion | `wwwroot` | MIT |
+| Lucide icons | `wwwroot` | ISC |
+| Fonts: Lilita One, Atkinson Hyperlegible, IBM Plex Mono | `wwwroot` | SIL Open Font License 1.1 |
diff --git a/installer/build.py b/installer/build.py
new file mode 100644
index 0000000..6b659c2
--- /dev/null
+++ b/installer/build.py
@@ -0,0 +1,314 @@
+"""Builds the Open RAG installer: one setup that needs no internet, no Python and no Ollama on the target computer.
+
+ uv run python installer/build.py # stage everything, check it, run Inno Setup
+ uv run python installer/build.py --no-iscc # stage and check only (installer/build/stage)
+
+The stage mirrors the installed app:
+
+ OpenRag.exe, wwwroot/ ... the desktop app (self-contained .NET) and its interface
+ engine/python/ a standalone CPython with open-rag-engine and its locked dependencies
+ engine/models/--/ the embedding and reranker models, copied from the Hugging Face cache
+ engine/llm/ llama.cpp's llama-server (CPU build) and the Qwen3 GGUF, copied from Ollama
+ engine/ore.toml points the engine at those models
+
+Before building, the models must be on this computer: run `ore ask` once (Hugging Face models) and
+`ollama pull qwen3:4b-instruct-2507-q4_K_M`. The only download is the pinned llama.cpp release, verified by its digest.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tomllib
+import urllib.request
+import zipfile
+from pathlib import Path
+
+from open_rag_engine.config import EngineConfig
+
+ROOT = Path(__file__).resolve().parents[1]
+HERE = ROOT / "installer"
+BUILD = HERE / "build"
+STAGE = BUILD / "stage"
+ENGINE = STAGE / "engine"
+CACHE = HERE / ".cache"
+DIST = HERE / "dist"
+APP_PROJECT = ROOT / "desktop" / "src" / "OpenRag.App"
+
+PYTHON_VERSION = "3.12"
+TORCH_INDEX = "https://download.pytorch.org/whl/cpu"
+
+LLAMA_BUILD = "b12052"
+LLAMA_ZIP = f"llama-{LLAMA_BUILD}-bin-win-cpu-x64.zip"
+LLAMA_URL = f"https://github.com/ggml-org/llama.cpp/releases/download/{LLAMA_BUILD}/{LLAMA_ZIP}"
+LLAMA_SHA256 = "0f6a20186bed5ad765ccac87832ce8e15a7a44eedc7825cd1dbdd114d423e7f0"
+
+OLLAMA_MODEL = ("qwen3", "4b-instruct-2507-q4_K_M")
+# Must match LlmBundle.ModelAlias in desktop/src/OpenRag.Core/Engine.cs, which passes it to llama-server.
+LLM_ALIAS = "qwen3-4b-instruct"
+
+ISCC = Path(os.environ.get("ISCC", r"C:\Program Files (x86)\Inno Setup 6\ISCC.exe"))
+GITHUB_FILE_LIMIT = 2 * 1024**3
+
+
+def run(*args: str | Path, cwd: Path = ROOT, attempts: int = 1) -> str:
+ """Runs a build tool and returns its output. `attempts` > 1 retries a step that antivirus scanning of freshly
+ written files can briefly lock ("Access is denied")."""
+ print(" >", " ".join(str(a) for a in args), flush=True)
+ for attempt in range(1, attempts + 1):
+ result = subprocess.run([str(a) for a in args], cwd=cwd, capture_output=True, text=True, encoding="utf-8")
+ if result.returncode == 0:
+ return result.stdout.strip()
+ if attempt < attempts:
+ print(f" failed ({result.returncode}), trying again", flush=True)
+ command = " ".join(map(str, args))
+ sys.exit(f"Failed ({result.returncode}): {command}\n{result.stdout[-3000:]}\n{result.stderr[-3000:]}")
+
+
+def step(title: str) -> None:
+ print(f"\n== {title}", flush=True)
+
+
+def sha256_of(path: Path) -> str:
+ digest = hashlib.sha256()
+ with path.open("rb") as handle:
+ while block := handle.read(1 << 20):
+ digest.update(block)
+ return digest.hexdigest()
+
+
+def folder_size(path: Path) -> int:
+ return sum(f.stat().st_size for f in path.rglob("*") if f.is_file())
+
+
+# --- the app ------------------------------------------------------------------------------------------------------
+
+
+def publish_app() -> None:
+ step("Desktop app (dotnet publish, self-contained win-x64)")
+ run("dotnet", "publish", APP_PROJECT, "-c", "Release", "-r", "win-x64", "--self-contained", "-o", STAGE)
+ if not (STAGE / "OpenRag.exe").is_file() or not (STAGE / "wwwroot" / "index.html").is_file():
+ sys.exit("The publish output has no OpenRag.exe or wwwroot/index.html.")
+
+
+# --- the engine ---------------------------------------------------------------------------------------------------
+
+
+def stage_python() -> Path:
+ step(f"Standalone Python {PYTHON_VERSION}")
+ run("uv", "python", "install", PYTHON_VERSION)
+ # --system: under `uv run` the project's virtualenv is active, and it must not be the one we copy.
+ source = Path(run("uv", "python", "find", "--system", "--managed-python", PYTHON_VERSION)).parent
+ target = ENGINE / "python"
+ shutil.copytree(source, target, ignore=shutil.ignore_patterns("__pycache__"))
+ # uv marks its Pythons as managed elsewhere; this private copy is ours to install into.
+ for marker in target.glob("Lib/EXTERNALLY-MANAGED"):
+ marker.unlink()
+ return target / "python.exe"
+
+
+def install_engine(python: Path) -> None:
+ step("open-rag-engine and its locked dependencies (CPU torch)")
+ wheels = BUILD / "wheel"
+ run("uv", "build", "--wheel", "--out-dir", wheels)
+ requirements = BUILD / "requirements.txt"
+ run("uv", "export", "--frozen", "--no-dev", "--no-emit-project", "--no-hashes", "--output-file", requirements)
+ # Copies, not links into uv's cache: the stage must stand alone.
+ install = ("uv", "pip", "install", "--python", python, "--link-mode", "copy")
+ torch_cpu = ("--index-strategy", "unsafe-best-match", "--extra-index-url", TORCH_INDEX)
+ run(*install, *torch_cpu, "-r", requirements, attempts=3)
+ wheel = max(wheels.glob("open_rag_engine-*.whl"), key=lambda w: w.stat().st_mtime)
+ run(*install, "--no-deps", wheel, attempts=3)
+ trim_python(python.parent)
+
+
+def trim_python(python_dir: Path) -> None:
+ """Drops what only building software needs: console-script launchers (they hold this build machine's paths),
+ torch's C++ headers and import libraries."""
+ site = python_dir / "Lib" / "site-packages"
+ removable = [python_dir / "Scripts", site / "torch" / "include", *site.glob("torch/lib/*.lib")]
+ freed = 0
+ for path in removable:
+ if path.is_dir():
+ freed += folder_size(path)
+ shutil.rmtree(path)
+ elif path.is_file():
+ freed += path.stat().st_size
+ path.unlink()
+ print(f" trimmed {freed / 1e6:.0f} MB")
+
+
+def hf_cache() -> Path:
+ if cache := os.environ.get("HF_HUB_CACHE"):
+ return Path(cache)
+ home = os.environ.get("HF_HOME")
+ return Path(home) / "hub" if home else Path.home() / ".cache" / "huggingface" / "hub"
+
+
+def stage_models(config: EngineConfig) -> None:
+ step("Embedding and reranker models (from the Hugging Face cache)")
+ for model in (config.embeddings.model, config.rerank.model):
+ repo = hf_cache() / f"models--{model.replace('/', '--')}"
+ ref = repo / "refs" / "main"
+ if not ref.is_file():
+ sys.exit(f"{model} is not in {hf_cache()}. Run `ore ask` once so it downloads, then build again.")
+ snapshot = repo / "snapshots" / ref.read_text().strip()
+ target = ENGINE / "models" / model.replace("/", "--")
+ # The cache may hold symlinks to its blobs; copytree copies the files they point to.
+ shutil.copytree(snapshot, target, symlinks=False, ignore=shutil.ignore_patterns("onnx", "openvino"))
+ print(f" {model}: {folder_size(target) / 1e6:.0f} MB")
+
+
+def write_config() -> None:
+ step("Engine configuration")
+ (ENGINE / "ore.toml").write_text(
+ "# Written by installer/build.py. The installed engine loads its models from this folder and asks the\n"
+ "# language model the app starts (llama-server); the app passes that server's address with --llm-url.\n"
+ 'models_dir = "models"\n'
+ "\n"
+ "[llm]\n"
+ 'provider = "openai"\n'
+ f'model = "{LLM_ALIAS}"\n',
+ encoding="utf-8",
+ )
+
+
+# --- the language model -------------------------------------------------------------------------------------------
+
+
+def llama_zip() -> Path:
+ """The pinned llama.cpp release, downloaded once into installer/.cache and checked against its digest."""
+ archive = CACHE / LLAMA_ZIP
+ if not archive.is_file():
+ CACHE.mkdir(parents=True, exist_ok=True)
+ print(f" downloading {LLAMA_URL}")
+ partial = archive.with_suffix(".part")
+ with urllib.request.urlopen(LLAMA_URL, timeout=60) as response, partial.open("wb") as out:
+ shutil.copyfileobj(response, out)
+ partial.replace(archive)
+ if (actual := sha256_of(archive)) != LLAMA_SHA256:
+ sys.exit(f"{archive} has digest {actual}, expected {LLAMA_SHA256}. Delete it and build again.")
+ return archive
+
+
+def stage_llama_server() -> None:
+ step(f"llama.cpp {LLAMA_BUILD} (CPU build)")
+ target = ENGINE / "llm"
+ target.mkdir(parents=True, exist_ok=True)
+ with zipfile.ZipFile(llama_zip()) as archive:
+ for member in archive.infolist():
+ # Names are flattened, so nothing can land outside the target folder.
+ name = Path(member.filename).name
+ if not member.is_dir() and is_server_file(name):
+ with archive.open(member) as source, (target / name).open("wb") as out:
+ shutil.copyfileobj(source, out)
+ if not (target / "llama-server.exe").is_file():
+ sys.exit(f"{LLAMA_ZIP} has no llama-server.exe.")
+ # The release zip carries only the OpenMP licence; llama.cpp's own (MIT) is kept in installer/licenses.
+ shutil.copyfile(HERE / "licenses" / "llama.cpp-LICENSE.txt", target / "LICENSE-llama.cpp.txt")
+
+
+def is_server_file(name: str) -> bool:
+ """llama-server and the libraries it loads; the release's other tools (bench, quantize ...) and their `-impl`
+ libraries stay out."""
+ if name.startswith("LICENSE") or name in ("llama-server.exe", "llama-server-impl.dll"):
+ return True
+ return name.endswith(".dll") and not name.endswith("-impl.dll")
+
+
+def ollama_models() -> Path:
+ return Path(os.environ.get("OLLAMA_MODELS", Path.home() / ".ollama" / "models"))
+
+
+def stage_gguf() -> None:
+ step(f"Language model {':'.join(OLLAMA_MODEL)} (from Ollama)")
+ name, tag = OLLAMA_MODEL
+ manifest = ollama_models() / "manifests" / "registry.ollama.ai" / "library" / name / tag
+ if not manifest.is_file():
+ sys.exit(f"Run `ollama pull {name}:{tag}` first ({manifest} is missing).")
+ layers = {layer["mediaType"]: layer["digest"] for layer in json.loads(manifest.read_text())["layers"]}
+
+ def blob(media_type: str) -> tuple[Path, str]:
+ digest = layers[media_type]
+ return ollama_models() / "blobs" / digest.replace(":", "-"), digest.split(":", 1)[1]
+
+ source, expected = blob("application/vnd.ollama.image.model")
+ target = ENGINE / "llm" / "model.gguf"
+ shutil.copyfile(source, target)
+ if sha256_of(target) != expected:
+ sys.exit(f"The copied model doesn't match Ollama's digest {expected}.")
+ if "application/vnd.ollama.image.license" in layers:
+ shutil.copyfile(blob("application/vnd.ollama.image.license")[0], ENGINE / "llm" / "MODEL_LICENSE.txt")
+ print(f" {target.stat().st_size / 1e9:.2f} GB, digest verified")
+
+
+# --- checks and the installer -------------------------------------------------------------------------------------
+
+
+def copy_notices() -> None:
+ shutil.copyfile(ROOT / "LICENSE", STAGE / "LICENSE.txt")
+ shutil.copyfile(HERE / "THIRD_PARTY_NOTICES.md", STAGE / "THIRD_PARTY_NOTICES.md")
+
+
+def check_stage(python: Path) -> None:
+ """The staged engine must import with nothing from this machine: isolated mode, no user site, no PYTHONPATH."""
+ step("Checking the stage")
+ env = {k: v for k, v in os.environ.items() if not k.startswith(("PYTHON", "VIRTUAL_ENV", "UV_"))}
+ probe = "import open_rag_engine, torch, chromadb, sentence_transformers, langchain_openai; print(torch.__version__)"
+ result = subprocess.run([python, "-I", "-c", probe], capture_output=True, text=True, env=env, cwd=ENGINE)
+ if result.returncode != 0:
+ sys.exit(f"The bundled engine doesn't import:\n{result.stderr[-3000:]}")
+ print(f" engine imports (torch {result.stdout.strip()})")
+ server = ENGINE / "llm" / "llama-server.exe"
+ result = subprocess.run([server, "--version"], capture_output=True, text=True, cwd=server.parent)
+ if result.returncode != 0:
+ sys.exit(f"llama-server doesn't start:\n{result.stderr[-2000:]}")
+ # It prints its version to stderr.
+ print(f" llama-server: {(result.stdout + result.stderr).strip().splitlines()[0]}")
+ print(f" stage: {folder_size(STAGE) / 1e9:.2f} GB")
+
+
+def version() -> str:
+ return tomllib.loads((ROOT / "pyproject.toml").read_text(encoding="utf-8"))["project"]["version"]
+
+
+def run_iscc() -> None:
+ step("Inno Setup")
+ if not ISCC.is_file():
+ sys.exit(f"Inno Setup's compiler isn't at {ISCC}; install Inno Setup 6 or set ISCC.")
+ run(ISCC, f"/DAppVersion={version()}", f"/DStage={STAGE}", f"/DOutputDir={DIST}", HERE / "OpenRag.iss")
+ for file in sorted(DIST.glob("OpenRag-Setup*")):
+ print(f" {file.name}: {file.stat().st_size / 1e6:.0f} MB")
+ if file.stat().st_size >= GITHUB_FILE_LIMIT:
+ sys.exit(f"{file.name} is too large for a GitHub release (2 GiB per file); lower DiskSliceSize.")
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ parser.add_argument("--no-iscc", action="store_true", help="stage and check, but don't build the installer")
+ args = parser.parse_args()
+
+ if STAGE.exists():
+ shutil.rmtree(STAGE)
+ if DIST.exists():
+ shutil.rmtree(DIST)
+ publish_app()
+ python = stage_python()
+ install_engine(python)
+ stage_models(EngineConfig())
+ write_config()
+ stage_llama_server()
+ stage_gguf()
+ copy_notices()
+ check_stage(python)
+ if not args.no_iscc:
+ run_iscc()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/installer/licenses/llama.cpp-LICENSE.txt b/installer/licenses/llama.cpp-LICENSE.txt
new file mode 100644
index 0000000..e7dca55
--- /dev/null
+++ b/installer/licenses/llama.cpp-LICENSE.txt
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-2026 The ggml authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/installer/smoke_test.py b/installer/smoke_test.py
new file mode 100644
index 0000000..698af13
--- /dev/null
+++ b/installer/smoke_test.py
@@ -0,0 +1,201 @@
+"""End-to-end check of a built Open RAG, without its window: starts the bundled llama-server and engine the way the
+app does, with model downloads blocked, indexes the example pump manual and asks it a question.
+
+ uv run python installer/smoke_test.py # the stage (installer/build/stage)
+ uv run python installer/smoke_test.py "%LOCALAPPDATA%\\Programs\\Open RAG" # an installed app
+
+The data goes to a temporary folder, so it never touches the app's own library.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import queue
+import secrets
+import socket
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+STAGE = ROOT / "installer" / "build" / "stage"
+DOCS = ROOT / "examples" / "docs"
+QUESTION = "Why does my pump keep turning itself off?"
+# Must match LlmBundle in desktop/src/OpenRag.Core/Engine.cs.
+MODEL_ALIAS = "qwen3-4b-instruct"
+START_TIMEOUT = 300
+
+
+def free_port() -> int:
+ with socket.socket() as probe:
+ probe.bind(("127.0.0.1", 0))
+ return probe.getsockname()[1]
+
+
+def clean_env(**extra: str) -> dict[str, str]:
+ """This machine's environment minus anything that could point Python at a developer setup, with model
+ downloads sent to a dead address so any attempt fails loudly."""
+ env = {k: v for k, v in os.environ.items() if not k.startswith(("PYTHON", "VIRTUAL_ENV", "UV_", "HF_"))}
+ return {**env, "HF_ENDPOINT": "http://127.0.0.1:9", "PYTHONUTF8": "1", "PYTHONDONTWRITEBYTECODE": "1", **extra}
+
+
+def request(url: str, body: object | None = None, token: str | None = None, method: str | None = None):
+ data = None if body is None else json.dumps(body).encode()
+ headers = {"Content-Type": "application/json"} | ({"Authorization": f"Bearer {token}"} if token else {})
+ return urllib.request.urlopen(urllib.request.Request(url, data, headers, method=method), timeout=600)
+
+
+def call(base: str, token: str, path: str, body: object | None = None) -> dict:
+ with request(base + path, body, token) as response:
+ return json.loads(response.read() or b"{}")
+
+
+def wait_for(check, what: str, timeout: float = START_TIMEOUT) -> None:
+ deadline = time.monotonic() + timeout
+ while time.monotonic() < deadline:
+ try:
+ if check():
+ return
+ except (urllib.error.URLError, ConnectionError):
+ pass
+ time.sleep(1)
+ sys.exit(f"FAIL: {what} not ready within {timeout} s")
+
+
+def start(args: list[str | Path], env: dict[str, str], log: Path, cwd: Path) -> tuple[subprocess.Popen, queue.Queue]:
+ """Starts a process with its output copied to a log and to a queue of lines (to spot ORE_READY)."""
+ process = subprocess.Popen(
+ [str(a) for a in args],
+ cwd=cwd,
+ env=env,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.STDOUT,
+ text=True,
+ encoding="utf-8",
+ errors="replace",
+ creationflags=subprocess.CREATE_NO_WINDOW,
+ )
+ lines: queue.Queue = queue.Queue()
+
+ def pump() -> None:
+ with log.open("w", encoding="utf-8") as out:
+ for line in process.stdout:
+ out.write(line)
+ out.flush()
+ lines.put(line.strip())
+
+ threading.Thread(target=pump, daemon=True).start()
+ return process, lines
+
+
+def ready_port(lines: queue.Queue, process: subprocess.Popen, log: Path) -> int:
+ deadline = time.monotonic() + START_TIMEOUT
+ while time.monotonic() < deadline:
+ if process.poll() is not None:
+ sys.exit(f"FAIL: the engine exited ({process.returncode}). See {log}")
+ try:
+ line = lines.get(timeout=1)
+ except queue.Empty:
+ continue
+ if line.startswith("ORE_READY port="):
+ return int(line.split("=", 1)[1])
+ sys.exit(f"FAIL: the engine didn't print ORE_READY. See {log}")
+
+
+def main() -> None:
+ sys.stdout.reconfigure(encoding="utf-8") # answers quote units such as °C
+ app = Path(sys.argv[1]) if len(sys.argv) > 1 else STAGE
+ engine = app / "engine"
+ work = Path(tempfile.mkdtemp(prefix="openrag-smoke-"))
+ port, key, token = free_port(), secrets.token_urlsafe(32), secrets.token_urlsafe(32)
+ llm_url = f"http://127.0.0.1:{port}"
+ print(f"app: {app}\nlogs: {work}")
+
+ started = time.monotonic()
+ llm, _ = start(
+ [
+ engine / "llm" / "llama-server.exe",
+ "-m",
+ engine / "llm" / "model.gguf",
+ "--host",
+ "127.0.0.1",
+ "--port",
+ str(port),
+ "--ctx-size",
+ "8192",
+ "--jinja",
+ "--alias",
+ MODEL_ALIAS,
+ "--no-webui",
+ ],
+ clean_env(LLAMA_API_KEY=key),
+ work / "llm.log",
+ engine / "llm",
+ )
+ server, lines = start(
+ [
+ engine / "python" / "python.exe",
+ "-m",
+ "open_rag_engine",
+ "serve",
+ "--data-dir",
+ work / "data",
+ "--parent-pid",
+ str(os.getpid()),
+ "--warm",
+ "--llm-url",
+ f"{llm_url}/v1",
+ "--config",
+ engine / "ore.toml",
+ ],
+ clean_env(ORE_API_TOKEN=token, ORE_LLM_API_KEY=key),
+ work / "engine.log",
+ engine,
+ )
+ try:
+ base = f"http://127.0.0.1:{ready_port(lines, server, work / 'engine.log')}"
+ print(f"engine ready after {time.monotonic() - started:.0f} s")
+ wait_for(lambda: request(f"{llm_url}/health").status == 200, "llama-server")
+ print(f"language model ready after {time.monotonic() - started:.0f} s")
+
+ try:
+ # /health and /v1/models are public in llama-server; chat is not.
+ request(f"{llm_url}/v1/chat/completions", {"messages": [{"role": "user", "content": "hi"}]}).close()
+ sys.exit("FAIL: llama-server answered without its key")
+ except urllib.error.HTTPError as error:
+ assert error.code == 401, error.code
+ print("language model refuses requests without the key")
+
+ category = call(base, token, "/categories", {"name": "Smoke test"})
+ section = call(base, token, "/sections", {"name": "Pump manual", "category_id": category["id"]})
+ call(base, token, f"/sections/{section['id']}/folders", {"path": str(DOCS)})
+ call(base, token, f"/sections/{section['id']}/index", {})
+ wait_for(lambda: call(base, token, f"/sections/{section['id']}/status")["state"] == "idle", "indexing")
+ status = call(base, token, f"/sections/{section['id']}/status")
+ if status["error"]:
+ sys.exit(f"FAIL: indexing: {status['error']}")
+ print(f"indexed {DOCS.name}: {status['report']}")
+
+ asked = time.monotonic()
+ ask = {"scope": {"kind": "section", "id": section["id"]}, "question": QUESTION}
+ with request(base + "/ask", ask, token) as response:
+ events = [json.loads(line) for line in response.read().decode().splitlines() if line.strip()]
+ done = events[-1]
+ if done.get("type") != "done" or not done.get("text") or not done.get("sources"):
+ sys.exit(f"FAIL: no cited answer: {done}")
+ print(f"\nQ: {QUESTION}\nA ({time.monotonic() - asked:.0f} s): {done['text']}")
+ print("sources:", ", ".join(s["label"] for s in done["sources"]))
+ print("\nPASS")
+ finally:
+ for process in (server, llm):
+ process.terminate()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/src/open_rag_engine/__main__.py b/src/open_rag_engine/__main__.py
new file mode 100644
index 0000000..ff93e78
--- /dev/null
+++ b/src/open_rag_engine/__main__.py
@@ -0,0 +1,5 @@
+"""`python -m open_rag_engine ...` runs the same CLI as `ore ...` (the desktop app starts the engine this way)."""
+
+from .cli import app
+
+app()
diff --git a/src/open_rag_engine/api.py b/src/open_rag_engine/api.py
index 8024fec..a86b505 100644
--- a/src/open_rag_engine/api.py
+++ b/src/open_rag_engine/api.py
@@ -7,11 +7,13 @@
from __future__ import annotations
+import asyncio
import json
import logging
import queue
import secrets
import threading
+from collections.abc import AsyncIterator, Callable
from dataclasses import asdict
from typing import Any, Literal
@@ -160,35 +162,57 @@ def ask(body: AskIn) -> StreamingResponse:
library.scope_sections(body.scope.kind, body.scope.id) # unknown or busy scopes fail before streaming starts
history = [(t.question, t.answer) for t in body.history]
default_section = body.scope.id if body.scope.kind == "section" else None
- events: queue.Queue[dict[str, Any] | None] = queue.Queue()
-
- def work() -> None:
- try:
- answer = library.ask(
- body.scope.kind,
- body.scope.id,
- body.question,
- history,
- on_token=lambda text: events.put({"type": "token", "text": text}),
- )
- events.put({"type": "done", **_answer(answer, default_section)})
- except Exception as error: # the stream is already open, so the error travels as an event
- status, title, detail = _classify(error)
- events.put({"type": "error", "status": status, "title": title, "detail": detail})
- finally:
- events.put(None)
-
- threading.Thread(target=work, name="ask", daemon=True).start()
-
- def lines():
- while (event := events.get()) is not None:
- yield json.dumps(event, ensure_ascii=False) + "\n"
- return StreamingResponse(lines(), media_type="application/x-ndjson")
+ def run(on_token: Callable[[str], None]) -> dict[str, Any]:
+ answer = library.ask(body.scope.kind, body.scope.id, body.question, history, on_token=on_token)
+ return {"type": "done", **_answer(answer, default_section)}
+
+ return StreamingResponse(answer_stream(run), media_type="application/x-ndjson")
return app
+class _Cancelled(Exception):
+ """The client stopped listening, so the answer is abandoned."""
+
+
+def answer_stream(run: Callable[[Callable[[str], None]], dict[str, Any]]) -> AsyncIterator[str]:
+ """Runs an answer in a worker thread and yields it as NDJSON lines: tokens, then the final event.
+
+ When the client goes away (Stop, a closed window), the stream is cancelled and the next token raises inside the
+ model's own token loop, so generation stops instead of running on for nobody.
+ """
+ events: queue.Queue[dict[str, Any] | None] = queue.Queue()
+ cancelled = threading.Event()
+
+ def on_token(text: str) -> None:
+ if cancelled.is_set():
+ raise _Cancelled
+ events.put({"type": "token", "text": text})
+
+ def work() -> None:
+ try:
+ events.put(run(on_token))
+ except _Cancelled:
+ pass
+ except Exception as error: # the stream is already open, so the error travels as an event
+ status, title, detail = _classify(error)
+ events.put({"type": "error", "status": status, "title": title, "detail": detail})
+ finally:
+ events.put(None)
+
+ threading.Thread(target=work, name="ask", daemon=True).start()
+
+ async def lines() -> AsyncIterator[str]:
+ try:
+ while (event := await asyncio.to_thread(events.get)) is not None:
+ yield json.dumps(event, ensure_ascii=False) + "\n"
+ finally:
+ cancelled.set()
+
+ return lines()
+
+
def _section(section: Section) -> dict[str, Any]:
return {
"id": section.id,
diff --git a/src/open_rag_engine/cli.py b/src/open_rag_engine/cli.py
index 7e489f6..6cee8f8 100644
--- a/src/open_rag_engine/cli.py
+++ b/src/open_rag_engine/cli.py
@@ -55,8 +55,12 @@ def _startup() -> None:
TraceOpt = Annotated[bool, typer.Option("--trace", help="Show what every pipeline stage returned.")]
+def _models_on_disk(config: EngineConfig) -> list[str]:
+ return [config.model_path(config.embeddings.model), config.model_path(config.rerank.model)]
+
+
def build_engine(config: EngineConfig) -> Engine:
- go_offline_if_possible([config.embeddings.model, config.rerank.model])
+ go_offline_if_possible(_models_on_disk(config))
return Engine.from_config(config)
@@ -246,6 +250,11 @@ def serve(
port: Annotated[int, typer.Option(help="Port on 127.0.0.1; 0 picks a free one.")] = 0,
origin: Annotated[list[str] | None, typer.Option(help="Web origin allowed to call the API.")] = None,
parent_pid: Annotated[int | None, typer.Option(help="Exit when this process exits.")] = None,
+ data_dir: Annotated[Path | None, typer.Option(help="Where indexes and the workspace live.")] = None,
+ warm: Annotated[bool, typer.Option(help="Load the embedding and reranker models in the background.")] = False,
+ llm_url: Annotated[
+ str | None, typer.Option(help="OpenAI-compatible LLM server to use instead of the configured one.")
+ ] = None,
config: ConfigOpt = None,
) -> None:
"""Run the local API for the desktop app. Prints `ORE_READY port=` once it listens."""
@@ -255,12 +264,19 @@ def action():
if len(token) < 32:
raise ValueError(f"Set {TOKEN_VARIABLE} to a random secret of at least 32 characters.")
cfg = _config(config)
- go_offline_if_possible([cfg.embeddings.model, cfg.rerank.model])
+ if data_dir is not None:
+ cfg = EngineConfig.model_validate({**cfg.model_dump(), "data_dir": data_dir})
+ if llm_url is not None:
+ cfg = cfg.updated("llm", provider="openai", base_url=llm_url)
+ go_offline_if_possible(_models_on_disk(cfg))
from .api import create_app
from .factory import LocalModels
from .library import Library
- api = create_app(Library(cfg, LocalModels(cfg)), token, origin or ["https://app.ore"])
+ models = LocalModels(cfg)
+ api = create_app(Library(cfg, models), token, origin or ["https://app.ore"])
+ if warm:
+ threading.Thread(target=_warm, args=(models,), name="warm-up", daemon=True).start()
server = _listen(port)
typer.echo(f"ORE_READY port={server.getsockname()[1]}")
sys.stdout.flush()
@@ -273,6 +289,15 @@ def action():
_run(action)
+def _warm(models: Any) -> None:
+ """Load the models before the first question, so it isn't the one that waits."""
+ try:
+ models.embeddings.embed_query("warm-up")
+ models.cross_encoder.score([("warm-up", "warm-up")])
+ except Exception as error: # the first real request will load (and report) them instead
+ typer.echo(f"warm-up skipped: {error}", err=True)
+
+
def _listen(port: int) -> socket.socket:
"""Bind to loopback only. The socket is handed to uvicorn, so the chosen port is known before it starts."""
server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
diff --git a/src/open_rag_engine/config.py b/src/open_rag_engine/config.py
index b01de7f..3215de4 100644
--- a/src/open_rag_engine/config.py
+++ b/src/open_rag_engine/config.py
@@ -73,6 +73,9 @@ class AnswerConfig(_Section):
class EngineConfig(_Section):
data_dir: Path = Path(".ore")
+ models_dir: Path | None = None
+ """Bundled model folders, named like the model with "/" as "--" (intfloat--multilingual-e5-small). A model found
+ there loads from it; the configured model name, and so the index fingerprint, stays the same."""
collection: str = Field("default", pattern=r"^[A-Za-z0-9][A-Za-z0-9_-]{1,61}[A-Za-z0-9]$")
chunking: ChunkingConfig = ChunkingConfig()
embeddings: EmbeddingConfig = EmbeddingConfig()
@@ -93,7 +96,15 @@ def index_fingerprint(self) -> str:
def fingerprint(self) -> str:
"""Identifies the whole configuration, for reproducible evaluation runs (driver D-07)."""
- return _digest(self.model_dump_json(exclude={"data_dir"}))
+ return _digest(self.model_dump_json(exclude={"data_dir", "models_dir"}))
+
+ def model_path(self, model: str) -> str:
+ """Where to load a Hugging Face model from: its bundled folder when there is one, else its name."""
+ if self.models_dir is not None:
+ folder = self.models_dir / model.replace("/", "--")
+ if folder.is_dir():
+ return str(folder)
+ return model
def _digest(text: str) -> str:
@@ -107,4 +118,8 @@ def load_config(path: Path | None) -> EngineConfig:
if not path.is_file():
raise FileNotFoundError(f"Configuration file not found: {path}")
with path.open("rb") as handle:
- return EngineConfig.model_validate(tomllib.load(handle))
+ data = tomllib.load(handle)
+ # A relative models_dir is relative to the configuration file, so a bundled engine works wherever it is installed.
+ if isinstance(data.get("models_dir"), str) and not Path(data["models_dir"]).is_absolute():
+ data["models_dir"] = str(path.resolve().parent / data["models_dir"])
+ return EngineConfig.model_validate(data)
diff --git a/src/open_rag_engine/factory.py b/src/open_rag_engine/factory.py
index 8f4e6cd..f697edc 100644
--- a/src/open_rag_engine/factory.py
+++ b/src/open_rag_engine/factory.py
@@ -3,7 +3,8 @@
from __future__ import annotations
import os
-from functools import cached_property
+import threading
+from typing import Any
from langchain_community.cross_encoders import HuggingFaceCrossEncoder
from langchain_core.embeddings import Embeddings
@@ -15,27 +16,47 @@
class LocalModels:
def __init__(self, config: EngineConfig):
self._config = config
-
- @cached_property
+ # One lock for all models: the warm-up and a first question must not load the same model twice, and on a
+ # CPU two loads at once would only slow each other down.
+ self._lock = threading.Lock()
+ self._loaded: dict[str, Any] = {}
+
+ def _once(self, name: str, build: Any) -> Any:
+ with self._lock:
+ if name not in self._loaded:
+ self._loaded[name] = build()
+ return self._loaded[name]
+
+ @property
def embeddings(self) -> Embeddings:
+ return self._once("embeddings", self._embeddings)
+
+ @property
+ def cross_encoder(self) -> HuggingFaceCrossEncoder:
+ return self._once("cross_encoder", self._cross_encoder)
+
+ @property
+ def llm(self) -> BaseChatModel:
+ return self._once("llm", self._llm)
+
+ def _embeddings(self) -> Embeddings:
from langchain_huggingface import HuggingFaceEmbeddings
_quiet_transformers()
cfg = self._config.embeddings
return HuggingFaceEmbeddings(
- model_name=cfg.model,
+ model_name=self._config.model_path(cfg.model),
model_kwargs={"device": "cpu"},
encode_kwargs=_encode_kwargs(cfg.passage_prefix),
query_encode_kwargs=_encode_kwargs(cfg.query_prefix),
)
- @cached_property
- def cross_encoder(self) -> HuggingFaceCrossEncoder:
+ def _cross_encoder(self) -> HuggingFaceCrossEncoder:
_quiet_transformers()
- return HuggingFaceCrossEncoder(model_name=self._config.rerank.model, model_kwargs={"device": "cpu"})
+ model = self._config.model_path(self._config.rerank.model)
+ return HuggingFaceCrossEncoder(model_name=model, model_kwargs={"device": "cpu"})
- @cached_property
- def llm(self) -> BaseChatModel:
+ def _llm(self) -> BaseChatModel:
cfg = self._config.llm
if cfg.provider == "openai":
from langchain_openai import ChatOpenAI
diff --git a/tests/test_api.py b/tests/test_api.py
index 5088605..5fc43ce 100644
--- a/tests/test_api.py
+++ b/tests/test_api.py
@@ -113,3 +113,34 @@ def test_asking_while_indexing_is_a_conflict(config, tmp_path: Path):
body = {"scope": {"kind": "section", "id": section_id}, "question": "pump?"}
response = client.post("/ask", json=body, headers=AUTH)
assert response.status_code == 409 and "Still indexing" in response.json()["detail"]
+
+
+def test_closing_the_stream_stops_the_answer():
+ import asyncio
+ import threading
+ import time
+
+ from open_rag_engine.api import answer_stream
+
+ produced: list[int] = []
+ finished = threading.Event()
+
+ def run(on_token):
+ try:
+ for i in range(200):
+ on_token(str(i))
+ produced.append(i)
+ time.sleep(0.01)
+ return {"type": "done"}
+ finally:
+ finished.set()
+
+ async def first_then_stop():
+ stream = answer_stream(run)
+ first = await anext(stream)
+ await stream.aclose()
+ return first
+
+ assert json.loads(asyncio.run(first_then_stop())) == {"type": "token", "text": "0"}
+ assert finished.wait(5)
+ assert len(produced) < 200
diff --git a/tests/test_config.py b/tests/test_config.py
index 7e3d08b..989fdc6 100644
--- a/tests/test_config.py
+++ b/tests/test_config.py
@@ -69,3 +69,17 @@ def test_index_fingerprint_tracks_only_what_changes_the_index():
assert cfg.index_fingerprint() == cfg.updated("retrieval", k=3).index_fingerprint()
assert cfg.index_fingerprint() != cfg.updated("chunking", chunk_size=400).index_fingerprint()
assert cfg.fingerprint() != cfg.updated("retrieval", k=3).fingerprint()
+
+
+def test_bundled_models_load_from_models_dir_without_changing_the_index(tmp_path: Path):
+ (tmp_path / "models" / "intfloat--multilingual-e5-small").mkdir(parents=True)
+ path = tmp_path / "ore.toml"
+ path.write_text('models_dir = "models"\n', encoding="utf-8")
+ cfg = load_config(path)
+ assert cfg.models_dir == tmp_path / "models"
+ assert cfg.model_path("intfloat/multilingual-e5-small") == str(
+ tmp_path / "models" / "intfloat--multilingual-e5-small"
+ )
+ assert cfg.model_path("cross-encoder/other") == "cross-encoder/other"
+ assert cfg.index_fingerprint() == EngineConfig().index_fingerprint()
+ assert cfg.fingerprint() == EngineConfig().fingerprint()
diff --git a/tests/test_engine_and_cli.py b/tests/test_engine_and_cli.py
index 442e945..07d1221 100644
--- a/tests/test_engine_and_cli.py
+++ b/tests/test_engine_and_cli.py
@@ -120,3 +120,19 @@ def test_listen_binds_loopback_on_a_free_port():
assert host == "127.0.0.1" and port > 0
finally:
server.close()
+
+
+def test_warm_up_loads_both_models_and_never_raises():
+ calls = []
+
+ class Models:
+ @property
+ def embeddings(self):
+ return type("E", (), {"embed_query": lambda self, text: calls.append("embed")})()
+
+ @property
+ def cross_encoder(self):
+ raise RuntimeError("no model files")
+
+ cli._warm(Models())
+ assert calls == ["embed"]
diff --git a/tests/test_factory.py b/tests/test_factory.py
index e924a7d..d4f6648 100644
--- a/tests/test_factory.py
+++ b/tests/test_factory.py
@@ -13,3 +13,25 @@ def test_an_openai_compatible_server_can_replace_ollama(monkeypatch):
llm = LocalModels(cfg).llm
assert type(llm).__name__ == "ChatOpenAI" and llm.model_name == "qwen3-4b"
assert str(llm.openai_api_base) == "http://127.0.0.1:8090/v1"
+
+
+def test_each_model_loads_once_even_when_asked_for_at_the_same_time(monkeypatch):
+ import threading
+ import time
+
+ models = LocalModels(EngineConfig())
+ builds = []
+
+ def slow_build():
+ builds.append(1)
+ time.sleep(0.2)
+ return object()
+
+ monkeypatch.setattr(models, "_embeddings", slow_build)
+ results = []
+ threads = [threading.Thread(target=lambda: results.append(models.embeddings)) for _ in range(4)]
+ for t in threads:
+ t.start()
+ for t in threads:
+ t.join()
+ assert len(builds) == 1 and len({id(r) for r in results}) == 1