RAVEN

Retrieval Augmented Adaptive Epistemic Navigation

📖 User Documentation · 🏗️ Architecture Overview

A privacy-first, fully offline RAG (Retrieval-Augmented Generation) desktop application. RAVEN is a complete workspace for interacting with your documents through local AI — not just a chatbot with a search button.

RAVEN runs entirely on your machine. No data leaves your computer. No cloud calls. No telemetry.

Features

• Fully Offline — Everything runs locally. No internet required after initial setup.
• 8 Retrieval Mechanisms — 4 main strategies (Embedded, Hierarchical, Agreement-Based, Vector-Conditioned), each with Local and Global variants. The model can adaptively choose the best mechanism based on your query.
• Multi-Knowledge Architecture — Organize files into separate Knowledge databases by category (engineering, medical, legal, etc.). Prevents data contamination during retrieval.
• Intelligent Ingestion — Upload a file, and the base model automatically splits it into semantically coherent sections, extracting summaries, keywords, conditions, and definitions.
• Adaptive Retrieval — RAVEN can automatically select the optimal retrieval strategy for each query, or you can choose manually.
• Source Reconstruction — Retrieved answers include highlighted source sections from the original files so you can verify results instead of trusting blindly.
• Memory Pipeline — Sliding-window context management with persistent memory stored per conversation.
• Model Management — Download and switch between multiple base models (Gemma 4, Qwen2.5) directly from the app.
• Parameter Tuning — Adjust n_ctx, n_gpu_layers, n_threads per model.
• Sentence Boundary Detection — ONNX-powered neural SBD for accurate text segmentation during ingestion.
• Persistent Conversations — Full chat history with memory update system.

How It Works

RAVEN operates in two phases: Ingestion and Retrieval.

Ingestion

When you upload a file, RAVEN assigns it to a Knowledge database (you choose which one). The base model reads the entire file and splits it into sections based on semantic shifts in context. For each section, it creates a compact structured JSON containing a summary, keywords, conditional statements, and definitions. The file is then chunked into 150-token segments with overlap, and each chunk is converted into an embedding vector (1024-dim via BGE-M3) stored using sqlite-vec for fast ANN search.

Retrieval

When you ask a question, RAVEN selects a retrieval mechanism — either adaptively via the base model or by your explicit choice. Depending on the mechanism, it performs vector similarity search, hierarchical LLM-based reasoning over section metadata, or a combination of both. The retrieved sections are passed to the base model alongside your query, and the model generates a response grounded in your documents.

In parallel, the Source Reconstruction engine extracts the relevant sections, reconstructs the original file, and highlights the retrieved portions so you can verify every answer against its source.

Knowledge Base

Files are stored across multiple isolated SQLite databases called Knowledges. Each Knowledge has a user-defined summary describing its contents. This separation prevents data contamination — a query about engineering files won't accidentally pull in medical records. Global retrieval searches across all Knowledges; Local retrieval stays within one.

Memory

RAVEN maintains a strict 32K token context window with a sliding window for long conversations. Older messages are automatically saved to a per-conversation memory database and can be retrieved via embedded search when the model needs to recall past context.

Tech Stack

• UI: Flet (Python → Flutter desktop)
• LLM: llama-cpp-python with Vulkan GPU acceleration (GGUF models)
• Embeddings: BGE-M3 (F16, 1024-dim)
• Vector Search: sqlite-vec
• Sentence Boundary Detection: SaT-3L-SM (ONNX)
• Download Engine: curl_cffi
• Packaging: PyInstaller + Inno Setup

System Requirements

• OS: Windows 10 or later
• Python: 3.11 (for source builds)
• GPU: Vulkan-compatible (recommended for LLM inference)
• VRAM: 6 GB minimum
• RAM: 8 GB minimum, 16 GB+ recommended
• Storage: ~5 GB free (models + app)

Download

Pre-built installers are available on the Releases page.

Download RAVEN_V0_1_Setup.exe and run it. No Python installation required for the binary distribution.

---

Building from Source

1. Clone the repository

git clone https://github.com/NoomexAI/RAVEN.git
cd RAVEN

2. Create a virtual environment

python -m venv venv
.\venv\Scripts\activate   # Windows

3. Install llama-cpp-python with Vulkan backend

You must have vulkan-sdk and Microsoft C++ build tools with a C++ compiler like MSVC installed to build llama-cpp-python with vulkan.

$env:CMAKE_ARGS="-DGGML_VULKAN=1"   # Windows
pip install llama-cpp-python --no-cache-dir --force-reinstall -v

For CUDA or CPU-only backends, see the llama-cpp-python documentation for instructions.

4. Install dependencies

pip install -r requirements.txt

5. Download required models

The embedding and SBD models are hard dependencies:

Model	File	Size	Location
BGE-M3 Embeddings	bge-m3-F16.gguf	~1.1 GB	models/embedding_model/
SaT-3L-SM SBD	model_optimized.onnx	~408 MB	models/sbd_model/sat-3l-sm/
SaT-3L-SM config	config.json	~1 KB	models/sbd_model/sat-3l-sm/

Download links (all from HuggingFace):

• bge-m3-F16.gguf: gpustack/bge-m3-GGUF
• sat-3l-sm (config.json + model_optimized.onnx): segment-any-text/sat-3l-sm

Create the directory structure and place the downloaded files:

models/
├── embedding_model/
│   └── bge-m3-F16.gguf
└── sbd_model/
    └── sat-3l-sm/
        ├── config.json
        └── model_optimized.onnx

6. Run the app

.\venv\Scripts\python.exe main.py   # Windows

Base models can be downloaded directly from the app's settings page.

7. Packaging

Run pack.bat file.

pack.bat

This will create dist/RAVEN_V0_1/RAVEN_V0_1.exe file.

Right click on installer.iss file and click on Compile. This will create an installer/RAVEN_V0_1_setup.exe file.

Project Structure

RAVEN/
├── core/              — Core logic (LLM, pipeline, RAG, conversation, constants)
├── shared/            — Shared utilities (download manager, settings, event bus)
├── ui/                — Flet UI components
├── models/            — Model files (download manually, see step 5)
├── data/              — User data (conversations, knowledge bases, settings)
├── grammar/           — LLM grammar files (used during ingestion)
├── dist/              — PyInstaller build output
└── installer/         — Setup executable

License

MIT — Copyright (c) 2026 NoomexAI