cpp-workspace

A C++ Retrieval-Augmented Generation (RAG) application powered by Ollama, featuring embeddings via Qdrant vector database, ncurses UI with theme support, and streaming output.

Capabilities

• Connects to local Ollama for LLM inference.
• Generates embeddings and stores them in Qdrant vector database.
• Retrieves relevant documents and generates context-aware answers.
• Provides an interactive ncurses terminal UI with streaming responses.

Requirements

In order to run your own copy of the project it is recommended to satisfly the following requirements.

Supported operating systems

• 🏆 Debian based Linux
  • see help for available options:

    # always inspect scripts before running them on your machine
    bash tools/shell/install.sh ?

  • install all dependencies required to work with the project:

    # always inspect scripts before running them on your machine
    bash tools/shell/install.sh all

• 🆗 macOS
  • see help for available options:

    # always inspect scripts before running them on your machine
    bash tools/shell/install.sh ?

  • install all dependencies required to work with the project (some dependencies may be missing):

    # always inspect scripts before running them on your machine
    bash tools/shell/install.sh all osx

• 🤷 Windows
  • Install using one of the following approaches:
    • MSVC (recommended): Download and install Visual Studio Community with C++ build tools
    • MinGW: Install via MSYS2 or Chocolatey
    • WSL2: Use Windows Subsystem for Linux and follow the Linux instructions
    • Additionally, install CMake and Git for Windows.
    • given that the dev environment is set up, the following commands should be used to install shellcheck via PowerShell;

      iwr -useb get.scoop.sh | iex
      scoop install shellcheck

    • recommended shell: Git for Windows > Git BASH;
    • configure Git to use LF as a carriage return

      git config --global core.autocrlf false
      git config --global core.eol lf

Integrated development environment

🏆 Visual Studio Code - recommended for all operating systems

Suggested extensions:

• C/C++ Extension Pack
• CMake Tools

See .vscode/extensions for the complete list.

Core dependencies

• Git
• Python or NodeJS for conventional commits
• Bash 5 for scripting
• CMake
• A Build system (one of):
  • Make
  • Ninja
• A C++ compiler (one of):
  • GCC
  • Clang
  • MSVC
• Docker to run Qdrant locally
• Ollama

Environment variables

In the project root, create a .env file with the following content

export QDRANT_URL="http://localhost:6333"
export QDRANT_API_KEY="your-secure-read-and-write-key"
export QDRANT_API_KEY_READ_ONLY="your-secure-read-only-key"

Contributing: Conventional Commits

This project requires Commitizen for standardized commit messages.

Setup:

• Linux/macOS: brew install commitizen or pip install commitizen
• Windows: Use WSL2 and follow Linux instructions, or install via MSYS2

Committing:

cz commit  # Interactive commit prompt

FAQ

Commands

1. Install

   bash ./tools/shell/install.sh --help

2. Build

   bash ./tools/shell/build.sh --help

3. Format

   bash ./tools/shell/format.sh

Manual build

rm -rf ./build/* ;\
  conan install . --build=missing ;\
  cmake --preset conan-release ;\
  cmake --build --preset conan-release

or

rm -rf ./build/* ./CMakeUserPresets.json ;\
  conan install . --build=missing ;\
  cmake --preset conan-release ;\
  cmake --build --preset conan-release

Runtime arguments

This app accepts the following command-line arguments to customize behavior:

Argument	Type	Default	Description
--model=<name>	String	gemma3n:latest	The LLM model to use for inference.
--embedding_model=<name>	String	embeddinggemma:latest	The model to use for generating embeddings.
--prompt=<text>	String	Hey! What's up!	Initial prompt or query to send to the model.
--stream=<true|false>	Boolean	false	Enable streaming responses.
--rag=<true|false>	Boolean	false	Enable Retrieval-Augmented Generation (RAG) mode.
--interactive=<true|false>	Boolean	false	Enable interactive mode for multi-turn conversations.
--dark_theme=<true|false>	Boolean	false	Use dark theme for the ncurses interface.
--skip_embedding=<true|false>	Boolean	false	Skip embedding creation.
--help=<true|false>	Boolean	false	Print help.

Notes

• Boolean arguments accept true or false (case-sensitive lowercase)
• String arguments (--model, --embedding_model, --prompt) accept any alphanumeric string; no spaces or special characters are recommended
• Arguments can be provided in any order

Run the app

Source .env first (see the Environment variables section), then run the app

source .env; \
  ./build/Release/bin/cpp-workspace-app

Quick Start

1. Install Ollama and pull two models, e.g. embeddinggemma:latest and gemma3n:latest.

2. Set up a virtual environment containing required dependencies

   sudo apt-get update; \
     sudo apt-get install -y \
       build-essential \
       cmake \
       git \
       python3-pip \
       clang-format \
       clang-tidy \
       cppcheck; \
     python3 -m venv .venv

   source .venv/bin/activate; \
     pip install conan; \
     conan --version; \
     conan profile detect --force

3. Build the project or download the latest release:

   bash tools/shell/build.sh --clean --release --exe-args '--skip_embedding=true'

4. Run in interactive RAG mode:

   ./build/Release/bin/cpp-workspace-app --interactive=true --rag=true