ofxRAG

openFrameworks addon for low-level Retrieval-Augmented Generation (RAG).

What is ofxRAG?

ofxRAG brings retrieval-augmented context building into the openFrameworks ecosystem. It acts as a low-level bridge between:

openFrameworks (oF) SentencePiece ONNX Runtime FAISS ofxRAG focuses exclusively on retrieval and context preparation. It does not include any text generation logic.

Instead, it is designed to be fully compatible with ofxLlamaCpp, which can be used as a separate, local runtime backend for text generation using GGUF LLaMA-family models.

Together, ofxRAG and ofxLlamaCpp enable fully local, offline, and transparent Retrieval-Augmented Generation pipelines for creative coding projects, interactive installations, research systems, and long-running real-time applications—without Python, cloud services, or high-level framework abstractions.

Tested Environments

ofxRAG has been validated on:

x86_64 (Ubuntu 24.04.3 LTS, Debian 12 & 13) ARM 64-bit (Raspberry Pi) macOS (Apple Silicon M2) openFrameworks: of_v0.12.0_linux64gcc6_release of_v0.12.1_linux64_gcc6_release

Dependencies

SentencePiece Subword tokenization library for text inputs, ensuring model-consistent and language-agnostic preprocessing. https://github.com/google/sentencepiece

ONNX Runtime High-performance inference engine for executing pre-exported embedding models in a deployment-ready environment. https://github.com/microsoft/onnxruntime

FAISS Efficient similarity search and clustering library for large-scale vectorized document collections. https://github.com/facebookresearch/faiss

Build Tool Dependency

CMake CMake is required to configure and build the native dependencies used by ofxRAG, specifically SentencePiece and FAISS. ONNX Runtime is integrated as a prebuilt binary and does not require compilation.

CMake is cross-platform and must be installed before attempting to build these libraries

Ubuntu / Debian (Linux):

sudo apt update
sudo apt install cmake

macOS (OS X):

brew install cmake

Example Dependencies

ofxDropdown (developed by roymacdonald) is used in the example_chat to provide a graphical user interface for selecting LLM models and chat templates via a dropdown menu. https://github.com/roymacdonald/ofxDropdown ofxLlamaCpp (developed by yannickhofmann) is used in the example_chat to provide local, offline text generation using GGUF LLaMA-family models. https://github.com/yannickhofmann/ofxLlamaCpp ofxPoDoFo (developed by nariakiiwatani, forked and edited by Yannick Hofmann yannickhofmann) is used in example_chat to enable information retrieval from PDFs. https://github.com/yannickhofmann/ofxPoDoFo ofxClipper (developed by bakercp) is a wrapper around ClipperLib providing polygon boolean operations, used in ofxPoDoFo to implement PDF clipping paths via geometric intersection of drawing and clipping paths. https://github.com/bakercp/ofxClipper

Setup

In the scripts folder, you will find a shell script to automatically clone and build the proper libraries. Navigate to the scripts folder and execute:

chmod +x install_deps.sh
./install_deps.sh

Platform Notes

macOS: install_deps.sh expects Homebrew to be installed. The script uses Homebrew to install or locate libomp for the FAISS build. Linux (linux64 and linuxaarch64 / Raspberry Pi): the build expects system OpenMP, BLAS, and LAPACK libraries to be available at link time. On many Linux systems these are already present; if linking fails with missing gomp, blas, or lapack symbols, install the corresponding development packages for your distribution.

ofxRAG uses pre-exported ONNX embedding models and their corresponding SentencePiece tokenizers. A helper script is provided to download compatible models into the addon's local models/ directory.

From the scripts folder, run:

chmod +x download_models.sh
./download_models.sh

Build and Run the Examples

Once the static libraries are compiled and the models are in place, you can build and run the example projects. The example_chat additionally requires at least one GGUF language model to be placed manually in the data/models folder. Please refer to the notes.txt file inside the data/models directory for details and model recommendations. The example does not include a Makefile. Generate the project using the openFrameworks Project Generator as usual. Then navigate into the example folder you wish to build (e.g., example_search):

cd example_search

Run make to compile the openFrameworks example:

make

Run the release executable:

make RunRelease

License

Copyright (c) 2025 Yannick Hofmann.

BSD Simplified License.

For information on usage and redistribution, and for a DISCLAIMER OF ALL WARRANTIES, see the file, "LICENSE.txt," in this distribution.