(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
new file mode 100644
index 0000000..5929e8c
--- /dev/null
+++ b/docs/adr/0007-desktop-app.md
@@ -0,0 +1,100 @@
+# ADR-0007: A Windows desktop app over a local engine API
+
+- **Status:** Proposed
+- **Date:** 2026-11-02
+- **Deciders:** Wadi, Ghassen
+- **Requirements:** D-01, D-02, D-06, D-10, C-03, C-04
+
+## Context and problem
+
+Teachers, researchers and students want to ask questions about their own study material without sending it anywhere. They organise it in **categories** (a subject or research area) and **sections** (a course, session, project or reading list). Each section has its own folders, and an answer must come only from the section, or the category, they choose. Many of their laptops are offline or locked down, so the app must work with no network and ship as one self-contained installer.
+
+How do we build that app on top of the engine?
+
+## Decision drivers
+
+- Fully offline after installation, with nothing to configure (D-02, C-03).
+- Runs on ordinary Windows laptops without a GPU (C-04).
+- A modern, friendly interface: most users are not technical.
+- Answers stay grounded and cited (D-06), and every source can be opened.
+- The engine stays the single implementation of retrieval and answering (D-01).
+
+## Considered options
+
+1. **WPF shell with WebView2 and a React interface; the engine runs as a hidden child process with a loopback HTTP API.**
+2. **Native WPF (XAML)**, calling the engine the same way.
+3. **Electron or Tauri.**
+4. **No app:** `ore serve` plus the user's browser.
+
+## Decision
+
+Option 1, the same structure as our Duet app.
+
+- **Shell (.NET, WPF).** It owns the window, the native dialogs (pick a folder, open a source file) and the engine's lifetime:
+ - It starts `ore serve` with a fresh random token in `ORE_API_TOKEN`, and reads the `ORE_READY port=` line.
+ - 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 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`, 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.
+ - A **category** question searches each section, fuses the lists with reciprocal rank fusion, and reranks the fused candidates once.
+ - Indexing runs in the background, one job at a time, and drops files that were deleted from the folders.
+ - It keeps the documents of folders that are temporarily missing, such as an unplugged USB drive.
+- **Offline by construction.**
+ - When every model is on disk, the engine sets `HF_HUB_OFFLINE`, and telemetry is off.
+ - The self-contained installer bundles llama.cpp's `llama-server` with a GGUF build of the default model (Qwen3 4B Instruct, Apache-2.0). The engine reaches it through `provider = "openai"`, because the OpenAI-compatible API is what `llama-server` speaks.
+ - Ollama remains the default for developers, and it is too large to bundle.
+
+### Consequences
+
+- **Good:**
+ - The interface can look modern without fighting XAML.
+ - The engine stays one Python code path, tested once.
+ - The same API serves a future web UI or MCP server.
+- **Bad:**
+ - Two runtimes ship together, .NET and Python, which makes the installer large (several GB, mostly models).
+ - **Mitigation:** the packaging work keeps models and runtimes in separate, cacheable folders, and compresses what compresses.
+- **Bad:**
+ - A local HTTP port is an attack surface.
+ - **Mitigation:** the three guards above, all covered by tests.
+
+### Confirmation
+
+`tests/test_api.py` checks the token, the loopback-host rule and the CORS origin. `tests/test_library.py` checks that a section answers only from its own documents and that a category answers from all of its sections.
+
+## Pros and cons of the options
+
+### WPF + WebView2 + React
+
+- Good, because it uses the stack and patterns we already proved in Duet: virtual-host assets, the job object and Mica.
+- Good, because WebView2 is preinstalled on Windows 11.
+- Bad, because there are two UI technologies to know.
+
+### Native WPF
+
+- Good, because it is one technology with no web layer.
+- Bad, because a polished, friendly interface takes much longer to build.
+
+### Electron or Tauri
+
+- Good, because they are cross-platform.
+- Bad, because Electron adds another large runtime, and Tauri adds Rust. Neither buys us anything for a Windows-first app.
+
+### Browser plus `ore serve`
+
+- Good, because there is nothing to build.
+- Bad, because it gives no folder picker and no way to open source files, and users would have to start a server themselves.
+
+## More information
+
+[ADR-0006](0006-python-and-langchain.md) (engine stack), [interfaces](../architecture/05-interfaces.md) (error categories and problem details).
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 5a670a9..f07acc5 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -15,6 +15,7 @@ Each significant decision gets one short record: the context, the options we wei
| [0004](0004-index-generations.md) | Index generations built from independently keyed builds | Proposed |
| [0005](0005-verified-citations.md) | Citations are enforced, verified and attributed, not trusted | Proposed |
| [0006](0006-python-and-langchain.md) | Python and LangChain for the first engine | Proposed |
+| [0007](0007-desktop-app.md) | A Windows desktop app over a local engine API | Proposed |
## Planned
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/pyproject.toml b/pyproject.toml
index b86a553..84188bd 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -22,6 +22,9 @@ dependencies = [
"torch>=2.4",
"pydantic>=2.7",
"typer>=0.12",
+ "fastapi>=0.115",
+ "uvicorn>=0.32",
+ "langchain-openai>=1.0,<2",
]
[project.scripts]
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
new file mode 100644
index 0000000..a86b505
--- /dev/null
+++ b/src/open_rag_engine/api.py
@@ -0,0 +1,303 @@
+"""A local HTTP API for the desktop app, reachable only from this machine.
+
+Three guards: only loopback Host headers are served (no DNS rebinding), every request needs the bearer token the app
+generated at launch, and CORS allows only the app's own origin. Errors are RFC 9457 problem details without stack
+traces or document content.
+"""
+
+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
+
+import httpx
+from fastapi import Depends, FastAPI, HTTPException, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse, Response, StreamingResponse
+from pydantic import BaseModel, Field
+from starlette.middleware.trustedhost import TrustedHostMiddleware
+
+from . import __version__
+from .answer import Answer
+from .documents import PAGE, SOURCE, citation_label
+from .ingest import IndexMismatchError
+from .library import SECTION_ID, ConflictError, IndexStatus, Library
+from .workspace import NotFoundError, Section, WorkspaceError
+
+log = logging.getLogger(__name__)
+
+SNIPPET = 400
+
+
+class NameIn(BaseModel):
+ name: str = Field(min_length=1, max_length=80)
+
+
+class SectionIn(NameIn):
+ category_id: str = Field(min_length=1, max_length=64)
+
+
+class SectionPatch(BaseModel):
+ name: str | None = Field(None, min_length=1, max_length=80)
+ category_id: str | None = Field(None, min_length=1, max_length=64)
+
+
+class FolderIn(BaseModel):
+ path: str = Field(min_length=1, max_length=1024)
+
+
+class ScopeIn(BaseModel):
+ kind: Literal["section", "category"]
+ id: str = Field(min_length=1, max_length=64)
+
+
+class TurnIn(BaseModel):
+ question: str = Field(max_length=4000)
+ answer: str = Field(max_length=20000)
+
+
+class AskIn(BaseModel):
+ scope: ScopeIn
+ question: str = Field(min_length=1, max_length=4000)
+ history: list[TurnIn] = Field(default_factory=list, max_length=20)
+
+
+def create_app(library: Library, token: str, origins: list[str]) -> FastAPI:
+ expected = f"Bearer {token}".encode()
+
+ def require_token(request: Request) -> None:
+ if not secrets.compare_digest(request.headers.get("authorization", "").encode(), expected):
+ raise HTTPException(status_code=401, detail="Missing or wrong token")
+
+ app = FastAPI(
+ title="open-rag-engine",
+ version=__version__,
+ docs_url=None,
+ redoc_url=None,
+ openapi_url=None,
+ dependencies=[Depends(require_token)],
+ )
+ app.add_middleware(
+ CORSMiddleware,
+ allow_origins=origins,
+ allow_methods=["GET", "POST", "PATCH", "DELETE"],
+ allow_headers=["Authorization", "Content-Type"],
+ )
+ app.add_middleware(TrustedHostMiddleware, allowed_hosts=["127.0.0.1", "localhost"])
+ _add_error_handlers(app)
+ ws = library.workspace
+
+ @app.get("/health")
+ def health() -> dict[str, str]:
+ return {"status": "ok", "version": __version__}
+
+ @app.get("/library")
+ def overview() -> dict[str, Any]:
+ return {
+ "categories": [asdict(c) for c in ws.categories()],
+ "sections": [
+ {**_section(s), "documents": library.stats(s.id)["documents"], "status": _status(library.status(s.id))}
+ for s in ws.sections()
+ ],
+ }
+
+ @app.post("/categories", status_code=201)
+ def add_category(body: NameIn) -> dict[str, str]:
+ return asdict(ws.add_category(body.name))
+
+ @app.patch("/categories/{category_id}")
+ def rename_category(category_id: str, body: NameIn) -> dict[str, str]:
+ return asdict(ws.rename_category(category_id, body.name))
+
+ @app.delete("/categories/{category_id}", status_code=204)
+ def delete_category(category_id: str) -> Response:
+ ws.delete_category(category_id)
+ return Response(status_code=204)
+
+ @app.post("/sections", status_code=201)
+ def add_section(body: SectionIn) -> dict[str, Any]:
+ return _section(ws.add_section(body.name, body.category_id))
+
+ @app.patch("/sections/{section_id}")
+ def update_section(section_id: str, body: SectionPatch) -> dict[str, Any]:
+ return _section(ws.update_section(section_id, name=body.name, category_id=body.category_id))
+
+ @app.delete("/sections/{section_id}", status_code=204)
+ def delete_section(section_id: str) -> Response:
+ library.delete_section(section_id)
+ return Response(status_code=204)
+
+ @app.post("/sections/{section_id}/folders")
+ def add_folder(section_id: str, body: FolderIn) -> dict[str, Any]:
+ from pathlib import Path
+
+ return _section(ws.add_folder(section_id, Path(body.path)))
+
+ @app.post("/sections/{section_id}/folders/remove")
+ def remove_folder(section_id: str, body: FolderIn) -> dict[str, Any]:
+ return _section(ws.remove_folder(section_id, body.path))
+
+ @app.post("/sections/{section_id}/index", status_code=202)
+ def index(section_id: str) -> dict[str, Any]:
+ return _status(library.start_indexing(section_id))
+
+ @app.get("/sections/{section_id}/status")
+ def status(section_id: str) -> dict[str, Any]:
+ return _status(library.status(section_id))
+
+ @app.get("/sections/{section_id}/documents")
+ def documents(section_id: str) -> list[dict[str, Any]]:
+ return library.documents(section_id)
+
+ @app.post("/ask")
+ 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
+
+ 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,
+ "name": section.name,
+ "category_id": section.category_id,
+ "folders": list(section.folders),
+ }
+
+
+def _status(status: IndexStatus) -> dict[str, Any]:
+ report = status.report
+ return {
+ "state": status.state,
+ "done": status.done,
+ "total": status.total,
+ "current": status.current,
+ "error": status.error,
+ "missing_folders": list(status.missing_folders),
+ "report": None
+ if report is None
+ else {
+ "added": len(report.added),
+ "updated": len(report.updated),
+ "unchanged": len(report.unchanged),
+ "removed": len(report.removed),
+ "failed": [{"source": s, "error": e} for s, e in report.failed],
+ },
+ }
+
+
+def _answer(answer: Answer, default_section: str | None) -> dict[str, Any]:
+ def source(number: int) -> dict[str, Any]:
+ passage = answer.retrieval.passages[number - 1]
+ meta = passage.doc.metadata
+ return {
+ "number": number,
+ "label": citation_label(passage.doc),
+ "source": meta.get(SOURCE),
+ "page": meta.get(PAGE),
+ "section_id": meta.get(SECTION_ID, default_section),
+ "score": passage.score,
+ "snippet": passage.doc.page_content[:SNIPPET],
+ }
+
+ return {
+ "question": answer.question,
+ "text": answer.text,
+ "abstained": answer.abstained,
+ "grounded": answer.grounded,
+ "invalid_citations": answer.invalid_citations,
+ "citations": [source(c.number) for c in answer.citations],
+ "sources": [source(n) for n in range(1, len(answer.retrieval.passages) + 1)],
+ }
+
+
+def _classify(error: Exception) -> tuple[int, str, str]:
+ if isinstance(error, NotFoundError):
+ return 404, "Not found", str(error)
+ if isinstance(error, WorkspaceError):
+ return 422, "Invalid request", str(error)
+ if isinstance(error, ConflictError | IndexMismatchError):
+ return 409, "Conflict", str(error)
+ if isinstance(error, httpx.ConnectError) or type(error).__name__ == "APIConnectionError":
+ return 503, "Language model unavailable", "The local language model isn't running."
+ log.exception("Unexpected error", exc_info=error)
+ return 500, "Internal error", "Something went wrong. The engine log has the details."
+
+
+def _problem(status: int, title: str, detail: str) -> JSONResponse:
+ body = {"type": "about:blank", "title": title, "status": status, "detail": detail}
+ return JSONResponse(body, status_code=status, media_type="application/problem+json")
+
+
+def _add_error_handlers(app: FastAPI) -> None:
+ @app.exception_handler(HTTPException)
+ async def http_error(_: Request, error: HTTPException) -> JSONResponse:
+ return _problem(error.status_code, "Unauthorized" if error.status_code == 401 else "Error", str(error.detail))
+
+ @app.exception_handler(RequestValidationError)
+ async def invalid(_: Request, error: RequestValidationError) -> JSONResponse:
+ detail = "; ".join(f"{'.'.join(str(p) for p in e['loc'][1:])}: {e['msg']}" for e in error.errors())
+ return _problem(422, "Invalid request", detail)
+
+ async def known_error(_: Request, error: Exception) -> JSONResponse:
+ return _problem(*_classify(error))
+
+ for known in (NotFoundError, WorkspaceError, ConflictError, IndexMismatchError, httpx.ConnectError, Exception):
+ app.add_exception_handler(known, known_error)
diff --git a/src/open_rag_engine/cli.py b/src/open_rag_engine/cli.py
index 0313d01..6cee8f8 100644
--- a/src/open_rag_engine/cli.py
+++ b/src/open_rag_engine/cli.py
@@ -2,7 +2,11 @@
from __future__ import annotations
+import os
+import socket
import sys
+import threading
+import time
from pathlib import Path
from typing import Annotated, Any
@@ -15,6 +19,7 @@
from .conversation import Turn
from .engine import Engine
from .ingest import IndexMismatchError
+from .offline import go_offline_if_possible, quiet_and_private
from .pipeline import RetrievalResult
app = typer.Typer(
@@ -27,8 +32,9 @@
@app.callback()
-def _utf8_output() -> None:
- """Write UTF-8 even when Windows pipes stdout with a legacy code page, so accents and units survive."""
+def _startup() -> None:
+ """Private, quiet, UTF-8 output. Runs before any command loads a model."""
+ quiet_and_private()
for stream in (sys.stdout, sys.stderr):
reconfigure = getattr(stream, "reconfigure", None)
if reconfigure is not None:
@@ -49,7 +55,12 @@ def _utf8_output() -> 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(_models_on_disk(config))
return Engine.from_config(config)
@@ -231,6 +242,84 @@ def action():
_run(action)
+TOKEN_VARIABLE = "ORE_API_TOKEN"
+
+
+@app.command()
+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."""
+
+ def action():
+ token = os.environ.get(TOKEN_VARIABLE, "")
+ if len(token) < 32:
+ raise ValueError(f"Set {TOKEN_VARIABLE} to a random secret of at least 32 characters.")
+ cfg = _config(config)
+ 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
+
+ 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()
+ if parent_pid:
+ threading.Thread(target=_exit_with_parent, args=(parent_pid,), daemon=True).start()
+ import uvicorn
+
+ uvicorn.Server(uvicorn.Config(api, log_level="warning", access_log=False)).run(sockets=[server])
+
+ _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)
+ server.bind(("127.0.0.1", port))
+ return server
+
+
+def _exit_with_parent(pid: int) -> None:
+ """Backstop for the app's job object: if the app disappears, the engine must not linger."""
+ if sys.platform == "win32":
+ import ctypes
+
+ synchronize, infinite = 0x00100000, 0xFFFFFFFF
+ handle = ctypes.windll.kernel32.OpenProcess(synchronize, False, pid)
+ if handle:
+ ctypes.windll.kernel32.WaitForSingleObject(handle, infinite)
+ else:
+ while os.getppid() == pid:
+ time.sleep(2)
+ os._exit(0)
+
+
def _echo_token(token: str) -> None:
typer.echo(token, nl=False)
diff --git a/src/open_rag_engine/config.py b/src/open_rag_engine/config.py
index 242d7ac..3215de4 100644
--- a/src/open_rag_engine/config.py
+++ b/src/open_rag_engine/config.py
@@ -54,6 +54,8 @@ class RerankConfig(_Section):
class LLMConfig(_Section):
+ provider: Literal["ollama", "openai"] = "ollama"
+ """`openai` means any OpenAI-compatible server, such as llama.cpp's `llama-server` bundled with the desktop app."""
model: str = "qwen3:4b-instruct-2507-q4_K_M"
base_url: str = "http://localhost:11434"
temperature: float = Field(0.0, ge=0, le=2)
@@ -71,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()
@@ -91,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:
@@ -105,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/engine.py b/src/open_rag_engine/engine.py
index 59cbc51..58e81d6 100644
--- a/src/open_rag_engine/engine.py
+++ b/src/open_rag_engine/engine.py
@@ -15,7 +15,7 @@
from .config import EngineConfig
from .conversation import Turn, standalone_question
from .evaluation import EvalReport, evaluate, load_dataset
-from .ingest import IndexMismatchError, IngestReport, ingest
+from .ingest import IndexMismatchError, IngestReport, Progress, ingest
from .pipeline import RetrievalPipeline, RetrievalResult
from .rerank import Reranker
from .retrieval import Filter
@@ -50,12 +50,21 @@ def from_config(cls, config: EngineConfig) -> Engine:
def store(self) -> ChunkStore:
return ChunkStore(self.config.data_dir, self.config.collection, self._models.embeddings)
- def ingest(self, paths: Iterable[Path], rebuild: bool = False) -> IngestReport:
+ def ingest(
+ self,
+ paths: Iterable[Path],
+ rebuild: bool = False,
+ prune: bool = False,
+ on_progress: Progress | None = None,
+ keep: Sequence[str] = (),
+ ) -> IngestReport:
cfg = self.config
embeddings = self._models.embeddings if cfg.chunking.strategy == "semantic" else None
- return ingest(paths, self.store, make_splitter(cfg.chunking, embeddings), cfg.index_fingerprint(), rebuild)
+ splitter = make_splitter(cfg.chunking, embeddings)
+ return ingest(paths, self.store, splitter, cfg.index_fingerprint(), rebuild, prune, on_progress, keep)
- def pipeline(self) -> RetrievalPipeline:
+ def pipeline(self, rerank: bool | None = None, top_n: int | None = None) -> RetrievalPipeline:
+ """The configured pipeline; `rerank` and `top_n` override the configuration for this call only."""
cfg = self.config
indexed_with = self.store.manifest().index_fingerprint
if indexed_with is not None and indexed_with != cfg.index_fingerprint():
@@ -63,9 +72,11 @@ def pipeline(self) -> RetrievalPipeline:
"The collection was indexed with a different chunking or embedding configuration. "
"Run `ore ingest --rebuild` with the current configuration first."
)
- reranker = Reranker(self._models.cross_encoder, cfg.rerank.top_n) if cfg.rerank.enabled else None
+ top_n = top_n or cfg.rerank.top_n
+ use_reranker = cfg.rerank.enabled if rerank is None else rerank
+ reranker = Reranker(self._models.cross_encoder, top_n) if use_reranker else None
llm = self._models.llm if cfg.retrieval.multi_query else None
- return RetrievalPipeline(self.store, cfg.retrieval, reranker=reranker, llm=llm, top_n=cfg.rerank.top_n)
+ return RetrievalPipeline(self.store, cfg.retrieval, reranker=reranker, llm=llm, top_n=top_n)
def retrieve(self, query: str, filter: Filter | None = None) -> RetrievalResult:
return self.pipeline().run(query, filter)
diff --git a/src/open_rag_engine/factory.py b/src/open_rag_engine/factory.py
index d7fbfa7..f697edc 100644
--- a/src/open_rag_engine/factory.py
+++ b/src/open_rag_engine/factory.py
@@ -2,7 +2,9 @@
from __future__ import annotations
-from functools import cached_property
+import os
+import threading
+from typing import Any
from langchain_community.cross_encoders import HuggingFaceCrossEncoder
from langchain_core.embeddings import Embeddings
@@ -14,28 +16,57 @@
class LocalModels:
def __init__(self, config: EngineConfig):
self._config = config
+ # 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] = {}
- @cached_property
+ 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:
- return HuggingFaceCrossEncoder(model_name=self._config.rerank.model, model_kwargs={"device": "cpu"})
+ def _cross_encoder(self) -> HuggingFaceCrossEncoder:
+ _quiet_transformers()
+ model = self._config.model_path(self._config.rerank.model)
+ return HuggingFaceCrossEncoder(model_name=model, model_kwargs={"device": "cpu"})
+
+ def _llm(self) -> BaseChatModel:
+ cfg = self._config.llm
+ if cfg.provider == "openai":
+ from langchain_openai import ChatOpenAI
+
+ # A local server needs no key; a hosted one reads the user's own key from the environment (C-03).
+ key = os.environ.get("ORE_LLM_API_KEY", "not-needed")
+ return ChatOpenAI(model=cfg.model, base_url=cfg.base_url, api_key=key, temperature=cfg.temperature)
- @cached_property
- def llm(self) -> BaseChatModel:
from langchain_ollama import ChatOllama
- cfg = self._config.llm
# Reasoning adds minutes before the first answer token on a CPU, so it is off by default (LLMConfig.think).
return ChatOllama(
model=cfg.model,
@@ -52,3 +83,11 @@ def _encode_kwargs(prefix: str) -> dict[str, object]:
if prefix:
kwargs["prompt"] = prefix
return kwargs
+
+
+def _quiet_transformers() -> None:
+ """No "Loading weights" progress bars or advisory warnings on the console."""
+ from transformers.utils import logging as transformers_logging
+
+ transformers_logging.disable_progress_bar()
+ transformers_logging.set_verbosity_error()
diff --git a/src/open_rag_engine/ingest.py b/src/open_rag_engine/ingest.py
index ec2fdbb..72a0377 100644
--- a/src/open_rag_engine/ingest.py
+++ b/src/open_rag_engine/ingest.py
@@ -3,7 +3,7 @@
from __future__ import annotations
import logging
-from collections.abc import Iterable
+from collections.abc import Callable, Iterable, Sequence
from dataclasses import dataclass, field
from pathlib import Path
from typing import Protocol
@@ -32,11 +32,28 @@ class IngestReport:
unchanged: list[str] = field(default_factory=list)
failed: list[tuple[str, str]] = field(default_factory=list)
chunks_added: int = 0
+ removed: list[str] = field(default_factory=list)
+
+
+Progress = Callable[[int, int, str], None]
+"""Called after each file with (files done, files in total, source path)."""
def ingest(
- paths: Iterable[Path], store: ChunkStore, splitter: Splitter, index_fingerprint: str, rebuild: bool = False
+ paths: Iterable[Path],
+ store: ChunkStore,
+ splitter: Splitter,
+ index_fingerprint: str,
+ rebuild: bool = False,
+ prune: bool = False,
+ on_progress: Progress | None = None,
+ keep: Sequence[str] = (),
) -> IngestReport:
+ """Index the files under `paths`.
+
+ With `prune`, documents that are no longer under `paths` leave the index, except those under a folder in
+ `keep` (for example a USB drive that is unplugged right now).
+ """
files = discover(paths)
stored = store.manifest().index_fingerprint
if rebuild:
@@ -52,25 +69,46 @@ def ingest(
unchanged: list[str] = []
failed: list[tuple[str, str]] = []
chunks_added = 0
- for path in files:
+ outcomes: dict[str, list[str]] = {"added": added, "updated": updated, "unchanged": unchanged}
+ for done, path in enumerate(files, start=1):
source = path.as_posix()
- doc_id = content_hash(path.read_bytes())
- previous = store.manifest().documents.get(source)
- if previous == doc_id:
- unchanged.append(source)
- continue
- try:
- chunks = _chunk(load(path), splitter, doc_id, index_fingerprint)
- except Exception as error: # one unreadable file must not stop the batch
- log.warning("Could not ingest %s: %s", source, error)
- failed.append((source, str(error)))
- continue
- if previous is not None:
- store.remove(source)
- store.add(source, doc_id, chunks, index_fingerprint)
- (updated if previous is not None else added).append(source)
- chunks_added += len(chunks)
- return IngestReport(added, updated, unchanged, failed, chunks_added)
+ outcome, count, error = _ingest_file(path, source, store, splitter, index_fingerprint)
+ if error is not None:
+ failed.append((source, error))
+ else:
+ outcomes[outcome].append(source)
+ chunks_added += count
+ if on_progress:
+ on_progress(done, len(files), source)
+
+ removed: list[str] = []
+ if prune:
+ present = {path.as_posix() for path in files}
+ kept = tuple(folder.rstrip("/") + "/" for folder in keep)
+ for source in store.manifest().documents:
+ if source not in present and not source.startswith(kept):
+ store.remove(source)
+ removed.append(source)
+ return IngestReport(added, updated, unchanged, failed, chunks_added, removed)
+
+
+def _ingest_file(
+ path: Path, source: str, store: ChunkStore, splitter: Splitter, index_fingerprint: str
+) -> tuple[str, int, str | None]:
+ """Index one file unless it is unchanged: (outcome, chunks added, error message or None)."""
+ doc_id = content_hash(path.read_bytes())
+ previous = store.manifest().documents.get(source)
+ if previous == doc_id:
+ return "unchanged", 0, None
+ try:
+ chunks = _chunk(load(path), splitter, doc_id, index_fingerprint)
+ except Exception as error: # one unreadable file must not stop the batch
+ log.warning("Could not ingest %s: %s", source, error)
+ return "failed", 0, str(error)
+ if previous is not None:
+ store.remove(source)
+ store.add(source, doc_id, chunks, index_fingerprint)
+ return ("updated" if previous is not None else "added"), len(chunks), None
def _chunk(documents: list[Document], splitter: Splitter, doc_id: str, index_fingerprint: str) -> list[Document]:
diff --git a/src/open_rag_engine/library.py b/src/open_rag_engine/library.py
new file mode 100644
index 0000000..b439fa8
--- /dev/null
+++ b/src/open_rag_engine/library.py
@@ -0,0 +1,199 @@
+"""The desktop app's service: sections with their own indexes, background indexing, and answers scoped to a
+section or to a whole category."""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import threading
+from collections.abc import Callable, Sequence
+from concurrent.futures import Executor, Future, ThreadPoolExecutor
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Any, Literal
+
+from langchain_core.documents import Document
+
+from .answer import Answer, generate_answer
+from .config import EngineConfig
+from .conversation import Turn, standalone_question
+from .documents import CHUNK_INDEX, SOURCE, citation_label
+from .engine import Engine, Models
+from .fusion import reciprocal_rank_fusion
+from .ingest import IngestReport
+from .pipeline import Passage, RetrievalResult, StageTrace
+from .rerank import Reranker
+from .workspace import Section, Workspace
+
+log = logging.getLogger(__name__)
+
+SECTION_ID = "section_id"
+ScopeKind = Literal["section", "category"]
+
+
+class ConflictError(RuntimeError):
+ """The request clashes with work in progress, such as asking a section while it is being indexed."""
+
+
+@dataclass(frozen=True)
+class IndexStatus:
+ state: Literal["idle", "indexing", "error"] = "idle"
+ done: int = 0
+ total: int = 0
+ current: str | None = None
+ error: str | None = None
+ missing_folders: tuple[str, ...] = ()
+ report: IngestReport | None = None
+
+
+class Library:
+ def __init__(self, config: EngineConfig, models: Models, executor: Executor | None = None):
+ self.config = config
+ self._models = models
+ self.workspace = Workspace(Path(config.data_dir) / "workspace.json")
+ # One indexing job at a time: on a laptop CPU, parallel jobs only slow each other down.
+ self._executor = executor or ThreadPoolExecutor(max_workers=1, thread_name_prefix="indexer")
+ self._engines: dict[str, Engine] = {}
+ self._status: dict[str, IndexStatus] = {}
+ self._futures: dict[str, Future] = {}
+ self._lock = threading.RLock()
+
+ def engine(self, section_id: str) -> Engine:
+ section = self.workspace.section(section_id)
+ with self._lock:
+ if section_id not in self._engines:
+ config = EngineConfig.model_validate({**self.config.model_dump(), "collection": section.collection})
+ engine = Engine(config, self._models)
+ _ = engine.store # open the store now, under the lock
+ self._engines[section_id] = engine
+ return self._engines[section_id]
+
+ def status(self, section_id: str) -> IndexStatus:
+ self.workspace.section(section_id)
+ return self._status.get(section_id, IndexStatus())
+
+ def stats(self, section_id: str) -> dict[str, Any]:
+ return self.engine(section_id).stats()
+
+ def documents(self, section_id: str) -> list[dict[str, Any]]:
+ counts: dict[str, int] = {}
+ for chunk in self.engine(section_id).store.chunks():
+ source = str(chunk.metadata.get(SOURCE))
+ counts[source] = counts.get(source, 0) + 1
+ return [{"source": s, "name": PurePosixPath(s).name, "chunks": n} for s, n in sorted(counts.items())]
+
+ def start_indexing(self, section_id: str) -> IndexStatus:
+ self.workspace.section(section_id)
+ with self._lock:
+ current = self.status(section_id)
+ if current.state == "indexing":
+ return current
+ started = IndexStatus(state="indexing", missing_folders=current.missing_folders)
+ self._status[section_id] = started
+ self._futures[section_id] = self._executor.submit(self._index, section_id)
+ return started
+
+ def wait_for_index(self, section_id: str, timeout: float | None = None) -> IndexStatus:
+ future = self._futures.get(section_id)
+ if future is not None:
+ future.result(timeout)
+ return self.status(section_id)
+
+ def delete_section(self, section_id: str) -> None:
+ if self.status(section_id).state == "indexing":
+ raise ConflictError("Wait until this section has finished indexing")
+ engine = self.engine(section_id)
+ engine.store.vectors.delete_collection()
+ with self._lock:
+ self._engines.pop(section_id, None)
+ self._status.pop(section_id, None)
+ shutil.rmtree(engine.store.directory, ignore_errors=True)
+ self.workspace.delete_section(section_id)
+
+ def ask(
+ self,
+ kind: ScopeKind,
+ scope_id: str,
+ question: str,
+ history: Sequence[Turn] = (),
+ on_token: Callable[[str], None] | None = None,
+ ) -> Answer:
+ sections = self.scope_sections(kind, scope_id)
+ if kind == "section":
+ return self.engine(scope_id).ask(question, history, on_token=on_token)
+ llm = self._models.llm
+ standalone = standalone_question(llm, history, question)
+ retrieval = self._retrieve_across(sections, standalone)
+ min_score = self.config.answer.min_rerank_score if self.config.rerank.enabled else None
+ return generate_answer(standalone, retrieval, llm, min_score, on_token)
+
+ def scope_sections(self, kind: ScopeKind, scope_id: str) -> list[Section]:
+ """The sections a question searches. Raises when the scope is unknown or a section is still indexing."""
+ if kind == "section":
+ sections = [self.workspace.section(scope_id)]
+ else:
+ self.workspace.category(scope_id)
+ sections = self.workspace.sections(scope_id)
+ busy = [s.name for s in sections if self.status(s.id).state == "indexing"]
+ if busy:
+ raise ConflictError(f"Still indexing: {', '.join(busy)}. Ask again when it has finished.")
+ return sections
+
+ def _index(self, section_id: str) -> None:
+ section = self.workspace.section(section_id)
+ present = [Path(f) for f in section.folders if Path(f).is_dir()]
+ missing = tuple(f for f in section.folders if not Path(f).is_dir())
+
+ def progress(done: int, total: int, source: str) -> None:
+ self._set(section_id, IndexStatus("indexing", done, total, source, None, missing))
+
+ try:
+ report = self.engine(section_id).ingest(present, prune=True, keep=missing, on_progress=progress)
+ except Exception as error: # surfaced to the app as an error state rather than lost in a thread
+ log.exception("Indexing section %s failed", section_id)
+ self._set(section_id, IndexStatus(state="error", error=str(error), missing_folders=missing))
+ return
+ files = len(report.added) + len(report.updated) + len(report.unchanged) + len(report.failed)
+ self._set(section_id, IndexStatus("idle", files, files, None, None, missing, report))
+
+ def _set(self, section_id: str, status: IndexStatus) -> None:
+ with self._lock:
+ self._status[section_id] = status
+
+ def _retrieve_across(self, sections: list[Section], query: str) -> RetrievalResult:
+ """Search each section, fuse their lists with RRF, then rerank the fused candidates once."""
+ cfg = self.config
+ lists: list[list[Document]] = []
+ trace: list[StageTrace] = []
+ for section in sections:
+ result = self.engine(section.id).pipeline(rerank=False, top_n=cfg.retrieval.k).run(query)
+ docs = [_tagged(p.doc, section.id) for p in result.passages]
+ lists.append(docs)
+ trace.append(
+ StageTrace(
+ f"section {section.name}",
+ sum(t.ms for t in result.trace),
+ [("*", _label(d), p.score) for d, p in zip(docs, result.passages, strict=True)][:10],
+ )
+ )
+ fused = reciprocal_rank_fusion(lists, k=cfg.retrieval.rrf_k)[: cfg.retrieval.k]
+ trace.append(StageTrace("fusion", 0.0, [("*", _label(d), s) for d, s in fused[:10]]))
+ fusion_scores = {id(d): s for d, s in fused}
+ if cfg.rerank.enabled:
+ ranked = Reranker(self._models.cross_encoder, cfg.rerank.top_n).rerank(query, [d for d, _ in fused])
+ trace.append(StageTrace("rerank", 0.0, [("*", _label(d), s) for d, s in ranked]))
+ else:
+ ranked = fused[: cfg.rerank.top_n]
+ passages = [
+ Passage(d, s, {"fusion": fusion_scores.get(id(d)), **({"rerank": s} if cfg.rerank.enabled else {})})
+ for d, s in ranked
+ ]
+ return RetrievalResult(query=query, queries=[query], passages=passages, trace=trace)
+
+
+def _tagged(doc: Document, section_id: str) -> Document:
+ return Document(page_content=doc.page_content, metadata={**doc.metadata, SECTION_ID: section_id})
+
+
+def _label(doc: Document) -> str:
+ return f"{citation_label(doc)} #{doc.metadata.get(CHUNK_INDEX, '?')}"
diff --git a/src/open_rag_engine/offline.py b/src/open_rag_engine/offline.py
new file mode 100644
index 0000000..fb1c484
--- /dev/null
+++ b/src/open_rag_engine/offline.py
@@ -0,0 +1,50 @@
+"""Keep the engine private and quiet: no telemetry, no progress bars, and no network when the models are on disk.
+
+Call these before any Hugging Face library is imported; they read the environment once, at import time.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable, MutableMapping
+from pathlib import Path
+
+PRIVATE_DEFAULTS = {
+ "HF_HUB_DISABLE_TELEMETRY": "1",
+ "DO_NOT_TRACK": "1",
+ "ANONYMIZED_TELEMETRY": "False",
+ "HF_HUB_DISABLE_PROGRESS_BARS": "1",
+ "TRANSFORMERS_VERBOSITY": "error",
+ "TOKENIZERS_PARALLELISM": "false",
+}
+
+
+def quiet_and_private(env: MutableMapping[str, str] = os.environ) -> None:
+ for key, value in PRIVATE_DEFAULTS.items():
+ env.setdefault(key, value)
+
+
+def hf_cache(env: MutableMapping[str, str] = os.environ) -> Path:
+ if "HF_HUB_CACHE" in env:
+ return Path(env["HF_HUB_CACHE"])
+ home = Path(env["HF_HOME"]) if "HF_HOME" in env else Path.home() / ".cache" / "huggingface"
+ return home / "hub"
+
+
+def available_offline(model: str, env: MutableMapping[str, str] = os.environ) -> bool:
+ """A local model folder, or a Hugging Face repo that is already in the cache."""
+ if Path(model).is_dir():
+ return True
+ if model.count("/") != 1:
+ return False
+ snapshots = hf_cache(env) / f"models--{model.replace('/', '--')}" / "snapshots"
+ return any((snap / "config.json").is_file() for snap in snapshots.glob("*")) if snapshots.is_dir() else False
+
+
+def go_offline_if_possible(models: Iterable[str], env: MutableMapping[str, str] = os.environ) -> bool:
+ """Forbid network access to Hugging Face when every model is already on disk. Returns whether it did."""
+ if not all(available_offline(m, env) for m in models):
+ return False
+ env["HF_HUB_OFFLINE"] = "1"
+ env["TRANSFORMERS_OFFLINE"] = "1"
+ return True
diff --git a/src/open_rag_engine/workspace.py b/src/open_rag_engine/workspace.py
new file mode 100644
index 0000000..2cecc7e
--- /dev/null
+++ b/src/open_rag_engine/workspace.py
@@ -0,0 +1,162 @@
+"""Categories and sections for the desktop app. A section is a set of folders with its own index (one collection)."""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+import uuid
+from dataclasses import asdict, dataclass, replace
+from pathlib import Path
+
+MAX_NAME = 80
+
+
+class WorkspaceError(ValueError):
+ """A request that breaks a workspace rule, such as an empty name."""
+
+
+class NotFoundError(KeyError):
+ """An unknown category or section."""
+
+ def __str__(self) -> str:
+ return str(self.args[0]) if self.args else "Not found"
+
+
+@dataclass(frozen=True)
+class Category:
+ id: str
+ name: str
+
+
+@dataclass(frozen=True)
+class Section:
+ id: str
+ name: str
+ category_id: str
+ folders: tuple[str, ...] = ()
+
+ @property
+ def collection(self) -> str:
+ return f"s-{self.id}"
+
+
+@dataclass(frozen=True)
+class _State:
+ categories: tuple[Category, ...] = ()
+ sections: tuple[Section, ...] = ()
+
+
+class Workspace:
+ """Persisted as one JSON file. Every change writes a new state; nothing is mutated in place."""
+
+ def __init__(self, path: Path):
+ self._path = path
+ self._lock = threading.Lock()
+
+ def categories(self) -> list[Category]:
+ return list(self._load().categories)
+
+ def sections(self, category_id: str | None = None) -> list[Section]:
+ return [s for s in self._load().sections if category_id is None or s.category_id == category_id]
+
+ def category(self, category_id: str) -> Category:
+ return _find(self._load().categories, category_id, "category")
+
+ def section(self, section_id: str) -> Section:
+ return _find(self._load().sections, section_id, "section")
+
+ def add_category(self, name: str) -> Category:
+ category = Category(_new_id(), _valid_name(name))
+ self._update(lambda s: replace(s, categories=(*s.categories, category)))
+ return category
+
+ def rename_category(self, category_id: str, name: str) -> Category:
+ renamed = replace(self.category(category_id), name=_valid_name(name))
+ self._update(lambda s: replace(s, categories=_swap(s.categories, renamed)))
+ return renamed
+
+ def delete_category(self, category_id: str) -> None:
+ self.category(category_id)
+ if self.sections(category_id):
+ raise WorkspaceError("Move or delete the sections in this category first")
+ self._update(lambda s: replace(s, categories=tuple(c for c in s.categories if c.id != category_id)))
+
+ def add_section(self, name: str, category_id: str) -> Section:
+ self.category(category_id)
+ section = Section(_new_id(), _valid_name(name), category_id)
+ self._update(lambda s: replace(s, sections=(*s.sections, section)))
+ return section
+
+ def update_section(self, section_id: str, name: str | None = None, category_id: str | None = None) -> Section:
+ section = self.section(section_id)
+ if category_id is not None:
+ self.category(category_id)
+ updated = replace(
+ section,
+ name=_valid_name(name) if name is not None else section.name,
+ category_id=category_id or section.category_id,
+ )
+ self._update(lambda s: replace(s, sections=_swap(s.sections, updated)))
+ return updated
+
+ def delete_section(self, section_id: str) -> None:
+ self.section(section_id)
+ self._update(lambda s: replace(s, sections=tuple(x for x in s.sections if x.id != section_id)))
+
+ def add_folder(self, section_id: str, folder: Path) -> Section:
+ section = self.section(section_id)
+ if not folder.is_dir():
+ raise WorkspaceError(f"Not a folder: {folder}")
+ path = folder.resolve().as_posix()
+ if path in section.folders:
+ return section
+ updated = replace(section, folders=(*section.folders, path))
+ self._update(lambda s: replace(s, sections=_swap(s.sections, updated)))
+ return updated
+
+ def remove_folder(self, section_id: str, folder: Path | str) -> Section:
+ section = self.section(section_id)
+ target = Path(folder).resolve().as_posix() if Path(folder).exists() else str(folder)
+ updated = replace(section, folders=tuple(f for f in section.folders if f not in {target, str(folder)}))
+ self._update(lambda s: replace(s, sections=_swap(s.sections, updated)))
+ return updated
+
+ def _load(self) -> _State:
+ if not self._path.exists():
+ return _State()
+ data = json.loads(self._path.read_text(encoding="utf-8"))
+ return _State(
+ categories=tuple(Category(**c) for c in data.get("categories", [])),
+ sections=tuple(Section(**{**s, "folders": tuple(s.get("folders", []))}) for s in data.get("sections", [])),
+ )
+
+ def _update(self, change) -> None:
+ with self._lock:
+ state = change(self._load())
+ self._path.parent.mkdir(parents=True, exist_ok=True)
+ tmp = self._path.with_suffix(".tmp")
+ tmp.write_text(json.dumps(asdict(state), indent=1, ensure_ascii=False), encoding="utf-8")
+ os.replace(tmp, self._path)
+
+
+def _new_id() -> str:
+ return uuid.uuid4().hex[:12]
+
+
+def _valid_name(name: str) -> str:
+ name = (name or "").strip()
+ if not name or len(name) > MAX_NAME:
+ raise WorkspaceError(f"A name needs 1 to {MAX_NAME} characters")
+ return name
+
+
+def _find(items, item_id: str, kind: str):
+ for item in items:
+ if item.id == item_id:
+ return item
+ raise NotFoundError(f"Unknown {kind}: {item_id}")
+
+
+def _swap(items, new):
+ return tuple(new if item.id == new.id else item for item in items)
diff --git a/tests/test_api.py b/tests/test_api.py
new file mode 100644
index 0000000..5fc43ce
--- /dev/null
+++ b/tests/test_api.py
@@ -0,0 +1,146 @@
+import json
+from pathlib import Path
+
+import pytest
+from fastapi.testclient import TestClient
+from langchain_core.language_models.fake_chat_models import FakeListChatModel
+
+from open_rag_engine.api import create_app
+from open_rag_engine.library import Library
+
+from .conftest import FakeModels, HashEmbeddings, OverlapCrossEncoder
+from .test_library import ManualExecutor, write
+
+TOKEN = "t" * 32
+ORIGIN = "https://app.ore"
+AUTH = {"Authorization": f"Bearer {TOKEN}"}
+
+
+def make_client(library: Library, base_url: str = "http://127.0.0.1:8765") -> TestClient:
+ return TestClient(create_app(library, token=TOKEN, origins=[ORIGIN]), base_url=base_url)
+
+
+@pytest.fixture
+def library(config) -> Library:
+ return Library(
+ config, FakeModels(HashEmbeddings(), OverlapCrossEncoder(), FakeListChatModel(responses=["1.2 kW [1]."]))
+ )
+
+
+@pytest.fixture
+def client(library) -> TestClient:
+ return make_client(library)
+
+
+def test_every_request_needs_the_token(client: TestClient):
+ assert client.get("/health").status_code == 401
+ assert client.get("/health", headers={"Authorization": "Bearer wrong"}).status_code == 401
+ response = client.get("/health", headers=AUTH)
+ assert response.status_code == 200 and response.json()["status"] == "ok"
+
+
+def test_only_loopback_hosts_are_served(library: Library):
+ assert make_client(library, "http://evil.example").get("/health", headers=AUTH).status_code == 400
+
+
+def test_cors_allows_only_the_app_origin(client: TestClient):
+ preflight = {"Access-Control-Request-Method": "POST", "Access-Control-Request-Headers": "authorization"}
+ ok = client.options("/ask", headers={"Origin": ORIGIN, **preflight})
+ assert ok.status_code == 200 and ok.headers["access-control-allow-origin"] == ORIGIN
+ denied = client.options("/ask", headers={"Origin": "https://evil.example", **preflight})
+ assert "access-control-allow-origin" not in denied.headers
+
+
+def create_section(client: TestClient, folder: Path) -> str:
+ category = client.post("/categories", json={"name": "Garden"}, headers=AUTH)
+ assert category.status_code == 201
+ section = client.post("/sections", json={"name": "Pump", "category_id": category.json()["id"]}, headers=AUTH)
+ assert section.status_code == 201
+ section_id = section.json()["id"]
+ added = client.post(f"/sections/{section_id}/folders", json={"path": str(folder)}, headers=AUTH)
+ assert added.status_code == 200 and added.json()["folders"] == [folder.resolve().as_posix()]
+ return section_id
+
+
+def test_library_flow(client: TestClient, library: Library, tmp_path: Path):
+ section_id = create_section(client, write(tmp_path / "pump", {"power.md": "The pump draws 1.2 kW."}))
+ started = client.post(f"/sections/{section_id}/index", headers=AUTH)
+ assert started.status_code == 202 and started.json()["state"] == "indexing"
+ library.wait_for_index(section_id)
+ status = client.get(f"/sections/{section_id}/status", headers=AUTH).json()
+ assert status["state"] == "idle" and status["report"]["added"] == 1
+ assert [d["name"] for d in client.get(f"/sections/{section_id}/documents", headers=AUTH).json()] == ["power.md"]
+ overview = client.get("/library", headers=AUTH).json()
+ assert overview["categories"][0]["name"] == "Garden"
+ assert overview["sections"][0]["documents"] == 1 and overview["sections"][0]["status"]["state"] == "idle"
+ renamed = client.patch(f"/sections/{section_id}", json={"name": "Garden pump"}, headers=AUTH)
+ assert renamed.json()["name"] == "Garden pump"
+ assert client.delete(f"/sections/{section_id}", headers=AUTH).status_code == 204
+
+
+def test_ask_streams_tokens_then_the_cited_answer(client: TestClient, library: Library, tmp_path: Path):
+ section_id = create_section(client, write(tmp_path / "pump", {"power.md": "The pump draws 1.2 kW."}))
+ client.post(f"/sections/{section_id}/index", headers=AUTH)
+ library.wait_for_index(section_id)
+ body = {"scope": {"kind": "section", "id": section_id}, "question": "How much power?", "history": []}
+ response = client.post("/ask", json=body, headers=AUTH)
+ assert response.status_code == 200 and response.headers["content-type"].startswith("application/x-ndjson")
+ events = [json.loads(line) for line in response.text.splitlines()]
+ assert "".join(e["text"] for e in events if e["type"] == "token") == "1.2 kW [1]."
+ done = events[-1]
+ assert done["type"] == "done" and done["grounded"] is True
+ citation = done["citations"][0]
+ assert citation["label"] == "power.md" and citation["section_id"] == section_id
+ assert citation["source"].endswith("/pump/power.md") and "1.2 kW" in citation["snippet"]
+
+
+def test_errors_are_problem_details(client: TestClient, tmp_path: Path):
+ missing = client.get("/sections/nope/status", headers=AUTH)
+ assert missing.status_code == 404 and missing.json()["title"] == "Not found"
+ assert client.post("/categories", json={"name": ""}, headers=AUTH).status_code == 422
+ category_id = client.post("/categories", json={"name": "A"}, headers=AUTH).json()["id"]
+ section_id = client.post("/sections", json={"name": "S", "category_id": category_id}, headers=AUTH).json()["id"]
+ bad_folder = client.post(f"/sections/{section_id}/folders", json={"path": str(tmp_path / "nope")}, headers=AUTH)
+ assert bad_folder.status_code == 422 and "Not a folder" in bad_folder.json()["detail"]
+ assert client.delete(f"/categories/{category_id}", headers=AUTH).status_code == 422
+
+
+def test_asking_while_indexing_is_a_conflict(config, tmp_path: Path):
+ models = FakeModels(HashEmbeddings(), OverlapCrossEncoder(), FakeListChatModel(responses=["-"]))
+ client = make_client(Library(config, models, executor=ManualExecutor()))
+ section_id = create_section(client, write(tmp_path / "pump", {"a.md": "pump"}))
+ client.post(f"/sections/{section_id}/index", headers=AUTH)
+ 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 7e109af..07d1221 100644
--- a/tests/test_engine_and_cli.py
+++ b/tests/test_engine_and_cli.py
@@ -105,3 +105,34 @@ def test_querying_with_a_changed_index_configuration_asks_for_a_rebuild(monkeypa
changed = config.updated("chunking", chunk_size=300)
result = run_cli(monkeypatch, changed, "search", "pump")
assert result.exit_code == 1 and "--rebuild" in result.output
+
+
+def test_serve_refuses_to_start_without_a_strong_token(monkeypatch):
+ monkeypatch.delenv("ORE_API_TOKEN", raising=False)
+ result = CliRunner().invoke(cli.app, ["serve"])
+ assert result.exit_code == 1 and "ORE_API_TOKEN" in result.output
+
+
+def test_listen_binds_loopback_on_a_free_port():
+ server = cli._listen(0)
+ try:
+ host, port = server.getsockname()
+ 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
new file mode 100644
index 0000000..d4f6648
--- /dev/null
+++ b/tests/test_factory.py
@@ -0,0 +1,37 @@
+from open_rag_engine.config import EngineConfig
+from open_rag_engine.factory import LocalModels
+
+
+def test_ollama_is_the_default_llm_runtime():
+ llm = LocalModels(EngineConfig()).llm
+ assert type(llm).__name__ == "ChatOllama" and llm.reasoning is False
+
+
+def test_an_openai_compatible_server_can_replace_ollama(monkeypatch):
+ monkeypatch.delenv("ORE_LLM_API_KEY", raising=False)
+ cfg = EngineConfig().updated("llm", provider="openai", base_url="http://127.0.0.1:8090/v1", model="qwen3-4b")
+ 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
diff --git a/tests/test_ingest.py b/tests/test_ingest.py
index 84dfd5d..cd88780 100644
--- a/tests/test_ingest.py
+++ b/tests/test_ingest.py
@@ -60,3 +60,31 @@ def test_a_different_index_configuration_needs_a_rebuild(corpus: Path, config):
_ingest([corpus], changed, store)
_, report = _ingest([corpus], changed, store, rebuild=True)
assert len(report.added) == 5 and len(store.chunks()) == 5
+
+
+def test_prune_removes_documents_whose_files_are_gone(corpus: Path, config):
+ store, _ = _ingest([corpus], config)
+ (corpus / "winter.md").unlink()
+ splitter = make_splitter(config.chunking, embeddings=None)
+ report = ingest([corpus], store, splitter, config.index_fingerprint(), prune=True)
+ assert [Path(s).name for s in report.removed] == ["winter.md"]
+ assert len(store.chunks()) == 4 and len(store.vectors.get()["ids"]) == 4
+
+
+def test_prune_with_no_paths_empties_the_collection(corpus: Path, config):
+ store, _ = _ingest([corpus], config)
+ report = ingest([], store, make_splitter(config.chunking, None), config.index_fingerprint(), prune=True)
+ assert len(report.removed) == 5 and store.chunks() == []
+
+
+def test_progress_is_reported_per_file(corpus: Path, config):
+ seen: list[tuple[int, int]] = []
+ store = _store(config)
+ ingest(
+ [corpus],
+ store,
+ make_splitter(config.chunking, None),
+ config.index_fingerprint(),
+ on_progress=lambda done, total, source: seen.append((done, total)),
+ )
+ assert seen == [(1, 5), (2, 5), (3, 5), (4, 5), (5, 5)]
diff --git a/tests/test_library.py b/tests/test_library.py
new file mode 100644
index 0000000..cba8618
--- /dev/null
+++ b/tests/test_library.py
@@ -0,0 +1,139 @@
+from concurrent.futures import Future
+from pathlib import Path
+
+import pytest
+from langchain_core.language_models.fake_chat_models import FakeListChatModel
+
+from open_rag_engine.library import ConflictError, Library
+from open_rag_engine.workspace import NotFoundError
+
+from .conftest import FakeModels, HashEmbeddings, OverlapCrossEncoder
+
+
+class ManualExecutor:
+ """Holds submitted jobs until the test runs them."""
+
+ def __init__(self):
+ self.jobs = []
+
+ def submit(self, fn, *args):
+ future = Future()
+ self.jobs.append((fn, args, future))
+ return future
+
+ def run_all(self):
+ for fn, args, future in self.jobs:
+ future.set_result(fn(*args))
+ self.jobs = []
+
+
+def write(folder: Path, files: dict[str, str]) -> Path:
+ folder.mkdir(parents=True, exist_ok=True)
+ for name, text in files.items():
+ (folder / name).write_text(text, encoding="utf-8")
+ return folder
+
+
+@pytest.fixture
+def library(config) -> Library:
+ llm = FakeListChatModel(responses=["It draws 1.2 kW [1]."])
+ return Library(config, FakeModels(HashEmbeddings(), OverlapCrossEncoder(), llm))
+
+
+@pytest.fixture
+def two_sections(library: Library, tmp_path: Path):
+ category = library.workspace.add_category("Garden")
+ pump = library.workspace.add_section("Pump", category.id)
+ mower = library.workspace.add_section("Mower", category.id)
+ library.workspace.add_folder(
+ pump.id, write(tmp_path / "pump", {"power.md": "The pump draws 1.2 kW at full speed."})
+ )
+ library.workspace.add_folder(
+ mower.id, write(tmp_path / "mower", {"blade.md": "Sharpen the mower blade every spring."})
+ )
+ for section in (pump, mower):
+ library.start_indexing(section.id)
+ library.wait_for_index(section.id)
+ return category, pump, mower
+
+
+def sources(answer) -> set[str]:
+ return {Path(p.doc.metadata["source"]).name for p in answer.retrieval.passages}
+
+
+def test_indexing_reports_progress_and_counts(library: Library, two_sections):
+ _, pump, _ = two_sections
+ status = library.status(pump.id)
+ assert status.state == "idle" and (status.done, status.total) == (1, 1)
+ assert library.stats(pump.id)["documents"] == 1
+ assert [d["name"] for d in library.documents(pump.id)] == ["power.md"]
+
+
+def test_a_section_answers_only_from_its_own_documents(library: Library, two_sections):
+ _, pump, _ = two_sections
+ answer = library.ask("section", pump.id, "When should I sharpen the blade?")
+ assert sources(answer) <= {"power.md"}
+
+
+def test_a_category_answers_from_all_its_sections(library: Library, two_sections):
+ category, _, mower = two_sections
+ answer = library.ask("category", category.id, "sharpen the mower blade")
+ assert Path(answer.retrieval.passages[0].doc.metadata["source"]).name == "blade.md"
+ assert answer.retrieval.passages[0].doc.metadata["section_id"] == mower.id
+ assert {"power.md", "blade.md"} >= sources(answer)
+
+
+def test_cannot_ask_while_the_section_is_indexing(config, tmp_path: Path):
+ executor = ManualExecutor()
+ library = Library(
+ config,
+ FakeModels(HashEmbeddings(), OverlapCrossEncoder(), FakeListChatModel(responses=["-"])),
+ executor=executor,
+ )
+ section = library.workspace.add_section("Pump", library.workspace.add_category("Garden").id)
+ library.workspace.add_folder(section.id, write(tmp_path / "pump", {"a.md": "pump"}))
+ assert library.start_indexing(section.id).state == "indexing"
+ assert library.start_indexing(section.id).state == "indexing" and len(executor.jobs) == 1
+ with pytest.raises(ConflictError):
+ library.ask("section", section.id, "pump?")
+ executor.run_all()
+ assert library.status(section.id).state == "idle"
+
+
+def test_removed_files_and_folders_leave_the_index(library: Library, two_sections, tmp_path: Path):
+ _, pump, _ = two_sections
+ library.workspace.remove_folder(pump.id, tmp_path / "pump")
+ library.start_indexing(pump.id)
+ status = library.wait_for_index(pump.id)
+ assert len(status.report.removed) == 1 and library.stats(pump.id)["documents"] == 0
+
+
+def test_a_missing_folder_is_reported_and_its_documents_are_kept(library: Library, two_sections, tmp_path: Path):
+ _, pump, _ = two_sections
+ for file in (tmp_path / "pump").iterdir():
+ file.unlink()
+ (tmp_path / "pump").rmdir()
+ library.start_indexing(pump.id)
+ status = library.wait_for_index(pump.id)
+ assert status.missing_folders == ((tmp_path / "pump").resolve().as_posix(),)
+ assert library.stats(pump.id)["documents"] == 1
+
+
+def test_indexing_errors_are_reported(library: Library, two_sections, monkeypatch):
+ _, pump, _ = two_sections
+
+ def boom(*args, **kwargs):
+ raise RuntimeError("disk full")
+
+ monkeypatch.setattr(library.engine(pump.id), "ingest", boom)
+ library.start_indexing(pump.id)
+ status = library.wait_for_index(pump.id)
+ assert status.state == "error" and "disk full" in status.error
+
+
+def test_deleting_a_section_removes_its_index(library: Library, two_sections, config):
+ _, pump, _ = two_sections
+ library.delete_section(pump.id)
+ with pytest.raises(NotFoundError):
+ library.status(pump.id)
+ assert not (config.data_dir / pump.collection / "chunks.jsonl").exists()
diff --git a/tests/test_offline.py b/tests/test_offline.py
new file mode 100644
index 0000000..62d3ee5
--- /dev/null
+++ b/tests/test_offline.py
@@ -0,0 +1,35 @@
+from pathlib import Path
+
+from open_rag_engine.offline import available_offline, go_offline_if_possible, quiet_and_private
+
+
+def cached(cache: Path, repo: str) -> None:
+ snapshot = cache / f"models--{repo.replace('/', '--')}" / "snapshots" / "abc123"
+ snapshot.mkdir(parents=True)
+ (snapshot / "config.json").write_text("{}", encoding="utf-8")
+
+
+def test_quiet_and_private_keeps_explicit_settings():
+ env = {"DO_NOT_TRACK": "0"}
+ quiet_and_private(env)
+ assert env["DO_NOT_TRACK"] == "0" and env["HF_HUB_DISABLE_TELEMETRY"] == "1"
+
+
+def test_local_folders_and_cached_repos_are_available(tmp_path: Path):
+ env = {"HF_HUB_CACHE": str(tmp_path / "cache")}
+ cached(tmp_path / "cache", "intfloat/multilingual-e5-small")
+ folder = tmp_path / "models" / "reranker"
+ folder.mkdir(parents=True)
+ assert available_offline("intfloat/multilingual-e5-small", env)
+ assert available_offline(str(folder), env)
+ assert not available_offline("other/model", env)
+ assert not available_offline("qwen3:4b", env)
+
+
+def test_goes_offline_only_when_every_model_is_on_disk(tmp_path: Path):
+ env = {"HF_HOME": str(tmp_path)}
+ cached(tmp_path / "hub", "a/one")
+ assert not go_offline_if_possible(["a/one", "b/two"], env) and "HF_HUB_OFFLINE" not in env
+ cached(tmp_path / "hub", "b/two")
+ assert go_offline_if_possible(["a/one", "b/two"], env)
+ assert env["HF_HUB_OFFLINE"] == "1" and env["TRANSFORMERS_OFFLINE"] == "1"
diff --git a/tests/test_workspace.py b/tests/test_workspace.py
new file mode 100644
index 0000000..f17d94e
--- /dev/null
+++ b/tests/test_workspace.py
@@ -0,0 +1,70 @@
+from pathlib import Path
+
+import pytest
+
+from open_rag_engine.workspace import NotFoundError, Workspace, WorkspaceError
+
+
+@pytest.fixture
+def ws(tmp_path: Path) -> Workspace:
+ return Workspace(tmp_path / "workspace.json")
+
+
+def test_categories_and_sections_persist(ws: Workspace, tmp_path: Path):
+ physics = ws.add_category("Physics")
+ optics = ws.add_section("Lesson 3: Optics", physics.id)
+ again = Workspace(tmp_path / "workspace.json")
+ assert [c.name for c in again.categories()] == ["Physics"]
+ assert again.section(optics.id) == optics
+ assert optics.collection.startswith("s-") and optics.collection != optics.id
+
+
+def test_sections_filter_by_category(ws: Workspace):
+ a, b = ws.add_category("A"), ws.add_category("B")
+ ws.add_section("one", a.id)
+ ws.add_section("two", b.id)
+ assert [s.name for s in ws.sections(a.id)] == ["one"]
+ assert len(ws.sections()) == 2
+
+
+def test_rename_and_move(ws: Workspace):
+ a, b = ws.add_category("A"), ws.add_category("B")
+ section = ws.add_section("one", a.id)
+ assert ws.rename_category(a.id, "Alpha").name == "Alpha"
+ moved = ws.update_section(section.id, name="uno", category_id=b.id)
+ assert (moved.name, moved.category_id) == ("uno", b.id)
+
+
+@pytest.mark.parametrize("name", ["", " ", "x" * 81])
+def test_names_are_validated(ws: Workspace, name: str):
+ with pytest.raises(WorkspaceError):
+ ws.add_category(name)
+
+
+def test_a_category_with_sections_cannot_be_deleted(ws: Workspace):
+ cat = ws.add_category("A")
+ section = ws.add_section("one", cat.id)
+ with pytest.raises(WorkspaceError):
+ ws.delete_category(cat.id)
+ ws.delete_section(section.id)
+ ws.delete_category(cat.id)
+ assert ws.categories() == []
+
+
+def test_unknown_ids_raise_not_found(ws: Workspace):
+ with pytest.raises(NotFoundError):
+ ws.section("nope")
+ with pytest.raises(NotFoundError):
+ ws.add_section("x", "missing-category")
+
+
+def test_folders_are_validated_and_deduplicated(ws: Workspace, tmp_path: Path):
+ section = ws.add_section("one", ws.add_category("A").id)
+ folder = tmp_path / "notes"
+ folder.mkdir()
+ ws.add_folder(section.id, folder)
+ updated = ws.add_folder(section.id, folder)
+ assert updated.folders == (folder.resolve().as_posix(),)
+ with pytest.raises(WorkspaceError):
+ ws.add_folder(section.id, tmp_path / "missing")
+ assert ws.remove_folder(section.id, folder).folders == ()
diff --git a/uv.lock b/uv.lock
index 918972c..59125a9 100644
--- a/uv.lock
+++ b/uv.lock
@@ -644,6 +644,23 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/e6/c4/ebdf7837bc4ef6fd98cfb013c28855bb358467bf86c1af011bbc21e21df0/durationpy-0.11-py3-none-any.whl", hash = "sha256:a739fe2b8972c250ff72f8e2c488d18cf25f7b852f49ee76048775d5171df30c", size = 4133, upload-time = "2026-08-26T13:55:59.456Z" },
]
+[[package]]
+name = "fastapi"
+version = "0.162.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "annotated-doc" },
+ { name = "opentelemetry-api" },
+ { name = "pydantic" },
+ { name = "starlette" },
+ { name = "typing-extensions" },
+ { name = "typing-inspection" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e9/eb/2cf8c80abf09b2800aef0a83b41066fbfda8ee5495b7a08b9d1af40f7046/fastapi-0.162.0.tar.gz", hash = "sha256:6a22c1e2e6e32e0633ee7e170f00009a29b8228b16feb219ee42f32fd8d88a8f", size = 527867, upload-time = "2026-10-23T18:47:33.264Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/b4/4f/3f2c25c9b43970b5e9a08beb5e04776247edea684ddc0930f4f02f0bb6cb/fastapi-0.162.0-py3-none-any.whl", hash = "sha256:3785963de305dd09912426cb81f2d230fce98ab3521cdfe97265c8d14983128c", size = 148912, upload-time = "2026-10-23T18:47:31.734Z" },
+]
+
[[package]]
name = "filelock"
version = "4.2.6"
@@ -1076,6 +1093,101 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/62/a1/3d680cbfd5f4b8f15abc1d571870c5fc3e594bb582bc3b64ea099db13e56/jinja2-3.1.6-py3-none-any.whl", hash = "sha256:85ece4451f492d0c13c5dd7c13a64681a86afae63a5f347908daf103ce6d2f67", size = 134899, upload-time = "2025-03-05T20:05:00.369Z" },
]
+[[package]]
+name = "jiter"
+version = "0.18.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/63/5b/f68319f4fe624311a744a33d10fdbcac4c971991e348223cba60d31780b2/jiter-0.18.0.tar.gz", hash = "sha256:a0ca63fd9450a212e4e658d4cfe0ab4977c4f9b0003c68828b843c65e27662ff", size = 234470, upload-time = "2026-10-23T13:51:13.103Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/45/0e/075bfa4fa46820da9ac8cf8a67c435b0586012279fba15deccde0e73b9ce/jiter-0.18.0-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:77a01cdf4381a1becbe5b827f682006f47b712581667451c5b1eb259b9ae7041", size = 290095, upload-time = "2026-10-23T13:49:14.118Z" },
+ { url = "https://files.pythonhosted.org/packages/2e/e2/f4000a4d9c519ca019bf0e2922cc0c6b6db347be6303161382eda7635be7/jiter-0.18.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:7b41cd64ee6b54db94bea6274e6e37002ed526aa06c114a8be6f36ffe21c184e", size = 316319, upload-time = "2026-10-23T13:49:15.263Z" },
+ { url = "https://files.pythonhosted.org/packages/51/93/9aaef4d18d19446fd044b9cff0323b1b45b5526f077f1a80418567a6eef8/jiter-0.18.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d7424194e68ef44e94290961f59319850d7ce11a329a3957f91709c15ded6618", size = 335631, upload-time = "2026-10-23T13:49:16.551Z" },
+ { url = "https://files.pythonhosted.org/packages/fd/9e/d2dc5e8179e248df7ef1c7c8822554f4c7f694a33be30790bb523f1e657a/jiter-0.18.0-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:04a484fce032a8b2c21dec0410a805d7b16573eb34297156a3b4d242c507d2b4", size = 322596, upload-time = "2026-10-23T13:49:17.875Z" },
+ { url = "https://files.pythonhosted.org/packages/22/ca/28bfd20743be0b2b37c1ddfe069a637d5180e535f1c8faad555cf7ac0b98/jiter-0.18.0-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:860ac97858116bda0ac02ef5f50c541fc1a84ad7b9368cac68d4de5697a9012d", size = 333858, upload-time = "2026-10-23T13:49:19.343Z" },
+ { url = "https://files.pythonhosted.org/packages/69/89/e42f7dba54dcf7787aa4be3e22cdcb1f14d9635b6527949652ab490d6f8e/jiter-0.18.0-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:39ef656cf371971486ec545ca0ae2da8d037d5479bc906121e3e46de86ee73c4", size = 348656, upload-time = "2026-10-23T13:49:20.796Z" },
+ { url = "https://files.pythonhosted.org/packages/74/6a/b13407f609ddaf9a1f0cdf1336326dc5c8c7fc56943e8450a04a542f5edf/jiter-0.18.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b3c741e6b778c951a6861964ee475118812a33208426c54fb92bf4e318bda834", size = 336286, upload-time = "2026-10-23T13:49:22.152Z" },
+ { url = "https://files.pythonhosted.org/packages/b2/7e/b560f97495a485a569e7fa338a13587328854f6a40cd2e93602c327ca4a6/jiter-0.18.0-cp312-cp312-manylinux_2_31_riscv64.whl", hash = "sha256:1277ac083a58d2f49a24ff9a28fd9876a6443a1992d4467a1db80fb45e354b18", size = 314415, upload-time = "2026-10-23T13:49:23.645Z" },
+ { url = "https://files.pythonhosted.org/packages/8b/97/457b6ec16f1f3f25ec760f23728f43a2b20ddf934fcd8f02c81a2183597e/jiter-0.18.0-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:ccf224d2e706be81d464b59c2bc3f98ba65d12c092c1789e625127e64488944e", size = 332078, upload-time = "2026-10-23T13:49:24.917Z" },
+ { url = "https://files.pythonhosted.org/packages/0e/d9/6f616071650f7bb8fcbce674d4dde7e59cfbd8a4d30f5c71c03630425d6e/jiter-0.18.0-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:5c7fc8e5357d1ad082bb177be71e398fcd3d458726439255ca5cb0d706060269", size = 480354, upload-time = "2026-10-23T13:49:26.221Z" },
+ { url = "https://files.pythonhosted.org/packages/42/72/52a3630c8213cdc8093cc86dc6ad50f2bc89ccfa97ef272205d38a24e16d/jiter-0.18.0-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:a6bba0404b46157a651d1fe512cf2c59c8e42836a9284c35cdff35310758ba4f", size = 515322, upload-time = "2026-10-23T13:49:27.652Z" },
+ { url = "https://files.pythonhosted.org/packages/31/54/987cfee52bdf8a286e9c1c58192a9bb64f8773a6be36e4ec46959f67fb7e/jiter-0.18.0-cp312-cp312-win32.whl", hash = "sha256:07ae058bc052ead609b49bbae78c01bf4dee8f5f9d21705cbae9bfe59b33efc9", size = 185341, upload-time = "2026-10-23T13:49:29.147Z" },
+ { url = "https://files.pythonhosted.org/packages/c5/c9/b1279eecf68e5f62c918af3f7f856a071ae7db0c90b8fd2235b1b6020c8c/jiter-0.18.0-cp312-cp312-win_amd64.whl", hash = "sha256:79d1fe529bd7065c6f3f50279a08c2ab82eaa0631a6f5dfafa9c65105eeaaafa", size = 225889, upload-time = "2026-10-23T13:49:30.306Z" },
+ { url = "https://files.pythonhosted.org/packages/e0/14/715f84be58a7fc97779aa40c37164acfa25ccb2cee89bfb69358e7071ff3/jiter-0.18.0-cp312-cp312-win_arm64.whl", hash = "sha256:1f8b3b3d8761dee3cddcb5d3e99eaccc0155bbefc345affcdedcc758a4933a1f", size = 181852, upload-time = "2026-10-23T13:49:31.811Z" },
+ { url = "https://files.pythonhosted.org/packages/50/94/aa275cdb099fd84e402977f8fc8628e2cee2f7c8eafe1d1d5c5e722f5ee5/jiter-0.18.0-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:1517648b5f6268513dea206241a99d9991d6ffcbdbc406848e77a7f02ed3ccf1", size = 289648, upload-time = "2026-10-23T13:49:33.059Z" },
+ { url = "https://files.pythonhosted.org/packages/8d/30/3eaf67279c6183393d3608b6713c93668ae82ea59f0589ea59d8176d8741/jiter-0.18.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:7161217e2190b9b2c8c79b81699be29d67010f6f77e09a53a3b62261792d5489", size = 315919, upload-time = "2026-10-23T13:49:34.457Z" },
+ { url = "https://files.pythonhosted.org/packages/f8/2b/d18adcfec3516b97b24c0d5cd1b0ced22cada8ea9806f21bece75af49ffe/jiter-0.18.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:9623fc90f1a4754452a525383ce70476476c16556098944709b8cdbd9ad905f0", size = 335231, upload-time = "2026-10-23T13:49:35.776Z" },
+ { url = "https://files.pythonhosted.org/packages/41/e8/42cff1077883ea5311621dc9384a1ede4799bc3c01411798ac75f7a71f15/jiter-0.18.0-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:f9083a7c2a4ee6358bc0401c46b4d5090f208f6fadfb6275c7b5fe3217e13506", size = 321590, upload-time = "2026-10-23T13:49:36.997Z" },
+ { url = "https://files.pythonhosted.org/packages/1d/4d/2fbedfce563223d4783a872cead5f5bb74d2d1e418f963410ca28e4b7394/jiter-0.18.0-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:4632f5172800da4cd42fd53f4553c772acd08f1c33dd7ac135e29d735080fa0d", size = 332960, upload-time = "2026-10-23T13:49:38.615Z" },
+ { url = "https://files.pythonhosted.org/packages/04/a0/b082b2d8bd3bef9a888cc0a0f060a24644f24b5195f2e8227a40507e6b71/jiter-0.18.0-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:c00b1f8fc1dd06c610305be36778b38148ed1e9a532bdd81189c3c0d9905c888", size = 348149, upload-time = "2026-10-23T13:49:39.826Z" },
+ { url = "https://files.pythonhosted.org/packages/64/11/babc8d3c004bb2f11b7e3adfe27a5bc7c1e13cdfc6360d424c57355c55ff/jiter-0.18.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6e3350b7431f7b8315b925d9ca0f29a44e8fb6ed45c1fe552392cb6297966bb9", size = 335978, upload-time = "2026-10-23T13:49:41.165Z" },
+ { url = "https://files.pythonhosted.org/packages/3b/21/c50bf83c39d60f0df896ebcb025b316b670a703397d08bea2c69b9615101/jiter-0.18.0-cp313-cp313-manylinux_2_31_riscv64.whl", hash = "sha256:3b49071fb7917cdbc6d80c81a491c6ad146c1a8fd6cb3076cd3c1bfeb6e266f6", size = 313767, upload-time = "2026-10-23T13:49:42.538Z" },
+ { url = "https://files.pythonhosted.org/packages/af/19/3f66480d5bfd3f49571a073eefac4d890dd590a8eb3c78b15e0293909cc6/jiter-0.18.0-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:04e210f5ddcccdbde484821040216a112381e6484abc549c20c38e9698ab07ca", size = 331070, upload-time = "2026-10-23T13:49:43.782Z" },
+ { url = "https://files.pythonhosted.org/packages/5a/3d/b5662c84b14475c8b018ed1ca2ea44069194b7d97a03bac81ae6b46f6b9f/jiter-0.18.0-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:5b339f6ae14fe7be92f391cc65cc5c80ff76e8da76d63b18fc14664f09b7cece", size = 479939, upload-time = "2026-10-23T13:49:45.033Z" },
+ { url = "https://files.pythonhosted.org/packages/80/b8/081c0414379ee2564aa7808f78e963538a2c4aed2f8d31775e2423e1cdbf/jiter-0.18.0-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:5cb43336244e063f9cc11e44730e4b92dea70c6eb9b649d268c5ebebc4bc7685", size = 514734, upload-time = "2026-10-23T13:49:46.236Z" },
+ { url = "https://files.pythonhosted.org/packages/0f/1c/6f7bf98786851ae424a1d88562586302536cc137848fd12d2add3960fab3/jiter-0.18.0-cp313-cp313-win32.whl", hash = "sha256:9656d0e9001f69c4af6523874ff445ab4e5db7b835f59733cc5ff51e73a9aa57", size = 184699, upload-time = "2026-10-23T13:49:47.398Z" },
+ { url = "https://files.pythonhosted.org/packages/38/53/5803216c024a241a0bf41ed2668713d7228f92c5593e40d5e873e3b20e0b/jiter-0.18.0-cp313-cp313-win_amd64.whl", hash = "sha256:8f26198220165eb9627847401fff4d0ca8bebf3ef840a88c6312918d2291c33a", size = 222493, upload-time = "2026-10-23T13:49:48.533Z" },
+ { url = "https://files.pythonhosted.org/packages/fe/8e/484919ccb041c9a1e84059be02bd37ff086b8b084e21630e0958d3ae41a3/jiter-0.18.0-cp313-cp313-win_arm64.whl", hash = "sha256:bef1fe687dc6af17bef9f644a95d465f15f0efa20b743c858e0b6a14e2c0c73e", size = 181250, upload-time = "2026-10-23T13:49:49.777Z" },
+ { url = "https://files.pythonhosted.org/packages/74/0e/45a502771d73d4a939132d8bf85d7b049c7ca06a07f84b414b525c3dc084/jiter-0.18.0-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:248e939f67a9f8030e2624260a9f417decfe275af37aa96728d256468a9c4086", size = 291757, upload-time = "2026-10-23T13:49:50.95Z" },
+ { url = "https://files.pythonhosted.org/packages/21/f6/d9cfa2bf2a969fb8e002fb8d8a6cd98d49a6248cb7e4ffe2247766af13fb/jiter-0.18.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:0390fa550fcafbf69fb97ccb287bd71192f90410a1c7dd600ca4000aa9aabcf2", size = 318585, upload-time = "2026-10-23T13:49:52.407Z" },
+ { url = "https://files.pythonhosted.org/packages/46/38/ea1dae56f123e3a864188cbbc577314293c0dcc019a880fa9c0a8097934a/jiter-0.18.0-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d8013186f2b9a8c27ededa601050392527aa9d27ffd35d49aae424fbd2062f38", size = 338099, upload-time = "2026-10-23T13:49:53.658Z" },
+ { url = "https://files.pythonhosted.org/packages/1f/d9/fcc5c53a32f98d52f4fd46fda62b69f5c7c2c975a582c0e18501250a4f78/jiter-0.18.0-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:bd4316df8e2074fcf5173f6001f1fc9596e7c1e8c4bf499b02f9ebe92babdfb1", size = 324016, upload-time = "2026-10-23T13:49:54.999Z" },
+ { url = "https://files.pythonhosted.org/packages/d4/63/c24cd08907f08e6a3ba3173616ad268a3d32dd81c63ba34b991d08577d28/jiter-0.18.0-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:a9e474da7a9f65d3b460cca93cc8a0f4ec0220d1fa41f1f7a3709195ead60056", size = 335904, upload-time = "2026-10-23T13:49:56.214Z" },
+ { url = "https://files.pythonhosted.org/packages/0b/78/19ca1c8fe87bd3c8540b91504ff2dd52c9c538233044c4cf787fc1fab39b/jiter-0.18.0-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:d55acd326db8ecfc94f21951abd20902c7939d35925444e48d94527e287bead7", size = 350523, upload-time = "2026-10-23T13:49:57.552Z" },
+ { url = "https://files.pythonhosted.org/packages/c3/27/84be9cc1c2b781d2da7c694fd7608311af3aaab91f20eb00d4999285b351/jiter-0.18.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:a01642d403b8925f2b1e1bb51b4ba49ece8a2bdc9b9560fc8ed0b1f2b35b567a", size = 338324, upload-time = "2026-10-23T13:49:58.842Z" },
+ { url = "https://files.pythonhosted.org/packages/9a/ac/7b3bfb49b19e42ebc2ae56ec307c372602dd1e17892f7e051c9bf97cd7e6/jiter-0.18.0-cp314-cp314-manylinux_2_31_riscv64.whl", hash = "sha256:89ba6b674d4bd7290f9943bbeba0e1bf35955bbb1e07e41ba94691648cf133d5", size = 316484, upload-time = "2026-10-23T13:50:00.257Z" },
+ { url = "https://files.pythonhosted.org/packages/f9/6a/e37f50885aa4daa1dfe413784692ead6b48a1d9e857cd394a61bf345189c/jiter-0.18.0-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:feadebdfee32c61e91066433f4aa74c891752e26e43032c1feef08dda6d9b6ed", size = 334225, upload-time = "2026-10-23T13:50:01.542Z" },
+ { url = "https://files.pythonhosted.org/packages/8b/f8/1026bc92f0fd443a1137993d1448a7d7c4b7a34bec2722a1533302ebc4b4/jiter-0.18.0-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:dd7e57efd54a3580620f635c48a3226f910e23649b7eb83ffbc6f0f3386293b8", size = 482157, upload-time = "2026-10-23T13:50:02.849Z" },
+ { url = "https://files.pythonhosted.org/packages/1b/2d/61f3c35736873c34eeee3d0008067febd88ded8e8cf6f9a0ab090348a787/jiter-0.18.0-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:ea69e23481497c2143775a98d273ccc43de5c92a6387df18c903d2d37bc2b181", size = 516956, upload-time = "2026-10-23T13:50:04.19Z" },
+ { url = "https://files.pythonhosted.org/packages/6b/bf/9d14be58e76324f4927c7f8e5dbe2f9fd04faaec884a6465173f8142eac1/jiter-0.18.0-cp314-cp314-pyemscripten_2026_0_wasm32.whl", hash = "sha256:d9b61af76a3cd90ad9656a331737d97dab8c05facb2d04cb41fb16c9adadc966", size = 112087, upload-time = "2026-10-23T13:50:05.423Z" },
+ { url = "https://files.pythonhosted.org/packages/c6/7d/cff751c560d514da283bae595fe154714f285ec5ac15e2b16e9e0c0c8948/jiter-0.18.0-cp314-cp314-win32.whl", hash = "sha256:fe42726d7fe171cd8fc1966d4457a6aae03bd408d519d2cc5e7726805460b51e", size = 186562, upload-time = "2026-10-23T13:50:06.81Z" },
+ { url = "https://files.pythonhosted.org/packages/04/70/4e7f51e517be4146400fd1ce642d535380a38c7db5ab475d38bbcd16a82d/jiter-0.18.0-cp314-cp314-win_amd64.whl", hash = "sha256:f1e738b851019d6bb6ff4a42c6319bdede967dec958ef3ec6feb7ab9d12408f7", size = 225448, upload-time = "2026-10-23T13:50:08.302Z" },
+ { url = "https://files.pythonhosted.org/packages/78/43/02bfb85f63e04c87c406731197e41f2e6b415035e41497428e0422fb326e/jiter-0.18.0-cp314-cp314-win_arm64.whl", hash = "sha256:80a961b1c5c7786bc03b332deb7f7ebe818b7baa6e26685e2bf480548ca128b4", size = 182907, upload-time = "2026-10-23T13:50:09.795Z" },
+ { url = "https://files.pythonhosted.org/packages/9c/66/5cbde35cbb14c8339af39c9bc61cbda08b212116f96603d23b7c9cc84a4d/jiter-0.18.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:b066f37dd9ec19fc7931d79dee38f56b6f849217bbe824a7dad4518ef96ee515", size = 318962, upload-time = "2026-10-23T13:50:10.91Z" },
+ { url = "https://files.pythonhosted.org/packages/eb/d1/dccc47ed6070d3b25622823048a80a49fe87ccd737e5d66b802ca20e4fde/jiter-0.18.0-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ccdc09887b04f50f1761eedcfd19da882d9d834096bc1215049af637023f7db7", size = 336718, upload-time = "2026-10-23T13:50:12.149Z" },
+ { url = "https://files.pythonhosted.org/packages/de/a5/8d4ec06d7a0f2bccbde8508ed847ccd323a9dd1fbab5900cda3fc5bd71f8/jiter-0.18.0-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:6133abcd0f332964fbb8145adb1ce775cd0312c9eaf6e4bf26b7a5c9b6f7cca7", size = 322945, upload-time = "2026-10-23T13:50:13.591Z" },
+ { url = "https://files.pythonhosted.org/packages/7f/50/49d06214b30c685d64ffdd40fdb50a98b6ccff4b012fc9ed491d44de9ef1/jiter-0.18.0-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:ca381b4a466023d1fdd04c889c759b46f7d9654f622b28bb01e65abf31d07bba", size = 335325, upload-time = "2026-10-23T13:50:14.807Z" },
+ { url = "https://files.pythonhosted.org/packages/f4/9a/4ecb866a7a01a4e76d9ffbde3fac2cd66ad978c8c797953d44f91fbf2040/jiter-0.18.0-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:9b961fedf589ffa182fe302fc4371acf4606d3ed4a6a48a151fbfd724d811f5a", size = 350578, upload-time = "2026-10-23T13:50:16.125Z" },
+ { url = "https://files.pythonhosted.org/packages/16/7e/c8b5ecb6af4c9454376263f167f3f8bb5dec41b10fac4f48ea4557b9f115/jiter-0.18.0-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:3b77eabfbae1ac47872be0076899e66340bbef39b862971c3d6c9a4b7c91fd10", size = 338791, upload-time = "2026-10-23T13:50:17.703Z" },
+ { url = "https://files.pythonhosted.org/packages/8a/04/45ba31ce79022706323fd2291f87d956fd51fdfcba2ba8924b3de62f0ce2/jiter-0.18.0-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:92a16933d0fa852133500837d33cd6a4f75e4414d77389c58269e12bafc2ee02", size = 316169, upload-time = "2026-10-23T13:50:18.915Z" },
+ { url = "https://files.pythonhosted.org/packages/62/c1/fd36126144f4c32d1b76939278e9d3b7b798075c0478b641d6066621bafd/jiter-0.18.0-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:2f7ba518893a4ccef5afb38e41bc3e126bf652354417ec4e75e5a5b000fb1ef6", size = 334754, upload-time = "2026-10-23T13:50:20.169Z" },
+ { url = "https://files.pythonhosted.org/packages/cc/e2/30a5ac1a3ee9e01bda75a4fcb55bbeddcf8875f8ce7e680b787c177f14b5/jiter-0.18.0-cp314-cp314t-musllinux_1_1_aarch64.whl", hash = "sha256:04d67a44b040a6662a35edc9869030f7aa566bf5baaf3549c99d847aa44213e2", size = 481094, upload-time = "2026-10-23T13:50:21.481Z" },
+ { url = "https://files.pythonhosted.org/packages/33/de/5e736a36eff6933da012dc440540f79e3ccfc06e27f557638280657df023/jiter-0.18.0-cp314-cp314t-musllinux_1_1_x86_64.whl", hash = "sha256:e4d4819398d5330636bc0b91ccc0048dba782076fb99257038257ba6f121c840", size = 515524, upload-time = "2026-10-23T13:50:22.872Z" },
+ { url = "https://files.pythonhosted.org/packages/0a/ea/1e8bc5b0c920a13e5b698106dbb2d2da5c5e3474668746246f649abb6d5f/jiter-0.18.0-cp314-cp314t-win32.whl", hash = "sha256:c435e795a7ea4b372166a058a5b49a25caeb9c94e469a1414868b14c83ee5c41", size = 185058, upload-time = "2026-10-23T13:50:24.098Z" },
+ { url = "https://files.pythonhosted.org/packages/1e/0f/a742b397699c3af52dd95443332164884fe6204e5faa5321b7c073beab0f/jiter-0.18.0-cp314-cp314t-win_amd64.whl", hash = "sha256:5a3d5397da7ae46c7a9601ef02d2c9ec47a6c3abe15e1ea940eaf93e675ee20e", size = 225598, upload-time = "2026-10-23T13:50:25.44Z" },
+ { url = "https://files.pythonhosted.org/packages/b3/b7/08ae26347dca48d5cadca33be2f2f5b6b1ae790b322109083d6f95959feb/jiter-0.18.0-cp314-cp314t-win_arm64.whl", hash = "sha256:4b81b474e4a8ec745ab20a6762275a360e1147cb70cf08872ec14e1aa5debc37", size = 183052, upload-time = "2026-10-23T13:50:26.675Z" },
+ { url = "https://files.pythonhosted.org/packages/c2/d6/0d2a8a9747ad918141827fabdc05abc3bf73986f7f36647fb8c19708e21e/jiter-0.18.0-cp315-cp315-macosx_10_12_x86_64.whl", hash = "sha256:30f8ae18425e0247ffff4e4a5753ec1952e1b81ed4e7949b84e5ecfaf8315833", size = 291908, upload-time = "2026-10-23T13:50:27.94Z" },
+ { url = "https://files.pythonhosted.org/packages/54/b4/19c582727e22681c6069db037c3b3e354c6fbdce7fbc5290a7bc7bc5884f/jiter-0.18.0-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:93150a3bb0317d8f5a94d4c3ea68db1cb434b94ac819e08c443cea97b7645f2f", size = 316544, upload-time = "2026-10-23T13:50:29.167Z" },
+ { url = "https://files.pythonhosted.org/packages/c3/62/5d34e93dc5d1e707788a378335efc876cdc731ceb2111b0a9d7c6f9fdada/jiter-0.18.0-cp315-cp315-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:c9c8a61d6227cdcb0a67c678f30a020837c9f3dd7e0b3f916781defa157e4eb9", size = 338101, upload-time = "2026-10-23T13:50:30.457Z" },
+ { url = "https://files.pythonhosted.org/packages/75/e2/0b16a6ca5479cd9efa3c59497cd42f1979a539b6c664a5b9c87e3632f176/jiter-0.18.0-cp315-cp315-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:285cc15ff9ffcd4ce7f0b9ce02fcbc65e22fcf7dfbda1a3d71ccac8d7b73f8a1", size = 324213, upload-time = "2026-10-23T13:50:31.695Z" },
+ { url = "https://files.pythonhosted.org/packages/85/9d/620a97457a0210092bf9faa1eb30f5da094fab2de07a9478af7c254e22fd/jiter-0.18.0-cp315-cp315-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:c8f69ef2e28f8c1759bc1522385ab3e4ade0b1056053cecf67449a947c4525a8", size = 335777, upload-time = "2026-10-23T13:50:32.984Z" },
+ { url = "https://files.pythonhosted.org/packages/76/08/a3514df093824f10a61dc1d0bbc22285ed779ba42f15d727499a8c877e16/jiter-0.18.0-cp315-cp315-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:eec2da60423287bd60377b0fad1723560dcc51cfb2b99615be8431ad425c4438", size = 350490, upload-time = "2026-10-23T13:50:34.421Z" },
+ { url = "https://files.pythonhosted.org/packages/cd/60/8f8b51bae62259b429e83d0adff69d93e39e4fadbc4bd1856dc2a0950639/jiter-0.18.0-cp315-cp315-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:5db2cdae6a2f01e8f52ab2154886dcf5bb1844b4f31245440bf623ec91b65b08", size = 338591, upload-time = "2026-10-23T13:50:35.759Z" },
+ { url = "https://files.pythonhosted.org/packages/2e/ed/5307f0eb051d987510fdd1020c904927c0b364a4937d372817bdefaced31/jiter-0.18.0-cp315-cp315-manylinux_2_31_riscv64.whl", hash = "sha256:029da1f29852beac2f9001f20209b73b29b4d7bdc748c7f8028895769e2cc0d8", size = 316623, upload-time = "2026-10-23T13:50:37.316Z" },
+ { url = "https://files.pythonhosted.org/packages/f9/0e/4bdc945ffbf77c60f07c726fbeb45508018322df9d9942d262256397062e/jiter-0.18.0-cp315-cp315-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:67c6662b1b7e5728a507db06ad1b8a7ff8ade04c2a74f092d467209ef744d3a4", size = 334720, upload-time = "2026-10-23T13:50:38.507Z" },
+ { url = "https://files.pythonhosted.org/packages/4b/33/fb3e8f9354e7edab05f3752383eac58ce6e785f2f1626b697dd5dd0a86e4/jiter-0.18.0-cp315-cp315-musllinux_1_1_aarch64.whl", hash = "sha256:4db12daef4a231df528a16f70d5ff7f5e3be21f70e8ad904e4c61442366e8a10", size = 482130, upload-time = "2026-10-23T13:50:40.023Z" },
+ { url = "https://files.pythonhosted.org/packages/2e/3d/3aef2be95155bbacadd8691208b6f0f7371cc0cefe80241a1245e38e308d/jiter-0.18.0-cp315-cp315-musllinux_1_1_x86_64.whl", hash = "sha256:4654ea93f525ea96adf289afcf1ead32d773b8325ec326862b4f81f5f4570835", size = 516986, upload-time = "2026-10-23T13:50:41.279Z" },
+ { url = "https://files.pythonhosted.org/packages/3c/f6/2aa54fd5da3d0a93de2655e2525426263168454259ba3f2fb70d1b36fbc9/jiter-0.18.0-cp315-cp315-win32.whl", hash = "sha256:f035d01b450ac4e141502f1ce142462cee638198ff5a0237c80e6683798b3b87", size = 186645, upload-time = "2026-10-23T13:50:42.526Z" },
+ { url = "https://files.pythonhosted.org/packages/b5/77/5b54ca8c292b83991cafbac6b022f515e46f1ae77dd5f4a97cc33644b235/jiter-0.18.0-cp315-cp315-win_amd64.whl", hash = "sha256:4a18ef4fe95685b000d95eca797cc683e0c178a4b364f2e39f6c79ab107a26e6", size = 225087, upload-time = "2026-10-23T13:50:43.779Z" },
+ { url = "https://files.pythonhosted.org/packages/9f/f3/53b7f39b83c757380ab57d9bc3f934431d6b6751f007e8122f7f63c10c2c/jiter-0.18.0-cp315-cp315-win_arm64.whl", hash = "sha256:c73922e4ff4b1ad2929cd795c98223c6688a43c5fd42e9deb8955e4d43b00abb", size = 183120, upload-time = "2026-10-23T13:50:44.985Z" },
+ { url = "https://files.pythonhosted.org/packages/77/f8/3a3ef55c528722f3b4be0e7b9686a37ddbe86ed96510bc1c2a63dab7f14b/jiter-0.18.0-cp315-cp315t-macosx_11_0_arm64.whl", hash = "sha256:0ccf55f6fcdcee82fe40ae617e9d64b8e5f433fa6cb5bf7d2969e584e6df0e5d", size = 317996, upload-time = "2026-10-23T13:50:46.266Z" },
+ { url = "https://files.pythonhosted.org/packages/e1/15/b06c1c17bed30b5c5dabb40f80a56a3b71b89c16ae86552307f7ccedc93a/jiter-0.18.0-cp315-cp315t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:163a55e77f8e92d739b1f4ef212f1d445ddc58ecdf0da1feca44ef424b5331f8", size = 336638, upload-time = "2026-10-23T13:50:47.444Z" },
+ { url = "https://files.pythonhosted.org/packages/87/79/b7bcd3e8c850326a323d18a5607334ea40659e22a4fc321e315d1d230007/jiter-0.18.0-cp315-cp315t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:9de6c9133be12a51ea2d8c270f39a04ed45ee369802bb6270649b952e6cec256", size = 323116, upload-time = "2026-10-23T13:50:48.715Z" },
+ { url = "https://files.pythonhosted.org/packages/5e/99/4c53c9d46462cd0691c3c188f89612e63a424d19f5befd1b0631f8f90638/jiter-0.18.0-cp315-cp315t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:2ea4f2ed18eba7454182d4ff727444788ae51ad11bf5a25ad892f5f0ad3e754b", size = 335162, upload-time = "2026-10-23T13:50:49.987Z" },
+ { url = "https://files.pythonhosted.org/packages/6f/ab/ef873065a3a1c442a4e62558b77bfa338066317dbafdfdc991121201f5ad/jiter-0.18.0-cp315-cp315t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:626d5c9fb8b57babc6ce9d03224846ecb094e1d22ff5bff6080398e7f8aee162", size = 350560, upload-time = "2026-10-23T13:50:51.478Z" },
+ { url = "https://files.pythonhosted.org/packages/19/7e/48e78558d7cb3d289211da0397b7ed31cfe3efc98dd85f2324abd574c07c/jiter-0.18.0-cp315-cp315t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b3c3318cc6ef857b6554b43479c30e8249fc143189d500d4137cde9c58412e6d", size = 337848, upload-time = "2026-10-23T13:50:52.961Z" },
+ { url = "https://files.pythonhosted.org/packages/2c/35/b0a093e72def7caec970dd8536c3d42af3add3aedfb3c06ac0588effde26/jiter-0.18.0-cp315-cp315t-manylinux_2_31_riscv64.whl", hash = "sha256:9a70f25f6de76a01e309e109c9bcf2143c5c126b3488dd17a25c7aa404b28f16", size = 315870, upload-time = "2026-10-23T13:50:54.152Z" },
+ { url = "https://files.pythonhosted.org/packages/48/a4/fd7ca4d1ce8b876be7a260f5e31615854aed5b041553a63e85c4a265cb63/jiter-0.18.0-cp315-cp315t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:22d8dd757e603224e46786d63cb7d7bfbddc8f579a02e7b082840468d18c06f3", size = 335253, upload-time = "2026-10-23T13:50:55.427Z" },
+ { url = "https://files.pythonhosted.org/packages/f5/71/ccd7154afecd4687b22a8195d5dc6460f89f6e17537ec78edb58a2faac34/jiter-0.18.0-cp315-cp315t-musllinux_1_1_aarch64.whl", hash = "sha256:552a8714f26ddcb43115c82da6d045b3b9f2fa5997d8b21b2f8ec3721503bebb", size = 480775, upload-time = "2026-10-23T13:50:56.91Z" },
+ { url = "https://files.pythonhosted.org/packages/c8/b9/bad5391d7fb734cd6ebc383c8603bc324518bf4ce865f5d813908ae42596/jiter-0.18.0-cp315-cp315t-musllinux_1_1_x86_64.whl", hash = "sha256:8060a206e290410d3bfc3bd91715f3ec90a499246f8335d48927e0b3b6a6ccc5", size = 515619, upload-time = "2026-10-23T13:50:58.231Z" },
+ { url = "https://files.pythonhosted.org/packages/c8/5c/9596452ad56340e6ed395c5fe27ab102bb2aa0c4b59de2e6a8b3dc3b03a7/jiter-0.18.0-cp315-cp315t-win32.whl", hash = "sha256:91d463858f11ee76ce8e39f391bbcbf1d4c3cc4703a1496fed3a5666dcd5e01d", size = 185204, upload-time = "2026-10-23T13:50:59.456Z" },
+ { url = "https://files.pythonhosted.org/packages/08/c8/62c798e2a1a6f827eac1d45232c93b1b0e387a22d559c8483dc7302d5fd5/jiter-0.18.0-cp315-cp315t-win_amd64.whl", hash = "sha256:6ee49daab0b826279c152ad8d61171ea17f4197f91a5e14251d0d5d4adf51059", size = 224948, upload-time = "2026-10-23T13:51:00.624Z" },
+ { url = "https://files.pythonhosted.org/packages/64/42/cdfa494914b6d512431e795d8d6226b84b77b733bb8b5eccafd5a1a86dad/jiter-0.18.0-cp315-cp315t-win_arm64.whl", hash = "sha256:bec676a0dc24d4dabd4bdfb3d1f1bf80d4d3dd892fc5c5b3f8f953e2459dbfce", size = 183182, upload-time = "2026-10-23T13:51:01.797Z" },
+ { url = "https://files.pythonhosted.org/packages/a0/c2/49ee8f4743c27e61c52b4746ba636b43bedda97131a14043dc6f5ce5bb9d/jiter-0.18.0-graalpy312-graalpy250_312_native-macosx_10_12_x86_64.whl", hash = "sha256:118c1fd995f349f1cad0557f31d6860f336b4aeef7f002dedbc068027f68e2c3", size = 287302, upload-time = "2026-10-23T13:51:08.073Z" },
+ { url = "https://files.pythonhosted.org/packages/60/72/394036294ac3226216f73bfa4b14df920eb5baf7fb80fa7e0a0d7ef442a6/jiter-0.18.0-graalpy312-graalpy250_312_native-macosx_11_0_arm64.whl", hash = "sha256:44d0d719cd7845e66b01a0cf346ec9882073e710a05e89a5b6d87be47a9dc69c", size = 277797, upload-time = "2026-10-23T13:51:09.324Z" },
+ { url = "https://files.pythonhosted.org/packages/ce/80/f0dadedaa9a109f31e8978c7db355593916968d5956f382188a3f8c0888c/jiter-0.18.0-graalpy312-graalpy250_312_native-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:4d1d2dc4d930ebc225f488b6b3790acebb2e51b3a165a4a42cc1d05bb927f83e", size = 300192, upload-time = "2026-10-23T13:51:10.551Z" },
+ { url = "https://files.pythonhosted.org/packages/93/51/e57dbc6c264ec6557a677189755fe4525d83439237418e3ae59771ac1cde/jiter-0.18.0-graalpy312-graalpy250_312_native-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ebb0c346b6c5d9c033fe9e9b6ed6a1ff6dac0288fe681c3434dde6eb9c264fa1", size = 301141, upload-time = "2026-10-23T13:51:11.882Z" },
+]
+
[[package]]
name = "joblib"
version = "1.6.0"
@@ -1275,6 +1387,21 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/2c/b2/c2acb076590a98bee2816ed5f285e00df162a34238f9e276e175e14ebc35/langchain_ollama-1.1.0-py3-none-any.whl", hash = "sha256:43ac83a6eacb0f43855810739794dd55019e0d9b17bdcf3ecb3b1991ac3b59dd", size = 31413, upload-time = "2026-04-07T02:47:59.642Z" },
]
+[[package]]
+name = "langchain-openai"
+version = "1.7.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "certifi" },
+ { name = "langchain-core" },
+ { name = "openai" },
+ { name = "tiktoken" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/58/f5/a430230cb50b4b4ade021a5fe5df5a8c5adefa468435d460d2f77f2506ea/langchain_openai-1.7.3.tar.gz", hash = "sha256:c1d2d0fbd4f542ddcdf176c07abcf4d86c3b716513929250bbef04e3efc5e0b5", size = 3407726, upload-time = "2026-10-26T23:08:33.98Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/c4/52/5bcba40b1d7e46f352a727c57c231b820069bc83310f97933e10eccbd935/langchain_openai-1.7.3-py3-none-any.whl", hash = "sha256:0ab77cc4579b87c50823b7ccb5d8af48d6c6ae2084f156dcdc37151fcc0717e6", size = 146342, upload-time = "2026-10-26T23:08:32.577Z" },
+]
+
[[package]]
name = "langchain-protocol"
version = "0.0.20"
@@ -1887,6 +2014,7 @@ version = "0.1.0"
source = { editable = "." }
dependencies = [
{ name = "chromadb" },
+ { name = "fastapi" },
{ name = "langchain-chroma" },
{ name = "langchain-classic" },
{ name = "langchain-community" },
@@ -1894,6 +2022,7 @@ dependencies = [
{ name = "langchain-experimental" },
{ name = "langchain-huggingface" },
{ name = "langchain-ollama" },
+ { name = "langchain-openai" },
{ name = "langchain-text-splitters" },
{ name = "pydantic" },
{ name = "pypdf" },
@@ -1902,6 +2031,7 @@ dependencies = [
{ name = "torch", version = "2.15.0", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "sys_platform == 'darwin'" },
{ name = "torch", version = "2.15.0+cpu", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "sys_platform != 'darwin'" },
{ name = "typer" },
+ { name = "uvicorn" },
]
[package.dev-dependencies]
@@ -1914,6 +2044,7 @@ dev = [
[package.metadata]
requires-dist = [
{ name = "chromadb", specifier = ">=1.0" },
+ { name = "fastapi", specifier = ">=0.115" },
{ name = "langchain-chroma", specifier = ">=1.0,<2" },
{ name = "langchain-classic", specifier = ">=1.0,<2" },
{ name = "langchain-community", specifier = ">=0.4,<0.5" },
@@ -1921,6 +2052,7 @@ requires-dist = [
{ name = "langchain-experimental", specifier = ">=0.4,<0.5" },
{ name = "langchain-huggingface", specifier = ">=1.0,<2" },
{ name = "langchain-ollama", specifier = ">=1.0,<2" },
+ { name = "langchain-openai", specifier = ">=1.0,<2" },
{ name = "langchain-text-splitters", specifier = ">=1.1,<2" },
{ name = "pydantic", specifier = ">=2.7" },
{ name = "pypdf", specifier = ">=5.0" },
@@ -1928,6 +2060,7 @@ requires-dist = [
{ name = "sentence-transformers", specifier = ">=5.0" },
{ name = "torch", specifier = ">=2.4", index = "https://download.pytorch.org/whl/cpu" },
{ name = "typer", specifier = ">=0.12" },
+ { name = "uvicorn", specifier = ">=0.32" },
]
[package.metadata.requires-dev]
@@ -1937,6 +2070,23 @@ dev = [
{ name = "ruff", specifier = ">=0.6" },
]
+[[package]]
+name = "openai"
+version = "3.42.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "anyio" },
+ { name = "httpx2" },
+ { name = "jiter" },
+ { name = "pydantic" },
+ { name = "sniffio" },
+ { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/9f/7b/e01d5288d13e3bae3714ed39df402f99f88f422dcd978c5ce94848037200/openai-3.42.1.tar.gz", hash = "sha256:4222d919374648ff572753626e942f26eb1ece8a5e0e9a2708c9be4d560f070f", size = 2356422, upload-time = "2026-11-01T20:57:02.607Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/fd/11/37b847d8a057000193974eeea1bcc681355ae50d35865f2eb2b323de6153/openai-3.42.1-py3-none-any.whl", hash = "sha256:c1959518a8e26f81a3564357082cb684540be639a21fece35ac5619415a3eadc", size = 2397433, upload-time = "2026-11-01T20:57:00.622Z" },
+]
+
[[package]]
name = "opentelemetry-api"
version = "1.45.2"
@@ -3228,6 +3378,19 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/c1/69/c75534e336b06b3fd3f76de73d89736510800e60c77c58d4e4ce18389018/sqlalchemy-2.1.6-py3-none-any.whl", hash = "sha256:106878cf3795cd3d357e2e858609f9e44f20f19b2d8e48a3532bef3f90b03fbe", size = 2063055, upload-time = "2026-10-21T18:42:10.234Z" },
]
+[[package]]
+name = "starlette"
+version = "1.10.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "anyio" },
+ { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/48/bb/3d8757f21e9a53d9035c9eb039a777047139a16bfdbedfc7a58241c3d914/starlette-1.10.0.tar.gz", hash = "sha256:b8399098d4c1e3522734f7235dc79b1fc967f96cf139c81e0fa30479e0685f9b", size = 2734356, upload-time = "2026-10-24T15:04:12.342Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/88/2e/947cfe02def9371c07cd5bf5b6b61c829e9aecb9904db02a66cfafbc1eec/starlette-1.10.0-py3-none-any.whl", hash = "sha256:478c0ab3b4ced6e82719849c118fa406f0278a3499c1a898cd15cd31bdc38ce4", size = 80571, upload-time = "2026-10-24T15:04:10.371Z" },
+]
+
[[package]]
name = "sympy"
version = "1.14.0"
@@ -3258,6 +3421,60 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/43/3f/f88a53f60a472b46f4023f56d204dd7de33d34c5d2acbfa0d70a674e639e/threadpoolctl-3.7.0-py3-none-any.whl", hash = "sha256:cd8b60b5641b45c67bbf73c64c843235fc2d8a480c87389f52f5dbee893b86be", size = 26362, upload-time = "2026-09-15T15:46:19.168Z" },
]
+[[package]]
+name = "tiktoken"
+version = "0.14.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "regex" },
+ { name = "requests" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/66/62/167a842aa0429d45f5e797354fd4343a96f6043d67d0513c675c7b8d36e6/tiktoken-0.14.0.tar.gz", hash = "sha256:231dec90efcdccf1b565a1416107736f1e09b1a08fe736ef9d6363e626d03874", size = 38898, upload-time = "2026-08-17T19:49:49.514Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/8c/da/e273746b9d24a63c776bc60fba914351573ad9c575b52601eb5e60632564/tiktoken-0.14.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:8e947aefe98ef74cce94923f90e48c98fe34eb1ec0a6bfdfadfc5a96359bfc36", size = 1094408, upload-time = "2026-08-17T19:48:49.269Z" },
+ { url = "https://files.pythonhosted.org/packages/69/9f/fe6b1aca23331aa5271df5a4bd07bf68a7059254d47faee1b8272592a777/tiktoken-0.14.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:d6cebe67765569df3dafac8474e4eccf5c19d24140492567a5e58a11445732a4", size = 1038499, upload-time = "2026-08-17T19:48:50.666Z" },
+ { url = "https://files.pythonhosted.org/packages/0b/35/e9f47647c9e163bd1de30fe1a491669b7248cfc67b7404c35c009a701e1a/tiktoken-0.14.0-cp312-cp312-manylinux_2_28_aarch64.whl", hash = "sha256:7db45b98e94adf4173a5cd7422b150999a7ee11ff847783a14f6e1b80cc38cb6", size = 1186355, upload-time = "2026-08-17T19:48:51.93Z" },
+ { url = "https://files.pythonhosted.org/packages/51/11/9976ad86980a00cdef05e730a0127a2578a1bc6d11644d8d47246de2eb26/tiktoken-0.14.0-cp312-cp312-manylinux_2_28_x86_64.whl", hash = "sha256:7896eea257fe497a2b7134474d909156c6744ce8da35bce88011a960e008aa0d", size = 1204197, upload-time = "2026-08-17T19:48:53.18Z" },
+ { url = "https://files.pythonhosted.org/packages/d4/9c/7035b0bcfaa68d1ee4803fc5be5214ad865669b05bd20e7105ae8a18afc6/tiktoken-0.14.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:b950248272f1b303dc32986396e2dccfa10cf6d1e83ec8f0bba1776660305482", size = 1250635, upload-time = "2026-08-17T19:48:54.392Z" },
+ { url = "https://files.pythonhosted.org/packages/bc/1d/69cabf18bed7f4366da076735816abce0d4db3fae491ae338a6612128777/tiktoken-0.14.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:3de75343041a1c57333b1e707ac8a9769738241d7d6a55d39e12cf84548337c6", size = 1316085, upload-time = "2026-08-17T19:48:55.525Z" },
+ { url = "https://files.pythonhosted.org/packages/bd/bd/a2e884fb1402cba5be08836590320012b2d8ada0e2eef9911a64df4bcd2d/tiktoken-0.14.0-cp312-cp312-win_amd64.whl", hash = "sha256:087538c080e5ff421abd3a0785ed63c5111d06af98e6cd0d374dbe5969147ca3", size = 941208, upload-time = "2026-08-17T19:48:56.938Z" },
+ { url = "https://files.pythonhosted.org/packages/50/53/ee1453623bf65f019328721ccb6587846d2c5b7b82f34e73ca09101f072e/tiktoken-0.14.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:e9c5fe393aab56469f04e432ff851216d3def3436cf5f07e442a240164bf500f", size = 1094198, upload-time = "2026-08-17T19:48:57.955Z" },
+ { url = "https://files.pythonhosted.org/packages/ad/5f/6448cfe278c3664ba9ec5b5ac08344341f7dc3d42888476e215a14eda2be/tiktoken-0.14.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:cbe2cc3bba939bcdaf103e03df9d5039d33887080b315624be28ec69059e5f94", size = 1038820, upload-time = "2026-08-17T19:48:59.015Z" },
+ { url = "https://files.pythonhosted.org/packages/69/3b/d67eac1bcce9dee3abe23aff5e3ded3116bbebaf67b80a0811c06d3806fc/tiktoken-0.14.0-cp313-cp313-manylinux_2_28_aarch64.whl", hash = "sha256:2157f52e4b4d7ac5ecc7457b3716834706e7ef9a46f5144029bfeb7cf71f4e06", size = 1186175, upload-time = "2026-08-17T19:49:00.068Z" },
+ { url = "https://files.pythonhosted.org/packages/37/62/cae690d9783146b0f81f564ada0f8f611de68178c0c9c7e1e969f0516b48/tiktoken-0.14.0-cp313-cp313-manylinux_2_28_x86_64.whl", hash = "sha256:26e60f6a956ee171ab728b37b8439905d7ea1db435c30f9822f291e9861c861d", size = 1203884, upload-time = "2026-08-17T19:49:01.163Z" },
+ { url = "https://files.pythonhosted.org/packages/b9/1e/633e30237b94e383cf814145499079f3bb9cdd4aeafc1bc42e01b0f810a6/tiktoken-0.14.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:380873f330b741c4435574f37edb20813d04603ace2d53e0a63560e1fec83010", size = 1250980, upload-time = "2026-08-17T19:49:02.274Z" },
+ { url = "https://files.pythonhosted.org/packages/cb/56/4c12f07b812f84206f38d723eb1ebfdd34bad9309b5dbc0bee6bbcff4cbf/tiktoken-0.14.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:3fd7c14b1cb45b486c39fc9b3443bb341f3e2fc7e6f31247f3435a5836651632", size = 1315434, upload-time = "2026-08-17T19:49:03.434Z" },
+ { url = "https://files.pythonhosted.org/packages/c9/e0/c65603f0c44811def666d3fbf611bf2af3b5e1ef613e06c19411419830b3/tiktoken-0.14.0-cp313-cp313-win_amd64.whl", hash = "sha256:90a762670c7f968184723769a06ed51f5cf5ce5dcd1e30164f25c72d85c2d1f1", size = 940883, upload-time = "2026-08-17T19:49:04.583Z" },
+ { url = "https://files.pythonhosted.org/packages/59/b0/1cf129f4af8fc513931f931023def596b7c4bfc77026513cd9d851da9e88/tiktoken-0.14.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:e067f4cbcc5d036e8aff7fe7a6b530a8f4de2e4616ad9005a24a1879e24e6450", size = 1096273, upload-time = "2026-08-17T19:49:05.807Z" },
+ { url = "https://files.pythonhosted.org/packages/62/85/2ae74575e321148484147e10b53c3b1717c59ebaa9edb4fe18b1f5c055f8/tiktoken-0.14.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:f2af4a336ea56d6c14f27741a0e1d8294a35dd0b038bcf990d232ebb54eb994b", size = 1040269, upload-time = "2026-08-17T19:49:06.943Z" },
+ { url = "https://files.pythonhosted.org/packages/89/29/92a1120a12e4bcf2d5464350d1a91b68a433d63ce656bb7f806c27aec09c/tiktoken-0.14.0-cp314-cp314-manylinux_2_28_aarch64.whl", hash = "sha256:f702e0aeeb6506e57687e881c59e844ebe8f0a6a097ddafe20e3ab25f387be4e", size = 1186101, upload-time = "2026-08-17T19:49:08.102Z" },
+ { url = "https://files.pythonhosted.org/packages/5b/7d/144af98dc5ad68108451a82e2f5a17f80e2663f5115058b8dfd215c1ad02/tiktoken-0.14.0-cp314-cp314-manylinux_2_28_x86_64.whl", hash = "sha256:e3442bbb2f0c588cec876061e37ae67b455b9df9978b003c8fe30e45f2ef5b42", size = 1204457, upload-time = "2026-08-17T19:49:09.28Z" },
+ { url = "https://files.pythonhosted.org/packages/e6/1f/be7cb06ab2108f612f3e92e7b76cf391e192db0db37a984616f0cc32aafc/tiktoken-0.14.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:979c1524f753b662b0f3cd261b135afe6659cce33caaa7a5ea00dd1756b3055c", size = 1251716, upload-time = "2026-08-17T19:49:10.509Z" },
+ { url = "https://files.pythonhosted.org/packages/ab/6b/81f158d0f90adb826cd704069c2129a046cb784a2a09861009519fc41cf4/tiktoken-0.14.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:2cc19ac87b41c9493c9778ff5847f0c8bbcf5bd0ec6b87ce06c1c802adc8a771", size = 1315432, upload-time = "2026-08-17T19:49:11.844Z" },
+ { url = "https://files.pythonhosted.org/packages/fc/ec/f5fa35ec13f07279fdcaf3cc9c04bbb154ea591d23978651f2b672593e8a/tiktoken-0.14.0-cp314-cp314-win_amd64.whl", hash = "sha256:eceeff0c62419bc78d4b6e70a4762a4d25df3ae8f2d5946e3853ce93e7a57098", size = 988046, upload-time = "2026-08-17T19:49:13.282Z" },
+ { url = "https://files.pythonhosted.org/packages/68/c9/7756717408d3d0dfea3f046c9466144b28afde39ff69d5808f2475dcd7f5/tiktoken-0.14.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:6eb94895c45f26bb8f5546e5fd8a069efcf6e3f108ea9d5cbe3bf6f7f3983438", size = 1096261, upload-time = "2026-08-17T19:49:14.351Z" },
+ { url = "https://files.pythonhosted.org/packages/79/29/46ad8061f57bd9f8b2ea0aa82bf574e0f2aa040b0857a1582adba9957899/tiktoken-0.14.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:86951a971c53979ec857bd8c4a32dc227ab0fd33f6c12a3bd62d3fbf5f0bfcaa", size = 1040183, upload-time = "2026-08-17T19:49:15.707Z" },
+ { url = "https://files.pythonhosted.org/packages/5a/7c/3184d17b868456f17b60b1a75f5ec0405618a43aa753336df341d8f11781/tiktoken-0.14.0-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:e2eca764c53490f8930dbce329e0769f11108d87d908282a80c5c130e26e7037", size = 1186719, upload-time = "2026-08-17T19:49:16.84Z" },
+ { url = "https://files.pythonhosted.org/packages/0b/e8/46de4400d5bf859f640feee85bd7e32235f68ddf25db53c63be78e581e3a/tiktoken-0.14.0-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:26cc4b4840fa0e9f4b72ed489883e12f57e00d1021ca794720e3c29a12f0edef", size = 1204660, upload-time = "2026-08-17T19:49:17.987Z" },
+ { url = "https://files.pythonhosted.org/packages/29/ce/af8964c38bc8226dd8950305b7a255fa33345d5572f78af7275a313d28e0/tiktoken-0.14.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:2fc834fbe3f6a0736905c36ab709537e6840dbd63b982dc9e0216ae7d305ba1a", size = 1250932, upload-time = "2026-08-17T19:49:19.28Z" },
+ { url = "https://files.pythonhosted.org/packages/1d/4b/323631116fc986d9cc5bbeb2b8223c7c85e61a8bb94ea5ab4951023b149b/tiktoken-0.14.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:ca4db6ff5c5bf600f9b7761a0070ed44dfe5797a76bd432fb978bc480ef40c58", size = 1315190, upload-time = "2026-08-17T19:49:20.467Z" },
+ { url = "https://files.pythonhosted.org/packages/18/8b/ba48a73729c9270989b36f37ab2ed5525e52690d715097c9fa791aaa5d05/tiktoken-0.14.0-cp314-cp314t-win_amd64.whl", hash = "sha256:7aab286a020660a039097912a088236b985d18a3090d73f136c4413d29d37ca0", size = 987717, upload-time = "2026-08-17T19:49:21.704Z" },
+ { url = "https://files.pythonhosted.org/packages/1d/10/b73b7e319179e0f60b32475f783b044f9cece872c53b6662664e9084b0d0/tiktoken-0.14.0-cp315-cp315-macosx_10_15_x86_64.whl", hash = "sha256:14b47e3674f2624803a8acc8fb367b7e24fc53055f9df3296482fe9a3a34a232", size = 1096280, upload-time = "2026-08-17T19:49:22.779Z" },
+ { url = "https://files.pythonhosted.org/packages/c2/6b/09999a9bf1d559670d1680e8f8e419ac0e2c5f6aac82e9bfdf70f260b30a/tiktoken-0.14.0-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:19d643d701fdaa70e5b9c7f8f96abcaffe77ca5e482a3a1a7dde46feb4284695", size = 1040433, upload-time = "2026-08-17T19:49:23.998Z" },
+ { url = "https://files.pythonhosted.org/packages/cd/7b/8537be0836f3df99b2a636b44399bfa43cd757f2b8b4097dacb794cf24a7/tiktoken-0.14.0-cp315-cp315-manylinux_2_28_aarch64.whl", hash = "sha256:e4ddf863b59347deaa92302dcd90e5eb003cdc9be06ec2b692c38d1bdd9efd49", size = 1186989, upload-time = "2026-08-17T19:49:25.021Z" },
+ { url = "https://files.pythonhosted.org/packages/7c/9d/f9c56d7a943a4468abf9ef37661bb9b8e0cd3aa8aa87368c7146cc3f3222/tiktoken-0.14.0-cp315-cp315-manylinux_2_28_x86_64.whl", hash = "sha256:60c47ca69ddda0dea8256fffd12e1b86f4b59734a20e4a70c61f63cc5f021df4", size = 1204615, upload-time = "2026-08-17T19:49:26.37Z" },
+ { url = "https://files.pythonhosted.org/packages/4b/d2/98a38579db25c4a8a84e31dd95d9072ec5f21f7e70de591da0412e29b25b/tiktoken-0.14.0-cp315-cp315-musllinux_1_2_aarch64.whl", hash = "sha256:728303a072163130c5b477b1f20d6211895569c1d5302c24ffc93a3009160871", size = 1251828, upload-time = "2026-08-17T19:49:27.423Z" },
+ { url = "https://files.pythonhosted.org/packages/0c/83/467be424746c039c5493c0f4102feab16b9b48eb6f5c089b2a2438e3cde2/tiktoken-0.14.0-cp315-cp315-musllinux_1_2_x86_64.whl", hash = "sha256:3c5349c9f916283bba32bec8af69b763e4faa304dc004d0eaaea66a3cf004c1f", size = 1316260, upload-time = "2026-08-17T19:49:29.101Z" },
+ { url = "https://files.pythonhosted.org/packages/02/ee/ddf46ca78e371f5890e96b6e7d089a85b3536432be219851eb0481786ca8/tiktoken-0.14.0-cp315-cp315-win_amd64.whl", hash = "sha256:1b6e4adcfd285c44502aed51df98aaaca4f0fea028165dbf8a9e857b9f98d8ea", size = 988230, upload-time = "2026-08-17T19:49:30.246Z" },
+ { url = "https://files.pythonhosted.org/packages/2a/00/5162e90c851a28da18ed382d34898b79a8022548e5619a64e14c03ce7c3d/tiktoken-0.14.0-cp315-cp315t-macosx_10_15_x86_64.whl", hash = "sha256:11d8211b290855d2721334ff17dd9b3a17bfb26872be01f25d73612ef7ece890", size = 1096186, upload-time = "2026-08-17T19:49:31.656Z" },
+ { url = "https://files.pythonhosted.org/packages/65/97/a5a7bfccf25b1bb65e82bae8edff11ac3c9c041c374b7b4a823d60c38133/tiktoken-0.14.0-cp315-cp315t-macosx_11_0_arm64.whl", hash = "sha256:d0781223705199b289faa59601bb9c2441712d4c600dd13c43d8fd6a33d22cd5", size = 1039947, upload-time = "2026-08-17T19:49:32.848Z" },
+ { url = "https://files.pythonhosted.org/packages/fb/ba/ef427fc638f1439181c5e12dd26b70e881861f89c007aa7e5b36300f8342/tiktoken-0.14.0-cp315-cp315t-manylinux_2_28_aarch64.whl", hash = "sha256:2ea70afba6b9eddbf22c165142e5f0a2ad7aa36a452873c48b57bb2aeb8492ae", size = 1186997, upload-time = "2026-08-17T19:49:34.121Z" },
+ { url = "https://files.pythonhosted.org/packages/3e/88/2f3f85a968cdc514152129af0a060ebcccb067005a2f29b0d5ef3c838514/tiktoken-0.14.0-cp315-cp315t-manylinux_2_28_x86_64.whl", hash = "sha256:78571efc311c30b73f31eb949a921d6dac39a5d9dc42d1cfa8f8db157b3447b1", size = 1205211, upload-time = "2026-08-17T19:49:35.284Z" },
+ { url = "https://files.pythonhosted.org/packages/4e/f6/80760e98a08e6649d2d68afb6035af713121dfb615acce8c4f73810ec438/tiktoken-0.14.0-cp315-cp315t-musllinux_1_2_aarch64.whl", hash = "sha256:86f66c85e796f5d05d5c4a60ec1d40cbfebc47a32464053528c797163fa9ab89", size = 1251479, upload-time = "2026-08-17T19:49:36.419Z" },
+ { url = "https://files.pythonhosted.org/packages/c5/84/50966fb6918a0fb9b32721277e5342bf729a2d74350074d662fbedf9772e/tiktoken-0.14.0-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:149d97453c4c98c04b081d64a85e635921269b532710d6faf81e9e82b790e7d3", size = 1316673, upload-time = "2026-08-17T19:49:37.756Z" },
+ { url = "https://files.pythonhosted.org/packages/35/5e/9b01afd037bfa22a0033963fa091e0f75b6fb15cd85bffb42ff86e697323/tiktoken-0.14.0-cp315-cp315t-win_amd64.whl", hash = "sha256:561e7580f84a79859af1ef6f676968e9030fcc3fe195700b15235bca64f009c9", size = 987929, upload-time = "2026-08-17T19:49:38.947Z" },
+]
+
[[package]]
name = "tokenizers"
version = "0.23.3"