rlama

RLAMA - User Guide

⚠️ Project Temporarily Paused
This project is currently on pause due to my work and university commitments that take up a lot of my time. I am not able to actively maintain this project at the moment. Development will resume when my situation allows it.

RLAMA is a powerful AI-driven question-answering tool for your documents, seamlessly integrating with your local Ollama models. It enables you to create, manage, and interact with Retrieval-Augmented Generation (RAG) systems tailored to your documentation needs.

Table of Contents

• Vision & Roadmap
• Installation
• Available Commands
  • rag - Create a RAG system
  • crawl-rag - Create a RAG system from a website
  • wizard - Create a RAG system with interactive setup
  • watch - Set up directory watching for a RAG system
  • watch-off - Disable directory watching for a RAG system
  • check-watched - Check a RAG's watched directory for new files
  • web-watch - Set up website monitoring for a RAG system
  • web-watch-off - Disable website monitoring for a RAG system
  • check-web-watched - Check a RAG's monitored website for updates
  • run - Use a RAG system
  • api - Start API server
  • list - List RAG systems
  • delete - Delete a RAG system
  • list-docs - List documents in a RAG
  • list-chunks - Inspect document chunks
  • view-chunk - View chunk details
  • add-docs - Add documents to RAG
  • crawl-add-docs - Add website content to RAG
  • update-model - Change LLM model
  • update - Update RLAMA
  • version - Display version
  • hf-browse - Browse GGUF models on Hugging Face
  • run-hf - Run a Hugging Face GGUF model
• Uninstallation
• Supported Document Formats
• Troubleshooting
• Using OpenAI Models

Vision & Roadmap

RLAMA aims to become the definitive tool for creating local RAG systems that work seamlessly for everyone—from individual developers to large enterprises. Here's our strategic roadmap:

Completed Features ✅

• ✅ Basic RAG System Creation: CLI tool for creating and managing RAG systems
• ✅ Document Processing: Support for multiple document formats (.txt, .md, .pdf, etc.)
• ✅ Document Chunking: Advanced semantic chunking with multiple strategies (fixed, semantic, hierarchical, hybrid)
• ✅ Vector Storage: Local storage of document embeddings
• ✅ Context Retrieval: Basic semantic search with configurable context size
• ✅ Ollama Integration: Seamless connection to Ollama models
• ✅ Cross-Platform Support: Works on Linux, macOS, and Windows
• ✅ Easy Installation: One-line installation script
• ✅ API Server: HTTP endpoints for integrating RAG capabilities in other applications
• ✅ Web Crawling: Create RAGs directly from websites
• ✅ Guided RAG Setup Wizard: Interactive interface for easy RAG creation
• ✅ Hugging Face Integration: Access to 45,000+ GGUF models from Hugging Face Hub

Small LLM Optimization (Q2 2025)

• Prompt Compression: Smart context summarization for limited context windows
• ✅ Adaptive Chunking: Dynamic content segmentation based on semantic boundaries and document structure
• ✅ Minimal Context Retrieval: Intelligent filtering to eliminate redundant content
• Parameter Optimization: Fine-tuned settings for different model sizes

Advanced Embedding Pipeline (Q2-Q3 2025)

• Multi-Model Embedding Support: Integration with various embedding models
• Hybrid Retrieval Techniques: Combining sparse and dense retrievers for better accuracy
• Embedding Evaluation Tools: Built-in metrics to measure retrieval quality
• Automated Embedding Cache: Smart caching to reduce computation for similar queries

User Experience Enhancements (Q3 2025)

• Lightweight Web Interface: Simple browser-based UI for the existing CLI backend
• Knowledge Graph Visualization: Interactive exploration of document connections
• Domain-Specific Templates: Pre-configured settings for different domains

Enterprise Features (Q4 2025)

• Multi-User Access Control: Role-based permissions for team environments
• Integration with Enterprise Systems: Connectors for SharePoint, Confluence, Google Workspace
• Knowledge Quality Monitoring: Detection of outdated or contradictory information
• System Integration API: Webhooks and APIs for embedding RLAMA in existing workflows
• AI Agent Creation Framework: Simplified system for building custom AI agents with RAG capabilities

Next-Gen Retrieval Innovations (Q1 2026)

• Multi-Step Retrieval: Using the LLM to refine search queries for complex questions
• Cross-Modal Retrieval: Support for image content understanding and retrieval
• Feedback-Based Optimization: Learning from user interactions to improve retrieval
• Knowledge Graphs & Symbolic Reasoning: Combining vector search with structured knowledge

RLAMA's core philosophy remains unchanged: to provide a simple, powerful, local RAG solution that respects privacy, minimizes resource requirements, and works seamlessly across platforms.

Installation

Prerequisites

• Ollama installed and running

Installation from terminal

curl -fsSL https://raw.githubusercontent.com/dontizi/rlama/main/install.sh | sh

