From a59ff897faa06c5aa5dd511be339f6e3333203fc Mon Sep 17 00:00:00 2001
From: Wadi
Date: Mon, 2 Nov 2026 19:10:15 +0100
Subject: [PATCH 1/3] feat: bundled model folders (models_dir) and ore serve
--llm-url
A bundled engine loads its models from models_dir/-- under the same model names, so the index
fingerprint and existing indexes stay valid. --llm-url points the engine at the llama-server the app starts.
---
src/open_rag_engine/cli.py | 13 +++++++++++--
src/open_rag_engine/config.py | 19 +++++++++++++++++--
src/open_rag_engine/factory.py | 5 +++--
tests/test_config.py | 14 ++++++++++++++
4 files changed, 45 insertions(+), 6 deletions(-)
diff --git a/src/open_rag_engine/cli.py b/src/open_rag_engine/cli.py
index 46f78a5..6cee8f8 100644
--- a/src/open_rag_engine/cli.py
+++ b/src/open_rag_engine/cli.py
@@ -55,8 +55,12 @@ def _startup() -> None:
TraceOpt = Annotated[bool, typer.Option("--trace", help="Show what every pipeline stage returned.")]
+def _models_on_disk(config: EngineConfig) -> list[str]:
+ return [config.model_path(config.embeddings.model), config.model_path(config.rerank.model)]
+
+
def build_engine(config: EngineConfig) -> Engine:
- go_offline_if_possible([config.embeddings.model, config.rerank.model])
+ go_offline_if_possible(_models_on_disk(config))
return Engine.from_config(config)
@@ -248,6 +252,9 @@ def serve(
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."""
@@ -259,7 +266,9 @@ def action():
cfg = _config(config)
if data_dir is not None:
cfg = EngineConfig.model_validate({**cfg.model_dump(), "data_dir": data_dir})
- go_offline_if_possible([cfg.embeddings.model, cfg.rerank.model])
+ 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
diff --git a/src/open_rag_engine/config.py b/src/open_rag_engine/config.py
index b01de7f..3215de4 100644
--- a/src/open_rag_engine/config.py
+++ b/src/open_rag_engine/config.py
@@ -73,6 +73,9 @@ class AnswerConfig(_Section):
class EngineConfig(_Section):
data_dir: Path = Path(".ore")
+ models_dir: Path | None = None
+ """Bundled model folders, named like the model with "/" as "--" (intfloat--multilingual-e5-small). A model found
+ there loads from it; the configured model name, and so the index fingerprint, stays the same."""
collection: str = Field("default", pattern=r"^[A-Za-z0-9][A-Za-z0-9_-]{1,61}[A-Za-z0-9]$")
chunking: ChunkingConfig = ChunkingConfig()
embeddings: EmbeddingConfig = EmbeddingConfig()
@@ -93,7 +96,15 @@ def index_fingerprint(self) -> str:
def fingerprint(self) -> str:
"""Identifies the whole configuration, for reproducible evaluation runs (driver D-07)."""
- return _digest(self.model_dump_json(exclude={"data_dir"}))
+ return _digest(self.model_dump_json(exclude={"data_dir", "models_dir"}))
+
+ def model_path(self, model: str) -> str:
+ """Where to load a Hugging Face model from: its bundled folder when there is one, else its name."""
+ if self.models_dir is not None:
+ folder = self.models_dir / model.replace("/", "--")
+ if folder.is_dir():
+ return str(folder)
+ return model
def _digest(text: str) -> str:
@@ -107,4 +118,8 @@ def load_config(path: Path | None) -> EngineConfig:
if not path.is_file():
raise FileNotFoundError(f"Configuration file not found: {path}")
with path.open("rb") as handle:
- return EngineConfig.model_validate(tomllib.load(handle))
+ data = tomllib.load(handle)
+ # A relative models_dir is relative to the configuration file, so a bundled engine works wherever it is installed.
+ if isinstance(data.get("models_dir"), str) and not Path(data["models_dir"]).is_absolute():
+ data["models_dir"] = str(path.resolve().parent / data["models_dir"])
+ return EngineConfig.model_validate(data)
diff --git a/src/open_rag_engine/factory.py b/src/open_rag_engine/factory.py
index 8f4e6cd..7e2f609 100644
--- a/src/open_rag_engine/factory.py
+++ b/src/open_rag_engine/factory.py
@@ -23,7 +23,7 @@ def embeddings(self) -> Embeddings:
_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),
@@ -32,7 +32,8 @@ def embeddings(self) -> Embeddings:
@cached_property
def cross_encoder(self) -> HuggingFaceCrossEncoder:
_quiet_transformers()
- return HuggingFaceCrossEncoder(model_name=self._config.rerank.model, model_kwargs={"device": "cpu"})
+ model = self._config.model_path(self._config.rerank.model)
+ return HuggingFaceCrossEncoder(model_name=model, model_kwargs={"device": "cpu"})
@cached_property
def llm(self) -> BaseChatModel:
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()
From 20c2789877714d2ce49790ee6558305ae0902176 Mon Sep 17 00:00:00 2001
From: Wadi
Date: Mon, 2 Nov 2026 20:03:40 +0100
Subject: [PATCH 2/3] feat: Windows installer with a bundled language model
installer/build.py stages a self-contained Open RAG and runs Inno Setup:
the published app, a uv-managed CPython 3.12 with the engine and its locked
dependencies (CPU torch), the embedding and reranker models from the Hugging
Face cache, the Qwen3 GGUF from Ollama (digest-checked) and llama.cpp's
llama-server (pinned b12052, sha256-checked). The setup installs per user,
keeps the library on uninstall and comes in parts below GitHub's 2 GiB limit.
The app starts the bundled llama-server on a free loopback port with its own
key and points the engine at it with --llm-url. ChildHost replaces EngineHost
and runs both processes, waiting on ORE_READY or a /health probe. Logs rotate
at 5 MB. installer/smoke_test.py checks a stage or an installed app end to end.
The window also opens the credits' GitHub and LinkedIn links, and only those
(ExternalLinks).
---
README.md | 12 +-
desktop/README.md | 5 +
desktop/src/OpenRag.App/MainWindow.xaml.cs | 93 ++++--
desktop/src/OpenRag.App/OpenRag.App.csproj | 3 +
desktop/src/OpenRag.Core/ChildHost.cs | 238 +++++++++++++
desktop/src/OpenRag.Core/Engine.cs | 208 +++---------
desktop/src/OpenRag.Core/ExternalLinks.cs | 17 +
.../tests/OpenRag.Core.Tests/EngineTests.cs | 59 +++-
.../OpenRag.Core.Tests/ExternalLinksTests.cs | 46 +++
installer/OpenRag.iss | 108 ++++++
installer/README.md | 74 +++++
installer/THIRD_PARTY_NOTICES.md | 28 ++
installer/build.py | 314 ++++++++++++++++++
installer/licenses/llama.cpp-LICENSE.txt | 21 ++
installer/smoke_test.py | 201 +++++++++++
15 files changed, 1232 insertions(+), 195 deletions(-)
create mode 100644 desktop/src/OpenRag.Core/ChildHost.cs
create mode 100644 desktop/src/OpenRag.Core/ExternalLinks.cs
create mode 100644 desktop/tests/OpenRag.Core.Tests/ExternalLinksTests.cs
create mode 100644 installer/OpenRag.iss
create mode 100644 installer/README.md
create mode 100644 installer/THIRD_PARTY_NOTICES.md
create mode 100644 installer/build.py
create mode 100644 installer/licenses/llama.cpp-LICENSE.txt
create mode 100644 installer/smoke_test.py
diff --git a/README.md b/README.md
index c077327..387c874 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,11 @@ We just finished a full course on retrieval-augmented generation and built a sma
## Try it
-You need Python 3.12+, [uv](https://docs.astral.sh/uv/) and [Ollama](https://ollama.com/).
+**On Windows, without installing anything else:** download Open RAG, the desktop app, from the
+[latest release](https://github.com/Carthavate/open-rag-engine/releases/latest). Put the `.exe` and its `.bin` parts in
+one folder and run the `.exe`. It brings its own models and works offline.
+
+**From source:** you need Python 3.12+, [uv](https://docs.astral.sh/uv/) and [Ollama](https://ollama.com/).
```bash
uv sync
@@ -88,5 +92,7 @@ We review each other's work through pull requests. See [CONTRIBUTING.md](CONTRIB
## Team
-- [Wadi](https://github.com/TWadi)
-- [Ghassen](https://github.com/GhassenJamoussi99)
+Open RAG is developed by:
+
+- Wadi Touil: [GitHub](https://github.com/TWadi) · [LinkedIn](https://www.linkedin.com/in/wadi-touil-117472319/)
+- Ghassen Jamoussi: [GitHub](https://github.com/GhassenJamoussi99) · [LinkedIn](https://www.linkedin.com/in/ghassen-jamoussi/)
diff --git a/desktop/README.md b/desktop/README.md
index bf6dbc0..61def12 100644
--- a/desktop/README.md
+++ b/desktop/README.md
@@ -53,3 +53,8 @@ npm test
- **Against a real engine in the browser:** start `ORE_API_TOKEN=<32+ chars> uv run ore serve --origin http://localhost:5176`, then open `http://localhost:5176/?api=http://127.0.0.1:&token=`.
- **Live reload inside the app (Debug builds only):** set `OPENRAG_DEV_URL=http://localhost:5176` before starting `OpenRag.exe`.
+
+## Installer
+
+`installer/build.py` builds `OpenRag-Setup.exe`, a self-contained setup that brings its own Python, models and
+llama.cpp server, so it needs no internet after installing. See [installer/README.md](../installer/README.md).
diff --git a/desktop/src/OpenRag.App/MainWindow.xaml.cs b/desktop/src/OpenRag.App/MainWindow.xaml.cs
index 952cf71..8aee7fa 100644
--- a/desktop/src/OpenRag.App/MainWindow.xaml.cs
+++ b/desktop/src/OpenRag.App/MainWindow.xaml.cs
@@ -21,6 +21,7 @@ public partial class MainWindow : Window
private const string DevUrlVariable = "OPENRAG_DEV_URL";
private static readonly TimeSpan EngineStartTimeout = TimeSpan.FromMinutes(3);
+ private static readonly TimeSpan HealthCheckTimeout = TimeSpan.FromSeconds(2);
private static readonly JsonSerializerOptions Json = new(JsonSerializerDefaults.Web);
private static readonly string WebRoot = Path.Combine(AppContext.BaseDirectory, "wwwroot");
@@ -32,7 +33,8 @@ public partial class MainWindow : Window
private readonly HttpClient _http = new(new SocketsHttpHandler { UseProxy = false }) { Timeout = Timeout.InfiniteTimeSpan };
private readonly SemaphoreSlim _lifecycle = new(1, 1);
private readonly Dictionary _asks = [];
- private EngineHost? _engine;
+ private ChildHost? _engine;
+ private ChildHost? _llm;
private EngineProxy? _proxy;
private object _engineState = new { type = "engine", state = "starting" };
private string _origin = $"https://{AppHost}";
@@ -115,44 +117,77 @@ private async Task LaunchEngineAsync()
}
try
{
- var engine = new EngineHost(command, command.ServeArguments(_paths.Data, Environment.ProcessId), _paths.EngineLog);
- engine.Started += process => _job?.Add(process);
- // Only the current engine may report a crash; a late exit from a replaced one is ignored.
- engine.Exited += code => Dispatcher.BeginInvoke(() =>
+ var environment = new Dictionary { ["ORE_API_TOKEN"] = _token };
+ string? llmUrl = null;
+ Task llmReady = Task.CompletedTask;
+ if (command.Llm is { } bundle)
{
- if (!ReferenceEquals(engine, _engine))
- {
- return;
- }
- _proxy = null;
- SetEngineState("failed", $"The engine stopped unexpectedly (exit code {code}). Details are in {_paths.EngineLog}.");
- });
- _engine = engine;
- var connection = await engine.StartAsync(new Dictionary { ["ORE_API_TOKEN"] = _token }, EngineStartTimeout);
+ // The language model loads while the engine warms up; both must be ready before the first question.
+ var port = LlmBundle.FreePort();
+ var key = Token.New();
+ llmUrl = $"http://127.0.0.1:{port}/v1";
+ environment["ORE_LLM_API_KEY"] = key;
+ _llm = Watch(new ChildHost(new EngineCommand(bundle.ServerPath, [], Path.GetDirectoryName(bundle.ServerPath)!, null),
+ bundle.Arguments(port), _paths.LlmLog, "language model"), _paths.LlmLog);
+ llmReady = _llm.StartAsync(new Dictionary { [LlmBundle.ApiKeyVariable] = key },
+ cancel => IsHealthyAsync(port, cancel), EngineStartTimeout);
+ }
+ _engine = Watch(new ChildHost(command, command.ServeArguments(_paths.Data, Environment.ProcessId, llmUrl), _paths.EngineLog),
+ _paths.EngineLog);
+ var connection = await _engine.StartAsync(environment, EngineStartTimeout);
+ await llmReady;
_proxy = new EngineProxy(_http, connection.BaseUrl, _token);
SetEngineState("ready");
}
catch (EngineStartException e)
{
- SetEngineState("failed", $"{e.Message}\n\nThe full log is in {_paths.EngineLog}.");
+ await StopEngineAsync();
+ SetEngineState("failed", $"{e.Message}\n\nThe logs are in {_paths.Logs}.");
}
catch (Exception e)
{
// Anything else (no permission to create the log folder, a blocked program) must not leave "starting" forever.
LogError(e);
+ await StopEngineAsync();
SetEngineState("failed", $"Open RAG couldn't start its engine: {e.Message}\n\nDetails are in {_paths.ErrorLog}.");
}
}
+ /// Puts a helper process in the job object and reports a crash, but only while it is still the current one:
+ /// a late exit from a replaced engine or model is ignored.
+ private ChildHost Watch(ChildHost host, string log)
+ {
+ host.Started += process => _job?.Add(process);
+ host.Exited += code => Dispatcher.BeginInvoke(() =>
+ {
+ if (!ReferenceEquals(host, _engine) && !ReferenceEquals(host, _llm))
+ {
+ return;
+ }
+ _proxy = null;
+ var what = ReferenceEquals(host, _llm) ? "language model" : "engine";
+ SetEngineState("failed", $"The {what} stopped unexpectedly (exit code {code}). Details are in {log}.");
+ });
+ return host;
+ }
+
+ /// llama-server answers /health with 200 once the model is loaded (503 while loading).
+ private async Task IsHealthyAsync(int port, CancellationToken cancel)
+ {
+ using var timeout = CancellationTokenSource.CreateLinkedTokenSource(cancel);
+ timeout.CancelAfter(HealthCheckTimeout);
+ using var response = await _http.GetAsync($"http://127.0.0.1:{port}/health", timeout.Token);
+ return response.IsSuccessStatusCode;
+ }
+
private async Task StopEngineAsync()
{
_proxy = null;
var engine = _engine;
+ var llm = _llm;
_engine = null;
- if (engine is not null)
- {
- await engine.DisposeAsync();
- }
+ _llm = null;
+ await Task.WhenAll(engine?.DisposeAsync().AsTask() ?? Task.CompletedTask, llm?.DisposeAsync().AsTask() ?? Task.CompletedTask);
}
private void LogError(Exception e)
@@ -262,6 +297,9 @@ private async void OnWebMessage(object? sender, CoreWebView2WebMessageReceivedEv
case "restartEngine":
await StartEngineAsync(restart: true);
break;
+ case "openLink":
+ OpenLink(message.GetProperty("url").GetString());
+ break;
case "api":
await ForwardAsync(message);
break;
@@ -420,6 +458,23 @@ private async Task OpenSourceAsync(string? path, bool reveal)
}
}
+ /// Opens one of the app's own links (the credits, the source code) in the default browser.
+ private void OpenLink(string? url)
+ {
+ if (!ExternalLinks.IsAllowed(url))
+ {
+ return;
+ }
+ try
+ {
+ Process.Start(new ProcessStartInfo(url!) { UseShellExecute = true });
+ }
+ catch (System.ComponentModel.Win32Exception ex)
+ {
+ Post(new { type = "notice", message = $"Couldn't open your browser: {ex.Message}" });
+ }
+ }
+
private async Task ShutdownAsync()
{
SystemEvents.UserPreferenceChanged -= OnUserPreferenceChanged;
diff --git a/desktop/src/OpenRag.App/OpenRag.App.csproj b/desktop/src/OpenRag.App/OpenRag.App.csproj
index 8685a25..b55fc03 100644
--- a/desktop/src/OpenRag.App/OpenRag.App.csproj
+++ b/desktop/src/OpenRag.App/OpenRag.App.csproj
@@ -17,6 +17,9 @@
OpenRag
Open RAG
Open RAG
+ Wadi Touil; Ghassen Jamoussi
+ Carthavate
+ Copyright (C) 2026 Wadi Touil and Ghassen Jamoussi
0.1.0
Assets\OpenRag.ico
$(MSBuildThisFileDirectory)..\..\web\
diff --git a/desktop/src/OpenRag.Core/ChildHost.cs b/desktop/src/OpenRag.Core/ChildHost.cs
new file mode 100644
index 0000000..ca998ca
--- /dev/null
+++ b/desktop/src/OpenRag.Core/ChildHost.cs
@@ -0,0 +1,238 @@
+using System.Diagnostics;
+
+namespace OpenRag.Core;
+
+public sealed record EngineConnection(Uri BaseUrl);
+
+public sealed class EngineStartException(string message) : Exception(message);
+
+/// Runs a helper program (the engine, or the bundled language model server) as a hidden child process, writes
+/// its output to a log, and tells when it is ready: either from a line it prints, or from a health check.
+public sealed class ChildHost(EngineCommand command, IReadOnlyList arguments, string logPath, string name = "engine")
+ : IAsyncDisposable
+{
+ private const int TailLines = 12;
+ private static readonly TimeSpan ProbeInterval = TimeSpan.FromMilliseconds(500);
+
+ private readonly Queue _tail = new();
+ private readonly Lock _log = new();
+ private readonly TaskCompletionSource _readyLine = new(TaskCreationOptions.RunContinuationsAsynchronously);
+ private readonly TaskCompletionSource _exited = new(TaskCreationOptions.RunContinuationsAsynchronously);
+ private Process? _process;
+ private volatile bool _stopping;
+ private volatile bool _ready;
+
+ /// Raised when the process exits after it was ready, unless we stopped it ourselves.
+ public event Action? Exited;
+
+ /// Lets the app put the process in its job object, so it dies with the app.
+ public event Action? Started;
+
+ /// Starts the process and waits for its ORE_READY port=N line.
+ public async Task StartAsync(IReadOnlyDictionary environment, TimeSpan timeout,
+ CancellationToken cancel = default)
+ {
+ Start(environment);
+ return await WaitAsync(_readyLine.Task, timeout, cancel);
+ }
+
+ /// Starts the process and waits until says it is ready (for example a health check).
+ public async Task StartAsync(IReadOnlyDictionary environment, Func> probe,
+ TimeSpan timeout, CancellationToken cancel = default)
+ {
+ Start(environment);
+ await WaitAsync(Probe(probe), timeout, cancel);
+ }
+
+ private async Task Probe(Func> probe)
+ {
+ using var stop = new CancellationTokenSource();
+ _ = _exited.Task.ContinueWith(_ => stop.Cancel(), TaskScheduler.Default);
+ while (!stop.IsCancellationRequested)
+ {
+ try
+ {
+ if (await probe(stop.Token))
+ {
+ return true;
+ }
+ await Task.Delay(ProbeInterval, stop.Token);
+ }
+ catch (Exception e) when (e is OperationCanceledException or HttpRequestException)
+ {
+ // Not up yet, or it exited; WaitAsync reports which.
+ }
+ }
+ return false;
+ }
+
+ /// Above this size the log moves to .old when the process next starts, so it can't grow forever.
+ public const long MaxLogBytes = 5 * 1024 * 1024;
+
+ private void Start(IReadOnlyDictionary environment)
+ {
+ Directory.CreateDirectory(Path.GetDirectoryName(logPath)!);
+ RotateLog();
+ var info = new ProcessStartInfo(command.FileName)
+ {
+ WorkingDirectory = command.WorkingDirectory,
+ UseShellExecute = false,
+ CreateNoWindow = true,
+ RedirectStandardOutput = true,
+ RedirectStandardError = true,
+ StandardOutputEncoding = System.Text.Encoding.UTF8,
+ StandardErrorEncoding = System.Text.Encoding.UTF8,
+ };
+ foreach (var argument in arguments)
+ {
+ info.ArgumentList.Add(argument);
+ }
+ info.Environment["PYTHONUTF8"] = "1";
+ foreach (var (key, value) in environment)
+ {
+ info.Environment[key] = value;
+ }
+
+ var process = new Process { StartInfo = info, EnableRaisingEvents = true };
+ process.OutputDataReceived += (_, e) =>
+ {
+ Write(e.Data);
+ if (ReadyLine.TryParsePort(e.Data) is { } port)
+ {
+ _readyLine.TrySetResult(new EngineConnection(new Uri($"http://127.0.0.1:{port}/")));
+ }
+ };
+ process.ErrorDataReceived += (_, e) => Write(e.Data);
+ process.Exited += (_, _) =>
+ {
+ var code = SafeExitCode(process);
+ _exited.TrySetResult(code);
+ // Before it was ready, the waiting start reports the failure. A stop we asked for is not a crash.
+ if (_ready && !_stopping)
+ {
+ Exited?.Invoke(code);
+ }
+ };
+
+ try
+ {
+ process.Start();
+ }
+ catch (System.ComponentModel.Win32Exception e)
+ {
+ throw new EngineStartException($"Couldn't start the {name} ({command.FileName}): {e.Message}");
+ }
+ _process = process;
+ Started?.Invoke(process);
+ process.BeginOutputReadLine();
+ process.BeginErrorReadLine();
+ }
+
+ private async Task WaitAsync(Task ready, TimeSpan timeout, CancellationToken cancel)
+ {
+ using var timer = CancellationTokenSource.CreateLinkedTokenSource(cancel);
+ timer.CancelAfter(timeout);
+ try
+ {
+ var first = await Task.WhenAny(ready, _exited.Task).WaitAsync(timer.Token);
+ if (first == ready && !_exited.Task.IsCompleted && (ready.Result is not bool ok || ok))
+ {
+ _ready = true;
+ return ready.Result;
+ }
+ throw new EngineStartException(FailureMessage(await _exited.Task));
+ }
+ catch (OperationCanceledException) when (!cancel.IsCancellationRequested)
+ {
+ Stop();
+ throw new EngineStartException($"The {name} didn't start within {timeout.TotalSeconds:0} seconds. {Tail()}");
+ }
+ }
+
+ public void Stop()
+ {
+ _stopping = true;
+ try
+ {
+ if (_process is { HasExited: false } process)
+ {
+ process.Kill(entireProcessTree: true);
+ }
+ }
+ catch (Exception e) when (e is InvalidOperationException or System.ComponentModel.Win32Exception)
+ {
+ // Already gone.
+ }
+ }
+
+ public async ValueTask DisposeAsync()
+ {
+ Stop();
+ if (_process is not null)
+ {
+ await _process.WaitForExitAsync().WaitAsync(TimeSpan.FromSeconds(5)).ContinueWith(_ => { });
+ _process.Dispose();
+ }
+ }
+
+ private void Write(string? line)
+ {
+ if (line is null)
+ {
+ return;
+ }
+ lock (_log)
+ {
+ _tail.Enqueue(line);
+ while (_tail.Count > TailLines)
+ {
+ _tail.Dequeue();
+ }
+ try
+ {
+ File.AppendAllText(logPath, $"{DateTime.Now:HH:mm:ss} {line}{Environment.NewLine}");
+ }
+ catch (IOException)
+ {
+ // The log is a convenience; a locked file must not stop the process.
+ }
+ }
+ }
+
+ private void RotateLog()
+ {
+ try
+ {
+ if (File.Exists(logPath) && new FileInfo(logPath).Length > MaxLogBytes)
+ {
+ File.Move(logPath, logPath + ".old", overwrite: true);
+ }
+ }
+ catch (IOException)
+ {
+ // Rotation is housekeeping; the process starts either way.
+ }
+ }
+
+ private string Tail()
+ {
+ lock (_log)
+ {
+ return _tail.Count == 0 ? "" : "Last output:\n" + string.Join("\n", _tail);
+ }
+ }
+
+ private string FailureMessage(int code) => $"The {name} stopped (exit code {code}) before it was ready. {Tail()}".Trim();
+
+ private static int SafeExitCode(Process process)
+ {
+ try
+ {
+ return process.ExitCode;
+ }
+ catch (InvalidOperationException)
+ {
+ return -1;
+ }
+ }
+}
diff --git a/desktop/src/OpenRag.Core/Engine.cs b/desktop/src/OpenRag.Core/Engine.cs
index 0a743d2..c062e48 100644
--- a/desktop/src/OpenRag.Core/Engine.cs
+++ b/desktop/src/OpenRag.Core/Engine.cs
@@ -1,4 +1,5 @@
-using System.Diagnostics;
+using System.Net;
+using System.Net.Sockets;
using System.Security.Cryptography;
using System.Text.RegularExpressions;
@@ -14,6 +15,7 @@ public sealed record AppPaths(string Root)
public string WebView => Path.Combine(Root, "WebView2");
public string Logs => Path.Combine(Root, "logs");
public string EngineLog => Path.Combine(Logs, "engine.log");
+ public string LlmLog => Path.Combine(Logs, "llm.log");
public string ErrorLog => Path.Combine(Logs, "errors.log");
}
@@ -56,12 +58,42 @@ public static bool IsLocalDocumentPath(string? path) =>
public static bool CanOpen(string? path) => IsLocalDocumentPath(path) && File.Exists(path);
}
-/// How to start the engine: a program, its base arguments, where to run it, and an optional config file.
-public sealed record EngineCommand(string FileName, IReadOnlyList Arguments, string WorkingDirectory, string? ConfigPath)
+/// The language model an installed app brings along: llama.cpp's server and a GGUF model file.
+public sealed record LlmBundle(string ServerPath, string ModelPath)
{
- public IReadOnlyList ServeArguments(string dataDirectory, int parentProcessId)
+ public const string ModelAlias = "qwen3-4b-instruct";
+
+ /// llama-server reads its key from here, so the key never shows on its command line.
+ public const string ApiKeyVariable = "LLAMA_API_KEY";
+
+ /// Loopback only, with its own key; the context matches the engine's default (8192 tokens).
+ public IReadOnlyList Arguments(int port) =>
+ ["-m", ModelPath, "--host", "127.0.0.1", "--port", port.ToString(), "--ctx-size", "8192", "--jinja",
+ "--alias", ModelAlias, "--no-webui"];
+
+ public static int FreePort()
+ {
+ var listener = new TcpListener(IPAddress.Loopback, 0);
+ listener.Start();
+ var port = ((IPEndPoint)listener.LocalEndpoint).Port;
+ listener.Stop();
+ return port;
+ }
+}
+
+/// How to start the engine: a program, its base arguments, where to run it, an optional config file, and the
+/// bundled language model when there is one.
+public sealed record EngineCommand(string FileName, IReadOnlyList Arguments, string WorkingDirectory, string? ConfigPath,
+ LlmBundle? Llm = null)
+{
+ /// The bundled language model's server, when the app runs one (an OpenAI-compatible /v1 URL).
+ public IReadOnlyList ServeArguments(string dataDirectory, int parentProcessId, string? llmUrl = null)
{
var args = new List(Arguments) { "--data-dir", dataDirectory, "--parent-pid", parentProcessId.ToString(), "--warm" };
+ if (llmUrl is not null)
+ {
+ args.AddRange(["--llm-url", llmUrl]);
+ }
if (ConfigPath is not null)
{
args.AddRange(["--config", ConfigPath]);
@@ -84,7 +116,10 @@ public static class EngineLocator
if (File.Exists(python))
{
var config = Path.Combine(engine, "ore.toml");
- return new EngineCommand(python, ["-m", "open_rag_engine", "serve"], engine, File.Exists(config) ? config : null);
+ var server = Path.Combine(engine, "llm", "llama-server.exe");
+ var model = Path.Combine(engine, "llm", "model.gguf");
+ var llm = File.Exists(server) && File.Exists(model) ? new LlmBundle(server, model) : null;
+ return new EngineCommand(python, ["-m", "open_rag_engine", "serve"], engine, File.Exists(config) ? config : null, llm);
}
if (!allowCheckout)
{
@@ -112,166 +147,3 @@ private static bool IsCheckout(string dir)
return File.Exists(pyproject) && File.ReadAllText(pyproject).Contains("name = \"open-rag-engine\"", StringComparison.Ordinal);
}
}
-
-public sealed record EngineConnection(Uri BaseUrl);
-
-public sealed class EngineStartException(string message) : Exception(message);
-
-/// Runs the engine as a hidden child process, writes its output to a log, and reports the port it listens on.
-public sealed class EngineHost(EngineCommand command, IReadOnlyList arguments, string logPath) : IAsyncDisposable
-{
- private const int TailLines = 12;
- private readonly Queue _tail = new();
- private readonly Lock _log = new();
- private Process? _process;
- private volatile bool _stopping;
-
- /// Raised when the engine exits after it was ready (a crash, or killed from outside).
- public event Action? Exited;
-
- /// Lets the app put the process in its job object, so the engine dies with the app.
- public event Action? Started;
-
- public async Task StartAsync(IReadOnlyDictionary environment, TimeSpan timeout,
- CancellationToken cancel = default)
- {
- Directory.CreateDirectory(Path.GetDirectoryName(logPath)!);
- var info = new ProcessStartInfo(command.FileName)
- {
- WorkingDirectory = command.WorkingDirectory,
- UseShellExecute = false,
- CreateNoWindow = true,
- RedirectStandardOutput = true,
- RedirectStandardError = true,
- StandardOutputEncoding = System.Text.Encoding.UTF8,
- StandardErrorEncoding = System.Text.Encoding.UTF8,
- };
- foreach (var argument in arguments)
- {
- info.ArgumentList.Add(argument);
- }
- info.Environment["PYTHONUTF8"] = "1";
- foreach (var (key, value) in environment)
- {
- info.Environment[key] = value;
- }
-
- var ready = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
- var process = new Process { StartInfo = info, EnableRaisingEvents = true };
- process.OutputDataReceived += (_, e) =>
- {
- Write(e.Data);
- if (ReadyLine.TryParsePort(e.Data) is { } port)
- {
- ready.TrySetResult(new EngineConnection(new Uri($"http://127.0.0.1:{port}/")));
- }
- };
- process.ErrorDataReceived += (_, e) => Write(e.Data);
- process.Exited += (_, _) =>
- {
- var code = SafeExitCode(process);
- // A stop we asked for is not a crash, so it isn't reported.
- if (!ready.TrySetException(new EngineStartException(FailureMessage(code))) && !_stopping)
- {
- Exited?.Invoke(code);
- }
- };
-
- try
- {
- process.Start();
- }
- catch (System.ComponentModel.Win32Exception e)
- {
- throw new EngineStartException($"Couldn't start the engine ({command.FileName}): {e.Message}");
- }
- _process = process;
- Started?.Invoke(process);
- process.BeginOutputReadLine();
- process.BeginErrorReadLine();
-
- using var timer = CancellationTokenSource.CreateLinkedTokenSource(cancel);
- timer.CancelAfter(timeout);
- try
- {
- return await ready.Task.WaitAsync(timer.Token);
- }
- catch (OperationCanceledException) when (!cancel.IsCancellationRequested)
- {
- Stop();
- throw new EngineStartException($"The engine didn't start within {timeout.TotalSeconds:0} seconds. {Tail()}");
- }
- }
-
- public void Stop()
- {
- _stopping = true;
- try
- {
- if (_process is { HasExited: false } process)
- {
- process.Kill(entireProcessTree: true);
- }
- }
- catch (Exception e) when (e is InvalidOperationException or System.ComponentModel.Win32Exception)
- {
- // Already gone.
- }
- }
-
- public async ValueTask DisposeAsync()
- {
- Stop();
- if (_process is not null)
- {
- await _process.WaitForExitAsync().WaitAsync(TimeSpan.FromSeconds(5)).ContinueWith(_ => { });
- _process.Dispose();
- }
- }
-
- private void Write(string? line)
- {
- if (line is null)
- {
- return;
- }
- lock (_log)
- {
- _tail.Enqueue(line);
- while (_tail.Count > TailLines)
- {
- _tail.Dequeue();
- }
- try
- {
- File.AppendAllText(logPath, $"{DateTime.Now:HH:mm:ss} {line}{Environment.NewLine}");
- }
- catch (IOException)
- {
- // The log is a convenience; a locked file must not stop the engine.
- }
- }
- }
-
- private string Tail()
- {
- lock (_log)
- {
- return _tail.Count == 0 ? "" : "Last output:\n" + string.Join("\n", _tail);
- }
- }
-
- private string FailureMessage(int code) => $"The engine stopped (exit code {code}) before it was ready. {Tail()}".Trim();
-
- private static int SafeExitCode(Process process)
- {
- try
- {
- return process.ExitCode;
- }
- catch (InvalidOperationException)
- {
- return -1;
- }
- }
-}
diff --git a/desktop/src/OpenRag.Core/ExternalLinks.cs b/desktop/src/OpenRag.Core/ExternalLinks.cs
new file mode 100644
index 0000000..1de1982
--- /dev/null
+++ b/desktop/src/OpenRag.Core/ExternalLinks.cs
@@ -0,0 +1,17 @@
+namespace OpenRag.Core;
+
+/// The only web pages the app opens, in the default browser: its authors' profiles and its source code. The
+/// page asks by URL; anything not on this list is ignored, so even a compromised page can't open other sites.
+public static class ExternalLinks
+{
+ public static IReadOnlySet Allowed { get; } = new HashSet(StringComparer.Ordinal)
+ {
+ "https://github.com/Carthavate/open-rag-engine",
+ "https://github.com/TWadi",
+ "https://www.linkedin.com/in/wadi-touil-117472319/",
+ "https://github.com/GhassenJamoussi99",
+ "https://www.linkedin.com/in/ghassen-jamoussi/",
+ };
+
+ public static bool IsAllowed(string? url) => url is not null && Allowed.Contains(url);
+}
diff --git a/desktop/tests/OpenRag.Core.Tests/EngineTests.cs b/desktop/tests/OpenRag.Core.Tests/EngineTests.cs
index e72f73b..aeff025 100644
--- a/desktop/tests/OpenRag.Core.Tests/EngineTests.cs
+++ b/desktop/tests/OpenRag.Core.Tests/EngineTests.cs
@@ -104,6 +104,23 @@ public void Prefers_the_bundled_engine_next_to_the_app()
Assert.Equal(config, command.ConfigPath);
}
+ [Fact]
+ public void An_installed_app_brings_its_language_model()
+ {
+ using var dir = new TempDir();
+ dir.Make("engine", "python", "python.exe");
+ var server = dir.Make("engine", "llm", "llama-server.exe");
+ var model = dir.Make("engine", "llm", "model.gguf");
+ var command = EngineLocator.Find(dir.Path, Env(), allowCheckout: false)!;
+ Assert.Equal(new LlmBundle(server, model), command.Llm);
+ var args = command.Llm!.Arguments(4242);
+ Assert.Equal("127.0.0.1", args[args.ToList().IndexOf("--host") + 1]);
+ Assert.Equal("4242", args[args.ToList().IndexOf("--port") + 1]);
+ }
+
+ [Fact]
+ public void Free_ports_are_real_loopback_ports() => Assert.InRange(LlmBundle.FreePort(), 1024, 65535);
+
[Fact]
public void Finds_a_development_checkout_above_the_app()
{
@@ -150,9 +167,18 @@ public void Serve_arguments_add_data_dir_parent_and_config()
Assert.Equal(["-m", "open_rag_engine", "serve", "--data-dir", "C:/data", "--parent-pid", "42", "--warm",
"--config", "C:/app/ore.toml"], args);
}
+
+ [Fact]
+ public void Serve_arguments_point_the_engine_at_the_bundled_model()
+ {
+ var command = new EngineCommand("python.exe", ["-m", "open_rag_engine", "serve"], "C:/app", null);
+ var args = command.ServeArguments("C:/data", 42, "http://127.0.0.1:5000/v1");
+ Assert.Equal(["-m", "open_rag_engine", "serve", "--data-dir", "C:/data", "--parent-pid", "42", "--warm",
+ "--llm-url", "http://127.0.0.1:5000/v1"], args);
+ }
}
-public class EngineHostTests
+public class ChildHostTests
{
private static EngineCommand Cmd(string script) => new("cmd.exe", ["/c", script], Environment.CurrentDirectory, null);
@@ -160,7 +186,7 @@ public class EngineHostTests
public async Task Start_returns_the_port_the_engine_announces()
{
using var dir = new TempDir();
- await using var host = new EngineHost(Cmd("echo starting & echo ORE_READY port=4321 & ping -n 20 127.0.0.1 >nul"),
+ await using var host = new ChildHost(Cmd("echo starting & echo ORE_READY port=4321 & ping -n 20 127.0.0.1 >nul"),
["/c", "echo starting & echo ORE_READY port=4321 & ping -n 20 127.0.0.1 >nul"], Path.Combine(dir.Path, "engine.log"));
var connection = await host.StartAsync(new Dictionary { ["ORE_API_TOKEN"] = "x" }, TimeSpan.FromSeconds(20));
Assert.Equal(new Uri("http://127.0.0.1:4321/"), connection.BaseUrl);
@@ -172,7 +198,7 @@ public async Task A_deliberate_stop_is_not_reported_as_a_crash()
{
using var dir = new TempDir();
var script = "echo ORE_READY port=4322 & ping -n 30 127.0.0.1 >nul";
- await using var host = new EngineHost(Cmd(script), ["/c", script], Path.Combine(dir.Path, "engine.log"));
+ await using var host = new ChildHost(Cmd(script), ["/c", script], Path.Combine(dir.Path, "engine.log"));
var crashes = 0;
host.Exited += _ => crashes++;
await host.StartAsync(new Dictionary(), TimeSpan.FromSeconds(20));
@@ -186,18 +212,41 @@ public async Task A_start_that_times_out_stops_the_process()
{
using var dir = new TempDir();
var script = "ping -n 30 127.0.0.1 >nul";
- await using var host = new EngineHost(Cmd(script), ["/c", script], Path.Combine(dir.Path, "engine.log"));
+ await using var host = new ChildHost(Cmd(script), ["/c", script], Path.Combine(dir.Path, "engine.log"));
System.Diagnostics.Process? started = null;
host.Started += p => started = p;
await Assert.ThrowsAsync(() => host.StartAsync(new Dictionary(), TimeSpan.FromSeconds(1)));
Assert.True(started!.WaitForExit(5000));
}
+ [Fact]
+ public async Task A_health_probe_decides_when_a_server_is_ready()
+ {
+ using var dir = new TempDir();
+ var script = "echo loading & ping -n 30 127.0.0.1 >nul";
+ await using var host = new ChildHost(Cmd(script), ["/c", script], Path.Combine(dir.Path, "llm.log"), "language model");
+ var checks = 0;
+ await host.StartAsync(new Dictionary(), _ => Task.FromResult(++checks >= 3), TimeSpan.FromSeconds(20));
+ Assert.Equal(3, checks);
+ }
+
+ [Fact]
+ public async Task A_server_that_exits_while_loading_is_reported()
+ {
+ using var dir = new TempDir();
+ var script = "echo failed to load model 1>&2 & exit 1";
+ await using var host = new ChildHost(Cmd(script), ["/c", script], Path.Combine(dir.Path, "llm.log"), "language model");
+ var error = await Assert.ThrowsAsync(() =>
+ host.StartAsync(new Dictionary(), _ => Task.FromResult(false), TimeSpan.FromSeconds(20)));
+ Assert.Contains("failed to load model", error.Message);
+ Assert.Contains("language model", error.Message);
+ }
+
[Fact]
public async Task A_crash_before_ready_reports_the_last_output()
{
using var dir = new TempDir();
- await using var host = new EngineHost(Cmd("echo no module named open_rag_engine 1>&2 & exit 3"),
+ await using var host = new ChildHost(Cmd("echo no module named open_rag_engine 1>&2 & exit 3"),
["/c", "echo no module named open_rag_engine 1>&2 & exit 3"], Path.Combine(dir.Path, "engine.log"));
var error = await Assert.ThrowsAsync(() =>
host.StartAsync(new Dictionary(), TimeSpan.FromSeconds(20)));
diff --git a/desktop/tests/OpenRag.Core.Tests/ExternalLinksTests.cs b/desktop/tests/OpenRag.Core.Tests/ExternalLinksTests.cs
new file mode 100644
index 0000000..be68cf4
--- /dev/null
+++ b/desktop/tests/OpenRag.Core.Tests/ExternalLinksTests.cs
@@ -0,0 +1,46 @@
+using System.Text.RegularExpressions;
+using OpenRag.Core;
+
+namespace OpenRag.Core.Tests;
+
+public class ExternalLinksTests
+{
+ [Theory]
+ [InlineData("https://github.com/TWadi")]
+ [InlineData("https://www.linkedin.com/in/ghassen-jamoussi/")]
+ [InlineData("https://github.com/Carthavate/open-rag-engine")]
+ public void Opens_the_credits_and_the_source(string url) => Assert.True(ExternalLinks.IsAllowed(url));
+
+ [Theory]
+ [InlineData(null)]
+ [InlineData("")]
+ [InlineData("http://github.com/TWadi")]
+ [InlineData("https://github.com/TWadi/../evil")]
+ [InlineData("https://github.com/TWadi.evil.example")]
+ [InlineData("https://GITHUB.com/TWadi")]
+ [InlineData("file:///C:/Windows/System32/calc.exe")]
+ [InlineData("javascript:alert(1)")]
+ public void Refuses_anything_else(string? url) => Assert.False(ExternalLinks.IsAllowed(url));
+
+ /// The Credits sheet (desktop/web/src/lib/credits.ts) must only show links the window will open.
+ [Fact]
+ public void Every_link_in_the_credits_sheet_opens()
+ {
+ var credits = File.ReadAllText(Path.Combine(DesktopFolder(), "web", "src", "lib", "credits.ts"));
+ var links = Regex.Matches(credits, "\"(https://[^\"]+)\"").Select(m => m.Groups[1].Value).ToList();
+ Assert.Equal(5, links.Count);
+ Assert.All(links, link => Assert.True(ExternalLinks.IsAllowed(link), $"{link} isn't in ExternalLinks.Allowed"));
+ }
+
+ private static string DesktopFolder()
+ {
+ for (var dir = new DirectoryInfo(AppContext.BaseDirectory); dir is not null; dir = dir.Parent)
+ {
+ if (File.Exists(Path.Combine(dir.FullName, "OpenRag.slnx")))
+ {
+ return dir.FullName;
+ }
+ }
+ throw new DirectoryNotFoundException("desktop/OpenRag.slnx not found above the test output.");
+ }
+}
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()
From 935fcc3bb5e5f580e96455491dd364d657ac4333 Mon Sep 17 00:00:00 2001
From: Wadi
Date: Mon, 2 Nov 2026 20:04:30 +0100
Subject: [PATCH 3/3] feat: credits for Wadi and Ghassen in the app
The sidebar says who developed Open RAG and opens a Credits sheet with both
authors' GitHub and LinkedIn and the source code. Links open in the default
browser through the window, which accepts only the links on its own list; a
test checks the sheet's links against it.
---
desktop/web/src/components/Credits.tsx | 88 ++++++++++++++++++++++++++
desktop/web/src/components/Dialogs.tsx | 2 +-
desktop/web/src/components/Sidebar.tsx | 10 ++-
desktop/web/src/lib/credits.ts | 29 +++++++++
desktop/web/src/lib/host.ts | 4 ++
5 files changed, 129 insertions(+), 4 deletions(-)
create mode 100644 desktop/web/src/components/Credits.tsx
create mode 100644 desktop/web/src/lib/credits.ts
diff --git a/desktop/web/src/components/Credits.tsx b/desktop/web/src/components/Credits.tsx
new file mode 100644
index 0000000..fa4d46f
--- /dev/null
+++ b/desktop/web/src/components/Credits.tsx
@@ -0,0 +1,88 @@
+import { ExternalLink } from "lucide-react";
+import { useState, type ReactNode } from "react";
+import { CREDITS, SOURCE_URL, type Credit } from "../lib/credits";
+import { host } from "../lib/host";
+import { Sheet } from "./Dialogs";
+import { Button, LogoMark } from "./primitives";
+
+function Initials({ credit, className = "" }: { credit: Credit; className?: string }) {
+ return (
+
+ {credit.initials}
+
+ );
+}
+
+function LinkButton({ href, label, children }: { href: string; label: string; children: ReactNode }) {
+ return (
+
+ );
+}
+
+/** The sidebar's "Developed by" line; it opens the Credits sheet with both authors' GitHub and LinkedIn. */
+export function Credits() {
+ const [open, setOpen] = useState(false);
+ const first = (c: Credit) => c.name.split(" ")[0];
+ return (
+ <>
+
+
+ setOpen(false)}>
+
+
+
Credits
+
+
+ Open RAG is developed by Wadi and Ghassen, from the RAG course we made for the AI Engineering Arena.
+
+
+ {CREDITS.map((c) => (
+ -
+
+
+ GitHub
+ LinkedIn
+
+
+ ))}
+
+
+ Free and open source (AGPL-3.0).{" "}
+
+
+
+
+
+
+ >
+ );
+}
diff --git a/desktop/web/src/components/Dialogs.tsx b/desktop/web/src/components/Dialogs.tsx
index 70e2072..92d5b7d 100644
--- a/desktop/web/src/components/Dialogs.tsx
+++ b/desktop/web/src/components/Dialogs.tsx
@@ -2,7 +2,7 @@ import { AnimatePresence, motion } from "motion/react";
import { useEffect, useRef, useState, type ReactNode } from "react";
import { Button } from "./primitives";
-function Sheet({ open, onClose, children }: { open: boolean; onClose: () => void; children: ReactNode }) {
+export function Sheet({ open, onClose, children }: { open: boolean; onClose: () => void; children: ReactNode }) {
useEffect(() => {
if (!open) return;
const onKey = (e: KeyboardEvent) => e.key === "Escape" && onClose();
diff --git a/desktop/web/src/components/Sidebar.tsx b/desktop/web/src/components/Sidebar.tsx
index d34611a..7d8c0cc 100644
--- a/desktop/web/src/components/Sidebar.tsx
+++ b/desktop/web/src/components/Sidebar.tsx
@@ -1,6 +1,7 @@
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 = {
@@ -38,9 +39,12 @@ export function Sidebar(props: Props) {
)}
-