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 ( + + ); +} + +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) => ( +
  • +
    + +
    +

    {c.name}

    +

    {c.role}

    +
    +
    +
    + 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) {

)} -