Tech Stack

RLAMA is built with:

• Core Language: Go (chosen for performance, cross-platform compatibility, and single binary distribution)
• CLI Framework: Cobra (for command-line interface structure)
• LLM Integration: Ollama API (for embeddings and completions)
• Storage: Local filesystem-based storage (JSON files for simplicity and portability)
• Vector Search: Custom implementation of cosine similarity for embedding retrieval

Architecture

RLAMA follows a clean architecture pattern with clear separation of concerns:

…

Data Flow

1. Document Processing: Documents are loaded from the file system, parsed based on their type, and converted to plain text.
2. Embedding Generation: Document text is sent to Ollama to generate vector embeddings.
3. Storage: The RAG system (documents + embeddings) is stored in the user's home directory (~/.rlama).
4. Query Process: When a user asks a question, it's converted to an embedding, compared against stored document embeddings, and relevant content is retrieved.
5. Response Generation: Retrieved content and the question are sent to Ollama to generate a contextually-informed response.

Visual Representation

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Documents  │────>│  Document   │────>│  Embedding  │
│  (Input)    │     │  Processing │     │  Generation │
└─────────────┘     └─────────────┘     └─────────────┘
                                              │
                                              ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Query     │────>│  Vector     │ environment variable > default location.

### rag - Create a RAG system

Creates a new RAG system by indexing all documents in the specified folder.

```bash
rlama rag [model] [rag-name] [folder-path]

Parameters:

• model: Name of the Ollama model to use (e.g., llama3, mistral, gemma) or a Hugging Face model using the format hf.co/username/repository[:quantization].
• rag-name: Unique name to identify your RAG system.
• folder-path: Path to the folder containing your documents.

Example:

# Using a standard Ollama model
rlama rag llama3 documentation ./docs

# Using a Hugging Face model
rlama rag hf.co/bartowski/Llama-3.2-1B-Instruct-GGUF my-rag ./docs

# Using a Hugging Face model with specific quantization
rlama rag hf.co/mlabonne/Meta-Llama-3.1-8B-Instruct-abliterated-GGUF:Q5_K_M my-rag ./docs

crawl-rag - Create a RAG system from a website

Creates a new RAG system by crawling a website and indexing its content.

rlama crawl-rag [model] [rag-name] [website-url]

…

bash
# Create a new RAG from a documentation website
rlama crawl-rag llama3 docs-rag https://docs.example.com

# Customize crawling behavior
rlama crawl-rag llama3 blog-rag https://blog.example.com --max-depth=3 --exclude-path=/archive,/tags

# Create a RAG with semantic chunking
rlama rag llama3 documentation ./docs --chunking-strategy=semantic

# Use hierarchical chunking for large documents
rlama rag llama3 book-rag ./books --chunking-strategy=hierarchical

wizard - Create a RAG system with interactive setup

Provides an interactive step-by-step wizard for creating a new RAG system.

rlama wizard

The wizard guides you through:

• Naming your RAG
• Choosing an Ollama model
• Selecting document sources (local folder or website)
• Configuring chunking parameters
• Setting up file filtering

Example:

rlama wizard
# Follow the prompts to create your customized RAG

watch - Set up directory watching for a RAG system

Configure a RAG system to automatically watch a directory for new files and add them to the RAG.

rlama watch [rag-name] [directory-path] [interval]

Parameters:

• rag-name: Name of the RAG system to watch.
• directory-path: Path to the directory to watch for new files.
• interval: Time in minutes to check for new files (use 0 to check only when the RAG is used).

Example:

# Set up directory watching to check every 60 minutes
rlama watch my-docs ./watched-folder 60

# Set up directory watching to only check when the RAG is used
rlama watch my-docs ./watched-folder 0

# Customize what files to watch
rlama watch my-docs ./watched-folder 30 --exclude-dir=node_modules,tmp --process-ext=.md,.txt

watch-off - Disable directory watching for a RAG system

Disable automatic directory watching for a RAG system.

rlama watch-off [rag-name]

Parameters:

• rag-name: Name of the RAG system to disable watching.

Example:

rlama watch-off my-docs

check-watched - Check a RAG's watched directory for new files

Manually check a RAG's watched directory for new files and add them to the RAG.

rlama check-watched [rag-name]

Parameters:

• rag-name: Name of the RAG system to check.

Example:

rlama check-watched my-docs

web-watch - Set up website monitoring for a RAG system

Configure a RAG system to automatically monitor a website for updates and add new content to the RAG.

rlama web-watch [rag-name] [website-url] [interval]

Parameters:

• rag-name: Name of the RAG system to monitor.
• website-url: URL of the website to monitor.
• interval: Time in minutes between checks (use 0 to check only when the RAG is used).

Example:

# Set up website monitoring to check every 60 minutes
rlama web-watch my