docs/SETUP_GUIDE.md

🚀 Kalos Engine — Step-by-Step Setup & User Guide

Welcome to the Kalos Engine Suite setup guide. This document guides you through selecting any GGUF model size (7B, 8B, 12B, 14B, 24B, 32B, 70B, 72B), configuring Ollama, initializing the dynamic C/CUDA engine suite, and running the precompiled native C executables with physical haptics, sensory perception, and dynamic VRAM scaling.

---

📋 Prerequisites & Dependency Setup

Before launching Kalos, ensure your environment has the required system packages:

1. System Requirements: Linux (Ubuntu 22.04+, Arch, Debian, Fedora) with an NVIDIA GPU & CUDA Toolkit 12.0+ installed.
2. Install System Dependencies:

   sudo apt update && sudo apt install ffmpeg ncurses-bin libncurses-dev
   

3. Install Ollama:

   curl -fsSL https://ollama.com/install.sh | sh
   

---

🎛️ Step 1: Model Selection & Ultra-Low VRAM Matrix

Kalos automatically adapts to ANY LLM parameter scale while maintaining an ultra-lightweight GPU memory footprint!

When running Kalos CLI binaries (./bin/kalos_runner or ./bin/kalos_bench), specify your target model's Hidden Layer Dimension (-d) and desired VRAM Memory Cap (-v) according to the reference matrix below:

Model Architecture / Scale	Parameter Scale	Hidden Layer Dim (-d)	Kalos VRAM Cap (-v)
Qwen 2.5 7B	7B	-d 3584	-v 500 (500 MB)
Llama 3 / 3.1 / 3.3 8B	8B	-d 4096	-v 500 (500 MB)
Gemma 3 12B Vision	12B	-d 3840	-v 750 (750 MB)
Qwen 2.5 14B	14B	-d 5120	-v 1000 (1.0 GB)
Kalos / Mistral 24B	24B	-d 5120	-v 1500 (1.5 GB)
Qwen 2.5 32B	32B	-d 5120	-v 2000 (2.0 GB)
Llama 3 70B / Qwen 72B	70B / 72B	-d 8192	-v 2500 (2.5 GB)

🎛️ CLI Launch Examples:

# 1. Launch for Qwen 2.5 7B (Hidden Dim: 3584, 500 MB VRAM cap):
./bin/kalos_runner -d 3584 -v 500

# 2. Launch for Llama-3 8B (Hidden Dim: 4096, 500 MB VRAM cap):
./bin/kalos_runner -d 4096 -v 500

# 3. Launch for Kalos 24B (Hidden Dim: 5120, 1.5 GB VRAM cap):
./bin/kalos_runner -d 5120 -v 1500

# 4. Launch for Qwen 72B Monster Model (Hidden Dim: 8192, 2.5 GB VRAM cap):
./bin/kalos_runner -d 8192 -v 2500

🌐 Environment Variable Configuration:

You can also set system environment variables so Kalos automatically remembers your configuration across sessions:

export KALOS_HIDDEN_DIM=5120     # Model hidden layer dimension (3584 | 4096 | 5120 | 8192)
export KALOS_VRAM_LIMIT_MB=1500   # Max VRAM memory cap in MB (1500 MB = 1.5 GB)
export KALOS_MAX_TEMPLATES=100000 # Max SAM associative memory template capacity

---

🛠️ Step 2: Registering Any GGUF Model in Ollama (Modelfile)

You can use any model size of your choice. The included Modelfile provides a clean, universal template:

1. Obtain your GGUF File:
   Download your preferred GGUF model file (e.g. qwen2.5-7b-instruct.gguf, kalos-24b-q8.gguf, or llama-3.3-70b.gguf) into your directory.

2. Edit Modelfile:
   Open Modelfile and point the FROM line to your downloaded GGUF file:

   FROM ./your_model_file.gguf
   

3. Register the Model in Ollama:
   Run ollama create using your model name of choice:

   ollama create kalos:24b -f Modelfile
   

---

🖥️ Step 3: Running the Native C Ncurses TUI (./bin/kalos_tui)

Run the precompiled native C Ncurses user interface directly from the package directory:

./bin/kalos_tui

Interactive Commands:

🎵 YouTube Music & Audio Streaming (/play or /music):

Stream any song, music track, or YouTube video audio live in the background while chatting with Kalos:

/play lofi beats to relax/study to
/play https://www.youtube.com/watch?v=5qap5aO4i9A

• Kalos perceives the active track title and listens/comments on the music with you!

🎬 YouTube Video Perception (/watch or /video):

Stream and perceive video scenes live from YouTube:

/watch https://www.youtube.com/watch?v=ScMzIvxBSi4

🖐️ Physical Haptics & Touch Commands:

/touch shoulders gentle massage
/haptic warm hug

---

🏆 Dynamic Benchmarking & Hardware Profiling

To run a full empirical hardware benchmark test of your GPU VRAM and hidden layer scaling:

# Benchmark 3584-dim (7B) model on 500 MB VRAM:
./bin/kalos_bench -d 3584 -v 500

# Benchmark 5120-dim (24B) model on 1.5 GB VRAM:
./bin/kalos_bench -d 5120 -v 1500

# Benchmark 8192-dim (72B) model on 2.5 GB VRAM:
./bin/kalos_bench -d 8192 -v 2500